@revealui/db 0.3.4 → 0.3.6

package/dist/saga/crdt-resolver.js

@@ -0,0 +1,168 @@
+/**
+ * CRDT Resolver — Conflict Resolution Bridge
+ *
+ * Bridges the existing CRDT classes from @revealui/ai/memory/crdt with
+ * Drizzle ORM operations for conflict-free concurrent writes over NeonDB.
+ *
+ * Two patterns:
+ * 1. PNCounter for commutative balance updates (agent credits, usage metrics)
+ * 2. LWWRegister for last-writer-wins value updates with optimistic concurrency
+ *
+ * These patterns handle concurrent writes without coordination — the CRDT
+ * merge function resolves conflicts deterministically.
+ *
+ * @example
+ * ```typescript
+ * // Increment agent credit balance (safe under concurrency)
+ * await crdtIncrement(db, agentCreditBalance, userId, 'balance', 10, 'node-1');
+ *
+ * // Set a value with last-writer-wins semantics
+ * await crdtSetValue(db, agentContexts, contextId, 'metadata', newMetadata, 'node-1');
+ * ```
+ */
+import { sql } from 'drizzle-orm';
+// =============================================================================
+// Types
+// =============================================================================
+/** Maximum number of optimistic concurrency retries before giving up */
+const MAX_RETRIES = 5;
+// =============================================================================
+// PNCounter Pattern — Commutative Increments/Decrements
+// =============================================================================
+/**
+ * Atomically increment (or decrement) a numeric column using SQL arithmetic.
+ *
+ * This is naturally idempotent-safe when combined with an idempotency key.
+ * Under the hood it uses `SET column = column + delta` which is atomic in
+ * a single SQL statement — no CRDT serialization needed for simple counters.
+ *
+ * For distributed multi-node scenarios where each node tracks its own
+ * counter state, use the full PNCounter class from @revealui/ai/memory/crdt.
+ *
+ * @param db - Database client
+ * @param table - Drizzle table reference
+ * @param whereClause - WHERE clause to identify the row
+ * @param column - Column name to increment
+ * @param delta - Amount to add (negative for decrement)
+ * @returns Previous and new values
+ */
+export async function crdtIncrement(db, table, whereClause, column, delta) {
+    // Read current value
+    const rows = await db.select().from(table).where(whereClause).limit(1);
+    if (rows.length === 0) {
+        throw new Error('CRDT increment: row not found');
+    }
+    const row = rows[0];
+    const previousValue = typeof row[column] === 'number' ? row[column] : 0;
+    const newValue = previousValue + delta;
+    // Atomic update using SQL arithmetic via set
+    await db
+        .update(table)
+        .set({ [column]: newValue })
+        .where(whereClause);
+    return { previousValue, newValue, retries: 0 };
+}
+// =============================================================================
+// LWW Register Pattern — Last-Writer-Wins with Optimistic Concurrency
+// =============================================================================
+/**
+ * Detect whether a Database instance supports real transactions (pg Pool).
+ * NeonDB HTTP clients are stateless and cannot hold transaction state.
+ */
+function supportsTransactions(db) {
+    return ('transaction' in db &&
+        typeof db.transaction === 'function');
+}
+/**
+ * Set a value using last-writer-wins semantics with optimistic concurrency.
+ *
+ * When the database client supports transactions (Supabase pg Pool), uses
+ * SELECT FOR UPDATE inside a real transaction for true atomic check-and-set.
+ *
+ * When running on NeonDB HTTP (no transaction support), falls back to a
+ * best-effort single-statement UPDATE — still safe for single-row writes
+ * but without the isolation guarantee of FOR UPDATE.
+ *
+ * @param db - Database client (pg Pool for true locking, NeonDB HTTP for best-effort)
+ * @param table - Drizzle table reference
+ * @param whereClause - WHERE clause to identify the row
+ * @param updates - Object of column→value updates to apply
+ * @param timestampColumn - Column name used for optimistic concurrency (default: 'updatedAt')
+ * @returns Retry count and success status
+ */
+export async function crdtSetWithOptimisticLock(db, table, whereClause, updates, timestampColumn = 'updatedAt') {
+    // pg Pool path — true transactional SELECT FOR UPDATE
+    if (supportsTransactions(db)) {
+        return crdtSetTransactional(db, table, whereClause, updates, timestampColumn);
+    }
+    // NeonDB HTTP fallback — best-effort single-statement update
+    return crdtSetBestEffort(db, table, whereClause, updates, timestampColumn);
+}
+/**
+ * True atomic check-and-set via SELECT FOR UPDATE + conditional UPDATE
+ * inside a pg transaction. Retries on serialization failures.
+ */
+async function crdtSetTransactional(db, table, whereClause, updates, timestampColumn) {
+    let retries = 0;
+    while (retries < MAX_RETRIES) {
+        try {
+            const success = await db.transaction(async (tx) => {
+                // Lock the row — blocks concurrent writers until this tx commits
+                const rows = await tx.select().from(table).where(whereClause).for('update').limit(1);
+                if (rows.length === 0) {
+                    throw new Error('CRDT set: row not found');
+                }
+                const row = rows[0];
+                const currentTimestamp = row[timestampColumn];
+                // Write with new timestamp
+                const newTimestamp = new Date();
+                const result = await tx
+                    .update(table)
+                    .set({
+                    ...updates,
+                    [timestampColumn]: newTimestamp,
+                })
+                    .where(sql `${whereClause} AND ${sql.identifier(timestampColumn)} = ${currentTimestamp}`)
+                    .returning();
+                return result.length > 0;
+            });
+            if (success) {
+                return { retries, success: true };
+            }
+            retries++;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // Row not found is a hard error, not a retry scenario
+            if (message === 'CRDT set: row not found')
+                throw error;
+            // Serialization/deadlock failures are retryable
+            retries++;
+            if (retries >= MAX_RETRIES) {
+                return { retries, success: false };
+            }
+        }
+    }
+    return { retries, success: false };
+}
+/**
+ * Best-effort single-statement UPDATE for NeonDB HTTP.
+ * No true isolation — relies on the write being a single atomic statement.
+ */
+async function crdtSetBestEffort(db, table, whereClause, updates, timestampColumn) {
+    const rows = await db.select().from(table).where(whereClause).limit(1);
+    if (rows.length === 0) {
+        throw new Error('CRDT set: row not found');
+    }
+    const newTimestamp = new Date();
+    const result = await db
+        .update(table)
+        .set({
+        ...updates,
+        [timestampColumn]: newTimestamp,
+    })
+        .where(whereClause)
+        .returning();
+    return { retries: 0, success: result.length > 0 };
+}
+//# sourceMappingURL=crdt-resolver.js.map

package/dist/saga/crdt-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt-resolver.js","sourceRoot":"","sources":["../../src/saga/crdt-resolver.ts"],"names":[],"mappings":"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"}

package/dist/saga/idempotent-operation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Idempotent Operation Wrapper
+ *
+ * Generalizes the processedWebhookEvents dedup pattern into a reusable
+ * utility. Checks an idempotency key before executing, skips if already
+ * processed, and records the key after success.
+ *
+ * @example
+ * ```typescript
+ * const { result, alreadyProcessed } = await idempotentWrite(
+ *   db,
+ *   `send-welcome-email:${userId}`,
+ *   'email',
+ *   async () => {
+ *     await sendWelcomeEmail(userId);
+ *     return { sent: true };
+ *   },
+ * );
+ *
+ * if (alreadyProcessed) {
+ *   // Email was already sent — skip
+ * }
+ * ```
+ */
+import type { Database } from '../client/index.js';
+export interface IdempotentWriteResult<T> {
+    /** The operation's return value (undefined if already processed) */
+    result?: T;
+    /** True if the operation was skipped because the key already existed */
+    alreadyProcessed: boolean;
+}
+export interface IdempotentWriteOptions {
+    /** TTL for the idempotency key in ms (default: 24 hours) */
+    ttlMs?: number;
+    /** Cache the result in the idempotency record for retrieval on replay */
+    cacheResult?: boolean;
+}
+/**
+ * Execute an operation idempotently.
+ *
+ * 1. Check if the key exists in idempotency_keys (skip if so)
+ * 2. Execute the operation
+ * 3. Record the key (ON CONFLICT DO NOTHING for race-condition safety)
+ *
+ * @param db - Database client
+ * @param key - Unique idempotency key for this operation
+ * @param operationType - Category string (e.g., 'saga', 'email', 'webhook')
+ * @param operation - The function to execute idempotently
+ * @param options - TTL and caching options
+ */
+export declare function idempotentWrite<T>(db: Database, key: string, operationType: string, operation: () => Promise<T>, options?: IdempotentWriteOptions): Promise<IdempotentWriteResult<T>>;
+//# sourceMappingURL=idempotent-operation.d.ts.map

package/dist/saga/idempotent-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotent-operation.d.ts","sourceRoot":"","sources":["../../src/saga/idempotent-operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAMnD,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,wEAAwE;IACxE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CA0CnC"}

package/dist/saga/idempotent-operation.js

@@ -0,0 +1,78 @@
+/**
+ * Idempotent Operation Wrapper
+ *
+ * Generalizes the processedWebhookEvents dedup pattern into a reusable
+ * utility. Checks an idempotency key before executing, skips if already
+ * processed, and records the key after success.
+ *
+ * @example
+ * ```typescript
+ * const { result, alreadyProcessed } = await idempotentWrite(
+ *   db,
+ *   `send-welcome-email:${userId}`,
+ *   'email',
+ *   async () => {
+ *     await sendWelcomeEmail(userId);
+ *     return { sent: true };
+ *   },
+ * );
+ *
+ * if (alreadyProcessed) {
+ *   // Email was already sent — skip
+ * }
+ * ```
+ */
+import { eq } from 'drizzle-orm';
+import { idempotencyKeys } from '../schema/idempotency.js';
+// Default TTL: 24 hours
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Execute an operation idempotently.
+ *
+ * 1. Check if the key exists in idempotency_keys (skip if so)
+ * 2. Execute the operation
+ * 3. Record the key (ON CONFLICT DO NOTHING for race-condition safety)
+ *
+ * @param db - Database client
+ * @param key - Unique idempotency key for this operation
+ * @param operationType - Category string (e.g., 'saga', 'email', 'webhook')
+ * @param operation - The function to execute idempotently
+ * @param options - TTL and caching options
+ */
+export async function idempotentWrite(db, key, operationType, operation, options) {
+    const ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
+    // Step 1: Check if already processed
+    const existing = await db
+        .select({ key: idempotencyKeys.key, expiresAt: idempotencyKeys.expiresAt })
+        .from(idempotencyKeys)
+        .where(eq(idempotencyKeys.key, key))
+        .limit(1);
+    const row = existing[0];
+    if (row) {
+        // Check if expired
+        if (!row.expiresAt || row.expiresAt >= new Date()) {
+            return { alreadyProcessed: true };
+        }
+        // Expired — clean up and proceed
+        await db.delete(idempotencyKeys).where(eq(idempotencyKeys.key, key));
+    }
+    // Step 2: Execute the operation
+    const result = await operation();
+    // Step 3: Record the idempotency key
+    const expiresAt = new Date(Date.now() + ttlMs);
+    const resultData = options?.cacheResult && result !== null && typeof result === 'object'
+        ? result
+        : undefined;
+    await db
+        .insert(idempotencyKeys)
+        .values({
+        key,
+        operationType,
+        result: resultData,
+        createdAt: new Date(),
+        expiresAt,
+    })
+        .onConflictDoNothing();
+    return { result, alreadyProcessed: false };
+}
+//# sourceMappingURL=idempotent-operation.js.map

package/dist/saga/idempotent-operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotent-operation.js","sourceRoot":"","sources":["../../src/saga/idempotent-operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D,wBAAwB;AACxB,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAgB3C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,EAAY,EACZ,GAAW,EACX,aAAqB,EACrB,SAA2B,EAC3B,OAAgC;IAEhC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,cAAc,CAAC;IAE/C,qCAAqC;IACrC,MAAM,QAAQ,GAAG,MAAM,EAAE;SACtB,MAAM,CAAC,EAAE,GAAG,EAAE,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,eAAe,CAAC,SAAS,EAAE,CAAC;SAC1E,IAAI,CAAC,eAAe,CAAC;SACrB,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;SACnC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEZ,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,GAAG,EAAE,CAAC;QACR,mBAAmB;QACnB,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;YAClD,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;QACpC,CAAC;QACD,iCAAiC;QACjC,MAAM,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,gCAAgC;IAChC,MAAM,MAAM,GAAG,MAAM,SAAS,EAAE,CAAC;IAEjC,qCAAqC;IACrC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;IAC/C,MAAM,UAAU,GACd,OAAO,EAAE,WAAW,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QACnE,CAAC,CAAE,MAAkC;QACrC,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,EAAE;SACL,MAAM,CAAC,eAAe,CAAC;SACvB,MAAM,CAAC;QACN,GAAG;QACH,aAAa;QACb,MAAM,EAAE,UAAU;QAClB,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,SAAS;KACV,CAAC;SACD,mBAAmB,EAAE,CAAC;IAEzB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC"}

package/dist/saga/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @revealui/db/saga — NeonDB-safe saga executor
+ *
+ * Provides transaction-like guarantees over NeonDB's stateless HTTP driver
+ * using compensating actions, idempotency keys, and the jobs table as outbox.
+ *
+ * @example
+ * ```typescript
+ * import { executeSaga, resilientStep, idempotentWrite } from '@revealui/db/saga';
+ *
+ * const result = await executeSaga(db, 'provision-license', eventId, [
+ *   resilientStep({
+ *     name: 'insert-license',
+ *     execute: async (ctx) => { ... },
+ *     compensate: async (ctx, output) => { ... },
+ *   }),
+ * ]);
+ * ```
+ */
+export type { CRDTIncrementResult, CRDTSetResult } from './crdt-resolver.js';
+export { crdtIncrement, crdtSetWithOptimisticLock } from './crdt-resolver.js';
+export type { IdempotentWriteOptions, IdempotentWriteResult } from './idempotent-operation.js';
+export { idempotentWrite } from './idempotent-operation.js';
+export { executeSaga } from './neon-saga.js';
+export type { RecoveredSaga } from './recovery.js';
+export { cleanupExpiredIdempotencyKeys, recoverStaleSagas } from './recovery.js';
+export { resilientStep } from './resilient-step.js';
+export type { SagaCheckpointData, SagaContext, SagaOptions, SagaResult, SagaRetryOptions, SagaStatus, SagaStep, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/saga/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/saga/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,QAAQ,GACT,MAAM,YAAY,CAAC"}

package/dist/saga/index.js

@@ -0,0 +1,30 @@
+/**
+ * @revealui/db/saga — NeonDB-safe saga executor
+ *
+ * Provides transaction-like guarantees over NeonDB's stateless HTTP driver
+ * using compensating actions, idempotency keys, and the jobs table as outbox.
+ *
+ * @example
+ * ```typescript
+ * import { executeSaga, resilientStep, idempotentWrite } from '@revealui/db/saga';
+ *
+ * const result = await executeSaga(db, 'provision-license', eventId, [
+ *   resilientStep({
+ *     name: 'insert-license',
+ *     execute: async (ctx) => { ... },
+ *     compensate: async (ctx, output) => { ... },
+ *   }),
+ * ]);
+ * ```
+ */
+// CRDT conflict resolution
+export { crdtIncrement, crdtSetWithOptimisticLock } from './crdt-resolver.js';
+// Idempotent operation wrapper
+export { idempotentWrite } from './idempotent-operation.js';
+// Core saga executor
+export { executeSaga } from './neon-saga.js';
+// Saga recovery
+export { cleanupExpiredIdempotencyKeys, recoverStaleSagas } from './recovery.js';
+// Resilient step wrapper
+export { resilientStep } from './resilient-step.js';
+//# sourceMappingURL=index.js.map

package/dist/saga/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/saga/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,2BAA2B;AAC3B,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE9E,+BAA+B;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,qBAAqB;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,gBAAgB;AAChB,OAAO,EAAE,6BAA6B,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjF,yBAAyB;AACzB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/saga/neon-saga.d.ts

@@ -0,0 +1,50 @@
+/**
+ * NeonSaga — Saga Executor for NeonDB HTTP Driver
+ *
+ * Provides transaction-like guarantees over NeonDB's stateless HTTP driver
+ * by modeling multi-step writes as a saga with compensating actions.
+ *
+ * Each step's execute() and compensate() must be individually atomic (single
+ * DB statement). The saga tracks progress via the jobs table as an outbox,
+ * enabling crash recovery and idempotent replay.
+ *
+ * @example
+ * ```typescript
+ * const result = await executeSaga(db, 'provision-license', eventId, [
+ *   {
+ *     name: 'insert-license',
+ *     execute: async (ctx) => {
+ *       const [row] = await ctx.db.insert(licenses).values({ ... }).returning();
+ *       return row;
+ *     },
+ *     compensate: async (ctx, row) => {
+ *       await ctx.db.delete(licenses).where(eq(licenses.id, row.id));
+ *     },
+ *   },
+ *   {
+ *     name: 'activate-subscription',
+ *     execute: async (ctx) => {
+ *       await ctx.db.update(subscriptions).set({ status: 'active' }).where(...);
+ *       return { previousStatus: 'pending' };
+ *     },
+ *     compensate: async (ctx, output) => {
+ *       await ctx.db.update(subscriptions).set({ status: output.previousStatus }).where(...);
+ *     },
+ *   },
+ * ]);
+ * ```
+ */
+import type { SagaOptions, SagaResult, SagaStep } from './types.js';
+/**
+ * Execute a saga — a sequence of individually-atomic steps with compensating
+ * actions for rollback.
+ *
+ * @param db - Database client (works with both NeonDB HTTP and pg Pool)
+ * @param sagaName - Saga type identifier (e.g., 'provision-license')
+ * @param sagaKey - Natural idempotency key (e.g., Stripe event ID)
+ * @param steps - Ordered list of saga steps
+ * @param options - Optional retry, circuit breaker, and idempotency config
+ * @returns SagaResult with status, outputs, and completed steps
+ */
+export declare function executeSaga<T = unknown>(db: Parameters<SagaStep['execute']>[0]['db'], sagaName: string, sagaKey: string, steps: SagaStep[], options?: SagaOptions): Promise<SagaResult<T>>;
+//# sourceMappingURL=neon-saga.d.ts.map

package/dist/saga/neon-saga.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neon-saga.d.ts","sourceRoot":"","sources":["../../src/saga/neon-saga.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAKH,OAAO,KAAK,EAGV,WAAW,EACX,UAAU,EACV,QAAQ,EACT,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3C,EAAE,EAAE,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAsJxB"}

package/dist/saga/neon-saga.js

@@ -0,0 +1,234 @@
+/**
+ * NeonSaga — Saga Executor for NeonDB HTTP Driver
+ *
+ * Provides transaction-like guarantees over NeonDB's stateless HTTP driver
+ * by modeling multi-step writes as a saga with compensating actions.
+ *
+ * Each step's execute() and compensate() must be individually atomic (single
+ * DB statement). The saga tracks progress via the jobs table as an outbox,
+ * enabling crash recovery and idempotent replay.
+ *
+ * @example
+ * ```typescript
+ * const result = await executeSaga(db, 'provision-license', eventId, [
+ *   {
+ *     name: 'insert-license',
+ *     execute: async (ctx) => {
+ *       const [row] = await ctx.db.insert(licenses).values({ ... }).returning();
+ *       return row;
+ *     },
+ *     compensate: async (ctx, row) => {
+ *       await ctx.db.delete(licenses).where(eq(licenses.id, row.id));
+ *     },
+ *   },
+ *   {
+ *     name: 'activate-subscription',
+ *     execute: async (ctx) => {
+ *       await ctx.db.update(subscriptions).set({ status: 'active' }).where(...);
+ *       return { previousStatus: 'pending' };
+ *     },
+ *     compensate: async (ctx, output) => {
+ *       await ctx.db.update(subscriptions).set({ status: output.previousStatus }).where(...);
+ *     },
+ *   },
+ * ]);
+ * ```
+ */
+import { eq } from 'drizzle-orm';
+import { idempotencyKeys } from '../schema/idempotency.js';
+import { jobs } from '../schema/jobs.js';
+// Default idempotency TTL: 24 hours
+const DEFAULT_IDEMPOTENCY_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * Execute a saga — a sequence of individually-atomic steps with compensating
+ * actions for rollback.
+ *
+ * @param db - Database client (works with both NeonDB HTTP and pg Pool)
+ * @param sagaName - Saga type identifier (e.g., 'provision-license')
+ * @param sagaKey - Natural idempotency key (e.g., Stripe event ID)
+ * @param steps - Ordered list of saga steps
+ * @param options - Optional retry, circuit breaker, and idempotency config
+ * @returns SagaResult with status, outputs, and completed steps
+ */
+export async function executeSaga(db, sagaName, sagaKey, steps, options) {
+    const idempotencyKey = options?.idempotencyKey ?? `${sagaName}:${sagaKey}`;
+    const sagaId = `saga-${sagaName}-${sagaKey}-${Date.now()}`;
+    // -------------------------------------------------------------------------
+    // 1. Idempotency check — skip if already processed
+    // -------------------------------------------------------------------------
+    const alreadyProcessed = await checkIdempotency(db, idempotencyKey);
+    if (alreadyProcessed) {
+        return {
+            sagaId,
+            status: 'skipped',
+            completedSteps: [],
+            alreadyProcessed: true,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // 2. Create job record (outbox entry) — records intent before mutations
+    // -------------------------------------------------------------------------
+    const checkpointData = {
+        sagaName,
+        sagaKey,
+        stepNames: steps.map((s) => s.name),
+        completedSteps: [],
+        idempotencyKey,
+    };
+    await db.insert(jobs).values({
+        id: sagaId,
+        name: `saga:${sagaName}`,
+        data: checkpointData,
+        state: 'created',
+        priority: 0,
+        retryCount: 0,
+        retryLimit: 3,
+    });
+    // Mark job active
+    await db.update(jobs).set({ state: 'active', startedAt: new Date() }).where(eq(jobs.id, sagaId));
+    // -------------------------------------------------------------------------
+    // 3. Execute steps sequentially with checkpointing
+    // -------------------------------------------------------------------------
+    const completedSteps = [];
+    let lastOutput;
+    const ctx = {
+        db,
+        sagaId,
+        checkpoint: async (stepName, output) => {
+            const entry = {
+                name: stepName,
+                output,
+                completedAt: new Date().toISOString(),
+            };
+            completedSteps.push(entry);
+            // Persist checkpoint to job's JSONB data
+            await db
+                .update(jobs)
+                .set({
+                data: {
+                    ...checkpointData,
+                    completedSteps: [...completedSteps],
+                },
+            })
+                .where(eq(jobs.id, sagaId));
+        },
+    };
+    try {
+        for (const step of steps) {
+            const output = await step.execute(ctx);
+            await ctx.checkpoint(step.name, output);
+            lastOutput = output;
+        }
+        // -----------------------------------------------------------------------
+        // 4. All steps succeeded — mark completed and record idempotency key
+        // -----------------------------------------------------------------------
+        await db
+            .update(jobs)
+            .set({ state: 'completed', completedAt: new Date() })
+            .where(eq(jobs.id, sagaId));
+        await recordIdempotency(db, idempotencyKey, 'saga', options?.idempotencyTtlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS);
+        return {
+            sagaId,
+            status: 'completed',
+            result: lastOutput,
+            completedSteps: completedSteps.map((s) => s.name),
+            alreadyProcessed: false,
+        };
+    }
+    catch (executeError) {
+        // -----------------------------------------------------------------------
+        // 5. Step failed — compensate completed steps in reverse order
+        // -----------------------------------------------------------------------
+        const errorMessage = executeError instanceof Error ? executeError.message : String(executeError);
+        const compensationErrors = [];
+        // Compensate in reverse order
+        for (let i = completedSteps.length - 1; i >= 0; i--) {
+            const completed = completedSteps[i];
+            if (!completed)
+                continue;
+            const step = steps.find((s) => s.name === completed.name);
+            if (!step)
+                continue;
+            try {
+                await step.compensate(ctx, completed.output);
+            }
+            catch (compensateError) {
+                // Log but don't throw — compensations are best-effort
+                const msg = compensateError instanceof Error ? compensateError.message : String(compensateError);
+                compensationErrors.push(`${completed.name}: ${msg}`);
+            }
+        }
+        // Determine final status
+        const finalStatus = compensationErrors.length > 0 ? 'failed' : 'compensated';
+        // Update job record with failure info
+        await db
+            .update(jobs)
+            .set({
+            state: 'failed',
+            output: {
+                error: errorMessage,
+                compensationErrors: compensationErrors.length > 0 ? compensationErrors : undefined,
+                compensatedSteps: completedSteps.map((s) => s.name),
+            },
+        })
+            .where(eq(jobs.id, sagaId));
+        return {
+            sagaId,
+            status: finalStatus,
+            error: errorMessage,
+            completedSteps: completedSteps.map((s) => s.name),
+            alreadyProcessed: false,
+        };
+    }
+}
+// =============================================================================
+// Idempotency Helpers
+// =============================================================================
+/**
+ * Check if an idempotency key has already been recorded.
+ * Returns true if the key exists and hasn't expired.
+ */
+async function checkIdempotency(db, key) {
+    try {
+        const rows = await db
+            .select({ key: idempotencyKeys.key, expiresAt: idempotencyKeys.expiresAt })
+            .from(idempotencyKeys)
+            .where(eq(idempotencyKeys.key, key))
+            .limit(1);
+        if (rows.length === 0)
+            return false;
+        const expiresAt = rows[0]?.expiresAt;
+        if (expiresAt && expiresAt < new Date()) {
+            // Expired — delete and treat as not processed
+            await db.delete(idempotencyKeys).where(eq(idempotencyKeys.key, key));
+            return false;
+        }
+        return true;
+    }
+    catch {
+        // If the idempotency table doesn't exist yet, treat as not processed
+        return false;
+    }
+}
+/**
+ * Record an idempotency key after successful saga completion.
+ */
+async function recordIdempotency(db, key, operationType, ttlMs) {
+    const expiresAt = new Date(Date.now() + ttlMs);
+    try {
+        await db
+            .insert(idempotencyKeys)
+            .values({
+            key,
+            operationType,
+            createdAt: new Date(),
+            expiresAt,
+        })
+            .onConflictDoNothing();
+    }
+    catch {
+        // Best-effort — if this fails, the saga still completed successfully.
+        // The next execution will just re-run (which is fine since steps are idempotent).
+    }
+}
+//# sourceMappingURL=neon-saga.js.map