@prenta/core 0.118.0

package/dist/fields/presets.js

@@ -0,0 +1,350 @@
+// ─── Common single-purpose presets ────────────────────────────────────────
+/** Page/post title field — usually the column shown in admin lists. */
+export function titleField(opts = {}) {
+    return {
+        title: {
+            type: 'text',
+            label: opts.label ?? 'Title',
+            required: opts.required ?? true,
+            maxLength: 200,
+            admin: { placeholder: opts.placeholder ?? 'Enter a clear, descriptive title' },
+        },
+    };
+}
+/** URL slug. Defaults to deriving from `title`. */
+export function slugField(opts = {}) {
+    return {
+        slug: {
+            type: 'slug',
+            label: 'Slug',
+            from: opts.from ?? 'title',
+            required: opts.required ?? true,
+            unique: true,
+            admin: { description: 'URL-friendly identifier. Auto-derived from the title.' },
+        },
+    };
+}
+/**
+ * Explicit URL path for a page. Distinct from `slug`: a `slug` is the
+ * URL-friendly identifier auto-derived from the title, while `path` is the full
+ * route the page renders at (e.g. `/`, `/about`, `/services/seo`), so a site can
+ * model nested or custom routes the slug alone can't express. Optional — the
+ * renderer falls back to `/${slug}` when it's blank.
+ */
+export function pagePathField(opts = {}) {
+    return {
+        path: {
+            type: 'text',
+            label: opts.label ?? 'Path',
+            required: opts.required ?? false,
+            maxLength: 512,
+            admin: {
+                description: 'Full URL path this page renders at (e.g. "/", "/about", "/services/seo"). Falls back to /slug when blank.',
+            },
+        },
+    };
+}
+/** Short excerpt / dek shown in listings and OG cards. */
+export function excerptField(opts = {}) {
+    return {
+        excerpt: {
+            type: 'text',
+            label: opts.label ?? 'Excerpt',
+            maxLength: opts.maxLength ?? 280,
+            admin: {
+                description: 'Short summary shown in listings, search results, and OG cards.',
+            },
+        },
+    };
+}
+/** Long-form rich text content. */
+export function richContentField(opts = {}) {
+    const name = opts.name ?? 'content';
+    return {
+        [name]: {
+            type: 'richText',
+            label: opts.label ?? 'Content',
+            required: opts.required,
+            features: ['bold', 'italic', 'link', 'heading', 'list', 'code', 'image', 'embed'],
+        },
+    };
+}
+/** Featured/hero image. */
+export function featuredImageField(opts = {}) {
+    return {
+        featuredImage: {
+            type: 'media',
+            label: opts.label ?? 'Featured image',
+            required: opts.required,
+            accept: ['image/jpeg', 'image/png', 'image/webp', 'image/avif'],
+            admin: {
+                description: 'Hero image used at the top of the page and in social previews.',
+            },
+        },
+    };
+}
+/**
+ * Editorial category. With `options` it becomes a `select` (structured
+ * vocabulary — the editor renders a dropdown instead of free text); without,
+ * it stays a free-text field for back-compat with existing sites.
+ */
+export function categoryField(opts = {}) {
+    if (opts.options && opts.options.length > 0) {
+        return {
+            category: {
+                type: 'select',
+                label: opts.label ?? 'Category',
+                required: opts.required,
+                options: opts.options.map((o) => typeof o === 'string' ? { label: o, value: slugifyOption(o) } : o),
+            },
+        };
+    }
+    return {
+        category: {
+            type: 'text',
+            label: opts.label ?? 'Category',
+            required: opts.required,
+            maxLength: 80,
+        },
+    };
+}
+function slugifyOption(label) {
+    return label
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** Tags (array of plain strings). */
+export function tagsField(opts = {}) {
+    return {
+        tags: {
+            type: 'array',
+            label: opts.label ?? 'Tags',
+            maxRows: opts.maxRows ?? 12,
+            fields: {
+                tag: { type: 'text', label: 'Tag', required: true, maxLength: 40 },
+            },
+        },
+    };
+}
+/** Published-at datetime. */
+export function publishedDateField() {
+    return {
+        publishedDate: {
+            type: 'date',
+            label: 'Published date',
+            includeTime: true,
+            admin: {
+                description: 'When this content should appear as published. Defaults to first publish time.',
+            },
+        },
+    };
+}
+/** Author byline — text + optional relationship to a `team` collection. */
+export function authorField(opts = {}) {
+    const fields = {
+        authorName: {
+            type: 'text',
+            label: opts.label ?? 'Author name',
+            admin: { description: 'Display name shown on the byline.' },
+        },
+    };
+    if (opts.relationTo) {
+        fields.author = {
+            type: 'relationship',
+            label: 'Author',
+            relationTo: opts.relationTo,
+            admin: {
+                description: `Optional reference to a ${opts.relationTo} record. Overrides Author name when set.`,
+            },
+        };
+    }
+    return fields;
+}
+/** Pull-quote / featured quote, used by case studies and testimonials. */
+export function quoteField(opts = {}) {
+    const name = opts.name ?? 'quote';
+    return {
+        [name]: {
+            type: 'text',
+            label: opts.label ?? 'Quote',
+            maxLength: 600,
+            admin: { description: 'Featured quote rendered as a pull-quote.' },
+        },
+    };
+}
+/** Call-to-action label + URL pair. */
+export function ctaField(opts = {}) {
+    const prefix = opts.name ?? 'cta';
+    return {
+        [`${prefix}Label`]: {
+            type: 'text',
+            label: `${opts.label ?? 'CTA'} label`,
+            maxLength: 80,
+            admin: { description: 'Button text for the primary call to action.' },
+        },
+        [`${prefix}Url`]: {
+            type: 'url',
+            label: `${opts.label ?? 'CTA'} URL`,
+            admin: { description: 'Where the CTA button links to.' },
+        },
+    };
+}
+/** SEO meta fields — meta title, description, OG image, canonical, robots. */
+export function seoFields() {
+    return {
+        metaTitle: {
+            type: 'text',
+            label: 'SEO title',
+            maxLength: 70,
+            admin: {
+                description: 'Overrides the page title in <title> and OG tags. Keep under 60 chars.',
+                position: 'sidebar',
+            },
+        },
+        metaDescription: {
+            type: 'text',
+            label: 'SEO description',
+            maxLength: 200,
+            admin: {
+                description: 'Search engine description. 120–160 characters is ideal.',
+                position: 'sidebar',
+            },
+        },
+        ogImage: {
+            type: 'media',
+            label: 'Social share image',
+            accept: ['image/jpeg', 'image/png', 'image/webp'],
+            admin: {
+                description: 'Custom OG/Twitter image (1200×630 recommended). Falls back to featured image.',
+                position: 'sidebar',
+            },
+        },
+        canonical: {
+            type: 'url',
+            label: 'Canonical URL',
+            admin: {
+                description: 'Override the canonical URL for syndicated content.',
+                position: 'sidebar',
+            },
+        },
+        noIndex: {
+            type: 'boolean',
+            label: 'Hide from search engines',
+            admin: { description: 'Adds noindex to the robots meta tag.', position: 'sidebar' },
+        },
+    };
+}
+/** Address + phone + hours fields for location-style records. */
+export function locationFields() {
+    return {
+        address: {
+            type: 'json',
+            label: 'Address',
+            admin: {
+                description: 'PostalAddress object: { streetAddress, addressLocality, addressRegion, postalCode, addressCountry }.',
+            },
+        },
+        phone: {
+            type: 'text',
+            label: 'Phone',
+            maxLength: 40,
+            admin: { description: 'Customer-facing phone number in E.164 or local format.' },
+        },
+        email: {
+            type: 'email',
+            label: 'Email',
+        },
+        hours: {
+            type: 'json',
+            label: 'Hours of operation',
+            admin: {
+                description: 'OpeningHoursSpecification array: [{ dayOfWeek: "Monday", opens: "09:00", closes: "17:00" }, ...].',
+            },
+        },
+    };
+}
+/** Geo coordinates pair — useful for Schema.org Place / LocalBusiness. */
+export function geoFields() {
+    return {
+        latitude: {
+            type: 'number',
+            label: 'Latitude',
+            min: -90,
+            max: 90,
+            step: 0.0001,
+        },
+        longitude: {
+            type: 'number',
+            label: 'Longitude',
+            min: -180,
+            max: 180,
+            step: 0.0001,
+        },
+    };
+}
+/** Price + currency pair — used by service / product types. */
+export function priceFields(opts = {}) {
+    return {
+        price: {
+            type: 'number',
+            label: 'Price',
+            min: 0,
+            step: 0.01,
+        },
+        currency: {
+            type: 'text',
+            label: 'Currency',
+            maxLength: 3,
+            defaultValue: opts.currency ?? 'USD',
+            admin: { description: 'ISO 4217 currency code (USD, EUR, GBP, ...).' },
+        },
+    };
+}
+/**
+ * Single-reference relation preset. Use when a document points at exactly
+ * one other document — e.g. `post → primaryService`, `caseStudy → client`,
+ * `page → location`. The admin renders this with the {@link RelationshipField}
+ * picker.
+ *
+ * @example
+ *   ...relationField('primaryService', { relationTo: 'services', label: 'Primary service' })
+ */
+export function relationField(name, opts) {
+    return {
+        [name]: {
+            type: 'relationship',
+            label: opts.label ?? name,
+            relationTo: opts.relationTo,
+            ...(opts.required ? { required: true } : {}),
+            admin: {
+                description: opts.description ??
+                    `Reference to a ${Array.isArray(opts.relationTo) ? opts.relationTo.join(' or ') : opts.relationTo} document.`,
+            },
+        },
+    };
+}
+/**
+ * Many-relation preset. Use when a document can point at zero-or-more
+ * peers — e.g. `post.relatedPosts`, `service.relatedCaseStudies`,
+ * `caseStudy.featuredTeamMembers`. Always renders as a multi-select picker.
+ *
+ * @example
+ *   ...relatedDocsField('relatedPosts', { relationTo: 'posts' })
+ */
+export function relatedDocsField(name, opts) {
+    return {
+        [name]: {
+            type: 'relationship',
+            label: opts.label ?? name,
+            relationTo: opts.relationTo,
+            hasMany: true,
+            admin: {
+                description: opts.description ??
+                    `Zero or more ${Array.isArray(opts.relationTo) ? opts.relationTo.join(' / ') : opts.relationTo} references.`,
+            },
+        },
+    };
+}
+//# sourceMappingURL=presets.js.map

package/dist/fields/presets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.js","sourceRoot":"","sources":["../../src/fields/presets.ts"],"names":[],"mappings":"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"}

package/dist/fields/relations.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Runtime support for the `relationship` field type.
+ *
+ * Two responsibilities:
+ *
+ *   1. **Validation** — confirm the IDs a caller writes actually point at
+ *      live (non-deleted) documents in the declared target collection(s).
+ *      Without this an integrator can accidentally store stale or fabricated
+ *      IDs and the bug surfaces only on render.
+ *
+ *   2. **Population (depth=1)** — opt-in expansion of stored IDs into full
+ *      reference summaries (`{ id, title, slug, status, collection }`) so
+ *      frontend consumers don't need to round-trip per relation.
+ *
+ * Both helpers walk the field schema, support `hasMany`, and tolerate the
+ * `relationTo: string | string[]` polymorphism that `RelationshipField`
+ * permits. We deliberately cap the population depth at 1 — recursive
+ * expansion would let a single read pull half the database when authors,
+ * related posts, and case studies all link to one another.
+ */
+import type { FieldDefinition } from '../config/types.js';
+export interface RelationLookup {
+    /**
+     * Fetch documents by id, returning a map keyed by id. Implementations
+     * should filter by `deletedAt: null` and restrict to the requested
+     * collection(s). Missing ids are simply omitted from the returned map.
+     */
+    fetchByIds: (collections: string[], ids: string[]) => Promise<Map<string, RelationSummary>>;
+}
+export interface RelationSummary {
+    id: string;
+    collection: string;
+    title?: string | null;
+    slug?: string | null;
+    status?: string | null;
+    /** Whatever subset of the document data the lookup wants to expose. */
+    data?: Record<string, unknown> | null;
+}
+/**
+ * Walk a field schema and collect every relation reference present in the
+ * document data. Returns `{ collection -> Set<id> }` and an inventory of
+ * which field paths hold which ids — used by both validation and populate.
+ */
+export declare function collectRelationRefs(fields: Record<string, FieldDefinition>, data: Record<string, unknown>): {
+    byCollection: Map<string, Set<string>>;
+    refsByPath: Array<{
+        path: string;
+        field: FieldDefinition;
+        ids: string[];
+    }>;
+};
+/**
+ * Validate that every relation reference in `data` points at a live
+ * document. Throws on the first broken reference with a precise error
+ * (path + missing id + target collection) so admins can fix the input
+ * instead of guessing.
+ */
+export declare function validateRelations(fields: Record<string, FieldDefinition>, data: Record<string, unknown>, lookup: RelationLookup): Promise<void>;
+export interface PopulateOptions {
+    /**
+     * Whitelist of field paths to populate. `['*']` expands all relations.
+     * Otherwise: top-level field names (matches the most common case where
+     * a frontend only wants e.g. `author` populated, not every reference).
+     *
+     * Nested paths (e.g. `relatedPosts.author`) are intentionally not
+     * supported — depth=1 only.
+     */
+    paths?: string[] | '*';
+}
+/**
+ * Replace stored IDs with `{ id, title, slug, status, collection }` summaries
+ * for every relation field in the document. The original IDs remain
+ * accessible via the summary's `id` field, so callers that wrote raw IDs
+ * still see them after a populated read.
+ *
+ * Returns a *new* document object; the input is not mutated.
+ */
+export declare function populateRelations(fields: Record<string, FieldDefinition>, data: Record<string, unknown>, lookup: RelationLookup, options?: PopulateOptions): Promise<Record<string, unknown>>;
+/**
+ * Parse the `?populate=` query param into an options object.
+ *   - `?populate=*`          → expand all relations
+ *   - `?populate=true`       → expand all relations (alias)
+ *   - `?populate=a,b`        → expand only `a` and `b`
+ *   - missing / `false`      → no expansion
+ */
+export declare function parsePopulateParam(raw: string | null | undefined): PopulateOptions | null;
+//# sourceMappingURL=relations.d.ts.map

package/dist/fields/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../src/fields/relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAEzD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;CAC5F;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;CACtC;AAkBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B;IACD,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;IACtC,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,eAAe,CAAC;QAAC,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAA;CAC3E,CAgCA;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAgDD,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAA;CACvB;AAaD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAgElC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAWzF"}

package/dist/fields/relations.js

@@ -0,0 +1,231 @@
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function relationTargets(field) {
+    if (field.type !== 'relationship')
+        return [];
+    return Array.isArray(field.relationTo) ? field.relationTo : [field.relationTo];
+}
+function extractIds(value) {
+    if (value === null || value === undefined || value === '')
+        return [];
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === 'string' && v.length > 0);
+    }
+    if (typeof value === 'string' && value.length > 0)
+        return [value];
+    return [];
+}
+/**
+ * Walk a field schema and collect every relation reference present in the
+ * document data. Returns `{ collection -> Set<id> }` and an inventory of
+ * which field paths hold which ids — used by both validation and populate.
+ */
+export function collectRelationRefs(fields, data) {
+    const byCollection = new Map();
+    const refsByPath = [];
+    function visit(fieldDefs, obj, prefix) {
+        if (!obj || typeof obj !== 'object')
+            return;
+        const objRec = obj;
+        for (const [name, def] of Object.entries(fieldDefs)) {
+            const value = objRec[name];
+            const path = prefix ? `${prefix}.${name}` : name;
+            if (def.type === 'relationship') {
+                const ids = extractIds(value);
+                if (ids.length === 0)
+                    continue;
+                refsByPath.push({ path, field: def, ids });
+                for (const target of relationTargets(def)) {
+                    if (!byCollection.has(target))
+                        byCollection.set(target, new Set());
+                    for (const id of ids)
+                        byCollection.get(target).add(id);
+                }
+            }
+            else if (def.type === 'array' && Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    visit(def.fields, value[i], `${path}[${i}]`);
+                }
+            }
+        }
+    }
+    visit(fields, data, '');
+    return { byCollection, refsByPath };
+}
+/**
+ * Validate that every relation reference in `data` points at a live
+ * document. Throws on the first broken reference with a precise error
+ * (path + missing id + target collection) so admins can fix the input
+ * instead of guessing.
+ */
+export async function validateRelations(fields, data, lookup) {
+    const { byCollection, refsByPath } = collectRelationRefs(fields, data);
+    if (refsByPath.length === 0)
+        return;
+    const found = await batchedFetch(lookup, byCollection);
+    for (const ref of refsByPath) {
+        const targets = relationTargets(ref.field);
+        for (const id of ref.ids) {
+            let resolved = false;
+            for (const target of targets) {
+                const docMap = found.get(target);
+                if (docMap?.has(id)) {
+                    resolved = true;
+                    break;
+                }
+            }
+            if (!resolved) {
+                const target = targets.length === 1 ? targets[0] : targets.join(' | ');
+                throw new Error(`Relation field "${ref.path}" references document "${id}" which does not exist in collection "${target}".`);
+            }
+        }
+    }
+}
+/**
+ * Issue **one** `fetchByIds` call across every target collection and bucket
+ * the result back into a `collection -> id -> summary` map.
+ *
+ * The naive shape — one `await` per collection — costs N database round-trips
+ * when a document carries relations into N collections (an author + media +
+ * related posts trio is three). Each round-trip is ~80 ms over a typical
+ * cross-region Function -> Postgres path, so the cost adds up fast on
+ * cache-miss reads. Batching is safe because `RelationLookup.fetchByIds`
+ * already accepts a multi-collection input (`collection: { in: collections }`
+ * on the Prisma side) and every returned summary carries its source
+ * `collection` field, so we can bucket without ambiguity.
+ *
+ * IDs are deduplicated across collections so we never ship the same id twice
+ * in the `IN (...)` list. Targets are deduplicated for the same reason.
+ */
+async function batchedFetch(lookup, byCollection) {
+    const found = new Map();
+    if (byCollection.size === 0)
+        return found;
+    const collections = [];
+    const ids = new Set();
+    for (const [collection, idSet] of byCollection.entries()) {
+        collections.push(collection);
+        found.set(collection, new Map());
+        for (const id of idSet)
+            ids.add(id);
+    }
+    if (ids.size === 0)
+        return found;
+    const byId = await lookup.fetchByIds(collections, Array.from(ids));
+    for (const [id, summary] of byId) {
+        // Defensive: only bucket into collections we actually asked for. A
+        // lookup that returns an out-of-band collection (custom implementation
+        // bug) shouldn't poison the result map.
+        const bucket = found.get(summary.collection);
+        if (bucket)
+            bucket.set(id, summary);
+    }
+    return found;
+}
+function shouldPopulatePath(path, paths) {
+    // Opt-in: with no paths specified, nothing gets populated. Callers must
+    // explicitly pass '*' to expand everything or list paths by name.
+    if (!paths)
+        return false;
+    if (paths === '*' || (Array.isArray(paths) && paths.includes('*')))
+        return true;
+    if (!Array.isArray(paths))
+        return false;
+    // Top-level only — strip array indexers.
+    const top = path.replace(/\[\d+\].*$/, '').split('.')[0];
+    return paths.includes(top);
+}
+/**
+ * Replace stored IDs with `{ id, title, slug, status, collection }` summaries
+ * for every relation field in the document. The original IDs remain
+ * accessible via the summary's `id` field, so callers that wrote raw IDs
+ * still see them after a populated read.
+ *
+ * Returns a *new* document object; the input is not mutated.
+ */
+export async function populateRelations(fields, data, lookup, options = {}) {
+    const { byCollection, refsByPath } = collectRelationRefs(fields, data);
+    const eligibleRefs = refsByPath.filter((r) => shouldPopulatePath(r.path, options.paths));
+    if (eligibleRefs.length === 0)
+        return data;
+    // Limit the batch to ids we'll actually use.
+    const trimmedByCollection = new Map();
+    for (const ref of eligibleRefs) {
+        for (const target of relationTargets(ref.field)) {
+            const all = byCollection.get(target);
+            if (!all)
+                continue;
+            for (const id of ref.ids) {
+                if (all.has(id)) {
+                    if (!trimmedByCollection.has(target))
+                        trimmedByCollection.set(target, new Set());
+                    trimmedByCollection.get(target).add(id);
+                }
+            }
+        }
+    }
+    const found = await batchedFetch(lookup, trimmedByCollection);
+    // Deep-clone the data so we don't mutate the caller's object.
+    const cloned = JSON.parse(JSON.stringify(data));
+    function lookupSummary(field, id) {
+        for (const target of relationTargets(field)) {
+            const summary = found.get(target)?.get(id);
+            if (summary)
+                return summary;
+        }
+        // Reference not found — return the raw id rather than dropping it, so
+        // the frontend at least sees that a relation was present.
+        return id;
+    }
+    function replace(fieldDefs, obj, prefix) {
+        for (const [name, def] of Object.entries(fieldDefs)) {
+            const value = obj[name];
+            const path = prefix ? `${prefix}.${name}` : name;
+            if (def.type === 'relationship' && shouldPopulatePath(path, options.paths)) {
+                if (def.hasMany || Array.isArray(value)) {
+                    const ids = extractIds(value);
+                    if (ids.length === 0)
+                        continue;
+                    obj[name] = ids.map((id) => lookupSummary(def, id));
+                }
+                else if (typeof value === 'string' && value.length > 0) {
+                    obj[name] = lookupSummary(def, value);
+                }
+            }
+            else if (def.type === 'array' && Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    const item = value[i];
+                    if (item && typeof item === 'object') {
+                        replace(def.fields, item, `${path}[${i}]`);
+                    }
+                }
+            }
+        }
+    }
+    replace(fields, cloned, '');
+    return cloned;
+}
+/**
+ * Parse the `?populate=` query param into an options object.
+ *   - `?populate=*`          → expand all relations
+ *   - `?populate=true`       → expand all relations (alias)
+ *   - `?populate=a,b`        → expand only `a` and `b`
+ *   - missing / `false`      → no expansion
+ */
+export function parsePopulateParam(raw) {
+    if (!raw)
+        return null;
+    if (raw === 'true' || raw === '*')
+        return { paths: '*' };
+    if (raw === 'false' || raw === '0')
+        return null;
+    const parts = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    if (parts.includes('*'))
+        return { paths: '*' };
+    return { paths: parts };
+}
+//# sourceMappingURL=relations.js.map