@payloadcms/figma 0.0.1-alpha.3 → 0.0.1-alpha.31

package/dist/db-content-api/utilities/data/index.js

@@ -0,0 +1,166 @@
+import { flattenAllFields, traverseFields } from 'payload';
+import { applyDefaults } from './applyDefaults.js';
+import { castFieldValue } from './castFieldValue.js';
+import { stripFields } from './stripFields.js';
+/**
+ * Transform data before sending to Content API (WRITE operations)
+ *
+ * Conversions applied:
+ * - Default values: Apply static defaults for undefined fields (when applyDefaults=true)
+ * - Type casting: Convert values to match field types (e.g., number -> string for text fields)
+ * - RichText fields: Objects -> JSON strings
+ *
+ * Note: Date fields are automatically converted to ISO strings by JSON.stringify()
+ */ export function dataToContentAPI(payload, collectionSlug, data, options) {
+    if (!data || typeof data !== 'object') {
+        return data;
+    }
+    // Deep clone to avoid mutating original data
+    const transformed = JSON.parse(JSON.stringify(data));
+    // Get collection config
+    const isGlobal = collectionSlug.startsWith('_global-');
+    const actualSlug = isGlobal ? collectionSlug.substring(8) : collectionSlug;
+    const collectionConfig = isGlobal ? payload.config.globals?.find((g)=>g.slug === actualSlug) : payload.config.collections.find((c)=>c.slug === actualSlug);
+    if (!collectionConfig?.fields) {
+        return transformed;
+    }
+    // Apply static defaults recursively to handle nested structures (arrays, groups)
+    // This must happen before traverseFields to ensure defaults are in place
+    if (options?.applyDefaults) {
+        applyDefaults(transformed, collectionConfig.fields);
+    }
+    // Use Payload's traverseFields to iterate over all fields for transformations
+    const callback = ({ field, ref })=>{
+        if (!('name' in field) || !field.name) {
+            return;
+        }
+        if (!ref || typeof ref !== 'object') {
+            return;
+        }
+        const current = ref;
+        let value = current[field.name];
+        // Transform existing values
+        if (value !== null && value !== undefined) {
+            // Step 1: Apply type casting (e.g., number -> string for text fields)
+            value = castFieldValue(field, value);
+            current[field.name] = value;
+            // Step 2: Apply Content API specific transformations
+            // RichText: object -> JSON string
+            if (field.type === 'richText' && typeof value !== 'string') {
+                current[field.name] = JSON.stringify(value);
+            }
+        // Date fields are already handled by JSON.stringify() which converts Date -> ISO string
+        }
+    };
+    traverseFields({
+        callback,
+        fields: collectionConfig.fields,
+        ref: transformed
+    });
+    stripFields({
+        config: payload.config,
+        data: transformed,
+        fields: flattenAllFields({
+            cache: true,
+            fields: collectionConfig.fields
+        }),
+        reservedKeys: [
+            'id',
+            'globalType'
+        ]
+    });
+    // Convert numeric ID to string for Content API
+    const customIDType = payload.collections?.[collectionSlug]?.customIDType;
+    if (customIDType === 'number') {
+        transformed.id = String(transformed.id);
+    }
+    return transformed;
+}
+/**
+ * Transform data received from Content API (READ operations)
+ *
+ * Conversions applied:
+ * - RichText fields: JSON strings -> Objects
+ *
+ * Note: Date fields come as ISO strings from Content API and stay as strings
+ * (matching MongoDB and other adapters' behavior)
+ */ export function dataFromContentAPI(payload, collectionSlug, data) {
+    if (!data || typeof data !== 'object') {
+        return data;
+    }
+    // Deep clone to avoid mutating original data
+    const transformed = JSON.parse(JSON.stringify(data));
+    // Get collection config
+    const isGlobal = collectionSlug.startsWith('_global-');
+    const actualSlug = isGlobal ? collectionSlug.substring(8) : collectionSlug;
+    const collectionConfig = isGlobal ? payload.config.globals?.find((g)=>g.slug === actualSlug) : payload.config.collections.find((c)=>c.slug === actualSlug);
+    if (!collectionConfig?.fields) {
+        return transformed;
+    }
+    // Use Payload's traverseFields to iterate over all fields
+    const callback = ({ field, parentPath, ref })=>{
+        if (!('name' in field) || !field.name) {
+            return;
+        }
+        if (!ref || typeof ref !== 'object') {
+            return;
+        }
+        const current = ref;
+        const value = current[field.name];
+        if (value !== null && value !== undefined) {
+            // RichText: JSON string -> object
+            if (field.type === 'richText' && typeof value === 'string') {
+                try {
+                    current[field.name] = JSON.parse(value);
+                } catch (error) {
+                    const fieldPath = parentPath ? `${parentPath}.${field.name}` : field.name;
+                    payload.logger.warn({
+                        err: error instanceof Error ? error : new Error(String(error)),
+                        msg: `Failed to parse richtext field '${fieldPath}' in collection '${collectionSlug}'`
+                    });
+                }
+            }
+        // Date fields: Already ISO strings from Content API, no conversion needed
+        }
+    };
+    traverseFields({
+        callback,
+        fields: collectionConfig.fields,
+        ref: transformed
+    });
+    // Convert string ID to number if collection uses numeric custom ID
+    const customIDType = payload.collections?.[collectionSlug]?.customIDType;
+    if (customIDType === 'number') {
+        transformed.id = Number(transformed.id);
+    }
+    stripFields({
+        config: payload.config,
+        data: transformed,
+        fields: flattenAllFields({
+            cache: true,
+            fields: collectionConfig.fields
+        }),
+        reservedKeys: [
+            'id',
+            'globalType'
+        ]
+    });
+    // Handle auth-specific fields that aren't in the field schema
+    // When these fields are null in DB, Content API omits them from response (undefined)
+    // But Payload expects them to be null, not undefined
+    // Only add them if the collection has auth enabled
+    if ('auth' in collectionConfig && collectionConfig.auth) {
+        const authFields = [
+            'resetPasswordExpiration',
+            'lockUntil'
+        ];
+        for (const fieldName of authFields){
+            if (!(fieldName in transformed)) {
+                transformed[fieldName] = null;
+            }
+        }
+    }
+    return transformed;
+}
+
+//# sourceMappingURL=index.js.map

package/dist/db-content-api/utilities/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/db-content-api/utilities/data/index.ts"],"sourcesContent":["import type { CollectionConfig, GlobalConfig, Payload, TraverseFieldsCallback } from 'payload'\n\nimport { flattenAllFields, traverseFields } from 'payload'\n\nimport type { components } from '../../generated/content-api-types.js'\n\nimport { applyDefaults } from './applyDefaults.js'\nimport { castFieldValue } from './castFieldValue.js'\nimport { stripFields } from './stripFields.js'\n\ntype DataWithOperations = components['schemas']['DataWithOperations']\n\n/**\n * Transform data before sending to Content API (WRITE operations)\n *\n * Conversions applied:\n * - Default values: Apply static defaults for undefined fields (when applyDefaults=true)\n * - Type casting: Convert values to match field types (e.g., number -> string for text fields)\n * - RichText fields: Objects -> JSON strings\n *\n * Note: Date fields are automatically converted to ISO strings by JSON.stringify()\n */\nexport function dataToContentAPI(\n  payload: Payload,\n  collectionSlug: string,\n  data: unknown,\n  options?: { applyDefaults?: boolean },\n): DataWithOperations {\n  if (!data || typeof data !== 'object') {\n    return data as DataWithOperations\n  }\n\n  // Deep clone to avoid mutating original data\n  const transformed = JSON.parse(JSON.stringify(data))\n\n  // Get collection config\n  const isGlobal = collectionSlug.startsWith('_global-')\n  const actualSlug = isGlobal ? collectionSlug.substring(8) : collectionSlug\n  const collectionConfig: CollectionConfig | GlobalConfig | undefined = isGlobal\n    ? payload.config.globals?.find((g) => g.slug === actualSlug)\n    : payload.config.collections.find((c) => c.slug === actualSlug)\n\n  if (!collectionConfig?.fields) {\n    return transformed as DataWithOperations\n  }\n\n  // Apply static defaults recursively to handle nested structures (arrays, groups)\n  // This must happen before traverseFields to ensure defaults are in place\n  if (options?.applyDefaults) {\n    applyDefaults(transformed, collectionConfig.fields)\n  }\n\n  // Use Payload's traverseFields to iterate over all fields for transformations\n  const callback: TraverseFieldsCallback = ({ field, ref }) => {\n    if (!('name' in field) || !field.name) {\n      return\n    }\n    if (!ref || typeof ref !== 'object') {\n      return\n    }\n\n    const current = ref as Record<string, unknown>\n    let value = current[field.name]\n\n    // Transform existing values\n    if (value !== null && value !== undefined) {\n      // Step 1: Apply type casting (e.g., number -> string for text fields)\n      value = castFieldValue(field, value)\n      current[field.name] = value\n\n      // Step 2: Apply Content API specific transformations\n      // RichText: object -> JSON string\n      if (field.type === 'richText' && typeof value !== 'string') {\n        current[field.name] = JSON.stringify(value)\n      }\n      // Date fields are already handled by JSON.stringify() which converts Date -> ISO string\n    }\n  }\n\n  traverseFields({ callback, fields: collectionConfig.fields, ref: transformed })\n\n  stripFields({\n    config: payload.config,\n    data: transformed,\n    fields: flattenAllFields({ cache: true, fields: collectionConfig.fields }),\n    reservedKeys: ['id', 'globalType'],\n  })\n\n  // Convert numeric ID to string for Content API\n  const customIDType = payload.collections?.[collectionSlug]?.customIDType\n  if (customIDType === 'number') {\n    transformed.id = String(transformed.id)\n  }\n\n  return transformed as DataWithOperations\n}\n\n/**\n * Transform data received from Content API (READ operations)\n *\n * Conversions applied:\n * - RichText fields: JSON strings -> Objects\n *\n * Note: Date fields come as ISO strings from Content API and stay as strings\n * (matching MongoDB and other adapters' behavior)\n */\nexport function dataFromContentAPI(\n  payload: Payload,\n  collectionSlug: string,\n  data: unknown,\n): unknown {\n  if (!data || typeof data !== 'object') {\n    return data\n  }\n\n  // Deep clone to avoid mutating original data\n  const transformed = JSON.parse(JSON.stringify(data))\n\n  // Get collection config\n  const isGlobal = collectionSlug.startsWith('_global-')\n  const actualSlug = isGlobal ? collectionSlug.substring(8) : collectionSlug\n  const collectionConfig: CollectionConfig | GlobalConfig | undefined = isGlobal\n    ? payload.config.globals?.find((g) => g.slug === actualSlug)\n    : payload.config.collections.find((c) => c.slug === actualSlug)\n\n  if (!collectionConfig?.fields) {\n    return transformed\n  }\n\n  // Use Payload's traverseFields to iterate over all fields\n  const callback: TraverseFieldsCallback = ({ field, parentPath, ref }) => {\n    if (!('name' in field) || !field.name) {\n      return\n    }\n    if (!ref || typeof ref !== 'object') {\n      return\n    }\n\n    const current = ref as Record<string, unknown>\n    const value = current[field.name]\n\n    if (value !== null && value !== undefined) {\n      // RichText: JSON string -> object\n      if (field.type === 'richText' && typeof value === 'string') {\n        try {\n          current[field.name] = JSON.parse(value)\n        } catch (error) {\n          const fieldPath = parentPath ? `${parentPath}.${field.name}` : field.name\n          payload.logger.warn({\n            err: error instanceof Error ? error : new Error(String(error)),\n            msg: `Failed to parse richtext field '${fieldPath}' in collection '${collectionSlug}'`,\n          })\n        }\n      }\n      // Date fields: Already ISO strings from Content API, no conversion needed\n    }\n  }\n\n  traverseFields({ callback, fields: collectionConfig.fields, ref: transformed })\n\n  // Convert string ID to number if collection uses numeric custom ID\n  const customIDType = payload.collections?.[collectionSlug]?.customIDType\n  if (customIDType === 'number') {\n    transformed.id = Number(transformed.id)\n  }\n\n  stripFields({\n    config: payload.config,\n    data: transformed,\n    fields: flattenAllFields({ cache: true, fields: collectionConfig.fields }),\n    reservedKeys: ['id', 'globalType'],\n  })\n\n  // Handle auth-specific fields that aren't in the field schema\n  // When these fields are null in DB, Content API omits them from response (undefined)\n  // But Payload expects them to be null, not undefined\n  // Only add them if the collection has auth enabled\n  if ('auth' in collectionConfig && collectionConfig.auth) {\n    const authFields = ['resetPasswordExpiration', 'lockUntil']\n    for (const fieldName of authFields) {\n      if (!(fieldName in transformed)) {\n        transformed[fieldName] = null\n      }\n    }\n  }\n\n  return transformed\n}\n"],"names":["flattenAllFields","traverseFields","applyDefaults","castFieldValue","stripFields","dataToContentAPI","payload","collectionSlug","data","options","transformed","JSON","parse","stringify","isGlobal","startsWith","actualSlug","substring","collectionConfig","config","globals","find","g","slug","collections","c","fields","callback","field","ref","name","current","value","undefined","type","cache","reservedKeys","customIDType","id","String","dataFromContentAPI","parentPath","error","fieldPath","logger","warn","err","Error","msg","Number","auth","authFields","fieldName"],"mappings":"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"}

package/dist/db-content-api/utilities/data/stripFields.d.ts

@@ -0,0 +1,48 @@
+import type { FlattenedField, SanitizedConfig } from 'payload';
+/**
+ * Strips fields from data that are not defined in the schema or are invalid.
+ *
+ * This function was copied from the MongoDB adapter's implementation:
+ * @see packages/db-mongodb/src/utilities/transform.ts (stripFields function)
+ *
+ * @description
+ * This utility performs deep sanitization of document data by:
+ * 1. **Removing undefined fields**: Strips any field not present in the collection's schema
+ *    (e.g., sensitive fields like `password`, `apiKey`, or any extra fields not in config)
+ * 2. **Removing invalid locales**: Deletes locale keys that don't exist in `config.localization.localeCodes`
+ *    (e.g., if data contains `{ "es-MX": "..." }` but only `"en"` is configured)
+ * 3. **Removing invalid blocks**: Filters out blocks with unknown `blockType` values
+ *    (prevents data corruption from blocks that don't exist in the schema)
+ * 4. **Recursive sanitization**: Processes nested structures (arrays, groups, blocks, localized fields)
+ *    to ensure deep data integrity
+ *
+ * @remarks
+ * Unlike MongoDB's adapter which uses Mongoose schemas with `strict: true` (rejecting extra fields
+ * on write), Content API uses flexible JSONB storage that accepts any fields. Therefore, this
+ * function is called on **both read and write operations** to ensure data consistency.
+ *
+ * The MongoDB adapter also supports an `allowAdditionalKeys` option that allows reading/writing
+ * fields not in the schema. For now, Content API does not support this feature - we always
+ * sanitize data. If users request this functionality in the future, we can consider adding it.
+ *
+ * @todo
+ * 1. Consider moving this utility to `payload/shared` so both MongoDB and Content API adapters
+ *    can use the same implementation, reducing code duplication and maintenance burden.
+ *
+ * 2. Performance optimization: This function iterates through all fields recursively.
+ *    The `dataToContentAPI` and `dataFromContentAPI` functions in
+ *    `packages/figma/src/db-content-api/utilities/data.ts` also iterate through fields
+ *    to transform richText (object ↔ JSON string), custom IDs (number ↔ string), and dates.
+ *    Consider combining both traversals into a single abstraction to avoid iterating twice.
+ *
+ * 3. Feature parity: MongoDB adapter has `allowAdditionalKeys` option. We currently always
+ *    strip additional keys, but could add this as a configurable option if users need it.
+ */
+export declare const stripFields: ({ config, data, fields, parentIsLocalized, reservedKeys, }: {
+    config: SanitizedConfig;
+    data: any;
+    fields: FlattenedField[];
+    parentIsLocalized?: boolean;
+    reservedKeys?: string[];
+}) => void;
+//# sourceMappingURL=stripFields.d.ts.map

package/dist/db-content-api/utilities/data/stripFields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripFields.d.ts","sourceRoot":"","sources":["../../../../src/db-content-api/utilities/data/stripFields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAI9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,WAAW,+DAMrB;IACD,MAAM,EAAE,eAAe,CAAA;IAEvB,IAAI,EAAE,GAAG,CAAA;IACT,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB,SAmLA,CAAA"}

package/dist/db-content-api/utilities/data/stripFields.js

@@ -0,0 +1,195 @@
+import { fieldShouldBeLocalized } from 'payload/shared';
+/**
+ * Strips fields from data that are not defined in the schema or are invalid.
+ *
+ * This function was copied from the MongoDB adapter's implementation:
+ * @see packages/db-mongodb/src/utilities/transform.ts (stripFields function)
+ *
+ * @description
+ * This utility performs deep sanitization of document data by:
+ * 1. **Removing undefined fields**: Strips any field not present in the collection's schema
+ *    (e.g., sensitive fields like `password`, `apiKey`, or any extra fields not in config)
+ * 2. **Removing invalid locales**: Deletes locale keys that don't exist in `config.localization.localeCodes`
+ *    (e.g., if data contains `{ "es-MX": "..." }` but only `"en"` is configured)
+ * 3. **Removing invalid blocks**: Filters out blocks with unknown `blockType` values
+ *    (prevents data corruption from blocks that don't exist in the schema)
+ * 4. **Recursive sanitization**: Processes nested structures (arrays, groups, blocks, localized fields)
+ *    to ensure deep data integrity
+ *
+ * @remarks
+ * Unlike MongoDB's adapter which uses Mongoose schemas with `strict: true` (rejecting extra fields
+ * on write), Content API uses flexible JSONB storage that accepts any fields. Therefore, this
+ * function is called on **both read and write operations** to ensure data consistency.
+ *
+ * The MongoDB adapter also supports an `allowAdditionalKeys` option that allows reading/writing
+ * fields not in the schema. For now, Content API does not support this feature - we always
+ * sanitize data. If users request this functionality in the future, we can consider adding it.
+ *
+ * @todo
+ * 1. Consider moving this utility to `payload/shared` so both MongoDB and Content API adapters
+ *    can use the same implementation, reducing code duplication and maintenance burden.
+ *
+ * 2. Performance optimization: This function iterates through all fields recursively.
+ *    The `dataToContentAPI` and `dataFromContentAPI` functions in
+ *    `packages/figma/src/db-content-api/utilities/data.ts` also iterate through fields
+ *    to transform richText (object ↔ JSON string), custom IDs (number ↔ string), and dates.
+ *    Consider combining both traversals into a single abstraction to avoid iterating twice.
+ *
+ * 3. Feature parity: MongoDB adapter has `allowAdditionalKeys` option. We currently always
+ *    strip additional keys, but could add this as a configurable option if users need it.
+ */ export const stripFields = ({ config, data, fields, parentIsLocalized = false, reservedKeys = [] })=>{
+    for(const k in data){
+        if (!fields.some((field)=>field.name === k) && !reservedKeys.includes(k)) {
+            delete data[k];
+        }
+    }
+    for (const field of fields){
+        reservedKeys = [];
+        const fieldData = data[field.name];
+        if (!fieldData || typeof fieldData !== 'object') {
+            continue;
+        }
+        const shouldLocalizeField = fieldShouldBeLocalized({
+            field,
+            parentIsLocalized
+        });
+        if (field.type === 'blocks') {
+            reservedKeys.push('blockType');
+        }
+        if ('flattenedFields' in field || 'blocks' in field) {
+            if (shouldLocalizeField && config.localization) {
+                for(const localeKey in fieldData){
+                    if (!config.localization.localeCodes.some((code)=>code === localeKey)) {
+                        delete fieldData[localeKey];
+                        continue;
+                    }
+                    const localeData = fieldData[localeKey];
+                    if (!localeData || typeof localeData !== 'object') {
+                        continue;
+                    }
+                    if (field.type === 'array' || field.type === 'blocks') {
+                        if (!Array.isArray(localeData)) {
+                            continue;
+                        }
+                        let hasNull = false;
+                        for(let i = 0; i < localeData.length; i++){
+                            const data = localeData[i];
+                            let fields = null;
+                            if (field.type === 'array') {
+                                fields = field.flattenedFields;
+                            } else {
+                                let maybeBlock = undefined;
+                                if (field.blockReferences) {
+                                    const maybeBlockReference = field.blockReferences.find((each)=>{
+                                        const slug = typeof each === 'string' ? each : each.slug;
+                                        return slug === data.blockType;
+                                    });
+                                    if (maybeBlockReference) {
+                                        if (typeof maybeBlockReference === 'object') {
+                                            maybeBlock = maybeBlockReference;
+                                        } else {
+                                            maybeBlock = config.blocks?.find((each)=>each.slug === maybeBlockReference);
+                                        }
+                                    }
+                                }
+                                if (!maybeBlock) {
+                                    maybeBlock = field.blocks.find((each)=>each.slug === data.blockType);
+                                }
+                                if (maybeBlock) {
+                                    fields = maybeBlock.flattenedFields;
+                                } else {
+                                    localeData[i] = null;
+                                    hasNull = true;
+                                }
+                            }
+                            if (!fields) {
+                                continue;
+                            }
+                            stripFields({
+                                config,
+                                data,
+                                fields,
+                                parentIsLocalized: parentIsLocalized || field.localized,
+                                reservedKeys
+                            });
+                        }
+                        if (hasNull) {
+                            fieldData[localeKey] = localeData.filter(Boolean);
+                        }
+                        continue;
+                    } else {
+                        stripFields({
+                            config,
+                            data: localeData,
+                            fields: field.flattenedFields,
+                            parentIsLocalized: parentIsLocalized || field.localized,
+                            reservedKeys
+                        });
+                    }
+                }
+                continue;
+            }
+            if (field.type === 'array' || field.type === 'blocks') {
+                if (!Array.isArray(fieldData)) {
+                    continue;
+                }
+                let hasNull = false;
+                for(let i = 0; i < fieldData.length; i++){
+                    const data = fieldData[i];
+                    let fields = null;
+                    if (field.type === 'array') {
+                        fields = field.flattenedFields;
+                    } else {
+                        let maybeBlock = undefined;
+                        if (field.blockReferences) {
+                            const maybeBlockReference = field.blockReferences.find((each)=>{
+                                const slug = typeof each === 'string' ? each : each.slug;
+                                return slug === data.blockType;
+                            });
+                            if (maybeBlockReference) {
+                                if (typeof maybeBlockReference === 'object') {
+                                    maybeBlock = maybeBlockReference;
+                                } else {
+                                    maybeBlock = config.blocks?.find((each)=>each.slug === maybeBlockReference);
+                                }
+                            }
+                        }
+                        if (!maybeBlock) {
+                            maybeBlock = field.blocks.find((each)=>each.slug === data.blockType);
+                        }
+                        if (maybeBlock) {
+                            fields = maybeBlock.flattenedFields;
+                        } else {
+                            fieldData[i] = null;
+                            hasNull = true;
+                        }
+                    }
+                    if (!fields) {
+                        continue;
+                    }
+                    stripFields({
+                        config,
+                        data,
+                        fields,
+                        parentIsLocalized: parentIsLocalized || field.localized,
+                        reservedKeys
+                    });
+                }
+                if (hasNull) {
+                    data[field.name] = fieldData.filter(Boolean);
+                }
+                continue;
+            } else {
+                stripFields({
+                    config,
+                    data: fieldData,
+                    fields: field.flattenedFields,
+                    parentIsLocalized: parentIsLocalized || field.localized,
+                    reservedKeys
+                });
+            }
+        }
+    }
+};
+
+//# sourceMappingURL=stripFields.js.map

package/dist/db-content-api/utilities/data/stripFields.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../src/db-content-api/utilities/data/stripFields.ts"],"sourcesContent":["import type { FlattenedBlock, FlattenedField, SanitizedConfig } from 'payload'\n\nimport { fieldShouldBeLocalized } from 'payload/shared'\n\n/**\n * Strips fields from data that are not defined in the schema or are invalid.\n *\n * This function was copied from the MongoDB adapter's implementation:\n * @see packages/db-mongodb/src/utilities/transform.ts (stripFields function)\n *\n * @description\n * This utility performs deep sanitization of document data by:\n * 1. **Removing undefined fields**: Strips any field not present in the collection's schema\n *    (e.g., sensitive fields like `password`, `apiKey`, or any extra fields not in config)\n * 2. **Removing invalid locales**: Deletes locale keys that don't exist in `config.localization.localeCodes`\n *    (e.g., if data contains `{ \"es-MX\": \"...\" }` but only `\"en\"` is configured)\n * 3. **Removing invalid blocks**: Filters out blocks with unknown `blockType` values\n *    (prevents data corruption from blocks that don't exist in the schema)\n * 4. **Recursive sanitization**: Processes nested structures (arrays, groups, blocks, localized fields)\n *    to ensure deep data integrity\n *\n * @remarks\n * Unlike MongoDB's adapter which uses Mongoose schemas with `strict: true` (rejecting extra fields\n * on write), Content API uses flexible JSONB storage that accepts any fields. Therefore, this\n * function is called on **both read and write operations** to ensure data consistency.\n *\n * The MongoDB adapter also supports an `allowAdditionalKeys` option that allows reading/writing\n * fields not in the schema. For now, Content API does not support this feature - we always\n * sanitize data. If users request this functionality in the future, we can consider adding it.\n *\n * @todo\n * 1. Consider moving this utility to `payload/shared` so both MongoDB and Content API adapters\n *    can use the same implementation, reducing code duplication and maintenance burden.\n *\n * 2. Performance optimization: This function iterates through all fields recursively.\n *    The `dataToContentAPI` and `dataFromContentAPI` functions in\n *    `packages/figma/src/db-content-api/utilities/data.ts` also iterate through fields\n *    to transform richText (object ↔ JSON string), custom IDs (number ↔ string), and dates.\n *    Consider combining both traversals into a single abstraction to avoid iterating twice.\n *\n * 3. Feature parity: MongoDB adapter has `allowAdditionalKeys` option. We currently always\n *    strip additional keys, but could add this as a configurable option if users need it.\n */\nexport const stripFields = ({\n  config,\n  data,\n  fields,\n  parentIsLocalized = false,\n  reservedKeys = [],\n}: {\n  config: SanitizedConfig\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  data: any\n  fields: FlattenedField[]\n  parentIsLocalized?: boolean\n  reservedKeys?: string[]\n}) => {\n  for (const k in data) {\n    if (!fields.some((field) => field.name === k) && !reservedKeys.includes(k)) {\n      delete data[k]\n    }\n  }\n\n  for (const field of fields) {\n    reservedKeys = []\n    const fieldData = data[field.name]\n    if (!fieldData || typeof fieldData !== 'object') {\n      continue\n    }\n\n    const shouldLocalizeField = fieldShouldBeLocalized({ field, parentIsLocalized })\n\n    if (field.type === 'blocks') {\n      reservedKeys.push('blockType')\n    }\n\n    if ('flattenedFields' in field || 'blocks' in field) {\n      if (shouldLocalizeField && config.localization) {\n        for (const localeKey in fieldData) {\n          if (!config.localization.localeCodes.some((code) => code === localeKey)) {\n            delete fieldData[localeKey]\n            continue\n          }\n\n          const localeData = fieldData[localeKey]\n\n          if (!localeData || typeof localeData !== 'object') {\n            continue\n          }\n\n          if (field.type === 'array' || field.type === 'blocks') {\n            if (!Array.isArray(localeData)) {\n              continue\n            }\n\n            let hasNull = false\n            for (let i = 0; i < localeData.length; i++) {\n              const data = localeData[i]\n              let fields: FlattenedField[] | null = null\n\n              if (field.type === 'array') {\n                fields = field.flattenedFields\n              } else {\n                let maybeBlock: FlattenedBlock | undefined = undefined\n\n                if (field.blockReferences) {\n                  const maybeBlockReference = field.blockReferences.find((each) => {\n                    const slug = typeof each === 'string' ? each : each.slug\n                    return slug === data.blockType\n                  })\n\n                  if (maybeBlockReference) {\n                    if (typeof maybeBlockReference === 'object') {\n                      maybeBlock = maybeBlockReference\n                    } else {\n                      maybeBlock = config.blocks?.find((each) => each.slug === maybeBlockReference)\n                    }\n                  }\n                }\n\n                if (!maybeBlock) {\n                  maybeBlock = field.blocks.find((each) => each.slug === data.blockType)\n                }\n\n                if (maybeBlock) {\n                  fields = maybeBlock.flattenedFields\n                } else {\n                  localeData[i] = null\n                  hasNull = true\n                }\n              }\n\n              if (!fields) {\n                continue\n              }\n\n              stripFields({\n                config,\n                data,\n                fields,\n                parentIsLocalized: parentIsLocalized || field.localized,\n                reservedKeys,\n              })\n            }\n\n            if (hasNull) {\n              fieldData[localeKey] = localeData.filter(Boolean)\n            }\n\n            continue\n          } else {\n            stripFields({\n              config,\n              data: localeData,\n              fields: field.flattenedFields,\n              parentIsLocalized: parentIsLocalized || field.localized,\n              reservedKeys,\n            })\n          }\n        }\n        continue\n      }\n\n      if (field.type === 'array' || field.type === 'blocks') {\n        if (!Array.isArray(fieldData)) {\n          continue\n        }\n\n        let hasNull = false\n\n        for (let i = 0; i < fieldData.length; i++) {\n          const data = fieldData[i]\n          let fields: FlattenedField[] | null = null\n\n          if (field.type === 'array') {\n            fields = field.flattenedFields\n          } else {\n            let maybeBlock: FlattenedBlock | undefined = undefined\n\n            if (field.blockReferences) {\n              const maybeBlockReference = field.blockReferences.find((each) => {\n                const slug = typeof each === 'string' ? each : each.slug\n                return slug === data.blockType\n              })\n\n              if (maybeBlockReference) {\n                if (typeof maybeBlockReference === 'object') {\n                  maybeBlock = maybeBlockReference\n                } else {\n                  maybeBlock = config.blocks?.find((each) => each.slug === maybeBlockReference)\n                }\n              }\n            }\n\n            if (!maybeBlock) {\n              maybeBlock = field.blocks.find((each) => each.slug === data.blockType)\n            }\n\n            if (maybeBlock) {\n              fields = maybeBlock.flattenedFields\n            } else {\n              fieldData[i] = null\n              hasNull = true\n            }\n          }\n\n          if (!fields) {\n            continue\n          }\n\n          stripFields({\n            config,\n            data,\n            fields,\n            parentIsLocalized: parentIsLocalized || field.localized,\n            reservedKeys,\n          })\n        }\n\n        if (hasNull) {\n          data[field.name] = fieldData.filter(Boolean)\n        }\n\n        continue\n      } else {\n        stripFields({\n          config,\n          data: fieldData,\n          fields: field.flattenedFields,\n          parentIsLocalized: parentIsLocalized || field.localized,\n          reservedKeys,\n        })\n      }\n    }\n  }\n}\n"],"names":["fieldShouldBeLocalized","stripFields","config","data","fields","parentIsLocalized","reservedKeys","k","some","field","name","includes","fieldData","shouldLocalizeField","type","push","localization","localeKey","localeCodes","code","localeData","Array","isArray","hasNull","i","length","flattenedFields","maybeBlock","undefined","blockReferences","maybeBlockReference","find","each","slug","blockType","blocks","localized","filter","Boolean"],"mappings":"AAEA,SAASA,sBAAsB,QAAQ,iBAAgB;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCC,GACD,OAAO,MAAMC,cAAc,CAAC,EAC1BC,MAAM,EACNC,IAAI,EACJC,MAAM,EACNC,oBAAoB,KAAK,EACzBC,eAAe,EAAE,EAQlB;IACC,IAAK,MAAMC,KAAKJ,KAAM;QACpB,IAAI,CAACC,OAAOI,IAAI,CAAC,CAACC,QAAUA,MAAMC,IAAI,KAAKH,MAAM,CAACD,aAAaK,QAAQ,CAACJ,IAAI;YAC1E,OAAOJ,IAAI,CAACI,EAAE;QAChB;IACF;IAEA,KAAK,MAAME,SAASL,OAAQ;QAC1BE,eAAe,EAAE;QACjB,MAAMM,YAAYT,IAAI,CAACM,MAAMC,IAAI,CAAC;QAClC,IAAI,CAACE,aAAa,OAAOA,cAAc,UAAU;YAC/C;QACF;QAEA,MAAMC,sBAAsBb,uBAAuB;YAAES;YAAOJ;QAAkB;QAE9E,IAAII,MAAMK,IAAI,KAAK,UAAU;YAC3BR,aAAaS,IAAI,CAAC;QACpB;QAEA,IAAI,qBAAqBN,SAAS,YAAYA,OAAO;YACnD,IAAII,uBAAuBX,OAAOc,YAAY,EAAE;gBAC9C,IAAK,MAAMC,aAAaL,UAAW;oBACjC,IAAI,CAACV,OAAOc,YAAY,CAACE,WAAW,CAACV,IAAI,CAAC,CAACW,OAASA,SAASF,YAAY;wBACvE,OAAOL,SAAS,CAACK,UAAU;wBAC3B;oBACF;oBAEA,MAAMG,aAAaR,SAAS,CAACK,UAAU;oBAEvC,IAAI,CAACG,cAAc,OAAOA,eAAe,UAAU;wBACjD;oBACF;oBAEA,IAAIX,MAAMK,IAAI,KAAK,WAAWL,MAAMK,IAAI,KAAK,UAAU;wBACrD,IAAI,CAACO,MAAMC,OAAO,CAACF,aAAa;4BAC9B;wBACF;wBAEA,IAAIG,UAAU;wBACd,IAAK,IAAIC,IAAI,GAAGA,IAAIJ,WAAWK,MAAM,EAAED,IAAK;4BAC1C,MAAMrB,OAAOiB,UAAU,CAACI,EAAE;4BAC1B,IAAIpB,SAAkC;4BAEtC,IAAIK,MAAMK,IAAI,KAAK,SAAS;gCAC1BV,SAASK,MAAMiB,eAAe;4BAChC,OAAO;gCACL,IAAIC,aAAyCC;gCAE7C,IAAInB,MAAMoB,eAAe,EAAE;oCACzB,MAAMC,sBAAsBrB,MAAMoB,eAAe,CAACE,IAAI,CAAC,CAACC;wCACtD,MAAMC,OAAO,OAAOD,SAAS,WAAWA,OAAOA,KAAKC,IAAI;wCACxD,OAAOA,SAAS9B,KAAK+B,SAAS;oCAChC;oCAEA,IAAIJ,qBAAqB;wCACvB,IAAI,OAAOA,wBAAwB,UAAU;4CAC3CH,aAAaG;wCACf,OAAO;4CACLH,aAAazB,OAAOiC,MAAM,EAAEJ,KAAK,CAACC,OAASA,KAAKC,IAAI,KAAKH;wCAC3D;oCACF;gCACF;gCAEA,IAAI,CAACH,YAAY;oCACfA,aAAalB,MAAM0B,MAAM,CAACJ,IAAI,CAAC,CAACC,OAASA,KAAKC,IAAI,KAAK9B,KAAK+B,SAAS;gCACvE;gCAEA,IAAIP,YAAY;oCACdvB,SAASuB,WAAWD,eAAe;gCACrC,OAAO;oCACLN,UAAU,CAACI,EAAE,GAAG;oCAChBD,UAAU;gCACZ;4BACF;4BAEA,IAAI,CAACnB,QAAQ;gCACX;4BACF;4BAEAH,YAAY;gCACVC;gCACAC;gCACAC;gCACAC,mBAAmBA,qBAAqBI,MAAM2B,SAAS;gCACvD9B;4BACF;wBACF;wBAEA,IAAIiB,SAAS;4BACXX,SAAS,CAACK,UAAU,GAAGG,WAAWiB,MAAM,CAACC;wBAC3C;wBAEA;oBACF,OAAO;wBACLrC,YAAY;4BACVC;4BACAC,MAAMiB;4BACNhB,QAAQK,MAAMiB,eAAe;4BAC7BrB,mBAAmBA,qBAAqBI,MAAM2B,SAAS;4BACvD9B;wBACF;oBACF;gBACF;gBACA;YACF;YAEA,IAAIG,MAAMK,IAAI,KAAK,WAAWL,MAAMK,IAAI,KAAK,UAAU;gBACrD,IAAI,CAACO,MAAMC,OAAO,CAACV,YAAY;oBAC7B;gBACF;gBAEA,IAAIW,UAAU;gBAEd,IAAK,IAAIC,IAAI,GAAGA,IAAIZ,UAAUa,MAAM,EAAED,IAAK;oBACzC,MAAMrB,OAAOS,SAAS,CAACY,EAAE;oBACzB,IAAIpB,SAAkC;oBAEtC,IAAIK,MAAMK,IAAI,KAAK,SAAS;wBAC1BV,SAASK,MAAMiB,eAAe;oBAChC,OAAO;wBACL,IAAIC,aAAyCC;wBAE7C,IAAInB,MAAMoB,eAAe,EAAE;4BACzB,MAAMC,sBAAsBrB,MAAMoB,eAAe,CAACE,IAAI,CAAC,CAACC;gCACtD,MAAMC,OAAO,OAAOD,SAAS,WAAWA,OAAOA,KAAKC,IAAI;gCACxD,OAAOA,SAAS9B,KAAK+B,SAAS;4BAChC;4BAEA,IAAIJ,qBAAqB;gCACvB,IAAI,OAAOA,wBAAwB,UAAU;oCAC3CH,aAAaG;gCACf,OAAO;oCACLH,aAAazB,OAAOiC,MAAM,EAAEJ,KAAK,CAACC,OAASA,KAAKC,IAAI,KAAKH;gCAC3D;4BACF;wBACF;wBAEA,IAAI,CAACH,YAAY;4BACfA,aAAalB,MAAM0B,MAAM,CAACJ,IAAI,CAAC,CAACC,OAASA,KAAKC,IAAI,KAAK9B,KAAK+B,SAAS;wBACvE;wBAEA,IAAIP,YAAY;4BACdvB,SAASuB,WAAWD,eAAe;wBACrC,OAAO;4BACLd,SAAS,CAACY,EAAE,GAAG;4BACfD,UAAU;wBACZ;oBACF;oBAEA,IAAI,CAACnB,QAAQ;wBACX;oBACF;oBAEAH,YAAY;wBACVC;wBACAC;wBACAC;wBACAC,mBAAmBA,qBAAqBI,MAAM2B,SAAS;wBACvD9B;oBACF;gBACF;gBAEA,IAAIiB,SAAS;oBACXpB,IAAI,CAACM,MAAMC,IAAI,CAAC,GAAGE,UAAUyB,MAAM,CAACC;gBACtC;gBAEA;YACF,OAAO;gBACLrC,YAAY;oBACVC;oBACAC,MAAMS;oBACNR,QAAQK,MAAMiB,eAAe;oBAC7BrB,mBAAmBA,qBAAqBI,MAAM2B,SAAS;oBACvD9B;gBACF;YACF;QACF;IACF;AACF,EAAC"}

package/dist/db-content-api/utilities/joins.d.ts

@@ -0,0 +1,55 @@
+import type { JoinQuery, Payload, SanitizedCollectionConfig } from 'payload';
+import type { components } from '../generated/content-api-types.js';
+type ContentAPIJoin = components['schemas']['JoinClause'][number];
+/**
+ * Convert Payload's JoinQuery to Content API's join format.
+ *
+ * ## Content API Join Limitations
+ *
+ * The following Payload join features are NOT YET supported by Content API:
+ *
+ * 1. **hasMany relationships** - Content API's join uses `data#>'{path}'#>>'{}'` to extract
+ *    a single ID. HasMany relationships store arrays `["id1", "id2"]` which can't match.
+ *
+ * 2. **Array field relationships** - `on: 'array.category'` expects iteration over array
+ *    elements, but Content API treats the path as a single JSONB extraction.
+ *
+ * 3. **Polymorphic relationships** - Stored as `{ relationTo, value }` objects, but
+ *    Content API expects a simple ID string.
+ *
+ * 4. **Localized relationship fields** - Locale-aware joins not implemented.
+ *
+ * Note: "Where querying through joins" (e.g., `where: { 'relatedPosts.title': { equals: 'x' } }`)
+ * is a separate Payload feature that filters documents based on joined data. This is NOT
+ * a join feature but a where clause feature, and would need separate Content API support.
+ *
+ * Payload's JoinQuery format (at runtime):
+ * {
+ *   'group.relatedPosts': {    // joinPath - where results go in the document
+ *     sort: '-title',          // Payload sort format
+ *     limit: 10,
+ *     page: 2,                 // page-based pagination
+ *     where: { ... },          // Payload where format
+ *     count: true
+ *   }
+ * }
+ *
+ * Content API's join format:
+ * [{
+ *   collectionId: 'posts',     // collection to join FROM
+ *   on: 'group.category',      // field in joined collection pointing to this doc
+ *   path: 'group.relatedPosts', // where to put results
+ *   count: false,
+ *   where: { ... },            // Content API where format
+ *   sort: [{ path, direction }], // Content API sort format
+ *   limit: 10,
+ *   offset: 10                 // offset-based pagination
+ * }]
+ *
+ * The mapping requires the collection config to resolve:
+ * - Which collection each join field refers to
+ * - What the 'on' field is for each join
+ */
+export declare function convertPayloadJoinsToContentAPI(payload: Payload, collectionConfig: SanitizedCollectionConfig, joins: false | JoinQuery | undefined): ContentAPIJoin[] | undefined;
+export {};
+//# sourceMappingURL=joins.d.ts.map

package/dist/db-content-api/utilities/joins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"joins.d.ts","sourceRoot":"","sources":["../../../src/db-content-api/utilities/joins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAE5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAA;AAMnE,KAAK,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,gBAAgB,EAAE,yBAAyB,EAC3C,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,GACnC,cAAc,EAAE,GAAG,SAAS,CAkF9B"}

package/dist/db-content-api/utilities/joins.js

@@ -0,0 +1,130 @@
+import { convertPayloadSortToContentAPI } from '../temp-utilities/sorting.js';
+import { convertPayloadWhereToContentAPI } from './where.js';
+/**
+ * Convert Payload's JoinQuery to Content API's join format.
+ *
+ * ## Content API Join Limitations
+ *
+ * The following Payload join features are NOT YET supported by Content API:
+ *
+ * 1. **hasMany relationships** - Content API's join uses `data#>'{path}'#>>'{}'` to extract
+ *    a single ID. HasMany relationships store arrays `["id1", "id2"]` which can't match.
+ *
+ * 2. **Array field relationships** - `on: 'array.category'` expects iteration over array
+ *    elements, but Content API treats the path as a single JSONB extraction.
+ *
+ * 3. **Polymorphic relationships** - Stored as `{ relationTo, value }` objects, but
+ *    Content API expects a simple ID string.
+ *
+ * 4. **Localized relationship fields** - Locale-aware joins not implemented.
+ *
+ * Note: "Where querying through joins" (e.g., `where: { 'relatedPosts.title': { equals: 'x' } }`)
+ * is a separate Payload feature that filters documents based on joined data. This is NOT
+ * a join feature but a where clause feature, and would need separate Content API support.
+ *
+ * Payload's JoinQuery format (at runtime):
+ * {
+ *   'group.relatedPosts': {    // joinPath - where results go in the document
+ *     sort: '-title',          // Payload sort format
+ *     limit: 10,
+ *     page: 2,                 // page-based pagination
+ *     where: { ... },          // Payload where format
+ *     count: true
+ *   }
+ * }
+ *
+ * Content API's join format:
+ * [{
+ *   collectionId: 'posts',     // collection to join FROM
+ *   on: 'group.category',      // field in joined collection pointing to this doc
+ *   path: 'group.relatedPosts', // where to put results
+ *   count: false,
+ *   where: { ... },            // Content API where format
+ *   sort: [{ path, direction }], // Content API sort format
+ *   limit: 10,
+ *   offset: 10                 // offset-based pagination
+ * }]
+ *
+ * The mapping requires the collection config to resolve:
+ * - Which collection each join field refers to
+ * - What the 'on' field is for each join
+ */ export function convertPayloadJoinsToContentAPI(payload, collectionConfig, joins) {
+    // joins === false means explicitly disable all joins
+    // joins === undefined means use defaults (no custom query params)
+    if (joins === false || !joins) {
+        return undefined;
+    }
+    const result = [];
+    // Iterate through all join paths in the query
+    for (const [joinPath, joinQueryValue] of Object.entries(joins)){
+        // joinQuery === false means skip this specific join
+        if (joinQueryValue === false) {
+            continue;
+        }
+        // Normalize undefined/empty to empty object
+        const joinQuery = joinQueryValue ?? {};
+        // Find the SanitizedJoin config for this joinPath
+        // SanitizedJoins is indexed by the collection being joined FROM
+        let foundJoin;
+        // Search through all collections in the joins config
+        for (const [collectionSlug, sanitizedJoins] of Object.entries(collectionConfig.joins)){
+            for (const sanitizedJoin of sanitizedJoins){
+                if (sanitizedJoin.joinPath === joinPath) {
+                    foundJoin = {
+                        collectionSlug,
+                        on: sanitizedJoin.field.on
+                    };
+                    break;
+                }
+            }
+            if (foundJoin) {
+                break;
+            }
+        }
+        // Also check polymorphic joins
+        if (!foundJoin) {
+            for (const sanitizedJoin of collectionConfig.polymorphicJoins){
+                if (sanitizedJoin.joinPath === joinPath) {
+                    // For polymorphic joins, collection is an array - use first one
+                    const collections = sanitizedJoin.field.collection;
+                    foundJoin = {
+                        collectionSlug: Array.isArray(collections) ? collections[0] : collections,
+                        on: sanitizedJoin.field.on
+                    };
+                    break;
+                }
+            }
+        }
+        if (!foundJoin) {
+            payload.logger.warn(`Join path '${joinPath}' not found in collection config for '${collectionConfig.slug}'`);
+            continue;
+        }
+        // Convert pagination: Payload uses page, Content API JoinClause uses offset
+        let offset;
+        if (joinQuery.page && joinQuery.page > 1 && joinQuery.limit) {
+            offset = (joinQuery.page - 1) * joinQuery.limit;
+        }
+        const contentAPIJoin = {
+            collectionId: foundJoin.collectionSlug,
+            count: joinQuery.count ?? false,
+            on: foundJoin.on,
+            path: joinPath,
+            ...joinQuery.limit !== undefined && {
+                limit: joinQuery.limit
+            },
+            ...offset !== undefined && {
+                offset
+            },
+            ...joinQuery.sort && {
+                sort: convertPayloadSortToContentAPI(joinQuery.sort)
+            },
+            ...joinQuery.where && {
+                where: convertPayloadWhereToContentAPI(joinQuery.where)
+            }
+        };
+        result.push(contentAPIJoin);
+    }
+    return result.length > 0 ? result : undefined;
+}
+
+//# sourceMappingURL=joins.js.map