payload 1.0.27 → 1.0.28

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',
+  },
+})
+```

package/docs/plugins/overview.mdx

@@ -83,11 +83,10 @@ After all plugins are executed, the full config with all plugins will be sanitiz
 
 Here is an example for how to automatically add a `lastModifiedBy` field to all Payload collections using a Plugin written in TypeScript.
 
-```js
-import { Config } from 'payload/config';
-import { CollectionConfig } from 'payload/dist/collections/config/types';
+```ts
+import { Config, Plugin } from 'payload/config';
 
-const addLastModified = (incomingConfig: Config): Config => {
+const addLastModified: Plugin = (incomingConfig: Config): Config => {
   // Find all incoming auth-enabled collections
   // so we can create a lastModifiedBy relationship field
   // to all auth collections

package/docs/production/deployment.mdx

@@ -37,7 +37,7 @@ Because _**you**_ are in complete control of who can do what with your data, you
 Before running in Production, you need to have built a production-ready copy of the Payload Admin panel. To do this, Payload provides the `build` NPM script. You can use it by adding a `script` to your `package.json` file like this:
 
 `package.json`:
-```js
+```json
 {
   "name": "project-name-here",
   "scripts": {

package/docs/queries/overview.mdx

@@ -16,8 +16,10 @@ Payload provides an extremely granular querying language through all APIs. Each
 
 For example, say you have a collection as follows:
 
-```js
-const Post = {
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Post: CollectionConfig = {
   slug: 'posts',
   fields: [
     {

package/docs/queries/pagination.mdx

@@ -24,7 +24,7 @@ All collection `find` queries are paginated automatically. Responses are returne
 | nextPage      | `number` of next page, `null` if it doesn't exist          |
 
 **Example response:**
-```js
+```json
 {
   // Document Array // highlight-line
   "docs": [

package/docs/rest-api/overview.mdx

@@ -89,9 +89,11 @@ Each endpoint object needs to have:
 
 Example:
 
-```js
+```ts
+import { CollectionConfig } from 'payload/types';
+
 // a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
-const Orders = {
+const Orders: CollectionConfig = {
 	slug: 'orders',
 	fields: [ /* ... */ ],
   // highlight-start

package/docs/upload/overview.mdx

@@ -55,38 +55,40 @@ _An asterisk denotes that a property above is required._
 
 **Example Upload collection:**
 
-```js
-const Media = {
-  slug: "media",
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Media: CollectionConfig = {
+  slug: 'media',
   upload: {
-    staticURL: "/media",
-    staticDir: "media",
+    staticURL: '/media',
+    staticDir: 'media',
     imageSizes: [
       {
-        name: "thumbnail",
+        name: 'thumbnail',
         width: 400,
         height: 300,
-        crop: "centre",
+        crop: 'centre',
       },
       {
-        name: "card",
+        name: 'card',
         width: 768,
         height: 1024,
-        crop: "centre",
+        crop: 'centre',
       },
       {
-        name: "tablet",
+        name: 'tablet',
         width: 1024,
         // By specifying `null` or leaving a height undefined,
         // the image will be sized to a certain width,
         // but it will retain its original aspect ratio
         // and calculate a height automatically.
         height: null,
-        crop: "centre",
+        crop: 'centre',
       },
     ],
-    adminThumbnail: "thumbnail",
-    mimeTypes: ["image/*"],
+    adminThumbnail: 'thumbnail',
+    mimeTypes: ['image/*'],
   },
 };
 ```
@@ -97,17 +99,17 @@ Payload relies on the [`express-fileupload`](https://www.npmjs.com/package/expre
 
 A common example of what you might want to customize within Payload-wide Upload options would be to increase the allowed `fileSize` of uploads sent to Payload:
 
-```js
-import { buildConfig } from "payload/config";
+```ts
+import { buildConfig } from 'payload/config';
 
 export default buildConfig({
   collections: [
     {
-      slug: "media",
+      slug: 'media',
       fields: [
         {
-          name: "alt",
-          type: "text",
+          name: 'alt',
+          type: 'text',
         },
       ],
       upload: true,
@@ -158,12 +160,14 @@ You can specify how Payload retrieves admin thumbnails for your upload-enabled C
 
 **Example custom Admin thumbnail:**
 
-```js
-const Media = {
-  slug: "media",
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Media: CollectionConfig = {
+  slug: 'media',
   upload: {
-    staticURL: "/media",
-    staticDir: "media",
+    staticURL: '/media',
+    staticDir: 'media',
     imageSizes: [
       // ... image sizes here
     ],
@@ -191,13 +195,15 @@ Some example values are: `image/*`, `audio/*`, `video/*`, `image/png`, `applicat
 
 **Example mimeTypes usage:**
 
-```js
-const Media = {
-  slug: "media",
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Media: CollectionConfig = {
+  slug: 'media',
   upload: {
-    staticURL: "/media",
-    staticDir: "media",
-    mimeTypes: ["image/*", "application/pdf"], // highlight-line
+    staticURL: '/media',
+    staticDir: 'media',
+    mimeTypes: ['image/*', 'application/pdf'], // highlight-line
   },
 };
 ```

package/docs/versions/autosave.mdx

@@ -25,8 +25,10 @@ Collections and Globals both support the same options for configuring autosave.
 
 **Example config with versions, drafts, and autosave enabled:**
 
-```js
-const Pages = {
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Pages: CollectionConfig = {
   slug: 'pages',
   access: {
     read: ({ req }) => {

package/docs/versions/drafts.mdx

@@ -81,8 +81,10 @@ You can use the `read` [Access Control](/docs/access-control/collections#read) m
 
 Here is an example that utilizes the `_status` field to require a user to be logged in to retrieve drafts:
 
-```js
-const Pages = {
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Pages: CollectionConfig = {
   slug: 'pages',
   access: {
     read: ({ req }) => {
@@ -114,8 +116,10 @@ const Pages = {
 
 Here is an example for how to write an access control function that grants access to both documents where `_status` is equal to "published" and where `_status` does not exist:
 
-```js
-const Pages = {
+```ts
+import { CollectionConfig } from 'payload/types';
+
+const Pages: CollectionConfig = {
   slug: 'pages',
   access: {
     read: ({ req }) => {

package/docs/versions/overview.mdx

@@ -77,7 +77,7 @@ _slug_versions
 
 Each document in this new `versions` collection will store a set of meta properties about the version as well as a _full_ copy of the document. For example, a version's data might look like this for a Collection document:
 
-```js
+```json
 {
   "_id": "61cf752c19cdf1b1af7b61f1", // a unique ID of this version
   "parent": "61ce1354091d5b3ffc20ea6e", // the ID of the parent document

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Node, React and MongoDB Headless CMS and Application Framework",
   "license": "MIT",
   "author": {