@pramen/server 0.0.10 → 0.0.12

package/src/sdk/schema.ts

@@ -95,26 +95,82 @@ export type RelationBuilders = typeof relationBuilders;
 /** The default partition name for entities that don't declare one. */
 export const DEFAULT_PARTITION = "default";
 
+// --- triggers — declarative "on write → enqueue a task" (layered on the outbox) ---
+
+export type TriggerOp = "create" | "update" | "delete";
+
+/** A declarative trigger on an entity: when a matching write commits, the `Db` write
+ * path enqueues a task of `task` (handled by `app.tasks[task]`) IN THE SAME transaction
+ * as the write, with payload `{ entity, op, id, row }`. So a side effect (webhook,
+ * notification email) fires reliably after the write, off the single-writer path —
+ * reusing the whole outbox machinery (retry, idempotency, drain). Only ORM writes
+ * (`ctx.db` insert/update/delete) fire triggers; the raw `ctx.db.exec` escape hatch
+ * does not. */
+export interface TriggerDef {
+  /** The `app.tasks` handler kind that runs the side effect. */
+  readonly task: string;
+  /** Which ops fire it. For `update`, an array names the columns to watch — fire only
+   * when the update writes one of them; `true` fires on any update. */
+  readonly on: { create?: boolean; update?: boolean | readonly string[]; delete?: boolean };
+}
+
+/** Declare an entity trigger (sugar; returns the def). */
+export function trigger(def: TriggerDef): TriggerDef {
+  return def;
+}
+
+/** Does this trigger fire for `op` given the columns the write touched? */
+export function triggerFires(t: TriggerDef, op: TriggerOp, writtenCols: readonly string[]): boolean {
+  if (op === "create") return t.on.create === true;
+  if (op === "delete") return t.on.delete === true;
+  const u = t.on.update;
+  if (u === true) return true;
+  if (Array.isArray(u)) return u.some((f) => writtenCols.includes(f));
+  return false;
+}
+
 export interface EntityDef<F extends EntityFields = EntityFields, R extends RelationDefs = Record<string, never>> {
   readonly fields: F;
   readonly relations: R;
   /** The partition (Durable Object class) this entity lives in. Always populated;
    * defaults to `"default"` so downstream code never branches on `undefined`. */
   readonly partition: string;
+  /** Declarative write-triggers (see TriggerDef). Always an array (possibly empty). */
+  readonly triggers: readonly TriggerDef[];
 }
 
 export function Entity<F extends EntityFields, R extends RelationDefs = Record<string, never>>(
   build: (t: FieldBuilders) => F,
   relations?: (r: RelationBuilders) => R,
-  opts?: { partition?: string },
+  opts?: { partition?: string; triggers?: readonly TriggerDef[] },
 ): EntityDef<F, R> {
   return {
     fields: build(builders),
     relations: (relations ? relations(relationBuilders) : {}) as R,
     partition: opts?.partition ?? DEFAULT_PARTITION,
+    triggers: opts?.triggers ?? [],
   };
 }
 
+/** The triggers declared on an entity (empty if none / unknown entity). */
+export function triggersOf(schema: SchemaDef, entity: string): readonly TriggerDef[] {
+  return schema[entity]?.triggers ?? [];
+}
+
+/** Throw if any declarative trigger names a `task` not in `taskNames` — caught at
+ * deploy/load by createPramen, so a typo can't silently enqueue a task that never runs
+ * (it would retry then dead-letter). */
+export function validateTriggerTasks(schema: SchemaDef, taskNames: Iterable<string>): void {
+  const known = new Set(taskNames);
+  for (const [entity, def] of Object.entries(schema)) {
+    for (const t of def.triggers) {
+      if (!known.has(t.task)) {
+        throw new Error(`trigger on '${entity}' references task '${t.task}', but app.tasks has no such handler.`);
+      }
+    }
+  }
+}
+
 /** Annotate a field as renamed from a previous column name (migration hint). Wraps
  * a builder result, preserving its literal field type: `title: renamedFrom(t.text(), "name")`. */
 export function renamedFrom<F extends FieldDef>(field: F, from: string): F & { readonly renamedFrom: string } {
@@ -254,5 +310,17 @@ export function validateSchema(schema: SchemaDef): void {
         );
       }
     }
+    for (const t of def.triggers) {
+      if (!t.task) throw new Error(`trigger on '${entity}' is missing a 'task'.`);
+      if (!t.on.create && !t.on.update && !t.on.delete) {
+        throw new Error(`trigger '${t.task}' on '${entity}' fires on nothing — set on.create/update/delete.`);
+      }
+      const watched = Array.isArray(t.on.update) ? t.on.update : [];
+      for (const f of watched) {
+        if (!(f in def.fields)) {
+          throw new Error(`trigger '${t.task}' on '${entity}' watches unknown column '${f}'.`);
+        }
+      }
+    }
   }
 }

package/src/worker.ts

@@ -7,6 +7,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity, type VerifyStrategy } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { createMail } from "./runtime/mail";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -148,8 +149,9 @@ export function makeWorker(app: PramenApp) {
   const d1TaskCtx = (driver: Driver, env: Env): HandlerContext => {
     const identity: Identity = { roles: ["admin"] };
     const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
-    const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema }, app.schema);
-    return { db, kv: new Kv(env.KV), files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver) };
+    const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
+    const kv = new Kv(env.KV);
+    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv) };
   };
 
   /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the