@hardlydifficult/daemon 1.0.0

package/README.md

@@ -0,0 +1,123 @@
+# @hardlydifficult/teardown
+
+Idempotent resource teardown with signal trapping. Register cleanup functions once at resource creation time — all exit paths call a single `run()`.
+
+## Installation
+
+```bash
+npm install @hardlydifficult/teardown
+```
+
+## Quick Start
+
+```typescript
+import { createTeardown } from "@hardlydifficult/teardown";
+
+const teardown = createTeardown();
+teardown.add(() => server.stop());
+teardown.add(() => db.close());
+teardown.trapSignals();
+
+// Any manual exit path:
+await teardown.run();
+```
+
+## Creating a Teardown Registry
+
+Use `createTeardown()` to create a new teardown registry that manages cleanup functions.
+
+```typescript
+import { createTeardown } from "@hardlydifficult/teardown";
+
+const teardown = createTeardown();
+```
+
+## Registering Cleanup Functions
+
+Call `add()` to register a cleanup function. Functions run in LIFO order (last added runs first). The `add()` method returns an unregister function for selective cleanup.
+
+```typescript
+const teardown = createTeardown();
+
+// Register sync cleanup
+teardown.add(() => {
+  console.log("Closing server");
+  server.stop();
+});
+
+// Register async cleanup
+teardown.add(async () => {
+  console.log("Closing database");
+  await db.close();
+});
+
+// Unregister a specific function
+const unregister = teardown.add(() => {
+  console.log("This won't run");
+});
+unregister();
+
+await teardown.run();
+// Output:
+// Closing database
+// Closing server
+```
+
+## Running Teardown
+
+Call `run()` to execute all registered cleanup functions in LIFO order. The method is idempotent — subsequent calls are no-ops.
+
+```typescript
+const teardown = createTeardown();
+teardown.add(() => console.log("cleanup"));
+
+await teardown.run();
+// Output: cleanup
+
+await teardown.run();
+// No output (idempotent)
+```
+
+## Signal Trapping
+
+Call `trapSignals()` to automatically run teardown when the process receives SIGTERM or SIGINT signals. Returns an untrap function to remove signal handlers.
+
+```typescript
+const teardown = createTeardown();
+teardown.add(() => server.stop());
+
+// Wire SIGTERM/SIGINT to run() then process.exit(0)
+const untrap = teardown.trapSignals();
+
+// Later, if needed:
+untrap();
+```
+
+## Error Resilience
+
+Each teardown function is wrapped in try/catch. Errors don't block remaining teardowns — all functions run regardless of failures.
+
+```typescript
+const teardown = createTeardown();
+
+teardown.add(() => {
+  throw new Error("First cleanup fails");
+});
+teardown.add(() => {
+  console.log("Second cleanup still runs");
+});
+
+await teardown.run();
+// Output: Second cleanup still runs
+```
+
+## Behavior Reference
+
+| Behavior | Details |
+|----------|---------|
+| **LIFO order** | Teardowns run in reverse registration order (last added runs first) |
+| **Idempotent** | `run()` executes once; subsequent calls are no-ops |
+| **Error resilient** | Each function is wrapped in try/catch; failures don't block remaining teardowns |
+| **Safe unregister** | `add()` returns an unregister function; safe to call multiple times |
+| **Post-run add** | `add()` after `run()` is a silent no-op |
+| **Duplicate safe** | Same function added twice runs twice; unregister only removes its own registration |

package/dist/createTeardown.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Idempotent resource teardown with signal trapping
+ *
+ * Register cleanup functions once at resource creation time.
+ * All exit paths call a single `run()` — no duplication, no missed resources.
+ */
+export interface Teardown {
+    /** Register a teardown function. Returns an unregister function. */
+    add(fn: () => void | Promise<void>): () => void;
+    /** Run all teardown functions in LIFO order. Idempotent: second call is a no-op. */
+    run(): Promise<void>;
+    /** Wire SIGTERM/SIGINT to run() then process.exit(0). Returns an untrap function. */
+    trapSignals(): () => void;
+}
+/**
+ * Create a teardown registry
+ *
+ * @example
+ * ```typescript
+ * const teardown = createTeardown();
+ * teardown.add(() => server.stop());
+ * teardown.add(() => db.close());
+ * teardown.trapSignals();
+ *
+ * // Any manual exit path:
+ * await teardown.run();
+ * ```
+ */
+export declare function createTeardown(): Teardown;
+//# sourceMappingURL=createTeardown.d.ts.map

package/dist/createTeardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTeardown.d.ts","sourceRoot":"","sources":["../src/createTeardown.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;IAChD,oFAAoF;IACpF,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,qFAAqF;IACrF,WAAW,IAAI,MAAM,IAAI,CAAC;CAC3B;AAOD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAsDzC"}

package/dist/createTeardown.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTeardown = createTeardown;
+/**
+ * Create a teardown registry
+ *
+ * @example
+ * ```typescript
+ * const teardown = createTeardown();
+ * teardown.add(() => server.stop());
+ * teardown.add(() => db.close());
+ * teardown.trapSignals();
+ *
+ * // Any manual exit path:
+ * await teardown.run();
+ * ```
+ */
+function createTeardown() {
+    const entries = [];
+    let hasRun = false;
+    const run = async () => {
+        if (hasRun) {
+            return;
+        }
+        hasRun = true;
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const entry = entries[i];
+            if (entry.removed) {
+                continue;
+            }
+            try {
+                await entry.fn();
+            }
+            catch {
+                // Swallow errors per-fn so remaining teardowns still run
+            }
+        }
+    };
+    return {
+        add(fn) {
+            if (hasRun) {
+                // eslint-disable-next-line @typescript-eslint/no-empty-function
+                return () => { };
+            }
+            const entry = { fn, removed: false };
+            entries.push(entry);
+            return () => {
+                entry.removed = true;
+            };
+        },
+        run,
+        trapSignals() {
+            const onSignal = () => {
+                void run().then(() => process.exit(0));
+            };
+            process.on("SIGTERM", onSignal);
+            process.on("SIGINT", onSignal);
+            return () => {
+                process.off("SIGTERM", onSignal);
+                process.off("SIGINT", onSignal);
+            };
+        },
+    };
+}
+//# sourceMappingURL=createTeardown.js.map

package/dist/createTeardown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTeardown.js","sourceRoot":"","sources":["../src/createTeardown.ts"],"names":[],"mappings":";;AAkCA,wCAsDC;AApED;;;;;;;;;;;;;GAaG;AACH,SAAgB,cAAc;IAC5B,MAAM,OAAO,GAAY,EAAE,CAAC;IAC5B,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,GAAG,GAAG,KAAK,IAAmB,EAAE;QACpC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO;QACT,CAAC;QACD,MAAM,GAAG,IAAI,CAAC;QAEd,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACzB,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAClB,SAAS;YACX,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,EAAE,EAAE,CAAC;YACnB,CAAC;YAAC,MAAM,CAAC;gBACP,yDAAyD;YAC3D,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,CAAC,EAA8B;YAChC,IAAI,MAAM,EAAE,CAAC;gBACX,gEAAgE;gBAChE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;YAClB,CAAC;YAED,MAAM,KAAK,GAAU,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEpB,OAAO,GAAG,EAAE;gBACV,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;YACvB,CAAC,CAAC;QACJ,CAAC;QAED,GAAG;QAEH,WAAW;YACT,MAAM,QAAQ,GAAG,GAAS,EAAE;gBAC1B,KAAK,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACzC,CAAC,CAAC;YAEF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAE/B,OAAO,GAAG,EAAE;gBACV,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;gBACjC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAClC,CAAC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createTeardown, type Teardown } from "./createTeardown.js";
+export { runContinuousLoop, type ContinuousLoopOptions, } from "./runContinuousLoop.js";
+//# 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":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContinuousLoop = exports.createTeardown = void 0;
+var createTeardown_js_1 = require("./createTeardown.js");
+Object.defineProperty(exports, "createTeardown", { enumerable: true, get: function () { return createTeardown_js_1.createTeardown; } });
+var runContinuousLoop_js_1 = require("./runContinuousLoop.js");
+Object.defineProperty(exports, "runContinuousLoop", { enumerable: true, get: function () { return runContinuousLoop_js_1.runContinuousLoop; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAoE;AAA3D,mHAAA,cAAc,OAAA;AACvB,+DAGgC;AAF9B,yHAAA,iBAAiB,OAAA"}

package/dist/runContinuousLoop.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared utilities for graceful shutdown and continuous loop execution.
+ *
+ * This module provides interruptible sleep and continuous loop functionality with proper signal handling for
+ * SIGINT/SIGTERM.
+ */
+/** Options for running a continuous loop */
+export interface ContinuousLoopOptions {
+    /** Interval between cycles in seconds */
+    intervalSeconds: number;
+    /**
+     * Callback to run on each cycle.
+     *
+     * @param isShutdownRequested - Function to check if shutdown has been requested during the cycle
+     * @returns Promise that resolves when the cycle is complete (return value is ignored)
+     */
+    runCycle: (isShutdownRequested: () => boolean) => Promise<unknown>;
+    /** Optional callback for cleanup on shutdown */
+    onShutdown?: () => Promise<void>;
+}
+/**
+ * Run a function in a continuous loop with graceful shutdown support.
+ *
+ * Features:
+ *
+ * - Interruptible sleep that responds immediately to SIGINT/SIGTERM
+ * - Proper signal handler cleanup to prevent listener accumulation
+ * - Continues to next cycle even if current cycle fails
+ * - Passes shutdown check callback to runCycle for in-cycle interruption
+ *
+ * @param options - Configuration for the continuous loop
+ */
+export declare function runContinuousLoop(options: ContinuousLoopOptions): Promise<void>;
+//# sourceMappingURL=runContinuousLoop.d.ts.map

package/dist/runContinuousLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runContinuousLoop.d.ts","sourceRoot":"","sources":["../src/runContinuousLoop.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,mBAAmB,EAAE,MAAM,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAqCD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAuDf"}

package/dist/runContinuousLoop.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Shared utilities for graceful shutdown and continuous loop execution.
+ *
+ * This module provides interruptible sleep and continuous loop functionality with proper signal handling for
+ * SIGINT/SIGTERM.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContinuousLoop = runContinuousLoop;
+/**
+ * Creates an interruptible sleep that can be woken early by calling the returned cancel function.
+ *
+ * @returns An object with a promise that resolves after durationMs or when cancel() is called
+ */
+function createInterruptibleSleep(durationMs) {
+    let resolve = null;
+    let timeout = null;
+    const promise = new Promise((r) => {
+        resolve = r;
+        timeout = setTimeout(() => {
+            timeout = null;
+            resolve = null;
+            r();
+        }, durationMs);
+    });
+    const cancel = () => {
+        if (timeout !== null) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+        if (resolve !== null) {
+            resolve();
+            resolve = null;
+        }
+    };
+    return { promise, cancel };
+}
+/**
+ * Run a function in a continuous loop with graceful shutdown support.
+ *
+ * Features:
+ *
+ * - Interruptible sleep that responds immediately to SIGINT/SIGTERM
+ * - Proper signal handler cleanup to prevent listener accumulation
+ * - Continues to next cycle even if current cycle fails
+ * - Passes shutdown check callback to runCycle for in-cycle interruption
+ *
+ * @param options - Configuration for the continuous loop
+ */
+async function runContinuousLoop(options) {
+    const { intervalSeconds, runCycle, onShutdown } = options;
+    let shutdownRequested = false;
+    let cancelCurrentSleep = null;
+    const handleShutdown = (signal) => {
+        console.warn(`Received ${signal}, shutting down gracefully...`);
+        shutdownRequested = true;
+        if (cancelCurrentSleep !== null) {
+            cancelCurrentSleep();
+            cancelCurrentSleep = null;
+        }
+    };
+    const sigintHandler = () => {
+        handleShutdown("SIGINT");
+    };
+    const sigtermHandler = () => {
+        handleShutdown("SIGTERM");
+    };
+    process.on("SIGINT", sigintHandler);
+    process.on("SIGTERM", sigtermHandler);
+    const isShutdownRequested = () => shutdownRequested;
+    const shouldContinue = () => !shutdownRequested;
+    try {
+        while (shouldContinue()) {
+            try {
+                await runCycle(isShutdownRequested);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error(`Cycle error: ${errorMessage}`);
+            }
+            if (!shouldContinue()) {
+                break;
+            }
+            const sleep = createInterruptibleSleep(intervalSeconds * 1000);
+            cancelCurrentSleep = sleep.cancel;
+            await sleep.promise;
+            cancelCurrentSleep = null;
+        }
+    }
+    finally {
+        process.off("SIGINT", sigintHandler);
+        process.off("SIGTERM", sigtermHandler);
+        if (onShutdown !== undefined) {
+            await onShutdown();
+        }
+    }
+}
+//# sourceMappingURL=runContinuousLoop.js.map

package/dist/runContinuousLoop.js.map

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

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hardlydifficult/daemon",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.3",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}