@byline/core 4.6.1 → 4.7.0

package/dist/storage/storage-restore.js

@@ -0,0 +1,370 @@
+/**
+ * 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 { RESERVED_FIELD_NAMES } from '../config/validate-collections.js';
+import { ERR_DATABASE } from '../lib/errors.js';
+import { getLogger } from '../lib/logger.js';
+/**
+ * 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 const restoreFieldSetData = (fields, flattenedData, resolveLocale) => {
+    const result = {};
+    const warnings = [];
+    for (const item of flattenedData) {
+        // biome-ignore lint/style/noNonNullAssertion: TODO: put in a proper check here?
+        const fieldName = item.field_path[0];
+        // Reserved system attributes (e.g. `path`) live on `documentVersions`,
+        // not in the schema field tree. Silently skip orphan rows that may
+        // remain in store_* tables from earlier schemas where these names
+        // were declared as user fields.
+        if (RESERVED_FIELD_NAMES.has(fieldName)) {
+            continue;
+        }
+        const field = fields.find((f) => f.name === fieldName);
+        if (!field) {
+        }
+        else {
+            result[fieldName] = restoreFieldData(field, result[fieldName], item, 1, warnings, resolveLocale);
+        }
+    }
+    // Array/blocks/group/hasMany-relation fixup — a required list-shaped field
+    // with no stored rows reconstructs as an empty array rather than absent.
+    for (const field of fields) {
+        if ((field.type === 'array' ||
+            field.type === 'blocks' ||
+            (field.type === 'relation' && field.hasMany)) &&
+            !field.optional) {
+            result[field.name] = result[field.name] || [];
+        }
+        else if (field.type === 'group' && !field.optional) {
+            result[field.name] = result[field.name] || {};
+        }
+    }
+    return { data: result, warnings };
+};
+const restoreFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+    if (field.type === 'group') {
+        return restoreGroupFieldData(field, target, data, pathIndex, warnings, resolveLocale);
+    }
+    else if (field.type === 'array') {
+        return restoreArrayFieldData(field, target, data, pathIndex, warnings, resolveLocale);
+    }
+    else if (field.type === 'blocks') {
+        return restoreBlocksFieldData(field, target, data, pathIndex, warnings, resolveLocale);
+    }
+    else if (field.type === 'relation' && field.hasMany) {
+        return restoreMultiRelationFieldData(target, data, pathIndex, warnings);
+    }
+    if (field.localized) {
+        if (data.locale === 'all') {
+            warnings.push(`Received non-localized data for localized field at path ${data.field_path.join('.')}`);
+        }
+        else if (resolveLocale) {
+            // When resolving a specific locale, only accept the matching locale row
+            // and set the value directly instead of wrapping in { locale: value }.
+            if (data.locale === resolveLocale) {
+                target = extractValueFieldData(data);
+            }
+        }
+        else {
+            target = target || {};
+            target[data.locale] = extractValueFieldData(data);
+        }
+    }
+    else {
+        if (data.locale !== 'all') {
+            warnings.push(`Received localized data for non-localized field at path ${data.field_path.join('.')}`);
+        }
+        else {
+            target = extractValueFieldData(data);
+        }
+    }
+    return target;
+};
+const restoreGroupFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+    if (pathIndex >= data.field_path.length) {
+        warnings.push(`Path ended unexpectedly while restoring group: ${data.field_path.join('.')}`);
+        return target;
+    }
+    // biome-ignore lint/style/noNonNullAssertion: pathIndex is assumed to be a non-negative integer
+    const fieldName = data.field_path[pathIndex];
+    const subField = field.fields.find((f) => f.name === fieldName);
+    if (subField == null) {
+        // Sub-field was removed from the schema; silently skip orphaned rows.
+        return target;
+    }
+    target = target || {};
+    target[fieldName] = restoreFieldData(subField, target[fieldName], data, pathIndex + 1, warnings, resolveLocale);
+    return target;
+};
+const restoreArrayFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+    if (pathIndex >= data.field_path.length) {
+        warnings.push(`Path ended unexpectedly while restoring array: ${data.field_path.join('.')}`);
+        return target;
+    }
+    // biome-ignore lint/style/noNonNullAssertion: pathIndex is assumed to be a non-negative integer
+    const arrayIndex = Number.parseInt(data.field_path[pathIndex], 10);
+    if (Number.isNaN(arrayIndex) || arrayIndex < 0) {
+        warnings.push(`Invalid array index '${data.field_path[pathIndex]}' in path ${data.field_path.join('.')}`);
+        return target;
+    }
+    target = target || [];
+    target[arrayIndex] = target[arrayIndex] || {};
+    if (pathIndex + 1 === data.field_path.length) {
+        if (data.field_type === 'meta') {
+            target[arrayIndex]._id = data.item_id;
+        }
+        else {
+            warnings.push(`Expected meta field for array item but got ${data.field_type} at path ${data.field_path.join('.')}`);
+        }
+        return target;
+    }
+    // biome-ignore lint/style/noNonNullAssertion: pathIndex is assumed to be a non-negative integer
+    const fieldName = data.field_path[pathIndex + 1];
+    const subField = field.fields.find((f) => f.name === fieldName);
+    if (subField == null) {
+        // Sub-field was removed from the schema; silently skip orphaned rows.
+        return target;
+    }
+    target[arrayIndex][fieldName] = restoreFieldData(subField, target[arrayIndex][fieldName], data, pathIndex + 2, warnings, resolveLocale);
+    return target;
+};
+const restoreBlocksFieldData = (field, target, data, pathIndex, warnings, resolveLocale) => {
+    const arrayIndex = Number.parseInt(data.field_path[pathIndex] ?? '', 10);
+    if (Number.isNaN(arrayIndex) || arrayIndex < 0) {
+        warnings.push(`Invalid block index '${data.field_path[pathIndex]}' in path ${data.field_path.join('.')}`);
+        return target;
+    }
+    const blockType = data.field_path[pathIndex + 1];
+    if (typeof blockType !== 'string') {
+        warnings.push(`Invalid block type '${data.field_path[pathIndex + 1]}' in path ${data.field_path.join('.')}`);
+        return target;
+    }
+    const block = field.blocks.find((f) => f.blockType === blockType);
+    if (block == null) {
+        // Block type was removed from the schema; silently skip orphaned rows.
+        return target;
+    }
+    target = target || [];
+    target[arrayIndex] = target[arrayIndex] || {};
+    if (pathIndex + 2 === data.field_path.length) {
+        if (data.field_type === 'meta') {
+            target[arrayIndex]._id = data.item_id;
+            target[arrayIndex]._type = blockType;
+        }
+        else {
+            warnings.push(`Expected meta field for block item but got ${data.field_type} at path ${data.field_path.join('.')}`);
+        }
+        return target;
+    }
+    // biome-ignore lint/style/noNonNullAssertion: pathIndex is assumed to be a non-negative integer
+    const fieldName = data.field_path[pathIndex + 2];
+    const subField = block.fields.find((f) => f.name === fieldName);
+    if (subField == null) {
+        // Sub-field was removed from the schema; silently skip orphaned rows.
+        return target;
+    }
+    target[arrayIndex][fieldName] = restoreFieldData(subField, target[arrayIndex][fieldName], data, pathIndex + 3, warnings, resolveLocale);
+    return target;
+};
+const restoreMultiRelationFieldData = (target, data, pathIndex, warnings) => {
+    // Path shape: `[...prefix, <field>, <index>]`. At `pathIndex` we have the
+    // ordered position; the row itself is a single relation value.
+    const arrayIndex = Number.parseInt(data.field_path[pathIndex] ?? '', 10);
+    if (Number.isNaN(arrayIndex) || arrayIndex < 0) {
+        warnings.push(`Invalid relation index '${data.field_path[pathIndex]}' in path ${data.field_path.join('.')}`);
+        return target;
+    }
+    if (data.field_type !== 'relation') {
+        warnings.push(`Expected relation row for hasMany relation but got ${data.field_type} at path ${data.field_path.join('.')}`);
+        return target;
+    }
+    target = target || [];
+    target[arrayIndex] = extractValueFieldData(data);
+    return target;
+};
+const extractValueFieldData = (data) => {
+    switch (data.field_type) {
+        case 'text':
+            return data.value;
+        case 'boolean':
+            return data.value;
+        case 'json':
+            return data.value;
+        case 'numeric': {
+            if (data.number_type === 'float') {
+                return data.value_float;
+            }
+            else if (data.number_type === 'integer') {
+                return data.value_integer;
+            }
+            else if (data.number_type === 'decimal') {
+                return data.value_decimal;
+            }
+            else {
+                throw ERR_DATABASE({
+                    message: `unsupported number type: ${data.number_type}`,
+                    details: { numberType: data.number_type },
+                }).log(getLogger());
+            }
+        }
+        case 'datetime': {
+            if (data.date_type === 'time') {
+                return data.value_time;
+            }
+            else if (data.date_type === 'date') {
+                return data.value_date;
+            }
+            else if (data.date_type === 'datetime') {
+                return data.value_timestamp_tz;
+            }
+            else {
+                throw ERR_DATABASE({
+                    message: `unsupported date type: ${data.date_type}`,
+                    details: { dateType: data.date_type },
+                }).log(getLogger());
+            }
+        }
+        case 'file':
+            return {
+                fileId: data.file_id,
+                filename: data.filename,
+                originalFilename: data.original_filename,
+                mimeType: data.mime_type,
+                fileSize: data.file_size,
+                storageProvider: data.storage_provider,
+                storagePath: data.storage_path,
+                storageUrl: data.storage_url,
+                fileHash: data.file_hash,
+                imageWidth: data.image_width,
+                imageHeight: data.image_height,
+                imageFormat: data.image_format,
+                processingStatus: data.processing_status,
+                thumbnailGenerated: data.thumbnail_generated,
+                variants: data.variants?.map((variant) => ({
+                    name: variant.name,
+                    storagePath: variant.storage_path,
+                    storageUrl: variant.storage_url,
+                    width: variant.width,
+                    height: variant.height,
+                    format: variant.format,
+                })),
+            };
+        case 'relation':
+            return {
+                targetDocumentId: data.target_document_id,
+                targetCollectionId: data.target_collection_id,
+                relationshipType: data.relationship_type,
+                cascadeDelete: data.cascade_delete,
+            };
+    }
+};
+// ------------------------------------------------------------------------------
+// Unified row extraction: convert a UNION-ALL `UnifiedFieldValue` row (the shape
+// the adapter reads back from the seven store tables) into a `FlattenedFieldValue`
+// ready to feed into `restoreFieldSetData`. Paired with restore because it's the
+// read-path adapter between raw SQL results and the reconstruct pipeline.
+// ------------------------------------------------------------------------------
+export const extractFlattenedFieldValue = (unifiedValue) => {
+    const baseValue = {
+        locale: unifiedValue.locale,
+        field_path: unifiedValue.field_path.split('.'),
+    };
+    switch (unifiedValue.field_type) {
+        case 'text':
+            return {
+                ...baseValue,
+                field_type: 'text',
+                value: unifiedValue.text_value,
+            };
+        case 'numeric':
+            return {
+                ...baseValue,
+                field_type: 'numeric',
+                number_type: unifiedValue.number_type,
+                value_float: orUndefined(unifiedValue.value_float),
+                value_integer: orUndefined(unifiedValue.value_integer),
+                value_decimal: orUndefined(unifiedValue.value_decimal),
+            };
+        case 'boolean':
+            return {
+                ...baseValue,
+                field_type: 'boolean',
+                value: unifiedValue.boolean_value,
+            };
+        case 'datetime':
+            return {
+                ...baseValue,
+                field_type: 'datetime',
+                date_type: unifiedValue.date_type,
+                value_date: orUndefined(unifiedValue.value_date),
+                value_time: orUndefined(unifiedValue.value_time),
+                value_timestamp_tz: orUndefined(unifiedValue.value_timestamp_tz),
+            };
+        case 'file':
+            return {
+                ...baseValue,
+                field_type: 'file',
+                file_id: unifiedValue.file_id,
+                filename: unifiedValue.filename,
+                original_filename: unifiedValue.original_filename,
+                mime_type: unifiedValue.mime_type,
+                file_size: Number(unifiedValue.file_size),
+                storage_provider: unifiedValue.storage_provider,
+                storage_path: unifiedValue.storage_path,
+                storage_url: orUndefined(unifiedValue.storage_url),
+                file_hash: orUndefined(unifiedValue.file_hash),
+                image_width: orUndefined(unifiedValue.image_width),
+                image_height: orUndefined(unifiedValue.image_height),
+                image_format: orUndefined(unifiedValue.image_format),
+                processing_status: orUndefined(unifiedValue.processing_status),
+                thumbnail_generated: orUndefined(unifiedValue.thumbnail_generated),
+                variants: orUndefined(unifiedValue.variants),
+            };
+        case 'relation':
+            return {
+                ...baseValue,
+                field_type: 'relation',
+                target_document_id: unifiedValue.target_document_id,
+                target_collection_id: unifiedValue.target_collection_id,
+                relationship_type: orUndefined(unifiedValue.relationship_type),
+                cascade_delete: orUndefined(unifiedValue.cascade_delete),
+            };
+        case 'richText':
+        case 'json':
+            return {
+                ...baseValue,
+                field_type: 'json',
+                value: unifiedValue.json_value,
+            };
+        case 'meta':
+            return {
+                ...baseValue,
+                field_type: 'meta',
+                type: unifiedValue.meta_type,
+                item_id: unifiedValue.meta_item_id,
+            };
+        default:
+            throw ERR_DATABASE({
+                message: `unexpected field type: ${unifiedValue.field_type}`,
+                details: { fieldType: unifiedValue.field_type },
+            }).log(getLogger());
+    }
+};
+const orUndefined = (value) => {
+    return value === null ? undefined : value;
+};

package/dist/storage/storage-row-types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 type { FileStoreVariant } from '../@types/index.js';
+interface BaseFlattenedFieldData {
+    locale: string;
+    field_path: string[];
+}
+interface FlattenedTextFieldValue extends BaseFlattenedFieldData {
+    field_type: 'text';
+    value: string;
+}
+interface FlattenedNumericFieldValue extends BaseFlattenedFieldData {
+    field_type: 'numeric';
+    number_type: 'integer' | 'float' | 'decimal';
+    value_float?: number;
+    value_integer?: number;
+    value_decimal?: string;
+}
+interface FlattenedBooleanFieldValue extends BaseFlattenedFieldData {
+    field_type: 'boolean';
+    value: boolean;
+}
+interface FlattenedDateTimeFieldValue extends BaseFlattenedFieldData {
+    field_type: 'datetime';
+    date_type: 'datetime' | 'date' | 'time';
+    value_time?: string;
+    value_date?: Date | string;
+    value_timestamp_tz?: Date | string;
+}
+interface FlattenedFileFieldValue extends BaseFlattenedFieldData {
+    field_type: 'file';
+    file_id: string;
+    filename: string;
+    original_filename: string;
+    mime_type: string;
+    file_size: number;
+    storage_provider: string;
+    storage_path: string;
+    storage_url?: string;
+    file_hash?: string;
+    image_width?: number;
+    image_height?: number;
+    image_format?: string;
+    processing_status?: string;
+    thumbnail_generated?: boolean;
+    variants?: FileStoreVariant[];
+}
+interface FlattenedRelationFieldValue extends BaseFlattenedFieldData {
+    field_type: 'relation';
+    target_document_id: string;
+    target_collection_id: string;
+    relationship_type?: string;
+    cascade_delete?: boolean;
+}
+interface FlattenedJsonFieldValue extends BaseFlattenedFieldData {
+    field_type: 'json';
+    value: unknown;
+}
+interface FlattenedMetaFieldValue extends BaseFlattenedFieldData {
+    field_type: 'meta';
+    type: 'array_item' | 'group';
+    item_id: string;
+    meta?: unknown;
+}
+export type FlattenedFieldValue = FlattenedTextFieldValue | FlattenedNumericFieldValue | FlattenedBooleanFieldValue | FlattenedDateTimeFieldValue | FlattenedFileFieldValue | FlattenedRelationFieldValue | FlattenedJsonFieldValue | FlattenedMetaFieldValue;
+export interface UnifiedFieldValue {
+    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 | string | 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;
+    meta_type: string | null;
+    meta_item_id: string | null;
+}
+export {};

package/dist/storage/storage-row-types.js

@@ -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/storage-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { type StoreType } from './field-store-map.js';
+import type { FieldSet } from '../@types/index.js';
+/**
+ * Given a CollectionDefinition and a list of field names, determine which
+ * StoreTypes are needed to satisfy the query. This enables selective field
+ * loading — instead of a 7-table UNION ALL, we query only the relevant stores.
+ *
+ * Field names that don't match a collection field (e.g. 'status', 'updated_at')
+ * are silently ignored — they come from the document version row, not EAV stores.
+ *
+ * Structure fields (array, blocks) recursively include all their children's
+ * store types plus 'meta' for _id/_type tracking.
+ */
+export declare function resolveStoreTypes(fields: FieldSet, fieldNames: string[]): Set<StoreType>;

package/dist/storage/storage-utils.js

@@ -0,0 +1,60 @@
+/**
+ * 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 { fieldTypeToStoreType } from './field-store-map.js';
+// ------------------------------------------------------------------------------
+// Field name → store type resolution
+// ------------------------------------------------------------------------------
+/**
+ * Given a CollectionDefinition and a list of field names, determine which
+ * StoreTypes are needed to satisfy the query. This enables selective field
+ * loading — instead of a 7-table UNION ALL, we query only the relevant stores.
+ *
+ * Field names that don't match a collection field (e.g. 'status', 'updated_at')
+ * are silently ignored — they come from the document version row, not EAV stores.
+ *
+ * Structure fields (array, blocks) recursively include all their children's
+ * store types plus 'meta' for _id/_type tracking.
+ */
+export function resolveStoreTypes(fields, fieldNames) {
+    const stores = new Set();
+    for (const name of fieldNames) {
+        const field = fields.find((f) => f.name === name);
+        if (!field)
+            continue;
+        collectStoreTypes(field, stores);
+    }
+    return stores;
+}
+function collectStoreTypes(field, stores) {
+    const mapped = fieldTypeToStoreType[field.type];
+    if (mapped === 'meta') {
+        // Structure field — recurse into children and include meta for _id/_type
+        if (field.type === 'array') {
+            for (const child of field.fields) {
+                collectStoreTypes(child, stores);
+            }
+        }
+        else if (field.type === 'blocks') {
+            for (const block of field.blocks) {
+                for (const child of block.fields) {
+                    collectStoreTypes(child, stores);
+                }
+            }
+        }
+        // Meta rows are fetched separately (not via UNION ALL), so no store type to add
+    }
+    else if (mapped) {
+        stores.add(mapped);
+    }
+    // undefined (group) or unrecognized — recurse if group
+    if (field.type === 'group') {
+        for (const child of field.fields) {
+            collectStoreTypes(child, stores);
+        }
+    }
+}

package/dist/storage/store-manifest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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
+ *
+ * The dialect-independent column manifest for the EAV store tables.
+ *
+ * Every adapter's UNION ALL over its `store_*` tables projects into the same
+ * unified row shape (see `UnifiedFieldValue`). Instead of each adapter
+ * hand-maintaining its own list of columns, adapters generate their SELECT
+ * lists from this single manifest — adding a column or a new store table is
+ * a one-line change here rather than N hand-synchronized SQL fragments.
+ *
+ * This module is pure data: no SQL, no drizzle-orm, no pg. Each adapter owns
+ * its own SQL generation (e.g. `@byline/db-postgres`'s `storeSelectList()` +
+ * `pgNullCast()`) consuming this manifest.
+ */
+import type { StoreType } from './field-store-map.js';
+/**
+ * Each entry describes one column in the unified UNION ALL output.
+ *
+ * - `name`:     The output column alias (matches UnifiedFieldValue / FlattenedFieldValue).
+ * - `nullCast`: The abstract SQL type name used when a store table does NOT
+ *               provide this column (e.g. `'boolean'`, `'uuid'`, `'text'`).
+ *               Only the first SELECT in a UNION ALL strictly needs casts,
+ *               but including them everywhere is harmless and makes each
+ *               fragment self-describing. Each adapter maps this abstract
+ *               name to its own dialect cast — the Postgres adapter's
+ *               `pgNullCast()` renders it as `NULL::<cast>`.
+ * - `sources`:  A map from store type key → the source column name that
+ *               produces this column's value from that table. If a store
+ *               type is absent, the column is emitted as a typed NULL.
+ */
+export interface ColumnDef {
+    name: string;
+    nullCast: string;
+    sources?: Partial<Record<StoreType, string>>;
+}
+/** Store table names, keyed by StoreType. Shared naming convention across adapters. */
+export declare const storeTableNames: Record<StoreType, string>;
+/**
+ * Canonical column order for the unified UNION ALL output.
+ *
+ * The first 7 columns are shared across all store tables (base columns).
+ * The remaining columns are type-specific — each one declares which store
+ * table(s) provide it and what source column to read.
+ */
+export declare const storeColumnManifest: ColumnDef[];