chore: add JSDoc for globals Local API operations (#11313)

Continuation of #11265 for
globals.
Documents all the possible properties of globals Local API operations
with JSDoc.

Author: r1tsuu

packages/payload/src/globals/operations/local/countGlobalVersions.ts

@@ -8,16 +8,46 @@ import { countGlobalVersionsOperation } from '../countGlobalVersions.js'
 
 export type CountGlobalVersionsOptions<TSlug extends GlobalSlug> = {
   /**
-   * context, which will then be passed to req.context, which can be read by hooks
+   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
+   * which can be read by hooks. Useful if you want to pass additional information to the hooks which
+   * shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook
+   * to determine if it should run or not.
    */
   context?: RequestContext
+  /**
+   * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
+   */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   */
   disableErrors?: boolean
+  /**
+   * the Global slug to operate against.
+   */
   global: TSlug
+  /**
+   * Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
+   */
   locale?: TypedLocale
+  /**
+   * Skip access control.
+   * Set to `false` if you want to respect Access Control for the operation, for example when fetching data for the fron-end.
+   * @default true
+   */
   overrideAccess?: boolean
+  /**
+   * The `PayloadRequest` object. You can pass it to thread the current [transaction](https://payloadcms.com/docs/database/transactions), user and locale to the operation.
+   * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
+   */
   req?: Partial<PayloadRequest>
+  /**
+   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
+   */
   user?: Document
+  /**
+   * A filter [query](https://payloadcms.com/docs/queries/overview)
+   */
   where?: Where
 }
 

packages/payload/src/globals/operations/local/findOne.ts

@@ -14,18 +14,64 @@ import { createLocalReq } from '../../../utilities/createLocalReq.js'
 import { findOneOperation } from '../findOne.js'
 
 export type Options<TSlug extends GlobalSlug, TSelect extends SelectType> = {
+  /**
+   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
+   * which can be read by hooks. Useful if you want to pass additional information to the hooks which
+   * shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook
+   * to determine if it should run or not.
+   */
   context?: RequestContext
+  /**
+   * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
+   */
   depth?: number
+  /**
+   * Whether the document should be queried from the versions table/collection or not. [More](https://payloadcms.com/docs/versions/drafts#draft-api)
+   */
   draft?: boolean
+  /**
+   * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
+   */
   fallbackLocale?: false | TypedLocale
+  /**
+   * Include info about the lock status to the result with fields: `_isLocked` and `_userEditing`
+   */
   includeLockStatus?: boolean
+  /**
+   * Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
+   */
   locale?: 'all' | TypedLocale
+  /**
+   * Skip access control.
+   * Set to `false` if you want to respect Access Control for the operation, for example when fetching data for the fron-end.
+   * @default true
+   */
   overrideAccess?: boolean
+  /**
+   * Specify [populate](https://payloadcms.com/docs/queries/select#populate) to control which fields to include to the result from populated documents.
+   */
   populate?: PopulateType
+  /**
+   * The `PayloadRequest` object. You can pass it to thread the current [transaction](https://payloadcms.com/docs/database/transactions), user and locale to the operation.
+   * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
+   */
   req?: Partial<PayloadRequest>
+  /**
+   * Specify [select](https://payloadcms.com/docs/queries/select) to control which fields to include to the result.
+   */
   select?: TSelect
+  /**
+   * Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.
+   * @default false
+   */
   showHiddenFields?: boolean
+  /**
+   * the Global slug to operate against.
+   */
   slug: TSlug
+  /**
+   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
+   */
   user?: Document
 }
 

packages/payload/src/globals/operations/local/findVersionByID.ts

@@ -9,18 +9,65 @@ import { createLocalReq } from '../../../utilities/createLocalReq.js'
 import { findVersionByIDOperation } from '../findVersionByID.js'
 
 export type Options<TSlug extends GlobalSlug> = {
+  /**
+   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
+   * which can be read by hooks. Useful if you want to pass additional information to the hooks which
+   * shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook
+   * to determine if it should run or not.
+   */
   context?: RequestContext
+  /**
+   * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
+   */
   depth?: number
+  /**
+   * When set to `true`, errors will not be thrown.
+   * `null` will be returned instead, if the document on this ID was not found.
+   */
   disableErrors?: boolean
+  /**
+   * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
+   */
   fallbackLocale?: false | TypedLocale
+  /**
+   * The ID of the version to find.
+   */
   id: string
+  /**
+   * Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
+   */
   locale?: 'all' | TypedLocale
+  /**
+   * Skip access control.
+   * Set to `false` if you want to respect Access Control for the operation, for example when fetching data for the fron-end.
+   * @default true
+   */
   overrideAccess?: boolean
+  /**
+   * Specify [populate](https://payloadcms.com/docs/queries/select#populate) to control which fields to include to the result from populated documents.
+   */
   populate?: PopulateType
+  /**
+   * The `PayloadRequest` object. You can pass it to thread the current [transaction](https://payloadcms.com/docs/database/transactions), user and locale to the operation.
+   * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
+   */
   req?: Partial<PayloadRequest>
+  /**
+   * Specify [select](https://payloadcms.com/docs/queries/select) to control which fields to include to the result.
+   */
   select?: SelectType
+  /**
+   * Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.
+   * @default false
+   */
   showHiddenFields?: boolean
+  /**
+   * the Global slug to operate against.
+   */
   slug: TSlug
+  /**
+   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
+   */
   user?: Document
 }
 

packages/payload/src/globals/operations/local/findVersions.ts

@@ -18,20 +18,77 @@ import { createLocalReq } from '../../../utilities/createLocalReq.js'
 import { findVersionsOperation } from '../findVersions.js'
 
 export type Options<TSlug extends GlobalSlug> = {
+  /**
+   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
+   * which can be read by hooks. Useful if you want to pass additional information to the hooks which
+   * shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook
+   * to determine if it should run or not.
+   */
   context?: RequestContext
+  /**
+   * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
+   */
   depth?: number
+  /**
+   * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
+   */
   fallbackLocale?: false | TypedLocale
+  /**
+   * The maximum related documents to be returned.
+   * Defaults unless `defaultLimit` is specified for the collection config
+   * @default 10
+   */
   limit?: number
+  /**
+   * Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
+   */
   locale?: 'all' | TypedLocale
+  /**
+   * Skip access control.
+   * Set to `false` if you want to respect Access Control for the operation, for example when fetching data for the fron-end.
+   * @default true
+   */
   overrideAccess?: boolean
+  /**
+   * Get a specific page number
+   * @default 1
+   */
   page?: number
+  /**
+   * Specify [populate](https://payloadcms.com/docs/queries/select#populate) to control which fields to include to the result from populated documents.
+   */
   populate?: PopulateType
+  /**
+   * The `PayloadRequest` object. You can pass it to thread the current [transaction](https://payloadcms.com/docs/database/transactions), user and locale to the operation.
+   * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
+   */
   req?: Partial<PayloadRequest>
+  /**
+   * Specify [select](https://payloadcms.com/docs/queries/select) to control which fields to include to the result.
+   */
   select?: SelectType
+  /**
+   * Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.
+   * @default false
+   */
   showHiddenFields?: boolean
+  /**
+   * the Global slug to operate against.
+   */
   slug: TSlug
+  /**
+   * Sort the documents, can be a string or an array of strings
+   * @example '-version.createdAt' // Sort DESC by createdAt
+   * @example ['version.group', '-version.createdAt'] // sort by 2 fields, ASC group and DESC createdAt
+   */
   sort?: Sort
+  /**
+   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
+   */
   user?: Document
+  /**
+   * A filter [query](https://payloadcms.com/docs/queries/overview)
+   */
   where?: Where
 }
 

packages/payload/src/globals/operations/local/restoreVersion.ts

@@ -9,16 +9,56 @@ import { createLocalReq } from '../../../utilities/createLocalReq.js'
 import { restoreVersionOperation } from '../restoreVersion.js'
 
 export type Options<TSlug extends GlobalSlug> = {
+  /**
+   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
+   * which can be read by hooks. Useful if you want to pass additional information to the hooks which
+   * shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook
+   * to determine if it should run or not.
+   */
   context?: RequestContext
+  /**
+   * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
+   */
   depth?: number
+  /**
+   * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
+   */
   fallbackLocale?: false | TypedLocale
+  /**
+   * The ID of the version to restore.
+   */
   id: string
+  /**
+   * Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
+   */
   locale?: TypedLocale
+  /**
+   * Skip access control.
+   * Set to `false` if you want to respect Access Control for the operation, for example when fetching data for the fron-end.
+   * @default true
+   */
   overrideAccess?: boolean
+  /**
+   * Specify [populate](https://payloadcms.com/docs/queries/select#populate) to control which fields to include to the result from populated documents.
+   */
   populate?: PopulateType
+  /**
+   * The `PayloadRequest` object. You can pass it to thread the current [transaction](https://payloadcms.com/docs/database/transactions), user and locale to the operation.
+   * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
+   */
   req?: Partial<PayloadRequest>
+  /**
+   * Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.
+   * @default false
+   */
   showHiddenFields?: boolean
+  /**
+   * the Global slug to operate against.
+   */
   slug: TSlug
+  /**
+   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
+   */
   user?: Document
 }
 

packages/payload/src/globals/operations/local/update.ts

@@ -22,20 +22,74 @@ import { createLocalReq } from '../../../utilities/createLocalReq.js'
 import { updateOperation } from '../update.js'
 
 export type Options<TSlug extends GlobalSlug, TSelect extends SelectType> = {
+  /**
+   * [Context](https://payloadcms.com/docs/hooks/context), which will then be passed to `context` and `req.context`,
+   * which can be read by hooks. Useful if you want to pass additional information to the hooks which
+   * shouldn't be necessarily part of the document, for example a `triggerBeforeChange` option which can be read by the BeforeChange hook
+   * to determine if it should run or not.
+   */
   context?: RequestContext
+  /**
+   * The global data to update.
+   */
   data: DeepPartial<Omit<DataFromGlobalSlug<TSlug>, 'id'>>
+  /**
+   * [Control auto-population](https://payloadcms.com/docs/queries/depth) of nested relationship and upload fields.
+   */
   depth?: number
+  /**
+   * Update documents to a draft.
+   */
   draft?: boolean
+  /**
+   * Specify a [fallback locale](https://payloadcms.com/docs/configuration/localization) to use for any returned documents.
+   */
   fallbackLocale?: false | TypedLocale
+  /**
+   * Specify [locale](https://payloadcms.com/docs/configuration/localization) for any returned documents.
+   */
   locale?: 'all' | TypedLocale
+  /**
+   * Skip access control.
+   * Set to `false` if you want to respect Access Control for the operation, for example when fetching data for the fron-end.
+   * @default true
+   */
   overrideAccess?: boolean
+  /**
+   * If you are uploading a file and would like to replace
+   * the existing file instead of generating a new filename,
+   * you can set the following property to `true`
+   */
   overrideLock?: boolean
+  /**
+   * Specify [populate](https://payloadcms.com/docs/queries/select#populate) to control which fields to include to the result from populated documents.
+   */
   populate?: PopulateType
+  /**
+   * Publish the document / documents with a specific locale.
+   */
   publishSpecificLocale?: TypedLocale
+  /**
+   * The `PayloadRequest` object. You can pass it to thread the current [transaction](https://payloadcms.com/docs/database/transactions), user and locale to the operation.
+   * Recommended to pass when using the Local API from hooks, as usually you want to execute the operation within the current transaction.
+   */
   req?: Partial<PayloadRequest>
+  /**
+   * Specify [select](https://payloadcms.com/docs/queries/select) to control which fields to include to the result.
+   */
   select?: TSelect
+  /**
+   * Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.
+   * @default false
+   */
   showHiddenFields?: boolean
+  /**
+   * the Global slug to operate against.
+   */
   slug: TSlug
+  /**
+   * If you set `overrideAccess` to `false`, you can pass a user to use against the access control checks.
+   */
   user?: Document
 }