@randajan/revert

Reversible, reliable, readable.
A tiny utility for managing forward-backward processes with automatic rollback on error.

Supports both synchronous and asynchronous workflows with optional value passing between steps.

---

📦 Installation

1npm install @randajan/revert

or

1yarn install @randajan/revert

---

🧭 Package Variants

Package Path	Type	Description
@randajan/revert/async	ESM / CJS	Asynchronous version with logging, flow, utils
@randajan/revert/async/utils	ESM / CJS	Utility functions: revertable, sleep, attempt
@randajan/revert/sync	ESM / CJS	Synchronous version of the core logic
@randajan/revert/sync/utils	ESM / CJS	Sync utilities: revertable only (no sleep, attempt)

---

🚀 Quick Example

1import { Revertable } from "@randajan/revert/async";
2
3const task = new Revertable({ logger:(msg) => log2.push(msg) })
4  .pushNamed("s1", (log) => log("do1"), "r1", (log) =>{ log("undo1"); throw new Error("rollback")})
5  .pushNamed("s2", (log) => log("do2"))
6  .pushNamed("s3", (log) => log("do3"), "r3", (log) => log("undo3"))
7  .pushNamed("s4", (log) => { log("do4"); throw new Error("main"); }, "r4", (log) => log("undo4"));
8
9const result = await task.run();
10console.log(result);

📈 Log Output Example

1↓ 1/4 [info] s1
2↓ 1/4 [info] do1
3↓ 2/4 [info] s2
4↓ 2/4 [info] do2
5↓ 3/4 [info] s3
6↓ 3/4 [info] do3
7↓ 4/4 [info] s4
8↓ 4/4 [info] do4
9─ 4/4 [error] main
10↑ 3/4 [info] r3
11↑ 3/4 [info] undo3
12↑ 1/4 [info] r1
13↑ 1/4 [info] undo1
14⤫ 1/4 [error] rolback

---

📘 Class: Revertable

A class-based interface built over the core revertable function.

Constructor

1new Revertable(options?: {
2  pass?: "omit" | "keep" | "reduce",
3  logger?: (text: string, kind: string, dir: boolean, step: number, count: number) => void,
4  logFormat?: (data: any, kind: string, dir: boolean, step: number, count: number) => string
5})

Modes (pass)

Mode	Description
"omit"	No value is passed between steps (default)
"keep"	A static value is passed to each step but not modified
"reduce"	Each step receives and returns a value (like a reducer)

---

Method: push

1push(
2  fwd: (...args) => any | Promise<any>,
3  rwd: (...args) => any | Promise<any>
4): this

Adds a step to the process. Both forward and rollback handlers are required.

Method: run

1async run(initialValue?: any): Promise<{
2  status: "pass" | "undo" | "fail",
3  pass?: any,
4  undo?: Error,
5  undoStep?: number,
6  fail?: Error,
7  failStep?: number
8}>

Runs the sequence and handles rollback automatically.

---

🧰 Utility Functions (in utils)

1import { revertable, sleep, attempt } from "@randajan/revert/async/utils";

revertable

Core engine function.

1async revertable(
2  value: any,
3  stepCount: number,
4  fn: (value, dir, stepIndex, totalSteps) => any,
5  onError?: (err, dir, stepIndex, totalSteps) => void
6): Promise<{
7  status: "pass" | "undo" | "fail",
8  pass?: any,
9  undo?: Error,
10  undoStep?: number,
11  fail?: Error,
12  failStep?: number
13}>

Handles the entire flow + rollback mechanism. Minimal, flexible and fully decoupled from logging.

---

sleep

1async sleep(ms: number): Promise<void>

Simple delay utility using Promise + setTimeout.

without sync alternative

---

attempt

1async attempt(
2  fn: (attempt: number) => any,
3  attempts: number = 3,
4  delay: number = 2000
5): Promise<any>

Attempts the function multiple times until it succeeds, with delay between retries. sync attempts are without delay

---

🧪 Synchronous Variant

Available under:

• @randajan/revert/sync
• @randajan/revert/sync/utils

Same API, but no sleep and limited attempt (as they’re async-only).
Use revertable() directly for immediate rollback logic.

---

Support

If you have any questions or suggestions for improvements, feel free to open an issue in the repository.

📄 License

MIT © randajan