did-it-land 0.1.0 → 0.1.1

package/dist/adapters.d.ts

@@ -0,0 +1,60 @@
+import type { Capsule } from "./capsule.ts";
+import { type CompensationResult, type Outcome, type Transport } from "./reconcile.ts";
+/** The effect had already landed, so guard did not repeat the call. */
+export declare class Skipped {
+    readonly capsuleId: string;
+    readonly outcome: Outcome;
+    constructor(capsuleId: string, outcome: Outcome);
+}
+/** The probe could not tell whether the effect landed, so guard refused to act.
+ *
+ * Firing a side effect on an unknown answer is a guess, and for money-moving
+ * operations a guess in either direction is the bug this library exists to remove.
+ * The caller decides how to wait and re-probe: re-throw so the durable engine
+ * retries the step later, or catch and re-run guard after a delay. */
+export declare class UnknownOutcome extends Error {
+    readonly outcome: Outcome;
+    constructor(outcome: Outcome);
+}
+export interface GuardOptions {
+    /** How many extra probes to make on an unknown answer before giving up. */
+    unknownRetries?: number;
+    /** Seconds to wait between those retries. */
+    unknownWait?: number;
+    /** Injectable wait, so a test never sleeps for real. */
+    sleep?: (seconds: number) => void | Promise<void>;
+}
+/** Probe with the capsule, then act only if the effect definitely has not landed.
+ *
+ * landed skips the call and not_landed runs it. An unknown answer (an outage, a
+ * timeout, money still in flight) is never acted on. By default guard throws
+ * UnknownOutcome immediately so the engine's own retry policy takes over. Give it
+ * unknownRetries and it waits unknownWait seconds and asks again that many times
+ * before throwing, a bounded patience rather than an open-ended hang.
+ *
+ * One freshness caveat stands either way: an eventually consistent probe (Stripe
+ * search, for one) can answer not_landed moments after the effect landed, so a
+ * recovery path should wait out the vendor's freshness window before trusting a
+ * not_landed that follows a crash. */
+export declare function guard<T>(capsule: Capsule, context: Record<string, unknown>, transport: Transport | undefined, perform: () => T | Promise<T>, options?: GuardOptions): Promise<Skipped | Awaited<T>>;
+/** A record of completed effects that can be walked back on failure.
+ *
+ * The journal lives in process memory. It survives an exception inside the
+ * workflow, which is the case it exists for. Under a deterministic-replay engine
+ * the record() calls are replayed on recovery, but only when record() lives in
+ * workflow-body code: engines skip completed steps on recovery, so a record()
+ * inside a step body never replays. Call record() in the workflow with the step's
+ * return value, and create one Saga per workflow invocation. A bare process crash
+ * with no replaying engine loses the journal either way, so if it must outlive the
+ * process, persist each recorded context in your engine's own store. */
+export declare class Saga {
+    private steps;
+    record(capsule: Capsule, context: Record<string, unknown>, transport?: Transport): void;
+    /** Run unwind for every recorded effect, most recent first.
+     *
+     * One bad step must not strand the rest: an unwind that throws is captured as a
+     * CompensationResult with status "error" and the walk continues, so every
+     * recorded effect gets its attempt and the caller sees the full list. */
+    compensate(): Promise<CompensationResult[]>;
+    get size(): number;
+}

package/dist/adapters.js

@@ -0,0 +1,108 @@
+// Engine-free adapter pieces. A durable engine resumes a crashed workflow from its last
+// completed step, and its soft spot is a step that called a vendor and crashed before the
+// step checkpoint committed: on recovery the step re-runs and repeats the side effect.
+// guard and Saga close that gap without depending on any particular engine, so they stay
+// testable on their own.
+//
+//   guard(capsule, context, transport, perform)
+//       Probe first. If the effect already landed, skip perform() and return Skipped.
+//       Call it inside a step so a re-run reconciles before it re-charges.
+//
+//   Saga
+//       Record each effect as its step completes. If the workflow fails, compensate()
+//       runs unwind for every recorded effect in reverse order.
+import { reconcile, unwind, } from "./reconcile.js";
+/** The effect had already landed, so guard did not repeat the call. */
+export class Skipped {
+    capsuleId;
+    outcome;
+    constructor(capsuleId, outcome) {
+        this.capsuleId = capsuleId;
+        this.outcome = outcome;
+    }
+}
+/** The probe could not tell whether the effect landed, so guard refused to act.
+ *
+ * Firing a side effect on an unknown answer is a guess, and for money-moving
+ * operations a guess in either direction is the bug this library exists to remove.
+ * The caller decides how to wait and re-probe: re-throw so the durable engine
+ * retries the step later, or catch and re-run guard after a delay. */
+export class UnknownOutcome extends Error {
+    outcome;
+    constructor(outcome) {
+        super(`${outcome.capsuleId}: probe returned unknown ` +
+            `(evidence ${JSON.stringify(outcome.evidence)}), refusing to run the side effect`);
+        this.name = "UnknownOutcome";
+        this.outcome = outcome;
+    }
+}
+const realSleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+/** Probe with the capsule, then act only if the effect definitely has not landed.
+ *
+ * landed skips the call and not_landed runs it. An unknown answer (an outage, a
+ * timeout, money still in flight) is never acted on. By default guard throws
+ * UnknownOutcome immediately so the engine's own retry policy takes over. Give it
+ * unknownRetries and it waits unknownWait seconds and asks again that many times
+ * before throwing, a bounded patience rather than an open-ended hang.
+ *
+ * One freshness caveat stands either way: an eventually consistent probe (Stripe
+ * search, for one) can answer not_landed moments after the effect landed, so a
+ * recovery path should wait out the vendor's freshness window before trusting a
+ * not_landed that follows a crash. */
+export async function guard(capsule, context, transport, perform, options = {}) {
+    const attempts = Math.max(0, Math.trunc(options.unknownRetries ?? 0)) + 1;
+    const wait = options.unknownWait ?? 2.0;
+    const sleep = options.sleep ?? realSleep;
+    let outcome;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        outcome = await reconcile(capsule, context, transport);
+        if (outcome.status === "landed")
+            return new Skipped(capsule.id, outcome);
+        if (outcome.status === "not_landed")
+            return await perform();
+        if (attempt + 1 < attempts)
+            await sleep(wait);
+    }
+    throw new UnknownOutcome(outcome);
+}
+/** A record of completed effects that can be walked back on failure.
+ *
+ * The journal lives in process memory. It survives an exception inside the
+ * workflow, which is the case it exists for. Under a deterministic-replay engine
+ * the record() calls are replayed on recovery, but only when record() lives in
+ * workflow-body code: engines skip completed steps on recovery, so a record()
+ * inside a step body never replays. Call record() in the workflow with the step's
+ * return value, and create one Saga per workflow invocation. A bare process crash
+ * with no replaying engine loses the journal either way, so if it must outlive the
+ * process, persist each recorded context in your engine's own store. */
+export class Saga {
+    steps = [];
+    record(capsule, context, transport) {
+        this.steps.push({ capsule, context, transport });
+    }
+    /** Run unwind for every recorded effect, most recent first.
+     *
+     * One bad step must not strand the rest: an unwind that throws is captured as a
+     * CompensationResult with status "error" and the walk continues, so every
+     * recorded effect gets its attempt and the caller sees the full list. */
+    async compensate() {
+        const results = [];
+        for (let i = this.steps.length - 1; i >= 0; i--) {
+            const step = this.steps[i];
+            try {
+                results.push(await unwind(step.capsule, step.context, step.transport));
+            }
+            catch (err) {
+                results.push({
+                    status: "error",
+                    capsuleId: step.capsule.id,
+                    evidence: { error: String(err) },
+                });
+            }
+        }
+        return results;
+    }
+    get size() {
+        return this.steps.length;
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./capsule.ts";
 export * from "./reconcile.ts";
 export * from "./registry.ts";
-export declare const VERSION = "0.1.0";
+export * from "./adapters.ts";
+export * from "./native.ts";
+export declare const VERSION = "0.1.1";

package/dist/index.js

@@ -2,4 +2,6 @@
 export * from "./capsule.js";
 export * from "./reconcile.js";
 export * from "./registry.js";
-export const VERSION = "0.1.0";
+export * from "./adapters.js";
+export * from "./native.js";
+export const VERSION = "0.1.1";

package/dist/native.d.ts

@@ -0,0 +1,7 @@
+export interface QueryResult {
+    rows: unknown[];
+    rowCount?: number | null;
+}
+export interface Connection {
+    query(text: string, values: unknown[]): QueryResult | Promise<QueryResult>;
+}

package/dist/native.js

@@ -0,0 +1,68 @@
+// Native handlers for capsules that speak a driver protocol rather than HTTP.
+//
+// A native capsule names a handler id; this module resolves it to a small object with a
+// probe and a compensate method, mirroring the Python native handlers. The built-in
+// Postgres handlers are driver-agnostic: the caller passes a connection in the context
+// whose query(text, values) returns { rows, rowCount }, the shape node-postgres uses.
+// Only whitelisted identifiers are ever interpolated into SQL, and values always go
+// through the driver's own parameter binding.
+import { EffectError, registerNative, } from "./reconcile.js";
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PLACEHOLDER = {
+    numbered: "$1", qmark: "?", format: "%s", pyformat: "%s",
+};
+function ident(name, where) {
+    const s = String(name);
+    if (!IDENT.test(s))
+        throw new EffectError(`${where}: '${s}' is not a safe SQL identifier`);
+    return s;
+}
+function placeholder(context) {
+    return PLACEHOLDER[String(context.paramstyle ?? "numbered")] ?? "$1";
+}
+function connection(capsule, context) {
+    const conn = context.connection;
+    if (!conn)
+        throw new EffectError(`${capsule.id}: native handler needs context.connection`);
+    return conn;
+}
+// Probe: does a row with the natural key exist, and therefore did the insert land.
+class PostgresRowExists {
+    async probe(capsule, context) {
+        const conn = connection(capsule, context);
+        const table = ident(context.table, `${capsule.id}.table`);
+        const col = ident(context.key_column, `${capsule.id}.key_column`);
+        const ph = placeholder(context);
+        const result = await conn.query(`SELECT 1 FROM ${table} WHERE ${col} = ${ph} LIMIT 1`, [context.key_value]);
+        const landed = (result.rows?.length ?? 0) > 0;
+        return {
+            status: landed ? "landed" : "not_landed",
+            capsuleId: capsule.id,
+            evidence: { table, key_column: col },
+        };
+    }
+    compensate(capsule) {
+        throw new EffectError(`${capsule.id}: postgres_row_exists is a probe, not a compensation`);
+    }
+}
+// Compensation: delete the row addressed by its natural key.
+class PostgresDeleteByKey {
+    probe(capsule) {
+        throw new EffectError(`${capsule.id}: postgres_delete_by_key is a compensation, not a probe`);
+    }
+    async compensate(capsule, context) {
+        const conn = connection(capsule, context);
+        const table = ident(context.table, `${capsule.id}.table`);
+        const col = ident(context.key_column, `${capsule.id}.key_column`);
+        const ph = placeholder(context);
+        const result = await conn.query(`DELETE FROM ${table} WHERE ${col} = ${ph}`, [context.key_value]);
+        const deleted = result.rowCount ?? 0;
+        return {
+            status: deleted ? "compensated" : "no_compensation",
+            capsuleId: capsule.id,
+            evidence: { deleted },
+        };
+    }
+}
+registerNative("postgres_row_exists", new PostgresRowExists());
+registerNative("postgres_delete_by_key", new PostgresDeleteByKey());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "did-it-land",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Know whether a side-effect landed, and how to reverse it: a corpus of per-vendor effect capsules for durable and saga workflows.",
   "type": "module",
   "license": "MIT",