hive-cycle 0.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +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

package/dist/src/HiveCycle.d.ts

@@ -0,0 +1,28 @@
+import { HiveCycleOptions, Task, TaskHandler } from "./types";
+export declare class HiveCycle<TaskMap extends Record<string, any> = Record<string, any>> {
+    private queue;
+    private handlers;
+    private isRunning;
+    private options;
+    private activeCount;
+    constructor(options?: HiveCycleOptions);
+    /**
+     * Register a handler for a specific task type.
+     */
+    registerHandler<K extends keyof TaskMap & string>(type: K, handler: TaskHandler<TaskMap[K]>): void;
+    /**
+     * Enqueue a new task.
+     */
+    enqueue<K extends keyof TaskMap & string>(type: K, payload: TaskMap[K], options?: Partial<Task>): Promise<string>;
+    /**
+     * Start the worker loop.
+     */
+    start(): void;
+    /**
+     * Stop the worker loop.
+     */
+    stop(): void;
+    private loop;
+    private handleTask;
+    private sleep;
+}

package/dist/src/HiveCycle.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HiveCycle = void 0;
+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.
+// User didn't ask for uuid specifically, so I'll use crypto.randomUUID if available or Math.random shim.
+function generateId() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    return Math.random().toString(36).substring(2, 15);
+}
+class HiveCycle {
+    constructor(options = {}) {
+        this.handlers = new Map();
+        this.isRunning = false;
+        this.activeCount = 0;
+        this.options = {
+            queue: options.queue || new MemoryQueue_1.MemoryQueue(),
+            pollingInterval: options.pollingInterval || 1000,
+            maxConcurrency: options.maxConcurrency || 1,
+            logger: options.logger || console,
+        };
+        this.queue = this.options.queue;
+    }
+    /**
+     * Register a handler for a specific task type.
+     */
+    registerHandler(type, handler) {
+        this.handlers.set(type, handler);
+    }
+    /**
+     * Enqueue a new task.
+     */
+    async enqueue(type, payload, options) {
+        const task = {
+            id: generateId(),
+            type,
+            payload,
+            timestamp: Date.now(),
+            ...options,
+        };
+        await this.queue.enqueue(task);
+        return task.id;
+    }
+    /**
+     * Start the worker loop.
+     */
+    start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        this.options.logger.log("HiveCycle engine started.");
+        this.loop();
+    }
+    /**
+     * Stop the worker loop.
+     */
+    stop() {
+        this.isRunning = false;
+        this.options.logger.log("HiveCycle engine stopping...");
+    }
+    async loop() {
+        while (this.isRunning) {
+            if (this.activeCount < this.options.maxConcurrency) {
+                try {
+                    const task = await this.queue.dequeue();
+                    if (task) {
+                        this.handleTask(task);
+                        // If we have concurrency, we might want to immediately try to fetch another one
+                        // instead of waiting specifically. But to prevent tight CPU looping in async:
+                        // we continue the loop.
+                        continue;
+                    }
+                    else {
+                        // Queue empty
+                        await this.sleep(this.options.pollingInterval);
+                    }
+                }
+                catch (err) {
+                    this.options.logger.error("Error in main loop:", err);
+                    await this.sleep(this.options.pollingInterval);
+                }
+            }
+            else {
+                // Max concurrency reached
+                await this.sleep(100);
+            }
+        }
+    }
+    async handleTask(task) {
+        this.activeCount++;
+        try {
+            const handler = this.handlers.get(task.type);
+            if (!handler) {
+                throw new Error(`No handler registered for task type: ${task.type}`);
+            }
+            await handler(task);
+            await this.queue.acknowledge(task.id);
+            if (task.requeue) {
+                const nextRun = async () => {
+                    try {
+                        await this.enqueue(task.type, task.payload, {
+                            requeue: true,
+                            requeueDelay: task.requeueDelay,
+                        });
+                    }
+                    catch (e) {
+                        this.options.logger.error(`Failed to automatically requeue task ${task.type}`, e);
+                    }
+                };
+                if (task.requeueDelay && task.requeueDelay > 0) {
+                    setTimeout(nextRun, task.requeueDelay);
+                }
+                else {
+                    await nextRun();
+                }
+            }
+        }
+        catch (err) {
+            this.options.logger.error(`Task ${task.id} failed:`, err);
+            // Depending on the queue implementation, reject might be handled differently
+            await this.queue.reject(task.id, err);
+        }
+        finally {
+            this.activeCount--;
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.HiveCycle = HiveCycle;

package/dist/src/MemoryQueue.d.ts

@@ -0,0 +1,9 @@
+import { QueueAdapter, Task } from "./types";
+export declare class MemoryQueue implements QueueAdapter {
+    private queue;
+    private processing;
+    enqueue(task: Task): Promise<void>;
+    dequeue(): Promise<Task | null>;
+    acknowledge(taskId: string): Promise<void>;
+    reject(taskId: string, error?: Error): Promise<void>;
+}

package/dist/src/MemoryQueue.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryQueue = void 0;
+class MemoryQueue {
+    constructor() {
+        this.queue = [];
+        this.processing = new Map();
+    }
+    async enqueue(task) {
+        this.queue.push(task);
+    }
+    async dequeue() {
+        const task = this.queue.shift();
+        if (!task)
+            return null;
+        this.processing.set(task.id, task);
+        return task;
+    }
+    async acknowledge(taskId) {
+        this.processing.delete(taskId);
+    }
+    async reject(taskId, error) {
+        const task = this.processing.get(taskId);
+        if (task) {
+            this.processing.delete(taskId);
+            // Re-queue the task for retry
+            this.queue.push(task);
+        }
+    }
+}
+exports.MemoryQueue = MemoryQueue;

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./HiveCycle";
+export * from "./MemoryQueue";

package/dist/src/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./HiveCycle"), exports);
+__exportStar(require("./MemoryQueue"), exports);

package/dist/src/types.d.ts

@@ -0,0 +1,42 @@
+export interface Task<T = any> {
+    id: string;
+    type: string;
+    payload: T;
+    retries?: number;
+    timestamp?: number;
+    requeue?: boolean;
+    requeueDelay?: number;
+}
+export interface QueueAdapter {
+    /**
+     * Add a task to the queue
+     */
+    enqueue(task: Task): Promise<void>;
+    /**
+     * Retrieve the next task from the queue.
+     * Should return null if the queue is empty.
+     */
+    dequeue(): Promise<Task | null>;
+    /**
+     * Mark a task as successfully completed.
+     */
+    acknowledge(taskId: string): Promise<void>;
+    /**
+     * Handle a task failure (e.g., re-queue or move to DLQ).
+     */
+    reject(taskId: string, error?: Error): Promise<void>;
+}
+export interface TaskHandler<T = any> {
+    (task: Task<T>): Promise<void>;
+}
+export interface HiveCycleOptions {
+    queue?: QueueAdapter;
+    pollingInterval?: number;
+    maxConcurrency?: number;
+    logger?: Logger;
+}
+export interface Logger {
+    log(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,29 @@
+{
+    "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"
+    }
+}