payload 4.0.0-internal.2fddfc0 → 4.0.0-internal.31ba7ee

package/dist/utilities/configToJSONSchema.js

@@ -1,11 +1,13 @@
 import { createHash } from 'crypto';
 import { MissingEditorProp } from '../errors/MissingEditorProp.js';
-import { fieldAffectsData } from '../fields/config/types.js';
+import { fieldAffectsData, fieldIsVirtual } from '../fields/config/types.js';
 import { generateJobsJSONSchemas } from '../queues/config/generateJobsJSONSchemas.js';
 import { flattenAllFields } from './flattenAllFields.js';
 import { formatNames, toWords } from './formatLabels.js';
 import { getCollectionIDFieldTypes } from './getCollectionIDFieldTypes.js';
 import { optionsAreEqual } from './optionsAreEqual.js';
+// Virtual fields (computed) and join fields (derived from the inverse relationship) are read-only.
+const fieldIsInputExcluded = (field)=>field.type === 'join' || fieldIsVirtual(field);
 const fieldIsRequired = (field)=>{
     const isConditional = Boolean(field?.admin && field?.admin?.condition);
     if (isConditional) {
@@ -61,6 +63,22 @@ function generateEntitySelectSchemas(entities) {
         required: Object.keys(properties)
     };
 }
+function generateEntityInputSchemas(entities) {
+    const properties = [
+        ...entities
+    ].reduce((acc, { slug })=>{
+        acc[slug] = {
+            $ref: `#/$defs/${slug}_input`
+        };
+        return acc;
+    }, {});
+    return {
+        type: 'object',
+        additionalProperties: false,
+        properties,
+        required: Object.keys(properties)
+    };
+}
 function generateCollectionJoinsSchemas(collections) {
     const properties = [
         ...collections
@@ -308,11 +326,35 @@ function entityOrFieldToJsDocs({ entity, i18n }) {
     }
     return description;
 }
-export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, forceInlineBlocks, i18n, interfaceNameDefinitions, typeStringDefinitions }) {
+export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, forceInlineBlocks, i18n, interfaceNameDefinitions, typeStringDefinitions, variant = 'output' }) {
     const requiredFieldNames = new Set();
+    // Registers a named-interface (group/tab/array/select) def and returns its `$ref` name. For input,
+    // shares the read-shaped def when byte-identical; otherwise registers an `Input`-suffixed twin so
+    // the write shape doesn't collide with the read one.
+    const registerNamedInterface = (name, schema)=>{
+        if (variant === 'input') {
+            const outputDef = interfaceNameDefinitions.get(name);
+            if (outputDef && JSON.stringify(outputDef) === JSON.stringify(schema)) {
+                return name;
+            }
+            const inputName = `${name}Input`;
+            interfaceNameDefinitions.set(inputName, schema);
+            return inputName;
+        }
+        interfaceNameDefinitions.set(name, schema);
+        return name;
+    };
     return {
         properties: Object.fromEntries(fields.reduce((fieldSchemas, field, index)=>{
+            if (variant === 'input' && fieldIsInputExcluded(field)) {
+                return fieldSchemas;
+            }
+            const hasDefaultValue = 'defaultValue' in field && field.defaultValue !== undefined;
+            // `isRequired` only controls nullability (a non-required field gets `| null`). It does not
+            // change between variants, so e.g. a defaulted field stays non-null on input.
             const isRequired = fieldAffectsData(field) && fieldIsRequired(field);
+            // `isOptionalOnInput` controls the `?`: on input, defaulted fields can be omitted.
+            const isOptionalOnInput = variant === 'input' && hasDefaultValue;
             const fieldDescription = entityOrFieldToJsDocs({
                 entity: field,
                 i18n
@@ -338,14 +380,14 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                     forceInlineBlocks,
                                     i18n,
                                     interfaceNameDefinitions,
-                                    typeStringDefinitions
+                                    typeStringDefinitions,
+                                    variant
                                 })
                             }
                         };
                         if (field.interfaceName) {
-                            interfaceNameDefinitions.set(field.interfaceName, fieldSchema);
                             fieldSchema = {
-                                $ref: `#/$defs/${field.interfaceName}`
+                                $ref: `#/$defs/${registerNamedInterface(field.interfaceName, fieldSchema)}`
                             };
                         }
                         break;
@@ -372,7 +414,8 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                         forceInlineBlocks,
                                         i18n,
                                         interfaceNameDefinitions,
-                                        typeStringDefinitions
+                                        typeStringDefinitions,
+                                        variant
                                     });
                                     const blockSchema = {
                                         type: 'object',
@@ -389,7 +432,7 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                         ]
                                     };
                                     return forceInlineBlocks ? blockSchema : {
-                                        $ref: `#/$defs/${registerBlockInterface(block, blockSchema, interfaceNameDefinitions)}`
+                                        $ref: `#/$defs/${registerBlockInterface(block, blockSchema, interfaceNameDefinitions, variant)}`
                                     };
                                 })
                             } : {}
@@ -407,6 +450,7 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                 case 'code':
                 case 'date':
                 case 'email':
+                case 'slug':
                 case 'textarea':
                     {
                         fieldSchema = {
@@ -429,13 +473,13 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                     forceInlineBlocks,
                                     i18n,
                                     interfaceNameDefinitions,
-                                    typeStringDefinitions
+                                    typeStringDefinitions,
+                                    variant
                                 })
                             };
                             if (field.interfaceName) {
-                                interfaceNameDefinitions.set(field.interfaceName, fieldSchema);
                                 fieldSchema = {
-                                    $ref: `#/$defs/${field.interfaceName}`
+                                    $ref: `#/$defs/${registerNamedInterface(field.interfaceName, fieldSchema)}`
                                 };
                             }
                         }
@@ -560,9 +604,8 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                             enum: buildOptionEnums(field.options)
                         };
                         if (field.interfaceName) {
-                            interfaceNameDefinitions.set(field.interfaceName, fieldSchema);
                             fieldSchema = {
-                                $ref: `#/$defs/${field.interfaceName}`
+                                $ref: `#/$defs/${registerNamedInterface(field.interfaceName, fieldSchema)}`
                             };
                         }
                         break;
@@ -570,6 +613,19 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                 case 'relationship':
                 case 'upload':
                     {
+                        // Read: an ID or the populated doc. Input: only the ID, so drop the `$ref`.
+                        const relationValueSchema = (relation)=>variant === 'input' ? {
+                                type: collectionIDFieldTypes[relation]
+                            } : {
+                                oneOf: [
+                                    {
+                                        type: collectionIDFieldTypes[relation]
+                                    },
+                                    {
+                                        $ref: `#/$defs/${relation}`
+                                    }
+                                ]
+                            };
                         if (Array.isArray(field.relationTo)) {
                             if (field.hasMany) {
                                 fieldSchema = {
@@ -584,16 +640,7 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                                     relationTo: {
                                                         const: relation
                                                     },
-                                                    value: {
-                                                        oneOf: [
-                                                            {
-                                                                type: collectionIDFieldTypes[relation]
-                                                            },
-                                                            {
-                                                                $ref: `#/$defs/${relation}`
-                                                            }
-                                                        ]
-                                                    }
+                                                    value: relationValueSchema(relation)
                                                 },
                                                 required: [
                                                     'value',
@@ -614,16 +661,7 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                                 relationTo: {
                                                     const: relation
                                                 },
-                                                value: {
-                                                    oneOf: [
-                                                        {
-                                                            type: collectionIDFieldTypes[relation]
-                                                        },
-                                                        {
-                                                            $ref: `#/$defs/${relation}`
-                                                        }
-                                                    ]
-                                                }
+                                                value: relationValueSchema(relation)
                                             },
                                             required: [
                                                 'value',
@@ -637,7 +675,9 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                             fieldSchema = {
                                 ...baseFieldSchema,
                                 type: withNullableJSONSchemaType('array', isRequired),
-                                items: {
+                                items: variant === 'input' ? {
+                                    type: collectionIDFieldTypes[field.relationTo]
+                                } : {
                                     oneOf: [
                                         {
                                             type: collectionIDFieldTypes[field.relationTo]
@@ -648,6 +688,11 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                     ]
                                 }
                             };
+                        } else if (variant === 'input') {
+                            fieldSchema = {
+                                ...baseFieldSchema,
+                                type: withNullableJSONSchemaType(collectionIDFieldTypes[field.relationTo], isRequired)
+                            };
                         } else {
                             fieldSchema = {
                                 ...baseFieldSchema,
@@ -682,7 +727,8 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                     i18n,
                                     interfaceNameDefinitions,
                                     isRequired,
-                                    typeStringDefinitions
+                                    typeStringDefinitions,
+                                    variant
                                 })
                             };
                         } else {
@@ -735,9 +781,8 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                 }
                             }
                             if (field.interfaceName) {
-                                interfaceNameDefinitions.set(field.interfaceName, fieldSchema);
                                 fieldSchema = {
-                                    $ref: `#/$defs/${field.interfaceName}`
+                                    $ref: `#/$defs/${registerNamedInterface(field.interfaceName, fieldSchema)}`
                                 };
                             }
                             break;
@@ -757,13 +802,13 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
                                 forceInlineBlocks,
                                 i18n,
                                 interfaceNameDefinitions,
-                                typeStringDefinitions
+                                typeStringDefinitions,
+                                variant
                             })
                         };
                         if (field.interfaceName) {
-                            interfaceNameDefinitions.set(field.interfaceName, fieldSchema);
                             fieldSchema = {
-                                $ref: `#/$defs/${field.interfaceName}`
+                                $ref: `#/$defs/${registerNamedInterface(field.interfaceName, fieldSchema)}`
                             };
                         }
                         break;
@@ -792,12 +837,13 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
             if ('jsonSchema' in field && field?.jsonSchema?.length) {
                 for (const schema of field.jsonSchema){
                     fieldSchema = schema({
-                        jsonSchema: fieldSchema
+                        jsonSchema: fieldSchema,
+                        variant
                     });
                 }
             }
             if (fieldSchema && fieldAffectsData(field)) {
-                if (isRequired && fieldSchema.required !== false) {
+                if (isRequired && !isOptionalOnInput && fieldSchema.required !== false) {
                     requiredFieldNames.add(field.name);
                 }
                 fieldSchemas.set(field.name, fieldSchema);
@@ -808,17 +854,21 @@ export function fieldsToJSONSchema({ collectionIDFieldTypes, config, fields, for
     };
 }
 // This function is part of the public API and is exported through payload/utilities
-export function entityToJSONSchema(config, entity, interfaceNameDefinitions, defaultIDType, typeStringDefinitions, collectionIDFieldTypes, i18n, forceInlineBlocks) {
+export function entityToJSONSchema(config, entity, interfaceNameDefinitions, defaultIDType, typeStringDefinitions, collectionIDFieldTypes, i18n, forceInlineBlocks, variant = 'output') {
     if (!collectionIDFieldTypes) {
         collectionIDFieldTypes = getCollectionIDFieldTypes({
             config,
             defaultIDType
         });
     }
-    const title = entity.typescript?.interface ? entity.typescript.interface : formatNames(entity.slug).singular;
+    const isInput = variant === 'input';
+    const baseTitle = entity.typescript?.interface ? entity.typescript.interface : formatNames(entity.slug).singular;
+    const title = isInput ? `${baseTitle}Input` : baseTitle;
     let mutableFields = [
         ...entity.flattenedFields
     ];
+    // `required: true` keeps `id` non-null. On input it's made optional further below (it's dropped
+    // from `required`) so you can omit it or pass a custom ID, but it's still never `null`.
     const idField = {
         name: 'id',
         type: defaultIDType,
@@ -826,20 +876,18 @@ export function entityToJSONSchema(config, entity, interfaceNameDefinitions, def
     };
     const customIdField = mutableFields.find((field)=>field.name === 'id');
     if (customIdField && customIdField.type !== 'group' && customIdField.type !== 'tab') {
-        mutableFields = mutableFields.map((field)=>{
-            if (field === customIdField) {
-                return {
-                    ...field,
-                    required: true
-                };
-            }
-            return field;
-        });
+        mutableFields = mutableFields.map((field)=>field === customIdField ? {
+                ...field,
+                required: true
+            } : field);
     } else {
         mutableFields.unshift(idField);
     }
-    // mark timestamp fields required
-    if ('timestamps' in entity && entity.timestamps !== false) {
+    if (isInput) {
+        // Timestamps are managed by Payload. `_status` remains because create/update accept it.
+        mutableFields = mutableFields.filter((field)=>field.name !== 'createdAt' && field.name !== 'updatedAt');
+    } else if ('timestamps' in entity && entity.timestamps !== false) {
+        // mark timestamp fields required
         mutableFields = mutableFields.map((field)=>{
             if (field.name === 'createdAt' || field.name === 'updatedAt') {
                 return {
@@ -864,10 +912,16 @@ export function entityToJSONSchema(config, entity, interfaceNameDefinitions, def
         forceInlineBlocks,
         i18n,
         interfaceNameDefinitions,
-        typeStringDefinitions
+        typeStringDefinitions,
+        variant
     });
-    // Add collection property to auth collections
-    if (isAuthCollection) {
+    // On input, `id` is optional (omit it, or pass a custom ID). Removing it from `required` makes
+    // it optional without making it nullable.
+    if (isInput && Array.isArray(fieldsSchema.required)) {
+        fieldsSchema.required = fieldsSchema.required.filter((name)=>name !== 'id');
+    }
+    // The `User`-union discriminator (read-side, e.g. `req.user`); not part of create/update data.
+    if (isAuthCollection && !isInput) {
         fieldsSchema.properties = {
             ...fieldsSchema.properties,
             collection: {
@@ -903,10 +957,11 @@ export function entityToJSONSchema(config, entity, interfaceNameDefinitions, def
  * as part of the whole config schema.
  *
  * Relationship/upload `$ref`s to other collections are left in place - the caller handles those.
- */ export function entityToStandaloneJSONSchema({ config, defaultIDType, entity, i18n }) {
+ * (The `input` variant reduces relationships to IDs, so only rich-text node `$defs` still ref them.)
+ */ export function entityToStandaloneJSONSchema({ config, defaultIDType, entity, i18n, variant = 'output' }) {
     const definitions = new Map();
     // entityToJSONSchema fills `definitions` with everything the fields reference (node unions, blocks).
-    const schema = entityToJSONSchema(config, entity, definitions, defaultIDType, new Set(), undefined, i18n, true);
+    const schema = entityToJSONSchema(config, entity, definitions, defaultIDType, new Set(), undefined, i18n, true, variant);
     // Timezone fields `$ref` supportedTimezones, which lives on the root config schema, so add it here.
     const supportedTimezones = config.admin?.timezones?.supportedTimezones;
     if (supportedTimezones?.length && schemaHasRef([
@@ -1213,8 +1268,19 @@ const hashBlockSchema = (schema)=>createHash('sha256').update(JSON.stringify(sch
  * already uses that name - whether it was auto-generated or an explicit `interfaceName` - this one
  * gets a content-hash suffix (`Hero_3F2A1B0C`) so the two don't overwrite each other. Registering
  * the same block shape again reuses its name.
- */ export function registerBlockInterface(block, blockSchema, interfaceNameDefinitions) {
-    const baseName = block.interfaceName ?? toWords(block.slug, true);
+ *
+ * The `input` variant adds an `Input` suffix (`HeroInput`) - unless the read-shaped def is already
+ * registered with byte-identical content (a block with nothing that differs between input and
+ * output), in which case it's shared as-is rather than emitting a redundant twin.
+ */ export function registerBlockInterface(block, blockSchema, interfaceNameDefinitions, variant = 'output') {
+    const rawName = block.interfaceName ?? toWords(block.slug, true);
+    if (variant === 'input') {
+        const outputDef = interfaceNameDefinitions.get(rawName);
+        if (outputDef && hashBlockSchema(outputDef) === hashBlockSchema(blockSchema)) {
+            return rawName;
+        }
+    }
+    const baseName = variant === 'input' ? `${rawName}Input` : rawName;
     const existing = interfaceNameDefinitions.get(baseName);
     // The name is free - claim it.
     if (!existing) {
@@ -1261,8 +1327,12 @@ const hashBlockSchema = (schema)=>createHash('sha256').update(JSON.stringify(sch
                 entity: collection
             }))
     ];
+    const generateInputTypes = config.typescript?.generateInputTypes === true;
     const entityDefinitions = entities.reduce((acc, { type, entity })=>{
         acc[entity.slug] = entityToJSONSchema(config, entity, interfaceNameDefinitions, defaultIDType, typeStringDefinitions, collectionIDFieldTypes, i18n, forceInlineBlocks);
+        if (generateInputTypes) {
+            acc[`${entity.slug}_input`] = entityToJSONSchema(config, entity, interfaceNameDefinitions, defaultIDType, typeStringDefinitions, collectionIDFieldTypes, i18n, forceInlineBlocks, 'input');
+        }
         const select = fieldsToSelectJSONSchema({
             config,
             fields: entity.flattenedFields,
@@ -1359,6 +1429,10 @@ const hashBlockSchema = (schema)=>createHash('sha256').update(JSON.stringify(sch
             globalsSelect: generateEntitySelectSchemas(config.globals || []),
             locale: generateLocaleEntitySchemas(config.localization),
             widgets: widgetSchemas.schema,
+            ...generateInputTypes ? {
+                collectionsInput: generateEntityInputSchemas(config.collections || []),
+                globalsInput: generateEntityInputSchemas(config.globals || [])
+            } : {},
             ...config.typescript?.strictDraftTypes ? {
                 strictDraftTypes: {
                     type: 'boolean',
@@ -1375,6 +1449,10 @@ const hashBlockSchema = (schema)=>createHash('sha256').update(JSON.stringify(sch
             'collectionsSelect',
             'collectionsJoins',
             'globalsSelect',
+            ...generateInputTypes ? [
+                'collectionsInput',
+                'globalsInput'
+            ] : [],
             ...config.typescript?.strictDraftTypes ? [
                 'strictDraftTypes'
             ] : [],