payload 1.0.27 → 1.0.30

package/docs/fields/relationship.mdx

@@ -69,26 +69,26 @@ The `filterOptions` property can either be a `Where` query directly, or a functi
 
 **Example:**
 
-```js
-  const relationshipField = {
-    name: 'purchase',
-    type: 'relationship',
-    relationTo: ['products', 'services'],
-    filterOptions: ({ relationTo, siblingData }) => {
-      // returns a Where query dynamically by the type of relationship
-      if (relationTo === 'products') {
-        return {
-          'stock': { is_greater_than: siblingData.quantity }
-        }
+```ts
+const relationshipField = {
+  name: 'purchase',
+  type: 'relationship',
+  relationTo: ['products', 'services'],
+  filterOptions: ({ relationTo, siblingData }) => {
+    // returns a Where query dynamically by the type of relationship
+    if (relationTo === 'products') {
+      return {
+        'stock': { is_greater_than: siblingData.quantity }
       }
+    }
 
-      if (relationTo === 'services') {
-        return {
-          'isAvailable': { equals: true }
-        }
+    if (relationTo === 'services') {
+      return {
+        'isAvailable': { equals: true }
       }
-    },
-  };
+    }
+  },
+};
 ```
 
 You can learn more about writing queries [here](/docs/queries/overview).
@@ -106,7 +106,7 @@ Given the variety of options possible within the `relationship` field type, the
 
 The most simple pattern of a relationship is to use `hasMany: false` with a `relationTo` that allows for only one type of collection.
 
-```js
+```ts
 {
   slug: 'example-collection',
   fields: [
@@ -137,7 +137,7 @@ When querying documents in this collection via REST API, you could query as foll
 
 Also known as **dynamic references**, in this configuration, the `relationTo` field is an array of Collection slugs that tells Payload which Collections are valid to reference.
 
-```js
+```ts
 {
   slug: 'example-collection',
   fields: [
@@ -176,7 +176,7 @@ This query would return only documents that have an owner relationship to organi
 
 The `hasMany` tells Payload that there may be more than one collection saved to the field.
 
-```js
+```ts
 {
   slug: 'example-collection',
   fields: [
@@ -204,7 +204,7 @@ When querying documents, the format does not change for arrays:
 
 #### Has Many - Polymorphic
 
-```js
+```ts
 {
   slug: 'example-collection',
   fields: [

package/docs/fields/rich-text.mdx

@@ -126,9 +126,11 @@ Custom `Leaf` objects follow a similar pattern but require you to define the `Le
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {
@@ -178,7 +180,7 @@ Custom `Leaf` objects follow a similar pattern but require you to define the `Le
       }
     }
   ]
-}
+};
 ```
 
 For more examples regarding how to define your own elements and leaves, check out the example [`RichText` field](https://github.com/payloadcms/public-demo/blob/master/src/fields/hero.ts) within the Public Demo source code.
@@ -187,7 +189,7 @@ For more examples regarding how to define your own elements and leaves, check ou
 
 As the Rich Text field saves its content in a JSON format, you'll need to render it as HTML yourself. Here is an example for how to generate JSX / HTML from Rich Text content:
 
-```js
+```ts
 import React, { Fragment } from 'react';
 import escapeHTML from 'escape-html';
 import { Text } from 'slate';
@@ -308,7 +310,7 @@ If you want to utilize this functionality within your own custom elements, you c
 
 `customLargeBodyElement.js`:
 
-```js
+```ts
 import Button from './Button';
 import Element from './Element';
 import withLargeBody from './plugin';
@@ -338,7 +340,7 @@ The plugin itself extends Payload's built-in `shouldBreakOutOnEnter` Slate funct
 
 If you are building your own custom Rich Text elements or leaves, you may benefit from importing the following types:
 
-```js
+```ts
 import type {
   RichTextCustomElement,
   RichTextCustomLeaf,

package/docs/fields/row.mdx

@@ -21,9 +21,11 @@ keywords: row, fields, config, configuration, documentation, Content Management
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/fields/select.mdx

@@ -57,10 +57,11 @@ Set to `true` if you'd like this field to be sortable within the Admin UI using
 
 ### Example
 
-`collections/ExampleCollection.js`
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
 
-```js
-{
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/fields/tabs.mdx

@@ -34,9 +34,11 @@ Each tab has its own required `label` and `fields` array. You can also optionall
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/fields/text.mdx

@@ -46,9 +46,11 @@ Set this property to a string that will be used for browser autocomplete.
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/fields/textarea.mdx

@@ -46,9 +46,11 @@ Set this property to a string that will be used for browser autocomplete.
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/fields/ui.mdx

@@ -34,9 +34,11 @@ With this field, you can also inject custom `Cell` components that appear as add
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/fields/upload.mdx

@@ -46,9 +46,11 @@ keywords: upload, images media, fields, config, configuration, documentation, Co
 
 ### Example
 
-`collections/ExampleCollection.js`
-```js
-{
+`collections/ExampleCollection.ts`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   slug: 'example-collection',
   fields: [
     {

package/docs/getting-started/concepts.mdx

@@ -22,7 +22,7 @@ By default, the Payload config lives in the root folder of your code and is name
 	A Collection represents a type of content that Payload will store and can contain many documents.
 </Banner>
 
-Collections define the shape of your data as well as all functionalities attached to that data. They will contain or many "documents", all corresponding with the same fields and functionalities that you define.
+Collections define the shape of your data as well as all functionalities attached to that data. They will contain one or many "documents", all corresponding with the same fields and functionalities that you define.
 
 They can represent anything you can store in a database - for example - pages, posts, users, people, orders, categories, events, customers, transactions, and anything else your app needs.
 

package/docs/graphql/extending.mdx

@@ -33,7 +33,7 @@ Both `graphQL.queries` and `graphQL.mutations` functions should return an object
 
 `payload.config.js`:
 
-```js
+```ts
 import { buildConfig } from 'payload/config';
 import myCustomQueryResolver from './graphQL/resolvers/myCustomQueryResolver';
 

package/docs/graphql/overview.mdx

@@ -29,8 +29,10 @@ At the top of your Payload config you can define all the options to manage Graph
 
 Everything that can be done to a Collection via the REST or Local API can be done with GraphQL (outside of uploading files, which is REST-only). If you have a collection as follows:
 
-```js
-const PublicUser = {
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const PublicUser: CollectionConfig = {
   slug: 'public-users',
   auth: true, // Auth is enabled
   labels: {
@@ -70,8 +72,10 @@ const PublicUser = {
 
 Globals are also fully supported. For example:
 
-```js
-const Header = {
+```ts
+import { GlobalConfig } from 'payload/types';
+
+const Header: GlobalConfig = {
   slug: 'header',
   fields: [
     ...

package/docs/hooks/collections.mdx

@@ -30,10 +30,11 @@ Additionally, `auth`-enabled collections feature the following hooks:
 
 All collection Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.
 
-`collections/example-hooks.js`
-```js
-// Collection config
-module.exports = {
+`collections/exampleHooks.js`
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleHooks: CollectionConfig = {
   slug: 'example-hooks',
   fields: [
     { name: 'name', type: 'text'},
@@ -65,8 +66,10 @@ The `beforeOperation` Hook type can be used to modify the arguments that operati
 
 Available Collection operations include `create`, `read`, `update`, `delete`, `login`, `refresh` and `forgotPassword`.
 
-```js
-const beforeOperationHook = async ({
+```ts
+import { CollectionBeforeOperationHook } from 'payload/types';
+
+const beforeOperationHook: CollectionBeforeOperationHook = async ({
   args, // Original arguments passed into the operation
   operation, // name of the operation
 }) => {
@@ -78,8 +81,10 @@ const beforeOperationHook = async ({
 
 Runs before the `create` and `update` operations. This hook allows you to add or format data before the incoming data is validated.
 
-```js
-const beforeValidateHook = async ({
+```ts
+import { CollectionBeforeOperationHook } from 'payload/types';
+
+const beforeValidateHook: CollectionBeforeValidateHook = async ({
   data, // incoming data to update or create with
   req, // full express request
   operation, // name of the operation ie. 'create', 'update'
@@ -93,8 +98,10 @@ const beforeValidateHook = async ({
 
 Immediately following validation, `beforeChange` hooks will run within `create` and `update` operations. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.
 
-```js
-const beforeChangeHook = async ({
+```ts
+import { CollectionBeforeChangeHook } from 'payload/types';
+
+const beforeChangeHook: CollectionBeforeChangeHook = async ({
   data, // incoming data to update or create with
   req, // full express request
   operation, // name of the operation ie. 'create', 'update'
@@ -108,8 +115,10 @@ const beforeChangeHook = async ({
 
 After a document is created or updated, the `afterChange` hook runs. This hook is helpful to recalculate statistics such as total sales within a global, syncing user profile changes to a CRM, and more.
 
-```js
-const afterChangeHook = async ({
+```ts
+import { CollectionAfterChangeHook } from 'payload/types';
+
+const afterChangeHook: CollectionAfterChangeHook = async ({
   doc, // full document data
   req, // full express request
   operation, // name of the operation ie. 'create', 'update'
@@ -122,8 +131,10 @@ const afterChangeHook = async ({
 
 Runs before `find` and `findByID` operations are transformed for output by `afterRead`. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the `doc` argument.
 
-```js
-const beforeReadHook = async ({
+```ts
+import { CollectionBeforeReadHook } from 'payload/types';
+
+const beforeReadHook: CollectionBeforeReadHook = async ({
   doc, // full document data
   req, // full express request
   query, // JSON formatted query
@@ -136,8 +147,10 @@ const beforeReadHook = async ({
 
 Runs as the last step before documents are returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
 
-```js
-const afterReadHook = async ({
+```ts
+import { CollectionAfterReadHook } from 'payload/types';
+
+const afterReadHook: CollectionAfterReadHook = async ({
   doc, // full document data
   req, // full express request
   query, // JSON formatted query
@@ -151,8 +164,10 @@ const afterReadHook = async ({
 
 Runs before the `delete` operation. Returned values are discarded.
 
-```js
-const beforeDeleteHook = async ({
+```ts
+import { CollectionBeforeDeleteHook } from 'payload/types';
+
+const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
   req, // full express request
   id, // id of document to delete
 }) => {...}
@@ -162,8 +177,10 @@ const beforeDeleteHook = async ({
 
 Runs immediately after the `delete` operation removes records from the database. Returned values are discarded.
 
-```js
-const afterDeleteHook = async ({
+```ts
+import { CollectionAfterDeleteHook } from 'payload/types';
+
+const afterDeleteHook: CollectionAfterDeleteHook = async ({
   req, // full express request
   id, // id of document to delete
   doc, // deleted document
@@ -174,8 +191,10 @@ const afterDeleteHook = async ({
 
 For auth-enabled Collections, this hook runs after successful `login` operations. You can optionally modify the user that is returned.
 
-```js
-const beforeLoginHook = async ({
+```ts
+import { CollectionBeforeLoginHook } from 'payload/types';
+
+const beforeLoginHook: CollectionBeforeLoginHook = async ({
   req, // full express request
   user, // user being logged in
   token, // user token
@@ -188,8 +207,10 @@ const beforeLoginHook = async ({
 
 For auth-enabled Collections, this hook runs after successful `login` operations. You can optionally modify the user that is returned.
 
-```js
-const afterLoginHook = async ({
+```ts
+import { CollectionAfterLoginHook } from 'payload/types';
+
+const afterLoginHook: CollectionAfterLoginHook = async ({
   req, // full express request
 }) => {...}
 ```
@@ -198,8 +219,10 @@ const afterLoginHook = async ({
 
 For auth-enabled Collections, this hook runs after `logout` operations.
 
-```js
-const afterLogoutHook = async ({
+```ts
+import { CollectionAfterLogoutHook } from 'payload/types';
+
+const afterLogoutHook: CollectionAfterLogoutHook = async ({
   req, // full express request
 }) => {...}
 ```
@@ -208,8 +231,10 @@ const afterLogoutHook = async ({
 
 For auth-enabled Collections, this hook runs after `refresh` operations.
 
-```js
-const afterRefreshHook = async ({
+```ts
+import { CollectionAfterRefreshHook } from 'payload/types';
+
+const afterRefreshHook: CollectionAfterRefreshHook = async ({
   req, // full express request
   res, // full express response
   token, // newly refreshed user token
@@ -220,8 +245,10 @@ const afterRefreshHook = async ({
 
 For auth-enabled Collections, this hook runs after `me` operations.
 
-```js
-const afterMeHook = async ({
+```ts
+import { CollectionAfterMeHook } from 'payload/types';
+
+const afterMeHook: CollectionAfterMeHook = async ({
   req, // full express request
   response, // response to return
 }) => {...}
@@ -231,8 +258,10 @@ const afterMeHook = async ({
 
 For auth-enabled Collections, this hook runs after successful `forgotPassword` operations. Returned values are discarded.
 
-```js
-const afterLoginHook = async ({
+```ts
+import { CollectionAfterForgotPasswordHook } from 'payload/types';
+
+const afterLoginHook: CollectionAfterForgotPasswordHook = async ({
   req, // full express request
   user, // user being logged in
   token, // user token
@@ -245,7 +274,7 @@ const afterLoginHook = async ({
 
 Payload exports a type for each Collection hook which can be accessed as follows:
 
-```js
+```ts
 import type {
   CollectionBeforeOperationHook,
   CollectionBeforeValidateHook,
@@ -262,7 +291,4 @@ import type {
   CollectionAfterMeHook,
   CollectionAfterForgotPasswordHook,
 } from 'payload/types';
-
-// Use hook types here...
-}
 ```

package/docs/hooks/fields.mdx

@@ -26,8 +26,10 @@ Field-level hooks offer incredible potential for encapsulating your logic. They
 ## Config
 
 Example field configuration:
-```js
-{
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const ExampleCollection: CollectionConfig = {
   name: 'name',
   type: 'text',
   // highlight-start
@@ -77,7 +79,7 @@ All field hooks can optionally modify the return value of the field before the o
 
 Payload exports a type for field hooks which can be accessed and used as follows:
 
-```js
+```ts
 import type { FieldHook } from 'payload/types';
 
 // Field hook type is a generic that takes three arguments:

package/docs/hooks/globals.mdx

@@ -19,9 +19,10 @@ Globals feature the ability to define the following hooks:
 All Global Hook properties accept arrays of synchronous or asynchronous functions. Each Hook type receives specific arguments and has the ability to modify specific outputs.
 
 `globals/example-hooks.js`
-```js
-// Global config
-module.exports = {
+```ts
+import { GlobalConfig } from 'payload/types';
+
+const ExampleHooks: GlobalConfig = {
   slug: 'header',
   fields: [
     { name: 'title', type: 'text'},
@@ -40,8 +41,10 @@ module.exports = {
 
 Runs before the `update` operation. This hook allows you to add or format data before the incoming data is validated.
 
-```js
-const beforeValidateHook = async ({
+```ts
+import { GlobalBeforeValidateHook } from 'payload/types'
+
+const beforeValidateHook: GlobalBeforeValidateHook = async ({
   data, // incoming data to update or create with
   req, // full express request
   originalDoc, // original document
@@ -54,8 +57,10 @@ const beforeValidateHook = async ({
 
 Immediately following validation, `beforeChange` hooks will run within the `update` operation. At this stage, you can be confident that the data that will be saved to the document is valid in accordance to your field validations. You can optionally modify the shape of data to be saved.
 
-```js
-const beforeChangeHook = async ({
+```ts
+import { GlobalBeforeChangeHook } from 'payload/types'
+
+const beforeChangeHook: GlobalBeforeChangeHook = async ({
   data, // incoming data to update or create with
   req, // full express request
   originalDoc, // original document
@@ -68,8 +73,10 @@ const beforeChangeHook = async ({
 
 After a global is updated, the `afterChange` hook runs. Use this hook to purge caches of your applications, sync site data to CRMs, and more.
 
-```js
-const afterChangeHook = async ({
+```ts
+import { GlobalAfterChangeHook } from 'payload/types'
+
+const afterChangeHook: GlobalAfterChangeHook = async ({
   doc, // full document data
   req, // full express request
 }) => {
@@ -81,8 +88,10 @@ const afterChangeHook = async ({
 
 Runs before `findOne` global operation is transformed for output by `afterRead`. This hook fires before hidden fields are removed and before localized fields are flattened into the requested locale. Using this Hook will provide you with all locales and all hidden fields via the `doc` argument.
 
-```js
-const beforeReadHook = async ({
+```ts
+import { GlobalBeforeReadHook } from 'payload/types'
+
+const beforeReadHook: GlobalBeforeReadHook = async ({
   doc, // full document data
   req, // full express request
 }) => {...}
@@ -92,8 +101,10 @@ const beforeReadHook = async ({
 
 Runs as the last step before a global is returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
 
-```js
-const afterReadHook = async ({
+```ts
+import { GlobalAfterReadHook } from 'payload/types'
+
+const afterReadHook: GlobalAfterReadHook = async ({
   doc, // full document data
   req, // full express request
   findMany, // boolean to denote if this hook is running against finding one, or finding many (useful in versions)
@@ -104,7 +115,7 @@ const afterReadHook = async ({
 
 Payload exports a type for each Global hook which can be accessed as follows:
 
-```js
+```ts
 import type {
   GlobalBeforeValidateHook,
   GlobalBeforeChangeHook,
@@ -112,7 +123,4 @@ import type {
   GlobalBeforeReadHook,
   GlobalAfterReadHook,
 } from 'payload/types';
-
-// Use hook types here...
-}
 ```

package/docs/local-api/overview.mdx

@@ -28,10 +28,11 @@ You can gain access to the currently running `payload` object via two ways:
 You can import or require `payload` into your own files after it's been initialized, but you need to make sure that your `import` / `require` statements come **after** you call `payload.init()`—otherwise Payload won't have been initialized yet. That might be obvious. To us, it's usually not.
 
 Example:
-```js
+```ts
 import payload from 'payload';
+import { CollectionAfterChangeHook } from 'payload/types';
 
-const afterChangeHook = async () => {
+const afterChangeHook: CollectionAfterChangeHook = async () => {
   const posts = await payload.find({
     collection: 'posts',
   });
@@ -43,8 +44,8 @@ const afterChangeHook = async () => {
 Payload is available anywhere you have access to the Express `req` - including within your access control and hook functions.
 
 Example:
-```js
-const afterChangeHook = async ({ req: { payload }}) => {
+```ts
+const afterChangeHook: CollectionAfterChangeHook = async ({ req: { payload }}) => {
   const posts = await payload.find({
     collection: 'posts',
   });
@@ -319,3 +320,25 @@ const result = await payload.updateGlobal({
   showHiddenFields: true,
 })
 ```
+
+## TypeScript
+
+Local API calls also support passing in a generic. This is especially useful if you generate your TS types using a [generate types script](/docs/typescript/generate-types).
+
+Here is an example of usage:
+
+```ts
+// Our generated types
+import { Post } from './payload-types'
+
+// Add Post types as generic to create function
+const post: Post = await payload.create<Post>({
+  collection: 'posts',
+
+  // Data will now be typed as Post and give you type hints
+  data: {
+    title: 'my title',
+    description: 'my description',
+  },
+})
+```