keryx 0.17.0 → 0.18.0

package/classes/Action.ts

@@ -116,11 +116,19 @@ export type ActionMiddleware = {
     connection: Connection,
   ) => Promise<ActionMiddlewareResponse | void>;
   /**
-   * Runs after the action's `run()` method. Can replace the response by returning `{ updatedResponse }`.
+   * Runs after the action's `run()` method (in a `finally` block, so it always runs).
+   * Can replace the response by returning `{ updatedResponse }`.
+   *
+   * @param params - The validated action inputs (same object passed to `run()`).
+   * @param connection - The connection that initiated this action.
+   * @param error - The `TypedError` from the action's `run()`, or `undefined` on success.
+   *   Useful for middleware that needs to react to success/failure (e.g., committing or
+   *   rolling back a database transaction).
    */
   runAfter?: (
     params: ActionParams<Action>,
     connection: Connection,
+    error?: TypedError,
   ) => Promise<ActionMiddlewareResponse | void>;
 };
 

package/classes/Connection.ts

@@ -43,8 +43,10 @@ export class Connection<
   rateLimitInfo?: RateLimitInfo;
   /** Request correlation ID for distributed tracing. Propagated from the incoming `X-Request-Id` header when `config.server.web.correlationId.trustProxy` is enabled. */
   correlationId?: string;
-  /** App-defined request-scoped metadata. Reset to `{}` at the start of each `act()` call so that long-lived connections (e.g., WebSockets) don't leak state between actions. */
+  /** App-defined request-scoped metadata. Reset to `{}` at the start of each top-level `act()` call so that long-lived connections (e.g., WebSockets) don't leak state between actions. Preserved across nested `act()` calls so that middleware state (e.g., an open transaction) propagates to sub-actions. */
   metadata: Partial<TMeta>;
+  /** @internal Tracks nested `act()` depth so metadata is only reset on the outermost call. */
+  private _actDepth = 0;
 
   /**
    * Create a new connection and register it in `api.connections`.
@@ -94,7 +96,11 @@ export class Connection<
     method: Request["method"] = "",
     url: string = "",
   ): Promise<{ response: Object; error?: TypedError }> {
-    this.metadata = {};
+    // Only reset metadata on the outermost act() call. Nested calls (action
+    // chaining) preserve the parent's metadata so middleware state like an
+    // open database transaction propagates to sub-actions.
+    if (this._actDepth === 0) this.metadata = {};
+    this._actDepth++;
     const reqStartTime = new Date().getTime();
     let loggerResponsePrefix: "OK" | "ERROR" = "OK";
     let response: Object = {};
@@ -164,6 +170,7 @@ export class Connection<
             const middlewareResponse = await middleware.runAfter(
               formattedParams,
               this,
+              error,
             );
             if (middlewareResponse && middlewareResponse?.updatedResponse) {
               if (response instanceof StreamingResponse) {
@@ -177,6 +184,7 @@ export class Connection<
           }
         }
       }
+      this._actDepth--;
     }
 
     const duration = new Date().getTime() - reqStartTime;

package/index.ts

@@ -29,11 +29,14 @@ export { ErrorStatusCodes, ErrorType, TypedError } from "./classes/TypedError";
 export type { KeryxConfig } from "./config";
 export type { SessionData } from "./initializers/session";
 export { checkRateLimit, RateLimitMiddleware } from "./middleware/rateLimit";
+export { TransactionMiddleware } from "./middleware/transaction";
 export type { WebServer } from "./servers/web";
 export { buildProgram } from "./util/cli";
 export { deepMerge, loadFromEnvIfSet } from "./util/config";
 export { globLoader } from "./util/glob";
 export { toMarkdown } from "./util/toMarkdown";
+export type { DbOrTransaction, Transaction } from "./util/transaction";
+export { withTransaction } from "./util/transaction";
 export {
   isSecret,
   secret,

package/middleware/transaction.ts

@@ -0,0 +1,95 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import type { PoolClient } from "pg";
+import { api, logger } from "../api";
+import type { ActionMiddleware } from "../classes/Action";
+import type { Connection } from "../classes/Connection";
+import type { TypedError } from "../classes/TypedError";
+import type { Transaction } from "../util/transaction";
+
+/**
+ * Action middleware that wraps the entire action execution in a database transaction.
+ *
+ * In `runBefore`, a dedicated `PoolClient` is acquired from `api.db.pool`, a `BEGIN`
+ * is issued, and a transaction-scoped Drizzle instance is stored on
+ * `connection.metadata.transaction`. Actions and ops functions should use this
+ * instance (instead of `api.db.db`) for all queries that must be atomic.
+ *
+ * In `runAfter`, the transaction is committed on success or rolled back if the
+ * action threw an error. The pool client is always released.
+ *
+ * **Re-entrant**: When a parent action already opened a transaction (e.g., via
+ * `connection.act()` chaining), the middleware reuses the existing transaction
+ * instead of opening a new one. Only the outermost middleware instance commits
+ * or rolls back.
+ *
+ * @example
+ * ```ts
+ * import { Action, HTTP_METHOD, TransactionMiddleware, type ActionParams, type Connection } from "keryx";
+ *
+ * export class TransferFunds extends Action {
+ *   constructor() {
+ *     super({
+ *       name: "transfer:funds",
+ *       middleware: [SessionMiddleware, TransactionMiddleware],
+ *       web: { route: "/transfer", method: HTTP_METHOD.POST },
+ *       inputs: z.object({ fromId: z.number(), toId: z.number(), amount: z.number() }),
+ *     });
+ *   }
+ *
+ *   async run(params: ActionParams<TransferFunds>, connection: Connection) {
+ *     const tx = connection.metadata.transaction;
+ *     await tx.update(accounts).set(...).where(eq(accounts.id, params.fromId));
+ *     await tx.update(accounts).set(...).where(eq(accounts.id, params.toId));
+ *     return { success: true };
+ *   }
+ * }
+ * ```
+ */
+export const TransactionMiddleware: ActionMiddleware = {
+  runBefore: async (
+    _params: Record<string, unknown>,
+    connection: Connection,
+  ) => {
+    // If a parent action already opened a transaction, reuse it.
+    // Track depth so only the outermost middleware commits/rolls back.
+    const depth = (connection.metadata._txDepth as number | undefined) ?? 0;
+    connection.metadata._txDepth = depth + 1;
+
+    if (depth > 0) return; // already inside a transaction — nothing to do
+
+    const client: PoolClient = await api.db.pool.connect();
+    await client.query("BEGIN");
+    const tx = drizzle(client) as Transaction;
+    connection.metadata.transaction = tx;
+    connection.metadata._txClient = client;
+  },
+
+  runAfter: async (
+    _params: Record<string, unknown>,
+    connection: Connection,
+    error?: TypedError,
+  ) => {
+    const depth = (connection.metadata._txDepth as number | undefined) ?? 0;
+    connection.metadata._txDepth = Math.max(0, depth - 1);
+
+    // Only the outermost middleware manages the transaction lifecycle
+    if (depth > 1) return;
+
+    const client = connection.metadata._txClient as PoolClient | undefined;
+    if (!client) return;
+
+    try {
+      if (error) {
+        await client.query("ROLLBACK");
+        logger.debug("transaction rolled back");
+      } else {
+        await client.query("COMMIT");
+        logger.debug("transaction committed");
+      }
+    } finally {
+      client.release();
+      connection.metadata.transaction = undefined;
+      connection.metadata._txClient = undefined;
+    }
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",
@@ -99,7 +99,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "^1.1.8",
     "@types/formidable": "^3.4.6",
     "drizzle-kit": "^0.31.9",
     "drizzle-zod": "^0.8.3"

package/util/transaction.ts

@@ -0,0 +1,81 @@
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { api, logger } from "../api";
+import { ErrorType, TypedError } from "../classes/TypedError";
+
+/**
+ * A Drizzle database instance scoped to a single PostgreSQL connection.
+ * Returned by {@link withTransaction} and stored on `connection.metadata.transaction`
+ * by `TransactionMiddleware`. Shares the same query-builder interface as `api.db.db`,
+ * so ops functions can accept either without changing their query code.
+ */
+export type Transaction = NodePgDatabase<Record<string, never>>;
+
+/**
+ * Union of the top-level Drizzle database and a transaction-scoped instance.
+ * Use this as the `db` parameter type in ops/helper functions so callers can
+ * pass either `api.db.db` (no transaction) or a `Transaction` from middleware.
+ *
+ * @example
+ * ```ts
+ * import { api, type DbOrTransaction } from "keryx";
+ * import { users } from "../schema/users";
+ *
+ * export async function findUserByEmail(email: string, db: DbOrTransaction = api.db.db) {
+ *   return db.select().from(users).where(eq(users.email, email)).limit(1);
+ * }
+ * ```
+ */
+export type DbOrTransaction = NodePgDatabase<Record<string, never>>;
+
+/**
+ * Run a callback inside a database transaction with automatic commit/rollback.
+ *
+ * Acquires a dedicated `PoolClient` from `api.db.pool`, issues `BEGIN`, and
+ * creates a Drizzle instance scoped to that client. If `fn` resolves, the
+ * transaction is committed; if it throws, the transaction is rolled back and
+ * the error is re-thrown. The pool client is always released.
+ *
+ * For request-scoped transactions that span middleware + action execution,
+ * use `TransactionMiddleware` instead — it manages the same lifecycle
+ * automatically via `connection.metadata.transaction`.
+ *
+ * @param fn - Async callback that receives a transaction-scoped Drizzle instance.
+ *   All queries executed through `tx` participate in the same transaction.
+ * @returns The value returned by `fn`.
+ * @throws {TypedError} Re-throws `TypedError` directly. Wraps other errors in
+ *   a `TypedError` with `ErrorType.CONNECTION_ACTION_RUN`.
+ *
+ * @example
+ * ```ts
+ * const user = await withTransaction(async (tx) => {
+ *   const [created] = await tx.insert(users).values({ name: "Alice" }).returning();
+ *   await tx.insert(auditLogs).values({ action: "user:create", userId: created.id });
+ *   return created;
+ * });
+ * ```
+ */
+export async function withTransaction<T>(
+  fn: (tx: Transaction) => Promise<T>,
+): Promise<T> {
+  const client = await api.db.pool.connect();
+  try {
+    await client.query("BEGIN");
+    const tx = drizzle(client) as Transaction;
+    const result = await fn(tx);
+    await client.query("COMMIT");
+    logger.debug("transaction committed");
+    return result;
+  } catch (e) {
+    await client.query("ROLLBACK");
+    logger.debug("transaction rolled back");
+    if (e instanceof TypedError) throw e;
+    throw new TypedError({
+      message: `${e}`,
+      type: ErrorType.CONNECTION_ACTION_RUN,
+      originalError: e,
+    });
+  } finally {
+    client.release();
+  }
+}