@hardlydifficult/daemon 1.0.2 → 1.0.3

package/README.md

@@ -11,7 +11,35 @@ Opinionated utilities for long-running Node.js services:
 npm install @hardlydifficult/daemon
 ```
 
-## Teardown management
+## Quick Start
+
+```typescript
+import { createTeardown, runContinuousLoop } from "@hardlydifficult/daemon";
+
+// Graceful shutdown with LIFO cleanup
+const teardown = createTeardown();
+teardown.add(() => console.log("Cleaning up server"));
+teardown.add(() => console.log("Closing database connection"));
+teardown.trapSignals();
+
+// Continuous background task with signal-aware sleep
+await runContinuousLoop({
+  intervalSeconds: 5,
+  runCycle: async (isShutdownRequested) => {
+    console.log("Running task...");
+    if (isShutdownRequested()) {
+      return { stop: true };
+    }
+    // Perform background work
+    return "immediate"; // Run next cycle immediately
+  },
+  onShutdown: async () => {
+    await teardown.run();
+  },
+});
+```
+
+## Teardown Management
 
 Use `createTeardown()` to register cleanup functions once and execute them from
 every exit path.
@@ -29,14 +57,62 @@ teardown.trapSignals();
 await teardown.run();
 ```
 
-Behavior:
+### Behavior
+
+- **LIFO execution**: last added, first run
+- **Idempotent `run()`**: safe to call multiple times
+- **Per-function error isolation**: one failing teardown does not block others
+- **`add()` returns an unregister function**: allowing selective cleanup removal
+
+### `createTeardown()`
+
+Creates a teardown registry with idempotent resource cleanup.
+
+```typescript
+const teardown = createTeardown();
+
+// Register cleanup functions
+const unregister = teardown.add(() => server.stop());
+teardown.add(async () => db.close());
+
+// Unregister a specific cleanup
+unregister();
+
+// Manually trigger shutdown
+await teardown.run();
+
+// Wire SIGTERM/SIGINT handlers
+const untrap = teardown.trapSignals();
+// Later...
+untrap(); // Remove handlers
+```
+
+#### Teardown API
+
+| Method | Description |
+|--------|-----------|
+| `add(fn)` | Register a cleanup function; returns an unregister function |
+| `run()` | Run all teardown functions in LIFO order (idempotent) |
+| `trapSignals()` | Wire SIGINT/SIGTERM to `run()` then `process.exit(0)`; returns untrap function |
+
+### LIFO Execution
 
-- LIFO execution (last added, first run)
-- Idempotent `run()` (safe to call multiple times)
-- Per-function error isolation (one failing teardown does not block others)
-- `add()` returns an unregister function
+Teardown functions run in reverse registration order:
+
+```typescript
+const teardown = createTeardown();
+teardown.add(() => console.log("First"));
+teardown.add(() => console.log("Second"));
+teardown.add(() => console.log("Third"));
+
+await teardown.run();
+// Output:
+// Third
+// Second
+// First
+```
 
-## Continuous loop execution
+## Continuous Loop Execution
 
 Use `runContinuousLoop()` to run work cycles with graceful shutdown, dynamic
 delay control, and configurable error policy.
@@ -65,7 +141,7 @@ await runContinuousLoop({
 });
 ```
 
-### Cycle return contract
+### Cycle Return Contract
 
 `runCycle()` can return:
 
@@ -75,18 +151,18 @@ await runContinuousLoop({
 - `{ stop: true }`: stop gracefully after current cycle
 - `{ nextDelayMs: number | "immediate", stop?: true }`: explicit control object
 
-### Optional delay resolver
+### Optional Delay Resolver
 
 If your cycle returns domain data, derive schedule policy with
 `getNextDelayMs(result, context)`.
 
-### Error handling
+### Error Handling
 
 Use `onCycleError(error, context)` to route to Slack/Sentry and decide whether
 to `"continue"` or `"stop"`. Without this hook, cycle errors are logged and the
 loop continues.
 
-### Logger injection
+### Logger Injection
 
 By default, warnings and errors use `console.warn` and `console.error`. Pass
 `logger` to integrate your own logging implementation:
@@ -97,3 +173,93 @@ const logger = {
   error: (message, context) => myLogger.error(message, context),
 };
 ```
+
+### `runContinuousLoop()` Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `intervalSeconds` | `number` | Base interval between cycles (converted to ms) |
+| `runCycle` | `(isShutdownRequested: () => boolean) => Promise<...>` | Cycle function with shutdown check |
+| `getNextDelayMs?` | `(...)` => `ContinuousLoopDelay \| undefined` | Derive delay from cycle result |
+| `onCycleError?` | `ContinuousLoopErrorHandler` | Handle cycle errors, return `"continue"` or `"stop"` |
+| `onShutdown?` | `() => void \| Promise<void>` | Cleanup called after shutdown completes |
+| `logger?` | `ContinuousLoopLogger` | Custom logger (defaults to `console`) |
+
+### Return Values
+
+The `runCycle` function can return:
+- A delay value (`number` ms or `"immediate"`)
+- `{ stop: true }` to gracefully terminate
+- `{ nextDelayMs: ... }` to override delay
+
+```typescript
+await runContinuousLoop({
+  intervalSeconds: 5,
+  runCycle: async () => {
+    const data = await fetchData();
+    if (!data) {
+      return { nextDelayMs: "immediate" }; // Retry immediately
+    }
+    if (data.done) {
+      return { stop: true }; // End loop
+    }
+    return 2000; // Wait 2 seconds
+  },
+});
+```
+
+#### Delay Directives
+
+| Directive | Description |
+|----------|-------------|
+| `number` | Milliseconds to wait before next cycle |
+| `"immediate"` | Run next cycle without delay |
+| `{ stop: true }` | Stop the loop after current cycle |
+| `{ nextDelayMs: ... }` | Override default or derived delay |
+
+### Error Handling Example
+
+Cycles errors are caught and handled according to the error policy.
+
+```typescript
+await runContinuousLoop({
+  intervalSeconds: 1,
+  runCycle: async () => {
+    if (Math.random() > 0.8) {
+      throw new Error("Network failure");
+    }
+  },
+  onCycleError: async (error, context) => {
+    console.error(`Cycle ${context.cycleNumber} failed:`, error.message);
+    return "continue"; // Keep the loop running
+  },
+  logger: {
+    warn: (msg, ctx) => console.log(`[WARN] ${msg}`, ctx),
+    error: (msg, ctx) => console.error(`[ERROR] ${msg}`, ctx),
+  },
+});
+```
+
+If no `onCycleError` is provided, errors are logged and the loop continues.
+
+## Shutdown
+
+Signal handlers are automatically registered for `SIGINT` and `SIGTERM`, and removed on completion.
+
+```typescript
+const loopPromise = runContinuousLoop({
+  intervalSeconds: 1,
+  runCycle: async (isShutdownRequested) => {
+    while (!isShutdownRequested()) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  },
+  onShutdown: async () => {
+    await db.close();
+  },
+});
+
+// Later...
+process.kill(process.pid, "SIGTERM"); // Triggers graceful shutdown
+await loopPromise; // Resolves after onShutdown completes
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/daemon",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [