@u17g/deferrable 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Unbounded Pioneering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# @u17g/deferrable
+
+A tiny `defer` utility for JavaScript/TypeScript: register cleanup/rollback callbacks that run in LIFO order. Works in any runtime (Node.js, Bun, Deno, browsers).
+
+## Installation
+
+```sh
+npm install -S @u17g/deferrable
+pnpm add @u17g/deferrable
+bun add @u17g/deferrable
+```
+
+## Usage
+
+```ts
+import { deferrable } from "@u17g/deferrable";
+
+await deferrable(async (defer): Promise<string> => {
+  defer(async ([result, err]) => {
+    if (err) {
+      console.error(err);
+    } else {
+      console.log(result);
+    }
+  });
+  return "Hello, World!";
+});
+```
+
+### CommonJS
+
+```js
+const { deferrable } = require("@u17g/deferrable");
+```
+
+## TypeScript notes
+
+### Annotate the callback's return type (recommended)
+
+When using TypeScript, prefer annotating the return type of the callback you pass to `deferrable`:
+
+```ts
+await deferrable(async (defer): Promise<number> => {
+  defer(([value, err]) => {
+    // value: number | undefined
+    // err: Error | undefined
+  });
+  return 42;
+});
+```
+
+**Why**: `defer` is typed in terms of the generic `T` (the value that the callback returns). If you omit the return type annotation, TypeScript can fail to infer `T` correctly, which may surface as confusing type errors inside `defer(([value, err]) => ...)`.
+
+## Behavior
+
+`deferrable(callback)` runs `callback(defer)` and guarantees that deferred callbacks registered via `defer(...)` are executed **after** the callback finishes (either resolved or rejected).
+
+- **Execution order (LIFO)**: deferred callbacks run in reverse order of registration (stack behavior).
+- **Result passed to deferred callbacks**: each deferred callback receives a tuple `[value, error]`:
+  - `[value, undefined]` when the callback resolved
+  - `[undefined, error]` when the callback threw / rejected
+- **Error propagation**: if the callback fails, deferred callbacks still run, then the original error is re-thrown.
+- **Awaited sequentially**: deferred callbacks are awaited one by one (no parallel execution).
+- **Deferred callback errors are ignored**: if a deferred callback throws/rejects, it is swallowed and does not affect the final result.
+
+### Example: LIFO order
+
+```ts
+await deferrable(async (defer): Promise<string> => {
+  defer(() => console.log("first"));
+  defer(() => console.log("second"));
+  // Output:
+  // second
+  // first
+  return "ok";
+});
+```
+
+### Example: observing success/failure
+
+```ts
+await deferrable(async (defer): Promise<number> => {
+  defer(([value, err]) => {
+    if (err) {
+      console.error("failed:", err);
+    } else {
+      console.log("ok:", value);
+    }
+  });
+
+  // throw new Error("boom");
+  return 42;
+});
+```
+
+### Example: catching errors at the call site
+
+```ts
+await deferrable(async (_defer): Promise<void> => {
+  // Simulate failure
+  throw new Error("boom");
+}).catch((err) => {
+  console.error("caught:", err);
+});
+```
+
+## Patterns
+
+### Saga / compensating actions (transaction-like cleanup)
+
+Because deferred callbacks run **in reverse order (LIFO)** and still run even if the callback fails, you can use `deferrable` to implement a lightweight saga pattern: after each step succeeds, register its compensation. On failure, compensations run in reverse order automatically.
+
+```ts
+await deferrable(async (defer): Promise<void> => {
+  const orderId = await createOrder();
+  defer(async ([_, err]) => {
+    if (err) await cancelOrder(orderId);
+  });
+
+  const paymentId = await chargeCard();
+  defer(async ([_, err]) => {
+    if (err) await refundPayment(paymentId);
+  });
+
+  await reserveInventory(orderId);
+  defer(async ([_, err]) => {
+    if (err) await releaseInventory(orderId);
+  });
+}).catch((err) => {
+  // If anything throws above, the registered compensations will run:
+  // releaseInventory -> refundPayment -> cancelOrder
+  console.error("saga failed:", err);
+});
+
+async function createOrder(): Promise<string> {
+  return "order_123";
+}
+async function cancelOrder(_orderId: string): Promise<void> {}
+async function chargeCard(): Promise<string> {
+  return "payment_123";
+}
+async function refundPayment(_paymentId: string): Promise<void> {}
+async function reserveInventory(_orderId: string): Promise<void> {
+  throw new Error("out of stock");
+}
+async function releaseInventory(_orderId: string): Promise<void> {}
+```

package/dist/index.cjs

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deferrable = deferrable;
+function ok(value) {
+    return [value, undefined];
+}
+;
+function failure(error) {
+    return [undefined, error];
+}
+;
+async function wrap(promise) {
+    try {
+        const value = await promise;
+        return ok(value);
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+/**
+ * Deferrable execution.
+ *
+ * This function is used to execute a function with a deferrable execution stack - LIFO.
+ *
+ * @param fn - The function to execute.
+ * @returns The result of the function.
+ *
+ * @example
+ *
+ *  await deferrable(async (defer): Promise<string> => {
+ *    defer(async ([result, err]) => {
+ *      if (err) {
+ *        console.error(err);
+ *      } else {
+ *        console.log(result);
+ *      }
+ *    });
+ *
+ *    return "Hello, world!";
+ *  });
+ */
+async function deferrable(fn) {
+    const stack = [];
+    const defer = (exec) => {
+        stack.push(exec);
+    };
+    const result = await wrap(fn(defer));
+    while (stack.length) {
+        const exec = stack.pop();
+        try {
+            await exec(result);
+        }
+        catch { }
+    }
+    const [value, error] = result;
+    if (error !== undefined)
+        throw error;
+    return value;
+}
+;
+//# sourceMappingURL=index.js.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAyCA,gCAiBC;AAxDD,SAAS,EAAE,CAAI,KAAQ;IACrB,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAC5B,CAAC;AAAA,CAAC;AAEF,SAAS,OAAO,CAAY,KAAQ;IAClC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC5B,CAAC;AAAA,CAAC;AAEF,KAAK,UAAU,IAAI,CAAe,OAAmB;IACnD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC;QAC5B,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,KAAU,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACI,KAAK,UAAU,UAAU,CAC9B,EAAwI;IAExI,MAAM,KAAK,GAA8C,EAAE,CAAC;IAC5D,MAAM,KAAK,GAA6B,CAAC,IAAI,EAAE,EAAE;QAC/C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC,CAAC,CAAC;IACb,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,KAAK,CAAC;IACrC,OAAO,KAAU,CAAC;AACpB,CAAC;AAAA,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Deferrable execution.
+ *
+ * This function is used to execute a function with a deferrable execution stack - LIFO.
+ *
+ * @param fn - The function to execute.
+ * @returns The result of the function.
+ *
+ * @example
+ *
+ *  await deferrable(async (defer): Promise<string> => {
+ *    defer(async ([result, err]) => {
+ *      if (err) {
+ *        console.error(err);
+ *      } else {
+ *        console.log(result);
+ *      }
+ *    });
+ *
+ *    return "Hello, world!";
+ *  });
+ */
+export declare function deferrable<T, E = Error>(fn: (defer: (exec: (result: [value: T, error: undefined] | [value: undefined, error: E]) => void | Promise<void>) => void) => Promise<T>): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,EAC3C,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GACvI,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/index.js

@@ -0,0 +1,59 @@
+function ok(value) {
+    return [value, undefined];
+}
+;
+function failure(error) {
+    return [undefined, error];
+}
+;
+async function wrap(promise) {
+    try {
+        const value = await promise;
+        return ok(value);
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+/**
+ * Deferrable execution.
+ *
+ * This function is used to execute a function with a deferrable execution stack - LIFO.
+ *
+ * @param fn - The function to execute.
+ * @returns The result of the function.
+ *
+ * @example
+ *
+ *  await deferrable(async (defer): Promise<string> => {
+ *    defer(async ([result, err]) => {
+ *      if (err) {
+ *        console.error(err);
+ *      } else {
+ *        console.log(result);
+ *      }
+ *    });
+ *
+ *    return "Hello, world!";
+ *  });
+ */
+export async function deferrable(fn) {
+    const stack = [];
+    const defer = (exec) => {
+        stack.push(exec);
+    };
+    const result = await wrap(fn(defer));
+    while (stack.length) {
+        const exec = stack.pop();
+        try {
+            await exec(result);
+        }
+        catch { }
+    }
+    const [value, error] = result;
+    if (error !== undefined)
+        throw error;
+    return value;
+}
+;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,SAAS,EAAE,CAAI,KAAQ;IACrB,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AAC5B,CAAC;AAAA,CAAC;AAEF,SAAS,OAAO,CAAY,KAAQ;IAClC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAC5B,CAAC;AAAA,CAAC;AAEF,KAAK,UAAU,IAAI,CAAe,OAAmB;IACnD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC;QAC5B,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,KAAU,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,EAAwI;IAExI,MAAM,KAAK,GAA8C,EAAE,CAAC;IAC5D,MAAM,KAAK,GAA6B,CAAC,IAAI,EAAE,EAAE;QAC/C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;QAAC,MAAM,CAAC,CAAC,CAAC;IACb,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,KAAK,CAAC;IACrC,OAAO,KAAU,CAAC;AACpB,CAAC;AAAA,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@u17g/deferrable",
+  "description": "A tiny defer utility for JavaScript/TypeScript: register cleanup/rollback callbacks that run in LIFO order. Works in any runtime (Node.js, Bun, Deno, browsers).",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/u17g/deferrable.git"
+  },
+  "bugs": {
+    "url": "https://github.com/u17g/deferrable/issues"
+  },
+  "homepage": "https://github.com/u17g/deferrable#readme",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "bun run scripts/build.ts",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun test && bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+type Result<T, E = Error> = [value: T, error: undefined] | [value: undefined, error: E];
+
+function ok<T>(value: T): Result<T, never> {
+  return [value, undefined];
+};
+
+function failure<E = Error>(error: E): Result<never, E> {
+  return [undefined, error];
+};
+
+async function wrap<T, E = Error>(promise: Promise<T>): Promise<Result<T, E>> {
+  try {
+    const value = await promise;
+    return ok(value);
+  } catch (error) {
+    return failure(error as E);
+  }
+}
+
+/**
+ * Deferrable execution.
+ *
+ * This function is used to execute a function with a deferrable execution stack - LIFO.
+ *
+ * @param fn - The function to execute.
+ * @returns The result of the function.
+ *
+ * @example
+ *
+ *  await deferrable(async (defer): Promise<string> => {
+ *    defer(async ([result, err]) => {
+ *      if (err) {
+ *        console.error(err);
+ *      } else {
+ *        console.log(result);
+ *      }
+ *    });
+ *
+ *    return "Hello, world!";
+ *  });
+ */
+export async function deferrable<T, E = Error>(
+  fn: (defer: (exec: (result: [value: T, error: undefined] | [value: undefined, error: E]) => void | Promise<void>) => void) => Promise<T>,
+): Promise<T> {
+  const stack: Parameters<Parameters<typeof fn>[0]>[0][] = [];
+  const defer: Parameters<typeof fn>[0] = (exec) => {
+    stack.push(exec);
+  };
+  const result = await wrap<T, E>(fn(defer));
+  while (stack.length) {
+    const exec = stack.pop()!;
+    try {
+      await exec(result);
+    } catch { }
+  }
+  const [value, error] = result;
+  if (error !== undefined) throw error;
+  return value as T;
+};