@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/db/event-store-executor-write-atomic.d.ts

@@ -0,0 +1,4 @@
+import type { EventStoreExecutor } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+type WriteVerbs = Pick<EventStoreExecutor, "create" | "update" | "delete" | "forget" | "restore">;
+export declare function withOwnTransactionOnPool(verbs: WriteVerbs): WriteVerbs;
+export {};

package/dist/db/event-store-executor-write-atomic.js

@@ -0,0 +1,41 @@
+import { runnerCanBeginTransaction } from "./query.js";
+import { runInOwnTransaction } from "./tenant-db.js";
+import { isBoundTenantDb, tenantDbRunner, tenantDbWritesDeniedReason } from "./tenant-db-runner.js";
+// Aborts the surrounding transaction when a verb returns a failure instead of throwing.
+class RollbackOnFailure extends Error {
+}
+// Pool runners have no savepoint, so append, projection and hooks would otherwise commit as
+// separate autocommit statements. Tx and savepoint runners already provide atomicity.
+async function runVerbAtomically(db, run) {
+    // Unbound and denied handles keep their original error, a fresh transaction would reword it.
+    if (!isBoundTenantDb(db) ||
+        tenantDbWritesDeniedReason(db) !== undefined ||
+        !runnerCanBeginTransaction(tenantDbRunner(db))) {
+        return run(db);
+    }
+    let failure;
+    try {
+        return await runInOwnTransaction(db, async (txDb) => {
+            const result = await run(txDb);
+            if (!result.isSuccess) {
+                failure = result;
+                throw new RollbackOnFailure();
+            }
+            return result;
+        });
+    }
+    catch (error) {
+        if (error instanceof RollbackOnFailure && failure !== undefined)
+            return failure;
+        throw error;
+    }
+}
+export function withOwnTransactionOnPool(verbs) {
+    return {
+        create: (payload, user, db, options) => runVerbAtomically(db, (txDb) => verbs.create(payload, user, txDb, options)),
+        update: (payload, user, db, options) => runVerbAtomically(db, (txDb) => verbs.update(payload, user, txDb, options)),
+        delete: (payload, user, db, options) => runVerbAtomically(db, (txDb) => verbs.delete(payload, user, txDb, options)),
+        forget: (payload, user, db, options) => runVerbAtomically(db, (txDb) => verbs.forget(payload, user, txDb, options)),
+        restore: (payload, user, db, options) => runVerbAtomically(db, (txDb) => verbs.restore(payload, user, txDb, options)),
+    };
+}

package/dist/db/event-store-executor-write-steps.d.ts

@@ -0,0 +1,17 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { ZodType } from "zod";
+import type { UnavailableSelectOption } from "../engine/screen-helpers.ts";
+import type { EntityId } from "../engine/types/index.ts";
+import { type UnprocessableOpts, type WriteFailure, writeFailure } from "../errors/index.ts";
+import type { StoredEvent } from "../event-store/index.ts";
+import type { DbRow, DbRunner } from "./connection.ts";
+export declare function projectEntityEvent(db: TenantDb, runner: DbRunner, event: StoredEvent): Promise<void>;
+export declare function selectOptionNotAvailableFailure(entries: readonly UnavailableSelectOption[]): WriteFailure | undefined;
+export type PreSaveFn = (changes: Record<string, unknown>, previous: Record<string, unknown>, isNew: boolean) => Promise<Record<string, unknown>>;
+export declare function runPreSave(preSave: PreSaveFn | undefined, changes: Record<string, unknown>, previous: Record<string, unknown>, isNew: boolean, entityName: string, action: "create" | "update", outputSchema: () => ZodType): Promise<{
+    readonly data: DbRow;
+} | {
+    readonly failure: ReturnType<typeof writeFailure>;
+}>;
+export declare function ownershipDeniedFailure(details: NonNullable<UnprocessableOpts["details"]>): WriteFailure;
+export declare function optimisticLockFailure(entityId: EntityId, submittedVersion: number | undefined, currentVersion: number, skip: boolean | undefined): WriteFailure | undefined;

package/dist/db/event-store-executor-write-steps.js

@@ -0,0 +1,95 @@
+import { VersionConflictError as FrameworkVersionConflict, UnprocessableError, writeFailure, } from "../errors/index.js";
+import { hasLiveProjectionsForEvent, runProjectionsForEvent, } from "../pipeline/projections-runner.js";
+import { projectionRegistryOf } from "./projection-registry-binding.js";
+import { runInSavepointIfSupported } from "./query.js";
+// Custom projections for a write that did not go through the dispatcher (hook or
+// job writing a second aggregate). Savepoint like applyEntityEvent: a throwing
+// projection fails the write and the caller's transaction rolls it back.
+export async function projectEntityEvent(db, runner, event) {
+    const registry = projectionRegistryOf(db);
+    // skip: TenantDb not built by a dispatcher/job runner — nothing bound to project with
+    if (!registry)
+        return;
+    // skip: no live projection listens — avoid a SAVEPOINT round trip on every plain write
+    if (!hasLiveProjectionsForEvent(event, registry))
+        return;
+    await runInSavepointIfSupported(runner, (sp) => runProjectionsForEvent(event, registry, sp));
+}
+export function selectOptionNotAvailableFailure(entries) {
+    const [first] = entries;
+    if (!first)
+        return undefined;
+    const i18nKey = "kumiko.validation.optionNotAvailable";
+    return writeFailure(new UnprocessableError("select_option_not_available", {
+        i18nKey,
+        details: {
+            field: first.field,
+            value: first.value,
+            allowed: first.allowed,
+            fields: entries.map((entry) => ({
+                path: entry.field,
+                code: "select_option_not_available",
+                i18nKey,
+                params: { allowed: entry.allowed },
+            })),
+        },
+    }));
+}
+// preSave runs before ownership checks: authorization must evaluate the row
+// as it will actually be persisted, including hook-derived fields. A throwing
+// hook is an app-author bug (bad business rule, not a framework fault) — map it
+// to a clean writeFailure instead of letting it propagate as an internal_error
+// 500.
+export async function runPreSave(preSave, changes, previous, isNew, entityName, action, outputSchema) {
+    if (!preSave)
+        return { data: changes };
+    try {
+        const hookResult = await preSave(changes, previous, isNew);
+        // A hook that echoes `id`/`version` back (e.g. `{ ...changes, id: x }`)
+        // must not leak them into the persisted row — aggregateId already comes
+        // from generateId()/the loaded row, not from hook output.
+        const { id: _hookId, version: _hookVersion, ...safe } = hookResult;
+        // Hook output skips the handler's input validation yet goes straight into the projection.
+        // Validated only, not replaced by the parse result: hooks may set fields in storage form.
+        const parsed = outputSchema().safeParse(safe);
+        if (!parsed.success) {
+            return {
+                failure: writeFailure(new UnprocessableError("presave_hook_invalid_output", {
+                    i18nKey: "errors.presaveHookInvalidOutput",
+                    details: {
+                        entityName,
+                        action,
+                        handler: `${entityName}:${action}`,
+                        issues: parsed.error.issues.map((issue) => ({
+                            path: issue.path.join("."),
+                            message: issue.message,
+                        })),
+                    },
+                })),
+            };
+        }
+        return { data: safe };
+    }
+    catch (e) {
+        return {
+            failure: writeFailure(new UnprocessableError("presave_hook_failed", {
+                i18nKey: "errors.presaveHookFailed",
+                details: { entityName, action, message: e instanceof Error ? e.message : String(e) },
+            })),
+        };
+    }
+}
+export function ownershipDeniedFailure(details) {
+    return writeFailure(new UnprocessableError("ownership_denied", { i18nKey: "errors.ownershipDenied", details }));
+}
+export function optimisticLockFailure(entityId, submittedVersion, currentVersion, skip) {
+    if (skip)
+        return undefined;
+    if (submittedVersion === undefined) {
+        return writeFailure(new FrameworkVersionConflict({ entityId, expectedVersion: 0, currentVersion }));
+    }
+    if (currentVersion !== submittedVersion) {
+        return writeFailure(new FrameworkVersionConflict({ entityId, expectedVersion: submittedVersion, currentVersion }));
+    }
+    return undefined;
+}