test-cleanup-stack 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# cleanup-stack
+
+Zero-dependency LIFO cleanup queue for TypeScript test suites. Register teardown callbacks at the moment you create a resource — the stack runs them all in reverse order when the test ends, even if the test throws.
+
+## Install
+
+```bash
+npm install test-cleanup-stack
+```
+
+## Quick start
+
+```typescript
+import { createRegistry } from 'test-cleanup-stack'
+
+const cleanup = createRegistry()
+
+// Inside your test — register cleanup right next to creation
+const user = await api.createUser({ email: 'test@example.com' })
+cleanup.add(() => api.deleteUser(user.id), { label: `delete user ${user.id}` })
+
+const order = await api.createOrder({ userId: user.id })
+cleanup.add(() => api.cancelOrder(order.id), { label: `cancel order ${order.id}` })
+
+// At test end — runs: cancel order → delete user (LIFO)
+await cleanup.flush()
+```
+
+## Playwright fixture
+
+```typescript
+// core/fixtures/CleanupFixture.ts
+import { test as base } from '@playwright/test'
+import { createRegistry, TeardownRegistry } from 'test-cleanup-stack'
+
+export const test = base.extend<{ cleanup: TeardownRegistry }>({
+  cleanup: async ({}, use) => {
+    const cleanup = createRegistry()
+    await use(cleanup)
+    await cleanup.flush()   // runs after every test, pass or fail
+  },
+})
+```
+
+```typescript
+// your.spec.ts
+import { test } from './CleanupFixture'
+
+test('create and cancel order', async ({ cleanup, page }) => {
+  const order = await createOrder()
+  cleanup.add(() => cancelOrder(order.id), { label: `cancel ${order.id}` })
+
+  // test logic — if this throws, cleanup.flush() still runs in the fixture
+})
+```
+
+## Jest / Vitest
+
+```typescript
+import { createRegistry } from 'test-cleanup-stack'
+
+let cleanup: ReturnType<typeof createRegistry>
+
+beforeEach(() => { cleanup = createRegistry() })
+afterEach(() => cleanup.flush())
+
+test('example', async () => {
+  const user = await createUser()
+  cleanup.add(() => deleteUser(user.id))
+  // ...
+})
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `createRegistry(options?)` | Create an isolated registry (use one per test) |
+| `registry.add(fn, { label?, priority? })` | Register a cleanup callback. Returns a handle with `.remove()` |
+| `registry.flush()` | Run all teardowns LIFO, throw `AggregateError` if any fail |
+| `registry.flushSafe()` | Same as flush but swallows errors — for `afterAll` / best-effort cleanup |
+| `registry.pending()` | List labels of registered-but-not-yet-run teardowns |
+| `registry.reset()` | Clear all without running — for test setup scenarios |
+| `handle.remove()` | Deregister a specific callback without running it |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+/** Async or sync teardown callback. */
+type TeardownFn = () => Promise<void> | void;
+/** Options for registry.add(). */
+interface AddOptions {
+    /** Human-readable label shown in errors and pending(). */
+    label?: string;
+    /** Lower priority runs later (default 0). Same-priority entries run LIFO. */
+    priority?: number;
+}
+/** Options for createRegistry(). */
+interface RegistryOptions {
+    /** Called for each failed teardown callback before errors are collected. */
+    onError?: (err: unknown, label: string) => void;
+}
+/** Handle returned by registry.add() — use to remove a callback early. */
+interface TeardownHandle {
+    remove(): void;
+}
+/** A per-test cleanup registry. Create one per test via createRegistry(). */
+interface TeardownRegistry {
+    /**
+     * Register a cleanup callback. Returns a handle to remove it before flush.
+     * Callbacks registered during an active flush are queued for a second pass.
+     */
+    add(fn: TeardownFn, options?: AddOptions): TeardownHandle;
+    /**
+     * Run all callbacks in LIFO/priority order. Collects all errors and throws
+     * an AggregateError at the end so every callback always gets a chance to run.
+     */
+    flush(): Promise<void>;
+    /**
+     * Like flush() but swallows all errors — logs via onError if provided.
+     * Use in afterAll or CI teardown where you want best-effort cleanup.
+     */
+    flushSafe(): Promise<void>;
+    /** Labels of all registered-but-not-yet-flushed callbacks. */
+    pending(): string[];
+    /** Remove all entries without running them. */
+    reset(): void;
+}
+/**
+ * Create an isolated teardown registry.
+ * Always use createRegistry() per test — never share a singleton across
+ * parallel tests or retries.
+ */
+declare function createRegistry(options?: RegistryOptions): TeardownRegistry;
+/**
+ * Module-level singleton. Only use this in single-worker, non-parallel scripts.
+ * For Playwright/WDIO/Vitest parallel tests always use createRegistry() per test.
+ */
+declare const registry: TeardownRegistry;
+
+export { type AddOptions, type RegistryOptions, type TeardownFn, type TeardownHandle, type TeardownRegistry, createRegistry, registry };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/** Async or sync teardown callback. */
+type TeardownFn = () => Promise<void> | void;
+/** Options for registry.add(). */
+interface AddOptions {
+    /** Human-readable label shown in errors and pending(). */
+    label?: string;
+    /** Lower priority runs later (default 0). Same-priority entries run LIFO. */
+    priority?: number;
+}
+/** Options for createRegistry(). */
+interface RegistryOptions {
+    /** Called for each failed teardown callback before errors are collected. */
+    onError?: (err: unknown, label: string) => void;
+}
+/** Handle returned by registry.add() — use to remove a callback early. */
+interface TeardownHandle {
+    remove(): void;
+}
+/** A per-test cleanup registry. Create one per test via createRegistry(). */
+interface TeardownRegistry {
+    /**
+     * Register a cleanup callback. Returns a handle to remove it before flush.
+     * Callbacks registered during an active flush are queued for a second pass.
+     */
+    add(fn: TeardownFn, options?: AddOptions): TeardownHandle;
+    /**
+     * Run all callbacks in LIFO/priority order. Collects all errors and throws
+     * an AggregateError at the end so every callback always gets a chance to run.
+     */
+    flush(): Promise<void>;
+    /**
+     * Like flush() but swallows all errors — logs via onError if provided.
+     * Use in afterAll or CI teardown where you want best-effort cleanup.
+     */
+    flushSafe(): Promise<void>;
+    /** Labels of all registered-but-not-yet-flushed callbacks. */
+    pending(): string[];
+    /** Remove all entries without running them. */
+    reset(): void;
+}
+/**
+ * Create an isolated teardown registry.
+ * Always use createRegistry() per test — never share a singleton across
+ * parallel tests or retries.
+ */
+declare function createRegistry(options?: RegistryOptions): TeardownRegistry;
+/**
+ * Module-level singleton. Only use this in single-worker, non-parallel scripts.
+ * For Playwright/WDIO/Vitest parallel tests always use createRegistry() per test.
+ */
+declare const registry: TeardownRegistry;
+
+export { type AddOptions, type RegistryOptions, type TeardownFn, type TeardownHandle, type TeardownRegistry, createRegistry, registry };

package/dist/index.js

@@ -0,0 +1,113 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createRegistry: () => createRegistry,
+  registry: () => registry
+});
+module.exports = __toCommonJS(index_exports);
+var _seq = 0;
+function createRegistry(options = {}) {
+  const { onError } = options;
+  const entries = [];
+  let midFlushQueue = [];
+  let flushing = false;
+  function add(fn, opts = {}) {
+    const id = ++_seq;
+    const entry = {
+      fn,
+      label: opts.label ?? `teardown-${id}`,
+      priority: opts.priority ?? 0,
+      id
+    };
+    if (flushing) {
+      midFlushQueue.push(entry);
+    } else {
+      entries.push(entry);
+    }
+    return {
+      remove() {
+        let idx = entries.findIndex((e) => e.id === id);
+        if (idx !== -1) {
+          entries.splice(idx, 1);
+          return;
+        }
+        idx = midFlushQueue.findIndex((e) => e.id === id);
+        if (idx !== -1) midFlushQueue.splice(idx, 1);
+      }
+    };
+  }
+  async function runBatch(batch) {
+    const sorted = [...batch].sort(
+      (a, b) => b.priority !== a.priority ? b.priority - a.priority : b.id - a.id
+    );
+    const failures = [];
+    for (const entry of sorted) {
+      try {
+        await entry.fn();
+      } catch (err) {
+        onError?.(err, entry.label);
+        failures.push({ err, label: entry.label });
+      }
+    }
+    return failures;
+  }
+  async function flush() {
+    flushing = true;
+    const allFailures = [];
+    const primary = [...entries];
+    entries.length = 0;
+    allFailures.push(...await runBatch(primary));
+    while (midFlushQueue.length > 0) {
+      const secondary = [...midFlushQueue];
+      midFlushQueue = [];
+      allFailures.push(...await runBatch(secondary));
+    }
+    flushing = false;
+    if (allFailures.length > 0) {
+      const aggregate = new AggregateError(
+        allFailures.map((f) => f.err),
+        `cleanup-stack: ${allFailures.length} teardown(s) failed: ${allFailures.map((f) => f.label).join(", ")}`
+      );
+      throw aggregate;
+    }
+  }
+  async function flushSafe() {
+    try {
+      await flush();
+    } catch {
+    }
+  }
+  function pending() {
+    return [...entries, ...midFlushQueue].map((e) => e.label);
+  }
+  function reset() {
+    entries.length = 0;
+    midFlushQueue = [];
+  }
+  return { add, flush, flushSafe, pending, reset };
+}
+var registry = createRegistry();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRegistry,
+  registry
+});

package/dist/index.mjs

@@ -0,0 +1,87 @@
+// src/index.ts
+var _seq = 0;
+function createRegistry(options = {}) {
+  const { onError } = options;
+  const entries = [];
+  let midFlushQueue = [];
+  let flushing = false;
+  function add(fn, opts = {}) {
+    const id = ++_seq;
+    const entry = {
+      fn,
+      label: opts.label ?? `teardown-${id}`,
+      priority: opts.priority ?? 0,
+      id
+    };
+    if (flushing) {
+      midFlushQueue.push(entry);
+    } else {
+      entries.push(entry);
+    }
+    return {
+      remove() {
+        let idx = entries.findIndex((e) => e.id === id);
+        if (idx !== -1) {
+          entries.splice(idx, 1);
+          return;
+        }
+        idx = midFlushQueue.findIndex((e) => e.id === id);
+        if (idx !== -1) midFlushQueue.splice(idx, 1);
+      }
+    };
+  }
+  async function runBatch(batch) {
+    const sorted = [...batch].sort(
+      (a, b) => b.priority !== a.priority ? b.priority - a.priority : b.id - a.id
+    );
+    const failures = [];
+    for (const entry of sorted) {
+      try {
+        await entry.fn();
+      } catch (err) {
+        onError?.(err, entry.label);
+        failures.push({ err, label: entry.label });
+      }
+    }
+    return failures;
+  }
+  async function flush() {
+    flushing = true;
+    const allFailures = [];
+    const primary = [...entries];
+    entries.length = 0;
+    allFailures.push(...await runBatch(primary));
+    while (midFlushQueue.length > 0) {
+      const secondary = [...midFlushQueue];
+      midFlushQueue = [];
+      allFailures.push(...await runBatch(secondary));
+    }
+    flushing = false;
+    if (allFailures.length > 0) {
+      const aggregate = new AggregateError(
+        allFailures.map((f) => f.err),
+        `cleanup-stack: ${allFailures.length} teardown(s) failed: ${allFailures.map((f) => f.label).join(", ")}`
+      );
+      throw aggregate;
+    }
+  }
+  async function flushSafe() {
+    try {
+      await flush();
+    } catch {
+    }
+  }
+  function pending() {
+    return [...entries, ...midFlushQueue].map((e) => e.label);
+  }
+  function reset() {
+    entries.length = 0;
+    midFlushQueue = [];
+  }
+  return { add, flush, flushSafe, pending, reset };
+}
+var registry = createRegistry();
+export {
+  createRegistry,
+  registry
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "test-cleanup-stack",
+  "version": "1.0.0",
+  "description": "Zero-dependency LIFO cleanup queue for TypeScript test suites — survives test failures and retries",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["testing", "qa", "teardown", "cleanup", "playwright", "webdriverio", "jest", "vitest", "typescript"],
+  "license": "MIT",
+  "author": "Biswarak Raktim",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raktim1988/cleanup-stack.git"
+  },
+  "homepage": "https://github.com/raktim1988/cleanup-stack#readme",
+  "bugs": {
+    "url": "https://github.com/raktim1988/cleanup-stack/issues"
+  },
+  "engines": { "node": ">=16" },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}