@everystack/api 0.4.12 → 0.4.13

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.13] - 2026-10-30
+
+### BREAKING CHANGES
+
+- destroy is one generated SQL function per lifecycle table; purgeExpired is removed
+
+### Fixed
+
+- destroy hooks are refused on a table that is not a lifecycle table
+- a delete before-hook outage answers the fixed 503 again
+
+### Changed
+
+- one delete hook pair; beforeStamp and afterStamp are folded into beforeDelete and afterDelete
+
+### Documentation
+
+- one delete hook pair
+
 ## [0.4.12] - 2026-10-23
 
 ### BREAKING CHANGES

package/README.md

@@ -99,11 +99,9 @@ createHandler(db, schema, {
       afterCreate: async (row, user, client) => { /* notify */ },
       beforeUpdate: async (body, user, client) => body,
       afterUpdate: async (rows, user, client) => {},
-      beforeDelete: async (user, client) => {},
-      afterDelete: async (rows, user, client) => {},
-      // Lifecycle tables only (see "Extending lifecycle" in docs/handler.md); veto from '@everystack/api/handler':
-      beforeStamp: (row, ctx) => (ctx.user ? undefined : veto('sign in to delete')), // in the transaction; veto -> 409
-      afterStamp: async (rows, ctx) => {},   // after commit, once per batch (ctx.batch)
+      // All models; veto from '@everystack/api/handler' rolls back the request:
+      beforeDelete: (row, ctx) => (ctx.user ? undefined : veto('sign in to delete')), // in the transaction; veto -> 409
+      afterDelete: async (rows, ctx) => {},  // after commit, once per request; ctx.batch is null
       afterRestore: async (rows, ctx) => {}, // after commit, ctx.batch and ctx.counts
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.12",
+  "version": "0.4.13",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/handler/index.ts

@@ -30,14 +30,14 @@ export { HandlerError } from './errors';
 import { HandlerError } from './errors';
 export { veto, isVeto } from './veto';
 export type { HookVeto, LifecycleContext, DestroyContext, DestroyHook, BeforeLifecycleHook, AfterLifecycleHook } from './veto';
-import { isVeto, type AfterLifecycleHook, type BeforeLifecycleHook, type DestroyContext, type DestroyHook, type LifecycleContext } from './veto';
+import { isVeto, type AfterLifecycleHook, type BeforeLifecycleHook, type LifecycleContext } from './veto';
 
 /** A before hook returned veto(reason): the request is refused with 409 and its transaction rolls back. */
 class VetoRefusal extends Error {
   constructor(readonly reason: string) { super(reason); }
 }
 
-/** A lifecycle before hook threw inside its transaction; carried out so the handler can answer as for any before hook. */
+/** A delete before hook threw inside its transaction; carried out so the handler can answer as for any before hook. */
 class BeforeHookThrew extends Error {
   constructor(readonly thrown: unknown) { super('before hook threw'); }
 }
@@ -294,31 +294,13 @@ export interface HookConfig {
   beforeUpdate?: (body: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<Record<string, unknown>>;
   /** Called after UPDATE with all returned rows. Fire-and-forget. */
   afterUpdate?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
-  /** Called before DELETE. Throw to abort. */
-  beforeDelete?: (user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
-  /** Called after DELETE with all deleted rows. Fire-and-forget. */
-  afterDelete?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
-  /** After the hard DELETE statement and before commit, for each returned row. Return
-   * `veto(reason)` to refuse the request (409 `{ message, code: 'vetoed' }`, nothing deleted). A
-   * throw rolls back the database delete only. No transaction is passed; external effects
-   * cannot be undone and must be idempotent. Lifecycle API deletes do not call this.
-   * Treat the row as read-only: it is the same object later serialized into the response. */
-  beforeDestroy?: DestroyHook;
-  /** After a real removal commits, per returned row, best-effort. Must be idempotent.
-   * Treat the row as read-only: it is the same object later serialized into the response. */
-  afterDestroy?: DestroyHook;
-  /** Lifecycle tables only: inside the DELETE's transaction, before the DELETE statement, once per
-   * matched ROOT row (the pre-image), with `{ phase: 'stamp', batch: null }`. Return `veto(reason)` to
-   * refuse the whole request: 409 `{ message: reason, code: 'vetoed' }`, nothing stamped, no after
-   * hooks. A throw is a failure (a HandlerError keeps its status, anything else is 500). Cascaded
-   * children run no hook: guard them with the model's `deleteWhen`. */
-  beforeStamp?: BeforeLifecycleHook;
-  /** Lifecycle tables only: after a DELETE that stamped rows COMMITS, once per batch, with the
-   * stamped root rows of that batch (the pre-image, as the response lists them) and `ctx.batch`. A
-   * DELETE matching several rows stamps one batch per row, so this runs once per row then.
-   * Best-effort like afterDelete: a throw goes to onError and never changes the response. Not
-   * called when nothing was stamped, nor on a table that is not lifecycle. */
-  afterStamp?: AfterLifecycleHook;
+  /** Inside the transaction, once per matched root row. Return veto(reason) to roll back the
+   * request with 409. Lifecycle rows are pre-images; plain and legacy softDelete rows come from
+   * RETURNING. Throws roll back too. Cascaded children run no hook: guard them with deleteWhen. */
+  beforeDelete?: BeforeLifecycleHook;
+  /** After commit, once per request with its root rows, best-effort. Empty deletes fire nothing.
+   * Each lifecycle row carries its own deletedBatch; ctx.batch is null for a delete request. */
+  afterDelete?: AfterLifecycleHook;
   /** Lifecycle tables only: after `POST {table}/restore` COMMITS, with `[{ <key>: id }]` (the id as
    * the request sent it), `ctx.batch` and `ctx.counts`. Not called for a row deleted before batches
    * existed (batch null). Best-effort: a throw goes to onError and never changes the response. */
@@ -976,11 +958,23 @@ function declaredTables(options: HandlerOptions): Set<string> {
 }
 
 /**
- * Refuse a hook name reserved for a future release, so adding it later is additive and no one
- * ships a hook that is silently ignored. Every other unknown hook key is ignored, as before.
+ * Refuse removed and reserved hook names so a guard cannot be silently ignored.
+ * Other unknown hook keys are ignored, as before.
  */
 function refuseReservedHooks(options: HandlerOptions | undefined): void {
   for (const [tableName, hook] of Object.entries(options?.hooks ?? {})) {
+    for (const [oldName, replacement] of [['beforeStamp', 'beforeDelete'], ['afterStamp', 'afterDelete']]) {
+      if ((hook as Record<string, unknown> | undefined)?.[oldName] !== undefined) {
+        throw new Error(`[everystack/api] hooks.${tableName}.${oldName} was renamed to ${replacement}; update the hook name`);
+      }
+    }
+    if (!isLifecycleTable(tableName, options)) {
+      for (const name of ['beforeDestroy', 'afterDestroy']) {
+        if ((hook as Record<string, unknown> | undefined)?.[name] !== undefined) {
+          throw new Error(`[everystack/model] hooks.${tableName}.${name} runs only when a lifecycle table is destroyed, and ${tableName} is not a lifecycle table. Use beforeDelete or afterDelete, which run at the DELETE`);
+        }
+      }
+    }
     if (hook && (hook as { beforeRestore?: unknown }).beforeRestore !== undefined) {
       throw new Error(`[everystack/api] hooks.${tableName}.beforeRestore is reserved for a future release; remove it`);
     }
@@ -1816,11 +1810,8 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       // 2xx; a throw (a failed commit) skips it, since the write did not happen.
       // A retry wrapper around db.transaction must reset `deferred` per attempt,
       // or the hooks of an aborted attempt would run too.
-      const destroyHook = ownEntry(options?.hooks, tableName);
-      const destroyTransaction = method === 'DELETE'
-        && !isLifecycleTable(tableName, options)
-        && !(isSoftDeleteTable(tableName, table, options) && getSoftDeleteColumn(tableName, table, options))
-        && Boolean(destroyHook?.beforeDestroy || destroyHook?.afterDestroy);
+      const deleteTransaction = method === 'DELETE' && !isLifecycleTable(tableName, options)
+        && Boolean(ownEntry(options?.hooks, tableName)?.beforeDelete);
       const deferred: Deferred[] = [];
       let response: Response;
       try {
@@ -1844,7 +1835,10 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           }
 
           return json({ message: `Method ${method} not allowed` }, 405);
-        }, destroyTransaction);
+        }, deleteTransaction);
+      } catch (err) {
+        if (!(err instanceof BeforeHookThrew)) throw err;
+        response = beforeHookFailure(err.thrown, options, { requestId, name: `${tableName}.beforeDelete`, method: 'DELETE' }, deferred);
       } finally {
         // emitFault never throws, so this cannot replace the error in flight.
         for (const item of deferred) if (item.always) await item.run();
@@ -2759,8 +2753,8 @@ function pickColumns(row: Record<string, unknown>, columns: string[]): Record<st
 
 /**
  * The response for a before-hook that threw. A HandlerError keeps its own status and
- * message. An outage (the hook could not reach the database) answers the fixed 503,
- * like every other outage path. Anything else is a generic 500 so the hook's text
+ * message. Before-hook outages (create, update and delete) answer the fixed 503. Other non-HandlerError
+ * throws answer a generic 500 so the hook's text
  * never reaches the client. A 5xx is a fault and goes to onError; a 4xx HandlerError
  * is a refusal and does not. The fault is queued, not sent: with pgSettings the hook
  * ran inside the transaction, and a slow onError must not hold it open.
@@ -3224,125 +3218,50 @@ async function handleDelete(
 
   const hook = ownEntry(options?.hooks, tableName);
 
-  if (hook?.beforeDelete) {
-    try {
-      await hook.beforeDelete(user, client);
-    } catch (err) {
-      return beforeHookFailure(err, options, { requestId, name: tableName, method: 'DELETE' }, deferred);
-    }
-  }
-
   const conditions = filterResult.conditions;
 
   // Row ownership: AND WHERE <column> = user[<userField>] for IDOR protection
   if (scope.condition) conditions.push(scope.condition);
 
-  // Lifecycle: a real DELETE, which the table's trigger turns into a stamp (it reports 0 rows).
+  const ctx: LifecycleContext = { phase: 'delete', batch: null, user, client };
+  let rows: Record<string, unknown>[];
   if (isLifecycleTable(tableName, options)) {
-    let stamped: Awaited<ReturnType<typeof lifecycleDelete>>;
-    try {
-      stamped = await lifecycleDelete(db, table, tableName, conditions, options, hook?.beforeStamp
-        ? { run: hook.beforeStamp.bind(hook), ctx: { phase: 'stamp', source: 'api', batch: null, user, client } } : undefined);
-    } catch (err) {
-      // Its transaction has rolled back: nothing was stamped.
-      if (err instanceof BeforeHookThrew) return beforeHookFailure(err.thrown, options, { requestId, name: `${tableName}.beforeStamp`, method: 'DELETE' }, deferred);
-      throw err;
-    }
-    const { rows, batchOf } = stamped;
-    // The pre-image carries deletedBatch NULL; give each root its batch. stripHiddenColumns keeps
-    // it for a plain manage role only.
+    const deleted = await lifecycleDelete(db, table, tableName, conditions, options, hook?.beforeDelete
+      ? { run: hook.beforeDelete.bind(hook), ctx } : undefined);
+    rows = deleted.rows;
     const batchKey = columnPropertyName(table, LIFECYCLE_DELETED_BATCH);
-    if (batchKey) for (const [row, batch] of batchOf) row[batchKey] = batch;
-    if (hook?.afterDelete && rows.length > 0) {
-      const { afterDelete } = hook;
-      deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
-        () => afterDelete.call(hook, rows, user, client));
-    }
-    if (hook?.afterStamp && batchOf.size > 0) {
-      const { afterStamp } = hook;
-      const roots = new Map<string, Record<string, unknown>[]>();
-      for (const [row, batch] of batchOf) roots.set(batch, [...(roots.get(batch) ?? []), row]);
-      for (const [batch, batchRoots] of roots) {
-        const ctx: LifecycleContext = { phase: 'stamp', source: 'api', batch, user, client };
-        deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterStamp`, method: 'DELETE' },
-          async () => { await afterStamp.call(hook, batchRoots, ctx); });
-      }
-    }
-    return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
-  }
-
-  // Soft-delete: convert DELETE to UPDATE SET deleted_at = NOW()
-  if (isSoftDeleteTable(tableName, table, options)) {
-    const sdCol = getSoftDeleteColumn(tableName, table, options);
-    if (sdCol) {
-      // Only soft-delete records that aren't already deleted
-      conditions.push(isNull(sdCol));
-      const colName = options?.softDelete?.column || 'deletedAt';
-      let query: any = db.update(table).set({ [colName]: new Date() });
-
-      if (conditions.length === 1) {
-        query = query.where(conditions[0]);
-      } else {
-        query = query.where(and(...conditions));
-      }
-
-      const rows = await query.returning();
-
-      if (hook?.afterDelete && rows.length > 0) {
-        const { afterDelete } = hook;
-        deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
-          () => afterDelete.call(hook, rows, user, client));
-      }
-
-      return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
-    }
-  }
-
-  // Hard delete (no soft-delete configured for this table)
-  let query: any = db.delete(table);
-
-  if (conditions.length === 1) {
-    query = query.where(conditions[0]);
+    if (batchKey) for (const [row, batch] of deleted.batchOf) row[batchKey] = batch;
   } else {
-    query = query.where(and(...conditions));
-  }
-
-  const rows: Record<string, unknown>[] = await query.returning();
-
-  // RETURNING proves DELETE authority, including policies that differ from SELECT.
-  // The dispatcher keeps this statement and beforeDestroy in one caller transaction.
-  // A veto throws out of the caller transaction, so the DELETE rolls back; the dispatcher answers 409.
-  const ctx: DestroyContext = { phase: 'destroy', source: 'api', batch: null, user, client };
-  for (const row of rows) {
-    if (!hook?.beforeDestroy) break;
-    const verdict = await hook.beforeDestroy(row, ctx);
-    if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
-  }
-  if (hook?.afterDestroy) {
-    const { afterDestroy } = hook;
-    for (const row of rows) {
-      deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDestroy`, method: 'DELETE' },
-        async () => { await afterDestroy.call(hook, row, ctx); });
+    const sdCol = isSoftDeleteTable(tableName, table, options) && getSoftDeleteColumn(tableName, table, options);
+    if (sdCol) conditions.push(isNull(sdCol));
+    const query: any = sdCol
+      ? db.update(table).set({ [options?.softDelete?.column || 'deletedAt']: new Date() })
+      : db.delete(table);
+    rows = await query.where(conditions.length === 1 ? conditions[0] : and(...conditions)).returning();
+    // RETURNING proves the caller's write authority. A veto or throw leaves the caller's
+    // transaction, so the statement rolls back before the response is made.
+    if (hook?.beforeDelete) for (const row of rows) {
+      let verdict: unknown;
+      try { verdict = await hook.beforeDelete(row, ctx); } catch (err) { throw new BeforeHookThrew(err); }
+      if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
     }
   }
-
   if (hook?.afterDelete && rows.length > 0) {
     const { afterDelete } = hook;
     deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
-      () => afterDelete.call(hook, rows, user, client));
+      async () => { await afterDelete.call(hook, rows, ctx); });
   }
-
   return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
 }
 
 /**
- * DELETE on a lifecycle table. The trigger stamps each row and cancels its delete, so DELETE
+ * DELETE on a lifecycle table. The trigger marks each row deleted and cancels its removal, so DELETE
  * reports 0 rows and RETURNING has nothing. In one transaction: read the live rows the request
- * matches (the pre-image), run beforeStamp on each, DELETE those keys only (with the same
+ * matches (the pre-image), run beforeDelete on each, DELETE those keys only (with the same
  * conditions), then drop every row still live: RLS or the filter refused its delete. What is left is
  * the pre-image of the rows this request soft-deleted. The read takes no lock, so a hook sees the
- * row as read; a rule that must hold on the stamped values belongs in deleteWhen, which the trigger
- * checks on the current row. Under READ COMMITTED a row another request stamps between the read
+ * row as read; a rule that must hold on the current values belongs in deleteWhen, which the trigger
+ * checks on the current row. Under READ COMMITTED a row another request soft-deletes between the read
  * and the DELETE is still listed (and reaches afterDelete): a false attribution, never a leak.
  */
 async function lifecycleDelete(
@@ -3351,7 +3270,7 @@ async function lifecycleDelete(
   tableName: string,
   conditions: SQL[],
   options?: HandlerOptions,
-  beforeStamp?: { run: BeforeLifecycleHook; ctx: LifecycleContext },
+  beforeDelete?: { run: BeforeLifecycleHook; ctx: LifecycleContext },
 ): Promise<{ rows: Record<string, unknown>[]; batchOf: Map<Record<string, unknown>, string> }> {
   const sdCol = getSoftDeleteColumn(tableName, table, options);
   const pk = primaryKeyColumns(table);
@@ -3365,21 +3284,21 @@ async function lifecycleDelete(
     // No row lock: FOR UPDATE needs UPDATE privilege, which a delete-only role does not hold.
     const matched: Record<string, unknown>[] = await tx.select().from(table).where(and(...conditions, isNull(sdCol)));
     if (matched.length === 0) return [];
-    // beforeStamp: once per matched root, before the DELETE, inside this transaction. A veto or a
-    // throw leaves it, so nothing is stamped.
-    if (beforeStamp) {
+    // beforeDelete: once per matched root, before the DELETE, inside this transaction. A veto or a
+    // throw leaves it, so nothing is soft-deleted.
+    if (beforeDelete) {
       for (const row of matched) {
         let verdict: unknown;
-        try { verdict = await beforeStamp.run(row, beforeStamp.ctx); } catch (err) { throw new BeforeHookThrew(err); }
+        try { verdict = await beforeDelete.run(row, beforeDelete.ctx); } catch (err) { throw new BeforeHookThrew(err); }
         if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
       }
     }
-    // The transition appends one `<JSON key> <batch>` line per stamped root to this setting (a
+    // The transition appends one `<JSON key> <batch>` line per soft-deleted root to this setting (a
     // caller that is not a manage role cannot read deleted_batch). Cleared first, so only this
-    // DELETE's lines are read back; informational, the stamp columns stay the truth.
+    // DELETE's lines are read back; informational, the lifecycle columns stay the truth.
     await tx.execute(sql`SELECT pg_catalog.set_config('everystack.lifecycle_batch', '', true)`);
-    // Exactly the rows the hook saw: a row that starts to match while a hook runs is not stamped.
-    // The request filter stays, so a matched row edited out of it meanwhile is not stamped either.
+    // Exactly the rows the hook saw: a row that starts to match while a hook runs is not soft-deleted.
+    // The request filter stays, so a matched row edited out of it meanwhile is not soft-deleted either.
     const matchedKeys = matched.map(row => row[key]);
     await tx.delete(table).where(and(...conditions, isNull(sdCol), inArray(keyColumn, matchedKeys)));
     const stillLive: Record<string, unknown>[] = await tx
@@ -3393,12 +3312,12 @@ async function lifecycleDelete(
       try { byKey.set(String(JSON.parse(line.slice(0, -37))), line.slice(-36)); } catch { /* not a line the transition wrote */ }
     }
     const live = new Set(stillLive.map(row => String(row[key])));
-    const stamped = matched.filter(row => !live.has(String(row[key])));
-    for (const row of stamped) {
+    const deleted = matched.filter(row => !live.has(String(row[key])));
+    for (const row of deleted) {
       const batch = byKey.get(String(row[key]));
       if (batch) batchOf.set(row, batch);
     }
-    return stamped;
+    return deleted;
   });
   return { rows, batchOf };
 }
@@ -3445,7 +3364,7 @@ async function handleRestore(
     if (hook?.afterRestore && r && typeof r.batch === 'string') {
       try {
         await hook.afterRestore([{ [columnPropertyName(table, key.name) ?? key.name]: id }], {
-          phase: 'restore', source: 'api', batch: r.batch, user, client,
+          phase: 'restore', batch: r.batch, user, client,
           counts: { restored: Number(r.restored), skipped: Number(r.skipped) },
         });
       } catch (err) {

package/src/handler/veto.ts

@@ -26,11 +26,9 @@ export function isVeto(value: unknown): value is HookVeto {
 
 /** The one context every lifecycle hook receives. */
 export interface LifecycleContext {
-  /** `stamp`: the row was marked deleted. `restore`: a batch came back. `destroy`: physical removal. */
-  phase: 'stamp' | 'restore' | 'destroy';
-  /** `api`: a request through createHandler. `purge`: purgeExpired. */
-  source: 'api' | 'purge';
-  /** The lifecycle batch, or null when there is none to report (before a stamp, a non-lifecycle table, a pre-batch row). Never invented. */
+  /** `delete`: a request-level delete. `restore`: a batch came back. `destroy`: physical removal. */
+  phase: 'delete' | 'restore' | 'destroy';
+  /** Request-level deletes use null. Restore and destroy can carry the row's existing batch. */
   batch: string | null;
   user: Record<string, unknown> | null;
   client: Record<string, unknown> | null;
@@ -46,8 +44,8 @@ export interface DestroyContext extends LifecycleContext {
 /** beforeDestroy may return {@link veto}; afterDestroy's return value is ignored. */
 export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | HookVeto | Promise<void | HookVeto>;
 
-/** A before hook of the lifecycle: called once per root row; returns nothing or a veto. */
+/** Before commit, once per matched root row; returns nothing or a veto. Cascaded children run no hook: guard them with deleteWhen. */
 export type BeforeLifecycleHook = (row: Record<string, unknown>, ctx: LifecycleContext) => void | HookVeto | Promise<void | HookVeto>;
 
-/** An after hook of the lifecycle: called after commit with the root rows of one batch. Best-effort. */
+/** After commit, once per request with the root rows. Best-effort; cascaded children run no hook. */
 export type AfterLifecycleHook = (rows: Record<string, unknown>[], ctx: LifecycleContext) => void | Promise<void>;