@qianxude/tem 0.3.0 → 0.4.2

package/README.md

@@ -6,6 +6,14 @@ Built for **single-process, IO-bound scenarios** where you need reliable task ex
 
 ---
 
+## Installation
+
+```sh
+bun add @qianxude/tem
+```
+
+---
+
 ## Features
 
 - **SQLite Persistence** — Tasks survive process restarts using `bun:sqlite` with WAL mode
@@ -43,38 +51,37 @@ Don't use tem when you need:
 ```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
-  }
+  databasePath: "./tem.db",
+  concurrency: 5,
+  pollIntervalMs: 1000,
+  rateLimit: { requests: 60, windowMs: 60000 }  // 60 req/min
 });
 
 // Create a batch
 const batch = await tem.batch.create({
-  code: "2026-02-15-llm-fix",  // Your custom tag
+  code: "2026-02-15-llm-fix",
   type: "rewrite-docs"
 });
 
-// Enqueue tasks
-await tem.task.enqueueMany([
+// Create tasks
+await tem.task.createMany([
   { 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);
+// Register handler — payload is your task data, context has metadata
+tem.worker.register("rewrite", async (payload, context) => {
+  const result = await callLLM(payload);
   return result;  // Stored in task.result
 });
 
 // Start processing
 tem.worker.start();
+
+// Stop when done
+await tem.stop();
 ```
 
 ---
@@ -99,6 +106,111 @@ failed
 
 ---
 
+## Core Concepts
+
+- **Batch** — A named group of tasks. All recovery operations (resume, retry) work at batch level.
+- **Task** — A unit of work with a `type`, opaque `payload`, and tracked `status`.
+- **Worker** — Polls for pending tasks and dispatches them to registered handlers by type.
+- **Payload** — Opaque JSON; the framework never parses it. Your handler receives it as-is.
+- **Claim model** — Tasks are acquired atomically (`UPDATE ... WHERE status='pending'`), preventing duplicate execution.
+
+### Task Ordering
+
+Tasks within a batch are claimed and executed in **FIFO order** (First-In-First-Out) based on creation time.
+When multiple tasks are pending, the task created first will be claimed first:
+
+```typescript
+// These tasks will be claimed in order: task1, then task2, then task3
+await tem.task.create({ batchId: batch.id, type: "process", payload: { id: 1 } }); // task1
+await tem.task.create({ batchId: batch.id, type: "process", payload: { id: 2 } }); // task2
+await tem.task.create({ batchId: batch.id, type: "process", payload: { id: 3 } }); // task3
+```
+
+---
+
+## Error Handling
+
+By default, any thrown error causes the task to retry up to `defaultMaxAttempts`:
+
+```typescript
+tem.worker.register("process", async (payload, context) => {
+  console.log(`Attempt ${context.attempt}`);
+  const result = await callAPI(payload);  // throws → auto-retry
+  return result;
+});
+```
+
+For permanent failures that should not be retried, throw `NonRetryableError`:
+
+```typescript
+import { TEM, NonRetryableError } from "@qianxude/tem";
+
+tem.worker.register("validate", async (payload) => {
+  if (!payload.id) {
+    throw new NonRetryableError("Missing required field: id");
+    // Task goes directly to 'failed', no retries
+  }
+  return process(payload);
+});
+```
+
+---
+
+## Batch Interruption
+
+Automatically stop a batch when error thresholds are exceeded:
+
+```typescript
+const batch = await tem.batch.create({
+  code: "llm-run-01",
+  type: "summarize",
+  interruptionCriteria: {
+    maxErrorRate: 0.3,          // Stop if >30% tasks fail
+    maxFailedTasks: 10,         // Stop if >10 tasks fail
+    maxConsecutiveFailures: 5,  // Stop if 5 failures in a row
+  }
+});
+```
+
+Check interruption details after the batch stops:
+
+```typescript
+const logs = await tem.interruption.getInterruptionLog(batchId);
+// [{ reason, message, statsAtInterruption }]
+```
+
+Manually interrupt a running batch:
+
+```typescript
+await tem.interruptBatch(batchId, "manual", "Stopping due to bad data");
+```
+
+---
+
+## Auto-Detect Constraints
+
+Probe an API endpoint to discover its concurrency and rate limits before running tasks:
+
+```typescript
+const config = await TEM.detectConstraints({
+  url: "https://api.example.com/v1/endpoint",
+  method: "POST",
+  headers: { Authorization: "Bearer " + process.env.API_KEY },
+  body: { /* minimal valid request */ },
+  timeoutMs: 30000,
+  maxConcurrencyToTest: 50,
+  rateLimitTestDurationMs: 10000,
+});
+
+const tem = new TEM({
+  databasePath: "./tasks.db",
+  concurrency: config.concurrency,
+  rateLimit: config.rateLimit,
+});
+```
+
+---
+
 ## Recovery Patterns
 
 ### Resume After Crash
@@ -133,7 +245,7 @@ TEM
 ├── Worker             # Execution loop with concurrency/rate limiting
 ├── ConcurrencyController  # Semaphore for local concurrency
 ├── RateLimiter        # Token bucket for API rate limits
-└── RetryStrategy      # Configurable retry logic
+└── BatchInterruptionService  # Auto-stop on error thresholds
 ```
 
 ### Why Claim-Based?
@@ -199,12 +311,13 @@ This ensures:
 
 ```typescript
 interface TEMConfig {
-  dbPath: string;           // SQLite file path
-  concurrency?: number;     // Default: 5
-  pollInterval?: number;    // Default: 1000ms
+  databasePath: string;       // SQLite file path
+  concurrency?: number;       // Default: 5
+  pollIntervalMs?: number;    // Default: 1000ms
+  defaultMaxAttempts?: number; // Default: 3
   rateLimit?: {
-    perMinute?: number;
-    perSecond?: number;
+    requests: number;         // Number of requests
+    windowMs: number;         // Time window in ms (e.g. 60000 for per-minute)
   };
 }
 ```
@@ -216,57 +329,71 @@ interface TEMConfig {
 const batch = await tem.batch.create({
   code: "unique-batch-code",
   type: "batch-type",
-  metadata?: { ... }
+  metadata?: { ... },
+  interruptionCriteria?: {
+    maxErrorRate?: number;
+    maxFailedTasks?: number;
+    maxConsecutiveFailures?: number;
+  }
 });
 
-// Get batch info
-const batch = await tem.batch.get(batchId);
-
-// List batches
-const batches = await tem.batch.list({ type?: "..." });
+// Get batch by ID
+const batch = await tem.batch.getById(batchId);
 
 // Get statistics
 const stats = await tem.batch.getStats(batchId);
-// { pending: 5, running: 2, completed: 10, failed: 3 }
+// { pending, running, completed, failed, total }
 
 // Resume after crash (running → pending)
 await tem.batch.resume(batchId);
 
-// Retry all failed (failed → pending, attempt=0)
+// Retry all failed (failed → pending, attempt reset)
 await tem.batch.retryFailed(batchId);
 ```
 
 ### Task Operations
 
 ```typescript
-// Enqueue single task
-await tem.task.enqueue({
+// Create single task
+await tem.task.create({
   batchId: string,
   type: string,
   payload: object,
-  maxAttempt?: number  // Default: 3
+  maxAttempts?: number
 });
 
-// Bulk enqueue (transaction)
-await tem.task.enqueueMany([
+// Bulk create (single transaction)
+await tem.task.createMany([
   { batchId, type, payload },
   ...
 ]);
+
+// Get task by ID
+const task = await tem.task.getById(taskId);
 ```
 
 ### 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
+// payload: your task data; context: { taskId, batchId, attempt }
+tem.worker.register("task-type", async (payload, context) => {
+  const result = await doWork(payload);
+  return result;  // JSON-serialized to task.result
 });
 
 // Control execution
 tem.worker.start();
-await tem.worker.stop();
+await tem.stop();  // Stops worker and closes DB
+```
+
+### NonRetryableError
+
+```typescript
+import { NonRetryableError } from "@qianxude/tem";
+
+throw new NonRetryableError("reason");
+// Task goes to 'failed' immediately, skipping remaining attempts
 ```
 
 ---
@@ -298,6 +425,37 @@ await tem.worker.stop();
 
 ---
 
+## Mock Server
+
+Tem includes a built-in mock HTTP server for testing task execution under various constraints. Use it to simulate APIs with:
+
+- **Concurrency limits** — Test how your tasks handle 503 errors
+- **Rate limiting** — Verify retry behavior against 429 responses
+- **Error simulation** — Test resilience with configurable failure rates
+
+See [src/mock-server/README.md](src/mock-server/README.md) for detailed documentation.
+
+---
+
+## CLI
+
+Tem includes a CLI for batch diagnostics and monitoring:
+
+```sh
+# Generate diagnostic report
+tem report ./tem.db my-batch
+
+# List failed tasks
+tem list ./tem.db --batch my-batch --status failed
+
+# Watch batch progress in real-time
+tem watch ./tem.db --latest
+```
+
+See [src/cli/README.md](src/cli/README.md) for full documentation.
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qianxude/tem",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "A lightweight task execution engine for IO-bound workloads with SQLite persistence, retry, and rate limiting",
   "module": "src/index.ts",
   "type": "module",
@@ -22,6 +22,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test",
+    "coverage": "bun test --coverage",
     "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",
@@ -29,6 +30,7 @@
     "test:auto-detect": "bun test tests/integration/auto-detect.test.ts",
     "lint": "oxlint",
     "lint:file": "oxlint",
+    "example:llm-detect": "bun examples/llm-detect.ts",
     "dev": "bun --watch src/index.ts",
     "cli": "bun ./src/cli/index.ts",
     "publish:pkg": "bun publish --access public",

package/src/cli/README.md

@@ -0,0 +1,218 @@
+# tem CLI
+
+Command-line interface for batch diagnostics and monitoring.
+
+## Installation
+
+The CLI is included with the tem package:
+
+```sh
+bun add @qianxude/tem
+```
+
+You can run it directly with bun:
+
+```sh
+bun run src/cli/index.ts <command> [options]
+```
+
+Or install globally:
+
+```sh
+bun link
+```
+
+## Usage
+
+```
+tem <command> [options]
+```
+
+## Commands
+
+### `report`
+
+Generate a diagnostic report for batches.
+
+```sh
+tem report <db-path> [batch-code]
+```
+
+**Arguments:**
+
+- `db-path` - Path to the SQLite database file (required)
+- `batch-code` - Specific batch code to report on (optional)
+
+**Options:**
+
+- `--latest` - Report on the most recently created batch
+- `--limit-errors N` - Show top N error patterns (default: 10)
+
+**Examples:**
+
+```sh
+# Summary report for all batches
+tem report ./tem.db
+
+# Detailed report for specific batch
+tem report ./tem.db my-batch-code
+
+# Report on latest batch
+tem report ./tem.db --latest
+
+# Show top 20 error patterns
+tem report ./tem.db my-batch-code --limit-errors 20
+```
+
+**Report includes:**
+
+- Batch overview (code, type, status, timestamps, duration)
+- Status breakdown with counts and percentages
+- Timing analysis (avg/min/max task times, throughput)
+- Error patterns for failed tasks
+- Retry analysis statistics
+- Detection of stuck tasks (running > 5 minutes)
+
+---
+
+### `list`
+
+List tasks with filtering options.
+
+```sh
+tem list <db-path>
+```
+
+**Arguments:**
+
+- `db-path` - Path to the SQLite database file (required)
+
+**Options:**
+
+- `--batch <code>` - Filter by batch code
+- `--status <status>` - Filter by status: `pending`, `running`, `completed`, or `failed`
+- `--type <type>` - Filter by task type
+- `--limit <n>` - Limit results (default: 100)
+
+**Examples:**
+
+```sh
+# List all tasks (up to 100)
+tem list ./tem.db
+
+# List failed tasks from a specific batch
+tem list ./tem.db --batch my-batch --status failed
+
+# List pending tasks of a specific type
+tem list ./tem.db --status pending --type rewrite --limit 20
+```
+
+**Output columns:**
+
+- ID - Task UUID
+- Batch - Batch code
+- Type - Task type
+- Status - Current status
+- Attempts - Current attempt / max attempts
+- Created - Timestamp
+- Completed - Completion timestamp
+- Error - Truncated error message (if failed)
+
+---
+
+### `watch`
+
+Monitor a running batch in real-time.
+
+```sh
+tem watch <db-path> [batch-code]
+```
+
+**Arguments:**
+
+- `db-path` - Path to the SQLite database file (required)
+- `batch-code` - Specific batch code to watch (optional if using `--latest`)
+
+**Options:**
+
+- `--latest` - Watch the most recently created batch
+- `--interval N` - Refresh interval in seconds (default: 5)
+- `--timeout N` - Maximum watch time in seconds (default: 3600)
+- `--no-clear` - Don't clear screen between updates
+
+**Examples:**
+
+```sh
+# Watch the latest batch
+tem watch ./tem.db --latest
+
+# Watch specific batch with 10-second refresh
+tem watch ./tem.db my-batch-code --interval 10
+
+# Watch for up to 5 minutes
+tem watch ./tem.db --latest --timeout 300
+
+# Watch without clearing screen (for logging)
+tem watch ./tem.db --latest --no-clear
+```
+
+**Watch display includes:**
+
+- Visual progress bar
+- Batch status with color coding:
+  - 🟢 Green - Completed
+  - 🔴 Red - Failed
+  - 🟡 Yellow - Running
+  - 🔵 Cyan - Pending
+- Real-time statistics (pending, running, completed, failed, total)
+- Throughput and ETA
+- Recent errors (last 3)
+- Stuck task warnings (> 5 minutes running)
+
+Press `Ctrl+C` to stop watching. A final report is displayed when the batch completes.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Runtime error (database issues, batch not found, timeout) |
+| 2 | Usage error (missing arguments, invalid commands/options) |
+| 130 | Interrupted by user (SIGINT) |
+
+---
+
+## Global Options
+
+- `--help, -h` - Show help message for any command
+
+## Common Workflows
+
+### Debug a failing batch
+
+```sh
+# Watch the batch in one terminal
+tem watch ./tem.db my-batch --latest
+
+# In another terminal, list failed tasks
+tem list ./tem.db --batch my-batch --status failed
+
+# Generate detailed report
+tem report ./tem.db my-batch --limit-errors 20
+```
+
+### Monitor a long-running job
+
+```sh
+# Watch with longer interval to reduce database queries
+tem watch ./tem.db my-batch --interval 30 --timeout 7200
+```
+
+### Quick status check
+
+```sh
+# Summary of all batches
+tem report ./tem.db
+```

package/src/core/tem.ts

@@ -1,5 +1,5 @@
 import { Database, type DatabaseOptions } from '../database/index.js';
-import { BatchService, TaskService } from '../services/index.js';
+import { BatchService, TaskService, BatchInterruptionService } from '../services/index.js';
 import { Worker, type WorkerConfig } from './worker.js';
 import {
   detectConstraints,
@@ -27,12 +27,16 @@ export interface TEMConfig {
 
   // Polling
   pollIntervalMs: number;
+
+  // Optional: Specific batch ID to process (if set, only processes this batch)
+  batchId?: string;
 }
 
 export class TEM {
   readonly batch: BatchService;
   readonly task: TaskService;
   readonly worker: Worker;
+  readonly interruption: BatchInterruptionService;
 
   private database: Database;
 
@@ -70,6 +74,7 @@ export class TEM {
   }
 
   constructor(config: TEMConfig) {
+
     // Initialize database
     const dbOptions: DatabaseOptions = {
       path: config.databasePath,
@@ -79,12 +84,15 @@ export class TEM {
     // Initialize services
     this.batch = new BatchService(this.database);
     this.task = new TaskService(this.database);
+    this.interruption = new BatchInterruptionService(this.database, this.batch);
 
     // Initialize worker with config
     const workerConfig: WorkerConfig = {
       concurrency: config.concurrency,
       pollIntervalMs: config.pollIntervalMs,
       rateLimit: config.rateLimit,
+      batchId: config.batchId,
+      interruptionService: this.interruption,
     };
     this.worker = new Worker(this.task, workerConfig);
   }
@@ -97,4 +105,24 @@ export class TEM {
     await this.worker.stop();
     this.database.close();
   }
+
+  /**
+   * Manually interrupt a batch with a specified reason.
+   * This will stop the worker if processing this batch and prevent further tasks from being claimed.
+   *
+   * @param batchId - The ID of the batch to interrupt
+   * @param reason - The reason for interruption (default: 'manual')
+   * @param message - Optional custom message explaining the interruption
+   */
+  async interruptBatch(
+    batchId: string,
+    reason?: import('../interfaces/index.js').BatchInterruptionReason,
+    message?: string
+  ): Promise<void> {
+    await this.interruption.interrupt(
+      batchId,
+      reason ?? 'manual',
+      message ?? 'Batch manually interrupted'
+    );
+  }
 }