@hardlydifficult/daemon 1.0.4 → 1.0.6

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
+A utility library for building long-running Node.js processes with graceful shutdown and continuous background task execution.
 
 ## Installation
 
@@ -13,303 +10,166 @@ npm install @hardlydifficult/daemon
 
 ## Quick Start
 
-Create a daemon with signal-trapped teardown and a continuous loop:
-
 ```typescript
-import { createTeardown, runContinuousLoop } from "@hardlydifficult/daemon";
+import { runContinuousLoop, createTeardown } from "@hardlydifficult/daemon";
 
+// Setup graceful shutdown
 const teardown = createTeardown();
-
-// Register cleanup for resources
-teardown.add(() => console.log("Cleanup: closing server"));
-teardown.add(() => console.log("Cleanup: disconnecting database"));
-
-// Trap SIGINT/SIGTERM
+teardown.add(() => console.log("Shutting down..."));
 teardown.trapSignals();
 
-// Run a continuous loop
+// Run a background task every 5 seconds
 await runContinuousLoop({
   intervalSeconds: 5,
-  async runCycle(isShutdownRequested) {
+  runCycle: async (isShutdownRequested) => {
     console.log("Running cycle...");
-    if (isShutdownRequested()) {
-      return { stop: true };
-    }
-    // Perform background task
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    return { stop: true }; // Stop after first cycle for demo
+    if (isShutdownRequested()) return { stop: true };
+    return { nextDelayMs: "immediate" };
   },
   onShutdown: async () => {
-    console.log("Shutdown complete");
     await teardown.run();
   }
 });
 ```
 
-## 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();
-
-await teardown.run();
-```
+## Graceful Shutdown with `createTeardown`
 
-### Behavior
+Manages resource cleanup with LIFO execution order, signal trapping for SIGINT/SIGTERM, and idempotent teardown 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
+### Core API
 
-### `createTeardown()`
+#### `createTeardown(): Teardown`
 
-Creates a teardown registry with idempotent resource cleanup.
+Creates a teardown manager for registering cleanup functions.
 
 ```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
-```
+// Add cleanup functions
+teardown.add(() => server.close());
+teardown.add(() => db.close());
 
-#### 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
-
-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
+// Or use async functions
+teardown.add(async () => {
+  await flushPendingWrites();
+});
 ```
 
-## Continuous Loop Execution
+#### `Teardown.add(fn): () => void`
 
-Use `runContinuousLoop()` to run work cycles with graceful shutdown, dynamic
-delay control, and configurable error policy.
+Registers a cleanup function. Returns an unregister function for removing it.
 
 ```typescript
-import { runContinuousLoop } from "@hardlydifficult/daemon";
+const unregister = teardown.add(() => cleanup());
 
-await runContinuousLoop({
-  intervalSeconds: 30,
-  async runCycle(isShutdownRequested) {
-    if (isShutdownRequested()) {
-      return { stop: true };
-    }
-
-    const didWork = await syncQueue();
-    if (!didWork) {
-      return 60_000; // ms
-    }
-
-    return "immediate";
-  },
-  onCycleError(error, context) {
-    notifyOps(error, { cycleNumber: context.cycleNumber });
-    return "continue"; // or "stop"
-  },
-});
+// Later, remove it
+unregister();
 ```
 
-### 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
+#### `Teardown.run(): Promise<void>`
 
-### Optional Delay Resolver
-
-If your cycle returns domain data, derive schedule policy with
-`getNextDelayMs(result, context)`.
-
-### 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
-
-By default, warnings and errors use `console.warn` and `console.error`. Pass
-`logger` to integrate your own logging implementation:
+Runs all cleanup functions in LIFO order. Safe to call multiple times—subsequent calls are no-ops.
 
 ```typescript
-const logger = {
-  warn: (message, context) => myLogger.warn(message, context),
-  error: (message, context) => myLogger.error(message, context),
-};
+await teardown.run(); // Runs last-in-first-out
 ```
 
-### `runContinuousLoop()` Options
+#### `Teardown.trapSignals(): () => void`
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `intervalSeconds` | `number` | — | Interval between cycles in seconds |
-| `runCycle` | `Function` | — | Callback for each cycle |
-| `getNextDelayMs?` | `Function` | — | Derive delay from cycle result |
-| `onCycleError?` | `Function` | — | Handle cycle errors |
-| `onShutdown?` | `Function` | — | Cleanup on shutdown |
-| `logger?` | `ContinuousLoopLogger` | `console` | Logger for warnings/errors |
-
-### `ContinuousLoopRunCycleResult`
-
-The return type supports:
-- Raw delay (`number` or `"immediate"`)
-- Control object: `{ stop?: boolean; nextDelayMs?: ContinuousLoopDelay }`
-
-**Example:**
+Wires SIGINT/SIGTERM to automatically call `run()` then `process.exit(0)`.
 
 ```typescript
-async runCycle() {
-  // Return raw delay
-  return 5000;
-  
-  // Or return control directives
-  return { nextDelayMs: "immediate", stop: false };
-}
-```
-
-### `ContinuousLoopDelay`
+const untrap = teardown.trapSignals();
 
-```typescript
-type ContinuousLoopDelay = number | "immediate"
+// Later, restore default behavior
+untrap();
 ```
 
-### `ContinuousLoopCycleControl`
+### Behavior Notes
 
-```typescript
-interface ContinuousLoopCycleControl {
-  stop?: boolean;
-  nextDelayMs?: ContinuousLoopDelay;
-}
-```
+- 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.
 
-### `ContinuousLoopCycleContext`
+## Continuous Loop with `runContinuousLoop`
 
-Provides context to cycle and delay resolver functions.
+Runs a recurring task in a loop with built-in signal handling, dynamic delays, and configurable error policies.
 
-```typescript
-interface ContinuousLoopCycleContext {
-  cycleNumber: number;
-  isShutdownRequested: () => boolean;
-}
-```
+### Core Options
 
-### `ContinuousLoopErrorContext`
+| 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) |
 
-Same as `ContinuousLoopCycleContext`.
+### Return Values from `runCycle`
 
-### `ContinuousLoopErrorHandler`
+You can control loop behavior by returning one of:
 
-Handles errors and returns `"stop"` or `"continue"`.
-
-**Signature:**
+- **Delay value**: `number` (ms) or `"immediate"` to skip delay
+- **Control object**: `{ stop?: boolean; nextDelayMs?: Delay }`
 
 ```typescript
-type ContinuousLoopErrorHandler = (
-  error: unknown,
-  context: ContinuousLoopErrorContext
-) => ContinuousLoopErrorAction | Promise<ContinuousLoopErrorAction>
+await runContinuousLoop({
+  intervalSeconds: 10,
+  runCycle: async () => {
+    // Skip delay after this cycle
+    return "immediate";
+  }
+});
 ```
 
-**Example:**
+### Example: Backoff Loop
 
 ```typescript
-onCycleError: async (error, context) => {
-  console.error(`Cycle ${context.cycleNumber} failed: ${error.message}`);
-  return "stop"; // or "continue"
-}
-```
+import { runContinuousLoop } from "@hardlydifficult/daemon";
 
-### `ContinuousLoopErrorAction`
+type Result = { backoffMs: number } | { success: true };
 
-```typescript
-type ContinuousLoopErrorAction = "continue" | "stop"
+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"),
+});
 ```
 
-### `ContinuousLoopLogger`
-
-```typescript
-interface ContinuousLoopLogger {
-  warn(message: string, context?: Readonly<Record<string, unknown>>): void;
-  error(message: string, context?: Readonly<Record<string, unknown>>): void;
-}
-```
+### Error Handling
 
-**Example:**
+By default, cycle errors are logged to console and the loop continues. Custom error handling:
 
 ```typescript
-const logger = {
-  warn: (msg) => console.warn(`[WARN] ${msg}`),
-  error: (msg) => console.error(`[ERROR] ${msg}`)
-};
-
 await runContinuousLoop({
-  intervalSeconds: 10,
-  runCycle: () => Promise.resolve(),
-  logger
+  intervalSeconds: 5,
+  runCycle: async () => { throw new Error("fail"); },
+  onCycleError: async (error, context) => {
+    console.error(`Cycle ${context.cycleNumber} failed: ${error.message}`);
+    return "stop"; // or "continue"
+  }
 });
 ```
 
-## Shutdown
+### Shutdown Signals
 
-Signal handlers are automatically registered for `SIGINT` and `SIGTERM`, and removed on completion.
+The loop responds to `SIGINT` and `SIGTERM` by stopping after the current cycle completes. Use `isShutdownRequested()` inside `runCycle` to abort long-running work:
 
 ```typescript
-const loopPromise = runContinuousLoop({
+await runContinuousLoop({
   intervalSeconds: 1,
   runCycle: async (isShutdownRequested) => {
     while (!isShutdownRequested()) {
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await processChunk();
     }
-  },
-  onShutdown: async () => {
-    await db.close();
-  },
+    return { stop: true };
+  }
 });
-
-// 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.4",
+  "version": "1.0.6",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [