@hardlydifficult/daemon 1.0.3 → 1.0.5

package/README.md

@@ -1,9 +1,6 @@
 # @hardlydifficult/daemon
 
-Opinionated utilities for long-running Node.js services:
-
-- `createTeardown()` for idempotent cleanup with signal trapping
-- `runContinuousLoop()` for daemon-style cycle execution
+Graceful shutdown and continuous loop utilities for Node.js daemon processes.
 
 ## Installation
 
@@ -16,250 +13,177 @@ npm install @hardlydifficult/daemon
 ```typescript
 import { createTeardown, runContinuousLoop } from "@hardlydifficult/daemon";
 
-// Graceful shutdown with LIFO cleanup
 const teardown = createTeardown();
-teardown.add(() => console.log("Cleaning up server"));
+
+// Register cleanup functions
+teardown.add(() => console.log("Stopping server"));
 teardown.add(() => console.log("Closing database connection"));
+
+// Handle SIGINT/SIGTERM
 teardown.trapSignals();
 
-// Continuous background task with signal-aware sleep
+// Run a background task loop
 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
+    if (isShutdownRequested()) return;
+    console.log("Running periodic task...");
+    // Simulate work
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    return { stop: false };
   },
   onShutdown: async () => {
-    await teardown.run();
-  },
+    console.log("Shutting down loop");
+  }
 });
-```
-
-## Teardown Management
-
-Use `createTeardown()` to register cleanup functions once and execute them from
-every exit path.
-
-```typescript
-import { createTeardown } from "@hardlydifficult/daemon";
-
-const teardown = createTeardown();
-teardown.add(() => server.stop());
-teardown.add(async () => {
-  await db.close();
-});
-teardown.trapSignals();
 
+// Manual shutdown
 await teardown.run();
 ```
 
-### Behavior
+## Teardown Management
 
-- **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
+Idempotent resource teardown with signal trapping and LIFO cleanup order.
 
-### `createTeardown()`
+### createTeardown()
 
-Creates a teardown registry with idempotent resource cleanup.
+Creates a teardown registry for managing cleanup functions.
+
+**Features:**
+- Registers cleanup functions in order; runs them in LIFO order
+- Swallows errors per-function so remaining cleanup still executes
+- Idempotent: calling `run()` multiple times has no additional effect
+- Signal trapping for SIGINT/SIGTERM that calls `run()` then exits
+- Returns an unregister function for individual registrations
 
 ```typescript
 const teardown = createTeardown();
 
-// Register cleanup functions
-const unregister = teardown.add(() => server.stop());
-teardown.add(async () => db.close());
+// Add cleanup functions
+const unregister = teardown.add(() => server.close());
+teardown.add(() => db.close());
 
-// Unregister a specific cleanup
+// Unregister a specific function if needed
 unregister();
 
-// Manually trigger shutdown
-await teardown.run();
+// Handle OS signals
+teardown.trapSignals();
 
-// Wire SIGTERM/SIGINT handlers
-const untrap = teardown.trapSignals();
-// Later...
-untrap(); // Remove handlers
+// Run all cleanup
+await teardown.run();
 ```
 
-#### Teardown API
+#### Teardown Interface
 
 | 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 |
+|--------|-------------|
+| `add(fn)` | Registers a cleanup function (sync or async); returns unregister function |
+| `run()` | Runs all registered cleanup functions in LIFO order; idempotent |
+| `trapSignals()` | Attaches SIGINT/SIGTERM handlers; returns untrap function |
 
-### LIFO Execution
+### Signal Trapping
 
-Teardown functions run in reverse registration order:
+Signal handlers are attached via `trapSignals()` and call `run()` then `process.exit(0)`.
 
 ```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
+const untrap = teardown.trapSignals();
+// Later, if needed:
+untrap(); // Remove signal handlers
 ```
 
 ## Continuous Loop Execution
 
-Use `runContinuousLoop()` to run work cycles with graceful shutdown, dynamic
-delay control, and configurable error policy.
+Interruptible loop with configurable cycle interval, error handling, and graceful shutdown.
 
-```typescript
-import { runContinuousLoop } from "@hardlydifficult/daemon";
+### runContinuousLoop()
+
+Runs a function repeatedly with signal-aware sleep that can be interrupted.
 
+```typescript
 await runContinuousLoop({
-  intervalSeconds: 30,
-  async runCycle(isShutdownRequested) {
+  intervalSeconds: 10,
+  runCycle: async (isShutdownRequested) => {
     if (isShutdownRequested()) {
       return { stop: true };
     }
-
-    const didWork = await syncQueue();
-    if (!didWork) {
-      return 60_000; // ms
-    }
-
-    return "immediate";
+    await doWork();
+    // Return a delay override
+    return 5000; // milliseconds
   },
-  onCycleError(error, context) {
-    notifyOps(error, { cycleNumber: context.cycleNumber });
+  onCycleError: async (error, context) => {
+    console.error(`Cycle ${context.cycleNumber} failed:`, error);
     return "continue"; // or "stop"
   },
+  onShutdown: async () => {
+    await cleanup();
+  }
 });
 ```
 
-### Cycle Return Contract
-
-`runCycle()` can return:
-
-- any value/`undefined`: use default `intervalSeconds`
-- `number`: use that delay in milliseconds
-- `"immediate"`: run the next cycle without sleeping
-- `{ stop: true }`: stop gracefully after current cycle
-- `{ nextDelayMs: number | "immediate", stop?: true }`: explicit control object
-
-### Optional Delay Resolver
-
-If your cycle returns domain data, derive schedule policy with
-`getNextDelayMs(result, context)`.
+#### Loop Lifecycle
 
-### Error Handling
+- Runs cycles indefinitely until:
+  - `SIGINT` or `SIGTERM` is received
+  - `runCycle` returns `{ stop: true }`
+  - `onCycleError` returns `"stop"`
+- Each cycle may override the default delay or signal immediate continuation
 
-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.
+### Options
 
-### Logger Injection
+| Option | Type | Description |
+|--------|------|-------------|
+| `intervalSeconds` | `number` | Default delay between cycles (seconds) |
+| `runCycle` | `(isShutdownRequested: () => boolean) => Promise<...>` | Function to run each cycle |
+| `getNextDelayMs?` | `(result, context) => ContinuousLoopDelay` | Derive delay from cycle result |
+| `onCycleError?` | `(error, context) => "continue" \| "stop"` | Handle cycle errors |
+| `onShutdown?` | `() => void \| Promise<void>` | Cleanup after shutdown |
+| `logger?` | `ContinuousLoopLogger` | Optional custom logger |
 
-By default, warnings and errors use `console.warn` and `console.error`. Pass
-`logger` to integrate your own logging implementation:
+### Cycle Return Values
 
-```typescript
-const logger = {
-  warn: (message, context) => myLogger.warn(message, context),
-  error: (message, context) => myLogger.error(message, context),
-};
-```
+Cycles may return:
+- A delay in milliseconds (e.g., `5000`)
+- `"immediate"` to continue without delay
+- `{ stop: true }` to end the loop
+- `{ nextDelayMs: number \| "immediate" }` to override delay
 
-### `runContinuousLoop()` Options
+If the cycle returns a domain-specific result, use `getNextDelayMs` to derive the next delay.
 
-| 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`) |
+### Error Handling
 
-### Return Values
+By default:
+- Errors are logged to `console.error`
+- Loop continues to next cycle
 
-The `runCycle` function can return:
-- A delay value (`number` ms or `"immediate"`)
-- `{ stop: true }` to gracefully terminate
-- `{ nextDelayMs: ... }` to override delay
+Custom error handling via `onCycleError` can override behavior:
 
 ```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
-  },
-});
+onCycleError: async (error, context) => {
+  if (error instanceof FatalError) {
+    return "stop"; // Terminate loop
+  }
+  return "continue"; // Proceed
+}
 ```
 
-#### Delay Directives
+### Context Types
 
-| 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 |
+#### ContinuousLoopCycleContext
 
-### Error Handling Example
+| Field | Type | Description |
+|-------|------|-------------|
+| `cycleNumber` | `number` | 1-based cycle number |
+| `isShutdownRequested` | `() => boolean` | Check shutdown status |
 
-Cycles errors are caught and handled according to the error policy.
+#### ContinuousLoopErrorContext
 
-```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),
-  },
-});
-```
+Identical to `ContinuousLoopCycleContext`; passed to `onCycleError`.
 
-If no `onCycleError` is provided, errors are logged and the loop continues.
+#### ContinuousLoopLogger
 
-## 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();
-  },
-});
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `warn(message, context?)` | `string`, `Record<string, unknown>` | Warning log |
+| `error(message, context?)` | `string`, `Record<string, unknown>` | Error log |
 
-// Later...
-process.kill(process.pid, "SIGTERM"); // Triggers graceful shutdown
-await loopPromise; // Resolves after onShutdown completes
-```
+Default logger uses `console.warn`/`console.error`.

package/package.json

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