@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

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

@@ -0,0 +1,20 @@
+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 withoutEventInJson<T extends {
+    readonly event: unknown;
+}>(result: T): T;
+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,100 @@
+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";
+// The echoed event carries entity PII and must never reach a handler's JSON response, while
+// hooks and projections still read it by property. Non-enumerable keeps it out of spread/stringify.
+export function withoutEventInJson(result) {
+    return Object.defineProperty(result, "event", { value: result.event, enumerable: false });
+}
+// 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;
+}