simplifies createLocalReq usage

docs/admin/preferences.mdx

@@ -47,7 +47,7 @@ Payload automatically creates an internally used `payload-preferences` Collectio
 
 ## APIs
 
-Preferences are available to both [GraphQL](/docs/graphql/overview#preferences) and [REST](/docs/rest-api/overview#preferences) APIs.
+Preferences are available to both [GraphQL](/docs/graphql/overview#preferences), [REST](/docs/rest-api/overview#preferences), and [Local](/docs/local-api/overview#preferences) APIs. You can read and write preferences via any of these APIs.
 
 ## Adding or reading Preferences in your own components
 

docs/local-api/overview.mdx

@@ -460,6 +460,35 @@ const result = await payload.updateGlobal({
 })
 ```
 
+## Preferences
+
+### Find Preference by Key
+
+```ts
+// Result will be the preference value.
+const result = await payload.findPreferenceByKey({
+  key: preferencesKey,
+  req,
+  user,
+})
+```
+
+### Update Preference
+
+The `updatePreference` method uses the `upsert` operation internally, which means it will create a new preference if it doesn't exist, or update the existing one if it does.
+
+```ts
+// Result will be the updated preference value.
+const result = await payload.updatePreference({
+  key: preferencesKey,
+  req,
+  user,
+  value: {
+    // ...some new or updated prefs
+  },
+})
+```
+
 ## TypeScript
 
 Local API calls will automatically infer your [generated types](/docs/typescript/generating-types).

packages/payload/src/collections/operations/local/index.ts

@@ -1,5 +1,7 @@
-/* eslint-disable no-restricted-exports */
 import * as auth from '../../../auth/operations/local/index.js'
+/* eslint-disable no-restricted-exports */
+import { findOne as findPreferenceByKey } from '../../../preferences/operations/findOne.js'
+import { update as updatePreference } from '../../../preferences/operations/update.js'
 import count from './count.js'
 import countVersions from './countVersions.js'
 import create from './create.js'
@@ -21,8 +23,10 @@ export default {
   duplicate,
   find: findLocal,
   findByID,
+  findPreferenceByKey,
   findVersionByID,
   findVersions,
   restoreVersion,
   update,
+  updatePreference,
 }

packages/payload/src/index.ts

@@ -54,6 +54,7 @@ import type { Options as FindGlobalVersionByIDOptions } from './globals/operatio
 import type { Options as FindGlobalVersionsOptions } from './globals/operations/local/findVersions.js'
 import type { Options as RestoreGlobalVersionOptions } from './globals/operations/local/restoreVersion.js'
 import type { Options as UpdateGlobalOptions } from './globals/operations/local/update.js'
+import type { PreferenceRequest, PreferenceUpdateRequest } from './preferences/types.js'
 import type {
   ApplyDisableErrors,
   JsonObject,
@@ -375,6 +376,9 @@ export class BasePayload {
     return findVersions<TSlug>(this, options)
   }
 
+  findPreferenceByKey = async (args: PreferenceRequest) =>
+    localOperations.findPreferenceByKey(this, args)
+
   /**
    * @description Find version by ID
    * @param options
@@ -486,6 +490,9 @@ export class BasePayload {
     return update<TSlug, TSelect>(this, options)
   }
 
+  updatePreference = async (args: PreferenceUpdateRequest) =>
+    localOperations.updatePreference(this, args)
+
   validationRules: (args: OperationArgs<any>) => ValidationRule[]
 
   verifyEmail = async <TSlug extends CollectionSlug>(

packages/payload/src/preferences/operations/delete.ts

@@ -1,16 +1,17 @@
-import type { Document, Where } from '../../types/index.js'
+import type { Document, Payload, Where } from '../../types/index.js'
 import type { PreferenceRequest } from '../types.js'
 
 import { NotFound } from '../../errors/NotFound.js'
-import { UnauthorizedError } from '../../errors/UnathorizedError.js'
+import { UnauthorizedError } from '../../errors/UnauthorizedError.js'
+import { createLocalReq } from '../../utilities/createLocalReq.js'
 
-export async function deleteOperation(args: PreferenceRequest): Promise<Document> {
-  const {
-    key,
-    req: { payload },
-    req,
-    user,
-  } = args
+export async function deleteOperation(
+  payload: Payload,
+  args: PreferenceRequest,
+): Promise<Document> {
+  const { key, user } = args
+
+  const req = await createLocalReq(args, payload)
 
   if (!user) {
     throw new UnauthorizedError(req.t)
@@ -33,5 +34,6 @@ export async function deleteOperation(args: PreferenceRequest): Promise<Document
   if (result) {
     return result
   }
+
   throw new NotFound(req.t)
 }

packages/payload/src/preferences/operations/findOne.ts

@@ -1,19 +1,20 @@
-import type { TypedCollection } from '../../index.js'
-import type { Where } from '../../types/index.js'
+import type { Payload, Where } from '../../types/index.js'
 import type { PreferenceRequest } from '../types.js'
 
-export async function findOne(args: PreferenceRequest): Promise<TypedCollection['_preference']> {
-  const {
-    key,
-    req: { payload },
-    req,
-    user,
-  } = args
+import { createLocalReq, type TypedCollection } from '../../index.js'
+
+export async function findOne(
+  payload: Payload,
+  args: PreferenceRequest,
+): Promise<TypedCollection['_preference']> {
+  const { key, user } = args
 
   if (!user) {
     return null
   }
 
+  const req = await createLocalReq(args, payload)
+
   const where: Where = {
     and: [
       { key: { equals: key } },

packages/payload/src/preferences/operations/update.ts

@@ -1,16 +1,16 @@
-import type { Where } from '../../types/index.js'
+import type { Payload, Where } from '../../types/index.js'
 import type { PreferenceUpdateRequest } from '../types.js'
 
-import { UnauthorizedError } from '../../errors/UnathorizedError.js'
+import { UnauthorizedError } from '../../errors/UnauthorizedError.js'
+import { createLocalReq, type TypedCollection } from '../../index.js'
 
-export async function update(args: PreferenceUpdateRequest) {
-  const {
-    key,
-    req: { payload },
-    req,
-    user,
-    value,
-  } = args
+export async function update(
+  payload: Payload,
+  args: PreferenceUpdateRequest,
+): Promise<TypedCollection['_preference']> {
+  const { key, user, value } = args
+
+  const req = await createLocalReq(args, payload)
 
   if (!user) {
     throw new UnauthorizedError(req.t)

packages/payload/src/preferences/requestHandlers/delete.ts

@@ -12,7 +12,7 @@ export const deleteHandler: PayloadHandler = async (incomingReq): Promise<Respon
 
   try {
     data = await incomingReq.json()
-  } catch (error) {
+  } catch (_err) {
     data = {}
   }
 
@@ -23,7 +23,7 @@ export const deleteHandler: PayloadHandler = async (incomingReq): Promise<Respon
     reqWithData.json = () => Promise.resolve(data)
   }
 
-  const result = await deleteOperation({
+  const result = await deleteOperation(incomingReq.payload, {
     key: reqWithData.routeParams?.key as string,
     req: reqWithData,
     user: reqWithData.user,

packages/payload/src/preferences/requestHandlers/findOne.ts

@@ -12,7 +12,7 @@ export const findByIDHandler: PayloadHandler = async (incomingReq): Promise<Resp
 
   try {
     data = await incomingReq.json()
-  } catch (error) {
+  } catch (_err) {
     data = {}
   }
 
@@ -23,7 +23,7 @@ export const findByIDHandler: PayloadHandler = async (incomingReq): Promise<Resp
     reqWithData.json = () => Promise.resolve(data)
   }
 
-  const result = await findOne({
+  const result = await findOne(incomingReq.payload, {
     key: reqWithData.routeParams?.key as string,
     req: reqWithData,
     user: reqWithData.user,

packages/payload/src/preferences/requestHandlers/update.ts

@@ -12,7 +12,7 @@ export const updateHandler: PayloadHandler = async (incomingReq) => {
 
   try {
     data = await incomingReq.json()
-  } catch (error) {
+  } catch (_err) {
     data = {}
   }
 
@@ -23,7 +23,7 @@ export const updateHandler: PayloadHandler = async (incomingReq) => {
     reqWithData.json = () => Promise.resolve(data)
   }
 
-  const doc = await update({
+  const doc = await update(incomingReq.payload, {
     key: reqWithData.routeParams?.key as string,
     req: reqWithData,
     user: reqWithData?.user,

packages/payload/src/preferences/types.ts

@@ -3,7 +3,7 @@ import type { PayloadRequest } from '../types/index.js'
 export type PreferenceRequest = {
   key: string
   overrideAccess?: boolean
-  req: PayloadRequest
+  req?: PayloadRequest
   user: PayloadRequest['user']
 }