@hardlydifficult/daemon 1.0.5 → 1.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/daemon
 
-Graceful shutdown and continuous loop utilities for Node.js daemon processes.
+A utility library for building long-running Node.js processes with graceful shutdown and continuous background task execution.
 
 ## Installation
 
@@ -11,179 +11,165 @@ npm install @hardlydifficult/daemon
 ## Quick Start
 
 ```typescript
-import { createTeardown, runContinuousLoop } from "@hardlydifficult/daemon";
+import { runContinuousLoop, createTeardown } from "@hardlydifficult/daemon";
 
+// Setup graceful shutdown
 const teardown = createTeardown();
-
-// Register cleanup functions
-teardown.add(() => console.log("Stopping server"));
-teardown.add(() => console.log("Closing database connection"));
-
-// Handle SIGINT/SIGTERM
+teardown.add(() => console.log("Shutting down..."));
 teardown.trapSignals();
 
-// Run a background task loop
+// Run a background task every 5 seconds
 await runContinuousLoop({
   intervalSeconds: 5,
   runCycle: async (isShutdownRequested) => {
-    if (isShutdownRequested()) return;
-    console.log("Running periodic task...");
-    // Simulate work
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    return { stop: false };
+    console.log("Running cycle...");
+    if (isShutdownRequested()) return { stop: true };
+    return { nextDelayMs: "immediate" };
   },
   onShutdown: async () => {
-    console.log("Shutting down loop");
+    await teardown.run();
   }
 });
-
-// Manual shutdown
-await teardown.run();
 ```
 
-## Teardown Management
+## Graceful Shutdown with `createTeardown`
 
-Idempotent resource teardown with signal trapping and LIFO cleanup order.
+Manages resource cleanup with LIFO execution order, signal trapping for SIGINT/SIGTERM, and idempotent teardown behavior.
 
-### createTeardown()
+### Core API
 
-Creates a teardown registry for managing cleanup functions.
+#### `createTeardown(): Teardown`
 
-**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
+Creates a teardown manager for registering cleanup functions.
 
 ```typescript
 const teardown = createTeardown();
 
 // Add cleanup functions
-const unregister = teardown.add(() => server.close());
+teardown.add(() => server.close());
 teardown.add(() => db.close());
 
-// Unregister a specific function if needed
-unregister();
+// Or use async functions
+teardown.add(async () => {
+  await flushPendingWrites();
+});
+```
 
-// Handle OS signals
-teardown.trapSignals();
+#### `Teardown.add(fn): () => void`
 
-// Run all cleanup
-await teardown.run();
+Registers a cleanup function. Returns an unregister function for removing it.
+
+```typescript
+const unregister = teardown.add(() => cleanup());
+
+// Later, remove it
+unregister();
 ```
 
-#### Teardown Interface
+#### `Teardown.run(): Promise<void>`
 
-| Method | Description |
-|--------|-------------|
-| `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 |
+Runs all cleanup functions in LIFO order. Safe to call multiple times—subsequent calls are no-ops.
+
+```typescript
+await teardown.run(); // Runs last-in-first-out
+```
 
-### Signal Trapping
+#### `Teardown.trapSignals(): () => void`
 
-Signal handlers are attached via `trapSignals()` and call `run()` then `process.exit(0)`.
+Wires SIGINT/SIGTERM to automatically call `run()` then `process.exit(0)`.
 
 ```typescript
 const untrap = teardown.trapSignals();
-// Later, if needed:
-untrap(); // Remove signal handlers
+
+// Later, restore default behavior
+untrap();
 ```
 
-## Continuous Loop Execution
+### Behavior Notes
+
+- Errors in teardown functions are caught and logged, allowing remaining functions to complete.
+- Signal handlers are added only once per process and cleaned up automatically when untrap() is called.
+
+## Continuous Loop with `runContinuousLoop`
+
+Runs a recurring task in a loop with built-in signal handling, dynamic delays, and configurable error policies.
 
-Interruptible loop with configurable cycle interval, error handling, and graceful shutdown.
+### Core Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `intervalSeconds` | `number` | Default delay between cycles in seconds |
+| `runCycle` | `() => Promise<RunCycleResult>` | Main function executed per cycle |
+| `getNextDelayMs` | `() => Delay \| undefined` | Optional custom delay resolver |
+| `onCycleError` | `ErrorHandler` | Custom error handling strategy |
+| `onShutdown` | `() => Promise<void>` | Cleanup hook called on shutdown |
+| `logger` | `ContinuousLoopLogger` | Optional logger (defaults to console) |
 
-### runContinuousLoop()
+### Return Values from `runCycle`
 
-Runs a function repeatedly with signal-aware sleep that can be interrupted.
+You can control loop behavior by returning one of:
+
+- **Delay value**: `number` (ms) or `"immediate"` to skip delay
+- **Control object**: `{ stop?: boolean; nextDelayMs?: Delay }`
 
 ```typescript
 await runContinuousLoop({
   intervalSeconds: 10,
-  runCycle: async (isShutdownRequested) => {
-    if (isShutdownRequested()) {
-      return { stop: true };
-    }
-    await doWork();
-    // Return a delay override
-    return 5000; // milliseconds
-  },
-  onCycleError: async (error, context) => {
-    console.error(`Cycle ${context.cycleNumber} failed:`, error);
-    return "continue"; // or "stop"
-  },
-  onShutdown: async () => {
-    await cleanup();
+  runCycle: async () => {
+    // Skip delay after this cycle
+    return "immediate";
   }
 });
 ```
 
-#### Loop Lifecycle
-
-- 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
+### Example: Backoff Loop
 
-### Options
-
-| 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 |
-
-### Cycle Return Values
+```typescript
+import { runContinuousLoop } from "@hardlydifficult/daemon";
 
-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
+type Result = { backoffMs: number } | { success: true };
 
-If the cycle returns a domain-specific result, use `getNextDelayMs` to derive the next delay.
+await runContinuousLoop({
+  intervalSeconds: 60,
+  runCycle: async () => {
+    const success = await attemptTask();
+    return success 
+      ? { success: true } 
+      : { backoffMs: Math.min(60_000, Math.random() * 5_000) };
+  },
+  getNextDelayMs: (result) => 
+    "backoffMs" in result ? result.backoffMs : undefined,
+  onShutdown: () => console.log("Stopping loop"),
+});
+```
 
 ### Error Handling
 
-By default:
-- Errors are logged to `console.error`
-- Loop continues to next cycle
-
-Custom error handling via `onCycleError` can override behavior:
+By default, cycle errors are logged to console and the loop continues. Custom error handling:
 
 ```typescript
-onCycleError: async (error, context) => {
-  if (error instanceof FatalError) {
-    return "stop"; // Terminate loop
+await runContinuousLoop({
+  intervalSeconds: 5,
+  runCycle: async () => { throw new Error("fail"); },
+  onCycleError: async (error, context) => {
+    console.error(`Cycle ${context.cycleNumber} failed: ${error.message}`);
+    return "stop"; // or "continue"
   }
-  return "continue"; // Proceed
-}
+});
 ```
 
-### Context Types
-
-#### ContinuousLoopCycleContext
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `cycleNumber` | `number` | 1-based cycle number |
-| `isShutdownRequested` | `() => boolean` | Check shutdown status |
-
-#### ContinuousLoopErrorContext
-
-Identical to `ContinuousLoopCycleContext`; passed to `onCycleError`.
-
-#### ContinuousLoopLogger
+### Shutdown Signals
 
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `warn(message, context?)` | `string`, `Record<string, unknown>` | Warning log |
-| `error(message, context?)` | `string`, `Record<string, unknown>` | Error log |
+The loop responds to `SIGINT` and `SIGTERM` by stopping after the current cycle completes. Use `isShutdownRequested()` inside `runCycle` to abort long-running work:
 
-Default logger uses `console.warn`/`console.error`.
+```typescript
+await runContinuousLoop({
+  intervalSeconds: 1,
+  runCycle: async (isShutdownRequested) => {
+    while (!isShutdownRequested()) {
+      await processChunk();
+    }
+    return { stop: true };
+  }
+});
+```

package/package.json

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