@payloadcms/figma 0.0.1-alpha.9 → 0.1.0-alpha.1

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;

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

@@ -0,0 +1,170 @@
+import { fieldShouldBeLocalized } from 'payload/shared';
+import { resolveFlattenedBlock } from '../resolveBlocks.js';
+/**
+ * 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 {
+                                const maybeBlock = resolveFlattenedBlock({
+                                    blocks: field.blocks,
+                                    blockType: data.blockType,
+                                    configBlocks: config.blocks
+                                });
+                                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 {
+                        const maybeBlock = resolveFlattenedBlock({
+                            blocks: field.blocks,
+                            blockType: data.blockType,
+                            configBlocks: config.blocks
+                        });
+                        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
+                });
+            }
+        }
+    }
+};

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

@@ -0,0 +1,22 @@
+/**
+ * Transform publishedLocale to localizeStatus format
+ *
+ * publishedLocale is a legacy API that is going to be removed in Payload v4 in favor of localizeStatus.
+ * The db-adapter transforms publishedLocale here so Content API doesn't need to know about it.
+ */
+type VersionData = Record<string, unknown>;
+/**
+ * Transforms version data to use localizeStatus format
+ *
+ * If `publishedLocale` is provided and `_status` is a string, transforms to object format.
+ * If `_status` is already an object, leaves it unchanged.
+ *
+ * @example
+ * // Input (old format):
+ * { _status: 'published', text: 'Hello' }, publishedLocale: 'en'
+ *
+ * // Output (new format):
+ * { _status: { en: 'published' }, text: 'Hello' }
+ */
+export declare function transformToLocalizeStatus(versionData: VersionData, publishedLocale?: string): VersionData;
+export {};

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

@@ -0,0 +1,40 @@
+/**
+ * Transform publishedLocale to localizeStatus format
+ *
+ * publishedLocale is a legacy API that is going to be removed in Payload v4 in favor of localizeStatus.
+ * The db-adapter transforms publishedLocale here so Content API doesn't need to know about it.
+ */ /**
+ * Transforms version data to use localizeStatus format
+ *
+ * If `publishedLocale` is provided and `_status` is a string, transforms to object format.
+ * If `_status` is already an object, leaves it unchanged.
+ *
+ * @example
+ * // Input (old format):
+ * { _status: 'published', text: 'Hello' }, publishedLocale: 'en'
+ *
+ * // Output (new format):
+ * { _status: { en: 'published' }, text: 'Hello' }
+ */ export function transformToLocalizeStatus(versionData, publishedLocale) {
+    // No publishedLocale provided - no transformation needed
+    if (!publishedLocale) {
+        return versionData;
+    }
+    const status = versionData._status;
+    // If _status is already an object (localizeStatus format), return as-is
+    if (typeof status === 'object' && status !== null) {
+        return versionData;
+    }
+    // Transform: publishedLocale + string status → object status
+    if (typeof status === 'string') {
+        // Only the specified locale gets the status, others remain undefined
+        // (Content API / Payload will handle merging with existing locale statuses)
+        return {
+            ...versionData,
+            _status: {
+                [publishedLocale]: status
+            }
+        };
+    }
+    return versionData;
+}

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

@@ -0,0 +1,6 @@
+import type { Payload } from 'payload';
+export declare function validateRelationshipIds({ collectionSlug, data, payload, }: {
+    collectionSlug: string;
+    data: Record<string, unknown>;
+    payload: Payload;
+}): void;

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

@@ -0,0 +1,107 @@
+import { traverseFields } from 'payload';
+import { valueIsValueWithRelation } from 'payload/shared';
+import { RELATIONSHIP_ATOMIC_OPERATORS, unwrapAtomicOperation } from './atomicOperations.js';
+import { resolveFieldLocalization } from './resolveFieldLocalization.js';
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function collectRelationshipValues({ data, fields }) {
+    const relationships = [];
+    const callback = ({ field: declaredField, parentIsLocalized, ref })=>{
+        if (!('name' in declaredField) || !declaredField.name) {
+            return;
+        }
+        if (declaredField.type !== 'relationship' && declaredField.type !== 'upload') {
+            return;
+        }
+        if (!ref || typeof ref !== 'object') {
+            return;
+        }
+        // Only a field whose locale keys were not absorbed by a localized ancestor
+        // holds a locale map; an absorbed one holds the relationship value directly.
+        const field = resolveFieldLocalization({
+            field: declaredField,
+            isAbsorbed: parentIsLocalized
+        });
+        const rawValue = ref[field.name];
+        if (rawValue == null || rawValue === '') {
+            return;
+        }
+        // For localized fields, the value is a locale map (e.g. { en: "uuid", fr: "uuid" }).
+        // Iterate locale values instead of treating the map as an ID.
+        if ('localized' in field && field.localized) {
+            if (typeof rawValue === 'object' && !Array.isArray(rawValue)) {
+                for (const localeValue of Object.values(rawValue)){
+                    if (localeValue != null && localeValue !== '') {
+                        parseRelationshipValues(localeValue, field.relationTo, relationships);
+                    }
+                }
+            }
+            return;
+        }
+        parseRelationshipValues(rawValue, field.relationTo, relationships);
+    };
+    traverseFields({
+        callback,
+        fields,
+        fillEmpty: false,
+        ref: data
+    });
+    return relationships;
+}
+function parseRelationshipValues(rawValue, relationTo, relationships) {
+    const value = unwrapAtomicOperation(rawValue, RELATIONSHIP_ATOMIC_OPERATORS);
+    if (Array.isArray(relationTo)) {
+        // Polymorphic (single or hasMany): value is { relationTo, value } or array of them
+        const values = Array.isArray(value) ? value : [
+            value
+        ];
+        for (const v of values){
+            if (valueIsValueWithRelation(v) && v.value != null && v.value !== '') {
+                relationships.push({
+                    collection: v.relationTo,
+                    value: v.value
+                });
+            }
+        }
+    } else {
+        // Non-polymorphic (single or hasMany): value is a bare ID or array of IDs
+        const values = Array.isArray(value) ? value : [
+            value
+        ];
+        for (const v of values){
+            if (v != null && v !== '') {
+                relationships.push({
+                    collection: relationTo,
+                    value: v
+                });
+            }
+        }
+    }
+}
+function isValidId(value, customIDType) {
+    if (customIDType === 'number') {
+        const num = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
+        return Number.isFinite(num);
+    }
+    if (customIDType === 'text') {
+        return typeof value === 'string' && value.length > 0;
+    }
+    return typeof value === 'string' && UUID_REGEX.test(value);
+}
+export function validateRelationshipIds({ collectionSlug, data, payload }) {
+    const isGlobal = collectionSlug.startsWith('_global-');
+    const actualSlug = isGlobal ? collectionSlug.substring(8) : collectionSlug;
+    const config = isGlobal ? payload.config.globals?.find((g)=>g.slug === actualSlug) : payload.config.collections.find((c)=>c.slug === actualSlug);
+    if (!config?.fields) {
+        return;
+    }
+    const relationships = collectRelationshipValues({
+        data,
+        fields: config.fields
+    });
+    for (const { collection, value } of relationships){
+        const customIDType = payload.collections?.[collection]?.customIDType;
+        if (!isValidId(value, customIDType)) {
+            throw new Error(`Invalid relationship ID "${String(value)}" for collection "${collection}". Expected ${customIDType === 'number' ? 'a number' : customIDType === 'text' ? 'a non-empty string' : 'a valid UUID'}.`);
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { JoinQuery, Payload } from 'payload';
+import type { components } from '../generated/content-api-types.js';
+type ContentAPIJoin = components['schemas']['JoinClauseV1'][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.
+ *
+ * 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',
+ *     limit: 10,
+ *     page: 2,                 // page-based pagination
+ *     where: { ... },          // Payload where format
+ *     count: true
+ *   }
+ * }
+ *
+ * Content API's v1 join format:
+ * [{
+ *   path: 'group.relatedPosts', // where to put results
+ *   count: false,
+ *   where: { ... },            // Content API where format
+ *   sort: '-title',
+ *   limit: 10,
+ *   page: 2
+ * }]
+ *
+ * v1 resolves the joined collection and key from the document schema, so the
+ * adapter no longer emits collectionId/on. The collection config is still read
+ * to resolve default limit and sort for each join path.
+ */
+export declare function convertPayloadJoinsToContentAPI(payload: Payload, collectionSlug: string, joins: false | JoinQuery | undefined): ContentAPIJoin[] | undefined;
+export {};

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

@@ -0,0 +1,124 @@
+import { addFallbackSort } 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.
+ *
+ * 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',
+ *     limit: 10,
+ *     page: 2,                 // page-based pagination
+ *     where: { ... },          // Payload where format
+ *     count: true
+ *   }
+ * }
+ *
+ * Content API's v1 join format:
+ * [{
+ *   path: 'group.relatedPosts', // where to put results
+ *   count: false,
+ *   where: { ... },            // Content API where format
+ *   sort: '-title',
+ *   limit: 10,
+ *   page: 2
+ * }]
+ *
+ * v1 resolves the joined collection and key from the document schema, so the
+ * adapter no longer emits collectionId/on. The collection config is still read
+ * to resolve default limit and sort for each join path.
+ */ export function convertPayloadJoinsToContentAPI(payload, collectionSlug, joins) {
+    const collectionConfig = payload.config.collections.find((c)=>c.slug === collectionSlug);
+    if (!collectionConfig) {
+        return undefined;
+    }
+    // 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,
+                        defaultLimit: sanitizedJoin.field.defaultLimit,
+                        defaultSort: sanitizedJoin.field.defaultSort
+                    };
+                    break;
+                }
+            }
+            if (foundJoin) {
+                break;
+            }
+        }
+        // Also check polymorphic joins
+        if (!foundJoin) {
+            for (const sanitizedJoin of collectionConfig.polymorphicJoins){
+                if (sanitizedJoin.joinPath === joinPath) {
+                    foundJoin = {
+                        collectionSlug: sanitizedJoin.field.collection,
+                        defaultSort: sanitizedJoin.field.defaultSort
+                    };
+                    break;
+                }
+            }
+        }
+        if (!foundJoin) {
+            payload.logger.warn(`Join path '${joinPath}' not found in collection config for '${collectionConfig.slug}'`);
+            continue;
+        }
+        // Fall back to the default limit if not specified in the query
+        const effectiveLimit = joinQuery.limit ?? foundJoin.defaultLimit;
+        // Add fallback sort for the joined collection
+        const sortWithFallback = addFallbackSort(joinQuery.sort, payload, foundJoin.collectionSlug, foundJoin.defaultSort);
+        const contentAPIJoin = {
+            count: joinQuery.count ?? false,
+            path: joinPath,
+            ...effectiveLimit !== undefined && {
+                limit: effectiveLimit
+            },
+            ...joinQuery.page && {
+                page: joinQuery.page
+            },
+            ...sortWithFallback && {
+                sort: sortWithFallback
+            },
+            ...joinQuery.where && {
+                where: convertPayloadWhereToContentAPI(joinQuery.where)
+            }
+        };
+        result.push(contentAPIJoin);
+    }
+    return result.length > 0 ? result : undefined;
+}

package/dist/db-content-api/utilities/locale/index.d.ts

@@ -0,0 +1,9 @@
+import type { Payload } from 'payload';
+/**
+ * Determines what locale to send to Content API based on request locale value
+ * and config's defaultLocale.
+ *
+ * If no locale is provided, falls back to the default locale from config.
+ * Returns undefined for 'all' and '*' (special Payload values for returning all locales).
+ */
+export declare function addFallbackLocale(locale: null | string | undefined, payload: Payload): string | undefined;

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

@@ -0,0 +1,19 @@
+/**
+ * Determines what locale to send to Content API based on request locale value
+ * and config's defaultLocale.
+ *
+ * If no locale is provided, falls back to the default locale from config.
+ * Returns undefined for 'all' and '*' (special Payload values for returning all locales).
+ */ export function addFallbackLocale(locale, payload) {
+    const defaultLocale = payload.config.localization ? payload.config.localization.defaultLocale : undefined;
+    if (locale) {
+        // 'all' and '*' are special Payload values meaning "return all locales" - don't send to Content API
+        if (locale === 'all' || locale === '*') {
+            return undefined;
+        }
+        return locale;
+    } else if (defaultLocale) {
+        return defaultLocale;
+    }
+    return undefined;
+}

package/dist/db-content-api/utilities/meta/normalizeLocaleInWhere.d.ts

@@ -0,0 +1,9 @@
+import type { Payload, Where } from 'payload';
+/**
+ * Normalizes a Where clause by inserting locale keys into paths that traverse
+ * localized array/blocks fields without an explicit locale.
+ *
+ * Only runs when a locale is provided and the collection has localized array/blocks fields.
+ * Returns the original where clause if no transformation is needed.
+ */
+export declare function normalizeLocaleInWhere(where: undefined | Where, payload: Payload, collectionSlug: string, locale: string | undefined): undefined | Where;