@azlib/scheduler 0.2.0 → 1.0.1

package/README.md

@@ -1,108 +1,89 @@
 # @azlib/scheduler
 
-Cron-style job scheduling for Node.js workloads, designed to run standalone or embedded in host runtimes (for example Express).
-
-## Install
-
-```bash
-pnpm add @azlib/scheduler @azlib/queue @azlib/cache @azlib/logger
-```
-
-## Status
-
-This package is ready for phased implementation usage with:
-
-- schedule parsing and timezone normalization
-- job registration and lifecycle controls
-- standalone runtime start/stop orchestration
-- host lifecycle binding for embedded runtimes
-- queue-backed execution dispatch through `@azlib/queue`
-- cache integration through `@azlib/cache`
-- structured logs through `@azlib/logger`
-
-## Basic Usage
+Cron-style job scheduler for Node.js, supporting timezone normalization, overlap prevention policies, missed run executions, and database persistence.
+
+## Capabilities
+
+- Schedule parsing and timezone normalization
+- Job registration and lifecycle control (start, stop)
+- Standalone runner execution or embedded hosting (e.g. Express)
+- Host lifecycle bindings for graceful setups
+- Queue-backed execution dispatch through `@azlib/queue`
+- Cache coordination using `@azlib/cache`
+- Structured database state persistence (SQL persistence)
+
+## AI Agent Quick Reference
+
+### Core Exports
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `createSchedulerService(options: SchedulerServiceOptions)` | Function | Instantiates a SchedulerService instance and a Handler Registry. |
+| `createCronExpression(): CronExpressionBuilder` | Function | Fluent helper to construct standard 5-field cron strings. |
+| `bindSchedulerToHost(service: SchedulerService, adapter: SchedulerHostAdapter)` | Function | Automatically starts/stops the scheduler based on custom server bindings. |
+| `CronWeekday` | Enum | Monday through Sunday utility enum values. |
+
+### Core Types & Signatures
+
+- `SchedulerService`:
+  - `start(): Promise<void>`
+  - `stop(): Promise<void>`
+  - `registerJob(job: SchedulerJobDefinition): Promise<void>`
+  - `unregisterJob(jobName: string): Promise<void>`
+- `SchedulerHandlerRegistry`:
+  - `register(key: string, handler: (config?: any) => Promise<void>): void`
+- `SchedulerJobDefinition`:
+  - `name: string`
+  - `handlerKey: string`
+  - `schedule: SchedulerScheduleConfig`
+  - `config?: any` (JSON-serializable config injected into handler)
+- `SchedulerScheduleConfig`:
+  - `scheduleType: "cron"`
+  - `expression: string`
+  - `timezone?: string` (e.g. `"UTC"`, `"Asia/Saigon"`)
+  - `overlapPolicy: "allow" | "skip" | "enqueue"`
+  - `missedRunPolicy: "run-immediately" | "skip"`
+
+### Basic Usage
 
 ```ts
 import { createQueueService } from "@azlib/queue";
-import { createProviderFromEnv } from "@azlib/queue/providers";
-import {
-	createCronExpression,
-	createSchedulerService,
-} from "@azlib/scheduler";
-
-const queue = createQueueService({
-	provider: createProviderFromEnv({ QUEUE_PROVIDER: "memory" }),
-	defaultQueue: "scheduled-jobs",
-	retryPolicy: {
-		maxAttempts: 5,
-		backoffType: "exponential-jitter",
-		baseDelayMs: 1000,
-		maxDelayMs: 60000,
-	},
-});
+import { createSchedulerService, createCronExpression } from "@azlib/scheduler";
+
+const queue = createQueueService({ /* ... */ });
 
 const { service, handlers } = createSchedulerService({
-	mode: "standalone",
-	queueService: queue,
+  mode: "standalone",
+  queueService: queue,
 });
 
-handlers.register("daily-report", async (config: { template: string }) => {
-	await sendReport(config.template);
+// 1. Register executor logic
+handlers.register("purge-logs", async (config: { thresholdDays: number }) => {
+  await db.logs.deleteOlderThan(config.thresholdDays);
 });
 
+// 2. Register scheduled trigger
 await service.registerJob({
-	name: "report-job",
-	handlerKey: "daily-report",
-	schedule: {
-		scheduleType: "cron",
-		expression: createCronExpression().dailyAt(8, 0).build(),
-		timezone: "UTC",
-		overlapPolicy: "skip",
-		missedRunPolicy: "run-immediately",
-	},
-	config: { template: "daily-summary" },
+  name: "nightly-purge",
+  handlerKey: "purge-logs",
+  schedule: {
+    scheduleType: "cron",
+    expression: createCronExpression().dailyAt(2, 30).build(), // 02:30 AM
+    timezone: "UTC",
+    overlapPolicy: "skip",
+    missedRunPolicy: "run-immediately",
+  },
+  config: { thresholdDays: 30 },
 });
 
+// 3. Boot scheduler
 await service.start();
 ```
 
-## Cron Builder
-
-Use the fluent builder to avoid writing raw cron syntax directly:
-
-```ts
-import { CronWeekday, createCronExpression } from "@azlib/scheduler";
-
-const everyFiveMinutes = createCronExpression().everyNMinutes(5).build();
-const everyTwoHours = createCronExpression().atMinute(0).everyNHours(2).build();
-const weekdayMorning = createCronExpression()
-	.weeklyOn(CronWeekday.Monday, 9, 0)
-	.build();
-```
-
-## Embedded Runtime Binding
-
-```ts
-import { bindSchedulerToHost } from "@azlib/scheduler";
-
-bindSchedulerToHost(service, {
-	onStart(listener) {
-		app.listen(3000, () => {
-			void listener();
-		});
-	},
-	onStop(listener) {
-		process.on("SIGINT", () => {
-			void listener();
-		});
-	},
-});
-```
-
-## Validation
-
-```bash
-pnpm --filter @azlib/scheduler lint
-pnpm --filter @azlib/scheduler test
-pnpm --filter @azlib/scheduler build
-```
+### Behavioral Gotchas
+- **Timezone Safety**: Always specify a `timezone` in job configs to prevent local developer clocks from altering trigger cycles.
+- **Overlap Policies**:
+  - `skip`: If a previous job execution is still running, the new scheduled trigger is skipped.
+  - `enqueue`: Queues the new run to execute immediately after the active run completes.
+  - `allow`: Runs execution concurrent to existing instances (warning: potential race conditions).
+- **Execution Engine**: Jobs are not run inside the scheduler thread directly. Instead, they are dispatched as tasks to the configured `@azlib/queue` provider to preserve single-thread event loop safety.