@payloadcms/figma 0.0.1-alpha.8 → 0.1.0-alpha.0

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

@@ -0,0 +1,299 @@
+import { flattenAllFields, traverseFields } from 'payload';
+import { applyDefaults } from './applyDefaults.js';
+import { castFieldValue } from './castFieldValue.js';
+import { removeVirtualFields } from './removeVirtualFields.js';
+import { stripFields } from './stripFields.js';
+import { transformToLocalizeStatus } from './transformPublishedLocale.js';
+const ATOMIC_OPERATION_KEYS = [
+    '$push',
+    '$remove',
+    '$inc'
+];
+function isAtomicOperation(value) {
+    if (value === null || value === undefined || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    return keys.length === 1 && ATOMIC_OPERATION_KEYS.includes(keys[0]);
+}
+/**
+ * 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
+ * - Virtual fields: Remove fields with `virtual: true` (pure virtual fields should never be saved)
+ * - Timestamps: Add updatedAt (always), and createdAt (when createdAt=true)
+ * - publishedLocale: Transform to localizeStatus format (when publishedLocale is provided)
+ *
+ * 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;
+    }
+    // Transform publishedLocale to localizeStatus format before other transformations
+    const dataWithLocalizedStatus = transformToLocalizeStatus(data, options?.publishedLocale);
+    // Deep clone to avoid mutating original data
+    const transformed = JSON.parse(JSON.stringify(dataWithLocalizedStatus));
+    // 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, payload.config.blocks);
+    }
+    // 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];
+        if (isAtomicOperation(value)) {
+            return;
+        }
+        // null → [] for non-localized array-like fields. SQL adapters return null for empty join
+        // tables; Content API stores JSON null which breaks jsonb_array_elements queries.
+        if (value === null && !('localized' in field && field.localized)) {
+            const isHasManyArray = (field.type === 'relationship' || field.type === 'upload') && 'hasMany' in field && field.hasMany;
+            const isArrayLike = field.type === 'array' || field.type === 'blocks';
+            const isHasManySelect = field.type === 'select' && 'hasMany' in field && field.hasMany;
+            if (isHasManyArray || isArrayLike || isHasManySelect) {
+                current[field.name] = [];
+                return;
+            }
+        }
+        if (value !== null && value !== undefined) {
+            value = castFieldValue(field, value);
+            current[field.name] = value;
+            // Normalize non-localized hasMany relationship/upload: single value → array.
+            // Payload may not wrap in array before calling db.update (e.g. children: 'uuid').
+            const isNonLocalizedHasMany = !('localized' in field && field.localized) && (field.type === 'relationship' || field.type === 'upload') && 'hasMany' in field && field.hasMany;
+            if (isNonLocalizedHasMany && !Array.isArray(value)) {
+                current[field.name] = [
+                    value
+                ];
+            }
+            // RichText: object -> JSON string
+            if (field.type === 'richText' && typeof value !== 'string') {
+                current[field.name] = JSON.stringify(value);
+            }
+        }
+    };
+    traverseFields({
+        callback,
+        fields: collectionConfig.fields,
+        fillEmpty: false,
+        ref: transformed
+    });
+    stripFields({
+        config: payload.config,
+        data: transformed,
+        fields: flattenAllFields({
+            cache: true,
+            fields: collectionConfig.fields
+        }),
+        reservedKeys: [
+            'id',
+            'globalType'
+        ]
+    });
+    removeVirtualFields(transformed, collectionConfig.fields);
+    // Convert numeric ID to string for Content API
+    const customIDType = payload.collections?.[collectionSlug]?.customIDType;
+    if (customIDType === 'number') {
+        transformed.id = String(transformed.id);
+    }
+    // Add timestamps (Content API no longer auto-sets these in DB)
+    // Preserve existing timestamps when already present (e.g. version data that carries
+    // the parent document's timestamps), otherwise generate new ones.
+    // Explicit null means "don't change" — strip it so the API keeps the existing value.
+    const now = new Date().toISOString();
+    if (transformed.updatedAt === null) {
+        delete transformed.updatedAt;
+    } else if (transformed.updatedAt === undefined) {
+        transformed.updatedAt = now;
+    }
+    if (options?.createdAt && !transformed.createdAt) {
+        transformed.createdAt = now;
+    }
+    return transformed;
+}
+/**
+ * Transform data received from Content API (READ operations)
+ *
+ * Conversions applied:
+ * - RichText fields: JSON strings -> Objects
+ * - Virtual fields: Remove fields with `virtual: true` (should not be in DB but Content API backend may add them)
+ *
+ * Note: Date fields come as ISO strings from Content API and stay as strings
+ * (matching MongoDB and other adapters' behavior)
+ */ /**
+ * Extract version content from versionData that may be flat (no nested `version` key).
+ * Some callers spread version content at the top level alongside metadata
+ * (e.g. `{ ...version.version, createdAt }`), so we reconstruct the `version`
+ * object by filtering out known metadata keys.
+ */ export function resolveVersionContent(version, versionMeta) {
+    if (version !== undefined) {
+        return version;
+    }
+    const metaKeys = [
+        'createdAt',
+        'updatedAt',
+        'latest',
+        'parent'
+    ];
+    return Object.fromEntries(Object.entries(versionMeta).filter(([key])=>!metaKeys.includes(key)));
+}
+export function dataFromContentAPI(payload, collectionSlug, data, locale) {
+    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;
+    }
+    const isAllLocales = locale === 'all' || locale === '*';
+    // 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];
+        const isLocalized = 'localized' in field && field.localized;
+        // Group fields must always be an object so Payload can traverse sub-fields
+        // (e.g. join fields inside a group). A null/undefined group crashes afterRead.
+        if (field.type === 'group') {
+            if (value == null || typeof value !== 'object') {
+                current[field.name] = {};
+            }
+            return;
+        }
+        // Localized join fields: wrap in locale map so afterRead can hoist the value.
+        // Content API returns join data directly at the field path (e.g. { docs: [...] }),
+        // but Payload's afterRead expects localized fields as { [locale]: value }.
+        if (field.type === 'join' && isLocalized && value !== undefined && !isAllLocales && locale) {
+            current[field.name] = {
+                [locale]: value
+            };
+            return;
+        }
+        // Content API may omit fields; Payload expects null for optional fields.
+        // In all-locales mode, localized fields use {} so afterRead can safely iterate locale keys.
+        if (value === undefined) {
+            const isRequired = 'required' in field && field.required;
+            const isJoin = field.type === 'join';
+            if (!isRequired && !isJoin) {
+                current[field.name] = isLocalized && isAllLocales ? {} : null;
+            }
+            return;
+        }
+        // null localized field in all-locales mode → {} (empty locale map)
+        if (value === null && isLocalized && isAllLocales) {
+            current[field.name] = {};
+            return;
+        }
+        if (value !== null) {
+            // hasMany relationships: normalize to array (non-localized only).
+            // We store raw JSON so a single value stays as-is; Payload expects arrays.
+            if (field.type === 'relationship' && field.hasMany && !Array.isArray(value) && !('localized' in field && field.localized)) {
+                current[field.name] = [
+                    value
+                ];
+            }
+            // Localized array/blocks: empty per-locale arrays → null in single-locale mode.
+            // Payload's afterRead fallback triggers on null (not []), matching SQL adapter behavior.
+            if (isLocalized && !isAllLocales && (field.type === 'array' || field.type === 'blocks') && typeof value === 'object' && !Array.isArray(value)) {
+                const localeMap = value;
+                for (const localeKey of Object.keys(localeMap)){
+                    const localeValue = localeMap[localeKey];
+                    if (Array.isArray(localeValue) && localeValue.length === 0) {
+                        localeMap[localeKey] = null;
+                    }
+                }
+            }
+            // Localized fields: JSON string → parsed object (locale map).
+            // Simple strings that fail to parse as objects are kept as-is (expected for single-locale).
+            if ('localized' in field && field.localized && typeof value === 'string') {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (typeof parsed === 'object' && parsed !== null) {
+                        current[field.name] = parsed;
+                    }
+                } catch  {
+                // Not valid JSON - keep original value
+                }
+            } else 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,
+        fillEmpty: false,
+        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'
+        ]
+    });
+    // Remove virtual fields - must happen AFTER stripFields
+    removeVirtualFields(transformed, collectionConfig.fields);
+    // 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;
+}

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

@@ -0,0 +1,3 @@
+import type { Field, TabAsField } from 'payload';
+export declare function encodePointForWrite(field: Field | TabAsField, value: unknown): unknown;
+export declare function decodePointFromRead(field: Field | TabAsField, value: unknown): unknown;

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

@@ -0,0 +1,43 @@
+/**
+ * Payload stores a point as GeoJSON; the v1 server uses a bare `[lng, lat]`
+ * tuple. Unwrap on write, re-wrap on read so afterRead can restore the tuple.
+ */ function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCoordinateTuple(value) {
+    return Array.isArray(value) && value.length === 2 && value.every((v)=>typeof v === 'number');
+}
+function pointLeafToWire(value) {
+    if (isPlainObject(value) && isCoordinateTuple(value.coordinates)) {
+        return value.coordinates;
+    }
+    return value;
+}
+function pointLeafFromWire(value) {
+    if (isCoordinateTuple(value)) {
+        return {
+            type: 'Point',
+            coordinates: value
+        };
+    }
+    return value;
+}
+function mapPoint(field, value, mapLeaf) {
+    if (field.type !== 'point' || value === null || value === undefined) {
+        return value;
+    }
+    if ('localized' in field && field.localized && isPlainObject(value)) {
+        const result = {};
+        for (const [locale, localeValue] of Object.entries(value)){
+            result[locale] = mapLeaf(localeValue);
+        }
+        return result;
+    }
+    return mapLeaf(value);
+}
+export function encodePointForWrite(field, value) {
+    return mapPoint(field, value, pointLeafToWire);
+}
+export function decodePointFromRead(field, value) {
+    return mapPoint(field, value, pointLeafFromWire);
+}

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

@@ -0,0 +1,11 @@
+import type { CollectionConfig } from 'payload';
+/**
+ * Removes virtual fields (fields with virtual: true) from data recursively.
+ * Virtual fields should never be persisted in the database.
+ *
+ * @todo It might be a good idea to combine `stripFields` with `stripFields`
+ *  in a new utility that receives a callback with conditions. I didn't do
+ * it now because `stripFields` was copied from db-mongo and I'd like to
+ * find a way to unify everything.
+ */
+export declare function removeVirtualFields(data: Record<string, unknown>, fieldConfigs: CollectionConfig['fields']): void;

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

@@ -0,0 +1,52 @@
+/**
+ * Removes virtual fields (fields with virtual: true) from data recursively.
+ * Virtual fields should never be persisted in the database.
+ *
+ * @todo It might be a good idea to combine `stripFields` with `stripFields`
+ *  in a new utility that receives a callback with conditions. I didn't do
+ * it now because `stripFields` was copied from db-mongo and I'd like to
+ * find a way to unify everything.
+ */ export function removeVirtualFields(data, fieldConfigs) {
+    for (const field of fieldConfigs){
+        // Handle UI fields (row, collapsible, tabs) - they don't have names
+        // but contain other fields that might be virtual
+        if (field.type === 'row' || field.type === 'collapsible') {
+            if ('fields' in field) {
+                removeVirtualFields(data, field.fields);
+            }
+            continue;
+        }
+        if (field.type === 'tabs' && 'tabs' in field) {
+            for (const tab of field.tabs){
+                if ('fields' in tab) {
+                    removeVirtualFields(data, tab.fields);
+                }
+            }
+            continue;
+        }
+        // Skip fields without names
+        if (!('name' in field) || !field.name) {
+            continue;
+        }
+        // Remove field if it has virtual: true
+        if ('virtual' in field && field.virtual === true) {
+            delete data[field.name];
+            continue;
+        }
+        // Recursively handle nested structures (groups, arrays with items, etc.)
+        if ('fields' in field && field.name in data) {
+            const value = data[field.name];
+            if (field.type === 'array' && Array.isArray(value)) {
+                // Process each array item
+                for (const item of value){
+                    if (item && typeof item === 'object') {
+                        removeVirtualFields(item, field.fields);
+                    }
+                }
+            } else if (field.type === 'group' && value && typeof value === 'object') {
+                // Process group
+                removeVirtualFields(value, field.fields);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { Field, Payload, TabAsField } from 'payload';
+export declare function encodeRichTextForWrite(field: Field | TabAsField, value: unknown): unknown;
+export declare function decodeRichTextFromRead(field: Field | TabAsField, value: unknown, payload: Payload, fieldPath: string, collectionSlug: string): unknown;

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

@@ -0,0 +1,56 @@
+/**
+ * The v1 server stores richText as a serialized JSON string, so stringify on
+ * write and parse on read. A localized richText is a per-locale map, serialized
+ * and parsed per entry (not as one blob).
+ */ function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function richTextLeafToWire(value) {
+    if (value === null || value === undefined || typeof value === 'string') {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+export function encodeRichTextForWrite(field, value) {
+    if (field.type !== 'richText' || value === null || value === undefined) {
+        return value;
+    }
+    if ('localized' in field && field.localized && isPlainObject(value)) {
+        const result = {};
+        for (const [locale, localeValue] of Object.entries(value)){
+            result[locale] = richTextLeafToWire(localeValue);
+        }
+        return result;
+    }
+    return richTextLeafToWire(value);
+}
+function richTextLeafFromWire(value, onError) {
+    if (typeof value !== 'string') {
+        return value;
+    }
+    try {
+        return JSON.parse(value);
+    } catch (error) {
+        onError(error);
+        return value;
+    }
+}
+export function decodeRichTextFromRead(field, value, payload, fieldPath, collectionSlug) {
+    if (field.type !== 'richText' || value === null || value === undefined) {
+        return value;
+    }
+    const onError = (error)=>{
+        payload.logger.warn({
+            err: error instanceof Error ? error : new Error(String(error)),
+            msg: `Failed to parse richtext field '${fieldPath}' in collection '${collectionSlug}'`
+        });
+    };
+    if ('localized' in field && field.localized && isPlainObject(value)) {
+        const result = {};
+        for (const [locale, localeValue] of Object.entries(value)){
+            result[locale] = richTextLeafFromWire(localeValue, onError);
+        }
+        return result;
+    }
+    return richTextLeafFromWire(value, onError);
+}

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

@@ -0,0 +1,47 @@
+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;