@hardlydifficult/daemon 1.0.0 → 1.0.1

package/README.md

@@ -1,123 +1,114 @@
-# @hardlydifficult/teardown
+# @hardlydifficult/daemon
 
-Idempotent resource teardown with signal trapping. Register cleanup functions once at resource creation time — all exit paths call a single `run()`.
+Idempotent resource teardown with signal trapping and LIFO cleanup ordering.
 
 ## Installation
 
 ```bash
-npm install @hardlydifficult/teardown
+npm install @hardlydifficult/daemon
 ```
 
 ## Quick Start
 
 ```typescript
-import { createTeardown } from "@hardlydifficult/teardown";
+import { createTeardown, runContinuousLoop } from "@hardlydifficult/daemon";
 
+// Register cleanup functions
 const teardown = createTeardown();
-teardown.add(() => server.stop());
-teardown.add(() => db.close());
+teardown.add(() => console.log("Closing server"));
+teardown.add(() => console.log("Closing database"));
 teardown.trapSignals();
 
-// Any manual exit path:
+// Run teardown when ready
 await teardown.run();
+// Logs:
+// Closing database
+// Closing server
 ```
 
-## Creating a Teardown Registry
+## Teardown Management
 
-Use `createTeardown()` to create a new teardown registry that manages cleanup functions.
+Resource cleanup registry with idempotent execution and LIFO ordering.
 
-```typescript
-import { createTeardown } from "@hardlydifficult/teardown";
+### `createTeardown()`
 
+Creates a teardown registry for managing resource cleanup.
+
+```typescript
 const teardown = createTeardown();
 ```
 
-## Registering Cleanup Functions
+#### `.add(fn: () => void | Promise<void>): () => void`
 
-Call `add()` to register a cleanup function. Functions run in LIFO order (last added runs first). The `add()` method returns an unregister function for selective cleanup.
+Registers a teardown function. Returns an unregister function.
 
 ```typescript
 const teardown = createTeardown();
-
-// Register sync cleanup
-teardown.add(() => {
-  console.log("Closing server");
-  server.stop();
+const unregister = teardown.add(async () => {
+  await server.close();
 });
 
-// Register async cleanup
-teardown.add(async () => {
-  console.log("Closing database");
-  await db.close();
-});
-
-// Unregister a specific function
-const unregister = teardown.add(() => {
-  console.log("This won't run");
-});
+// Unregister before teardown if needed
 unregister();
-
-await teardown.run();
-// Output:
-// Closing database
-// Closing server
 ```
 
-## Running Teardown
+#### `.run(): Promise<void>`
 
-Call `run()` to execute all registered cleanup functions in LIFO order. The method is idempotent — subsequent calls are no-ops.
+Runs all teardown functions in LIFO order. Idempotent — subsequent calls are no-ops.
 
 ```typescript
 const teardown = createTeardown();
-teardown.add(() => console.log("cleanup"));
-
-await teardown.run();
-// Output: cleanup
+teardown.add(() => console.log("First"));
+teardown.add(() => console.log("Second"));
 
 await teardown.run();
-// No output (idempotent)
+// Logs:
+// Second
+// First
 ```
 
-## Signal Trapping
+#### `.trapSignals(): () => void`
 
-Call `trapSignals()` to automatically run teardown when the process receives SIGTERM or SIGINT signals. Returns an untrap function to remove signal handlers.
+Wires SIGTERM/SIGINT handlers to run teardown and exit. Returns an untrap function to remove handlers.
 
 ```typescript
 const teardown = createTeardown();
-teardown.add(() => server.stop());
-
-// Wire SIGTERM/SIGINT to run() then process.exit(0)
 const untrap = teardown.trapSignals();
 
-// Later, if needed:
+// Later, to stop trapping signals
 untrap();
 ```
 
-## Error Resilience
+## Continuous Loop Execution
 
-Each teardown function is wrapped in try/catch. Errors don't block remaining teardowns — all functions run regardless of failures.
+Runs cyclic tasks with graceful shutdown support.
 
-```typescript
-const teardown = createTeardown();
+### `runContinuousLoop(options: ContinuousLoopOptions): Promise<void>`
 
-teardown.add(() => {
-  throw new Error("First cleanup fails");
-});
-teardown.add(() => {
-  console.log("Second cleanup still runs");
-});
+Executes a cycle function repeatedly with interruptible sleep and signal handling.
 
-await teardown.run();
-// Output: Second cleanup still runs
+```typescript
+import { runContinuousLoop } from "@hardlydifficult/daemon";
+
+await runContinuousLoop({
+  intervalSeconds: 5,
+  runCycle: async (isShutdownRequested) => {
+    if (isShutdownRequested()) {
+      return;
+    }
+    // Perform work here
+    console.log("Running cycle...");
+  },
+  onShutdown: async () => {
+    console.log("Shutdown complete");
+  }
+});
 ```
 
-## Behavior Reference
+#### Options
 
-| Behavior | Details |
-|----------|---------|
-| **LIFO order** | Teardowns run in reverse registration order (last added runs first) |
-| **Idempotent** | `run()` executes once; subsequent calls are no-ops |
-| **Error resilient** | Each function is wrapped in try/catch; failures don't block remaining teardowns |
-| **Safe unregister** | `add()` returns an unregister function; safe to call multiple times |
-| **Post-run add** | `add()` after `run()` is a silent no-op |
-| **Duplicate safe** | Same function added twice runs twice; unregister only removes its own registration |
+| 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       |

package/package.json

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