@byline/core 3.20.3 → 3.21.0

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

@@ -24,6 +24,14 @@ const minimalCollection = {
         ],
     },
 };
+const numericCollection = {
+    ...minimalCollection,
+    fields: [
+        { name: 'quantity', type: 'integer' },
+        { name: 'score', type: 'float' },
+        { name: 'price', type: 'decimal' },
+    ],
+};
 /** Build a mock IDbAdapter. Returns the adapter plus individual mock fns. */
 function createMockDb() {
     const createDocumentVersion = vi.fn().mockResolvedValue({
@@ -235,6 +243,23 @@ describe('Document lifecycle service', () => {
             const persistedData = createDocumentVersion.mock.calls[0]?.[0].documentData;
             expect(persistedData.title).toBe('Mutated');
         });
+        it('normalizes numeric values before and after beforeCreate', async () => {
+            const { db, createDocumentVersion } = createMockDb();
+            const beforeCreate = vi.fn(({ data }) => {
+                expect(data).toMatchObject({ quantity: 2, score: 1.5, price: '10.00' });
+                data.quantity = '3';
+                data.price = 12.5;
+            });
+            const definition = { ...numericCollection, hooks: { beforeCreate } };
+            await createDocument(buildCtx(db, definition), {
+                data: { quantity: '2', score: '1.5', price: ' 10.00 ' },
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData).toMatchObject({
+                quantity: 3,
+                score: 1.5,
+                price: '12.5',
+            });
+        });
         it('derives path from useAsPath source field via the slugifier', async () => {
             const { db, createDocumentVersion } = createMockDb();
             const definition = { ...minimalCollection, useAsPath: 'title' };
@@ -378,6 +403,24 @@ describe('Document lifecycle service', () => {
             }));
             expect(createDocumentVersion).toHaveBeenCalledOnce();
         });
+        it('normalizes numeric values before and after beforeUpdate', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({ fields: { quantity: 1, score: 1, price: '1.0' } });
+            const beforeUpdate = vi.fn(({ data }) => {
+                expect(data.score).toBe(25);
+                data.score = '3.5';
+            });
+            const definition = { ...numericCollection, hooks: { beforeUpdate } };
+            await updateDocument(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                data: { quantity: '2', score: '2.5e1', price: 4.25 },
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData).toEqual({
+                quantity: 2,
+                score: 3.5,
+                price: '4.25',
+            });
+        });
         it('afterUpdate receives documentId and documentVersionId', async () => {
             const afterUpdate = vi.fn();
             const { db, getDocumentById } = createMockDb();
@@ -670,6 +713,29 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
+        it('normalizes patched and hook-produced numeric values before persistence', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                fields: { quantity: 1, score: 1, price: '1.00' },
+            });
+            const beforeUpdate = vi.fn(({ data }) => {
+                expect(data.quantity).toBe(7);
+                data.price = ' 8.500 ';
+            });
+            const definition = { ...numericCollection, hooks: { beforeUpdate } };
+            await updateDocumentWithPatches(buildCtx(db, definition), {
+                documentId: 'doc-1',
+                patches: [
+                    { kind: 'field.set', path: 'quantity', value: '7.0' },
+                    { kind: 'field.set', path: 'score', value: '2.75' },
+                ],
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData).toEqual({
+                quantity: 7,
+                score: 2.75,
+                price: '8.500',
+            });
+        });
     });
     // -----------------------------------------------------------------------
     // changeDocumentStatus

package/dist/services/index.d.ts

@@ -9,6 +9,7 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { type InterfaceI18nConfig, type TranslationDriftWarning, type ValidateTranslationsResult, validateTranslations, } from './i18n-validator.js';
+export { type CanonicalNumericFieldType, type CanonicalNumericValue, isCanonicalNumericValue, normalizeNumericFields, normalizeNumericValue, } from './normalize-numeric-fields.js';
 export { type CycleRelationValue, createReadContext, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateOptions, type PopulateSpec, populateDocuments, type ReadContext, resolveIdentityField, type UnresolvedRelationValue, } from './populate.js';
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';

package/dist/services/index.js

@@ -10,6 +10,7 @@ export * from './document-read.js';
 export * from './document-to-markdown.js';
 export * from './field-upload.js';
 export { validateTranslations, } from './i18n-validator.js';
+export { isCanonicalNumericValue, normalizeNumericFields, normalizeNumericValue, } from './normalize-numeric-fields.js';
 export { createReadContext, populateDocuments, resolveIdentityField, } from './populate.js';
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
 export { embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';

package/dist/services/normalize-numeric-fields.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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';
+export type CanonicalNumericFieldType = 'integer' | 'float' | 'decimal';
+export type CanonicalNumericValue = number | string;
+/** Return whether a value already has the storage-facing canonical type and shape. */
+export declare function isCanonicalNumericValue(fieldType: CanonicalNumericFieldType, value: unknown): value is CanonicalNumericValue;
+/**
+ * Convert a tolerant numeric write value to its canonical representation.
+ * `undefined` means the value was empty and should be removed.
+ */
+export declare function normalizeNumericValue(fieldType: CanonicalNumericFieldType, value: unknown, path: string): CanonicalNumericValue | undefined;
+/**
+ * Normalize every user-writable numeric leaf in a schema-shaped data tree.
+ * Mutates `data` in place. Counter fields are deliberately excluded because
+ * their values are supplied by the lifecycle allocator.
+ */
+export declare function normalizeNumericFields(fields: FieldSet, data: Record<string, any>): void;

package/dist/services/normalize-numeric-fields.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { ERR_VALIDATION } from '../lib/errors.js';
+import { walkFieldTree } from './walk-field-tree.js';
+const NUMERIC_LITERAL_RE = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+/** Return whether a value already has the storage-facing canonical type and shape. */
+export function isCanonicalNumericValue(fieldType, value) {
+    if (fieldType === 'decimal') {
+        return typeof value === 'string' && value.trim() === value && NUMERIC_LITERAL_RE.test(value);
+    }
+    return (typeof value === 'number' &&
+        Number.isFinite(value) &&
+        (fieldType !== 'integer' || Number.isInteger(value)));
+}
+/**
+ * Convert a tolerant numeric write value to its canonical representation.
+ * `undefined` means the value was empty and should be removed.
+ */
+export function normalizeNumericValue(fieldType, value, path) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return undefined;
+        if (!NUMERIC_LITERAL_RE.test(trimmed))
+            throwNumericValidation(fieldType, value, path);
+        if (fieldType === 'decimal')
+            return trimmed;
+        const numberValue = Number(trimmed);
+        if (!Number.isFinite(numberValue))
+            throwNumericValidation(fieldType, value, path);
+        if (fieldType === 'integer' && !Number.isInteger(numberValue)) {
+            throwNumericValidation(fieldType, value, path);
+        }
+        return numberValue;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throwNumericValidation(fieldType, value, path);
+        if (fieldType === 'integer' && !Number.isInteger(value)) {
+            throwNumericValidation(fieldType, value, path);
+        }
+        return fieldType === 'decimal' ? String(value) : value;
+    }
+    throwNumericValidation(fieldType, value, path);
+}
+/**
+ * Normalize every user-writable numeric leaf in a schema-shaped data tree.
+ * Mutates `data` in place. Counter fields are deliberately excluded because
+ * their values are supplied by the lifecycle allocator.
+ */
+export function normalizeNumericFields(fields, data) {
+    for (const leaf of walkFieldTree(fields, data)) {
+        if (!isWritableNumericType(leaf.field.type))
+            continue;
+        if (leaf.field.localized === true && isLocaleMap(leaf.value)) {
+            for (const [locale, localeValue] of Object.entries(leaf.value)) {
+                normalizeLeafValue(leaf.field.type, leaf.value, locale, localeValue, `${leaf.fieldPath}.${locale}`);
+            }
+            continue;
+        }
+        normalizeLeafValue(leaf.field.type, leaf.parent, leaf.key, leaf.value, leaf.fieldPath);
+    }
+}
+function normalizeLeafValue(fieldType, parent, key, value, path) {
+    const normalized = normalizeNumericValue(fieldType, value, path);
+    if (normalized === undefined) {
+        delete parent[key];
+    }
+    else {
+        parent[key] = normalized;
+    }
+}
+function isWritableNumericType(type) {
+    return type === 'integer' || type === 'float' || type === 'decimal';
+}
+function isLocaleMap(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function throwNumericValidation(fieldType, value, path) {
+    throw ERR_VALIDATION({
+        message: `invalid ${fieldType} value at '${path}'`,
+        details: { path, fieldType, value },
+    });
+}

package/dist/services/normalize-numeric-fields.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/normalize-numeric-fields.test.node.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { BylineError, ErrorCodes } from '../lib/errors.js';
+import { normalizeNumericFields, normalizeNumericValue } from './normalize-numeric-fields.js';
+const fields = [
+    { name: 'count', type: 'integer' },
+    { name: 'ratio', type: 'float' },
+    { name: 'price', type: 'decimal' },
+    { name: 'sequence', type: 'counter', group: 'test' },
+    {
+        name: 'settings',
+        type: 'group',
+        fields: [{ name: 'threshold', type: 'float' }],
+    },
+    {
+        name: 'rows',
+        type: 'array',
+        fields: [{ name: 'quantity', type: 'integer' }],
+    },
+    {
+        name: 'content',
+        type: 'blocks',
+        blocks: [
+            {
+                blockType: 'amount',
+                fields: [{ name: 'value', type: 'decimal' }],
+            },
+        ],
+    },
+];
+describe('normalizeNumericFields', () => {
+    it('normalizes numeric leaves through groups, arrays, and blocks while leaving counters alone', () => {
+        const data = {
+            count: '12',
+            ratio: ' 1.25e2 ',
+            price: ' 001.2300 ',
+            sequence: 'caller-owned-value',
+            settings: { threshold: 2 },
+            rows: [{ quantity: '3.0' }, { quantity: 4 }],
+            content: [{ _type: 'amount', value: 5.5 }],
+        };
+        normalizeNumericFields(fields, data);
+        expect(data).toEqual({
+            count: 12,
+            ratio: 125,
+            price: '001.2300',
+            sequence: 'caller-owned-value',
+            settings: { threshold: 2 },
+            rows: [{ quantity: 3 }, { quantity: 4 }],
+            content: [{ _type: 'amount', value: '5.5' }],
+        });
+        normalizeNumericFields(fields, data);
+        expect(data.price).toBe('001.2300');
+    });
+    it('removes empty and whitespace-only values', () => {
+        const data = { count: '', ratio: '   ', price: '\t' };
+        normalizeNumericFields(fields, data);
+        expect(data).toEqual({});
+    });
+    it('normalizes all-locale value maps and reports the locale-qualified path', () => {
+        const localizedFields = [
+            { name: 'amount', type: 'decimal', localized: true },
+        ];
+        const data = { amount: { en: ' 1.20 ', fr: 'not-a-number', de: '' } };
+        expect(() => normalizeNumericFields(localizedFields, data)).toThrowError(expect.objectContaining({
+            code: ErrorCodes.VALIDATION,
+            details: expect.objectContaining({ path: 'amount.fr' }),
+        }));
+        expect(data.amount.en).toBe('1.20');
+    });
+    it.each([
+        ['integer', '1.2'],
+        ['integer', Number.NaN],
+        ['float', Number.POSITIVE_INFINITY],
+        ['float', '1e'],
+        ['decimal', '--1'],
+    ])('rejects invalid %s input', (fieldType, value) => {
+        expect(() => normalizeNumericValue(fieldType, value, 'nested.2.value')).toThrowError(expect.objectContaining({
+            code: ErrorCodes.VALIDATION,
+            details: expect.objectContaining({ path: 'nested.2.value' }),
+        }));
+    });
+    it('throws a BylineError with ERR_VALIDATION', () => {
+        try {
+            normalizeNumericValue('integer', {}, 'count');
+            expect.fail('expected ERR_VALIDATION');
+        }
+        catch (error) {
+            expect(error).toBeInstanceOf(BylineError);
+            expect(error).toMatchObject({ code: ErrorCodes.VALIDATION });
+        }
+    });
+});

package/dist/services/populate.d.ts

@@ -134,10 +134,11 @@ export type { ReadContext } from '../@types/index.js';
 /** Build a fresh ReadContext. */
 export declare function createReadContext(overrides?: Partial<ReadContext>): ReadContext;
 export type { PopulateFieldOptions, PopulateFieldSpec, PopulateMap, PopulateSpec, } from '../@types/populate-types.js';
+export type { CycleRelationValue, PopulatedRelationValue, RelationFieldReadValue, RelationReadValue, UnpopulatedRelationValue, UnresolvedRelationValue, } from '../@types/relation-types.js';
 export interface PopulateOptions {
     db: IDbAdapter;
     /** Every collection definition in the app — needed to resolve target fields. */
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     /** The source collection id for `documents`. */
     collectionId: string;
     /**
@@ -204,25 +205,6 @@ export interface PopulateOptions {
      */
     richTextPopulate?: import('../@types/index.js').RichTextPopulateFn;
 }
-/** Marker placed in a relation leaf when the target was already materialised earlier in this request. */
-export interface CycleRelationValue extends RelatedDocumentValue {
-    _resolved: true;
-    _cycle: true;
-}
-/** Marker placed in a relation leaf when the target was not found (deleted). */
-export interface UnresolvedRelationValue extends RelatedDocumentValue {
-    _resolved: false;
-}
-/**
- * Envelope placed in a relation leaf when populate successfully fetched
- * the target document. The `document` field carries the raw storage-shape
- * doc (`@byline/client` then reshapes it to `ClientDocument` during
- * response shaping).
- */
-export interface PopulatedRelationValue extends RelatedDocumentValue {
-    _resolved: true;
-    document: Record<string, any>;
-}
 /**
  * Populate relation leaves in `opts.documents` in place, one DB
  * round-trip per depth level per target collection.

package/dist/services/richtext-populate.d.ts

@@ -102,4 +102,4 @@ export interface RichTextAdapterPresence {
  * Called once at `initBylineCore()` time. Fail-fast at boot is the right
  * posture; the alternative is a silent broken renderer at request time.
  */
-export declare function validateRichTextFieldFlags(collections: CollectionDefinition[], adapters: RichTextAdapterPresence): void;
+export declare function validateRichTextFieldFlags(collections: readonly CollectionDefinition[], adapters: RichTextAdapterPresence): void;

package/dist/services/validate-search-config.d.ts

@@ -25,4 +25,4 @@ export interface SearchProviderPresence {
  * actually opts in. Installations that don't use search leave
  * `ServerConfig.search` unset and pass cleanly.
  */
-export declare function validateSearchConfig(collections: CollectionDefinition[], adapters: SearchProviderPresence): void;
+export declare function validateSearchConfig(collections: readonly CollectionDefinition[], adapters: SearchProviderPresence): void;

package/dist/storage/collection-fingerprint.js

@@ -33,6 +33,12 @@ function canonicalField(field) {
             base.targetCollection = field.targetCollection;
             if (field.displayField !== undefined)
                 base.displayField = field.displayField;
+            if (field.hasMany === true)
+                base.hasMany = true;
+            if (field.minItems !== undefined)
+                base.minItems = field.minItems;
+            if (field.maxItems !== undefined)
+                base.maxItems = field.maxItems;
             return base;
         case 'datetime':
             if (field.mode !== undefined)

package/dist/storage/collection-fingerprint.test.node.js

@@ -145,6 +145,27 @@ describe('fingerprintCollection', () => {
         rel.targetCollection = 'tags';
         expect(await fingerprintCollection(b)).not.toBe(a);
     });
+    it('changes when a relation becomes hasMany', async () => {
+        const a = await fingerprintCollection(baseCollection());
+        const b = baseCollection();
+        const rel = b.fields.find((f) => f.name === 'category');
+        rel.hasMany = true;
+        expect(await fingerprintCollection(b)).not.toBe(a);
+    });
+    it.each([
+        'minItems',
+        'maxItems',
+    ])('changes when relation %s changes', async (constraint) => {
+        const a = baseCollection();
+        const aRel = a.fields.find((f) => f.name === 'category');
+        aRel.hasMany = true;
+        aRel[constraint] = 1;
+        const b = baseCollection();
+        const bRel = b.fields.find((f) => f.name === 'category');
+        bRel.hasMany = true;
+        bRel[constraint] = 2;
+        expect(await fingerprintCollection(b)).not.toBe(await fingerprintCollection(a));
+    });
     it('changes when a block variant is renamed', async () => {
         const a = await fingerprintCollection(baseCollection());
         const b = baseCollection();

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.20.3",
+  "version": "3.21.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -31,6 +31,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./codegen": {
+      "types": "./dist/codegen/index.d.ts",
+      "import": "./dist/codegen/index.js",
+      "require": "./dist/codegen/index.js"
+    },
     "./zod-schemas": {
       "types": "./dist/schemas/zod/index.d.ts",
       "import": "./dist/schemas/zod/index.js",
@@ -76,7 +81,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "3.20.3"
+    "@byline/auth": "3.21.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",