ezlogs-nextjs 0.1.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +106 -11
  2. package/bin/install-triggers.cjs +49 -11
  3. package/dist/actors/index.d.cts +1 -1
  4. package/dist/actors/index.d.ts +1 -1
  5. package/dist/{configuration-3Pei_XZ_.d.cts → configuration-OHLNivON.d.cts} +11 -20
  6. package/dist/{configuration-3Pei_XZ_.d.ts → configuration-OHLNivON.d.ts} +11 -20
  7. package/dist/db/drizzle.cjs +154 -18
  8. package/dist/db/drizzle.js +154 -18
  9. package/dist/db/prisma.cjs +242 -45
  10. package/dist/db/prisma.d.cts +39 -1
  11. package/dist/db/prisma.d.ts +39 -1
  12. package/dist/db/prisma.js +241 -46
  13. package/dist/db/supabase.cjs +154 -18
  14. package/dist/db/supabase.js +154 -18
  15. package/dist/index.cjs +761 -245
  16. package/dist/index.d.cts +2 -2
  17. package/dist/index.d.ts +2 -2
  18. package/dist/index.js +761 -245
  19. package/dist/jobs/bullmq.cjs +973 -16
  20. package/dist/jobs/bullmq.d.cts +8 -3
  21. package/dist/jobs/bullmq.d.ts +8 -3
  22. package/dist/jobs/bullmq.js +973 -16
  23. package/dist/jobs/inngest.cjs +880 -14
  24. package/dist/jobs/inngest.d.cts +7 -5
  25. package/dist/jobs/inngest.d.ts +7 -5
  26. package/dist/jobs/inngest.js +880 -14
  27. package/dist/jobs/supabase-queues.cjs +878 -16
  28. package/dist/jobs/supabase-queues.js +878 -16
  29. package/dist/jobs/trigger.cjs +914 -42
  30. package/dist/jobs/trigger.js +914 -42
  31. package/dist/jobs/upstash-workflow.cjs +914 -14
  32. package/dist/jobs/upstash-workflow.d.cts +16 -2
  33. package/dist/jobs/upstash-workflow.d.ts +16 -2
  34. package/dist/jobs/upstash-workflow.js +914 -15
  35. package/dist/triggers/index.cjs +405 -76
  36. package/dist/triggers/index.d.cts +36 -41
  37. package/dist/triggers/index.d.ts +36 -41
  38. package/dist/triggers/index.js +404 -74
  39. package/package.json +5 -1
  40. package/sql/postgres/00_install.sql +244 -21
@@ -117,17 +117,15 @@ interface PgLikeClient {
117
117
  declare function withDatabaseContext<T>(client: PgLikeClient, callback: (client: PgLikeClient) => Promise<T>): Promise<T>;
118
118
 
119
119
  /**
120
- * Shape of one row returned by the audit-log SELECT. Matches the
121
- * column list in `00_install.sql` exactly. Drivers vary on how they
120
+ * Shape of one row returned by the audit-log query. Matches the
121
+ * column list in `00_install.sql`. Drivers vary on how they
122
122
  * deserialize jsonb (`pg` returns plain objects; some serverless
123
123
  * drivers return strings) — `coerceJsonb` below handles both.
124
124
  */
125
125
  interface AuditRow {
126
126
  /**
127
127
  * The audit log row's primary key, stringified. Used only for
128
- * within-request emit dedup — never reaches the wire. We stringify
129
- * here so drivers that return bigint, number, or string all live in
130
- * one Set comparable type.
128
+ * within-request emit dedup — never reaches the wire.
131
129
  */
132
130
  id: string;
133
131
  table_name: string;
@@ -135,41 +133,40 @@ interface AuditRow {
135
133
  old_row: Record<string, unknown> | string | null;
136
134
  new_row: Record<string, unknown> | string | null;
137
135
  resource_id: string | null;
136
+ /** Stored correlation id (null when the write couldn't be tagged). */
137
+ correlation_id?: string | null;
138
+ /** Postgres transaction id — groups untagged rows into one action. */
139
+ txid?: string | null;
140
+ /** When the trigger fired — becomes the event timestamp. */
141
+ captured_at?: Date | null;
138
142
  }
139
143
  /**
140
- * Fetch audit rows tagged with `correlationId` in capture order.
144
+ * Claim (delete + return) the audit rows tagged with `correlationId`,
145
+ * oldest first. A row can only be claimed once, so concurrent flushes
146
+ * never emit the same row twice.
141
147
  *
142
- * Returns rows oldest-first (matches the trigger's `clock_timestamp`
143
- * within a transaction) so the dashboard renders them chronologically.
148
+ * If the reader role may not DELETE, falls back to a plain SELECT
149
+ * (rows then stay until the customer cleans them up) and warns once.
144
150
  *
145
- * Errors are caught and returned as `[]` — a failed audit read must
146
- * never break the host request. The error is logged at debug.
147
- */
148
- declare function readAuditRows(exec: SqlExecutor, correlationId: string,
149
- /**
150
- * Snapshot of `MAX(id)` taken at the start of the request. Used as
151
- * the lower bound for the time-window fallback path that catches
152
- * rows whose `correlation_id` is NULL — i.e., supabase-js writes
153
- * that didn't go through SET LOCAL because PostgREST doesn't
154
- * expose explicit transactions to the client.
151
+ * `since` limits the claim to rows written at or after that moment
152
+ * (a job claims only what it wrote, never the enqueuing request's rows).
155
153
  *
156
- * When null, the reader falls back to correlation-only matching
157
- * (Phase 5 primary path).
154
+ * Errors are caught and returned as `[]` — a failed audit read must
155
+ * never break the host request.
158
156
  */
159
- snapshotMaxId?: bigint | null): Promise<AuditRow[]>;
157
+ declare function readAuditRows(exec: SqlExecutor, correlationId: string, since?: Date | null): Promise<AuditRow[]>;
160
158
  /**
161
- * Take a snapshot of the current `MAX(id)` from `ezlogs_audit_log` and
162
- * store it on the per-request scope. Called at the start of each HTTP
163
- * request when `databaseReader` is configured. The reader's time-window
164
- * fallback uses this as the lower bound for catching supabase-js writes
165
- * (rows whose `correlation_id` is NULL because PostgREST didn't run
166
- * inside our explicit transaction).
159
+ * Drain rows no request will claim: untagged rows, and tagged rows
160
+ * older than ORPHAN_AGE. Each is emitted under its stored correlation
161
+ * id, or — when it has none — under one fresh id per database
162
+ * transaction, always with no actor. Never attributes a row to the
163
+ * request that happens to run the sweep.
167
164
  *
168
- * Errors are swallowed — a failed snapshot just means the time-window
169
- * fallback degrades to "match correlation_id only" for this request.
170
- * Never break the host's request over a bookkeeping query.
165
+ * Returns the number of rows emitted. Errors are swallowed.
171
166
  */
172
- declare function takeAuditSnapshot(exec: SqlExecutor): Promise<void>;
167
+ declare function sweepAuditLog(exec: SqlExecutor): Promise<number>;
168
+ /** Delete rows older than PRUNE_AGE without emitting them. Errors swallowed. */
169
+ declare function pruneAuditLog(exec: SqlExecutor): Promise<void>;
173
170
  /**
174
171
  * Detect which tables have the `ezlogs_audit` trigger attached. Used
175
172
  * by the per-ORM adapters to decide whether their per-mutation emit
@@ -196,20 +193,18 @@ declare function detectTriggerTrackedTables(exec: SqlExecutor): Promise<Set<stri
196
193
  */
197
194
  declare function emitAuditRows(rows: ReadonlyArray<AuditRow>): void;
198
195
  /**
199
- * End-of-request entry point. Reads rows for the current correlation
200
- * id and emits each one. Skips when no correlation is in scope (no
201
- * way to match rows back to this request) or no exec is supplied.
196
+ * End-of-request entry point. Claims rows for the current correlation
197
+ * id and emits each one, then runs the throttled sweep (untagged /
198
+ * orphaned rows, as their own actions) and prune. Skips when no
199
+ * correlation is in scope or no exec is supplied.
202
200
  *
203
201
  * The HTTP capturers call this after the user's handler returns,
204
202
  * before they push the HTTP event itself, so DB events arrive
205
203
  * grouped under the same correlation as the HTTP card.
206
204
  */
207
- declare function flushAuditLog(exec: SqlExecutor | null | undefined): Promise<void>;
208
-
209
- /** Read the current request's audit snapshot, if any. */
210
- declare function currentAuditSnapshot(): bigint | null;
211
- /** Run `callback` inside a fresh audit-snapshot scope. */
212
- declare function runWithAuditSnapshotScope<R>(callback: () => R): R;
205
+ declare function flushAuditLog(exec: SqlExecutor | null | undefined, options?: {
206
+ since?: Date | null;
207
+ }): Promise<void>;
213
208
 
214
209
  interface PgQueryConfig {
215
210
  text?: string;
@@ -247,4 +242,4 @@ interface PgModule {
247
242
  */
248
243
  declare function patchPgClient(pgModule: PgModule): void;
249
244
 
250
- export { type AuditRow, type DatabaseContextSnapshot, type Detected, type PgLikeClient, type SqlExecutor, applyDatabaseContext, buildTrackingSql, currentAuditSnapshot, detectEngine, detectTriggerTrackedTables, emitAuditRows, flushAuditLog, getDatabaseContext, parseArgs, patchPgClient, readAuditRows, runInstall, runWithAuditSnapshotScope, takeAuditSnapshot, withDatabaseContext };
245
+ export { type AuditRow, type DatabaseContextSnapshot, type Detected, type PgLikeClient, type SqlExecutor, applyDatabaseContext, buildTrackingSql, detectEngine, detectTriggerTrackedTables, emitAuditRows, flushAuditLog, getDatabaseContext, parseArgs, patchPgClient, pruneAuditLog, readAuditRows, runInstall, sweepAuditLog, withDatabaseContext };
@@ -117,17 +117,15 @@ interface PgLikeClient {
117
117
  declare function withDatabaseContext<T>(client: PgLikeClient, callback: (client: PgLikeClient) => Promise<T>): Promise<T>;
118
118
 
119
119
  /**
120
- * Shape of one row returned by the audit-log SELECT. Matches the
121
- * column list in `00_install.sql` exactly. Drivers vary on how they
120
+ * Shape of one row returned by the audit-log query. Matches the
121
+ * column list in `00_install.sql`. Drivers vary on how they
122
122
  * deserialize jsonb (`pg` returns plain objects; some serverless
123
123
  * drivers return strings) — `coerceJsonb` below handles both.
124
124
  */
125
125
  interface AuditRow {
126
126
  /**
127
127
  * The audit log row's primary key, stringified. Used only for
128
- * within-request emit dedup — never reaches the wire. We stringify
129
- * here so drivers that return bigint, number, or string all live in
130
- * one Set comparable type.
128
+ * within-request emit dedup — never reaches the wire.
131
129
  */
132
130
  id: string;
133
131
  table_name: string;
@@ -135,41 +133,40 @@ interface AuditRow {
135
133
  old_row: Record<string, unknown> | string | null;
136
134
  new_row: Record<string, unknown> | string | null;
137
135
  resource_id: string | null;
136
+ /** Stored correlation id (null when the write couldn't be tagged). */
137
+ correlation_id?: string | null;
138
+ /** Postgres transaction id — groups untagged rows into one action. */
139
+ txid?: string | null;
140
+ /** When the trigger fired — becomes the event timestamp. */
141
+ captured_at?: Date | null;
138
142
  }
139
143
  /**
140
- * Fetch audit rows tagged with `correlationId` in capture order.
144
+ * Claim (delete + return) the audit rows tagged with `correlationId`,
145
+ * oldest first. A row can only be claimed once, so concurrent flushes
146
+ * never emit the same row twice.
141
147
  *
142
- * Returns rows oldest-first (matches the trigger's `clock_timestamp`
143
- * within a transaction) so the dashboard renders them chronologically.
148
+ * If the reader role may not DELETE, falls back to a plain SELECT
149
+ * (rows then stay until the customer cleans them up) and warns once.
144
150
  *
145
- * Errors are caught and returned as `[]` — a failed audit read must
146
- * never break the host request. The error is logged at debug.
147
- */
148
- declare function readAuditRows(exec: SqlExecutor, correlationId: string,
149
- /**
150
- * Snapshot of `MAX(id)` taken at the start of the request. Used as
151
- * the lower bound for the time-window fallback path that catches
152
- * rows whose `correlation_id` is NULL — i.e., supabase-js writes
153
- * that didn't go through SET LOCAL because PostgREST doesn't
154
- * expose explicit transactions to the client.
151
+ * `since` limits the claim to rows written at or after that moment
152
+ * (a job claims only what it wrote, never the enqueuing request's rows).
155
153
  *
156
- * When null, the reader falls back to correlation-only matching
157
- * (Phase 5 primary path).
154
+ * Errors are caught and returned as `[]` — a failed audit read must
155
+ * never break the host request.
158
156
  */
159
- snapshotMaxId?: bigint | null): Promise<AuditRow[]>;
157
+ declare function readAuditRows(exec: SqlExecutor, correlationId: string, since?: Date | null): Promise<AuditRow[]>;
160
158
  /**
161
- * Take a snapshot of the current `MAX(id)` from `ezlogs_audit_log` and
162
- * store it on the per-request scope. Called at the start of each HTTP
163
- * request when `databaseReader` is configured. The reader's time-window
164
- * fallback uses this as the lower bound for catching supabase-js writes
165
- * (rows whose `correlation_id` is NULL because PostgREST didn't run
166
- * inside our explicit transaction).
159
+ * Drain rows no request will claim: untagged rows, and tagged rows
160
+ * older than ORPHAN_AGE. Each is emitted under its stored correlation
161
+ * id, or — when it has none — under one fresh id per database
162
+ * transaction, always with no actor. Never attributes a row to the
163
+ * request that happens to run the sweep.
167
164
  *
168
- * Errors are swallowed — a failed snapshot just means the time-window
169
- * fallback degrades to "match correlation_id only" for this request.
170
- * Never break the host's request over a bookkeeping query.
165
+ * Returns the number of rows emitted. Errors are swallowed.
171
166
  */
172
- declare function takeAuditSnapshot(exec: SqlExecutor): Promise<void>;
167
+ declare function sweepAuditLog(exec: SqlExecutor): Promise<number>;
168
+ /** Delete rows older than PRUNE_AGE without emitting them. Errors swallowed. */
169
+ declare function pruneAuditLog(exec: SqlExecutor): Promise<void>;
173
170
  /**
174
171
  * Detect which tables have the `ezlogs_audit` trigger attached. Used
175
172
  * by the per-ORM adapters to decide whether their per-mutation emit
@@ -196,20 +193,18 @@ declare function detectTriggerTrackedTables(exec: SqlExecutor): Promise<Set<stri
196
193
  */
197
194
  declare function emitAuditRows(rows: ReadonlyArray<AuditRow>): void;
198
195
  /**
199
- * End-of-request entry point. Reads rows for the current correlation
200
- * id and emits each one. Skips when no correlation is in scope (no
201
- * way to match rows back to this request) or no exec is supplied.
196
+ * End-of-request entry point. Claims rows for the current correlation
197
+ * id and emits each one, then runs the throttled sweep (untagged /
198
+ * orphaned rows, as their own actions) and prune. Skips when no
199
+ * correlation is in scope or no exec is supplied.
202
200
  *
203
201
  * The HTTP capturers call this after the user's handler returns,
204
202
  * before they push the HTTP event itself, so DB events arrive
205
203
  * grouped under the same correlation as the HTTP card.
206
204
  */
207
- declare function flushAuditLog(exec: SqlExecutor | null | undefined): Promise<void>;
208
-
209
- /** Read the current request's audit snapshot, if any. */
210
- declare function currentAuditSnapshot(): bigint | null;
211
- /** Run `callback` inside a fresh audit-snapshot scope. */
212
- declare function runWithAuditSnapshotScope<R>(callback: () => R): R;
205
+ declare function flushAuditLog(exec: SqlExecutor | null | undefined, options?: {
206
+ since?: Date | null;
207
+ }): Promise<void>;
213
208
 
214
209
  interface PgQueryConfig {
215
210
  text?: string;
@@ -247,4 +242,4 @@ interface PgModule {
247
242
  */
248
243
  declare function patchPgClient(pgModule: PgModule): void;
249
244
 
250
- export { type AuditRow, type DatabaseContextSnapshot, type Detected, type PgLikeClient, type SqlExecutor, applyDatabaseContext, buildTrackingSql, currentAuditSnapshot, detectEngine, detectTriggerTrackedTables, emitAuditRows, flushAuditLog, getDatabaseContext, parseArgs, patchPgClient, readAuditRows, runInstall, runWithAuditSnapshotScope, takeAuditSnapshot, withDatabaseContext };
245
+ export { type AuditRow, type DatabaseContextSnapshot, type Detected, type PgLikeClient, type SqlExecutor, applyDatabaseContext, buildTrackingSql, detectEngine, detectTriggerTrackedTables, emitAuditRows, flushAuditLog, getDatabaseContext, parseArgs, patchPgClient, pruneAuditLog, readAuditRows, runInstall, sweepAuditLog, withDatabaseContext };