hive-cycle 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jacob K Lewis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Jacob K Lewis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,134 +1,134 @@
-![HiveCycle Logo](logo.png)
-
-# HiveCycle
-
-A modular, type-safe TypeScript framework for running background task queues. `HiveCycle` provides a robust backbone for processing queued jobs with concurrency control, automatic retries/requeues, and pluggable queue storage.
-
-## Features
-
-- **Continuous Execution**: Runs a worker loop that constantly polls for new tasks.
-- **Type Safe**: leveraging TypeScript generics to strongly type your task payloads.
-- **Modular**: Abstract `QueueAdapter` allowing you to swap the default In-Memory queue for Redis, RabbitMQ, or SQL/NoSQL databases.
-- **Concurrency Control**: Limit how many tasks are processed simultaneously.
-- **Recurring Tasks**: Built-in support for tasks that automatically requeue themselves (cron-like behavior).
-
-## Installation
-
-```bash
-npm install hive-cycle
-```
-
-## Quick Start
-
-### Basic Usage
-
-```typescript
-import { HiveCycle } from "hive-cycle";
-
-const app = new HiveCycle();
-
-// 1. Register a handler
-app.registerHandler("email", async (task) => {
-  console.log("Sending email to:", task.payload.to);
-  // Perform async work here...
-});
-
-// 2. Start the engine
-app.start();
-
-// 3. Queue a task
-app.enqueue("email", { to: "user@example.com" });
-```
-
-### Type Safety
-
-Define your task map interface to get full autocomplete and type checking for payloads.
-
-```typescript
-import { HiveCycle } from "hive-cycle";
-
-// Define your task types and their payloads
-interface MyTaskMap {
-  "send-email": { to: string; subject: string; body: string };
-  "generate-report": { reportId: string };
-}
-
-const app = new HiveCycle<MyTaskMap>();
-
-// ✅ Fully typed argument
-app.registerHandler("send-email", async (task) => {
-  // task.payload is { to: string; subject: string; body: string }
-  console.log(task.payload.subject);
-});
-
-// ✅ Type-checked enqueue
-app.enqueue("send-email", {
-  to: "test@example.com",
-  subject: "Welcome",
-  body: "Hello World",
-});
-```
-
-## Advanced Usage
-
-### Recurring Tasks
-
-You can schedule tasks to automatically requeue themselves after completion, creating a loop.
-
-```typescript
-await app.enqueue(
-  "cleanup-job",
-  { key: "temp-files" },
-  {
-    requeue: true,
-    requeueDelay: 5000, // Run again 5 seconds after completion
-  }
-);
-```
-
-### Configuration
-
-You can pass options to the constructor to tune performance.
-
-```typescript
-const app = new HiveCycle({
-  // How many tasks to process in parallel
-  maxConcurrency: 5,
-
-  // How often to check for new tasks when queue is empty (ms)
-  pollingInterval: 1000,
-
-  // Custom logger (defaults to console)
-  logger: myLogger,
-
-  // Custom Queue Adapter (defaults to MemoryQueue)
-  queue: new RedisQueueAdapter(),
-});
-```
-
-### Custom Queue Adapter
-
-To use a persistent store (like Redis), implement the `QueueAdapter` interface.
-
-```typescript
-import { QueueAdapter, Task } from "hive-cycle";
-
-class MyRedisQueue implements QueueAdapter {
-  async enqueue(task: Task): Promise<void> {
-    /* ... */
-  }
-  async dequeue(): Promise<Task | null> {
-    /* ... */
-  }
-  async acknowledge(taskId: string): Promise<void> {
-    /* ... */
-  }
-  async reject(taskId: string, error?: Error): Promise<void> {
-    /* ... */
-  }
-}
-```
-
-## License
-
-MIT
+![HiveCycle Logo](logo.png)
+
+# HiveCycle
+
+A modular, type-safe TypeScript framework for running background task queues. `HiveCycle` provides a robust backbone for processing queued jobs with concurrency control, automatic retries/requeues, and pluggable queue storage.
+
+## Features
+
+- **Continuous Execution**: Runs a worker loop that constantly polls for new tasks.
+- **Type Safe**: leveraging TypeScript generics to strongly type your task payloads.
+- **Modular**: Abstract `QueueAdapter` allowing you to swap the default In-Memory queue for Redis, RabbitMQ, or SQL/NoSQL databases.
+- **Concurrency Control**: Limit how many tasks are processed simultaneously.
+- **Recurring Tasks**: Built-in support for tasks that automatically requeue themselves (cron-like behavior).
+
+## Installation
+
+```bash
+npm install hive-cycle
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { HiveCycle } from "hive-cycle";
+
+const app = new HiveCycle();
+
+// 1. Register a handler
+app.registerHandler("email", async (task) => {
+  console.log("Sending email to:", task.payload.to);
+  // Perform async work here...
+});
+
+// 2. Start the engine
+app.start();
+
+// 3. Queue a task
+app.enqueue("email", { to: "user@example.com" });
+```
+
+### Type Safety
+
+Define your task map interface to get full autocomplete and type checking for payloads.
+
+```typescript
+import { HiveCycle } from "hive-cycle";
+
+// Define your task types and their payloads
+interface MyTaskMap {
+  "send-email": { to: string; subject: string; body: string };
+  "generate-report": { reportId: string };
+}
+
+const app = new HiveCycle<MyTaskMap>();
+
+// ✅ Fully typed argument
+app.registerHandler("send-email", async (task) => {
+  // task.payload is { to: string; subject: string; body: string }
+  console.log(task.payload.subject);
+});
+
+// ✅ Type-checked enqueue
+app.enqueue("send-email", {
+  to: "test@example.com",
+  subject: "Welcome",
+  body: "Hello World",
+});
+```
+
+## Advanced Usage
+
+### Recurring Tasks
+
+You can schedule tasks to automatically requeue themselves after completion, creating a loop.
+
+```typescript
+await app.enqueue(
+  "cleanup-job",
+  { key: "temp-files" },
+  {
+    requeue: true,
+    requeueDelay: 5000, // Run again 5 seconds after completion
+  }
+);
+```
+
+### Configuration
+
+You can pass options to the constructor to tune performance.
+
+```typescript
+const app = new HiveCycle({
+  // How many tasks to process in parallel
+  maxConcurrency: 5,
+
+  // How often to check for new tasks when queue is empty (ms)
+  pollingInterval: 1000,
+
+  // Custom logger (defaults to console)
+  logger: myLogger,
+
+  // Custom Queue Adapter (defaults to MemoryQueue)
+  queue: new RedisQueueAdapter(),
+});
+```
+
+### Custom Queue Adapter
+
+To use a persistent store (like Redis), implement the `QueueAdapter` interface.
+
+```typescript
+import { QueueAdapter, Task } from "hive-cycle";
+
+class MyRedisQueue implements QueueAdapter {
+  async enqueue(task: Task): Promise<void> {
+    /* ... */
+  }
+  async dequeue(): Promise<Task | null> {
+    /* ... */
+  }
+  async acknowledge(taskId: string): Promise<void> {
+    /* ... */
+  }
+  async reject(taskId: string, error?: Error): Promise<void> {
+    /* ... */
+  }
+}
+```
+
+## License
+
+MIT

package/dist/src/HiveCycle.d.ts

@@ -5,6 +5,7 @@ export declare class HiveCycle<TaskMap extends Record<string, any> = Record<stri
     private isRunning;
     private options;
     private activeCount;
+    private server?;
     constructor(options?: HiveCycleOptions);
     /**
      * Register a handler for a specific task type.
@@ -22,6 +23,8 @@ export declare class HiveCycle<TaskMap extends Record<string, any> = Record<stri
      * Stop the worker loop.
      */
     stop(): void;
+    private startHealthServer;
+    private stopHealthServer;
     private loop;
     private handleTask;
     private sleep;

package/dist/src/HiveCycle.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HiveCycle = void 0;
+const http_1 = require("http");
 const MemoryQueue_1 = require("./MemoryQueue");
 // I will implement a simple ID generator to avoid deps for now if I didn't install uuid.
 // Wait, I haven't installed `uuid`. I should probably implement a simple random ID or install it later.
@@ -21,6 +22,7 @@ class HiveCycle {
             pollingInterval: options.pollingInterval || 1000,
             maxConcurrency: options.maxConcurrency || 1,
             logger: options.logger || console,
+            healthPort: options.healthPort,
         };
         this.queue = this.options.queue;
     }
@@ -52,6 +54,9 @@ class HiveCycle {
             return;
         this.isRunning = true;
         this.options.logger.log("HiveCycle engine started.");
+        if (this.options.healthPort) {
+            this.startHealthServer(this.options.healthPort);
+        }
         this.loop();
     }
     /**
@@ -60,6 +65,35 @@ class HiveCycle {
     stop() {
         this.isRunning = false;
         this.options.logger.log("HiveCycle engine stopping...");
+        this.stopHealthServer();
+    }
+    startHealthServer(port) {
+        this.server = (0, http_1.createServer)((req, res) => {
+            if (req.url === "/health" && req.method === "GET") {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    status: "ok",
+                    running: this.isRunning,
+                    activeCount: this.activeCount,
+                }));
+            }
+            else {
+                res.writeHead(404);
+                res.end();
+            }
+        });
+        this.server.listen(port, () => {
+            this.options.logger.log(`Health check server listening on port ${port}`);
+        });
+        this.server.on("error", (err) => {
+            this.options.logger.error("Health server error:", err);
+        });
+    }
+    stopHealthServer() {
+        if (this.server) {
+            this.server.close();
+            this.server = undefined;
+        }
     }
     async loop() {
         while (this.isRunning) {

package/dist/src/types.d.ts

@@ -34,6 +34,10 @@ export interface HiveCycleOptions {
     pollingInterval?: number;
     maxConcurrency?: number;
     logger?: Logger;
+    /**
+     * If provided, starts a health check HTTP server on this port.
+     */
+    healthPort?: number;
 }
 export interface Logger {
     log(message: string, ...args: any[]): void;

package/package.json

@@ -1,29 +1,30 @@
-{
-    "name": "hive-cycle",
-    "version": "0.1.0",
-    "description": "A modular TypeScript framework for background task processing",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "files": [
-        "dist/src",
-        "README.md"
-    ],
-    "scripts": {
-        "build": "tsc",
-        "prepublishOnly": "npm run build"
-    },
-    "keywords": [
-        "queue",
-        "background-jobs",
-        "task-runner",
-        "framework",
-        "typescript"
-    ],
-    "author": "Jacob K Lewis",
-    "repository": "jacobklewis/Hive-Cycle",
-    "license": "MIT",
-    "devDependencies": {
-        "typescript": "^5.0.0",
-        "@types/node": "^20.0.0"
-    }
+{
+    "name": "hive-cycle",
+    "version": "0.2.0",
+    "description": "A modular TypeScript framework for background task processing",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist/src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "test": "echo \"No tests specified\" && exit 0",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "queue",
+        "background-jobs",
+        "task-runner",
+        "framework",
+        "typescript"
+    ],
+    "author": "Jacob K Lewis",
+    "repository": "jacobklewis/Hive-Cycle",
+    "license": "MIT",
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@types/node": "^20.0.0"
+    }
 }