@byline/core 4.6.2 → 4.8.0

package/dist/@types/db-types.d.ts

@@ -1,5 +1,6 @@
 import type { RequestContext } from '@byline/auth';
 import type { CollectionDefinition } from '@byline/core';
+import type { DbErrorClassification } from '../lib/errors.js';
 import type { QueryPredicate } from './query-predicate.js';
 /**
  * Read mode for document queries.
@@ -245,6 +246,16 @@ export interface IDbAdapter {
     backfillSourceLocales?: () => Promise<{
         rowsUpdated: number;
     }>;
+    /**
+     * Classify a raw driver error into an adapter-agnostic, code-based shape so
+     * core can map database failures to domain errors without knowing driver
+     * anatomy. The error-side analogue of the storage `normalizeRow` seam.
+     *
+     * Optional: when absent, core treats every error as `DB_UNKNOWN` and rethrows
+     * it unchanged — the current behaviour for adapters that do not implement it.
+     * Canonical adapters (db-postgres, db-mysql) implement it.
+     */
+    classifyError?(err: unknown): DbErrorClassification;
 }
 /**
  * The realm of the actor that performed an audited change. `'admin'` for

package/dist/@types/store-types.d.ts

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import type { UnifiedFieldValue } from '../storage/storage-row-types.js';
 export interface BaseStore {
     field_path: string;
     field_name: string;
@@ -89,45 +90,8 @@ export declare function isRelationStore(fieldValue: FlattenedStore): fieldValue
 export declare function isJsonStore(fieldValue: FlattenedStore): fieldValue is JsonStore;
 export declare function isNumericStore(fieldValue: FlattenedStore): fieldValue is NumericStore;
 export declare function isDateTimeStore(fieldValue: FlattenedStore): fieldValue is DateTimeStore;
-export interface UnionRowValue {
-    id: string;
-    document_version_id: string;
-    collection_id: string;
-    field_type: string;
-    field_path: string;
-    field_name: string;
-    locale: string;
-    parent_path: string | null;
-    text_value: string | null;
-    boolean_value: boolean | null;
-    json_value: any | null;
-    date_type: string | null;
-    value_date: Date | null;
-    value_time: string | null;
-    value_timestamp_tz: Date | null;
-    file_id: string | null;
-    filename: string | null;
-    original_filename: string | null;
-    mime_type: string | null;
-    file_size: number | null;
-    storage_provider: string | null;
-    storage_path: string | null;
-    storage_url: string | null;
-    file_hash: string | null;
-    image_width: number | null;
-    image_height: number | null;
-    image_format: string | null;
-    processing_status: string | null;
-    thumbnail_generated: boolean | null;
-    variants: FileStoreVariant[] | null;
-    target_document_id: string | null;
-    target_collection_id: string | null;
-    relationship_type: string | null;
-    cascade_delete: boolean | null;
-    json_schema: string | null;
-    object_keys: string[] | null;
-    number_type: string | null;
-    value_integer: number | null;
-    value_decimal: string | null;
-    value_float: number | null;
-}
+/**
+ * @deprecated Use {@link UnifiedFieldValue} from '@byline/core' — same shape;
+ * this alias remains for source compatibility.
+ */
+export type UnionRowValue = UnifiedFieldValue;

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, type DbErrorClassification, type DbErrorCode, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { type BylineLogger, getLogger } from './lib/logger.js';
 export { AsyncRegistry, type RegisteredServices, Registry } from './lib/registry.js';

package/dist/index.js

@@ -23,7 +23,7 @@ export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
 export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
-export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
+export { BylineError, DbErrorCodes, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';
 export { AsyncRegistry, Registry } from './lib/registry.js';

package/dist/lib/errors.d.ts

@@ -127,3 +127,29 @@ export declare const ERR_AUDIT_UNSUPPORTED: (opts: BylineErrorOptions, errorCons
  * reconcile, while transports can distinguish it from a rolled-back mutation.
  */
 export declare const ERR_TREE_HOOK_COMMITTED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * Code-based classification of a raw database driver error, produced by
+ * `IDbAdapter.classifyError`. The error-side analogue of the storage
+ * `normalizeRow` seam: the adapter canonicalises driver anatomy into these
+ * codes so `@byline/core` can map DB failures to domain errors (e.g.
+ * `ERR_PATH_CONFLICT`) without knowing any driver's error shape.
+ *
+ * Distinct from `ErrorCodes` above: those are thrown `BylineError` codes;
+ * these are returned classification values. Extend with new codes (e.g. a
+ * future `STALE_RECORD` for optimistic-concurrency failures) as consumers
+ * need them.
+ */
+export declare const DbErrorCodes: {
+    readonly UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION';
+    readonly UNKNOWN: 'DB_UNKNOWN';
+};
+export type DbErrorCode = (typeof DbErrorCodes)[keyof typeof DbErrorCodes];
+export interface DbErrorClassification {
+    code: DbErrorCode;
+    /**
+     * For `DB_UNIQUE_VIOLATION`: the violated constraint / index name when the
+     * driver exposes it (Postgres carries it structurally; MySQL parses it from
+     * the error message). Absent when the driver surfaces no name.
+     */
+    constraint?: string;
+}

package/dist/lib/errors.js

@@ -164,3 +164,22 @@ export const ERR_AUDIT_UNSUPPORTED = createErrorType(ErrorCodes.AUDIT_UNSUPPORTE
  * reconcile, while transports can distinguish it from a rolled-back mutation.
  */
 export const ERR_TREE_HOOK_COMMITTED = createErrorType(ErrorCodes.TREE_HOOK_COMMITTED, 'warn');
+// ---------------------------------------------------------------------------
+// Database error classification (adapter seam)
+// ---------------------------------------------------------------------------
+/**
+ * Code-based classification of a raw database driver error, produced by
+ * `IDbAdapter.classifyError`. The error-side analogue of the storage
+ * `normalizeRow` seam: the adapter canonicalises driver anatomy into these
+ * codes so `@byline/core` can map DB failures to domain errors (e.g.
+ * `ERR_PATH_CONFLICT`) without knowing any driver's error shape.
+ *
+ * Distinct from `ErrorCodes` above: those are thrown `BylineError` codes;
+ * these are returned classification values. Extend with new codes (e.g. a
+ * future `STALE_RECORD` for optimistic-concurrency failures) as consumers
+ * need them.
+ */
+export const DbErrorCodes = {
+    UNIQUE_VIOLATION: 'DB_UNIQUE_VIOLATION',
+    UNKNOWN: 'DB_UNKNOWN',
+};

package/dist/services/document-lifecycle/create.js

@@ -86,7 +86,7 @@ export async function createDocument(ctx, params) {
             orderKey,
             createdBy: actorId(ctx),
         })
-            .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
+            .catch((err) => rethrowPathConflict(db, err, resolvedPath, defaultLocale));
         const documentId = extractDocumentId(result.document);
         const documentVersionId = extractVersionId(result.document);
         // `tree: true` collections place every document in the tree by default:

package/dist/services/document-lifecycle/duplicate.js

@@ -172,7 +172,7 @@ export async function duplicateDocument(ctx, params) {
                 orderKey,
                 createdBy: actorId(ctx),
             })
-                .catch((err) => rethrowPathConflict(err, finalPath, defaultLocale));
+                .catch((err) => rethrowPathConflict(db, err, finalPath, defaultLocale));
         }
         catch (err) {
             if (!isPathConflictError(err)) {
@@ -197,7 +197,7 @@ export async function duplicateDocument(ctx, params) {
                 orderKey,
                 createdBy: actorId(ctx),
             })
-                .catch((retryErr) => rethrowPathConflict(retryErr, finalPath, defaultLocale));
+                .catch((retryErr) => rethrowPathConflict(db, retryErr, finalPath, defaultLocale));
         }
         const newDocumentId = extractDocumentId(result.document);
         const newDocumentVersionId = extractVersionId(result.document);

package/dist/services/document-lifecycle/internals.d.ts

@@ -11,7 +11,7 @@
  * the barrel (`index.ts`), so the package's public surface is unchanged
  * by the per-operation split.
  */
-import { type CollectionDefinition, type CollectionHookSlot } from '../../@types/index.js';
+import { type CollectionDefinition, type CollectionHookSlot, type IDbAdapter } from '../../@types/index.js';
 import type { BylineLogger } from '../../lib/logger.js';
 import type { SlugifierFn } from '../../utils/slugify.js';
 import type { DocumentLifecycleContext } from './context.js';
@@ -64,20 +64,18 @@ export declare function extractVersionId(document: any): string;
 /** Extract the logical document id from the document object returned by `createDocumentVersion`. */
 export declare function extractDocumentId(document: any): string;
 /**
- * Detect a Postgres unique-constraint violation on
+ * Detect a unique-constraint violation on
  * `byline_document_paths(collection_id, locale, path)` and translate it
  * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
  *
- * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
- * the constraint name on the error object (`constraint`); matching by
- * name keeps this targeted to the path constraint and avoids spuriously
- * rebranding unrelated unique violations as path conflicts.
- *
- * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
- * original attached as `cause`, so we walk a short cause chain to find
- * the carried `code` / `constraint`.
+ * Driver anatomy (SQLSTATE codes, `cause`-chain walking, constraint-name
+ * carriage) is delegated to `db.classifyError` — the adapter seam that
+ * canonicalises a raw driver error into a `DbErrorClassification`. This
+ * function only knows the classification codes and the path constraint's
+ * name substring; it stays targeted to the path constraint so unrelated
+ * unique violations aren't spuriously rebranded as path conflicts.
  */
-export declare function rethrowPathConflict(err: unknown, path: string, locale: string): never;
+export declare function rethrowPathConflict(db: IDbAdapter, err: unknown, path: string, locale: string): never;
 /**
  * Detect whether an error is the `ERR_PATH_CONFLICT` raised by
  * `rethrowPathConflict`. Used by `duplicateDocument`'s retry logic to

package/dist/services/document-lifecycle/internals.js

@@ -13,7 +13,7 @@
  */
 import { normalizeCollectionHook, } from '../../@types/index.js';
 import { getCollectionDefinition, getServerConfig } from '../../config/config.js';
-import { ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
+import { DbErrorCodes, ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
 import { generateKeyBetween } from '../../lib/fractional-index.js';
 import { createReadContext } from '../populate.js';
 import { embedRichTextFields } from '../richtext-embed.js';
@@ -131,32 +131,25 @@ export function extractDocumentId(document) {
     return document?.document_id ?? '';
 }
 /**
- * Detect a Postgres unique-constraint violation on
+ * Detect a unique-constraint violation on
  * `byline_document_paths(collection_id, locale, path)` and translate it
  * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
  *
- * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
- * the constraint name on the error object (`constraint`); matching by
- * name keeps this targeted to the path constraint and avoids spuriously
- * rebranding unrelated unique violations as path conflicts.
- *
- * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
- * original attached as `cause`, so we walk a short cause chain to find
- * the carried `code` / `constraint`.
+ * Driver anatomy (SQLSTATE codes, `cause`-chain walking, constraint-name
+ * carriage) is delegated to `db.classifyError` — the adapter seam that
+ * canonicalises a raw driver error into a `DbErrorClassification`. This
+ * function only knows the classification codes and the path constraint's
+ * name substring; it stays targeted to the path constraint so unrelated
+ * unique violations aren't spuriously rebranded as path conflicts.
  */
-export function rethrowPathConflict(err, path, locale) {
-    let e = err;
-    // Walk at most a few `cause` hops — DrizzleQueryError → underlying pg error.
-    for (let i = 0; i < 3 && e; i++) {
-        if (e.code === '23505' &&
-            typeof e.constraint === 'string' &&
-            e.constraint.includes('document_paths_collection_locale_path')) {
-            throw ERR_PATH_CONFLICT({
-                message: `path "${path}" is already in use in this collection (locale: ${locale})`,
-                details: { path, locale, constraint: e.constraint },
-            });
-        }
-        e = e.cause;
+export function rethrowPathConflict(db, err, path, locale) {
+    const classification = db.classifyError?.(err);
+    if (classification?.code === DbErrorCodes.UNIQUE_VIOLATION &&
+        classification.constraint?.includes('document_paths_collection_locale_path')) {
+        throw ERR_PATH_CONFLICT({
+            message: `path "${path}" is already in use in this collection (locale: ${locale})`,
+            details: { path, locale, constraint: classification.constraint },
+        });
     }
     throw err;
 }

package/dist/services/document-lifecycle/rethrow-path-conflict.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/services/document-lifecycle/rethrow-path-conflict.test.node.js

@@ -0,0 +1,41 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { ErrorCodes } from '../../lib/errors.js';
+import { rethrowPathConflict } from './internals.js';
+const adapterWith = (c) => ({ classifyError: c === undefined ? undefined : () => c });
+describe('rethrowPathConflict', () => {
+    it('maps a unique violation on the path constraint to ERR_PATH_CONFLICT', () => {
+        const db = adapterWith({
+            code: 'DB_UNIQUE_VIOLATION',
+            constraint: 'byline_document_paths_document_paths_collection_locale_path',
+        });
+        try {
+            rethrowPathConflict(db, new Error('raw'), 'news/hello', 'en');
+            throw new Error('should have thrown');
+        }
+        catch (e) {
+            expect(e.code).toBe(ErrorCodes.PATH_CONFLICT);
+        }
+    });
+    it('rethrows raw when the unique violation is on a different constraint', () => {
+        const raw = new Error('raw');
+        const db = adapterWith({ code: 'DB_UNIQUE_VIOLATION', constraint: 'some_other_unique' });
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+    });
+    it('rethrows raw for DB_UNKNOWN', () => {
+        const raw = new Error('raw');
+        const db = adapterWith({ code: 'DB_UNKNOWN' });
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+    });
+    it('rethrows raw when the adapter has no classifyError', () => {
+        const raw = new Error('raw');
+        const db = adapterWith(undefined);
+        expect(() => rethrowPathConflict(db, raw, 'p', 'en')).toThrow(raw);
+    });
+});

package/dist/services/document-lifecycle/system-fields.js

@@ -104,7 +104,7 @@ export async function updateDocumentSystemFields(ctx, params) {
                     locale: sourceLocale,
                     path: pathForCommand,
                 })
-                    .catch((err) => rethrowPathConflict(err, pathForCommand, sourceLocale));
+                    .catch((err) => rethrowPathConflict(db, err, pathForCommand, sourceLocale));
                 await audit.append({
                     documentId: params.documentId,
                     collectionId,

package/dist/services/document-lifecycle/update.js

@@ -91,7 +91,7 @@ export async function updateDocument(ctx, params) {
             previousVersionId: originalData.document_version_id,
             createdBy: actorId(ctx),
         })
-            .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
+            .catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any
@@ -210,7 +210,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             previousVersionId: originalData.document_version_id,
             createdBy: actorId(ctx),
         })
-            .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
+            .catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         // Self-heal: re-root a genuinely-unplaced doc in a tree collection so any

package/dist/services/document-lifecycle.test.node.js

@@ -7,7 +7,7 @@
  */
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
-import { BylineError, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
+import { BylineError, DbErrorCodes, ERR_PATH_CONFLICT, ErrorCodes } from '../lib/errors.js';
 import { changeDocumentStatus, copyToLocale, createDocument, deleteDocument, duplicateDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentSystemFields, updateDocumentWithPatches, } from './document-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
@@ -50,7 +50,20 @@ function createMockDb() {
     // records the calls so write-point tests can assert the audit rows emitted.
     const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
     const withTransaction = vi.fn(async (fn) => fn());
+    // Fake classifier mirroring db-postgres's real one closely enough for
+    // rethrowPathConflict's consumption of the seam: a pg-shaped 23505 with a
+    // constraint name classifies as a unique violation; anything else is
+    // unknown. Individual tests inject pg-shaped errors on `createDocumentVersion`
+    // (see `translates a Postgres unique-constraint violation...` below).
+    const classifyError = vi.fn((err) => {
+        const e = err;
+        if (e?.code === '23505') {
+            return { code: DbErrorCodes.UNIQUE_VIOLATION, constraint: e.constraint };
+        }
+        return { code: DbErrorCodes.UNKNOWN };
+    });
     const db = {
+        classifyError,
         commands: {
             collections: {
                 create: vi.fn(),

package/dist/storage/index.d.ts

@@ -7,3 +7,8 @@
  */
 export { fingerprintCollection } from './collection-fingerprint.js';
 export { ALL_STORE_TYPES, type FieldStoreKind, type FieldStoreMapping, fieldTypeToStore, fieldTypeToStoreType, type StoreType, } from './field-store-map.js';
+export { flattenFieldSetData } from './storage-flatten.js';
+export { extractFlattenedFieldValue, type RestoreResult, restoreFieldSetData, } from './storage-restore.js';
+export { resolveStoreTypes } from './storage-utils.js';
+export { type ColumnDef, storeColumnManifest, storeTableNames } from './store-manifest.js';
+export type { FlattenedFieldValue, UnifiedFieldValue } from './storage-row-types.js';

package/dist/storage/index.js

@@ -7,3 +7,7 @@
  */
 export { fingerprintCollection } from './collection-fingerprint.js';
 export { ALL_STORE_TYPES, fieldTypeToStore, fieldTypeToStoreType, } from './field-store-map.js';
+export { flattenFieldSetData } from './storage-flatten.js';
+export { extractFlattenedFieldValue, restoreFieldSetData, } from './storage-restore.js';
+export { resolveStoreTypes } from './storage-utils.js';
+export { storeColumnManifest, storeTableNames } from './store-manifest.js';

package/dist/storage/multi-relation.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/storage/multi-relation.test.node.js

@@ -0,0 +1,92 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Storage round-trip for `hasMany` relations — an ordered list of relation
+ * values flattens to indexed `store_relation` rows (`<field>.0`, `<field>.1`,
+ * …) and reconstructs back into the same ordered array. Pure functions; no
+ * Postgres needed.
+ */
+import { describe, expect, it } from 'vitest';
+import { defineCollection } from '../@types/index.js';
+import { flattenFieldSetData } from './storage-flatten.js';
+import { restoreFieldSetData } from './storage-restore.js';
+const Articles = defineCollection({
+    path: 'articles',
+    labels: { singular: 'Article', plural: 'Articles' },
+    fields: [
+        { name: 'title', type: 'text' },
+        {
+            name: 'authors',
+            type: 'relation',
+            targetCollection: 'people',
+            hasMany: true,
+            optional: true,
+        },
+        // A required hasMany to exercise the empty-list fixup.
+        {
+            name: 'tags',
+            type: 'relation',
+            targetCollection: 'tags',
+            hasMany: true,
+        },
+    ],
+});
+const Single = defineCollection({
+    path: 'single',
+    labels: { singular: 'Single', plural: 'Singles' },
+    fields: [{ name: 'lead', type: 'relation', targetCollection: 'people', optional: true }],
+});
+describe('hasMany relation storage round-trip', () => {
+    it('flattens an ordered list to indexed relation rows', () => {
+        const flat = flattenFieldSetData(Articles.fields, {
+            title: 'Hello',
+            authors: [
+                { targetDocumentId: 'a1', targetCollectionId: 'people' },
+                { targetDocumentId: 'a2', targetCollectionId: 'people' },
+                { targetDocumentId: 'a3', targetCollectionId: 'people' },
+            ],
+            tags: [],
+        }, 'all');
+        const relRows = flat.filter((r) => r.field_type === 'relation');
+        expect(relRows.map((r) => r.field_path.join('.'))).toEqual([
+            'authors.0',
+            'authors.1',
+            'authors.2',
+        ]);
+        // Relations are non-localized — every row carries locale 'all'.
+        expect(relRows.every((r) => r.locale === 'all')).toBe(true);
+    });
+    it('reconstructs the ordered array (and preserves order)', () => {
+        const data = {
+            title: 'Hello',
+            authors: [
+                { targetDocumentId: 'a3', targetCollectionId: 'people' },
+                { targetDocumentId: 'a1', targetCollectionId: 'people' },
+                { targetDocumentId: 'a2', targetCollectionId: 'people' },
+            ],
+            tags: [{ targetDocumentId: 't1', targetCollectionId: 'tags' }],
+        };
+        const { data: restored, warnings } = restoreFieldSetData(Articles.fields, flattenFieldSetData(Articles.fields, data, 'all'));
+        expect(warnings).toEqual([]);
+        expect(restored.authors.map((a) => a.targetDocumentId)).toEqual(['a3', 'a1', 'a2']);
+        expect(restored.authors[0]).toMatchObject({
+            targetDocumentId: 'a3',
+            targetCollectionId: 'people',
+        });
+        expect(restored.tags.map((t) => t.targetDocumentId)).toEqual(['t1']);
+    });
+    it('reconstructs a required empty hasMany as []', () => {
+        const { data: restored } = restoreFieldSetData(Articles.fields, flattenFieldSetData(Articles.fields, { title: 'x', authors: [], tags: [] }, 'all'));
+        expect(restored.tags).toEqual([]);
+    });
+    it('leaves single (non-hasMany) relations as scalar values', () => {
+        const { data: restored } = restoreFieldSetData(Single.fields, flattenFieldSetData(Single.fields, { lead: { targetDocumentId: 'p1', targetCollectionId: 'people' } }, 'all'));
+        expect(Array.isArray(restored.lead)).toBe(false);
+        expect(restored.lead).toMatchObject({ targetDocumentId: 'p1', targetCollectionId: 'people' });
+    });
+});

package/dist/storage/storage-flatten-reconstruct.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};