payload 1.15.6 → 2.0.0-beta.1

package/docs/graphql/overview.mdx

@@ -1,124 +0,0 @@
----
-title: GraphQL Overview
-label: Overview
-order: 10
-desc: Payload ships with a fully featured and extensible GraphQL API, which can be used in addition to the REST and Local APIs to give you more flexibility.
-keywords: graphql, resolvers, mutations, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-In addition to its REST and Local APIs, Payload ships with a fully featured and extensible GraphQL API.
-
-By default, the GraphQL API is exposed via `/api/graphql`, but you can customize this URL via specifying your `routes` within the main Payload config.
-
-The labels you provide for your Collections and Globals are used to name the GraphQL types that are created to correspond to your config. Special characters and spaces are removed.
-
-## GraphQL Options
-
-At the top of your Payload config you can define all the options to manage GraphQL.
-
-| Option                          | Description                                                                                                                                                   |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mutations`                     | Any custom Mutations to be added in addition to what Payload provides. [More](/docs/graphql/extending)                                                        |
-| `queries`                       | Any custom Queries to be added in addition to what Payload provides. [More](/docs/graphql/extending)                                                          |
-| `maxComplexity`                 | A number used to set the maximum allowed complexity allowed by requests [More](/docs/graphql/overview#query-complexity-limits)                                |
-| `disablePlaygroundInProduction` | A boolean that if false will enable the GraphQL playground, defaults to true. [More](/docs/graphql/overview#graphql-playground)                               |
-| `disable`                       | A boolean that if true will disable the GraphQL entirely, defaults to false.                                                                                  |
-| `schemaOutputFile`              | A string for the file path used by the generate schema command. Defaults to `graphql.schema` next to `payload.config.ts` [More](/docs/graphql/graphql-schema) |
-
-## Collections
-
-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:
-
-```ts
-import { CollectionConfig } from 'payload/types';
-
-export const PublicUser: CollectionConfig = {
-  slug: 'public-users',
-  auth: true, // Auth is enabled
-  fields: [
-    ...
-  ],
-}
-```
-
-**Payload will automatically open up the following queries:**
-
-| Query Name         | Operation           |
-| ------------------ | ------------------- |
-| **`PublicUser`**   | `findByID`          |
-| **`PublicUsers`**  | `find`              |
-| **`mePublicUser`** | `me` auth operation |
-
-**And the following mutations:**
-
-| Query Name                     | Operation                       |
-| ------------------------------ | ------------------------------- |
-| **`createPublicUser`**         | `create`                        |
-| **`updatePublicUser`**         | `update`                        |
-| **`deletePublicUser`**         | `delete`                        |
-| **`forgotPasswordPublicUser`** | `forgotPassword` auth operation |
-| **`resetPasswordPublicUser`**  | `resetPassword` auth operation  |
-| **`unlockPublicUser`**         | `unlock` auth operation         |
-| **`verifyPublicUser`**         | `verify` auth operation         |
-| **`loginPublicUser`**          | `login` auth operation          |
-| **`logoutPublicUser`**         | `logout` auth operation         |
-| **`refreshTokenPublicUser`**   | `refresh` auth operation        |
-
-## Globals
-
-Globals are also fully supported. For example:
-
-```ts
-import { GlobalConfig } from 'payload/types';
-
-const Header: GlobalConfig = {
-  slug: 'header',
-  fields: [
-    ...
-  ],
-}
-```
-
-**Payload will open the following query:**
-
-| Query Name   | Operation |
-| ------------ | --------- |
-| **`Header`** | `findOne` |
-
-**And the following mutation:**
-
-| Query Name         | Operation |
-| ------------------ | --------- |
-| **`updateHeader`** | `update`  |
-
-## Preferences
-
-User [preferences](/docs/admin/overview#preferences) for the admin panel are also available to GraphQL. To query preferences you must supply an authorization token in the header and only the preferences of that user will be accessible and of the `key` argument.
-
-**Payload will open the following query:**
-
-| Query Name       | Operation |
-| ---------------- | --------- |
-| **`Preference`** | `findOne` |
-
-**And the following mutations:**
-
-| Query Name             | Operation |
-| ---------------------- | --------- |
-| **`updatePreference`** | `update`  |
-| **`deletePreference`** | `delete`  |
-
-## GraphQL Playground
-
-GraphQL Playground is enabled by default for development purposes, but disabled in production. You can enable it in production by passing `graphQL.disablePlaygroundInProduction` a `false` setting in the main Payload config.
-
-You can even log in using the `login[collection-singular-label-here]` mutation to use the Playground as an authenticated user.
-
-<Banner type="success">
-  <strong>Tip:</strong><br />
-  To see more regarding how the above queries and mutations are used, visit your GraphQL playground (by default at [http://localhost:3000/api/graphql-playground](http://localhost:3000/api/graphql-playground)) while your server is running. There, you can use the "Schema" and "Docs" buttons on the right to see a ton of detail about how GraphQL operates within Payload.
-</Banner>
-
-## Query complexity limits
-
-Payload comes with a built-in query complexity limiter to prevent bad people from trying to slow down your server by running massive queries. To learn more, [click here](/docs/production/preventing-abuse#limiting-graphql-complexity).

package/docs/hooks/collections.mdx

@@ -1,323 +0,0 @@
----
-title: Collection Hooks
-label: Collections
-order: 20
-desc: You can add hooks to any Collection, several hook types are available including beforeChange, afterRead, afterDelete and more.
-keywords: hooks, collections, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-Collections feature the ability to define the following hooks:
-
-- [beforeOperation](#beforeoperation)
-- [beforeValidate](#beforevalidate)
-- [beforeChange](#beforechange)
-- [afterChange](#afterchange)
-- [beforeRead](#beforeread)
-- [afterRead](#afterread)
-- [beforeDelete](#beforedelete)
-- [afterDelete](#afterdelete)
-- [afterOperation](#afteroperation)
-
-Additionally, `auth`-enabled collections feature the following hooks:
-
-- [beforeLogin](#beforelogin)
-- [afterLogin](#afterlogin)
-- [afterLogout](#afterlogout)
-- [afterRefresh](#afterrefresh)
-- [afterMe](#afterme)
-- [afterForgotPassword](#afterforgotpassword)
-
-## Config
-
-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/exampleHooks.js`
-
-```ts
-import { CollectionConfig } from 'payload/types';
-
-export const ExampleHooks: CollectionConfig = {
-  slug: 'example-hooks',
-  fields: [
-    { name: 'name', type: 'text'},
-  ],
-  hooks: {
-    beforeOperation: [(args) => {...}],
-    beforeValidate: [(args) => {...}],
-    beforeDelete: [(args) => {...}],
-    beforeChange: [(args) => {...}],
-    beforeRead: [(args) => {...}],
-    afterChange: [(args) => {...}],
-    afterRead: [(args) => {...}],
-    afterDelete: [(args) => {...}],
-    afterOperation: [(args) => {...}],
-
-    // Auth-enabled hooks
-    beforeLogin: [(args) => {...}],
-    afterLogin: [(args) => {...}],
-    afterLogout: [(args) => {...}],
-    afterRefresh: [(args) => {...}],
-    afterMe: [(args) => {...}],
-    afterForgotPassword: [(args) => {...}],
-  },
-}
-```
-
-### beforeOperation
-
-The `beforeOperation` hook can be used to modify the arguments that operations accept or execute side-effects that run before an operation begins.
-
-Available Collection operations include `create`, `read`, `update`, `delete`, `login`, `refresh`, and `forgotPassword`.
-
-```ts
-import { CollectionBeforeOperationHook } from "payload/types";
-
-const beforeOperationHook: CollectionBeforeOperationHook = async ({
-  args, // original arguments passed into the operation
-  operation, // name of the operation
-}) => {
-  return args; // return modified operation arguments as necessary
-};
-```
-
-### beforeValidate
-
-Runs before the `create` and `update` operations. This hook allows you to add or format data before the incoming data is validated server-side.
-
-Please do note that this does not run before the client-side validation. If you added a `validate` function, this would be the lifecycle:
-
-1. `validate` runs on the client
-2. if successful, `beforeValidate` runs on the server
-3. `validate` runs on the server
-
-```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'
-  originalDoc, // original document
-}) => {
-  return data; // Return data to either create or update a document with
-};
-```
-
-### beforeChange
-
-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.
-
-```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'
-  originalDoc, // original document
-}) => {
-  return data; // Return data to either create or update a document with
-};
-```
-
-### afterChange
-
-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.
-
-```ts
-import { CollectionAfterChangeHook } from "payload/types";
-
-const afterChangeHook: CollectionAfterChangeHook = async ({
-  doc, // full document data
-  req, // full express request
-  previousDoc, // document data before updating the collection
-  operation, // name of the operation ie. 'create', 'update'
-}) => {
-  return doc; // value to be used in subsequent afterChange hooks
-};
-```
-
-### beforeRead
-
-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.
-
-```ts
-import { CollectionBeforeReadHook } from "payload/types";
-
-const beforeReadHook: CollectionBeforeReadHook = async ({
-  doc, // full document data
-  req, // full express request
-  query, // JSON formatted query
-}) => {
-  return doc;
-};
-```
-
-### afterRead
-
-Runs as the last step before documents are returned. Flattens locales, hides protected fields, and removes fields that users do not have access to.
-
-```ts
-import { CollectionAfterReadHook } from "payload/types";
-
-const afterReadHook: CollectionAfterReadHook = async ({
-  doc, // full document data
-  req, // full express request
-  query, // JSON formatted query
-  findMany, // boolean to denote if this hook is running against finding one, or finding many
-}) => {
-  return doc;
-};
-```
-
-### beforeDelete
-
-Runs before the `delete` operation. Returned values are discarded.
-
-```ts
-import { CollectionBeforeDeleteHook } from 'payload/types';
-
-const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
-  req, // full express request
-  id, // id of document to delete
-}) => {...}
-```
-
-### afterDelete
-
-Runs immediately after the `delete` operation removes records from the database. Returned values are discarded.
-
-```ts
-import { CollectionAfterDeleteHook } from 'payload/types';
-
-const afterDeleteHook: CollectionAfterDeleteHook = async ({
-  req, // full express request
-  id, // id of document to delete
-  doc, // deleted document
-}) => {...}
-```
-
-### afterOperation
-
-The `afterOperation` hook can be used to modify the result of operations or execute side-effects that run after an operation has completed.
-
-Available Collection operations include `create`, `find`, `findByID`, `update`, `updateByID`, `delete`, `deleteByID`, `login`, `refresh`, and `forgotPassword`.
-
-```ts
-import { CollectionAfterOperationHook } from "payload/types";
-
-const afterOperationHook: CollectionAfterOperationHook = async ({
-  args, // arguments passed into the operation
-  operation, // name of the operation
-  result, // the result of the operation, before modifications
-}) => {
-  return result; // return modified result as necessary
-};
-```
-
-### beforeLogin
-
-For auth-enabled Collections, this hook runs during `login` operations where a user with the provided credentials exist, but before a token is generated and added to the response. You can optionally modify the user that is returned, or throw an error in order to deny the login operation.
-
-```ts
-import { CollectionBeforeLoginHook } from "payload/types";
-
-const beforeLoginHook: CollectionBeforeLoginHook = async ({
-  req, // full express request
-  user, // user being logged in
-}) => {
-  return user;
-};
-```
-
-### afterLogin
-
-For auth-enabled Collections, this hook runs after successful `login` operations. You can optionally modify the user that is returned.
-
-```ts
-import { CollectionAfterLoginHook } from 'payload/types';
-
-const afterLoginHook: CollectionAfterLoginHook = async ({
-  req, // full express request
-  user, // user that was logged in
-  token, // user token
-}) => {...}
-```
-
-### afterLogout
-
-For auth-enabled Collections, this hook runs after `logout` operations.
-
-```ts
-import { CollectionAfterLogoutHook } from 'payload/types';
-
-const afterLogoutHook: CollectionAfterLogoutHook = async ({
-  req, // full express request
-}) => {...}
-```
-
-### afterRefresh
-
-For auth-enabled Collections, this hook runs after `refresh` operations.
-
-```ts
-import { CollectionAfterRefreshHook } from 'payload/types';
-
-const afterRefreshHook: CollectionAfterRefreshHook = async ({
-  req, // full express request
-  res, // full express response
-  token, // newly refreshed user token
-}) => {...}
-```
-
-### afterMe
-
-For auth-enabled Collections, this hook runs after `me` operations.
-
-```ts
-import { CollectionAfterMeHook } from 'payload/types';
-
-const afterMeHook: CollectionAfterMeHook = async ({
-  req, // full express request
-  response, // response to return
-}) => {...}
-```
-
-### afterForgotPassword
-
-For auth-enabled Collections, this hook runs after successful `forgotPassword` operations. Returned values are discarded.
-
-```ts
-import { CollectionAfterForgotPasswordHook } from "payload/types";
-
-const afterLoginHook: CollectionAfterForgotPasswordHook = async ({
-  req, // full express request
-  user, // user being logged in
-  token, // user token
-}) => {
-  return user;
-};
-```
-
-## TypeScript
-
-Payload exports a type for each Collection hook which can be accessed as follows:
-
-```ts
-import type {
-  CollectionBeforeOperationHook,
-  CollectionBeforeValidateHook,
-  CollectionBeforeChangeHook,
-  CollectionAfterChangeHook,
-  CollectionAfterReadHook,
-  CollectionBeforeReadHook,
-  CollectionBeforeDeleteHook,
-  CollectionAfterDeleteHook,
-  CollectionBeforeLoginHook,
-  CollectionAfterLoginHook,
-  CollectionAfterLogoutHook,
-  CollectionAfterRefreshHook,
-  CollectionAfterMeHook,
-  CollectionAfterForgotPasswordHook,
-} from "payload/types";
-```

package/docs/hooks/context.mdx

@@ -1,127 +0,0 @@
----
-title: Context
-label: Context
-order: 50
-desc: Context allows you to pass in extra data that can be shared between hooks
-keywords: hooks, context, payload context, payloadcontext, data, extra data, shared data, shared, extra
----
-
-The `context` object in hooks is used to share data across different hooks. The persists throughout the entire lifecycle of a request and is available within every hook. This allows you to add logic to your hooks based on the request state by setting properties to `req.context` and using them elsewhere.
-
-## When to use Context
-
-Context gives you a way forward on otherwise difficult problems such as:
-
-1. **Passing data between hooks**: Needing data in multiple hooks from a 3rd party API, it could be retrieved and used in `beforeChange` and later used again in an `afterChange` hook without having to fetch it twice.
-2. **Preventing infinite loops**: Calling `payload.update()` on the same document that triggered an `afterChange` hook will create an infinite loop, control the flow by assigning a no-op condition to context
-3. **Passing data to local API**: Setting values on the `req.context` and pass it to `payload.create()` you can provide additional data to hooks without adding extraneous fields.
-4. **Passing data between hooks and middleware or custom endpoints**: Hooks could set context across multiple collections and then be used in a final `postMiddleware`.
-
-## How to Use Context
-
-Let's see examples on how context can be used in the first two scenarios mentioned above:
-
-### Passing data between hooks
-
-To pass data between hooks, you can assign values to context in an earlier hook in the lifecycle of a request and expect it the context in a later hook.
-
-For example:
-
-```ts
-const Customer: CollectionConfig = {
-  slug: 'customers',
-  hooks: {
-    beforeChange: [async ({ context, data }) => {
-      // assign the customerData to context for use later
-      context.customerData = await fetchCustomerData(data.customerID);
-      return {
-        ...data,
-        // some data we use here
-        name: context.customerData.name
-      };
-    }],
-    afterChange: [async ({ context, doc, req }) => {
-      // use context.customerData without needing to fetch it again
-      if (context.customerData.contacted === false) {
-        createTodo('Call Customer', context.customerData)
-      }
-    }],
-  },
-  fields: [ /* ... */  ],
-};
-```
-
-### Preventing infinite loops
-
-Let's say you have an `afterChange` hook, and you want to do a calculation inside the hook (as the document ID needed for the calculation is available in the `afterChange` hook, but not in the `beforeChange` hook). Once that's done, you want to update the document with the result of the calculation.
-
-Bad example:
-
-```ts
-const Customer: CollectionConfig = {
-  slug: 'customers',
-  hooks: {
-    afterChange: [async ({ doc }) => {
-      await payload.update({
-        // DANGER: updating the same slug as the collection in an afterChange will create an infinite loop!
-        collection: 'customers',
-        id: doc.id,
-        data: {
-          ...(await fetchCustomerData(data.customerID))
-        },
-      });
-    }],
-  },
-  fields: [ /* ... */ ],
-};
-```
-
-Instead of the above, we need to tell the `afterChange` hook to not run again if it performs the update (and thus not update itself again). We can solve that with context.
-
-Fixed example:
-
-```ts
-const MyCollection: CollectionConfig = {
-  slug: 'slug',
-  hooks: {
-    afterChange: [async ({ context, doc }) => {
-      // return if flag was previously set
-      if (context.triggerAfterChange === false) {
-        return;
-      }
-      await payload.update({
-        collection: contextHooksSlug,
-        id: doc.id,
-        data: {
-          ...(await fetchCustomerData(data.customerID))
-        },
-        context: {
-          // set a flag to prevent from running again
-          triggerAfterChange: false,
-        },
-      });
-    }],
-  },
-  fields: [ /* ... */ ],
-};
-```
-
-## Typing context
-
-The default typescript interface for `context` is `{ [key: string]: unknown }`. If you prefer a more strict typing in your project or when authoring plugins for others, you can override this using the `declare` syntax.
-
-This is known as "type augmentation" - a TypeScript feature which allows us to add types to existing objects. Simply put this in any .ts or .d.ts file:
-
-```ts
-import { RequestContext as OriginalRequestContext } from 'payload';
-
-declare module 'payload' {
-  // Create a new interface that merges your additional fields with the original one
-  export interface RequestContext extends OriginalRequestContext {
-    myObject?: string;
-    // ...
-  }
-}
-```
-
-This will add a the property `myObject` with a type of string to every context object. Make sure to follow this example correctly, as type augmentation can mess up your types if you do it wrong.

package/docs/hooks/fields.mdx

@@ -1,109 +0,0 @@
----
-title: Field Hooks
-label: Fields
-order: 30
-desc: Hooks can be added to any fields, and optionally modify the return value of the field before the operation continues.
-keywords: hooks, fields, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, express
----
-
-Field-level hooks offer incredible potential for encapsulating your logic. They help to isolate concerns and package up functionalities to be easily reusable across your projects.
-
-**Example use cases include:**
-
-- Automatically add an `owner` relationship to a Document based on the `req.user.id`
-- Encrypt / decrypt a sensitive field using `beforeValidate` and `afterRead` hooks
-- Auto-generate field data using a `beforeValidate` hook
-- Format incoming data such as kebab-casing a document `slug` with `beforeValidate`
-- Restrict updating a document to only once every X hours using the `beforeChange` hook
-
-**All field types provide the following hooks:**
-
-- `beforeValidate`
-- `beforeChange`
-- `afterChange`
-- `afterRead`
-
-## Config
-
-Example field configuration:
-```ts
-import { Field } from 'payload/types';
-
-const ExampleField: Field = {
-  name: 'name',
-  type: 'text',
-  // highlight-start
-  hooks: {
-    beforeValidate: [(args) => {...}],
-    beforeChange: [(args) => {...}],
-    afterChange: [(args) => {...}],
-    afterRead: [(args) => {...}],
-  }
-  // highlight-end
-}
-```
-
-## Arguments and return values
-
-All field-level hooks are formatted to accept the same arguments, although some arguments may be `undefined` based on which field hook you are utilizing.
-
-<Banner type="success">
-  <strong>Tip:</strong><br />
-  It's a good idea to conditionally scope your logic based on which operation is executing. For example, if you are writing a <strong>beforeChange</strong> hook, you may want to perform different logic based on if the current <strong>operation</strong> is <strong>create</strong> or <strong>update</strong>.
-</Banner>
-
-#### Arguments
-
-Field Hooks receive one `args` argument that contains the following properties:
-
-| Option                   | Description                                                                                                                                                                                                           |
-|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **`data`**               | The data passed to update the document within `create` and `update` operations, and the full document itself in the `afterRead` hook.                                                                                 |
-| **`siblingData`**        | The sibling data passed to a field that the hook is running against.                                                                                                                                                  |
-| **`findMany`**           | Boolean to denote if this hook is running against finding one, or finding many within the `afterRead` hook.                                                                                                           |
-| **`operation`**          | A string relating to which operation the field type is currently executing within. Useful within `beforeValidate`, `beforeChange`, and `afterChange` hooks to differentiate between `create` and `update` operations. |
-| **`originalDoc`**        | The full original document in `update` operations. In the `afterChange` hook, this is the resulting document of the operation.                                                                                        |
-| **`previousDoc`**        | The document before changes were applied, only in `afterChange` hooks.                                                                                                                                                |
-| **`previousSiblingDoc`** | The sibling data from the previous document in `afterChange` hook.                                                                                                                                                    |
-| **`req`**                | The Express `request` object. It is mocked for Local API operations.                                                                                                                                                  |
-| **`value`**              | The value of the field.                                                                                                                                                                                               |
-| **`previousValue`**      | The previous value of the field, before changes were applied, only in `afterChange` hooks.                                                                                                                            |
-
-#### Return value
-
-All field hooks can optionally modify the return value of the field before the operation continues. Field Hooks may optionally return the value that should be used within the field.
-
-<Banner type="warning">
-  <strong>Important</strong><br/>
-  Due to GraphQL's typed nature, you should never change the type of data that you return from a field, otherwise GraphQL will produce errors. If you need to change the shape or type of data, reconsider Field Hooks and instead evaluate if Collection / Global hooks might suit you better.
-</Banner>
-
-## TypeScript
-
-Payload exports a type for field hooks which can be accessed and used as follows:
-
-```ts
-import type { FieldHook } from 'payload/types';
-
-// Field hook type is a generic that takes three arguments:
-// 1: The document type
-// 2: The value type
-// 3: The sibling data type
-
-type ExampleFieldHook = FieldHook<ExampleDocumentType, string, SiblingDataType>;
-
-const exampleFieldHook: ExampleFieldHook = (args) => {
-  const {
-    value, // Typed as `string` as shown above
-    data, // Typed as a Partial of your ExampleDocumentType
-    siblingData, // Typed as a Partial of SiblingDataType
-    originalDoc, // Typed as ExampleDocumentType
-    operation,
-    req,
-  } = args;
-
-  // Do something here...
-
-  return value; // should return a string as typed above, undefined, or null
-}
-```