@byline/db-postgres 1.4.0 → 1.6.1

package/dist/modules/storage/storage-queries.d.ts

@@ -81,6 +81,13 @@ export declare class DocumentQueries implements IDocumentQueries {
      * restoration. Meta rows (from store_meta) are converted to
      * FlattenedFieldValue entries so that restoreFieldSetData can inject
      * _id and _type for blocks and array items inline.
+     *
+     * Returns `{ fields, warnings }`. When `lenient` is false (default), any
+     * non-empty `warnings` are promoted to a thrown `BylineError` — preserving
+     * the original strict behaviour. When `lenient` is true, the caller
+     * receives the partial reconstruction and the warnings list and decides
+     * how to surface them (the admin edit path uses this to render a
+     * "best-effort load" banner against an out-of-date document).
      */
     private reconstructFromUnifiedRows;
     /**
@@ -104,15 +111,22 @@ export declare class DocumentQueries implements IDocumentQueries {
     } | null>;
     /**
      * getDocumentById — gets the current version of a document by its logical document ID.
+     *
+     * When `lenient` is true, schema-mismatch warnings emitted during
+     * reconstruction are surfaced on the returned object as `restoreWarnings`
+     * rather than thrown. This is the admin edit path's "best-effort load"
+     * mode for documents written under a previous collection schema.
      */
-    getDocumentById({ collection_id, document_id, locale, reconstruct, readMode, filters, }: {
+    getDocumentById({ collection_id, document_id, locale, reconstruct, readMode, filters, lenient, }: {
         collection_id: string;
         document_id: string;
         locale?: string;
         reconstruct?: boolean;
         readMode?: ReadMode;
         filters?: DocumentFilter[];
+        lenient?: boolean;
     }): Promise<{
+        restoreWarnings?: string[] | undefined;
         document_version_id: string;
         document_id: string;
         path: string;

package/dist/modules/storage/storage-queries.js

@@ -93,8 +93,15 @@ export class DocumentQueries {
      * restoration. Meta rows (from store_meta) are converted to
      * FlattenedFieldValue entries so that restoreFieldSetData can inject
      * _id and _type for blocks and array items inline.
+     *
+     * Returns `{ fields, warnings }`. When `lenient` is false (default), any
+     * non-empty `warnings` are promoted to a thrown `BylineError` — preserving
+     * the original strict behaviour. When `lenient` is true, the caller
+     * receives the partial reconstruction and the warnings list and decides
+     * how to surface them (the admin edit path uses this to render a
+     * "best-effort load" banner against an out-of-date document).
      */
-    reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows) {
+    reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient = false) {
         const flattenedData = unifiedFieldValues.map((row) => extractFlattenedFieldValue(row));
         if (metaRows) {
             for (const meta of metaRows) {
@@ -108,7 +115,14 @@ export class DocumentQueries {
             }
         }
         const resolveLocale = locale !== 'all' ? locale : undefined;
-        return restoreFieldSetData(definition.fields, flattenedData, resolveLocale);
+        const { data, warnings } = restoreFieldSetData(definition.fields, flattenedData, resolveLocale);
+        if (!lenient && warnings.length > 0) {
+            throw ERR_DATABASE({
+                message: `document reconstruction failed with ${warnings.length} warnings`,
+                details: { warnings },
+            }).log(getLogger());
+        }
+        return { fields: data, warnings };
     }
     /**
      * getCurrentVersionMetadata — narrow metadata fetch for the current version.
@@ -145,8 +159,13 @@ export class DocumentQueries {
     }
     /**
      * getDocumentById — gets the current version of a document by its logical document ID.
+     *
+     * When `lenient` is true, schema-mismatch warnings emitted during
+     * reconstruction are surfaced on the returned object as `restoreWarnings`
+     * rather than thrown. This is the admin edit path's "best-effort load"
+     * mode for documents written under a previous collection schema.
      */
-    async getDocumentById({ collection_id, document_id, locale = 'en', reconstruct = true, readMode, filters, }) {
+    async getDocumentById({ collection_id, document_id, locale = 'en', reconstruct = true, readMode, filters, lenient = false, }) {
         const view = this.pickCurrentView(readMode);
         // 1. Get current version (or current published version, per readMode)
         const baseConditions = [
@@ -184,7 +203,7 @@ export class DocumentQueries {
             })
                 .from(metaStore)
                 .where(eq(metaStore.document_version_id, document.id));
-            const fields = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
+            const { fields, warnings } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows, lenient);
             return {
                 document_version_id: document.id,
                 document_id: document.document_id,
@@ -193,6 +212,7 @@ export class DocumentQueries {
                 created_at: document.created_at,
                 updated_at: document.updated_at,
                 fields,
+                ...(lenient && warnings.length > 0 ? { restoreWarnings: warnings } : {}),
             };
         }
         // Non-reconstructed: return raw flattened values
@@ -242,7 +262,7 @@ export class DocumentQueries {
             })
                 .from(metaStore)
                 .where(eq(metaStore.document_version_id, document.id));
-            const fields = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
+            const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
             return {
                 document_version_id: document.id,
                 document_id: document.document_id,
@@ -289,7 +309,7 @@ export class DocumentQueries {
         })
             .from(metaStore)
             .where(eq(metaStore.document_version_id, document.id));
-        const enrichedDocument = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
+        const { fields } = this.reconstructFromUnifiedRows(unifiedFieldValues, definition, locale, metaRows);
         const documentWithFields = {
             document_version_id: document.id,
             document_id: document.document_id,
@@ -297,7 +317,7 @@ export class DocumentQueries {
             status: document.status,
             created_at: document.created_at,
             updated_at: document.updated_at,
-            fields: enrichedDocument,
+            fields,
         };
         return documentWithFields;
     }
@@ -533,7 +553,7 @@ export class DocumentQueries {
         for (const doc of documents) {
             const versionFieldValues = fieldValuesByVersion.get(doc.id) || [];
             const docMetaRows = (metaByVersion.get(doc.id) ?? []);
-            const fields = this.reconstructFromUnifiedRows(versionFieldValues, definition, locale, docMetaRows);
+            const { fields } = this.reconstructFromUnifiedRows(versionFieldValues, definition, locale, docMetaRows);
             // When specific fields were requested, trim the reconstructed object
             // to only those fields. Store-level filtering avoids querying unused
             // tables, but fields sharing a store (e.g. price + views in numeric)

package/dist/modules/storage/storage-restore.d.ts

@@ -7,12 +7,22 @@
  */
 import type { FieldSet } from '@byline/core';
 import type { FlattenedFieldValue, UnifiedFieldValue } from './@types.js';
+export interface RestoreResult {
+    data: any;
+    warnings: string[];
+}
 /**
  * Main entrypoint for restoring a document's field data from flattened form
  * back into the original nested structure.
  *
+ * Always returns `{ data, warnings }`. Warnings carry per-row reasons (e.g.
+ * "Invalid block index 'undefined'") that are typically the result of a
+ * collection schema change leaving orphan rows behind. Callers decide what
+ * to do with them — strict reads reject any non-empty `warnings`, lenient
+ * reads (the admin edit path) surface them to the UI.
+ *
  * @param fields - The field definitions for the collection.
  * @param flattenedData - The flattened field data to restore.
  */
-export declare const restoreFieldSetData: (fields: FieldSet, flattenedData: FlattenedFieldValue[], resolveLocale?: string) => any;
+export declare const restoreFieldSetData: (fields: FieldSet, flattenedData: FlattenedFieldValue[], resolveLocale?: string) => RestoreResult;
 export declare const extractFlattenedFieldValue: (unifiedValue: UnifiedFieldValue) => FlattenedFieldValue;

package/dist/modules/storage/storage-restore.js

@@ -6,14 +6,16 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { ERR_DATABASE, getLogger, RESERVED_FIELD_NAMES } from '@byline/core';
-// ------------------------------------------------------------------------------
-// Restoration logic: take flattened field data and restore it to the original
-// nested structure.
-// ------------------------------------------------------------------------------
 /**
  * Main entrypoint for restoring a document's field data from flattened form
  * back into the original nested structure.
  *
+ * Always returns `{ data, warnings }`. Warnings carry per-row reasons (e.g.
+ * "Invalid block index 'undefined'") that are typically the result of a
+ * collection schema change leaving orphan rows behind. Callers decide what
+ * to do with them — strict reads reject any non-empty `warnings`, lenient
+ * reads (the admin edit path) surface them to the UI.
+ *
  * @param fields - The field definitions for the collection.
  * @param flattenedData - The flattened field data to restore.
  */
@@ -46,13 +48,7 @@ export const restoreFieldSetData = (fields, flattenedData, resolveLocale) => {
             result[field.name] = result[field.name] || {};
         }
     }
-    if (warnings.length > 0) {
-        throw ERR_DATABASE({
-            message: `document reconstruction failed with ${warnings.length} warnings`,
-            details: { warnings },
-        }).log(getLogger());
-    }
-    return result;
+    return { data: result, warnings };
 };
 const restoreFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
     if (field.type === 'group') {

package/dist/modules/storage/tests/storage-flatten-reconstruct.test.js

@@ -229,15 +229,16 @@ describe('01 Document Flattening and Reconstruction', () => {
         const flattened = flattenFieldSetData(DocsCollectionConfig.fields, sampleDocument, 'all');
         assert(flattened, 'Flattened document should not be null or undefined');
         assert(flattened.length > 0, 'Flattened document should contain field values');
-        const restored = restoreFieldSetData(DocsCollectionConfig.fields, flattened);
+        const { data: restored, warnings } = restoreFieldSetData(DocsCollectionConfig.fields, flattened);
         assert(restored, 'Restored document should not be null or undefined');
+        assert.deepStrictEqual(warnings, [], 'Round-trip restore should produce no warnings');
         const restoredJson = JSON.stringify(restored, null, 2);
         const expectedJson = JSON.stringify(expectedRestored, null, 2);
         assert.deepStrictEqual(JSON.parse(restoredJson), JSON.parse(expectedJson), 'Restored document should match the expected flat block shape');
     });
     it('should resolve localized fields when a specific locale is requested', () => {
         const flattened = flattenFieldSetData(DocsCollectionConfig.fields, sampleDocument, 'all');
-        const restored = restoreFieldSetData(DocsCollectionConfig.fields, flattened, 'en');
+        const { data: restored } = restoreFieldSetData(DocsCollectionConfig.fields, flattened, 'en');
         assert.strictEqual(restored.title, 'My First Document');
         assert.strictEqual(restored.summary, 'This is a sample document for testing purposes.');
     });
@@ -308,19 +309,19 @@ describe('reserved field-name tolerance on restore', () => {
             field_type: 'text',
             value: 'Hello',
         };
-        const restored = restoreFieldSetData(DocsCollectionConfig.fields, [orphanPathRow, titleRow], 'en');
+        const { data: restored, warnings } = restoreFieldSetData(DocsCollectionConfig.fields, [orphanPathRow, titleRow], 'en');
         assert.strictEqual(restored.path, undefined, 'reserved-name row must not land on the reconstructed document');
         assert.strictEqual(restored.title, 'Hello', 'non-reserved rows must still be restored');
+        assert.deepStrictEqual(warnings, [], 'reserved-name orphan must not surface as a restore warning');
     });
-    it('does not throw when the only row present is a reserved-name orphan', () => {
+    it('does not raise warnings when the only row present is a reserved-name orphan', () => {
         const orphanPathRow = {
             locale: 'all',
             field_path: ['path'],
             field_type: 'text',
             value: 'whatever',
         };
-        assert.doesNotThrow(() => {
-            restoreFieldSetData(DocsCollectionConfig.fields, [orphanPathRow]);
-        }, 'a reserved-name orphan must not be treated as an unknown field');
+        const { warnings } = restoreFieldSetData(DocsCollectionConfig.fields, [orphanPathRow]);
+        assert.deepStrictEqual(warnings, [], 'a reserved-name orphan must not be treated as an unknown field');
     });
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.4.0",
+  "version": "1.6.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -52,9 +52,9 @@
     "pg": "^8.20.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.4.0",
-    "@byline/core": "1.5.0",
-    "@byline/admin": "1.4.0"
+    "@byline/auth": "1.6.1",
+    "@byline/core": "1.6.1",
+    "@byline/admin": "1.6.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",