keryx 0.17.1 → 0.19.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,13 +29,18 @@ 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 { type PaginatedResult, paginate } from "./util/pagination";
 export { toMarkdown } from "./util/toMarkdown";
+export type { DbOrTransaction, Transaction } from "./util/transaction";
+export { withTransaction } from "./util/transaction";
 export {
   isSecret,
+  paginationInputs,
   secret,
   zBooleanFromString,
   zIdOrModel,

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.1",
+  "version": "0.19.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/util/pagination.ts

@@ -0,0 +1,54 @@
+/**
+ * Standardized pagination response envelope.
+ */
+export interface PaginatedResult<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    pages: number;
+  };
+}
+
+/**
+ * Applies pagination to a Drizzle select query and returns a standardized envelope.
+ *
+ * Runs the data query (with LIMIT/OFFSET) and a COUNT query in parallel for efficiency.
+ * The caller provides both queries separately so they can use different joins or WHERE
+ * clauses for the count (e.g., skipping expensive JOINs that don't affect the total).
+ *
+ * @param query - A Drizzle select query builder that has not yet had `.limit()` or
+ *   `.offset()` applied. Must support chaining `.limit(n).offset(n)`.
+ * @param countQuery - A promise resolving to `[{ count: number }]`. Typically built with
+ *   `db.select({ count: count() }).from(table).where(...)`.
+ * @param params - Object with `page` (1-indexed) and `limit`, matching the output of
+ *   `paginationInputs()`.
+ * @returns A `PaginatedResult<T>` containing the `data` array and `pagination` metadata.
+ */
+export async function paginate<T>(
+  query: {
+    limit: (n: number) => { offset: (n: number) => PromiseLike<T[]> };
+  },
+  countQuery: PromiseLike<{ count: number }[]>,
+  params: { page: number; limit: number },
+): Promise<PaginatedResult<T>> {
+  const offset = (params.page - 1) * params.limit;
+
+  const [data, countResult] = await Promise.all([
+    query.limit(params.limit).offset(offset),
+    countQuery,
+  ]);
+
+  const total = Number(countResult[0]?.count ?? 0);
+
+  return {
+    data,
+    pagination: {
+      page: params.page,
+      limit: params.limit,
+      total,
+      pages: Math.ceil(total / params.limit),
+    },
+  };
+}

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();
+  }
+}

package/util/zodMixins.ts

@@ -46,6 +46,39 @@ export function zBooleanFromString() {
   });
 }
 
+/**
+ * Creates a Zod schema for pagination inputs with sensible defaults.
+ * Returns `{ page, limit }` where `page` is 1-indexed.
+ *
+ * @param options - Optional overrides for default values and bounds.
+ * @param options.defaultLimit - Default number of items per page (default: 25).
+ * @param options.maxLimit - Maximum allowed items per page (default: 100).
+ * @returns A Zod object schema with `page` and `limit` fields.
+ */
+export function paginationInputs(options?: {
+  defaultLimit?: number;
+  maxLimit?: number;
+}) {
+  const defaultLimit = options?.defaultLimit ?? 25;
+  const maxLimit = options?.maxLimit ?? 100;
+
+  return z.object({
+    page: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .default(1)
+      .describe("Page number (1-indexed)"),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(maxLimit)
+      .default(defaultLimit)
+      .describe("Number of items per page"),
+  });
+}
+
 // Type for Drizzle tables with an id column
 type TableWithId = { id: any; $inferSelect: any };