@byline/core 4.16.0 → 4.17.0

package/dist/services/singleton-lifecycle/internals.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { IDocumentCommands, IDocumentQueries, SingletonDefinition, SingletonSaveOperation } from '../../@types/index.js';
+import type { DocumentLifecycleContext } from '../document-lifecycle/context.js';
+type VersionWriteResult = Awaited<ReturnType<IDocumentCommands['createDocumentVersion']>>;
+type CurrentVersionMetadata = NonNullable<Awaited<ReturnType<IDocumentQueries['getCurrentVersionMetadata']>>>;
+export interface SingletonSaveResult {
+    documentId: string;
+    documentVersionId: string;
+}
+export interface LockedSingletonSlot {
+    documentId: string | null;
+    currentVersion: CurrentVersionMetadata | null;
+}
+interface PreparedSingletonSave {
+    data: Record<string, any>;
+    originalData: Record<string, any> | null;
+    locale: string;
+    write: () => Promise<VersionWriteResult>;
+}
+/**
+ * Assert the kind-aware singleton update ability without touching storage.
+ * The runtime kind guard keeps this internal service from becoming an
+ * alternate write path for an ordinary collection.
+ */
+export declare function authorizeSingletonUpdate(ctx: DocumentLifecycleContext): SingletonDefinition;
+/**
+ * Resolve the mapped logical document id without running read authorization
+ * or hooks. Client-facing callers must authorize before invoking this resolver.
+ */
+export declare function resolveSingletonDocumentId(ctx: DocumentLifecycleContext): Promise<string | null>;
+/**
+ * Coordinate one singleton version write under the registered-slot lock.
+ * `prepare` runs after the mapping and current version have been read while
+ * locked. The before hook and write remain inside the outer transaction; the
+ * after hook cannot run until that transaction has committed.
+ */
+export declare function commitSingletonSave(params: {
+    ctx: DocumentLifecycleContext;
+    definition: SingletonDefinition;
+    operation: SingletonSaveOperation;
+    prepare: (slot: LockedSingletonSlot) => Promise<PreparedSingletonSave>;
+}): Promise<SingletonSaveResult>;
+export {};

package/dist/services/singleton-lifecycle/internals.js

@@ -0,0 +1,118 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { DbErrorCodes, ERR_CONFLICT, ERR_VALIDATION } from '../../lib/errors.js';
+import { extractDocumentId, extractVersionId } from '../document-lifecycle/internals.js';
+/**
+ * Assert the kind-aware singleton update ability without touching storage.
+ * The runtime kind guard keeps this internal service from becoming an
+ * alternate write path for an ordinary collection.
+ */
+export function authorizeSingletonUpdate(ctx) {
+    if (ctx.definition.singleton !== true) {
+        throw ERR_VALIDATION({
+            message: `singleton lifecycle requires a singleton definition; '${ctx.collectionPath}' is a collection`,
+            details: { path: ctx.collectionPath, expectedKind: 'singleton' },
+        }).log(ctx.logger);
+    }
+    assertActorCanPerform(ctx.requestContext, ctx.definition, 'update');
+    return ctx.definition;
+}
+/**
+ * Resolve the mapped logical document id without running read authorization
+ * or hooks. Client-facing callers must authorize before invoking this resolver.
+ */
+export function resolveSingletonDocumentId(ctx) {
+    return ctx.db.queries.singletons.getMappedDocumentId(ctx.collectionId);
+}
+/**
+ * Coordinate one singleton version write under the registered-slot lock.
+ * `prepare` runs after the mapping and current version have been read while
+ * locked. The before hook and write remain inside the outer transaction; the
+ * after hook cannot run until that transaction has committed.
+ */
+export async function commitSingletonSave(params) {
+    const { ctx, definition, operation } = params;
+    const hooks = await resolveHooks(definition);
+    const requestContext = ctx.requestContext;
+    if (requestContext == null) {
+        throw new Error('singleton authorization completed without a request context');
+    }
+    const committed = await ctx.db.withTransaction(async () => {
+        await ctx.db.commands.singletons.lockSlot(ctx.collectionId);
+        const mappedDocumentId = await resolveSingletonDocumentId(ctx);
+        const currentVersion = mappedDocumentId == null
+            ? null
+            : await ctx.db.queries.documents.getCurrentVersionMetadata({
+                collection_id: ctx.collectionId,
+                document_id: mappedDocumentId,
+            });
+        if (mappedDocumentId != null && currentVersion == null) {
+            throw ERR_CONFLICT({
+                message: `singleton '${ctx.collectionPath}' is mapped to a deleted or unavailable document; ` +
+                    'clear the mapping deliberately before rematerialising the slot',
+                details: { singletonPath: ctx.collectionPath, documentId: mappedDocumentId },
+            }).log(ctx.logger);
+        }
+        const slot = { documentId: mappedDocumentId, currentVersion };
+        const prepared = await params.prepare(slot);
+        const isInitialSave = mappedDocumentId == null;
+        const beforeSaveContext = {
+            data: prepared.data,
+            originalData: prepared.originalData,
+            singletonPath: ctx.collectionPath,
+            locale: prepared.locale,
+            requestContext,
+            isInitialSave,
+            operation,
+            documentId: mappedDocumentId,
+        };
+        await invokeSingletonHook(hooks?.beforeSave, beforeSaveContext);
+        const writeResult = await prepared.write();
+        const documentId = extractDocumentId(writeResult.document) || mappedDocumentId || '';
+        const documentVersionId = extractVersionId(writeResult.document);
+        if (documentId === '' || documentVersionId === '') {
+            throw new Error('singleton persistence did not return document and version ids');
+        }
+        if (isInitialSave) {
+            try {
+                await ctx.db.commands.singletons.setMapping(ctx.collectionId, documentId);
+            }
+            catch (error) {
+                if (ctx.db.classifyError?.(error)?.code === DbErrorCodes.UNIQUE_VIOLATION) {
+                    throw ERR_CONFLICT({
+                        message: `singleton '${ctx.collectionPath}' was materialised concurrently`,
+                        details: { singletonPath: ctx.collectionPath },
+                    }).log(ctx.logger);
+                }
+                throw error;
+            }
+        }
+        return {
+            documentId,
+            documentVersionId,
+            afterSaveContext: {
+                ...beforeSaveContext,
+                documentId,
+                documentVersionId,
+            },
+        };
+    });
+    await invokeSingletonHook(hooks?.afterSave, committed.afterSaveContext);
+    return {
+        documentId: committed.documentId,
+        documentVersionId: committed.documentVersionId,
+    };
+}
+async function invokeSingletonHook(hook, context) {
+    const hooks = hook == null ? [] : Array.isArray(hook) ? hook : [hook];
+    for (const invoke of hooks) {
+        await invoke(context);
+    }
+}

package/dist/services/singleton-lifecycle/restore.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { DocumentLifecycleContext } from '../document-lifecycle/context.js';
+import type { SingletonSaveResult } from './internals.js';
+/** Restore one historical singleton version as the new current version. */
+export declare function restoreSingletonVersion(ctx: DocumentLifecycleContext, params: {
+    sourceVersionId: string;
+}): Promise<SingletonSaveResult>;

package/dist/services/singleton-lifecycle/restore.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { applyRichTextEmbed } from '../document-lifecycle/internals.js';
+import { persistExistingDocumentVersion } from '../document-lifecycle/persistence.js';
+import { authorizeSingletonUpdate, commitSingletonSave } from './internals.js';
+/** Restore one historical singleton version as the new current version. */
+export async function restoreSingletonVersion(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'restoreSingletonVersion' }, async () => {
+        const definition = authorizeSingletonUpdate(ctx);
+        return commitSingletonSave({
+            ctx,
+            definition,
+            operation: { type: 'restore', sourceVersionId: params.sourceVersionId },
+            prepare: async (slot) => {
+                if (slot.documentId == null || slot.currentVersion == null) {
+                    throw ERR_NOT_FOUND({
+                        message: `singleton '${ctx.collectionPath}' has not been saved`,
+                        details: { singletonPath: ctx.collectionPath },
+                    }).log(ctx.logger);
+                }
+                const source = await ctx.db.queries.documents.getDocumentByVersion({
+                    document_version_id: params.sourceVersionId,
+                    collection_id: ctx.collectionId,
+                    locale: 'all',
+                });
+                if (source == null) {
+                    throw ERR_NOT_FOUND({
+                        message: 'source version not found',
+                        details: { sourceVersionId: params.sourceVersionId },
+                    }).log(ctx.logger);
+                }
+                const sourceRecord = source;
+                if (sourceRecord.document_id !== slot.documentId) {
+                    throw ERR_VALIDATION({
+                        message: 'source version does not belong to the singleton document',
+                        details: {
+                            singletonPath: ctx.collectionPath,
+                            sourceVersionId: params.sourceVersionId,
+                            sourceDocumentId: sourceRecord.document_id,
+                        },
+                    }).log(ctx.logger);
+                }
+                if (slot.currentVersion.document_version_id === params.sourceVersionId) {
+                    throw ERR_INVALID_TRANSITION({
+                        message: 'source version is already the current singleton version',
+                        details: {
+                            singletonPath: ctx.collectionPath,
+                            sourceVersionId: params.sourceVersionId,
+                        },
+                    }).log(ctx.logger);
+                }
+                const current = await ctx.db.queries.documents.getDocumentById({
+                    collection_id: ctx.collectionId,
+                    document_id: slot.documentId,
+                    locale: 'all',
+                    reconstruct: true,
+                });
+                if (current == null) {
+                    throw ERR_NOT_FOUND({
+                        message: 'current singleton version not found',
+                        details: { singletonPath: ctx.collectionPath, documentId: slot.documentId },
+                    }).log(ctx.logger);
+                }
+                const data = sourceRecord.fields ?? {};
+                const originalData = current.fields ?? {};
+                return {
+                    data,
+                    originalData,
+                    locale: 'all',
+                    write: async () => {
+                        await applyRichTextEmbed(ctx, data);
+                        return persistExistingDocumentVersion(ctx, {
+                            documentId: slot.documentId,
+                            action: 'restore',
+                            documentData: data,
+                            status: getDefaultStatus(definition),
+                            locale: 'all',
+                            previousVersionId: slot.currentVersion?.document_version_id,
+                        });
+                    },
+                };
+            },
+        });
+    });
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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 { DocumentLifecycleContext } from '../document-lifecycle/context.js';
+import type { SingletonSaveResult } from './internals.js';
+export interface UpdateSingletonParams {
+    data: Record<string, any>;
+    locale?: string;
+    expectedVersionId?: string;
+}
+/** Materialise or update a singleton slot as one immutable document version. */
+export declare function updateSingleton(ctx: DocumentLifecycleContext, params: UpdateSingletonParams): Promise<SingletonSaveResult>;

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

@@ -0,0 +1,107 @@
+/**
+ * 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 { ERR_CONFLICT, ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { normaliseDateFields } from '../../utils/normalise-dates.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { assignCounterValues } from '../assign-counter-values.js';
+import { applyRichTextEmbed } from '../document-lifecycle/internals.js';
+import { persistExistingDocumentVersion, persistInitialDocumentVersion, } from '../document-lifecycle/persistence.js';
+import { normalizeNumericFields } from '../normalize-numeric-fields.js';
+import { authorizeSingletonUpdate, commitSingletonSave } from './internals.js';
+/** Materialise or update a singleton slot as one immutable document version. */
+export async function updateSingleton(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'updateSingleton' }, async () => {
+        const definition = authorizeSingletonUpdate(ctx);
+        const locale = params.locale ?? ctx.defaultLocale;
+        const data = params.data;
+        return commitSingletonSave({
+            ctx,
+            definition,
+            operation: { type: 'save' },
+            prepare: async (slot) => {
+                if (slot.documentId == null && locale !== ctx.defaultLocale) {
+                    throw ERR_VALIDATION({
+                        message: `a singleton's first save must use the default content locale ` +
+                            `('${ctx.defaultLocale}'); received '${locale}'`,
+                        details: {
+                            singletonPath: ctx.collectionPath,
+                            defaultLocale: ctx.defaultLocale,
+                            providedLocale: locale,
+                        },
+                    }).log(ctx.logger);
+                }
+                if (params.expectedVersionId != null) {
+                    const currentVersionId = slot.currentVersion?.document_version_id;
+                    if (currentVersionId !== params.expectedVersionId) {
+                        throw ERR_CONFLICT({
+                            message: 'singleton version conflict',
+                            details: {
+                                singletonPath: ctx.collectionPath,
+                                expectedVersionId: params.expectedVersionId,
+                                currentVersionId: currentVersionId ?? null,
+                            },
+                        }).log(ctx.logger);
+                    }
+                }
+                const current = slot.documentId == null
+                    ? null
+                    : await ctx.db.queries.documents.getDocumentById({
+                        collection_id: ctx.collectionId,
+                        document_id: slot.documentId,
+                        locale,
+                        reconstruct: true,
+                        lenient: true,
+                        requestContext: ctx.requestContext,
+                    });
+                if (slot.documentId != null && current == null) {
+                    throw ERR_CONFLICT({
+                        message: `singleton '${ctx.collectionPath}' could not reconstruct its mapped document`,
+                        details: { singletonPath: ctx.collectionPath, documentId: slot.documentId },
+                    }).log(ctx.logger);
+                }
+                const currentRecord = current;
+                const originalData = currentRecord?.fields ?? null;
+                normaliseDateFields(data);
+                normalizeNumericFields(definition.fields, data);
+                return {
+                    data,
+                    originalData,
+                    locale,
+                    write: async () => {
+                        normalizeNumericFields(definition.fields, data);
+                        await assignCounterValues({
+                            fields: definition.fields,
+                            data,
+                            previousData: originalData ?? undefined,
+                            counters: ctx.db.commands.counters,
+                        });
+                        await applyRichTextEmbed(ctx, data);
+                        if (slot.documentId == null) {
+                            return persistInitialDocumentVersion(ctx, {
+                                action: 'create',
+                                documentData: data,
+                                path: crypto.randomUUID(),
+                                status: getDefaultStatus(definition),
+                                locale,
+                            });
+                        }
+                        return persistExistingDocumentVersion(ctx, {
+                            documentId: slot.documentId,
+                            action: 'update',
+                            documentData: data,
+                            status: getDefaultStatus(definition),
+                            locale,
+                            previousVersionId: slot.currentVersion?.document_version_id,
+                        });
+                    },
+                };
+            },
+        });
+    });
+}

package/dist/services/singleton-lifecycle.test.node.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 {};