@willyim/drizzle-audit 0.3.0 → 0.5.0

package/README.md

@@ -43,7 +43,7 @@ await withAuditedTransaction(db, currentUser.id, async (tx) => {
 
 Postgres triggers capture full row snapshots (`old_data`/`new_data` as JSONB) automatically.
 
-### D1/SQLite — App-Level Wrapper (recommended)
+### D1/SQLite — App-Level Wrapper
 
 For D1 and SQLite, the `withAudit` wrapper is the simplest approach. No triggers, no context tables — it intercepts operations in your JS code where you already have the user session.
 
@@ -69,15 +69,17 @@ export const auditLogs = d1AuditLogTable()
 // 3. Use in your app (e.g. React Router action)
 const audit = withAudit(db, auditLogs, { userId: session.userId })
 
-audit.insert(users, { id: "u1", name: "Ada" })
-audit.update(users, eq(users.id, "u1"), { name: "Ada Lovelace" })
-audit.delete(users, eq(users.id, "u1"))
+await audit.insert(users, { id: "u1", name: "Ada" })
+await audit.update(users, eq(users.id, "u1"), { name: "Ada Lovelace" })
+await audit.delete(users, eq(users.id, "u1"))
 
 // Non-audited access is still available
 audit.db.select().from(users).all()
 ```
 
-The wrapper auto-detects primary keys from your Drizzle table schema, captures old/new row data, and runs each operation + audit log insert in a transaction.
+The wrapper auto-detects primary keys from your Drizzle table schema and captures old/new row data. All methods return Promises and must be awaited.
+
+> **Note:** Each operation runs the data write and audit log insert as sequential statements with no transaction wrapper. This is required for D1 compatibility (D1 does not support `BEGIN`/`COMMIT` over the prepared-statement API). In the unlikely event of a failure between the two writes, one may succeed without the other. If you need atomic auditing, use the trigger-based approach instead (see below).
 
 ### D1/SQLite — Triggers
 
@@ -118,47 +120,62 @@ sqlite.exec(createAttachD1AuditTriggersSqlWithColumns([
 ]))
 ```
 
-## Workspace / Tenant Scoping
+## Context Columns
+
+Beyond `user_id`, you can declare arbitrary extra context columns (e.g.
+`workspace_id`, `tenant_id`, `request_id`). Each is an extra `TEXT` column on
+`audit_logs`, populated at write-time from a named runtime context value (a
+Postgres session GUC, or a `_audit_context` KV row in D1).
 
-All three approaches support an optional workspace column for multi-tenant apps.
+```ts
+type AuditContextColumn = {
+  column: string      // audit table column (TEXT, nullable)
+  sessionKey?: string // Postgres GUC the trigger reads — default `app.${column}`
+                      // D1: the _audit_context key — default `${column}`
+  index?: boolean     // create an index on the column — default true
+}
+```
 
 ### Postgres
 
 ```ts
-// Install with workspace column
-createAuditInstallSql({ workspaceIdColumn: "workspace_id" })
-export const auditLogs = pgAuditLogTable({ workspaceIdColumn: "workspace_id" })
+const contextColumns = [{ column: "workspace_id" }, { column: "tenant_id" }]
 
-// Pass workspace at runtime
+createAuditInstallSql({ contextColumns })
+export const auditLogs = pgAuditLogTable({ contextColumns })
+
+// Pass context at runtime (GUC name → value)
 await withAuditedTransaction(
   db, userId, async (tx) => { /* ... */ },
   "app.user_id",
-  { workspaceId: "ws_1" },
+  { context: { "app.workspace_id": "ws_1", "app.tenant_id": "t_1" } },
 )
 ```
 
-To add workspace to an existing install, use `createAuditAddWorkspaceColumnSql()`.
+To add context columns to an existing install, use
+`createAuditAddContextColumnsSql({ contextColumns })` — it adds each column and
+regenerates the trigger over the full set. Pass the complete list of columns the
+table should have.
 
 ### D1 Runtime
 
 ```ts
 const audit = withAudit(db, auditLogs, {
   userId: "user_1",
-  workspaceId: "ws_1",
+  context: { workspace_id: "ws_1", tenant_id: "t_1" },
 })
 ```
 
 ### D1 Triggers
 
 ```ts
-createD1AuditInstallSql({ workspaceIdColumn: "workspace_id" })
-createAttachD1AuditTriggersSql(
-  [{ table: "users" }],
-  { workspaceIdColumn: "workspace_id" },
-)
+const contextColumns = [{ column: "workspace_id" }, { column: "tenant_id" }]
+
+createD1AuditInstallSql({ contextColumns })
+createAttachD1AuditTriggersSql([{ table: "users" }], { contextColumns })
 
 withD1AuditedTransaction(db, "user_1", (tx) => { /* ... */ }, {
-  workspaceId: "ws_1",
+  context: { workspace_id: "ws_1", tenant_id: "t_1" },
 })
 ```
 
@@ -200,10 +217,16 @@ export function createAuditSql() {
 | `createAuditInstallSql(options?)` | SQL to create the audit table, indexes, and trigger function |
 | `createAttachAuditTriggerSql(target, options?)` | SQL to attach audit trigger to one table |
 | `createAttachAuditTriggersSql(targets, options?)` | Same, for multiple tables |
-| `createAuditAddWorkspaceColumnSql(options)` | SQL to add workspace column to existing install |
+| `createAuditAddContextColumnsSql(options)` | SQL to add context columns + regenerate trigger on existing install |
 | `setAuditContext(db, actorId, contextKey?, options?)` | Set actor context in current transaction |
 | `withAuditedTransaction(db, actorId, callback, contextKey?, options?)` | Transaction wrapper with actor context |
 
+### `@willyim/drizzle-audit`
+
+| Export | Description |
+|---|---|
+| `computeDiff(operation, oldData, newData, options?)` | Compute field-by-field diff from old/new row data |
+
 ### `@willyim/drizzle-audit/d1`
 
 | Export | Description |
@@ -231,6 +254,43 @@ export function createAuditSql() {
 - `.delete(table, where)` — Fetch old rows, delete, audit log (per row)
 - `.db` — Raw Drizzle instance for non-audited operations
 
+## Computing Diffs
+
+The `computeDiff` utility produces field-by-field diffs from the `old_data`/`new_data` captured by audit triggers. It works with any operation type and requires no Drizzle dependency.
+
+```ts
+import { computeDiff } from "@willyim/drizzle-audit"
+
+const result = computeDiff(
+  "UPDATE",
+  { id: "u1", name: "Ada", email: "ada@example.com" },
+  { id: "u1", name: "Ada Lovelace", email: "ada@example.com" },
+)
+// {
+//   operation: "UPDATE",
+//   changes: [{ field: "name", old: "Ada", new: "Ada Lovelace" }]
+// }
+```
+
+For INSERT operations, pass `null` as `oldData` — all fields appear as additions. For DELETE, pass `null` as `newData` — all fields appear as removals.
+
+```ts
+// INSERT — every field is new
+computeDiff("INSERT", null, { id: "u1", name: "Ada" })
+
+// DELETE — every field is removed
+computeDiff("DELETE", { id: "u1", name: "Ada" }, null)
+```
+
+By default, `updated_at` and `created_at` fields are excluded. Override with `ignoreFields`:
+
+```ts
+computeDiff("UPDATE", oldData, newData, { ignoreFields: [] }) // include all fields
+computeDiff("UPDATE", oldData, newData, { ignoreFields: ["internal_note"] })
+```
+
+Nested objects are compared using deep equality. Fields are returned sorted alphabetically.
+
 ## Audit Log Schema
 
 ### Postgres
@@ -273,6 +333,27 @@ CREATE TABLE audit_logs (
 | **Bypass risk** | Low (DB-level) | Medium (must use wrapper) | Low (DB-level) |
 | **Best for** | Postgres apps | D1/Cloudflare Workers | SQLite apps needing DB-level guarantees |
 
+## Migrating from 0.2.x → 0.3.0
+
+The `workspace_id`-specific options were removed in favor of the generic
+[Context Columns](#context-columns) API. Mechanical replacements:
+
+| Removed | Replacement |
+|---|---|
+| `pgAuditLogTable({ workspaceIdColumn: "workspace_id" })` | `pgAuditLogTable({ contextColumns: [{ column: "workspace_id" }] })` |
+| `d1AuditLogTable({ workspaceIdColumn: "workspace_id" })` | `d1AuditLogTable({ contextColumns: [{ column: "workspace_id" }] })` |
+| `createAuditInstallSql({ workspaceIdColumn: "workspace_id" })` | `createAuditInstallSql({ contextColumns: [{ column: "workspace_id" }] })` |
+| `createD1AuditInstallSql({ workspaceIdColumn })` | `createD1AuditInstallSql({ contextColumns: [{ column }] })` |
+| `createAttachD1AuditTriggersSql(targets, { workspaceIdColumn })` | `createAttachD1AuditTriggersSql(targets, { contextColumns: [{ column }] })` |
+| `createAuditAddWorkspaceColumnSql(options)` | `createAuditAddContextColumnsSql({ contextColumns: [...] })` |
+| Postgres runtime `{ workspaceId: v }` | `{ context: { "app.workspace_id": v } }` |
+| Postgres runtime `{ workspaceId: v, workspaceContextKey: "app.tenant_id" }` | `{ context: { "app.tenant_id": v } }` |
+| D1 runtime `{ workspaceId: v }` | `{ context: { workspace_id: v } }` |
+| `withAudit(db, table, { userId, workspaceId: v })` | `withAudit(db, table, { userId, context: { workspace_id: v } })` |
+
+The on-disk column name (`workspace_id`) is unchanged, so no data migration is
+needed — only call sites change.
+
 ## License
 
 MIT

package/dist/src/d1/audit-log-schema.d.ts

@@ -1,6 +1,7 @@
+import type { AuditContextColumn } from "./types.js";
 export type D1AuditLogTableOptions = {
-    /** When set (e.g. "workspace_id"), the table definition includes this optional column. */
-    workspaceIdColumn?: string;
+    /** Extra context columns to include in the table definition, matching the install. */
+    contextColumns?: AuditContextColumn[];
 };
 export declare function d1AuditLogTable(options?: D1AuditLogTableOptions): import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
     name: "audit_logs";

package/dist/src/d1/audit-log-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-log-schema.d.ts","sourceRoot":"","sources":["../../../src/d1/audit-log-schema.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,sBAAsB,GAAG;IACnC,0FAA0F;IAC1F,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyB/D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAMtE"}
+{"version":3,"file":"audit-log-schema.d.ts","sourceRoot":"","sources":["../../../src/d1/audit-log-schema.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEpD,MAAM,MAAM,sBAAsB,GAAG;IACnC,sFAAsF;IACtF,cAAc,CAAC,EAAE,kBAAkB,EAAE,CAAA;CACtC,CAAA;AAiBD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuB/D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAMtE"}

package/dist/src/d1/audit-log-schema.js

@@ -1,15 +1,25 @@
 import { index, integer, sqliteTable, text, } from "drizzle-orm/sqlite-core";
+function resolveColumns(options) {
+    const columns = [];
+    const seen = new Set();
+    for (const entry of options?.contextColumns ?? []) {
+        const column = entry.column?.trim();
+        if (column && !seen.has(column)) {
+            seen.add(column);
+            columns.push(column);
+        }
+    }
+    return columns;
+}
 export function d1AuditLogTable(options) {
-    const workspaceIdColumn = options?.workspaceIdColumn?.trim();
+    const contextColumns = resolveColumns(options);
     const columns = {
         id: integer("id").primaryKey({ autoIncrement: true }),
         table_name: text("table_name").notNull(),
         operation: text("operation").notNull(),
         row_id: text("row_id"),
         user_id: text("user_id"),
-        ...(workspaceIdColumn
-            ? { [workspaceIdColumn]: text(workspaceIdColumn) }
-            : {}),
+        ...Object.fromEntries(contextColumns.map((c) => [c, text(c)])),
         old_data: text("old_data"),
         new_data: text("new_data"),
         created_at: text("created_at").notNull().default("(datetime('now'))"),

package/dist/src/d1/index.d.ts

@@ -3,5 +3,6 @@ export type { D1AuditLogTableOptions } from "./audit-log-schema.js";
 export { createAttachD1AuditTriggerSql, createAttachD1AuditTriggersSql, createAttachD1AuditTriggerSqlWithColumns, createAttachD1AuditTriggersSqlWithColumns, createD1AuditInstallSql, } from "./sql.js";
 export type { D1AuditTriggerTargetWithColumns } from "./sql.js";
 export { clearD1AuditContext, setD1AuditContext, withD1AuditedTransaction, } from "./runtime.js";
-export type { D1AuditInstallOptions, D1AuditSqlExecutor, D1AuditTriggerTarget, } from "./types.js";
+export type { D1AuditContextOptions } from "./runtime.js";
+export type { AuditContextColumn, D1AuditInstallOptions, D1AuditSqlExecutor, D1AuditTriggerTarget, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/d1/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/d1/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC5E,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,wCAAwC,EACxC,yCAAyC,EACzC,uBAAuB,GACxB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAA;AAC/D,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,cAAc,CAAA;AAErB,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/d1/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC5E,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EACL,6BAA6B,EAC7B,8BAA8B,EAC9B,wCAAwC,EACxC,yCAAyC,EACzC,uBAAuB,GACxB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,+BAA+B,EAAE,MAAM,UAAU,CAAA;AAC/D,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAEzD,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,YAAY,CAAA"}

package/dist/src/d1/runtime.d.ts

@@ -1,4 +1,9 @@
 import type { D1AuditSqlExecutor } from "./types.js";
+export type D1AuditContextOptions = {
+    /** Map of context key → value written as KV rows the triggers read. */
+    context?: Record<string, string>;
+    contextTable?: string;
+};
 /**
  * Sets the audit context for the current transaction by writing to the
  * _audit_context table. Must be called inside a transaction before any
@@ -6,17 +11,15 @@ import type { D1AuditSqlExecutor } from "./types.js";
  *
  * D1/SQLite has no session variables, so triggers read context from this table.
  */
-export declare function setD1AuditContext(db: D1AuditSqlExecutor, actorId: string, options?: {
-    workspaceId?: string;
-    contextTable?: string;
-}): Promise<unknown> | undefined;
+export declare function setD1AuditContext(db: D1AuditSqlExecutor, actorId: string, options?: D1AuditContextOptions): Promise<unknown> | undefined;
 /**
  * Clears the audit context after a transaction completes.
  * Called automatically by withD1AuditedTransaction.
+ *
+ * Clears `user_id` plus any keys set via `context` so the next transaction
+ * starts clean.
  */
-export declare function clearD1AuditContext(db: D1AuditSqlExecutor, options?: {
-    contextTable?: string;
-}): unknown;
+export declare function clearD1AuditContext(db: D1AuditSqlExecutor, options?: D1AuditContextOptions): unknown;
 /**
  * Wraps a Drizzle SQLite transaction with audit context. Sets the actor
  * before the callback and clears the context after (success or failure).
@@ -37,8 +40,5 @@ export declare function clearD1AuditContext(db: D1AuditSqlExecutor, options?: {
  */
 export declare function withD1AuditedTransaction<TDb extends D1AuditSqlExecutor, TResult>(db: TDb & {
     transaction: (cb: (tx: any) => TResult) => TResult;
-}, actorId: string, callback: (tx: TDb) => TResult, options?: {
-    workspaceId?: string;
-    contextTable?: string;
-}): TResult;
+}, actorId: string, callback: (tx: TDb) => TResult, options?: D1AuditContextOptions): TResult;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/src/d1/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/d1/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAUpD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,gCAyB1D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,kBAAkB,EACtB,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,WAMpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,SAAS,kBAAkB,EAAE,OAAO,EAC9E,EAAE,EAAE,GAAG,GAAG;IAAE,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,KAAK,OAAO,CAAA;CAAE,EAChE,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,EAC9B,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,OAAO,CAWT"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/d1/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAUpD,MAAM,MAAM,qBAAqB,GAAG;IAClC,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAkBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,qBAAqB,gCAwBhC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,kBAAkB,EACtB,OAAO,CAAC,EAAE,qBAAqB,WAYhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,SAAS,kBAAkB,EAAE,OAAO,EAC9E,EAAE,EAAE,GAAG,GAAG;IAAE,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,KAAK,OAAO,CAAA;CAAE,EAChE,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,EAC9B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAWT"}

package/dist/src/d1/runtime.js

@@ -5,6 +5,19 @@ function assertActorId(actorId) {
         throw new Error("actorId must not be empty");
     }
 }
+/**
+ * Builds the KV map (key → value) to write. Empty/undefined values are dropped
+ * so the corresponding column stays NULL.
+ */
+function resolveContext(options) {
+    const context = {};
+    for (const [key, value] of Object.entries(options?.context ?? {})) {
+        if (value !== undefined && value !== "") {
+            context[key] = value;
+        }
+    }
+    return context;
+}
 /**
  * Sets the audit context for the current transaction by writing to the
  * _audit_context table. Must be called inside a transaction before any
@@ -15,26 +28,30 @@ function assertActorId(actorId) {
 export function setD1AuditContext(db, actorId, options) {
     assertActorId(actorId);
     const table = options?.contextTable ?? DEFAULT_CONTEXT_TABLE;
-    const result = db.run(sql `INSERT OR REPLACE INTO ${sql.identifier(table)} (key, value) VALUES ('user_id', ${actorId})`);
+    const context = resolveContext(options);
+    const writeKv = (key, value) => db.run(sql `INSERT OR REPLACE INTO ${sql.identifier(table)} (key, value) VALUES (${key}, ${value})`);
+    const result = writeKv("user_id", actorId);
     // Handle async drivers (D1) by chaining if result is a Promise
     if (result && typeof result.then === "function") {
-        return result.then(() => {
-            if (options?.workspaceId !== undefined && options.workspaceId !== "") {
-                return db.run(sql `INSERT OR REPLACE INTO ${sql.identifier(table)} (key, value) VALUES ('workspace_id', ${options.workspaceId})`);
-            }
-        });
+        return Object.entries(context).reduce((prev, [key, value]) => prev.then(() => writeKv(key, value)), result);
     }
-    if (options?.workspaceId !== undefined && options.workspaceId !== "") {
-        db.run(sql `INSERT OR REPLACE INTO ${sql.identifier(table)} (key, value) VALUES ('workspace_id', ${options.workspaceId})`);
+    for (const [key, value] of Object.entries(context)) {
+        writeKv(key, value);
     }
 }
 /**
  * Clears the audit context after a transaction completes.
  * Called automatically by withD1AuditedTransaction.
+ *
+ * Clears `user_id` plus any keys set via `context` so the next transaction
+ * starts clean.
  */
 export function clearD1AuditContext(db, options) {
     const table = options?.contextTable ?? DEFAULT_CONTEXT_TABLE;
-    return db.run(sql `DELETE FROM ${sql.identifier(table)} WHERE key IN ('user_id', 'workspace_id')`);
+    const keys = ["user_id", ...Object.keys(options?.context ?? {})];
+    const uniqueKeys = [...new Set(keys)];
+    const keyList = sql.join(uniqueKeys.map((k) => sql `${k}`), sql `, `);
+    return db.run(sql `DELETE FROM ${sql.identifier(table)} WHERE key IN (${keyList})`);
 }
 /**
  * Wraps a Drizzle SQLite transaction with audit context. Sets the actor

package/dist/src/d1/sql.d.ts

@@ -2,8 +2,8 @@ import type { D1AuditInstallOptions, D1AuditTriggerTarget } from "./types.js";
 /**
  * Generates SQL to install the audit_logs table and _audit_context table.
  *
- * The _audit_context table stores user_id (and optionally workspace_id) for
- * the current transaction. Since D1/SQLite has no session variables, triggers
+ * The _audit_context table stores user_id (and any configured context columns)
+ * for the current transaction. Since D1/SQLite has no session variables, triggers
  * read context from this table instead.
  */
 export declare function createD1AuditInstallSql(options?: D1AuditInstallOptions): string;

package/dist/src/d1/sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../../src/d1/sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAqB7E;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,qBAA0B,UA6C1E;AAoHD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE,qBAA0B,UAOpC;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,oBAAoB,EAAE,EAC/B,OAAO,GAAE,qBAA0B,UAQpC;AAID,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,GAAG;IACnE,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,CAAA;AA4HD;;;;;;;;;;;GAWG;AACH,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,+BAA+B,EACvC,OAAO,GAAE,qBAA0B,UAUpC;AAED,wBAAgB,yCAAyC,CACvD,OAAO,EAAE,+BAA+B,EAAE,EAC1C,OAAO,GAAE,qBAA0B,UAQpC"}
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../../src/d1/sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAA;AAyEnB;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,qBAA0B,UA8C1E;AAoHD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE,qBAA0B,UAOpC;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,oBAAoB,EAAE,EAC/B,OAAO,GAAE,qBAA0B,UAQpC;AAID,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,GAAG;IACnE,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB,CAAA;AA4HD;;;;;;;;;;;GAWG;AACH,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,+BAA+B,EACvC,OAAO,GAAE,qBAA0B,UAUpC;AAED,wBAAgB,yCAAyC,CACvD,OAAO,EAAE,+BAA+B,EAAE,EAC1C,OAAO,GAAE,qBAA0B,UAQpC"}

package/dist/src/d1/sql.js

@@ -13,29 +13,63 @@ function assertNonEmpty(value, label) {
     }
     return value;
 }
+/**
+ * Normalizes the context columns from the install options, de-duplicating by
+ * column name. For D1 the KV key defaults to the column name itself.
+ */
+function normalizeContextColumns(options) {
+    const resolved = [];
+    const seen = new Set();
+    for (const entry of options.contextColumns ?? []) {
+        const column = entry.column?.trim();
+        if (!column) {
+            throw new Error("contextColumns[].column must not be empty");
+        }
+        if (seen.has(column)) {
+            continue;
+        }
+        seen.add(column);
+        resolved.push({
+            column,
+            sessionKey: entry.sessionKey?.trim() || column,
+            index: entry.index ?? true,
+        });
+    }
+    return resolved;
+}
+/** Builds the column-name suffix for an INSERT column list. */
+function contextColsClause(contextColumns) {
+    return contextColumns.map((c) => `, ${quoteIdent(c.column)}`).join("");
+}
+/** Builds the matching VALUES suffix that reads each KV row from the context table. */
+function contextValuesClause(contextColumns, contextTable) {
+    return contextColumns
+        .map((c) => `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = ${quoteLiteral(c.sessionKey)})`)
+        .join("");
+}
 /**
  * Generates SQL to install the audit_logs table and _audit_context table.
  *
- * The _audit_context table stores user_id (and optionally workspace_id) for
- * the current transaction. Since D1/SQLite has no session variables, triggers
+ * The _audit_context table stores user_id (and any configured context columns)
+ * for the current transaction. Since D1/SQLite has no session variables, triggers
  * read context from this table instead.
  */
 export function createD1AuditInstallSql(options = {}) {
     const auditTable = assertNonEmpty(options.auditTable ?? DEFAULT_AUDIT_TABLE, "auditTable");
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     const auditColumns = [
         "id INTEGER PRIMARY KEY AUTOINCREMENT",
         "table_name TEXT NOT NULL",
         "operation TEXT NOT NULL CHECK (operation IN ('INSERT', 'UPDATE', 'DELETE'))",
         "row_id TEXT",
         "user_id TEXT",
-        ...(workspaceIdColumn ? [`${quoteIdent(workspaceIdColumn)} TEXT`] : []),
+        ...contextColumns.map((c) => `${quoteIdent(c.column)} TEXT`),
         "old_data TEXT",
         "new_data TEXT",
         "created_at TEXT NOT NULL DEFAULT (datetime('now'))",
     ];
-    const contextColumns = [
+    const contextTableColumns = [
         "key TEXT PRIMARY KEY",
         "value TEXT",
     ];
@@ -43,16 +77,14 @@ export function createD1AuditInstallSql(options = {}) {
         `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${auditTable}_table_name_idx`)} ON ${quoteIdent(auditTable)} (table_name);`,
         `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${auditTable}_row_id_idx`)} ON ${quoteIdent(auditTable)} (row_id);`,
         `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${auditTable}_user_id_idx`)} ON ${quoteIdent(auditTable)} (user_id);`,
-        ...(workspaceIdColumn
-            ? [
-                `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${auditTable}_${workspaceIdColumn}_idx`)} ON ${quoteIdent(auditTable)} (${quoteIdent(workspaceIdColumn)});`,
-            ]
-            : []),
+        ...contextColumns
+            .filter((c) => c.index)
+            .map((c) => `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${auditTable}_${c.column}_idx`)} ON ${quoteIdent(auditTable)} (${quoteIdent(c.column)});`),
         `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${auditTable}_created_at_idx`)} ON ${quoteIdent(auditTable)} (created_at);`,
     ];
     return [
         `CREATE TABLE IF NOT EXISTS ${quoteIdent(auditTable)} (\n  ${auditColumns.join(",\n  ")}\n);`,
-        `CREATE TABLE IF NOT EXISTS ${quoteIdent(contextTable)} (\n  ${contextColumns.join(",\n  ")}\n);`,
+        `CREATE TABLE IF NOT EXISTS ${quoteIdent(contextTable)} (\n  ${contextTableColumns.join(",\n  ")}\n);`,
         ...indexStatements,
     ].join("\n\n");
 }
@@ -63,7 +95,7 @@ function buildInsertTriggerSql(target, options) {
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
     const triggerPrefix = target.triggerPrefix ?? table;
     const triggerName = `${triggerPrefix}_audit_insert`;
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     return `
 DROP TRIGGER IF EXISTS ${quoteIdent(triggerName)};
 
@@ -71,12 +103,12 @@ CREATE TRIGGER ${quoteIdent(triggerName)}
 AFTER INSERT ON ${quoteIdent(table)}
 FOR EACH ROW
 BEGIN
-  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${workspaceIdColumn ? `, ${quoteIdent(workspaceIdColumn)}` : ""})
+  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${contextColsClause(contextColumns)})
   VALUES (
     ${quoteLiteral(table)},
     'INSERT',
     NEW.${quoteIdent(rowIdColumn)},
-    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${workspaceIdColumn ? `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'workspace_id')` : ""}
+    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${contextValuesClause(contextColumns, contextTable)}
   );
 END;`.trim();
 }
@@ -87,7 +119,7 @@ function buildUpdateTriggerSql(target, options) {
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
     const triggerPrefix = target.triggerPrefix ?? table;
     const triggerName = `${triggerPrefix}_audit_update`;
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     return `
 DROP TRIGGER IF EXISTS ${quoteIdent(triggerName)};
 
@@ -95,12 +127,12 @@ CREATE TRIGGER ${quoteIdent(triggerName)}
 AFTER UPDATE ON ${quoteIdent(table)}
 FOR EACH ROW
 BEGIN
-  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${workspaceIdColumn ? `, ${quoteIdent(workspaceIdColumn)}` : ""})
+  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${contextColsClause(contextColumns)})
   VALUES (
     ${quoteLiteral(table)},
     'UPDATE',
     NEW.${quoteIdent(rowIdColumn)},
-    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${workspaceIdColumn ? `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'workspace_id')` : ""}
+    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${contextValuesClause(contextColumns, contextTable)}
   );
 END;`.trim();
 }
@@ -111,7 +143,7 @@ function buildDeleteTriggerSql(target, options) {
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
     const triggerPrefix = target.triggerPrefix ?? table;
     const triggerName = `${triggerPrefix}_audit_delete`;
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     return `
 DROP TRIGGER IF EXISTS ${quoteIdent(triggerName)};
 
@@ -119,12 +151,12 @@ CREATE TRIGGER ${quoteIdent(triggerName)}
 AFTER DELETE ON ${quoteIdent(table)}
 FOR EACH ROW
 BEGIN
-  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${workspaceIdColumn ? `, ${quoteIdent(workspaceIdColumn)}` : ""})
+  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${contextColsClause(contextColumns)})
   VALUES (
     ${quoteLiteral(table)},
     'DELETE',
     OLD.${quoteIdent(rowIdColumn)},
-    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${workspaceIdColumn ? `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'workspace_id')` : ""}
+    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${contextValuesClause(contextColumns, contextTable)}
   );
 END;`.trim();
 }
@@ -160,7 +192,7 @@ function buildInsertTriggerWithColumnsSql(target, options) {
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
     const triggerPrefix = target.triggerPrefix ?? table;
     const triggerName = `${triggerPrefix}_audit_insert`;
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     return `
 DROP TRIGGER IF EXISTS ${quoteIdent(triggerName)};
 
@@ -168,12 +200,12 @@ CREATE TRIGGER ${quoteIdent(triggerName)}
 AFTER INSERT ON ${quoteIdent(table)}
 FOR EACH ROW
 BEGIN
-  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${workspaceIdColumn ? `, ${quoteIdent(workspaceIdColumn)}` : ""}, new_data)
+  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${contextColsClause(contextColumns)}, new_data)
   VALUES (
     ${quoteLiteral(table)},
     'INSERT',
     NEW.${quoteIdent(rowIdColumn)},
-    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${workspaceIdColumn ? `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'workspace_id')` : ""},
+    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${contextValuesClause(contextColumns, contextTable)},
     ${buildJsonObjectExpr(target.columns, "NEW")}
   );
 END;`.trim();
@@ -185,7 +217,7 @@ function buildUpdateTriggerWithColumnsSql(target, options) {
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
     const triggerPrefix = target.triggerPrefix ?? table;
     const triggerName = `${triggerPrefix}_audit_update`;
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     return `
 DROP TRIGGER IF EXISTS ${quoteIdent(triggerName)};
 
@@ -193,12 +225,12 @@ CREATE TRIGGER ${quoteIdent(triggerName)}
 AFTER UPDATE ON ${quoteIdent(table)}
 FOR EACH ROW
 BEGIN
-  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${workspaceIdColumn ? `, ${quoteIdent(workspaceIdColumn)}` : ""}, old_data, new_data)
+  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${contextColsClause(contextColumns)}, old_data, new_data)
   VALUES (
     ${quoteLiteral(table)},
     'UPDATE',
     NEW.${quoteIdent(rowIdColumn)},
-    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${workspaceIdColumn ? `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'workspace_id')` : ""},
+    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${contextValuesClause(contextColumns, contextTable)},
     ${buildJsonObjectExpr(target.columns, "OLD")},
     ${buildJsonObjectExpr(target.columns, "NEW")}
   );
@@ -211,7 +243,7 @@ function buildDeleteTriggerWithColumnsSql(target, options) {
     const contextTable = assertNonEmpty(options.contextTable ?? DEFAULT_CONTEXT_TABLE, "contextTable");
     const triggerPrefix = target.triggerPrefix ?? table;
     const triggerName = `${triggerPrefix}_audit_delete`;
-    const workspaceIdColumn = options.workspaceIdColumn?.trim();
+    const contextColumns = normalizeContextColumns(options);
     return `
 DROP TRIGGER IF EXISTS ${quoteIdent(triggerName)};
 
@@ -219,12 +251,12 @@ CREATE TRIGGER ${quoteIdent(triggerName)}
 AFTER DELETE ON ${quoteIdent(table)}
 FOR EACH ROW
 BEGIN
-  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${workspaceIdColumn ? `, ${quoteIdent(workspaceIdColumn)}` : ""}, old_data)
+  INSERT INTO ${quoteIdent(auditTable)} (table_name, operation, row_id, user_id${contextColsClause(contextColumns)}, old_data)
   VALUES (
     ${quoteLiteral(table)},
     'DELETE',
     OLD.${quoteIdent(rowIdColumn)},
-    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${workspaceIdColumn ? `,\n    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'workspace_id')` : ""},
+    (SELECT value FROM ${quoteIdent(contextTable)} WHERE key = 'user_id')${contextValuesClause(contextColumns, contextTable)},
     ${buildJsonObjectExpr(target.columns, "OLD")}
   );
 END;`.trim();

package/dist/src/d1/types.d.ts

@@ -6,13 +6,21 @@ import type { SQL } from "drizzle-orm";
 export type D1AuditSqlExecutor = {
     run: (query: SQL) => unknown;
 };
+export type AuditContextColumn = {
+    /** Column added to the audit table (TEXT, nullable). */
+    column: string;
+    /** The `_audit_context` key the trigger reads. Default `${column}`. */
+    sessionKey?: string;
+    /** Create an index on the column. Default true. */
+    index?: boolean;
+};
 export type D1AuditInstallOptions = {
     /** Name of the audit log table (default: "audit_logs") */
     auditTable?: string;
     /** Name of the context table used to pass user_id to triggers (default: "_audit_context") */
     contextTable?: string;
-    /** Optional workspace column name (e.g. "workspace_id") */
-    workspaceIdColumn?: string;
+    /** Extra context columns added to the audit table and populated by triggers from the _audit_context KV table. */
+    contextColumns?: AuditContextColumn[];
 };
 export type D1AuditTriggerTarget = {
     table: string;