@byline/db-postgres 3.18.0 → 3.20.0

package/dist/modules/counters/counters-commands.d.ts

@@ -17,6 +17,7 @@ export declare class CounterCommands implements ICounterCommands {
         sequenceName: string;
     }>;
     nextCounterValue(groupName: string): Promise<number>;
+    nextScopedCounterValue(scopeName: string): Promise<number>;
 }
 export declare function createCounterCommands(db: DatabaseConnection): ICounterCommands;
 export {};

package/dist/modules/counters/counters-commands.js

@@ -90,6 +90,25 @@ export class CounterCommands {
         }
         return typeof row.value === 'number' ? row.value : Number(row.value);
     }
+    async nextScopedCounterValue(scopeName) {
+        if (!scopeName || typeof scopeName !== 'string') {
+            throw new Error(`nextScopedCounterValue: scopeName must be a non-empty string`);
+        }
+        // Fast path: the scope has been used before — its registry row and
+        // sequence already exist, so this is exactly a nextCounterValue call.
+        const rows = await this.db
+            .select({ sequence_name: counterGroups.sequence_name })
+            .from(counterGroups)
+            .where(eq(counterGroups.group_name, scopeName))
+            .limit(1);
+        if (rows.length === 0) {
+            // First allocation for this scope: self-register (idempotent — a
+            // concurrent racer leaves exactly one sequence + registry row, and
+            // both callers draw distinct values from the same sequence).
+            await this.ensureCounterGroup(scopeName);
+        }
+        return this.nextCounterValue(scopeName);
+    }
 }
 export function createCounterCommands(db) {
     return new CounterCommands(db);

package/dist/modules/counters/tests/counters-scoped.test.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/modules/counters/tests/counters-scoped.test.js

@@ -0,0 +1,100 @@
+/**
+ * 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 { eq, sql } from 'drizzle-orm';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { counterGroups } from '../../../database/schema/index.js';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+import { createCounterCommands } from '../counters-commands.js';
+// ---------------------------------------------------------------------------
+// Track-and-clean fixtures
+// ---------------------------------------------------------------------------
+//
+// Integration tests share the dev database. Each scope this suite touches
+// creates a registry row + a Postgres sequence; track the scope names and
+// drop both on teardown so repeated runs start from a clean slate (and so
+// monotonicity assertions are not satisfied by a previous run's sequence).
+let db;
+let counters;
+const trackedScopes = new Set();
+async function cleanupScope(scopeName) {
+    const rows = await db
+        .select({ sequence_name: counterGroups.sequence_name })
+        .from(counterGroups)
+        .where(eq(counterGroups.group_name, scopeName))
+        .limit(1);
+    const sequenceName = rows[0]?.sequence_name;
+    await db.delete(counterGroups).where(eq(counterGroups.group_name, scopeName));
+    if (sequenceName) {
+        await db.execute(sql.raw(`DROP SEQUENCE IF EXISTS "${sequenceName}"`));
+    }
+}
+function scope(name) {
+    trackedScopes.add(name);
+    return name;
+}
+beforeAll(async () => {
+    const setup = setupTestDB();
+    db = setup.db;
+    counters = createCounterCommands(db);
+    // Clean any leftovers from a previously aborted run.
+    for (const name of trackedScopes) {
+        await cleanupScope(name);
+    }
+});
+afterAll(async () => {
+    for (const name of trackedScopes) {
+        await cleanupScope(name);
+    }
+    await teardownTestDB();
+});
+describe('nextScopedCounterValue', () => {
+    it('self-registers an unknown scope and allocates from 1', async () => {
+        const scopeName = scope('test:doc-a:files');
+        const first = await counters.nextScopedCounterValue(scopeName);
+        expect(first).toBe(1);
+        // The registry row and its backing sequence now exist.
+        const rows = await db
+            .select({ sequence_name: counterGroups.sequence_name })
+            .from(counterGroups)
+            .where(eq(counterGroups.group_name, scopeName));
+        expect(rows).toHaveLength(1);
+    });
+    it('is monotonic within a scope and never reuses a value', async () => {
+        const scopeName = scope('test:doc-b:files');
+        const a = await counters.nextScopedCounterValue(scopeName);
+        const b = await counters.nextScopedCounterValue(scopeName);
+        const c = await counters.nextScopedCounterValue(scopeName);
+        expect([a, b, c]).toEqual([1, 2, 3]);
+    });
+    it('scopes are independent — one scope does not advance another', async () => {
+        const scopeA = scope('test:doc-c:files');
+        const scopeB = scope('test:doc-d:files');
+        await counters.nextScopedCounterValue(scopeA);
+        await counters.nextScopedCounterValue(scopeA);
+        const bFirst = await counters.nextScopedCounterValue(scopeB);
+        expect(bFirst).toBe(1);
+    });
+    it('interoperates with nextCounterValue once registered (same sequence)', async () => {
+        const scopeName = scope('test:doc-e:files');
+        const viaScoped = await counters.nextScopedCounterValue(scopeName);
+        // After self-registration the static-path allocator sees the group too.
+        const viaStatic = await counters.nextCounterValue(scopeName);
+        expect(viaStatic).toBe(viaScoped + 1);
+    });
+    it('rejects an empty scope name', async () => {
+        await expect(counters.nextScopedCounterValue('')).rejects.toThrow(/scopeName must be a non-empty string/);
+    });
+    it('parallel allocations within one scope yield distinct values', async () => {
+        const scopeName = scope('test:doc-f:files');
+        const values = await Promise.all(Array.from({ length: 8 }, () => counters.nextScopedCounterValue(scopeName)));
+        const unique = new Set(values);
+        expect(unique.size).toBe(8);
+        expect(Math.min(...values)).toBe(1);
+        expect(Math.max(...values)).toBe(8);
+    });
+});

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

@@ -51,6 +51,17 @@ function* flattenFieldSetDataGen(fields, data, locale, parent_path = []) {
  * @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,

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

@@ -324,3 +324,82 @@ describe('reserved field-name tolerance on restore', () => {
         expect(warnings, 'a reserved-name orphan must not be treated as an unknown field').toEqual([]);
     });
 });
+describe('virtual fields', () => {
+    // Mirrors the publications shape that motivated `virtual`: a per-item
+    // "generate thumbnail" checkbox + page number inside an array group,
+    // plus a top-level virtual scalar. Virtual values must flow through the
+    // write pipeline (hooks see them) but emit NO store rows — reads
+    // reconstruct them as absent, so the next editing session starts clean.
+    const VirtualCollectionConfig = defineCollection({
+        path: 'virtual-docs',
+        labels: { singular: 'Virtual Doc', plural: 'Virtual Docs' },
+        fields: [
+            { name: 'title', type: 'text' },
+            { name: 'regenerateAll', type: 'checkbox', virtual: true, optional: true },
+            {
+                name: 'files',
+                type: 'array',
+                fields: [
+                    {
+                        name: 'filesGroup',
+                        type: 'group',
+                        fields: [
+                            { name: 'label', type: 'text' },
+                            { name: 'generateThumbnail', type: 'checkbox', virtual: true, optional: true },
+                            { name: 'thumbnailPage', type: 'integer', virtual: true, defaultValue: 1 },
+                        ],
+                    },
+                ],
+            },
+            {
+                name: 'scratch',
+                type: 'group',
+                virtual: true,
+                optional: true,
+                fields: [{ name: 'note', type: 'text', optional: true }],
+            },
+        ],
+    });
+    const virtualDocument = {
+        title: 'Publication-ish',
+        regenerateAll: true,
+        files: [
+            {
+                _id: 'item-1',
+                filesGroup: { label: 'English PDF', generateThumbnail: true, thumbnailPage: 3 },
+            },
+            {
+                _id: 'item-2',
+                filesGroup: { label: 'Thai PDF', generateThumbnail: false, thumbnailPage: 1 },
+            },
+        ],
+        scratch: { note: 'never stored' },
+    };
+    it('emits no store rows for virtual fields at any nesting depth', () => {
+        const flattened = flattenFieldSetData(VirtualCollectionConfig.fields, virtualDocument, 'all');
+        const paths = flattened.map((row) => row.field_path.join('.'));
+        // Persisted values survive…
+        expect(paths).toContain('title');
+        expect(paths).toContain('files.0.filesGroup.label');
+        expect(paths).toContain('files.1.filesGroup.label');
+        // …virtual leaves do not (top-level, nested in array group)…
+        expect(paths.some((p) => p.includes('regenerateAll'))).toBe(false);
+        expect(paths.some((p) => p.includes('generateThumbnail'))).toBe(false);
+        expect(paths.some((p) => p.includes('thumbnailPage'))).toBe(false);
+        // …and a virtual structure field omits its whole subtree.
+        expect(paths.some((p) => p.startsWith('scratch'))).toBe(false);
+    });
+    it('round-trip reconstruction leaves virtual fields structurally absent', () => {
+        const flattened = flattenFieldSetData(VirtualCollectionConfig.fields, virtualDocument, 'all');
+        const { data: restored, warnings } = restoreFieldSetData(VirtualCollectionConfig.fields, flattened);
+        expect(warnings).toEqual([]);
+        expect(restored.title).toBe('Publication-ish');
+        expect(restored.regenerateAll).toBeUndefined();
+        expect(restored.scratch).toBeUndefined();
+        const items = restored.files;
+        expect(items).toHaveLength(2);
+        expect(items[0]?.filesGroup.label).toBe('English PDF');
+        expect(items[0]?.filesGroup.generateThumbnail).toBeUndefined();
+        expect(items[0]?.filesGroup.thumbnailPage).toBeUndefined();
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.18.0",
+  "version": "3.20.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -56,9 +56,9 @@
     "npm-run-all": "^4.1.5",
     "pg": "^8.22.0",
     "uuid": "^14.0.1",
-    "@byline/auth": "3.18.0",
-    "@byline/core": "3.18.0",
-    "@byline/admin": "3.18.0"
+    "@byline/admin": "3.20.0",
+    "@byline/core": "3.20.0",
+    "@byline/auth": "3.20.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",