@byline/core 4.6.1 → 4.7.0

package/dist/storage/storage-flatten.js

@@ -0,0 +1,319 @@
+/**
+ * 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 { v7 as uuidv7 } from 'uuid';
+import { ERR_DATABASE } from '../lib/errors.js';
+import { getLogger } from '../lib/logger.js';
+import { isCanonicalNumericValue } from '../services/normalize-numeric-fields.js';
+// ------------------------------------------------------------------------------
+// Flattening logic: take a document's nested field data and flatten it into an
+// array of field values with associated metadata such as field path and locale.
+// ------------------------------------------------------------------------------
+/**
+ * Main entrypoint for flattening a document's (nested) field data into a flat
+ * array of field values.
+ *
+ * @param fields - The field definitions for the collection.
+ * @param data - The document's field data to flatten.
+ * @param locale - The locale to flatten for (or 'all' to flatten all locales).
+ */
+export const flattenFieldSetData = (fields, data, locale) => {
+    return Array.from(flattenFieldSetDataGen(fields, data, locale));
+};
+/**
+ * Flatten data for a FieldSet (Field[]) -- this could be the top-level field
+ * data for a document, or the data inside a group, array or blocks field.
+ *
+ * @param fields - The field definitions for the current field set.
+ * @param data - The field data for the current field set.
+ * @param locale - The locale to flatten for (or 'all' to flatten all locales).
+ * @param parent_path - The path segments leading up to the current field set.
+ * @returns
+ */
+function* flattenFieldSetDataGen(fields, data, locale, parent_path = []) {
+    if (data == null) {
+        return;
+    }
+    const fieldData = data;
+    for (const field of fields) {
+        yield* flattenFieldDataGen(field, fieldData[field.name], locale, [...parent_path, field.name]);
+    }
+}
+/**
+ * Flatten data for a single field.
+ *
+ * @param field - The field definition for the current field.
+ * @param data - The field data for the current field.
+ * @param locale - The locale to flatten for (or 'all' to flatten all locales).
+ * @param field_path - The path segments up to and including the current field.
+ * @returns
+ */
+function* flattenFieldDataGen(field, data, locale, field_path) {
+    // Virtual fields are never persisted. The value participated in the write
+    // pipeline (patches applied it, lifecycle hooks saw and could act on it),
+    // but no store_* row is written, so reads reconstruct the field as absent
+    // and the next editing session starts clean. This is the single
+    // enforcement point for the `virtual` contract — every nesting level
+    // (top-level, group children, array items, block fields) funnels through
+    // this function, and a virtual structure field omits its whole subtree.
+    // See `BaseField.virtual` in @byline/core.
+    if (field.virtual === true) {
+        return;
+    }
+    // Treat `null` the same as `undefined` — a removed/cleared field emits no
+    // storage rows for the new version, so reads reconstruct as absent. Without
+    // this guard, downstream value extractors (relation, file/image, group,
+    // localized) dereference `null` and crash.
+    if (data == null) {
+        return;
+    }
+    // Group fields are simple -- just use flattenFieldSetDataGen.  It will handle
+    // adding the appropriate field names to field_path.
+    if (field.type === 'group') {
+        yield* flattenFieldSetDataGen(field.fields, data, locale, field_path);
+    }
+    // For array fields, we must emit a single FlattenedMetaFieldData for each
+    // item to capture the item's stable ID, and then flatten the fields within
+    // each item using flattenFieldSetDataGen().
+    else if (field.type === 'array') {
+        const items = data;
+        for (let i = 0; i < items.length; i++) {
+            // biome-ignore lint/style/noNonNullAssertion: i is always in-bounds
+            const { _id, ...item_data } = items[i];
+            const item_path = [...field_path, `${i}`];
+            yield {
+                locale: 'all',
+                field_path: item_path,
+                field_type: 'meta',
+                type: 'array_item',
+                item_id: _id ?? uuidv7(),
+                meta: null,
+            };
+            yield* flattenFieldSetDataGen(field.fields, item_data, locale, item_path);
+        }
+    }
+    // Blocks are similar to arrays, but with an additional type discriminator for
+    // block variants.
+    else if (field.type === 'blocks') {
+        const items = data;
+        for (let i = 0; i < items.length; i++) {
+            // biome-ignore lint/style/noNonNullAssertion: i is always in-bounds
+            const { _id, _type, ...item_data } = items[i];
+            const item_path = [...field_path, `${i}`, _type];
+            const block = field.blocks.find((f) => f.blockType === _type);
+            if (!block) {
+                throw ERR_DATABASE({
+                    message: `invalid block type: ${_type}`,
+                    details: { blockType: _type },
+                }).log(getLogger());
+            }
+            yield {
+                locale: 'all',
+                field_path: item_path,
+                field_type: 'meta',
+                type: 'group',
+                item_id: _id ?? uuidv7(),
+                meta: null,
+            };
+            yield* flattenFieldSetDataGen(block.fields, item_data, locale, item_path);
+        }
+    }
+    // Ordered multi-target relation: emit one relation row per item at an
+    // indexed path (`<field>.0`, `<field>.1`, …), mirroring the array path
+    // convention. `restoreFieldSetData` reassembles the ordered array.
+    // Relations are non-localized, so every row carries locale 'all'. Identity
+    // is the `targetDocumentId` (the widget dedups), so no `store_meta` rows are
+    // needed. Must intercept before the generic value branch, which would
+    // otherwise read the whole array as a single relation value.
+    else if (field.type === 'relation' && field.hasMany) {
+        const items = data;
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            if (item == null)
+                continue;
+            yield flattenValueFieldData(field, [...field_path, `${i}`], item, 'all');
+        }
+    }
+    // Handle localized fields separately.
+    else if (field.localized) {
+        // If locale is 'all', data is expected to be an object that maps locales to
+        // the corresponding localized values, and we emit a separate
+        // FlattenedFieldData for each.
+        if (locale === 'all') {
+            const localizedData = data;
+            for (const [locale, value] of Object.entries(localizedData)) {
+                if (value !== undefined) {
+                    yield flattenValueFieldData(field, field_path, value, locale);
+                }
+            }
+        }
+        // If locale is not 'all', data is expected to be a single localized value
+        // for the specified locale, and we emit a single FlattenedFieldData for
+        // that locale.
+        else {
+            yield flattenValueFieldData(field, field_path, data, locale);
+        }
+    }
+    // For non-localized fields, data is expected to be the (non-localized) field
+    // value, and we emit a single FlattenedFieldData with locale 'all'.
+    else {
+        yield flattenValueFieldData(field, field_path, data, 'all');
+    }
+}
+const flattenValueFieldData = (field, field_path, value, locale) => {
+    const field_type = field.type;
+    switch (field_type) {
+        case 'text':
+        case 'textArea':
+        case 'code':
+        case 'select':
+            return {
+                locale,
+                field_path,
+                field_type: 'text',
+                value: value,
+            };
+        case 'float':
+            assertCanonicalNumericValue(field_type, value, field_path);
+            return {
+                locale,
+                field_path,
+                field_type: 'numeric',
+                number_type: 'float',
+                value_float: value,
+            };
+        case 'integer':
+            assertCanonicalNumericValue(field_type, value, field_path);
+            return {
+                locale,
+                field_path,
+                field_type: 'numeric',
+                number_type: 'integer',
+                value_integer: value,
+            };
+        case 'counter':
+            if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+                throwNonCanonicalNumericValue(field_type, value, field_path);
+            }
+            return {
+                locale,
+                field_path,
+                field_type: 'numeric',
+                number_type: 'integer',
+                value_integer: value,
+            };
+        case 'decimal':
+            assertCanonicalNumericValue(field_type, value, field_path);
+            return {
+                locale,
+                field_path,
+                field_type: 'numeric',
+                number_type: 'decimal',
+                value_decimal: value,
+            };
+        case 'boolean':
+        case 'checkbox':
+            return {
+                locale,
+                field_path,
+                field_type: 'boolean',
+                value: value,
+            };
+        case 'time':
+            return {
+                locale,
+                field_path,
+                field_type: 'datetime',
+                date_type: 'time',
+                value_time: value,
+            };
+        case 'date':
+            return {
+                locale,
+                field_path,
+                field_type: 'datetime',
+                date_type: 'date',
+                value_date: value,
+            };
+        case 'datetime':
+            return {
+                locale,
+                field_path,
+                field_type: 'datetime',
+                date_type: 'datetime',
+                value_timestamp_tz: value,
+            };
+        case 'file':
+        case 'image': {
+            const v = value;
+            return {
+                locale,
+                field_path,
+                field_type: 'file',
+                file_id: v.fileId,
+                filename: v.filename,
+                original_filename: v.originalFilename,
+                mime_type: v.mimeType,
+                file_size: v.fileSize,
+                storage_provider: v.storageProvider,
+                storage_path: v.storagePath,
+                storage_url: v.storageUrl,
+                file_hash: v.fileHash,
+                image_width: v.imageWidth,
+                image_height: v.imageHeight,
+                image_format: v.imageFormat,
+                processing_status: v.processingStatus,
+                thumbnail_generated: v.thumbnailGenerated,
+                variants: v.variants?.map((variant) => ({
+                    name: variant.name,
+                    storage_path: variant.storagePath,
+                    storage_url: variant.storageUrl,
+                    width: variant.width,
+                    height: variant.height,
+                    format: variant.format,
+                })),
+            };
+        }
+        case 'relation': {
+            const v = value;
+            return {
+                locale,
+                field_path,
+                field_type: 'relation',
+                target_document_id: v.targetDocumentId,
+                target_collection_id: v.targetCollectionId,
+                relationship_type: v.relationshipType,
+                cascade_delete: v.cascadeDelete,
+            };
+        }
+        case 'richText':
+        case 'json':
+        case 'object':
+            return {
+                locale,
+                field_path,
+                field_type: 'json',
+                value,
+            };
+        default:
+            throw ERR_DATABASE({
+                message: `unsupported field type: ${field_type}`,
+                details: { fieldType: field_type },
+            }).log(getLogger());
+    }
+};
+function assertCanonicalNumericValue(fieldType, value, fieldPath) {
+    if (!isCanonicalNumericValue(fieldType, value)) {
+        throwNonCanonicalNumericValue(fieldType, value, fieldPath);
+    }
+}
+function throwNonCanonicalNumericValue(fieldType, value, fieldPath) {
+    throw ERR_DATABASE({
+        message: `non-canonical ${fieldType} value reached storage at '${fieldPath.join('.')}'`,
+        details: { path: fieldPath.join('.'), fieldType, value },
+    });
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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 { FieldSet } from '../@types/index.js';
+import type { FlattenedFieldValue, UnifiedFieldValue } from './storage-row-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) => RestoreResult;
+export declare const extractFlattenedFieldValue: (unifiedValue: UnifiedFieldValue) => FlattenedFieldValue;