@byline/core 1.7.7 → 1.8.0

package/dist/@types/db-types.d.ts

@@ -207,7 +207,15 @@ export interface IDocumentCommands {
         collectionConfig: CollectionDefinition;
         action: string;
         documentData: any;
-        path: string;
+        /**
+         * Optional. When provided, the adapter upserts a row into
+         * `byline_document_paths` keyed by `(document_id, defaultContentLocale)`.
+         * When omitted, no path write occurs — the lifecycle uses this to
+         * skip path writes during translation (non-default-locale) saves.
+         * The unique constraint on `(collection_id, locale, path)` may
+         * surface as `ERR_PATH_CONFLICT` from the lifecycle layer.
+         */
+        path?: string;
         locale?: string;
         status?: string;
         createdBy?: string;

package/dist/lib/errors.d.ts

@@ -85,6 +85,7 @@ export declare const ErrorCodes: {
     readonly DATABASE: "ERR_DATABASE";
     readonly STORAGE: "ERR_STORAGE";
     readonly READ_BUDGET_EXCEEDED: "ERR_READ_BUDGET_EXCEEDED";
+    readonly PATH_CONFLICT: "ERR_PATH_CONFLICT";
 };
 export declare const ERR_UNHANDLED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_NOT_FOUND: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
@@ -95,3 +96,10 @@ export declare const ERR_PATCH_FAILED: (opts: BylineErrorOptions, errorConstruct
 export declare const ERR_DATABASE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_STORAGE: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
 export declare const ERR_READ_BUDGET_EXCEEDED: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;
+/**
+ * Thrown when a write attempts to set `path` to a value already used by
+ * another document in the same `(collection, locale)` scope. Surfaces the
+ * underlying Postgres unique-constraint violation on
+ * `byline_document_paths(collection_id, locale, path)`.
+ */
+export declare const ERR_PATH_CONFLICT: (opts: BylineErrorOptions, errorConstructor?: any) => BylineError;

package/dist/lib/errors.js

@@ -118,6 +118,7 @@ export const ErrorCodes = {
     DATABASE: 'ERR_DATABASE',
     STORAGE: 'ERR_STORAGE',
     READ_BUDGET_EXCEEDED: 'ERR_READ_BUDGET_EXCEEDED',
+    PATH_CONFLICT: 'ERR_PATH_CONFLICT',
 };
 // ---------------------------------------------------------------------------
 // Pre-instantiated factories
@@ -131,3 +132,10 @@ export const ERR_PATCH_FAILED = createErrorType(ErrorCodes.PATCH_FAILED);
 export const ERR_DATABASE = createErrorType(ErrorCodes.DATABASE);
 export const ERR_STORAGE = createErrorType(ErrorCodes.STORAGE);
 export const ERR_READ_BUDGET_EXCEEDED = createErrorType(ErrorCodes.READ_BUDGET_EXCEEDED);
+/**
+ * Thrown when a write attempts to set `path` to a value already used by
+ * another document in the same `(collection, locale)` scope. Surfaces the
+ * underlying Postgres unique-constraint violation on
+ * `byline_document_paths(collection_id, locale, path)`.
+ */
+export const ERR_PATH_CONFLICT = createErrorType(ErrorCodes.PATH_CONFLICT, 'warn');

package/dist/services/document-lifecycle.js

@@ -7,7 +7,7 @@
  */
 import { normalizeCollectionHook, } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
-import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_VALIDATION, } from '../lib/errors.js';
+import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
 import { applyPatches } from '../patches/index.js';
 import { normaliseDateFields } from '../utils/normalise-dates.js';
@@ -32,6 +32,65 @@ async function invokeHook(hook, ctx) {
 function extractVersionId(document) {
     return document?.id ?? document?.document_version_id ?? '';
 }
+/**
+ * Detect a Postgres unique-constraint violation on
+ * `byline_document_paths(collection_id, locale, path)` and translate it
+ * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
+ *
+ * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
+ * the constraint name on the error object (`constraint`); matching by
+ * name keeps this targeted to the path constraint and avoids spuriously
+ * rebranding unrelated unique violations as path conflicts.
+ *
+ * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
+ * original attached as `cause`, so we walk a short cause chain to find
+ * the carried `code` / `constraint`.
+ */
+function rethrowPathConflict(err, path, locale) {
+    let e = err;
+    // Walk at most a few `cause` hops — DrizzleQueryError → underlying pg error.
+    for (let i = 0; i < 3 && e; i++) {
+        if (e.code === '23505' &&
+            typeof e.constraint === 'string' &&
+            e.constraint.includes('document_paths_collection_locale_path')) {
+            throw ERR_PATH_CONFLICT({
+                message: `path "${path}" is already in use in this collection (locale: ${locale})`,
+                details: { path, locale, constraint: e.constraint },
+            });
+        }
+        e = e.cause;
+    }
+    throw err;
+}
+/**
+ * Resolve the path argument the storage primitive should receive on an
+ * update operation. Phase 1 only writes path rows under the default
+ * content locale; on translation saves a supplied path is dropped with
+ * a `logger.warn`, leaving the existing default-locale row untouched.
+ *
+ * Returns `undefined` to signal the storage primitive should skip the
+ * path write entirely (no upsert).
+ */
+function resolvePathForUpdate(args) {
+    const { explicitPath, currentPath, requestLocale, defaultLocale, documentId, logger } = args;
+    if (requestLocale === defaultLocale) {
+        // Default-locale write: pass path through when supplied; otherwise
+        // skip the write (existing path row stays as-is — sticky).
+        return explicitPath ?? undefined;
+    }
+    // Non-default-locale write: reject any path change with a warn so the
+    // operation succeeds but the editor / API caller is informed.
+    if (explicitPath !== null && explicitPath !== currentPath) {
+        logger?.warn({
+            documentId,
+            requestedLocale: requestLocale,
+            defaultLocale,
+            suppliedPath: explicitPath,
+            currentPath,
+        }, 'path changes apply only on default-locale writes; ignored on translation save');
+    }
+    return undefined;
+}
 /** Extract the logical document id from the document object returned by `createDocumentVersion`. */
 function extractDocumentId(document) {
     return document?.document_id ?? '';
@@ -97,7 +156,8 @@ export async function createDocument(ctx, params) {
         await invokeHook(hooks?.beforeCreate, { data, collectionPath });
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
         const resolvedPath = explicitPath ?? derivePath(definition, data, defaultLocale, slugifier);
-        const result = await db.commands.documents.createDocumentVersion({
+        const result = await db.commands.documents
+            .createDocumentVersion({
             collectionId,
             collectionVersion: ctx.collectionVersion,
             collectionConfig: definition,
@@ -106,7 +166,8 @@ export async function createDocument(ctx, params) {
             path: resolvedPath,
             status: params.status ?? data.status,
             locale: params.locale ?? defaultLocale,
-        });
+        })
+            .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
         const documentId = extractDocumentId(result.document);
         const documentVersionId = extractVersionId(result.document);
         await invokeHook(hooks?.afterCreate, {
@@ -150,19 +211,29 @@ export async function updateDocument(ctx, params) {
         await invokeHook(hooks?.beforeUpdate, { data, originalData, collectionPath });
         const defaultStatus = getDefaultStatus(definition);
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const resolvedPath = explicitPath ?? originalData.path ?? crypto.randomUUID();
-        const result = await db.commands.documents.createDocumentVersion({
+        const requestLocale = params.locale ?? defaultLocale;
+        const pathForCommand = resolvePathForUpdate({
+            explicitPath,
+            currentPath: originalData.path,
+            requestLocale,
+            defaultLocale,
+            documentId: params.documentId,
+            logger: ctx.logger,
+        });
+        const result = await db.commands.documents
+            .createDocumentVersion({
             documentId: params.documentId,
             collectionId,
             collectionVersion: ctx.collectionVersion,
             collectionConfig: definition,
             action: 'update',
             documentData: data,
-            path: resolvedPath,
+            path: pathForCommand,
             status: defaultStatus,
-            locale: params.locale ?? defaultLocale,
+            locale: requestLocale,
             previousVersionId: originalData.document_version_id,
-        });
+        })
+            .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         await invokeHook(hooks?.afterUpdate, {
@@ -236,19 +307,29 @@ export async function updateDocumentWithPatches(ctx, params) {
         // 6. Persist.
         const defaultStatus = getDefaultStatus(definition);
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
-        const resolvedPath = explicitPath ?? originalData.path ?? crypto.randomUUID();
-        const result = await db.commands.documents.createDocumentVersion({
+        const requestLocale = params.locale ?? defaultLocale;
+        const pathForCommand = resolvePathForUpdate({
+            explicitPath,
+            currentPath: originalData.path,
+            requestLocale,
+            defaultLocale,
+            documentId: params.documentId,
+            logger: ctx.logger,
+        });
+        const result = await db.commands.documents
+            .createDocumentVersion({
             documentId: params.documentId,
             collectionId,
             collectionVersion: ctx.collectionVersion,
             collectionConfig: definition,
             action: 'update',
             documentData: nextData,
-            path: resolvedPath,
+            path: pathForCommand,
             status: defaultStatus,
-            locale: params.locale ?? defaultLocale,
+            locale: requestLocale,
             previousVersionId: originalData.document_version_id,
-        });
+        })
+            .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
         // 7. afterUpdate hook.
@@ -493,6 +574,9 @@ export async function restoreDocumentVersion(ctx, params) {
         //    the source tree forward in a single flatten pass — the
         //    cross-locale carry-forward branch in createDocumentVersion does
         //    not fire when locale === 'all'.
+        //
+        // No `path` is passed: restore does not change the document's path
+        // (the existing byline_document_paths row stays as-is — sticky).
         const result = await db.commands.documents.createDocumentVersion({
             documentId: params.documentId,
             collectionId,
@@ -500,7 +584,6 @@ export async function restoreDocumentVersion(ctx, params) {
             collectionConfig: definition,
             action: 'restore',
             documentData: sourceFields,
-            path: currentMeta.path,
             status: getDefaultStatus(definition),
             locale: 'all',
             previousVersionId: currentMeta.document_version_id,

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

@@ -319,7 +319,7 @@ describe('Document lifecycle service', () => {
                 documentVersionId: 'ver-1',
             }));
         });
-        it('keeps path sticky from the previous version when no explicit path is supplied', async () => {
+        it('does not pass path to the storage primitive when no explicit path is supplied', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({
                 document_version_id: 'prev-ver',
@@ -333,8 +333,9 @@ describe('Document lifecycle service', () => {
                 documentId: 'doc-1',
                 data: { title: 'Brand New Title' },
             });
-            // Path is NOT re-derived from the now-changed title
-            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBe('original-path');
+            // Sticky path semantics: the storage layer is not asked to write the
+            // path row; the existing byline_document_paths row stays as-is.
+            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBeUndefined();
         });
         it('uses an explicit params.path verbatim on update, overriding the sticky value', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
@@ -365,6 +366,98 @@ describe('Document lifecycle service', () => {
             });
             expect(createDocumentVersion.mock.calls[0]?.[0].status).toBe('draft');
         });
+        it('drops path changes silently with a logger.warn on non-default-locale (translation) saves', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'about',
+                status: 'draft',
+                fields: { title: 'About' },
+            });
+            const ctx = buildCtx(db);
+            const warn = ctx.logger?.warn;
+            warn.mockClear();
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'À propos' },
+                locale: 'fr',
+                path: 'a-propos',
+            });
+            // Save still proceeds — the version row is created — but the path
+            // row is left untouched (no `path` flows to the storage primitive).
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBeUndefined();
+            expect(createDocumentVersion.mock.calls[0]?.[0].locale).toBe('fr');
+            // The caller is informed via a structured warn.
+            expect(warn).toHaveBeenCalledWith(expect.objectContaining({
+                documentId: 'doc-1',
+                requestedLocale: 'fr',
+                defaultLocale: 'en',
+                suppliedPath: 'a-propos',
+                currentPath: 'about',
+            }), expect.stringContaining('path changes apply only on default-locale writes'));
+        });
+        it('does not warn when a translation save supplies the same path as current', async () => {
+            const { db, getDocumentById } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'about',
+                status: 'draft',
+                fields: { title: 'About' },
+            });
+            const ctx = buildCtx(db);
+            const warn = ctx.logger?.warn;
+            warn.mockClear();
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'À propos' },
+                locale: 'fr',
+                path: 'about', // same as currentPath — idempotent, no warn
+            });
+            expect(warn).not.toHaveBeenCalled();
+        });
+        it('translates a Postgres unique-constraint violation on the path index to ERR_PATH_CONFLICT', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'about',
+                status: 'draft',
+                fields: { title: 'About' },
+            });
+            // Simulate the pg driver throwing a unique-violation on the path
+            // constraint when the upsert tries to claim a slug owned by another
+            // document in the same (collection, locale).
+            createDocumentVersion.mockRejectedValueOnce(Object.assign(new Error('duplicate key value violates unique constraint'), {
+                code: '23505',
+                constraint: 'idx_document_paths_collection_locale_path',
+            }));
+            const ctx = buildCtx(db);
+            try {
+                await updateDocument(ctx, {
+                    documentId: 'doc-1',
+                    data: { title: 'About' },
+                    path: 'home', // collides
+                });
+                throw new Error('expected ERR_PATH_CONFLICT');
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(BylineError);
+                expect(err.code).toBe(ErrorCodes.PATH_CONFLICT);
+            }
+        });
+        it('rethrows non-23505 errors unchanged', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({
+                document_version_id: 'prev-ver',
+                path: 'about',
+                status: 'draft',
+                fields: { title: 'About' },
+            });
+            const original = new Error('connection refused');
+            createDocumentVersion.mockRejectedValueOnce(original);
+            const ctx = buildCtx(db);
+            await expect(updateDocument(ctx, { documentId: 'doc-1', data: { title: 'X' }, path: 'home' })).rejects.toBe(original);
+        });
         it('supports an array of beforeUpdate and afterUpdate hooks', async () => {
             const callOrder = [];
             const hooks = {
@@ -719,13 +812,16 @@ describe('Document lifecycle service', () => {
             // Source version was 'archived'; default status for minimalCollection is 'draft'.
             expect(createDocumentVersion.mock.calls[0]?.[0].status).toBe('draft');
         });
-        it('keeps path sticky from the current version, not the source', async () => {
+        it('does not pass path on restore — the existing path row is sticky', async () => {
             const { db, createDocumentVersion, sourceVersionId } = setupRestore({
                 currentPath: 'sticky-path',
             });
             const ctx = buildCtx(db);
             await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
-            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBe('sticky-path');
+            // Restore never changes a document's path: the existing
+            // byline_document_paths row carries forward unchanged. The storage
+            // primitive only writes to document_paths when `path` is supplied.
+            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBeUndefined();
         });
         it('rejects when the source version belongs to a different document', async () => {
             const { db, sourceVersionId, createDocumentVersion } = setupRestore({

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.7.7",
+  "version": "1.8.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.7.7"
+    "@byline/auth": "1.8.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",