@qianxude/tem 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qianxude
+
+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,303 @@
+# tem
+
+A lightweight, embeddable task execution engine for IO-bound workloads (LLM calls, API requests) with SQLite persistence, automatic retry, and rate limiting.
+
+Built for **single-process, IO-bound scenarios** where you need reliable task execution without the complexity of distributed systems.
+
+---
+
+## Features
+
+- **SQLite Persistence** — Tasks survive process restarts using `bun:sqlite` with WAL mode
+- **Claim-based Execution** — Atomic task claiming prevents duplicate execution, safe for concurrent async operations
+- **Batch Management** — Group tasks into batches with custom `code` tags for easy identification and recovery
+- **Automatic Retry** — Configurable max attempts with automatic retry for failed tasks
+- **Resume & Recover** — Resume interrupted batches (crash recovery) or retry all failed tasks after fixing issues
+- **Built-in Concurrency Control** — Native semaphore-based concurrency, no need for p-limit/p-queue
+- **Rate Limiting** — Token bucket rate limiter for per-minute/per-second API limits (essential for LLM providers)
+- **Zero External Dependencies** — No Redis, no message queues, no complex infrastructure
+
+---
+
+## When to Use tem
+
+Use tem when you:
+
+- Run IO-bound tasks (LLM calls, API requests) from a single process
+- Need persistence across restarts without external databases
+- Want built-in retry and rate limiting without complex setup
+- Process tasks in batches and need checkpoint/resume capabilities
+- Don't need multi-process clusters or DAG dependencies (yet)
+
+Don't use tem when you need:
+
+- Multi-process worker clusters (CPU-bound tasks)
+- Complex task dependencies (DAG)
+- Sub-millisecond latency requirements
+- Distributed execution across machines
+
+---
+
+## Quick Start
+
+```typescript
+import { TEM } from "@qianxude/tem";
+
+// Initialize
+const tem = new TEM({
+  dbPath: "./tem.db",
+  concurrency: 5,           // Max 5 concurrent tasks
+  pollInterval: 1000,       // Check for new tasks every 1s
+  rateLimit: {
+    perMinute: 60,          // Respect LLM provider limits
+    perSecond: 5
+  }
+});
+
+// Create a batch
+const batch = await tem.batch.create({
+  code: "2026-02-15-llm-fix",  // Your custom tag
+  type: "rewrite-docs"
+});
+
+// Enqueue tasks
+await tem.task.enqueueMany([
+  { batchId: batch.id, type: "rewrite", payload: { docId: 1 } },
+  { batchId: batch.id, type: "rewrite", payload: { docId: 2 } },
+  { batchId: batch.id, type: "rewrite", payload: { docId: 3 } }
+]);
+
+// Register handler
+tem.worker.register("rewrite", async (task) => {
+  const result = await callLLM(task.payload);
+  return result;  // Stored in task.result
+});
+
+// Start processing
+tem.worker.start();
+```
+
+---
+
+## Task Lifecycle
+
+```
+pending
+   ↓ claim (atomic)
+running
+   ↓ success
+completed
+
+running
+   ↓ error + attempt < max_attempt
+pending (auto-retry)
+
+running
+   ↓ error + attempt >= max_attempt
+failed
+```
+
+---
+
+## Recovery Patterns
+
+### Resume After Crash
+
+If the process crashes while tasks are `running`, resume them on restart:
+
+```typescript
+// Reset all 'running' tasks back to 'pending'
+await tem.batch.resume(batchId);
+tem.worker.start();  // Continue processing
+```
+
+### Retry Failed Tasks
+
+After fixing the root cause (e.g., API key issue), retry all failed tasks:
+
+```typescript
+// Reset failed tasks to pending, attempt counter reset to 0
+await tem.batch.retryFailed(batchId);
+tem.worker.start();
+```
+
+---
+
+## Architecture
+
+```
+TEM
+├── DatabaseLayer      # bun:sqlite with WAL mode
+├── BatchService       # Batch CRUD + recovery
+├── TaskService        # Task enqueue + claim + state updates
+├── Worker             # Execution loop with concurrency/rate limiting
+├── ConcurrencyController  # Semaphore for local concurrency
+├── RateLimiter        # Token bucket for API rate limits
+└── RetryStrategy      # Configurable retry logic
+```
+
+### Why Claim-Based?
+
+Instead of:
+```typescript
+// WRONG: Race conditions in concurrent scenarios
+const task = await db.query("SELECT * FROM task WHERE status='pending'");
+await db.run("UPDATE task SET status='running' WHERE id=?", task.id);
+```
+
+tem uses atomic claim:
+```typescript
+// CORRECT: Atomic state transition with optimistic locking
+UPDATE task
+SET status='running', claimed_at=?, version=version+1
+WHERE id=? AND status='pending' AND version=?
+```
+
+This ensures:
+- No duplicate execution even with concurrent async operations
+- Safe for future multi-worker extensions
+- Clear ownership of running tasks
+
+---
+
+## Database Schema
+
+### batch
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | TEXT PK | UUID |
+| code | TEXT | User-provided batch tag (e.g., "2026-02-15-run") |
+| type | TEXT | Batch type for categorization |
+| created_at | INTEGER | Timestamp |
+| completed_at | INTEGER | Timestamp when all tasks done |
+| metadata | TEXT | JSON metadata |
+
+### task
+
+| Column | Type | Description |
+|--------|------|-------------|
+| id | TEXT PK | UUID |
+| batch_id | TEXT FK | Parent batch |
+| type | TEXT | Task type for handler routing |
+| status | TEXT | pending/running/completed/failed |
+| payload | TEXT | JSON input data (opaque to framework) |
+| result | TEXT | JSON output from handler |
+| error | TEXT | Error message on failure |
+| attempt | INTEGER | Current attempt count |
+| max_attempt | INTEGER | Max retry attempts |
+| claimed_at | INTEGER | When task was claimed |
+| completed_at | INTEGER | When task finished |
+| version | INTEGER | Optimistic lock version |
+| created_at | INTEGER | Timestamp |
+
+---
+
+## API Reference
+
+### TEM Configuration
+
+```typescript
+interface TEMConfig {
+  dbPath: string;           // SQLite file path
+  concurrency?: number;     // Default: 5
+  pollInterval?: number;    // Default: 1000ms
+  rateLimit?: {
+    perMinute?: number;
+    perSecond?: number;
+  };
+}
+```
+
+### Batch Operations
+
+```typescript
+// Create batch
+const batch = await tem.batch.create({
+  code: "unique-batch-code",
+  type: "batch-type",
+  metadata?: { ... }
+});
+
+// Get batch info
+const batch = await tem.batch.get(batchId);
+
+// List batches
+const batches = await tem.batch.list({ type?: "..." });
+
+// Get statistics
+const stats = await tem.batch.getStats(batchId);
+// { pending: 5, running: 2, completed: 10, failed: 3 }
+
+// Resume after crash (running → pending)
+await tem.batch.resume(batchId);
+
+// Retry all failed (failed → pending, attempt=0)
+await tem.batch.retryFailed(batchId);
+```
+
+### Task Operations
+
+```typescript
+// Enqueue single task
+await tem.task.enqueue({
+  batchId: string,
+  type: string,
+  payload: object,
+  maxAttempt?: number  // Default: 3
+});
+
+// Bulk enqueue (transaction)
+await tem.task.enqueueMany([
+  { batchId, type, payload },
+  ...
+]);
+```
+
+### Worker
+
+```typescript
+// Register handler
+tem.worker.register("task-type", async (task) => {
+  // task.id, task.batchId, task.payload, task.attempt
+  const result = await doWork(task.payload);
+  return result;  // Will be JSON-serialized to task.result
+});
+
+// Control execution
+tem.worker.start();
+await tem.worker.stop();
+```
+
+---
+
+## Design Principles
+
+1. **Single Process First** — No multi-process complexity until you actually need it
+2. **Database as Source of Truth** — SQLite with WAL mode, atomic updates only
+3. **Claim Model** — Never assume you own a task until you atomically claim it
+4. **Opaque Payload** — Framework doesn't parse payload; handlers decide business logic
+5. **Batch as Unit** — All operations (resume, retry) work at batch level for convenience
+
+---
+
+## Roadmap
+
+- [x] Core execution engine
+- [x] SQLite persistence
+- [x] Claim-based task acquisition
+- [x] Concurrency control
+- [x] Rate limiting
+- [x] Retry mechanism
+- [x] Batch resume/retry
+- [ ] Priority queue
+- [ ] Delayed/scheduled tasks
+- [ ] Task timeout handling
+- [ ] Metrics and observability
+- [ ] Multi-process worker cluster (future)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@qianxude/tem",
+  "version": "0.2.0",
+  "description": "A lightweight task execution engine for IO-bound workloads with SQLite persistence, retry, and rate limiting",
+  "module": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:integration": "bun test tests/integration/*.test.ts",
+    "test:mock-server": "bun test tests/integration/mock-server.test.ts",
+    "test:simple-tasks": "bun test tests/integration/tem-with-mock-server.test.ts",
+    "test:complex-tasks": "bun test tests/integration/llm-provider-simulation.test.ts",
+    "test:auto-detect": "bun test tests/integration/auto-detect.test.ts",
+    "lint": "oxlint",
+    "lint:file": "oxlint",
+    "dev": "bun --watch src/index.ts",
+    "publish:pkg": "bun publish --access public",
+    "version:patch": "./scripts/version.sh patch",
+    "version:minor": "./scripts/version.sh minor",
+    "version:major": "./scripts/version.sh major"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxlint": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,4 @@
+export { Worker, NonRetryableError } from './worker.js';
+export type { WorkerConfig } from './worker.js';
+export { TEM } from './tem.js';
+export type { TEMConfig, DetectOptions, DetectedConfig } from './tem.js';

package/src/core/tem.ts

@@ -0,0 +1,100 @@
+import { Database, type DatabaseOptions } from '../database/index.js';
+import { BatchService, TaskService } from '../services/index.js';
+import { Worker, type WorkerConfig } from './worker.js';
+import {
+  detectConstraints,
+  type DetectOptions,
+  type DetectedConfig,
+} from '../utils/auto-detect.js';
+
+export type { DetectOptions, DetectedConfig };
+
+export interface TEMConfig {
+  // Database
+  databasePath: string;
+
+  // Concurrency
+  concurrency: number;
+
+  // Rate limiting
+  rateLimit?: {
+    requests: number;
+    windowMs: number;
+  };
+
+  // Retry
+  defaultMaxAttempts: number;
+
+  // Polling
+  pollIntervalMs: number;
+}
+
+export class TEM {
+  readonly batch: BatchService;
+  readonly task: TaskService;
+  readonly worker: Worker;
+
+  private database: Database;
+
+  /**
+   * Auto-detect API constraints including maximum concurrency and rate limits.
+   * Uses binary search for concurrency detection and burst testing for rate limits.
+   *
+   * @example
+   * ```typescript
+   * const config = await TEM.detectConstraints({
+   *   url: 'https://api.openai.com/v1/chat/completions',
+   *   method: 'POST',
+   *   headers: {
+   *     'Authorization': 'Bearer ' + process.env.OPENAI_API_KEY,
+   *     'Content-Type': 'application/json'
+   *   },
+   *   body: {
+   *     model: 'gpt-4o-mini',
+   *     messages: [{ role: 'user', content: 'Hi' }],
+   *     max_tokens: 10
+   *   }
+   * });
+   *
+   * const tem = new TEM({
+   *   databasePath: './tasks.db',
+   *   concurrency: config.concurrency,
+   *   rateLimit: config.rateLimit,
+   *   defaultMaxAttempts: 3,
+   *   pollIntervalMs: 100
+   * });
+   * ```
+   */
+  static async detectConstraints(options: DetectOptions): Promise<DetectedConfig> {
+    return detectConstraints(options);
+  }
+
+  constructor(config: TEMConfig) {
+    // Initialize database
+    const dbOptions: DatabaseOptions = {
+      path: config.databasePath,
+    };
+    this.database = new Database(dbOptions);
+
+    // Initialize services
+    this.batch = new BatchService(this.database);
+    this.task = new TaskService(this.database);
+
+    // Initialize worker with config
+    const workerConfig: WorkerConfig = {
+      concurrency: config.concurrency,
+      pollIntervalMs: config.pollIntervalMs,
+      rateLimit: config.rateLimit,
+    };
+    this.worker = new Worker(this.task, workerConfig);
+  }
+
+  /**
+   * Stop the TEM engine.
+   * Stops the worker and closes the database connection.
+   */
+  async stop(): Promise<void> {
+    await this.worker.stop();
+    this.database.close();
+  }
+}

package/src/core/worker.ts

@@ -0,0 +1,168 @@
+import * as i from '../interfaces/index.js';
+import { TaskService } from '../services/task.js';
+import { ConcurrencyController, RateLimiter, type RateLimitConfig } from '../utils/index.js';
+
+/**
+ * Error class to mark errors as non-retryable.
+ * When thrown from a task handler, the task will fail immediately
+ * without retry attempts.
+ */
+export class NonRetryableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NonRetryableError';
+  }
+}
+
+export interface WorkerConfig {
+  concurrency: number;
+  pollIntervalMs: number;
+  rateLimit?: RateLimitConfig;
+}
+
+export class Worker {
+  private handlers = new Map<string, i.TaskHandler>();
+  private concurrency: ConcurrencyController;
+  private rateLimiter?: RateLimiter;
+  private running = false;
+  private pollIntervalMs: number;
+  private abortController: AbortController;
+  private inFlightTasks: Set<Promise<void>> = new Set();
+
+  constructor(
+    private taskService: TaskService,
+    config: WorkerConfig
+  ) {
+    this.concurrency = new ConcurrencyController(config.concurrency);
+    this.pollIntervalMs = config.pollIntervalMs;
+    this.abortController = new AbortController();
+
+    if (config.rateLimit) {
+      this.rateLimiter = new RateLimiter(config.rateLimit);
+    }
+  }
+
+  /**
+   * Register a handler for a specific task type.
+   */
+  register<TInput = unknown, TOutput = unknown>(
+    type: string,
+    handler: i.TaskHandler<TInput, TOutput>
+  ): void {
+    this.handlers.set(type, handler as i.TaskHandler);
+  }
+
+  /**
+   * Start the worker. Begins polling for and executing tasks.
+   */
+  start(): void {
+    if (this.running) return;
+
+    this.running = true;
+    this.abortController = new AbortController();
+    this.runLoop();
+  }
+
+  /**
+   * Stop the worker. Waits for in-flight tasks to complete.
+   */
+  async stop(): Promise<void> {
+    if (!this.running) return;
+
+    this.running = false;
+    this.abortController.abort();
+
+    // Wait for all in-flight tasks to complete
+    if (this.inFlightTasks.size > 0) {
+      await Promise.all(this.inFlightTasks);
+    }
+  }
+
+  /**
+   * Main execution loop.
+   */
+  private async runLoop(): Promise<void> {
+    while (this.running) {
+      // Acquire a slot first (may wait if at concurrency limit)
+      await this.concurrency.acquire();
+
+      try {
+        // Check if we're still running after acquiring
+        if (!this.running) {
+          this.concurrency.release();
+          break;
+        }
+
+        // Claim a task while holding the concurrency slot
+        const task = await this.taskService.claim();
+
+        if (!task) {
+          // No task available, release the slot and sleep
+          this.concurrency.release();
+          if (this.running) {
+            await Bun.sleep(this.pollIntervalMs);
+          }
+          continue;
+        }
+
+        // Execute task without awaiting to allow parallel execution
+        const taskPromise = this.execute(task);
+        this.inFlightTasks.add(taskPromise);
+        taskPromise.then(() => {
+          this.inFlightTasks.delete(taskPromise);
+        });
+      } catch {
+        // Release slot on error and continue
+        this.concurrency.release();
+      }
+    }
+  }
+
+  /**
+   * Execute a single task.
+   * Note: Assumes concurrency slot has already been acquired.
+   */
+  private async execute(task: i.Task): Promise<void> {
+    try {
+      if (this.rateLimiter) {
+        await this.rateLimiter.acquire();
+      }
+
+      const handler = this.handlers.get(task.type);
+      if (!handler) {
+        throw new NonRetryableError(`No handler registered for type: ${task.type}`);
+      }
+
+      const payload = JSON.parse(task.payload);
+      const context: i.TaskContext = {
+        taskId: task.id,
+        batchId: task.batchId,
+        attempt: task.attempt,
+        signal: this.abortController.signal,
+      };
+
+      const result = await handler(payload, context);
+      await this.taskService.complete(task.id, result);
+    } catch (error) {
+      await this.handleError(task, error);
+    } finally {
+      this.concurrency.release();
+    }
+  }
+
+  /**
+   * Handle task execution errors.
+   */
+  private async handleError(task: i.Task, error: unknown): Promise<void> {
+    const isRetryable = !(error instanceof NonRetryableError);
+    const shouldRetry = isRetryable && task.attempt < task.maxAttempt;
+
+    if (shouldRetry) {
+      // Reset to pending for automatic retry (attempt already incremented by claim)
+      await this.taskService.retry(task.id);
+    } else {
+      const message = error instanceof Error ? error.message : String(error);
+      await this.taskService.fail(task.id, message);
+    }
+  }
+}