@byline/core 3.20.4 → 3.21.0

package/dist/codegen/index.test.node.js

@@ -0,0 +1,230 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { AllFieldsCollection, AllFieldsCollections, } from './fixtures/all-fields.js';
+import { emitCollectionTypes } from './index.js';
+const fixtureDirectory = resolve(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+function collection(path, fields) {
+    return { path, labels: { singular: path, plural: path }, fields };
+}
+describe('emitCollectionTypes', () => {
+    it('matches the checked-in all-fields fixture and canonical inferred contracts exactly', () => {
+        const result = emitCollectionTypes(AllFieldsCollections);
+        const fixture = readFileSync(resolve(fixtureDirectory, 'all-fields.generated.txt'), 'utf8');
+        expect(result.source).toBe(fixture);
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
+    it('emits a versioned header, verifiable body hash, and canonical formatting', () => {
+        const { source, hash } = emitCollectionTypes([collection('plain', [])]);
+        const body = source.split('\n').slice(4).join('\n');
+        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 1\n\/\/ Hash: [a-f0-9]{64}\n\n/);
+        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v1\n${body}`).digest('hex'));
+        expect(source).toContain(`// Hash: ${hash}`);
+        expect(source.endsWith('\n')).toBe(true);
+        expect(source).not.toContain('\r');
+        expect(source).not.toContain(';');
+    });
+    it('sorts collections and declarations without changing field, select, or block union order', () => {
+        const alpha = collection('alpha', [
+            {
+                name: 'choice',
+                type: 'select',
+                options: [
+                    { label: 'Zulu', value: 'zulu' },
+                    { label: 'Duplicate Zulu', value: 'zulu' },
+                    { label: 'Alpha', value: 'alpha' },
+                ],
+            },
+            {
+                name: 'content',
+                type: 'blocks',
+                blocks: [
+                    { blockType: 'zulu', fields: [] },
+                    { blockType: 'alpha', fields: [] },
+                ],
+            },
+        ]);
+        const zulu = collection('zulu', [{ name: 'title', type: 'text' }]);
+        const forward = emitCollectionTypes([zulu, alpha]);
+        const reverse = emitCollectionTypes([alpha, zulu]);
+        expect(forward).toEqual(reverse);
+        expect(forward.source).toContain(`choice: 'zulu' | 'alpha'`);
+        expect(forward.source).toContain(`content: Array<ZuluBlockData | AlphaBlockData>`);
+        expect(forward.source.indexOf(`alpha: AlphaFields`)).toBeLessThan(forward.source.indexOf(`zulu: ZuluFields`));
+    });
+    it('normalizes identifiers and quotes only invalid property keys', () => {
+        const source = emitCollectionTypes([
+            collection('API_response', [
+                { name: 'validKey', type: 'text' },
+                { name: 'café', type: 'text' },
+                { name: 'not-valid', type: 'text' },
+                {
+                    name: 'choice',
+                    type: 'select',
+                    options: [
+                        { label: 'First', value: 'first' },
+                        { label: 'First duplicate', value: 'first' },
+                        { label: 'Second', value: 'second' },
+                    ],
+                },
+                {
+                    name: 'content',
+                    type: 'blocks',
+                    blocks: [{ blockType: 'photoBlock', fields: [] }],
+                },
+            ]),
+            collection('photoBlock', []),
+            collection('café—API_response', []),
+        ]).source;
+        expect(source).toContain('export type ApiResponseFields = {');
+        expect(source).toContain('export type PhotoBlockFields = {}');
+        expect(source).toContain('export type CafeApiResponseFields = {}');
+        expect(source).toContain('export type PhotoBlockData = {');
+        expect(source).toContain('validKey: string');
+        expect(source).toContain('café: string');
+        expect(source).toContain(`'not-valid': string`);
+        expect(source).toContain(`choice: 'first' | 'second'`);
+        expect(source).toContain('API_response: ApiResponseFields');
+        expect(source).toContain(`'café—API_response': CafeApiResponseFields`);
+    });
+    it('ignores non-type metadata but changes output for type-significant values', () => {
+        const base = collection('articles', [
+            { name: 'title', type: 'text' },
+            { name: 'kind', type: 'select', options: [{ label: 'News', value: 'news' }] },
+        ]);
+        const metadataOnly = {
+            ...base,
+            labels: { singular: 'Story', plural: 'Stories' },
+            version: 99,
+            fields: [
+                { name: 'title', type: 'text', label: 'Headline', helpText: 'Displayed prominently' },
+                {
+                    name: 'kind',
+                    type: 'select',
+                    label: 'Kind',
+                    options: [{ label: 'Article', value: 'news' }],
+                },
+            ],
+        };
+        const changed = collection('articles', [
+            { name: 'title', type: 'integer' },
+            { name: 'kind', type: 'select', options: [{ label: 'News', value: 'report' }] },
+        ]);
+        expect(emitCollectionTypes([metadataOnly])).toEqual(emitCollectionTypes([base]));
+        expect(emitCollectionTypes([changed]).hash).not.toBe(emitCollectionTypes([base]).hash);
+    });
+    it('imports only used canonical types in fixed order', () => {
+        const noImports = emitCollectionTypes([
+            collection('simple', [{ name: 'title', type: 'text' }]),
+        ]).source;
+        const selectedImports = emitCollectionTypes([
+            collection('typed', [
+                { name: 'data', type: 'json' },
+                { name: 'relation', type: 'relation', targetCollection: 'simple' },
+                { name: 'file', type: 'file' },
+            ]),
+        ]).source;
+        expect(noImports).not.toContain('import type');
+        expect(selectedImports).toContain("import type {\n  JsonValue,\n  RelatedDocumentValue,\n  StoredFileValue,\n} from '@byline/core'");
+        expect(selectedImports).not.toContain('JsonObject');
+    });
+    it('reuses identical block contracts and suffixes incompatible normalized names', () => {
+        const sharedA = { blockType: 'hero', fields: [{ name: 'title', type: 'text' }] };
+        const sharedB = {
+            blockType: 'hero',
+            fields: [{ name: 'title', type: 'text', label: 'Ignored metadata' }],
+        };
+        const incompatible = {
+            blockType: 'hero',
+            fields: [{ name: 'title', type: 'integer' }],
+        };
+        const source = emitCollectionTypes([
+            collection('foo-bar', [{ name: 'content', type: 'blocks', blocks: [sharedA] }]),
+            collection('foo_bar', [{ name: 'content', type: 'blocks', blocks: [sharedB] }]),
+            collection('other', [{ name: 'content', type: 'blocks', blocks: [incompatible] }]),
+        ]).source;
+        expect(source.match(/export type HeroBlockData_[a-f0-9]+ =/g)).toHaveLength(2);
+        expect(source.match(/export type FooBarFields_[a-f0-9]+ =/g)).toHaveLength(2);
+        expect(source.match(/_type: 'hero'/g)).toHaveLength(4);
+    });
+    it('escapes property keys, block discriminants, and select literals', () => {
+        const source = emitCollectionTypes([AllFieldsCollection]).source;
+        expect(source).toContain(`'content\\'s':`);
+        expect(source).toContain(`_type: 'quote\\'block'`);
+        expect(source).toContain(`'tone\\'choice'?: 'calm' | 'author\\'s' | undefined`);
+    });
+    it('does not mutate definitions and accepts deeply frozen input', () => {
+        const field = Object.freeze({ name: 'title', type: 'text' });
+        const fields = Object.freeze([field]);
+        const definition = Object.freeze({
+            path: 'frozen',
+            labels: Object.freeze({ singular: 'Frozen', plural: 'Frozen' }),
+            fields,
+        });
+        const before = JSON.stringify(definition);
+        emitCollectionTypes(Object.freeze([definition]));
+        expect(JSON.stringify(definition)).toBe(before);
+    });
+    it('rejects duplicate collection paths', () => {
+        expect(() => emitCollectionTypes([collection('same', []), collection('same', [])])).toThrow("duplicate collection path 'same'");
+    });
+    it('rejects duplicate sibling fields at any nesting level', () => {
+        expect(() => emitCollectionTypes([
+            collection('duplicates', [
+                {
+                    name: 'group',
+                    type: 'group',
+                    fields: [
+                        { name: 'same', type: 'text' },
+                        { name: 'same', type: 'integer' },
+                    ],
+                },
+            ]),
+        ])).toThrow("duplicate sibling field 'same'");
+    });
+    it('rejects duplicate block types within one blocks field', () => {
+        expect(() => emitCollectionTypes([
+            collection('duplicates', [
+                {
+                    name: 'content',
+                    type: 'blocks',
+                    blocks: [
+                        { blockType: 'hero', fields: [] },
+                        { blockType: 'hero', fields: [{ name: 'title', type: 'text' }] },
+                    ],
+                },
+            ]),
+        ])).toThrow("duplicate local block type 'hero'");
+    });
+    it('rejects cyclic runtime definitions', () => {
+        const fields = [];
+        fields.push({ name: 'recursive', type: 'group', fields });
+        expect(() => emitCollectionTypes([collection('cycle', fields)])).toThrow('cycle detected');
+    });
+    it('rejects unsupported runtime field types', () => {
+        expect(() => emitCollectionTypes([
+            collection('unsupported', [{ name: 'future', type: 'future' }]),
+        ])).toThrow("unsupported runtime field type 'future'");
+    });
+    it('is exposed only through the published codegen subpath', () => {
+        const packageJson = JSON.parse(readFileSync(resolve(fixtureDirectory, '../../../package.json'), 'utf8'));
+        const rootSource = readFileSync(resolve(fixtureDirectory, '../../index.ts'), 'utf8');
+        expect(packageJson.exports['./codegen']).toEqual({
+            types: './dist/codegen/index.d.ts',
+            import: './dist/codegen/index.js',
+            require: './dist/codegen/index.js',
+        });
+        expect(rootSource).not.toMatch(/codegen/);
+    });
+});

package/dist/core.d.ts

@@ -12,7 +12,7 @@ import { type CollectionRecord } from './services/collection-bootstrap.js';
 import type { CollectionDefinition, IDbAdapter, IStorageProvider, ServerConfig } from './@types/index.js';
 export interface BylineCore<TAdminStore = unknown> {
     config: ServerConfig<TAdminStore>;
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     db: IDbAdapter;
     storage: IStorageProvider | undefined;
     logger: BylineLogger;

package/dist/query/parse-where.d.ts

@@ -28,7 +28,7 @@ declare const DOCUMENT_LEVEL_KEYS: Set<string>;
  */
 export interface ParseContext {
     /** All registered collection definitions. */
-    collections: CollectionDefinition[];
+    collections: readonly CollectionDefinition[];
     /** Resolve a collection path → DB row id. */
     resolveCollectionId: (path: string) => Promise<string>;
     /**

package/dist/schemas/zod/builder.js

@@ -118,9 +118,12 @@ export const fieldToZodSchema = (field, strict = true) => {
             schema = z.number().int();
             break;
         case 'float':
-        case 'decimal':
             schema = z.number();
             break;
+        case 'decimal':
+            // Postgres numeric values are restored as strings to preserve precision.
+            schema = z.string();
+            break;
         case 'image':
         case 'file': {
             // StoredFileValue — the object written by the upload endpoint and
@@ -132,7 +135,7 @@ export const fieldToZodSchema = (field, strict = true) => {
                 filename: z.string(),
                 originalFilename: z.string(),
                 mimeType: z.string(),
-                fileSize: z.string(),
+                fileSize: z.number(),
                 storageProvider: z.string(),
                 storagePath: z.string(),
                 storageUrl: z.string().nullable().optional(),
@@ -181,7 +184,8 @@ export const fieldToZodSchema = (field, strict = true) => {
                 schema = arr;
             }
             else {
-                schema = relationValue.nullable();
+                // Storage omits cleared values; it never restores a relation as null.
+                schema = relationValue;
             }
             break;
         }

package/dist/schemas/zod/builder.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schemas/zod/builder.test.node.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { defineCollection } from '../../@types/collection-types.js';
+import { createCollectionSchemas } from './builder.js';
+const Assets = defineCollection({
+    path: 'assets',
+    labels: { singular: 'Asset', plural: 'Assets' },
+    fields: [
+        { name: 'price', type: 'decimal' },
+        { name: 'download', type: 'file' },
+        { name: 'owner', type: 'relation', targetCollection: 'people' },
+    ],
+});
+const fieldsFixture = {
+    price: '1234567890.123456789',
+    download: {
+        fileId: 'file-1',
+        filename: 'report.pdf',
+        originalFilename: 'Report.pdf',
+        mimeType: 'application/pdf',
+        fileSize: 4096,
+        storageProvider: 'local',
+        storagePath: 'assets/report.pdf',
+        processingStatus: 'complete',
+    },
+    owner: {
+        targetDocumentId: 'person-1',
+        targetCollectionId: 'people',
+    },
+};
+describe('collection Zod schemas', () => {
+    it('parses the canonical decimal and file storage read shapes', () => {
+        const parsed = createCollectionSchemas(Assets).get.parse({
+            id: '550e8400-e29b-41d4-a716-446655440000',
+            status: 'published',
+            createdAt: '2026-07-15T12:00:00.000Z',
+            updatedAt: '2026-07-15T12:00:00.000Z',
+            fields: fieldsFixture,
+        });
+        expect(parsed.fields.price).toBe(fieldsFixture.price);
+        expect(parsed.fields.download?.fileSize).toBe(4096);
+    });
+    it('rejects null for a required single relation in the strict fields schema', () => {
+        const result = createCollectionSchemas(Assets).fields.safeParse({
+            ...fieldsFixture,
+            owner: null,
+        });
+        expect(result.success).toBe(false);
+    });
+});

package/dist/services/collection-bootstrap.d.ts

@@ -19,7 +19,7 @@ export interface CollectionRecord {
     schemaHash: string;
 }
 export interface EnsureCollectionsInput {
-    definitions: CollectionDefinition[];
+    definitions: readonly CollectionDefinition[];
     db: IDbAdapter;
     logger?: BylineLogger;
 }

package/dist/services/discover-counter-groups.d.ts

@@ -9,7 +9,7 @@ import { type CollectionDefinition } from '../@types/index.js';
 import type { IDbAdapter } from '../@types/db-types.js';
 import type { BylineLogger } from '../lib/logger.js';
 export interface DiscoverCounterGroupsInput {
-    definitions: CollectionDefinition[];
+    definitions: readonly CollectionDefinition[];
     db: IDbAdapter;
     logger?: BylineLogger;
 }

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

@@ -17,8 +17,8 @@ export interface CreateDocumentResult {
  *   1. Default-locale enforcement: reject if `params.locale` is anything
  *      other than the configured default content locale (a brand-new
  *      document's canonical `path` lives in the default locale).
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeCreate({ data, collectionPath })`, then normalize numerics again
  *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
  *      → UUID fallback.
  *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')

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

@@ -13,6 +13,7 @@ import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
+import { normalizeNumericFields } from '../normalize-numeric-fields.js';
 import { actorId, appendTreeRoot, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 /**
  * Create a new document.
@@ -21,8 +22,8 @@ import { actorId, appendTreeRoot, applyRichTextEmbed, derivePath, extractDocumen
  *   1. Default-locale enforcement: reject if `params.locale` is anything
  *      other than the configured default content locale (a brand-new
  *      document's canonical `path` lives in the default locale).
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeCreate({ data, collectionPath })`, then normalize numerics again
  *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
  *      → UUID fallback.
  *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')
@@ -42,7 +43,9 @@ export async function createDocument(ctx, params) {
             }).log(ctx.logger);
         }
         normaliseDateFields(data);
+        normalizeNumericFields(definition.fields, data);
         await invokeHook(hooks?.beforeCreate, { data, collectionPath });
+        normalizeNumericFields(definition.fields, data);
         // Allocate counter-field values after beforeCreate so user-land hooks
         // can run their own logic on the raw payload, but before the flatten/
         // insert pass so the assigned values are persisted on the same write.

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

@@ -23,8 +23,8 @@ export interface UpdateDocumentWithPatchesResult {
  *
  * Flow:
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`, then normalize numerics again
  *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
  */
@@ -54,8 +54,8 @@ export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
  *   2. Optimistic concurrency check on `documentVersionId`
  *   3. `applyPatches(definition, originalData, patches)` → `nextData`
- *   4. `normaliseDateFields(nextData)`
- *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`
+ *   4. Normalize date and numeric fields
+ *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`, then normalize numerics again
  *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
  *

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

@@ -13,6 +13,7 @@ import { applyPatches } from '../../patches/index.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
+import { normalizeNumericFields } from '../normalize-numeric-fields.js';
 import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, selfHealTreePlacement, } from './internals.js';
 /**
  * Update a document via full replacement (PUT semantics).
@@ -22,8 +23,8 @@ import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invok
  *
  * Flow:
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
- *   2. `normaliseDateFields(data)`
- *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`
+ *   2. Normalize date and numeric fields
+ *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`, then normalize numerics again
  *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
  */
@@ -43,7 +44,9 @@ export async function updateDocument(ctx, params) {
         });
         const originalData = latest ?? {};
         normaliseDateFields(data);
+        normalizeNumericFields(definition.fields, data);
         await invokeHook(hooks?.beforeUpdate, { data, originalData, collectionPath });
+        normalizeNumericFields(definition.fields, data);
         // Counter fields are immutable: carry their values forward from the
         // previous version rather than trusting whatever (or nothing) the
         // caller sent. Lazy-allocates when a counter was added to the
@@ -111,8 +114,8 @@ export async function updateDocument(ctx, params) {
  *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
  *   2. Optimistic concurrency check on `documentVersionId`
  *   3. `applyPatches(definition, originalData, patches)` → `nextData`
- *   4. `normaliseDateFields(nextData)`
- *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`
+ *   4. Normalize date and numeric fields
+ *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`, then normalize numerics again
  *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
  *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
  *
@@ -160,8 +163,10 @@ export async function updateDocumentWithPatches(ctx, params) {
         const nextData = patchedDocument;
         // 4. Normalise dates.
         normaliseDateFields(nextData);
+        normalizeNumericFields(definition.fields, nextData);
         // 5. beforeUpdate hook.
         await invokeHook(hooks?.beforeUpdate, { data: nextData, originalData, collectionPath });
+        normalizeNumericFields(definition.fields, nextData);
         // 5b. Carry counter values forward from the previous version (or
         // lazy-allocate if the previous version is missing a value). See
         // updateDocument for the rationale — patch-based updates are

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;