@hardlydifficult/daemon 1.0.1 → 1.0.3

package/README.md

@@ -1,6 +1,9 @@
 # @hardlydifficult/daemon
 
-Idempotent resource teardown with signal trapping and LIFO cleanup ordering.
+Opinionated utilities for long-running Node.js services:
+
+- `createTeardown()` for idempotent cleanup with signal trapping
+- `runContinuousLoop()` for daemon-style cycle execution
 
 ## Installation
 
@@ -13,102 +16,250 @@ npm install @hardlydifficult/daemon
 ```typescript
 import { createTeardown, runContinuousLoop } from "@hardlydifficult/daemon";
 
-// Register cleanup functions
+// Graceful shutdown with LIFO cleanup
 const teardown = createTeardown();
-teardown.add(() => console.log("Closing server"));
-teardown.add(() => console.log("Closing database"));
+teardown.add(() => console.log("Cleaning up server"));
+teardown.add(() => console.log("Closing database connection"));
 teardown.trapSignals();
 
-// Run teardown when ready
-await teardown.run();
-// Logs:
-// Closing database
-// Closing server
+// 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
 
-Resource cleanup registry with idempotent execution and LIFO ordering.
-
-### `createTeardown()`
-
-Creates a teardown registry for managing resource cleanup.
+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();
 ```
 
-#### `.add(fn: () => void | Promise<void>): () => void`
+### Behavior
 
-Registers a teardown function. Returns an unregister function.
+- **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();
-const unregister = teardown.add(async () => {
-  await server.close();
-});
 
-// Unregister before teardown if needed
+// 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
 ```
 
-#### `.run(): Promise<void>`
+#### 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 |
 
-Runs all teardown functions in LIFO order. Idempotent — subsequent calls are no-ops.
+### 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();
-// Logs:
+// Output:
+// Third
 // Second
 // First
 ```
 
-#### `.trapSignals(): () => void`
+## Continuous Loop Execution
 
-Wires SIGTERM/SIGINT handlers to run teardown and exit. Returns an untrap function to remove handlers.
+Use `runContinuousLoop()` to run work cycles with graceful shutdown, dynamic
+delay control, and configurable error policy.
 
 ```typescript
-const teardown = createTeardown();
-const untrap = teardown.trapSignals();
+import { runContinuousLoop } from "@hardlydifficult/daemon";
+
+await runContinuousLoop({
+  intervalSeconds: 30,
+  async runCycle(isShutdownRequested) {
+    if (isShutdownRequested()) {
+      return { stop: true };
+    }
 
-// Later, to stop trapping signals
-untrap();
+    const didWork = await syncQueue();
+    if (!didWork) {
+      return 60_000; // ms
+    }
+
+    return "immediate";
+  },
+  onCycleError(error, context) {
+    notifyOps(error, { cycleNumber: context.cycleNumber });
+    return "continue"; // or "stop"
+  },
+});
 ```
 
-## Continuous Loop Execution
+### 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
 
-Runs cyclic tasks with graceful shutdown support.
+If your cycle returns domain data, derive schedule policy with
+`getNextDelayMs(result, context)`.
 
-### `runContinuousLoop(options: ContinuousLoopOptions): Promise<void>`
+### Error Handling
 
-Executes a cycle function repeatedly with interruptible sleep and signal 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:
 
 ```typescript
-import { runContinuousLoop } from "@hardlydifficult/daemon";
+const logger = {
+  warn: (message, context) => myLogger.warn(message, context),
+  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 (isShutdownRequested) => {
-    if (isShutdownRequested()) {
-      return;
+  runCycle: async () => {
+    const data = await fetchData();
+    if (!data) {
+      return { nextDelayMs: "immediate" }; // Retry immediately
+    }
+    if (data.done) {
+      return { stop: true }; // End loop
     }
-    // Perform work here
-    console.log("Running cycle...");
+    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),
   },
-  onShutdown: async () => {
-    console.log("Shutdown complete");
-  }
 });
 ```
 
-#### Options
+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();
+  },
+});
 
-| Name              | Type                            | Description                                    |
-|-------------------|---------------------------------|------------------------------------------------|
-| `intervalSeconds` | `number`                        | Interval between cycles in seconds             |
-| `runCycle`        | `(isShutdownRequested: () => boolean) => Promise<unknown>` | Callback to run each cycle (shutdown check provided) |
-| `onShutdown?`     | `() => Promise<void>`           | Optional cleanup callback after shutdown       |
+// Later...
+process.kill(process.pid, "SIGTERM"); // Triggers graceful shutdown
+await loopPromise; // Resolves after onShutdown completes
+```

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { createTeardown, type Teardown } from "./createTeardown.js";
-export { runContinuousLoop, type ContinuousLoopOptions, } from "./runContinuousLoop.js";
+export { runContinuousLoop, type ContinuousLoopCycleContext, type ContinuousLoopCycleControl, type ContinuousLoopDelay, type ContinuousLoopErrorAction, type ContinuousLoopErrorHandler, type ContinuousLoopErrorContext, type ContinuousLoopLogger, type ContinuousLoopOptions, type ContinuousLoopRunCycleResult, } from "./runContinuousLoop.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,4BAA4B,GAClC,MAAM,wBAAwB,CAAC"}

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yDAAoE;AAA3D,mHAAA,cAAc,OAAA;AACvB,+DAWgC;AAV9B,yHAAA,iBAAiB,OAAA"}

package/dist/runContinuousLoop.d.ts

@@ -4,19 +4,62 @@
  * This module provides interruptible sleep and continuous loop functionality with proper signal handling for
  * SIGINT/SIGTERM.
  */
+/** Delay directive returned by runCycle/getNextDelayMs. */
+export type ContinuousLoopDelay = number | "immediate";
+/** Context provided to each cycle and delay resolver. */
+export interface ContinuousLoopCycleContext {
+    /** 1-based cycle number for the current loop iteration */
+    cycleNumber: number;
+    /** Function to check if shutdown has been requested */
+    isShutdownRequested: () => boolean;
+}
+/** Context provided to cycle error handling callbacks. */
+export type ContinuousLoopErrorContext = ContinuousLoopCycleContext;
+/** Action returned by onCycleError to control loop behavior. */
+export type ContinuousLoopErrorAction = "continue" | "stop";
+type ContinuousLoopErrorDecision = ContinuousLoopErrorAction | undefined;
+/** Callback used to process cycle errors and decide loop policy. */
+export type ContinuousLoopErrorHandler = (error: unknown, context: ContinuousLoopErrorContext) => ContinuousLoopErrorDecision | Promise<ContinuousLoopErrorDecision>;
+/** Optional control directives that can be returned from runCycle. */
+export interface ContinuousLoopCycleControl {
+    /** Stop the loop after this cycle completes. */
+    stop?: boolean;
+    /** Override delay before the next cycle. */
+    nextDelayMs?: ContinuousLoopDelay;
+}
+/** Minimal logger interface compatible with @hardlydifficult/logger. */
+export interface ContinuousLoopLogger {
+    warn(message: string, context?: Readonly<Record<string, unknown>>): void;
+    error(message: string, context?: Readonly<Record<string, unknown>>): void;
+}
+/** Supported return shape from runCycle. */
+export type ContinuousLoopRunCycleResult<TResult = unknown> = TResult | ContinuousLoopDelay | ContinuousLoopCycleControl;
 /** Options for running a continuous loop */
-export interface ContinuousLoopOptions {
+export interface ContinuousLoopOptions<TResult = unknown> {
     /** 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)
+     * @returns Promise resolving to cycle result and optional control directives
+     */
+    runCycle: (isShutdownRequested: () => boolean) => Promise<ContinuousLoopRunCycleResult<TResult>>;
+    /**
+     * Optional hook to derive the next delay from a runCycle result.
+     * Used only when runCycle does not directly return a delay directive.
+     */
+    getNextDelayMs?: (result: ContinuousLoopRunCycleResult<TResult>, context: ContinuousLoopCycleContext) => ContinuousLoopDelay | undefined;
+    /**
+     * Optional error callback for cycle failures.
+     *
+     * Return "stop" to end the loop, otherwise it will continue.
      */
-    runCycle: (isShutdownRequested: () => boolean) => Promise<unknown>;
+    onCycleError?: ContinuousLoopErrorHandler;
     /** Optional callback for cleanup on shutdown */
-    onShutdown?: () => Promise<void>;
+    onShutdown?: () => void | Promise<void>;
+    /** Optional logger (defaults to console warn/error) */
+    logger?: ContinuousLoopLogger;
 }
 /**
  * Run a function in a continuous loop with graceful shutdown support.
@@ -25,10 +68,13 @@ export interface ContinuousLoopOptions {
  *
  * - 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
+ * - Per-cycle delay control via return value or getNextDelayMs
+ * - Graceful stop signaling from runCycle ({ stop: true })
+ * - Configurable error policy via onCycleError
  * - 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>;
+export declare function runContinuousLoop<TResult = unknown>(options: ContinuousLoopOptions<TResult>): Promise<void>;
+export {};
 //# sourceMappingURL=runContinuousLoop.d.ts.map

package/dist/runContinuousLoop.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"runContinuousLoop.d.ts","sourceRoot":"","sources":["../src/runContinuousLoop.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2DAA2D;AAC3D,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEvD,yDAAyD;AACzD,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,mBAAmB,EAAE,MAAM,OAAO,CAAC;CACpC;AAED,0DAA0D;AAC1D,MAAM,MAAM,0BAA0B,GAAG,0BAA0B,CAAC;AAEpE,gEAAgE;AAChE,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,MAAM,CAAC;AAE5D,KAAK,2BAA2B,GAAG,yBAAyB,GAAG,SAAS,CAAC;AAEzE,oEAAoE;AACpE,MAAM,MAAM,0BAA0B,GAAG,CACvC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,0BAA0B,KAChC,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;AAExE,sEAAsE;AACtE,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IACzE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAC3E;AAED,4CAA4C;AAC5C,MAAM,MAAM,4BAA4B,CAAC,OAAO,GAAG,OAAO,IACtD,OAAO,GACP,mBAAmB,GACnB,0BAA0B,CAAC;AAE/B,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB,CAAC,OAAO,GAAG,OAAO;IACtD,yCAAyC;IACzC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,EAAE,CACR,mBAAmB,EAAE,MAAM,OAAO,KAC/B,OAAO,CAAC,4BAA4B,CAAC,OAAO,CAAC,CAAC,CAAC;IACpD;;;OAGG;IACH,cAAc,CAAC,EAAE,CACf,MAAM,EAAE,4BAA4B,CAAC,OAAO,CAAC,EAC7C,OAAO,EAAE,0BAA0B,KAChC,mBAAmB,GAAG,SAAS,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,0BAA0B,CAAC;IAC1C,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,uDAAuD;IACvD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AA2HD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAG,OAAO,EACvD,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAwGf"}

package/dist/runContinuousLoop.js

@@ -7,6 +7,22 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runContinuousLoop = runContinuousLoop;
+const defaultLogger = {
+    warn(message, context) {
+        if (context === undefined) {
+            console.warn(message);
+            return;
+        }
+        console.warn(message, context);
+    },
+    error(message, context) {
+        if (context === undefined) {
+            console.error(message);
+            return;
+        }
+        console.error(message, context);
+    },
+};
 /**
  * Creates an interruptible sleep that can be woken early by calling the returned cancel function.
  *
@@ -35,6 +51,57 @@ function createInterruptibleSleep(durationMs) {
     };
     return { promise, cancel };
 }
+function normalizeDelayMs(delayMs, source) {
+    if (delayMs === "immediate") {
+        return delayMs;
+    }
+    if (!Number.isFinite(delayMs) || delayMs < 0) {
+        if (source === "intervalSeconds") {
+            throw new Error("intervalSeconds must be a non-negative finite number");
+        }
+        throw new Error(`${source} must return a non-negative finite number or "immediate"`);
+    }
+    return delayMs;
+}
+function getControlFromCycleResult(result) {
+    if (typeof result === "number" || result === "immediate") {
+        return { nextDelayMs: result };
+    }
+    if (typeof result !== "object" || result === null) {
+        return {};
+    }
+    const value = result;
+    const { nextDelayMs } = value;
+    return {
+        stop: value.stop === true,
+        nextDelayMs: typeof nextDelayMs === "number" || nextDelayMs === "immediate"
+            ? nextDelayMs
+            : undefined,
+    };
+}
+async function handleCycleError(error, context, onCycleError, logger) {
+    if (onCycleError !== undefined) {
+        try {
+            const action = await onCycleError(error, context);
+            return action === "stop" ? "stop" : "continue";
+        }
+        catch (handlerError) {
+            logger.error("onCycleError handler failed", {
+                cycleNumber: context.cycleNumber,
+                cycleError: error instanceof Error ? error.message : String(error),
+                handlerError: handlerError instanceof Error
+                    ? handlerError.message
+                    : String(handlerError),
+            });
+            return "continue";
+        }
+    }
+    logger.error("Cycle error", {
+        cycleNumber: context.cycleNumber,
+        error: error instanceof Error ? error.message : String(error),
+    });
+    return "continue";
+}
 /**
  * Run a function in a continuous loop with graceful shutdown support.
  *
@@ -42,17 +109,21 @@ function createInterruptibleSleep(durationMs) {
  *
  * - 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
+ * - Per-cycle delay control via return value or getNextDelayMs
+ * - Graceful stop signaling from runCycle ({ stop: true })
+ * - Configurable error policy via onCycleError
  * - 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;
+    const { intervalSeconds, runCycle, getNextDelayMs, onCycleError, onShutdown, logger = defaultLogger, } = options;
+    const defaultDelayMs = normalizeDelayMs(intervalSeconds * 1000, "intervalSeconds");
     let shutdownRequested = false;
     let cancelCurrentSleep = null;
+    let cycleNumber = 0;
     const handleShutdown = (signal) => {
-        console.warn(`Received ${signal}, shutting down gracefully...`);
+        logger.warn(`Received ${signal}, shutting down gracefully...`);
         shutdownRequested = true;
         if (cancelCurrentSleep !== null) {
             cancelCurrentSleep();
@@ -71,17 +142,46 @@ async function runContinuousLoop(options) {
     const shouldContinue = () => !shutdownRequested;
     try {
         while (shouldContinue()) {
+            cycleNumber += 1;
+            const cycleContext = {
+                cycleNumber,
+                isShutdownRequested,
+            };
+            let nextDelayMs = defaultDelayMs;
             try {
-                await runCycle(isShutdownRequested);
+                const cycleResult = await runCycle(isShutdownRequested);
+                if (!shouldContinue()) {
+                    continue;
+                }
+                const cycleControl = getControlFromCycleResult(cycleResult);
+                if (cycleControl.stop === true) {
+                    shutdownRequested = true;
+                    continue;
+                }
+                if (cycleControl.nextDelayMs !== undefined) {
+                    nextDelayMs = normalizeDelayMs(cycleControl.nextDelayMs, "runCycle");
+                }
+                else if (getNextDelayMs !== undefined) {
+                    const derivedDelay = getNextDelayMs(cycleResult, cycleContext);
+                    if (derivedDelay !== undefined) {
+                        nextDelayMs = normalizeDelayMs(derivedDelay, "getNextDelayMs");
+                    }
+                }
             }
             catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                console.error(`Cycle error: ${errorMessage}`);
+                const action = await handleCycleError(error, cycleContext, onCycleError, logger);
+                if (action === "stop") {
+                    shutdownRequested = true;
+                    continue;
+                }
             }
             if (!shouldContinue()) {
                 break;
             }
-            const sleep = createInterruptibleSleep(intervalSeconds * 1000);
+            if (nextDelayMs === "immediate") {
+                continue;
+            }
+            const sleep = createInterruptibleSleep(nextDelayMs);
             cancelCurrentSleep = sleep.cancel;
             await sleep.promise;
             cancelCurrentSleep = null;

package/dist/runContinuousLoop.js.map

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

package/package.json

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