@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/lifecycle-hooks.md

@@ -0,0 +1,368 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/lifecycle-hooks. Do not edit. -->
+
+# lifecycle-hooks
+
+preSave, postSave, and the rest. Your logic, our plumbing.
+
+## README
+
+# Lifecycle hooks
+
+Attach behaviour to the four entity lifecycle moments: validation
+(reject bad input), postSave (log every change), preDelete (block delete
+when an invariant says no), postDelete (log after commit). This recipe
+ships an `article` entity with hooks at each phase.
+
+Hooks are how a feature inserts cross-cutting logic without the handler
+body knowing about it. They run in the same transaction as the write
+unless explicitly opted out, so a thrown hook rolls the whole change
+back.
+
+## What it shows
+
+- **`r.hook("validation", handlerRef, fn)`** — runs before the
+  handler body executes. Returns either `null` (pass) or an array of
+  `{ field, error }` objects (fail). Used here to reject titles
+  containing the word "spam" and titles longer than 200 characters.
+- **`r.hook("postSave", { allOf: entityRef }, fn)`** — fires after every
+  successful save (create or update) in the same transaction.
+  `result.isNew` distinguishes create from update; `result.changes`
+  carries the changed fields only.
+- **`r.hook("preDelete", { allOf: entityRef }, fn)`** — fires inside the
+  delete transaction. Throws on invariant violations (here: "published
+  articles cannot be deleted") to roll the delete back. The handler
+  receives the full row snapshot — no extra load needed.
+- **`r.hook("postDelete", { allOf: entityRef }, fn)`** — fires after commit.
+  External side effects (logs, notifications) belong here because
+  failures cannot roll the delete back.
+
+## When to reach for it
+
+You want logic that runs alongside writes — auditing, notification
+emails, denormalised counter updates — without modifying the handler
+body. The split between in-transaction and after-commit phases lets you
+pick the right rollback semantics for each side effect.
+
+## Source
+
+The whole feature lives in `src/feature.ts` (~100 lines). Integration
+tests exercise each of the four hook phases plus the rollback path on
+preDelete violation.
+
+```bash
+bun kumiko test integration samples/lifecycle-hooks
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Lifecycle Hooks Sample — Integration Test
+// Proves: validation rejects bad data, postSave tracks changes
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { expectErrorIncludes } from "@cosmicdrift/kumiko-framework/testing";
+import { articleEntity, articlesFeature, hookLog } from "../feature";
+
+let stack: TestStack;
+
+const editor = createTestUser({ roles: ["Admin", "Editor"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [articlesFeature] });
+  await unsafeCreateEntityTable(stack.db, articleEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+  hookLog.length = 0;
+});
+
+describe("validation hook: single handler", () => {
+  test("rejects title with banned word", async () => {
+    const error = await stack.http.writeErr(
+      "blog:write:article:create",
+      {
+        title: "Buy cheap SPAM now",
+      },
+      editor,
+    );
+
+    expectErrorIncludes(error, "title_contains_banned_word");
+  });
+
+  test("accepts clean title", async () => {
+    const data = await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      {
+        title: "Clean Article",
+      },
+      editor,
+    );
+
+    expect(data.isNew).toBe(true);
+  });
+});
+
+describe("validation hook: multi-handler", () => {
+  test("rejects overly long title on create", async () => {
+    const error = await stack.http.writeErr(
+      "blog:write:article:create",
+      {
+        title: "X".repeat(201),
+      },
+      editor,
+    );
+
+    expectErrorIncludes(error, "title_too_long");
+  });
+
+  test("rejects overly long title on update", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      {
+        title: "Short",
+      },
+      editor,
+    );
+
+    const error = await stack.http.writeErr(
+      "blog:write:article:update",
+      {
+        id: created.id,
+        changes: { title: "Y".repeat(201) },
+        version: 1,
+      },
+      editor,
+    );
+
+    expectErrorIncludes(error, "title_too_long");
+  });
+});
+
+describe("postSave entity hook", () => {
+  test("logs create event", async () => {
+    await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      {
+        title: "Hook Test",
+      },
+      editor,
+    );
+
+    expect(hookLog).toHaveLength(1);
+    expect(hookLog[0]?.type).toBe("created");
+  });
+
+  test("logs update event with changes", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      {
+        title: "Before Update",
+      },
+      editor,
+    );
+
+    hookLog.length = 0;
+
+    await stack.http.writeOk<SaveContext>(
+      "blog:write:article:update",
+      {
+        id: created.id,
+        changes: { title: "After Update" },
+        version: 1,
+      },
+      editor,
+    );
+
+    expect(hookLog).toHaveLength(1);
+    expect(hookLog[0]?.type).toBe("updated");
+    expect(hookLog[0]?.data["changes"]).toEqual({ title: "After Update" });
+  });
+});
+
+describe("preDelete + postDelete entity hooks", () => {
+  test("postDelete fires after a successful delete", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      { title: "Doomed" },
+      editor,
+    );
+
+    hookLog.length = 0;
+
+    await stack.http.writeOk<SaveContext>("blog:write:article:delete", { id: created.id }, editor);
+
+    expect(hookLog).toHaveLength(1);
+    expect(hookLog[0]?.type).toBe("deleted");
+    expect(hookLog[0]?.data["id"]).toBe(created.id);
+  });
+
+  test("preDelete blocks delete when the article is still published", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      { title: "Live Article" },
+      editor,
+    );
+    await stack.http.writeOk<SaveContext>(
+      "blog:write:article:update",
+      {
+        id: created.id,
+        changes: { isPublished: true },
+        version: 1,
+      },
+      editor,
+    );
+
+    hookLog.length = 0;
+
+    const error = await stack.http.writeErr(
+      "blog:write:article:delete",
+      { id: created.id },
+      editor,
+    );
+
+    expectErrorIncludes(error, "published_article_cannot_be_deleted");
+
+    // postDelete MUST NOT fire when preDelete rolled the tx back
+    expect(hookLog.filter((e) => e.type === "deleted")).toHaveLength(0);
+  });
+
+  test("preDelete allows delete when article is not published", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "blog:write:article:create",
+      { title: "Draft Article" },
+      editor,
+    );
+
+    hookLog.length = 0;
+
+    await stack.http.writeOk<SaveContext>("blog:write:article:delete", { id: created.id }, editor);
+
+    expect(hookLog.map((e) => e.type)).toEqual(["deleted"]);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Lifecycle Hooks Sample
+// Shows: validation hooks (reject bad data), postSave entity hooks (track changes),
+// preDelete hooks (block delete on invariant violation), postDelete hooks
+// (log deletions after commit).
+
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type SaveContext,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError } from "@cosmicdrift/kumiko-framework/errors";
+
+export const articleEntity = createEntity({
+  table: "read_sample_articles",
+  fields: {
+    // maxLength high so zod lets long titles through — the validation hook
+    // below rejects titles > 200 so the sample can demonstrate the hook path.
+    title: createTextField({
+      personal: false,
+      reason: "is_business_data",
+      required: true,
+      maxLength: 1000,
+    }),
+    content: createTextField({ personal: false, reason: "is_business_data" }),
+    status: createTextField({ personal: false, reason: "is_business_data", default: "draft" }),
+    isPublished: createBooleanField({ default: false }),
+  },
+});
+
+// Collect hook events for testing
+export const hookLog: { type: string; data: Record<string, unknown> }[] = [];
+
+const editorWrite = { access: { roles: ["Admin", "Editor"] } } as const;
+
+export const articlesFeature = defineFeature("blog", (r) => {
+  const article = r.entity("article", articleEntity);
+
+  const articleCreate = r.writeHandler(
+    defineEntityCreateHandler("article", articleEntity, editorWrite),
+  );
+  const articleUpdate = r.writeHandler(
+    defineEntityUpdateHandler("article", articleEntity, editorWrite),
+  );
+  r.writeHandler(defineEntityDeleteHandler("article", articleEntity, editorWrite));
+
+  // --- Validation hook on create: reject banned words + length ---
+  r.hook("validation", articleCreate, (data) => {
+    const title = data["title"] as string;
+    if (title.toLowerCase().includes("spam")) {
+      return [{ field: "title", error: "title_contains_banned_word" }];
+    }
+    if (title.length > 200) {
+      return [{ field: "title", error: "title_too_long" }];
+    }
+    return null;
+  });
+
+  // --- Validation hook on update: length check on title changes ---
+  r.hook("validation", articleUpdate, (data) => {
+    const changes = data["changes"] as Record<string, unknown> | undefined;
+    const title = changes?.["title"] as string | undefined;
+    if (title && title.length > 200) {
+      return [{ field: "title", error: "title_too_long" }];
+    }
+    return null;
+  });
+
+  // --- postSave entity hook: log all saves ---
+  r.hook("postSave", { allOf: article }, async (result: SaveContext) => {
+    hookLog.push({
+      type: result.isNew ? "created" : "updated",
+      data: { id: result.id, changes: result.changes },
+    });
+  });
+
+  // --- preDelete entity hook: block delete when the article is still published.
+  // preDelete runs inside the write transaction and throws on violation, so
+  // the delete rolls back before any projection or event is written. The
+  // payload.data carries the full row snapshot taken just before delete —
+  // no extra load needed.
+  r.hook("preDelete", { allOf: article }, async (payload) => {
+    if (payload.data["isPublished"] === true) {
+      throw new ConflictError({
+        message: `article ${payload.id} is still published`,
+        i18nKey: "errors.publishedArticleCannotBeDeleted",
+        details: { reason: "published_article_cannot_be_deleted", entityId: payload.id },
+      });
+    }
+  });
+
+  // --- postDelete entity hook: log deletions after the transaction commits.
+  // Default phase is afterCommit so failures here can't roll back the delete.
+  r.hook("postDelete", { allOf: article }, async (payload) => {
+    hookLog.push({
+      type: "deleted",
+      data: { id: payload.id },
+    });
+  });
+});
+```