@byline/db-postgres 3.0.1 → 3.1.0

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

@@ -152,8 +152,43 @@ export declare class DocumentCommands implements IDocumentCommands {
      * version is assumed fresh (no rows), so no conflict handling is needed.
      * Used by `reAnchorDocument` to snapshot the current version into the new
      * re-anchored one without re-flattening (lossless, identity-preserving).
+     *
+     * When `excludeLocale` is provided, rows for that locale are skipped in the
+     * seven value-store tables — the carry-forward that powers `deleteDocumentLocale`
+     * (drop one locale's content, keep `'all'` + every other locale). The
+     * locale-agnostic `byline_store_meta` rows (block / array-item identities) are
+     * always copied wholesale, since a block's identity is shared across locales.
      */
     private copyAllVersionStoreRows;
+    /**
+     * deleteDocumentLocale
+     *
+     * Remove one content locale's data from a document by writing a **new
+     * immutable version** that carries forward every store row except the
+     * target locale's (the `'all'` rows and all other locales are kept). The
+     * prior version still holds the deleted locale, so the operation is
+     * recoverable via version restore, and a previously-published version keeps
+     * serving until the new version is published.
+     *
+     * The new version's status is supplied by the caller (the lifecycle service
+     * passes the workflow's default — a fresh draft, matching `copyToLocale`).
+     * The derived availability ledger is recomputed from the carried-forward
+     * rows, so the deleted locale drops out automatically. The default content
+     * locale (the document's anchor) must never be passed here — the lifecycle
+     * service enforces that.
+     *
+     * Mirrors `reAnchorDocument`'s new-version mechanics; defensively returns
+     * `null` when the document has no current version (the service validates
+     * existence first, so this is a guard).
+     */
+    deleteDocumentLocale(params: {
+        documentId: string;
+        locale: string;
+        status?: string;
+    }): Promise<{
+        newVersionId: string;
+        previousVersionId: string;
+    } | null>;
     /**
      * reAnchorDocument
      *

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

@@ -332,51 +332,61 @@ export class DocumentCommands {
      * version is assumed fresh (no rows), so no conflict handling is needed.
      * Used by `reAnchorDocument` to snapshot the current version into the new
      * re-anchored one without re-flattening (lossless, identity-preserving).
+     *
+     * When `excludeLocale` is provided, rows for that locale are skipped in the
+     * seven value-store tables — the carry-forward that powers `deleteDocumentLocale`
+     * (drop one locale's content, keep `'all'` + every other locale). The
+     * locale-agnostic `byline_store_meta` rows (block / array-item identities) are
+     * always copied wholesale, since a block's identity is shared across locales.
      */
-    async copyAllVersionStoreRows(tx, fromVersionId, toVersionId) {
+    async copyAllVersionStoreRows(tx, fromVersionId, toVersionId, excludeLocale) {
         const from = sql `${fromVersionId}::uuid`;
         const to = sql `${toVersionId}::uuid`;
+        // Appended to each value-store WHERE so the dropped locale's rows are not
+        // carried into the new version. Empty fragment (copy everything) when no
+        // exclusion is requested — the `reAnchorDocument` snapshot path.
+        const localeFilter = excludeLocale ? sql ` AND locale <> ${excludeLocale}` : sql ``;
         await tx.execute(sql `
       INSERT INTO byline_store_text
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, value, word_count, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, value, word_count, NOW(), NOW()
-      FROM byline_store_text WHERE document_version_id = ${from}
+      FROM byline_store_text WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_numeric
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, number_type, value_integer, value_decimal, value_float, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, number_type, value_integer, value_decimal, value_float, NOW(), NOW()
-      FROM byline_store_numeric WHERE document_version_id = ${from}
+      FROM byline_store_numeric WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_boolean
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, value, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, value, NOW(), NOW()
-      FROM byline_store_boolean WHERE document_version_id = ${from}
+      FROM byline_store_boolean WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_datetime
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, date_type, value_date, value_time, value_timestamp_tz, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, date_type, value_date, value_time, value_timestamp_tz, NOW(), NOW()
-      FROM byline_store_datetime WHERE document_version_id = ${from}
+      FROM byline_store_datetime WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_json
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, value, json_schema, object_keys, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, value, json_schema, object_keys, NOW(), NOW()
-      FROM byline_store_json WHERE document_version_id = ${from}
+      FROM byline_store_json WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_relation
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, target_document_id, target_collection_id, relationship_type, cascade_delete, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, target_document_id, target_collection_id, relationship_type, cascade_delete, NOW(), NOW()
-      FROM byline_store_relation WHERE document_version_id = ${from}
+      FROM byline_store_relation WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_file
         (id, document_version_id, collection_id, field_path, field_name, locale, parent_path, file_id, filename, original_filename, mime_type, file_size, file_hash, storage_provider, storage_path, storage_url, image_width, image_height, image_format, processing_status, thumbnail_generated, created_at, updated_at)
       SELECT gen_random_uuid(), ${to}, collection_id, field_path, field_name, locale, parent_path, file_id, filename, original_filename, mime_type, file_size, file_hash, storage_provider, storage_path, storage_url, image_width, image_height, image_format, processing_status, thumbnail_generated, NOW(), NOW()
-      FROM byline_store_file WHERE document_version_id = ${from}
+      FROM byline_store_file WHERE document_version_id = ${from}${localeFilter}
     `);
         await tx.execute(sql `
       INSERT INTO byline_store_meta
@@ -385,6 +395,67 @@ export class DocumentCommands {
       FROM byline_store_meta WHERE document_version_id = ${from}
     `);
     }
+    /**
+     * deleteDocumentLocale
+     *
+     * Remove one content locale's data from a document by writing a **new
+     * immutable version** that carries forward every store row except the
+     * target locale's (the `'all'` rows and all other locales are kept). The
+     * prior version still holds the deleted locale, so the operation is
+     * recoverable via version restore, and a previously-published version keeps
+     * serving until the new version is published.
+     *
+     * The new version's status is supplied by the caller (the lifecycle service
+     * passes the workflow's default — a fresh draft, matching `copyToLocale`).
+     * The derived availability ledger is recomputed from the carried-forward
+     * rows, so the deleted locale drops out automatically. The default content
+     * locale (the document's anchor) must never be passed here — the lifecycle
+     * service enforces that.
+     *
+     * Mirrors `reAnchorDocument`'s new-version mechanics; defensively returns
+     * `null` when the document has no current version (the service validates
+     * existence first, so this is a guard).
+     */
+    async deleteDocumentLocale(params) {
+        const { documentId, locale, status } = params;
+        return this.db.transaction(async (tx) => {
+            // 1. Current (latest, non-deleted) version + the document's anchor.
+            const current = await tx
+                .select({
+                versionId: documentVersions.id,
+                collectionId: documentVersions.collection_id,
+                collectionVersion: documentVersions.collection_version,
+                sourceLocale: documents.source_locale,
+            })
+                .from(documentVersions)
+                .innerJoin(documents, eq(documents.id, documentVersions.document_id))
+                .where(and(eq(documentVersions.document_id, documentId), eq(documentVersions.is_deleted, false)))
+                .orderBy(desc(documentVersions.id))
+                .limit(1)
+                .then((rows) => rows[0]);
+            if (current == null)
+                return null;
+            const sourceLocale = current.sourceLocale ?? this.defaultContentLocale;
+            // 2. New immutable version: a snapshot of the current version with the
+            //    target locale's value rows dropped (meta + 'all' + other locales
+            //    carried forward).
+            const newVersionId = uuidv7();
+            await tx.insert(documentVersions).values({
+                id: newVersionId,
+                document_id: documentId,
+                collection_id: current.collectionId,
+                collection_version: current.collectionVersion,
+                event_type: 'delete_locale',
+                status: status ?? 'draft',
+                change_summary: `deleted content locale ${locale}`,
+            });
+            await this.copyAllVersionStoreRows(tx, current.versionId, newVersionId, locale);
+            // 3. Recompute the new version's availability ledger against the source
+            //    locale — the dropped locale no longer covers it, so it falls out.
+            await this.writeVersionLocaleLedger(tx, newVersionId, sourceLocale);
+            return { newVersionId, previousVersionId: current.versionId };
+        });
+    }
     /**
      * reAnchorDocument
      *

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

@@ -216,6 +216,20 @@ export declare class DocumentQueries implements IDocumentQueries {
         created_at: Date;
         updated_at: Date;
     } | null>;
+    /**
+     * getCurrentPath — resolve a document's canonical (source-locale) path.
+     *
+     * Reuses `pathProjection` against `current_documents`, passing
+     * `requestedLocale: undefined` so the projection's fallback floor — the
+     * document's own `source_locale` (COALESCE-guarded to the default content
+     * locale for not-yet-anchored rows) — supplies the canonical path. Used by
+     * the lifecycle to populate `path` on the status-change / unpublish hook
+     * contexts. Returns `null` when no path row (or document) exists.
+     */
+    getCurrentPath({ collection_id, document_id, }: {
+        collection_id: string;
+        document_id: string;
+    }): Promise<string | null>;
     /**
      * getDocumentById — gets the current version of a document by its logical document ID.
      *

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

@@ -439,6 +439,26 @@ export class DocumentQueries {
             updated_at: row.updated_at ?? new Date(),
         };
     }
+    /**
+     * getCurrentPath — resolve a document's canonical (source-locale) path.
+     *
+     * Reuses `pathProjection` against `current_documents`, passing
+     * `requestedLocale: undefined` so the projection's fallback floor — the
+     * document's own `source_locale` (COALESCE-guarded to the default content
+     * locale for not-yet-anchored rows) — supplies the canonical path. Used by
+     * the lifecycle to populate `path` on the status-change / unpublish hook
+     * contexts. Returns `null` when no path row (or document) exists.
+     */
+    async getCurrentPath({ collection_id, document_id, }) {
+        const [row] = await this.db
+            .select({
+            path: this.pathProjection(sql `${currentDocumentsView.document_id}`, undefined, sql `${currentDocumentsView.source_locale}`),
+        })
+            .from(currentDocumentsView)
+            .where(and(eq(currentDocumentsView.collection_id, collection_id), eq(currentDocumentsView.document_id, document_id)))
+            .limit(1);
+        return row?.path ?? null;
+    }
     /**
      * getDocumentById — gets the current version of a document by its logical document ID.
      *

package/dist/modules/storage/tests/storage-delete-locale.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-delete-locale.test.js

@@ -0,0 +1,155 @@
+/**
+ * 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 DeleteLocaleCollectionConfig = {
+    path: `delete-locale-${timestamp}`,
+    labels: { singular: 'DeleteLocaleTest', plural: 'DeleteLocaleTests' },
+    fields: [
+        { name: 'title', type: 'text', localized: true },
+        // Non-localized → lives on `locale: 'all'` rows; must survive the delete.
+        { name: 'sku', type: 'text' },
+    ],
+};
+let testCollection = {};
+function readById(documentId, locale) {
+    return queryBuilders.documents.getDocumentById({
+        collection_id: testCollection.id,
+        document_id: documentId,
+        locale,
+    });
+}
+/**
+ * Create a fresh document with three localized titles (en/fr/de) and one
+ * shared non-localized field, returning the document id and the current
+ * (latest) version id.
+ */
+async function seedTrilingualDoc(titlePrefix) {
+    const v1 = await commandBuilders.documents.createDocumentVersion({
+        collectionId: testCollection.id,
+        collectionVersion: 1,
+        collectionConfig: DeleteLocaleCollectionConfig,
+        action: 'create',
+        documentData: { title: `${titlePrefix} EN`, sku: 'SKU-1' },
+        locale: 'en',
+        status: 'published',
+    });
+    const documentId = v1.document.document_id;
+    const v2 = await commandBuilders.documents.createDocumentVersion({
+        documentId,
+        collectionId: testCollection.id,
+        collectionVersion: 1,
+        collectionConfig: DeleteLocaleCollectionConfig,
+        action: 'update',
+        documentData: { title: `${titlePrefix} FR`, sku: 'SKU-1' },
+        locale: 'fr',
+        status: 'published',
+        previousVersionId: v1.document.id,
+    });
+    const v3 = await commandBuilders.documents.createDocumentVersion({
+        documentId,
+        collectionId: testCollection.id,
+        collectionVersion: 1,
+        collectionConfig: DeleteLocaleCollectionConfig,
+        action: 'update',
+        documentData: { title: `${titlePrefix} DE`, sku: 'SKU-1' },
+        locale: 'de',
+        status: 'published',
+        previousVersionId: v2.document.id,
+    });
+    return { documentId, currentVersionId: v3.document.id };
+}
+describe('deleteDocumentLocale integration', () => {
+    beforeAll(async () => {
+        const testDB = setupTestDB([DeleteLocaleCollectionConfig]);
+        commandBuilders = testDB.commandBuilders;
+        queryBuilders = testDB.queryBuilders;
+        const result = await commandBuilders.collections.create(DeleteLocaleCollectionConfig.path, DeleteLocaleCollectionConfig);
+        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('drops the target locale from availability, keeps the others', async () => {
+        const { documentId } = await seedTrilingualDoc('Avail');
+        const before = await readById(documentId, 'en');
+        expect(before?._availableVersionLocales, 'all three locales present').toEqual([
+            'de',
+            'en',
+            'fr',
+        ]);
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        const after = await readById(documentId, 'en');
+        expect(after?._availableVersionLocales, 'fr removed, de/en remain').toEqual(['de', 'en']);
+    });
+    it("keeps other locales' localized content and the shared non-localized field", async () => {
+        const { documentId } = await seedTrilingualDoc('Content');
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        const de = await readById(documentId, 'de');
+        expect(de?.fields.title, 'de content untouched').toBe('Content DE');
+        expect(de?.fields.sku, "non-localized 'all' field preserved").toBe('SKU-1');
+        const en = await readById(documentId, 'en');
+        expect(en?.fields.title, 'default-locale content untouched').toBe('Content EN');
+    });
+    it('lands the new version with the supplied status (a fresh draft)', async () => {
+        const { documentId } = await seedTrilingualDoc('Status');
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        const meta = await queryBuilders.documents.getCurrentVersionMetadata({
+            collection_id: testCollection.id,
+            document_id: documentId,
+        });
+        expect(meta?.status, 'delete-locale version is a draft').toBe('draft');
+    });
+    it('is recoverable — the prior version still holds the deleted locale', async () => {
+        const { documentId, currentVersionId } = await seedTrilingualDoc('Recover');
+        await commandBuilders.documents.deleteDocumentLocale({
+            documentId,
+            locale: 'fr',
+            status: 'draft',
+        });
+        // The pre-delete version is immutable and still carries the fr content.
+        const prior = (await queryBuilders.documents.getDocumentByVersion({
+            document_version_id: currentVersionId,
+            locale: 'fr',
+        }));
+        expect(prior?.fields.title, 'fr content survives in the prior version').toBe('Recover FR');
+    });
+    it('returns null for an unknown document', async () => {
+        const result = await commandBuilders.documents.deleteDocumentLocale({
+            documentId: crypto.randomUUID(),
+            locale: 'fr',
+            status: 'draft',
+        });
+        expect(result).toBeNull();
+    });
+});

package/dist/modules/storage/tests/storage-document-paths.test.js

@@ -181,4 +181,81 @@ describe('byline_document_paths integration', () => {
         });
         expect(result).toBe(null);
     });
+    describe('getCurrentPath', () => {
+        it('resolves a document’s canonical path under its default source locale', async () => {
+            const canonicalPath = `current-path-${Date.now()}`;
+            const created = await commandBuilders.documents.createDocumentVersion({
+                collectionId: testCollection.id,
+                collectionVersion: 1,
+                collectionConfig: PathsCollectionConfig,
+                action: 'create',
+                documentData: { title: 'Has Path' },
+                path: canonicalPath,
+                locale: 'all',
+                status: 'draft',
+            });
+            const documentId = created.document.document_id;
+            const path = await queryBuilders.documents.getCurrentPath({
+                collection_id: testCollection.id,
+                document_id: documentId,
+            });
+            expect(path).toBe(canonicalPath);
+        });
+        it('follows the source-locale anchor after a document is re-anchored', async () => {
+            const canonicalPath = `reanchor-path-${Date.now()}`;
+            // Create locale-agnostic content (ledger carries the 'all' sentinel) so
+            // the document is "complete" in any target and re-anchoring is eligible.
+            const created = await commandBuilders.documents.createDocumentVersion({
+                collectionId: testCollection.id,
+                collectionVersion: 1,
+                collectionConfig: PathsCollectionConfig,
+                action: 'create',
+                documentData: { title: 'Re-anchor me' },
+                path: canonicalPath,
+                locale: 'all',
+                status: 'draft',
+            });
+            const documentId = created.document.document_id;
+            // Flip the document's source locale from the default ('en') to 'fr'.
+            // reAnchorDocument moves the path row onto the new source locale,
+            // keeping the slug. getCurrentPath passes requestedLocale: undefined, so
+            // its fallback floor is COALESCE(source_locale, default) — it must now
+            // resolve via the 'fr' anchor, not the global default 'en'.
+            const result = await commandBuilders.documents.reAnchorDocument({
+                documentId,
+                targetLocale: 'fr',
+            });
+            expect(result.status).toBe('reanchored');
+            const path = await queryBuilders.documents.getCurrentPath({
+                collection_id: testCollection.id,
+                document_id: documentId,
+            });
+            expect(path).toBe(canonicalPath);
+        });
+        it('returns null when the document has no path row', async () => {
+            // Create a version without a `path` — no document_paths row is written.
+            const created = await commandBuilders.documents.createDocumentVersion({
+                collectionId: testCollection.id,
+                collectionVersion: 1,
+                collectionConfig: PathsCollectionConfig,
+                action: 'create',
+                documentData: { title: 'No Path' },
+                locale: 'all',
+                status: 'draft',
+            });
+            const documentId = created.document.document_id;
+            const path = await queryBuilders.documents.getCurrentPath({
+                collection_id: testCollection.id,
+                document_id: documentId,
+            });
+            expect(path).toBe(null);
+        });
+        it('returns null for a non-existent document', async () => {
+            const path = await queryBuilders.documents.getCurrentPath({
+                collection_id: testCollection.id,
+                document_id: crypto.randomUUID(),
+            });
+            expect(path).toBe(null);
+        });
+    });
 });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.0.1",
+  "version": "3.1.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.0.1",
-    "@byline/auth": "3.0.1",
-    "@byline/admin": "3.0.1"
+    "@byline/core": "3.1.0",
+    "@byline/auth": "3.1.0",
+    "@byline/admin": "3.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",