payload 0.12.12-beta.0 → 0.13.2

package/dist/utilities/sanitizeInternalFields.js

@@ -17,4 +17,4 @@ const sanitizeInternalFields = (incomingDoc) => Object.entries(incomingDoc).redu
     };
 }, {});
 exports.default = sanitizeInternalFields;
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2FuaXRpemVJbnRlcm5hbEZpZWxkcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlsaXRpZXMvc2FuaXRpemVJbnRlcm5hbEZpZWxkcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUFBLE1BQU0sY0FBYyxHQUFHLENBQUMsS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLENBQUMsQ0FBQztBQUUvQyxNQUFNLHNCQUFzQixHQUFHLENBQUMsV0FBVyxFQUFFLEVBQUUsQ0FBQyxNQUFNLENBQUMsT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxDQUFDLE1BQU0sRUFBRSxDQUFDLEdBQUcsRUFBRSxHQUFHLENBQUMsRUFBRSxFQUFFO0lBQ3hHLElBQUksR0FBRyxLQUFLLEtBQUssRUFBRTtRQUNqQixPQUFPO1lBQ0wsR0FBRyxNQUFNO1lBQ1QsRUFBRSxFQUFFLEdBQUc7U0FDUixDQUFDO0tBQ0g7SUFFRCxJQUFJLGNBQWMsQ0FBQyxPQUFPLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQyxDQUFDLEVBQUU7UUFDcEMsT0FBTyxNQUFNLENBQUM7S0FDZjtJQUVELE9BQU87UUFDTCxHQUFHLE1BQU07UUFDVCxDQUFDLEdBQUcsQ0FBQyxFQUFFLEdBQUc7S0FDWCxDQUFDO0FBQ0osQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDO0FBRVAsa0JBQWUsc0JBQXNCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2FuaXRpemVJbnRlcm5hbEZpZWxkcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy91dGlsaXRpZXMvc2FuaXRpemVJbnRlcm5hbEZpZWxkcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQUVBLE1BQU0sY0FBYyxHQUFHLENBQUMsS0FBSyxFQUFFLE1BQU0sRUFBRSxNQUFNLENBQUMsQ0FBQztBQUUvQyxNQUFNLHNCQUFzQixHQUFHLENBQTZCLFdBQVcsRUFBSyxFQUFFLENBQUMsTUFBTSxDQUFDLE9BQU8sQ0FBQyxXQUFXLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxHQUFHLEVBQUUsR0FBRyxDQUFDLEVBQUssRUFBRTtJQUMxSSxJQUFJLEdBQUcsS0FBSyxLQUFLLEVBQUU7UUFDakIsT0FBTztZQUNMLEdBQUcsTUFBTTtZQUNULEVBQUUsRUFBRSxHQUFHO1NBQ1IsQ0FBQztLQUNIO0lBRUQsSUFBSSxjQUFjLENBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxHQUFHLENBQUMsQ0FBQyxFQUFFO1FBQ3BDLE9BQU8sTUFBTSxDQUFDO0tBQ2Y7SUFFRCxPQUFPO1FBQ0wsR0FBRyxNQUFNO1FBQ1QsQ0FBQyxHQUFHLENBQUMsRUFBRSxHQUFHO0tBQ1gsQ0FBQztBQUNKLENBQUMsRUFBRSxFQUFPLENBQUMsQ0FBQztBQUVaLGtCQUFlLHNCQUFzQixDQUFDIn0=

package/docs/admin/components.mdx

@@ -90,13 +90,13 @@ All Payload fields support the ability to swap in your own React components. So,
 
 #### Sending and receiving values from the form
 
-When swapping out the `Field` component, you'll be responsible for sending and receiving the field's `value` from the form itself. To do so, import the `useFieldType` hook as follows:
+When swapping out the `Field` component, you'll be responsible for sending and receiving the field's `value` from the form itself. To do so, import the `useField` hook as follows:
 
 ```js
-import { useFieldType } from 'payload/components/forms';
+import { useField } from 'payload/components/forms';
 
 const CustomTextField = ({ path }) => {
-  const { value, setValue } = useFieldType({ path });
+  const { value, setValue } = useField({ path });
 
   return (
     <input

package/docs/fields/blocks.mdx

@@ -106,3 +106,12 @@ const ExampleCollection = {
 }
 
 ```
+
+### TypeScript
+
+As you build your own Block configs, you might want to store them in separate files but retain typing accordingly. To do so, you can import and use Payload's `Block` type:
+
+```js
+import type { Block } from 'payload/types';
+
+```

package/docs/fields/overview.mdx

@@ -239,3 +239,15 @@ This example will display the number of characters allowed as the user types.
 }
 ```
 This component will count the number of characters entered.
+
+### TypeScript
+
+You can import the internal Payload `Field` type as well as other common field types as follows:
+
+```js
+import type {
+  Field,
+  Validate,
+  Condition,
+} from 'payload/types';
+```

package/docs/fields/rich-text.mdx

@@ -313,3 +313,14 @@ Above, you can see that we are creating a custom SlateJS element with a name of
 
 The plugin itself extends Payload's built-in `shouldBreakOutOnEnter` Slate function to add its own element name to the list of elements that should "break out" when the `enter` key is pressed.
 
+### TypeScript
+
+If you are building your own custom Rich Text elements or leaves, you may benefit from importing the following types:
+
+```js
+import type {
+  RichTextCustomElement,
+  RichTextCustomLeaf,
+} from 'payload/types';
+
+```

package/docs/hooks/collections.mdx

@@ -188,3 +188,26 @@ const afterLoginHook = async ({
   return user;
 }
 ```
+
+## TypeScript
+
+Payload exports a type for each Collection hook which can be accessed as follows:
+
+```js
+import type {
+  CollectionBeforeOperationHook,
+  CollectionBeforeValidateHook,
+  CollectionBeforeChangeHook,
+  CollectionAfterChangeHook,
+  CollectionAfterReadHook,
+  CollectionBeforeReadHook,
+  CollectionBeforeDeleteHook,
+  CollectionAfterDeleteHook,
+  CollectionBeforeLoginHook,
+  CollectionAfterLoginHook,
+  CollectionAfterForgotPasswordHook,
+} from 'payload/types';
+
+// Use hook types here...
+}
+```

package/docs/hooks/fields.mdx

@@ -70,3 +70,31 @@ All field hooks can optionally modify the return value of the field before the o
   <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:
+
+```js
+import type { FieldHook } from 'payload/types';
+
+// Field hook type is a generic that takes two arguments:
+// 1: The document type
+// 2: the value type
+
+type ExampleFieldHook = FieldHook<ExampleDocumentType, string>;
+
+const exampleFieldHook: ExampleFieldHook = (args) => {
+  const {
+    value, // Typed as `string` as shown above
+    data, // Typed as a Partial of your ExampleDocumentType
+    originalDoc, // Typed as ExampleDocumentType
+    operation,
+    req,
+  }
+
+  // Do something here...
+
+  return value; // should return a string as typed above, undefined, or null
+}
+```

package/docs/hooks/globals.mdx

@@ -98,3 +98,20 @@ const afterReadHook = async ({
   req, // full express request
 }) => {...}
 ```
+
+## TypeScript
+
+Payload exports a type for each Global hook which can be accessed as follows:
+
+```js
+import type {
+  GlobalBeforeValidateHook,
+  GlobalBeforeChangeHook,
+  GlobalAfterChangeHook,
+  GlobalBeforeReadHook,
+  GlobalAfterReadHook,
+} from 'payload/types';
+
+// Use hook types here...
+}
+```

package/docs/typescript/generating-types.mdx

@@ -0,0 +1,114 @@
+---
+title: Generating TypeScript Interfaces
+label: Generating Types
+order: 20
+desc: Generate your own TypeScript interfaces based on your collections and globals.
+keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, express
+---
+
+While building your own custom functionality into Payload, like plugins, hooks, access control functions, custom routes, GraphQL queries / mutations, or anything else, you may benefit from generating your own TypeScript types dynamically from your Payload config itself.
+
+Run the following command in a Payload project to generate types:
+
+```
+payload generate:types
+```
+
+You can run this command whenever you need to regenerate your types, and then you can use these types in your Payload code directly.
+
+For example, let's look at the following simple Payload config:
+
+```ts
+const config: Config = {
+  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
+  admin: {
+    user: 'users',
+  }
+  collections: [
+    {
+      slug: 'users',
+      fields: [
+        {
+          name: 'name',
+          type: 'text',
+          required: true,
+        }
+      ]
+    },
+    {
+      slug: 'posts',
+      admin: {
+        useAsTitle: 'title',
+      },
+      fields: [
+        {
+          name: 'title',
+          type: 'text',
+        },
+        {
+          name: 'author',
+          type: 'relationship',
+          relationTo: 'users',
+        },
+      ]
+    }
+  ]
+}
+```
+
+By generating types, we'll end up with a file containing the following two TypeScript interfaces:
+
+```ts
+export interface User {
+  id: string;
+  name: string;
+  email?: string;
+  resetPasswordToken?: string;
+  resetPasswordExpiration?: string;
+  loginAttempts?: number;
+  lockUntil?: string;
+}
+
+export interface Post {
+  id: string;
+  title?: string;
+  author?: string | User;
+}
+
+```
+
+#### Customizing the output path of your generated types
+
+You can specify where you want your types to be generated by adding a property to your Payload config:
+
+```
+{
+  // the remainder of your config
+	typescript: {
+		outputFile: path.resolve(__dirname, './generated-types.ts'),
+	},
+}
+```
+
+The above example places your types next to your Payload config itself as the file `generated-types.ts`. By default, the file will be output to your current working directory as `payload-types.ts`.
+
+#### Adding an NPM script
+
+<Banner type="warning">
+  <strong>Important:</strong><br/>
+  Payload needs to be able to find your config to generate your types.
+</Banner>
+
+Payload will automatically try and locate your config, but might not always be able to find it. For example, if you are working in a `/src` directory or similar, you need to tell Payload where to find your config manually by using an environment variable. If this applies to you, you can create an NPM script to make generating your types easier.
+
+To add an NPM script to generate your types and show Payload where to find your config, open your `package.json` and update the `scripts` property to the following:
+
+```
+{
+  "scripts": {
+    "generate:types": "PAYLOAD_CONFIG_PATH=src/payload.config.ts payload generate:types",
+  },
+}
+```
+
+Now you can run `yarn generate:types` to easily generate your types.

package/docs/typescript/overview.mdx

@@ -0,0 +1,36 @@
+---
+title: TypeScript - Overview
+label: Overview
+order: 10
+desc: Payload is the most powerful TypeScript headless CMS available.
+keywords: headless cms, typescript, documentation, Content Management System, cms, headless, javascript, node, react, express
+---
+
+Payload supports TypeScript natively, and not only that, the entirety of the CMS is built with TypeScript. To get started developing with Payload and TypeScript, you can use one of Payload's built-in boilerplates in one line via `create-payload-app`:
+
+```
+npx create-payload-app
+```
+
+Pick a TypeScript project type to get started easily.
+
+#### Setting up from Scratch
+
+It's also possible to set up a TypeScript project from scratch. We plan to write up a guide for exactly how—so keep an eye out for that, too.
+
+## Using Payload's Exported Types
+
+Payload exports a number of types that you may find useful while writing your own plugins, hooks, access control functions, custom routes, GraphQL queries / mutations, or anything else.
+
+##### Config Types
+
+- [Base config](/docs/configuration/overview#typescript)
+- [Collections](/docs/configuration/collections#typescript)
+- [Globals](/docs/configuration/globals#typescript)
+- [Fields](/docs/fields/overview#typescript)
+
+##### Hook Types
+
+- [Collection hooks](/docs/hooks/collections#typescript)
+- [Global hooks](/docs/hooks/globals#typescript)
+- [Field hooks](/docs/hooks/fields#typescript)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload",
-  "version": "0.12.12-beta.0",
+  "version": "0.13.2",
   "description": "Node, React and MongoDB Headless CMS and Application Framework",
   "license": "SEE LICENSE IN license.md",
   "author": {

package/types.d.ts

@@ -16,5 +16,21 @@ export {
   AfterForgotPasswordHook as CollectionAfterForgotPasswordHook,
 } from './dist/collections/config/types';
 
-export { GlobalConfig, SanitizedGlobalConfig } from './dist/globals/config/types';
-export { Field, FieldHook, FieldAccess, RichTextCustomElement, RichTextCustomLeaf, Block } from './dist/fields/config/types';
+export {
+  GlobalConfig,
+  SanitizedGlobalConfig,
+  BeforeValidateHook as GlobalBeforeValidateHook,
+  BeforeChangeHook as GlobalBeforeChangeHook,
+  AfterChangeHook as GlobalAfterChangeHook,
+  BeforeReadHook as GlobalBeforeReadHook,
+  AfterReadHook as GlobalAfterReadHook,
+} from './dist/globals/config/types';
+
+export {
+  Field,
+  FieldHook,
+  FieldAccess,
+  RichTextCustomElement,
+  RichTextCustomLeaf,
+  Block,
+} from './dist/fields/config/types';

package/dist/admin/components/forms/useFieldType/index.d.ts

@@ -1,3 +0,0 @@
-import { Options, FieldType } from './types';
-declare const useFieldType: <T extends unknown>(options: Options) => FieldType<T>;
-export default useFieldType;