@byline/db-postgres 3.2.0 → 3.3.0

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

@@ -129,6 +129,66 @@ export declare class DocumentCommands implements IDocumentCommands {
         };
         fieldCount: number;
     }>;
+    /**
+     * writeDocumentPath
+     *
+     * Upsert the `byline_document_paths` row for a (document, locale) pair. The
+     * path row is document-grain and sticky across versions — it lives under the
+     * document's `source_locale` (its data anchor), not the mutable global
+     * default. Shared by `createDocumentVersion` (step 2a, create write path) and
+     * the standalone `updateDocumentPath` command (the non-versioned admin path
+     * widget write). The unique constraint on `(collection_id, locale, path)` may
+     * raise a `23505`, which the lifecycle layer maps to `ERR_PATH_CONFLICT`.
+     */
+    private writeDocumentPath;
+    /**
+     * writeDocumentAvailableLocales
+     *
+     * Replace a document's `byline_document_available_locales` rows wholesale —
+     * the editorial advertised-locale set. Document-grain and sticky across
+     * versions: `delete`-then-`insert`, deduplicated so a caller-supplied
+     * duplicate doesn't collide on the `(document_id, locale)` primary key. An
+     * empty array clears the set (advertise nothing). Shared by
+     * `createDocumentVersion` (step 2b, create write path) and the standalone
+     * `setDocumentAvailableLocales` command (the non-versioned admin
+     * available-locales widget write). See docs/I18N.md.
+     */
+    private writeDocumentAvailableLocales;
+    /**
+     * updateDocumentPath
+     *
+     * Standalone, non-versioned write of a document's URL path. Backs the admin
+     * path widget's direct-write Save path: it edits `byline_document_paths`
+     * in-place (document-grain, sticky) **without** minting a new document
+     * version or touching workflow status. The path's document-grain nature means
+     * the change is immediate and applies across every version of the document.
+     *
+     * Source-locale enforcement and `ERR_PATH_CONFLICT` mapping live in the
+     * lifecycle service that calls this; the command itself only performs the
+     * upsert (and surfaces the raw `23505` for the service to translate).
+     */
+    updateDocumentPath(params: {
+        documentId: string;
+        collectionId: string;
+        locale: string;
+        path: string;
+    }): Promise<void>;
+    /**
+     * setDocumentAvailableLocales
+     *
+     * Standalone, non-versioned write of a document's editorial advertised-locale
+     * set. Backs the admin available-locales widget's direct-write Save path: it
+     * replaces `byline_document_available_locales` wholesale (document-grain)
+     * **without** minting a new document version or touching workflow status. The
+     * change is immediate and applies across every version of the document; the
+     * public advertised set remains the intersection with the resolved version's
+     * completeness ledger. See docs/I18N.md.
+     */
+    setDocumentAvailableLocales(params: {
+        documentId: string;
+        collectionId: string;
+        availableLocales: string[];
+    }): Promise<void>;
     /**
      * writeVersionLocaleLedger
      *

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

@@ -123,21 +123,11 @@ export class DocumentCommands {
             // (collection_id, locale, path) bubble up as a Postgres error which the
             // lifecycle wraps as ERR_PATH_CONFLICT.
             if (params.path !== undefined) {
-                await tx
-                    .insert(documentPaths)
-                    .values({
-                    document_id: documentId,
+                await this.writeDocumentPath(tx, {
+                    documentId,
                     locale: sourceLocale,
-                    collection_id: params.collectionId,
+                    collectionId: params.collectionId,
                     path: params.path,
-                })
-                    .onConflictDoUpdate({
-                    target: [documentPaths.document_id, documentPaths.locale],
-                    set: {
-                        path: params.path,
-                        collection_id: params.collectionId,
-                        updated_at: new Date(),
-                    },
                 });
             }
             // 2b. Replace the document_available_locales rows when an editorial set
@@ -147,17 +137,11 @@ export class DocumentCommands {
             // included — replaces it wholesale. Deduplicated so a caller-supplied
             // duplicate doesn't collide on the (document_id, locale) primary key.
             if (params.availableLocales !== undefined) {
-                await tx
-                    .delete(documentAvailableLocales)
-                    .where(eq(documentAvailableLocales.document_id, documentId));
-                const locales = [...new Set(params.availableLocales)];
-                if (locales.length > 0) {
-                    await tx.insert(documentAvailableLocales).values(locales.map((locale) => ({
-                        document_id: documentId,
-                        locale,
-                        collection_id: params.collectionId,
-                    })));
-                }
+                await this.writeDocumentAvailableLocales(tx, {
+                    documentId,
+                    collectionId: params.collectionId,
+                    availableLocales: params.availableLocales,
+                });
             }
             // 3. Flatten the document data to field values
             const flattenedFields = flattenFieldSetData(params.collectionConfig.fields, params.documentData, params.locale ?? 'all');
@@ -279,6 +263,103 @@ export class DocumentCommands {
             };
         });
     }
+    /**
+     * writeDocumentPath
+     *
+     * Upsert the `byline_document_paths` row for a (document, locale) pair. The
+     * path row is document-grain and sticky across versions — it lives under the
+     * document's `source_locale` (its data anchor), not the mutable global
+     * default. Shared by `createDocumentVersion` (step 2a, create write path) and
+     * the standalone `updateDocumentPath` command (the non-versioned admin path
+     * widget write). The unique constraint on `(collection_id, locale, path)` may
+     * raise a `23505`, which the lifecycle layer maps to `ERR_PATH_CONFLICT`.
+     */
+    async writeDocumentPath(tx, args) {
+        await tx
+            .insert(documentPaths)
+            .values({
+            document_id: args.documentId,
+            locale: args.locale,
+            collection_id: args.collectionId,
+            path: args.path,
+        })
+            .onConflictDoUpdate({
+            target: [documentPaths.document_id, documentPaths.locale],
+            set: {
+                path: args.path,
+                collection_id: args.collectionId,
+                updated_at: new Date(),
+            },
+        });
+    }
+    /**
+     * writeDocumentAvailableLocales
+     *
+     * Replace a document's `byline_document_available_locales` rows wholesale —
+     * the editorial advertised-locale set. Document-grain and sticky across
+     * versions: `delete`-then-`insert`, deduplicated so a caller-supplied
+     * duplicate doesn't collide on the `(document_id, locale)` primary key. An
+     * empty array clears the set (advertise nothing). Shared by
+     * `createDocumentVersion` (step 2b, create write path) and the standalone
+     * `setDocumentAvailableLocales` command (the non-versioned admin
+     * available-locales widget write). See docs/I18N.md.
+     */
+    async writeDocumentAvailableLocales(tx, args) {
+        await tx
+            .delete(documentAvailableLocales)
+            .where(eq(documentAvailableLocales.document_id, args.documentId));
+        const locales = [...new Set(args.availableLocales)];
+        if (locales.length > 0) {
+            await tx.insert(documentAvailableLocales).values(locales.map((locale) => ({
+                document_id: args.documentId,
+                locale,
+                collection_id: args.collectionId,
+            })));
+        }
+    }
+    /**
+     * updateDocumentPath
+     *
+     * Standalone, non-versioned write of a document's URL path. Backs the admin
+     * path widget's direct-write Save path: it edits `byline_document_paths`
+     * in-place (document-grain, sticky) **without** minting a new document
+     * version or touching workflow status. The path's document-grain nature means
+     * the change is immediate and applies across every version of the document.
+     *
+     * Source-locale enforcement and `ERR_PATH_CONFLICT` mapping live in the
+     * lifecycle service that calls this; the command itself only performs the
+     * upsert (and surfaces the raw `23505` for the service to translate).
+     */
+    async updateDocumentPath(params) {
+        await this.db.transaction(async (tx) => {
+            await this.writeDocumentPath(tx, {
+                documentId: params.documentId,
+                locale: params.locale,
+                collectionId: params.collectionId,
+                path: params.path,
+            });
+        });
+    }
+    /**
+     * setDocumentAvailableLocales
+     *
+     * Standalone, non-versioned write of a document's editorial advertised-locale
+     * set. Backs the admin available-locales widget's direct-write Save path: it
+     * replaces `byline_document_available_locales` wholesale (document-grain)
+     * **without** minting a new document version or touching workflow status. The
+     * change is immediate and applies across every version of the document; the
+     * public advertised set remains the intersection with the resolved version's
+     * completeness ledger. See docs/I18N.md.
+     */
+    async setDocumentAvailableLocales(params) {
+        await this.db.transaction(async (tx) => {
+            await this.writeDocumentAvailableLocales(tx, {
+                documentId: params.documentId,
+                collectionId: params.collectionId,
+                availableLocales: params.availableLocales,
+            });
+        });
+    }
     /**
      * writeVersionLocaleLedger
      *

package/dist/modules/storage/tests/storage-system-fields-direct-write.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/storage/tests/storage-system-fields-direct-write.test.js

@@ -0,0 +1,151 @@
+/**
+ * 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 { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+let commandBuilders;
+let queryBuilders;
+const timestamp = Date.now();
+const DirectWriteCollectionConfig = {
+    path: `direct-write-${timestamp}`,
+    labels: { singular: 'DirectWriteTest', plural: 'DirectWriteTests' },
+    useAsPath: 'title',
+    fields: [{ name: 'title', type: 'text', localized: true }],
+};
+let testCollection = {};
+function readById(documentId) {
+    return queryBuilders.documents.getDocumentById({
+        collection_id: testCollection.id,
+        document_id: documentId,
+    });
+}
+describe('non-versioned system-field commands (direct write)', () => {
+    beforeAll(async () => {
+        const testDB = setupTestDB([DirectWriteCollectionConfig]);
+        commandBuilders = testDB.commandBuilders;
+        queryBuilders = testDB.queryBuilders;
+        const result = await commandBuilders.collections.create(DirectWriteCollectionConfig.path, DirectWriteCollectionConfig);
+        const collection = result[0];
+        if (collection == null) {
+            throw new Error('Failed to create test collection');
+        }
+        testCollection = { id: collection.id, name: collection.path };
+    });
+    afterAll(async () => {
+        try {
+            await commandBuilders.collections.delete(testCollection.id);
+        }
+        catch (error) {
+            console.error('Failed to cleanup test collection:', error);
+        }
+        await teardownTestDB();
+    });
+    it('setDocumentAvailableLocales writes the set without a new version or status change', async () => {
+        const created = await commandBuilders.documents.createDocumentVersion({
+            collectionId: testCollection.id,
+            collectionVersion: 1,
+            collectionConfig: DirectWriteCollectionConfig,
+            action: 'create',
+            documentData: { title: 'Advertise direct' },
+            path: 'advertise-direct',
+            availableLocales: ['en'],
+            locale: 'all',
+            status: 'published',
+        });
+        const documentId = created.document.document_id;
+        const before = await readById(documentId);
+        expect(before?.availableLocales).toEqual(['en']);
+        await commandBuilders.documents.setDocumentAvailableLocales({
+            documentId,
+            collectionId: testCollection.id,
+            availableLocales: ['en', 'fr'],
+        });
+        const after = await readById(documentId);
+        expect(after?.availableLocales, 'set rewritten').toEqual(['en', 'fr']);
+        expect(after?.document_version_id, 'no new version minted').toBe(before?.document_version_id);
+        expect(after?.status, 'status not reset to draft').toBe('published');
+    });
+    it('setDocumentAvailableLocales clears the set with an empty array, still no new version', async () => {
+        const created = await commandBuilders.documents.createDocumentVersion({
+            collectionId: testCollection.id,
+            collectionVersion: 1,
+            collectionConfig: DirectWriteCollectionConfig,
+            action: 'create',
+            documentData: { title: 'Advertise clear' },
+            path: 'advertise-clear',
+            availableLocales: ['en', 'fr'],
+            locale: 'all',
+            status: 'published',
+        });
+        const documentId = created.document.document_id;
+        const before = await readById(documentId);
+        await commandBuilders.documents.setDocumentAvailableLocales({
+            documentId,
+            collectionId: testCollection.id,
+            availableLocales: [],
+        });
+        const after = await readById(documentId);
+        expect(after?.availableLocales).toEqual([]);
+        expect(after?.document_version_id).toBe(before?.document_version_id);
+        expect(after?.status).toBe('published');
+    });
+    it('updateDocumentPath writes the path without a new version or status change', async () => {
+        const created = await commandBuilders.documents.createDocumentVersion({
+            collectionId: testCollection.id,
+            collectionVersion: 1,
+            collectionConfig: DirectWriteCollectionConfig,
+            action: 'create',
+            documentData: { title: 'Path direct' },
+            path: 'path-before',
+            locale: 'all',
+            status: 'published',
+        });
+        const documentId = created.document.document_id;
+        const before = await readById(documentId);
+        expect(before?.path).toBe('path-before');
+        await commandBuilders.documents.updateDocumentPath({
+            documentId,
+            collectionId: testCollection.id,
+            locale: 'en',
+            path: 'path-after',
+        });
+        const after = await readById(documentId);
+        expect(after?.path, 'path rewritten').toBe('path-after');
+        expect(after?.document_version_id, 'no new version minted').toBe(before?.document_version_id);
+        expect(after?.status, 'status not reset to draft').toBe('published');
+    });
+    it('updateDocumentPath raises on a colliding path (unique constraint)', async () => {
+        const a = await commandBuilders.documents.createDocumentVersion({
+            collectionId: testCollection.id,
+            collectionVersion: 1,
+            collectionConfig: DirectWriteCollectionConfig,
+            action: 'create',
+            documentData: { title: 'Collision A' },
+            path: 'collision-taken',
+            locale: 'all',
+            status: 'published',
+        });
+        const b = await commandBuilders.documents.createDocumentVersion({
+            collectionId: testCollection.id,
+            collectionVersion: 1,
+            collectionConfig: DirectWriteCollectionConfig,
+            action: 'create',
+            documentData: { title: 'Collision B' },
+            path: 'collision-free',
+            locale: 'all',
+            status: 'published',
+        });
+        expect(a.document.document_id).toBeTruthy();
+        await expect(commandBuilders.documents.updateDocumentPath({
+            documentId: b.document.document_id,
+            collectionId: testCollection.id,
+            locale: 'en',
+            // Same (collection, locale) path as document A — must collide.
+            path: 'collision-taken',
+        })).rejects.toThrow();
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/core": "3.2.0",
-    "@byline/admin": "3.2.0",
-    "@byline/auth": "3.2.0"
+    "@byline/admin": "3.3.0",
+    "@byline/auth": "3.3.0",
+    "@byline/core": "3.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",