@revealui/core 0.0.1-pre.4 → 0.2.0

package/dist/plugins/nested-docs.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from '../types/index.js';
+export interface NestedDocsPluginConfig {
+    collections?: string[];
+    parentFieldSlug?: string;
+    breadcrumbsFieldSlug?: string;
+}
+export declare function nestedDocsPlugin(config?: NestedDocsPluginConfig): Plugin;
+//# sourceMappingURL=nested-docs.d.ts.map

package/dist/plugins/nested-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-docs.d.ts","sourceRoot":"","sources":["../../src/plugins/nested-docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,MAAM,WAAW,sBAAsB;IACrC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,sBAA2B,GAAG,MAAM,CA+E5E"}

package/dist/plugins/nested-docs.js

@@ -0,0 +1,67 @@
+export function nestedDocsPlugin(config = {}) {
+    const { collections = [], parentFieldSlug = 'parent', breadcrumbsFieldSlug = 'breadcrumbs', } = config;
+    return (incomingConfig) => {
+        if (incomingConfig.collections) {
+            for (const collection of incomingConfig.collections) {
+                if (collections.includes(collection.slug)) {
+                    // Add parent field
+                    const parentField = {
+                        name: parentFieldSlug,
+                        type: 'relationship',
+                        relationTo: collection.slug,
+                        maxDepth: 1,
+                        admin: {
+                            position: 'sidebar',
+                        },
+                    };
+                    // Add breadcrumbs field
+                    const breadcrumbsField = {
+                        name: breadcrumbsFieldSlug,
+                        type: 'array',
+                        admin: {
+                            readOnly: true,
+                            components: {
+                                // biome-ignore lint/style/useNamingConvention: Payload component key.
+                                RowLabel: () => null,
+                            },
+                        },
+                        fields: [
+                            {
+                                name: 'doc',
+                                type: 'relationship',
+                                relationTo: collection.slug,
+                                maxDepth: 1,
+                            },
+                            {
+                                name: 'url',
+                                type: 'text',
+                            },
+                            {
+                                name: 'label',
+                                type: 'text',
+                            },
+                        ],
+                    };
+                    // Add hooks for breadcrumbs
+                    const beforeChangeHook = ({ data }) => {
+                        // Generate breadcrumbs based on parent
+                        if (data[parentFieldSlug]) {
+                            // This would need to be implemented with actual database queries
+                            data[breadcrumbsFieldSlug] = [];
+                        }
+                        return data;
+                    };
+                    collection.hooks = {
+                        ...collection.hooks,
+                        beforeChange: [
+                            ...(collection.hooks?.beforeChange || []),
+                            beforeChangeHook,
+                        ],
+                    };
+                    collection.fields = [...collection.fields, parentField, breadcrumbsField];
+                }
+            }
+        }
+        return incomingConfig;
+    };
+}

package/dist/plugins/redirects.d.ts

@@ -0,0 +1,17 @@
+import type { Field, Plugin, RevealRequest } from '../types/index.js';
+export interface RedirectsPluginConfig {
+    collections?: string[];
+    overrides?: {
+        fields?: (args: {
+            defaultFields: Field[];
+        }) => Field[];
+        hooks?: {
+            afterChange?: ((args: {
+                doc: Document;
+                req: RevealRequest;
+            }) => Promise<Document> | Document)[];
+        };
+    };
+}
+export declare function redirectsPlugin(config?: RedirectsPluginConfig): Plugin;
+//# sourceMappingURL=redirects.d.ts.map

package/dist/plugins/redirects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirects.d.ts","sourceRoot":"","sources":["../../src/plugins/redirects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEvF,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,aAAa,EAAE,KAAK,EAAE,CAAA;SAAE,KAAK,KAAK,EAAE,CAAA;QACtD,KAAK,CAAC,EAAE;YACN,WAAW,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE;gBACpB,GAAG,EAAE,QAAQ,CAAA;gBACb,GAAG,EAAE,aAAa,CAAA;aACnB,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAA;SACtC,CAAA;KACF,CAAA;CACF;AAED,wBAAgB,eAAe,CAAC,MAAM,GAAE,qBAA0B,GAAG,MAAM,CAsE1E"}

package/dist/plugins/redirects.js

@@ -0,0 +1,62 @@
+export function redirectsPlugin(config = {}) {
+    const { collections = ['pages', 'posts'] } = config;
+    return (incomingConfig) => {
+        // Add redirects collection
+        const redirectsCollection = {
+            slug: 'redirects',
+            admin: {
+                useAsTitle: 'from',
+                defaultColumns: ['from', 'to', 'status'],
+            },
+            fields: [
+                {
+                    name: 'from',
+                    type: 'text',
+                    required: true,
+                    unique: true,
+                    admin: {
+                        description: 'The URL to redirect from',
+                    },
+                },
+                {
+                    name: 'to',
+                    type: 'relationship',
+                    relationTo: collections,
+                    required: true,
+                    maxDepth: 1,
+                    admin: {
+                        description: 'The page or post to redirect to',
+                    },
+                },
+                {
+                    name: 'status',
+                    type: 'select',
+                    required: true,
+                    defaultValue: '301',
+                    options: [
+                        { label: '301 - Permanent', value: '301' },
+                        { label: '302 - Temporary', value: '302' },
+                    ],
+                },
+            ],
+        };
+        // Apply overrides if provided
+        if (config.overrides?.fields) {
+            redirectsCollection.fields = config.overrides.fields({
+                defaultFields: redirectsCollection.fields,
+            });
+        }
+        if (config.overrides?.hooks?.afterChange) {
+            redirectsCollection.hooks = {
+                ...redirectsCollection.hooks,
+                afterChange: config.overrides.hooks.afterChange,
+            };
+        }
+        incomingConfig.collections = [
+            ...(incomingConfig.collections || []),
+            // biome-ignore lint/suspicious/noExplicitAny: invariant generic needs any for heterogeneous array
+            redirectsCollection,
+        ];
+        return incomingConfig;
+    };
+}

package/dist/queries/index.d.ts

@@ -0,0 +1,2 @@
+export { type BuildWhereOptions, buildWhereClause, extractWhereValues, type ParameterStyle, } from './queryBuilder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/queries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/queries/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA"}

package/dist/queries/index.js

@@ -0,0 +1 @@
+export { buildWhereClause, extractWhereValues, } from './queryBuilder.js';

package/dist/queries/queryBuilder.d.ts

@@ -0,0 +1,47 @@
+import type { RevealFindOptions, RevealWhere } from '../types/index.js';
+/**
+ * Query Builder Utilities
+ *
+ * Handles building WHERE clauses from RevealWhere query objects.
+ * Uses PostgreSQL-style $1, $2 parameters by default.
+ */
+export type ParameterStyle = 'postgres' | 'positional';
+/**
+ * Options for building WHERE clauses
+ */
+export interface BuildWhereOptions {
+    /**
+     * Parameter style to use ('postgres' for $1, $2 or 'positional' for ?)
+     * @default 'postgres'
+     */
+    parameterStyle?: ParameterStyle;
+    /**
+     * Whether to include the WHERE keyword in the result
+     * @default false
+     */
+    includeWhereKeyword?: boolean;
+    /**
+     * Whether to quote field names
+     * @default true
+     */
+    quoteFields?: boolean;
+}
+/**
+ * Builds a WHERE clause from a RevealWhere query object.
+ * Supports nested AND/OR conditions and various operators.
+ *
+ * @param where - The WHERE condition object
+ * @param params - Array to push parameter values into (mutated)
+ * @param options - Build options
+ * @returns SQL WHERE clause (without WHERE keyword by default)
+ */
+export declare function buildWhereClause(where: RevealWhere | RevealFindOptions['where'] | undefined, params: unknown[], options?: BuildWhereOptions): string;
+/**
+ * Extracts parameter values from a RevealWhere query object.
+ * Used for building parameter arrays separately from WHERE clauses.
+ *
+ * @param where - The WHERE condition object
+ * @returns Array of parameter values in order
+ */
+export declare function extractWhereValues(where?: RevealWhere): unknown[];
+//# sourceMappingURL=queryBuilder.d.ts.map

package/dist/queries/queryBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryBuilder.d.ts","sourceRoot":"","sources":["../../src/queries/queryBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEvE;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,YAAY,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,SAAS,EAC3D,MAAM,EAAE,OAAO,EAAE,EACjB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAiNR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,EAAE,CAmEjE"}

package/dist/queries/queryBuilder.js

@@ -0,0 +1,252 @@
+/**
+ * Builds a WHERE clause from a RevealWhere query object.
+ * Supports nested AND/OR conditions and various operators.
+ *
+ * @param where - The WHERE condition object
+ * @param params - Array to push parameter values into (mutated)
+ * @param options - Build options
+ * @returns SQL WHERE clause (without WHERE keyword by default)
+ */
+export function buildWhereClause(where, params, options = {}) {
+    if (!where) {
+        return '';
+    }
+    const { parameterStyle = 'postgres', includeWhereKeyword = false, quoteFields = true } = options;
+    const getPlaceholder = () => {
+        if (parameterStyle === 'postgres') {
+            // Calculate placeholder BEFORE pushing to params array.
+            // PostgreSQL uses 1-indexed placeholders ($1, $2, $3...).
+            // If params.length = 0, next param will be at position 1 ($1).
+            // If params.length = 1, next param will be at position 2 ($2).
+            // Therefore: placeholder = params.length + 1
+            return `$${params.length + 1}`;
+        }
+        return '?';
+    };
+    const quoteField = (field) => {
+        return quoteFields ? `"${field}"` : field;
+    };
+    const whereWithGroups = where;
+    const isOperatorObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date);
+    // Handle and/or groups
+    if (Array.isArray(whereWithGroups.and)) {
+        const conditions = whereWithGroups.and
+            .map((w) => buildWhereClause(w, params, { ...options, includeWhereKeyword: false }))
+            .filter((c) => c.length > 0);
+        if (conditions.length === 0) {
+            return '';
+        }
+        const clause = conditions.join(' AND ');
+        return includeWhereKeyword ? `WHERE ${clause}` : clause;
+    }
+    if (Array.isArray(whereWithGroups.or)) {
+        const conditions = whereWithGroups.or
+            .map((w) => {
+            const clause = buildWhereClause(w, params, {
+                ...options,
+                includeWhereKeyword: false,
+            });
+            // Ensure clause doesn't start with "WHERE" (should never happen with includeWhereKeyword: false, but defensive)
+            if (clause.trim().toUpperCase().startsWith('WHERE')) {
+                throw new Error(`buildWhereClause returned clause starting with "WHERE" when includeWhereKeyword is false. This indicates a bug in the query builder. Clause: ${clause}`);
+            }
+            return clause;
+        })
+            .filter((c) => c.length > 0);
+        if (conditions.length === 0) {
+            return '';
+        }
+        const clause = `(${conditions.join(' OR ')})`;
+        return includeWhereKeyword ? `WHERE ${clause}` : clause;
+    }
+    // Handle field conditions
+    const conditions = [];
+    // Valid operators for validation
+    const validOperators = new Set([
+        'equals',
+        'not_equals',
+        'in',
+        'not_in',
+        'contains',
+        'greater_than',
+        'less_than',
+        'like',
+        'exists',
+    ]);
+    for (const [field, condition] of Object.entries(where)) {
+        // Skip special keys
+        if (field === 'and' || field === 'or') {
+            continue;
+        }
+        if (condition === null || condition === undefined) {
+            continue;
+        }
+        const quotedField = quoteField(field);
+        // If condition is a plain value, treat as equals
+        if (!isOperatorObject(condition)) {
+            // Get placeholder BEFORE pushing to ensure correct index
+            const placeholder = getPlaceholder();
+            params.push(condition);
+            conditions.push(`${quotedField} = ${placeholder}`);
+            continue;
+        }
+        // Handle operator objects
+        if (isOperatorObject(condition)) {
+            // Validate operators before processing
+            const operatorKeys = Object.keys(condition).filter((key) => key !== 'and' && key !== 'or');
+            const invalidOperators = operatorKeys.filter((key) => !validOperators.has(key));
+            if (invalidOperators.length > 0) {
+                throw new Error(`Invalid query operators: ${invalidOperators.join(', ')}. Valid operators are: ${Array.from(validOperators).join(', ')}`);
+            }
+            // equals
+            if ('equals' in condition && condition.equals !== undefined) {
+                const placeholder = getPlaceholder();
+                params.push(condition.equals);
+                conditions.push(`${quotedField} = ${placeholder}`);
+            }
+            // not_equals
+            if ('not_equals' in condition && condition.not_equals !== undefined) {
+                const placeholder = getPlaceholder();
+                params.push(condition.not_equals);
+                conditions.push(`${quotedField} != ${placeholder}`);
+            }
+            // in
+            if ('in' in condition && Array.isArray(condition.in)) {
+                if (condition.in.length > 0) {
+                    const placeholders = [];
+                    for (const value of condition.in) {
+                        const placeholder = getPlaceholder();
+                        params.push(value);
+                        placeholders.push(placeholder);
+                    }
+                    conditions.push(`${quotedField} IN (${placeholders.join(', ')})`);
+                }
+                else {
+                    // Empty IN clause should match nothing
+                    conditions.push('1=0'); // Always false
+                }
+            }
+            // not_in
+            if ('not_in' in condition && Array.isArray(condition.not_in)) {
+                if (condition.not_in.length > 0) {
+                    const placeholders = [];
+                    for (const value of condition.not_in) {
+                        const placeholder = getPlaceholder();
+                        params.push(value);
+                        placeholders.push(placeholder);
+                    }
+                    conditions.push(`${quotedField} NOT IN (${placeholders.join(', ')})`);
+                }
+            }
+            // contains (LIKE with wildcards)
+            if ('contains' in condition && typeof condition.contains === 'string') {
+                const placeholder = getPlaceholder();
+                params.push(`%${condition.contains}%`);
+                conditions.push(`${quotedField} LIKE ${placeholder}`);
+            }
+            // greater_than
+            if ('greater_than' in condition && condition.greater_than !== undefined) {
+                const placeholder = getPlaceholder();
+                params.push(condition.greater_than);
+                conditions.push(`${quotedField} > ${placeholder}`);
+            }
+            // less_than
+            if ('less_than' in condition && condition.less_than !== undefined) {
+                const placeholder = getPlaceholder();
+                params.push(condition.less_than);
+                conditions.push(`${quotedField} < ${placeholder}`);
+            }
+            // like
+            if ('like' in condition && typeof condition.like === 'string') {
+                const placeholder = getPlaceholder();
+                params.push(condition.like);
+                conditions.push(`${quotedField} LIKE ${placeholder}`);
+            }
+            // exists (check if field is not null)
+            if ('exists' in condition && typeof condition.exists === 'boolean') {
+                if (condition.exists) {
+                    conditions.push(`${quotedField} IS NOT NULL`);
+                }
+                else {
+                    conditions.push(`${quotedField} IS NULL`);
+                }
+            }
+        }
+    }
+    const clause = conditions.length > 0 ? conditions.join(' AND ') : '';
+    const result = includeWhereKeyword && clause ? `WHERE ${clause}` : clause;
+    // Defensive check: ensure we never return "WHERE" prefix when includeWhereKeyword is false
+    if (!includeWhereKeyword && result.trim().toUpperCase().startsWith('WHERE')) {
+        throw new Error(`buildWhereClause returned clause starting with "WHERE" when includeWhereKeyword is false. This indicates a bug in the query builder. Clause: ${result}`);
+    }
+    return result;
+}
+/**
+ * Extracts parameter values from a RevealWhere query object.
+ * Used for building parameter arrays separately from WHERE clauses.
+ *
+ * @param where - The WHERE condition object
+ * @returns Array of parameter values in order
+ */
+export function extractWhereValues(where) {
+    if (!where)
+        return [];
+    const values = [];
+    for (const [field, operators] of Object.entries(where)) {
+        if (field === 'and' || field === 'or')
+            continue;
+        if (typeof operators === 'object' &&
+            operators !== null &&
+            !Array.isArray(operators) &&
+            !(operators instanceof Date)) {
+            for (const [op, value] of Object.entries(operators)) {
+                switch (op) {
+                    case 'equals':
+                    case 'not_equals':
+                    case 'greater_than':
+                    case 'less_than':
+                        values.push(value);
+                        break;
+                    case 'contains':
+                        if (typeof value === 'string') {
+                            values.push(`%${value}%`);
+                        }
+                        break;
+                    case 'in':
+                        if (Array.isArray(value)) {
+                            values.push(...value);
+                        }
+                        break;
+                    case 'not_in':
+                        if (Array.isArray(value)) {
+                            values.push(...value);
+                        }
+                        break;
+                    case 'like':
+                        if (typeof value === 'string') {
+                            values.push(value);
+                        }
+                        break;
+                    // exists doesn't need a value
+                }
+            }
+        }
+        else if (operators !== null && operators !== undefined) {
+            // Plain value (treated as equals)
+            values.push(operators);
+        }
+    }
+    const whereWithGroups = where;
+    // Handle nested conditions
+    if (Array.isArray(whereWithGroups.and)) {
+        for (const w of whereWithGroups.and) {
+            values.push(...extractWhereValues(w));
+        }
+    }
+    if (Array.isArray(whereWithGroups.or)) {
+        for (const w of whereWithGroups.or) {
+            values.push(...extractWhereValues(w));
+        }
+    }
+    return values;
+}

package/dist/relationships/analyzer.d.ts

@@ -0,0 +1,39 @@
+import type { RevealCollectionConfig, RevealGlobalConfig, RevealUIField } from '../types/index.js';
+import type { RelationshipMetadata } from '../types/query.js';
+/**
+ * Relationship Field Analyzer
+ *
+ * Analyzes a collection config and extracts all relationship fields with their metadata.
+ * This is the foundation for depth-based relationship population.
+ *
+ * Based on RevealUI CMS analysis:
+ * - Simple relationships (single, no hasMany): Direct Foreign Keys
+ * - hasMany relationships: Junction Tables
+ * - Polymorphic relationships (relationTo array): Junction Tables with multiple FK columns
+ */
+/**
+ * Shared type for configs that have fields and slug (collections and globals)
+ */
+type ConfigWithFields = {
+    slug: string;
+    fields: RevealUIField[];
+};
+/**
+ * Analyzes a collection or global configuration and extracts all relationship fields
+ * with their storage metadata for proper query building.
+ *
+ * @param config - The collection or global configuration to analyze
+ * @param collectionSlug - Optional slug override (defaults to config.slug)
+ * @returns Array of relationship metadata for all relationship fields
+ */
+export declare function getRelationshipFields(config: RevealCollectionConfig | RevealGlobalConfig | ConfigWithFields, collectionSlug?: string): RelationshipMetadata[];
+/**
+ * Validates relationship metadata for consistency and correctness.
+ * Used during development to catch configuration errors early.
+ */
+export declare function validateRelationshipMetadata(metadata: RelationshipMetadata[]): {
+    valid: boolean;
+    errors: string[];
+};
+export {};
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/relationships/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/relationships/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAClG,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE7D;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,aAAa,EAAE,CAAA;CACxB,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,GAAG,kBAAkB,GAAG,gBAAgB,EACtE,cAAc,CAAC,EAAE,MAAM,GACtB,oBAAoB,EAAE,CAoDxB;AA6DD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG;IAC9E,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CA+BA"}

package/dist/relationships/analyzer.js

@@ -0,0 +1,127 @@
+/**
+ * Analyzes a collection or global configuration and extracts all relationship fields
+ * with their storage metadata for proper query building.
+ *
+ * @param config - The collection or global configuration to analyze
+ * @param collectionSlug - Optional slug override (defaults to config.slug)
+ * @returns Array of relationship metadata for all relationship fields
+ */
+export function getRelationshipFields(config, collectionSlug) {
+    const toSnakeCase = (string) => string
+        ?.replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/\s+/g, '-')
+        .toLowerCase();
+    const relationships = [];
+    const tableName = toSnakeCase(collectionSlug || config.slug);
+    // Recursively traverse fields to find all relationships
+    function traverseFields(fields, currentPath = '', parentLocalized = false) {
+        for (const field of fields) {
+            const fieldName = field.name || '';
+            const fieldPath = currentPath ? `${currentPath}.${fieldName}` : fieldName;
+            // Determine if field is localized (field-level or inherited from parent)
+            // Note: Collection-level localization is not yet supported in RevealCollectionConfig type
+            const isLocalized = field.localized === true || parentLocalized;
+            // Check if this is a relationship field
+            if (field.type === 'relationship' || field.type === 'upload') {
+                const metadata = createRelationshipMetadata(field, fieldPath || '', tableName, isLocalized);
+                if (metadata) {
+                    relationships.push(metadata);
+                }
+            }
+            // Recursively check nested fields (for arrays, groups, blocks, etc.)
+            if ('fields' in field && Array.isArray(field.fields)) {
+                const nestedFields = field.fields;
+                traverseFields(nestedFields, fieldPath, isLocalized);
+            }
+            // Check blocks
+            if (field.type === 'blocks' && 'blocks' in field && Array.isArray(field.blocks)) {
+                for (const block of field.blocks) {
+                    if ('fields' in block && Array.isArray(block.fields)) {
+                        const blockFields = block.fields;
+                        const blockSlug = typeof block.slug === 'string' ? block.slug : 'block';
+                        traverseFields(blockFields, `${fieldPath}.${blockSlug}`, isLocalized);
+                    }
+                }
+            }
+        }
+    }
+    traverseFields(config.fields);
+    return relationships;
+}
+/**
+ * Creates relationship metadata for a single field.
+ * Determines storage type based on field properties following RevealUI CMS patterns.
+ */
+function createRelationshipMetadata(field, fieldPath, parentTableName, isLocalized = false) {
+    // Skip if not a relationship field
+    if (field.type !== 'relationship' && field.type !== 'upload') {
+        return null;
+    }
+    // Skip if no relationTo (shouldn't happen but safety check)
+    if (!field.relationTo) {
+        return null;
+    }
+    const relationTo = field.relationTo;
+    const hasMany = field.hasMany ?? false;
+    const isPolymorphic = Array.isArray(relationTo);
+    // Determine storage type based on RevealUI CMS analysis
+    let storageType;
+    if (isPolymorphic) {
+        storageType = 'polymorphic';
+    }
+    else if (hasMany) {
+        storageType = 'junction_table';
+    }
+    else {
+        storageType = 'direct_fk';
+    }
+    // Generate table/column names
+    const tableName = storageType === 'direct_fk'
+        ? parentTableName // main table for direct FKs
+        : `${parentTableName}_rels`; // junction table
+    const fkColumnName = storageType === 'direct_fk'
+        ? `${field.name}_id` // e.g., author_id
+        : undefined; // junction tables have multiple FK columns
+    return {
+        fieldName: field.name,
+        path: fieldPath,
+        storageType,
+        relationTo,
+        hasMany,
+        localized: isLocalized,
+        tableName,
+        fkColumnName,
+        maxDepth: 1, // Default depth, will be configurable later
+        depth: 1, // Default depth for queries
+    };
+}
+/**
+ * Validates relationship metadata for consistency and correctness.
+ * Used during development to catch configuration errors early.
+ */
+export function validateRelationshipMetadata(metadata) {
+    const errors = [];
+    for (const rel of metadata) {
+        // Validate storage type logic
+        if (rel.storageType === 'polymorphic' && !Array.isArray(rel.relationTo)) {
+            errors.push(`Polymorphic relationship ${rel.fieldName} must have array relationTo`);
+        }
+        if (rel.storageType === 'direct_fk' && rel.hasMany) {
+            errors.push(`Direct FK relationship ${rel.fieldName} cannot have hasMany=true`);
+        }
+        if (rel.storageType !== 'direct_fk' && rel.fkColumnName) {
+            errors.push(`Non-direct-FK relationship ${rel.fieldName} should not have fkColumnName`);
+        }
+        // Validate table name format
+        if (rel.storageType === 'direct_fk' && rel.tableName?.includes('_rels')) {
+            errors.push(`Direct FK relationship ${rel.fieldName} should not use _rels table`);
+        }
+        if (rel.storageType !== 'direct_fk' && rel.tableName && !rel.tableName.includes('_rels')) {
+            errors.push(`Junction table relationship ${rel.fieldName} should use _rels table`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/dist/relationships/index.d.ts

@@ -0,0 +1,3 @@
+export { getRelationshipFields, validateRelationshipMetadata, } from './analyzer.js';
+export { relationshipPopulationPromise } from './population.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/relationships/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/relationships/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,6BAA6B,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/relationships/index.js

@@ -0,0 +1,2 @@
+export { getRelationshipFields, validateRelationshipMetadata, } from './analyzer.js';
+export { relationshipPopulationPromise } from './population.js';