@durable-effect/jobs 0.0.1-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 backpine
+
+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,490 @@
+# @durable-effect/jobs
+
+Durable jobs for Cloudflare Workers built on Effect. This package provides high-level abstractions for common durable patterns:
+
+- **Continuous** - Execute functions on a schedule (this guide)
+- **Debounce** - Accumulate events and flush on schedule/threshold (coming soon)
+- **WorkerPool** - Process events one at a time with retries (coming soon)
+
+## Installation
+
+```bash
+npm install @durable-effect/jobs effect
+```
+
+## Continuous Primitive
+
+The Continuous primitive executes a function on a recurring schedule. Perfect for:
+
+- Token refresh
+- Periodic data sync
+- Health checks
+- Report generation
+- Cache warming
+
+### Quick Start
+
+```ts
+import { Effect, Schema } from "effect";
+import { Continuous, createDurableJobs } from "@durable-effect/jobs";
+
+// 1. Define your primitive (name comes from the object key in step 2)
+const tokenRefresher = Continuous.make({
+  // Schema for persistent state
+  stateSchema: Schema.Struct({
+    accessToken: Schema.String,
+    refreshToken: Schema.String,
+    expiresAt: Schema.Number,
+  }),
+
+  // Execute every 30 minutes
+  schedule: Continuous.every("30 minutes"),
+
+  // The function to run
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      console.log(`Refreshing token (run #${ctx.runCount})`);
+
+      // Access current state
+      const { refreshToken } = ctx.state;
+
+      // Call your refresh API
+      const newTokens = yield* refreshTokens(refreshToken);
+
+      // Update state (persisted automatically)
+      ctx.setState({
+        accessToken: newTokens.access_token,
+        refreshToken: newTokens.refresh_token,
+        expiresAt: Date.now() + newTokens.expires_in * 1000,
+      });
+    }),
+});
+
+// 2. Create the Durable Object and Client - keys become primitive names
+const { Jobs, JobsClient } = createDurableJobs({
+  tokenRefresher,
+});
+
+// 3. Export the Durable Object class
+export { Jobs };
+
+// 4. Use in your worker
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const client = JobsClient.fromBinding(env.PRIMITIVES);
+
+    // Start a token refresher for a user (name matches the key from step 2)
+    await client.continuous("tokenRefresher").start({
+      id: "user-123",
+      input: {
+        accessToken: "",
+        refreshToken: "rt_initial_token",
+        expiresAt: 0,
+      },
+    });
+
+    return new Response("Token refresher started!");
+  },
+};
+```
+
+### wrangler.toml Configuration
+
+```toml
+[[durable_objects.bindings]]
+name = "PRIMITIVES"
+class_name = "Jobs"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["Jobs"]
+```
+
+## API Reference
+
+### `Continuous.make(config)`
+
+Creates a continuous primitive definition. The name is assigned when you register
+the primitive via `createDurableJobs()` - the object key becomes the name.
+
+```ts
+const myPrimitive = Continuous.make({
+  stateSchema: Schema.Struct({ ... }),
+  schedule: Continuous.every("1 hour"),
+  execute: (ctx) => Effect.succeed(undefined),
+});
+
+// Name "myPrimitive" comes from the key
+const { Jobs, JobsClient } = createDurableJobs({
+  myPrimitive,
+});
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config.stateSchema` | `Schema.Schema<S>` | Effect Schema for validating and serializing state |
+| `config.schedule` | `ContinuousSchedule` | When to execute (see Schedules below) |
+| `config.startImmediately` | `boolean` | Execute immediately on start (default: `true`) |
+| `config.execute` | `(ctx) => Effect<void, E, R>` | Function to execute on schedule |
+| `config.onError` | `(error, ctx) => Effect<void>` | Optional error handler |
+
+### Schedules
+
+#### `Continuous.every(interval)`
+
+Execute at a fixed interval.
+
+```ts
+Continuous.every("30 minutes")
+Continuous.every("1 hour")
+Continuous.every("24 hours")
+Continuous.every(Duration.minutes(30))
+```
+
+#### `Continuous.cron(expression)` (coming soon)
+
+Execute based on a cron expression.
+
+```ts
+// Every day at midnight
+Continuous.cron("0 0 * * *")
+
+// Every Monday at 9am
+Continuous.cron("0 9 * * 1")
+
+// Every hour
+Continuous.cron("0 * * * *")
+```
+
+### ContinuousContext
+
+The context object passed to your `execute` function:
+
+```ts
+interface ContinuousContext<S> {
+  // Current state (read-only reference)
+  readonly state: S;
+
+  // Replace the entire state
+  readonly setState: (state: S) => void;
+
+  // Update state via function
+  readonly updateState: (fn: (current: S) => S) => void;
+
+  // Unique instance identifier
+  readonly instanceId: string;
+
+  // Number of times execute has been called
+  readonly runCount: number;
+
+  // Name of this primitive
+  readonly primitiveName: string;
+}
+```
+
+### Client Methods
+
+#### `client.continuous(name).start({ id, input })`
+
+Start a continuous primitive instance.
+
+```ts
+const result = await client.continuous("tokenRefresher").start({
+  id: "user-123",           // Unique instance ID
+  input: { ... },           // Initial state (must match stateSchema)
+});
+
+// Result:
+// { _type: "continuous.start", instanceId: string, created: boolean, status: string }
+```
+
+If the instance already exists, returns `{ created: false }` with current status.
+
+#### `client.continuous(name).stop(id, options?)`
+
+Stop a running instance.
+
+```ts
+const result = await client.continuous("tokenRefresher").stop("user-123", {
+  reason: "User logged out",  // Optional reason
+});
+
+// Result:
+// { _type: "continuous.stop", stopped: boolean, reason: string }
+```
+
+#### `client.continuous(name).trigger(id)`
+
+Manually trigger immediate execution (bypasses schedule).
+
+```ts
+const result = await client.continuous("tokenRefresher").trigger("user-123");
+
+// Result:
+// { _type: "continuous.trigger", triggered: boolean }
+```
+
+#### `client.continuous(name).status(id)`
+
+Get current status of an instance.
+
+```ts
+const result = await client.continuous("tokenRefresher").status("user-123");
+
+// Result:
+// { _type: "continuous.status", status: string, runCount: number, nextRunAt?: number }
+```
+
+#### `client.continuous(name).getState(id)`
+
+Get current state of an instance.
+
+```ts
+const result = await client.continuous("tokenRefresher").getState("user-123");
+
+// Result:
+// { _type: "continuous.getState", state: S | null }
+```
+
+## Error Handling
+
+### Using `onError`
+
+Handle errors gracefully without failing the execution:
+
+```ts
+const resilientPrimitive = Continuous.make({
+  stateSchema: Schema.Struct({
+    data: Schema.String,
+    errorCount: Schema.Number,
+    lastError: Schema.NullOr(Schema.String),
+  }),
+  schedule: Continuous.every("5 minutes"),
+
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      // This might fail
+      const data = yield* fetchExternalData();
+      ctx.updateState((s) => ({
+        ...s,
+        data,
+        errorCount: 0,
+        lastError: null,
+      }));
+    }),
+
+  onError: (error, ctx) =>
+    Effect.sync(() => {
+      console.error(`Execution failed: ${error}`);
+      ctx.updateState((s) => ({
+        ...s,
+        errorCount: s.errorCount + 1,
+        lastError: String(error),
+      }));
+    }),
+});
+```
+
+### Typed Errors
+
+Define typed errors for better error handling:
+
+```ts
+class RefreshError extends Data.TaggedError("RefreshError")<{
+  readonly reason: string;
+}> {}
+
+const typedPrimitive = Continuous.make({
+  stateSchema: Schema.Struct({ token: Schema.String }),
+  schedule: Continuous.every("1 hour"),
+
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const result = yield* refreshToken(ctx.state.token);
+      if (!result.ok) {
+        return yield* Effect.fail(new RefreshError({ reason: result.error }));
+      }
+      ctx.setState({ token: result.token });
+    }),
+
+  onError: (error, ctx) =>
+    Effect.sync(() => {
+      // error is typed as RefreshError
+      console.error(`Refresh failed: ${error.reason}`);
+    }),
+});
+```
+
+## Testing
+
+Use the test runtime for unit testing:
+
+```ts
+import { describe, it, expect } from "vitest";
+import { Effect, Schema } from "effect";
+import { createTestRuntime, NoopTrackerLayer } from "@durable-effect/core";
+import { createJobsRuntimeFromLayer } from "@durable-effect/jobs";
+
+describe("tokenRefresher", () => {
+  it("refreshes token on schedule", async () => {
+    // Create test runtime with time control
+    const { layer, time, handles } = createTestRuntime("test-instance", 1000000);
+
+    // Create registry (manually add name for test registry)
+    const registry = {
+      continuous: new Map([["tokenRefresher", { ...tokenRefresher, name: "tokenRefresher" }]]),
+      debounce: new Map(),
+      workerPool: new Map(),
+    };
+
+    // Create runtime from test layer
+    const runtime = createJobsRuntimeFromLayer(layer, registry);
+
+    // Start the primitive
+    await runtime.handle({
+      type: "continuous",
+      action: "start",
+      name: "tokenRefresher",
+      id: "test-user",
+      input: { accessToken: "", refreshToken: "rt_test", expiresAt: 0 },
+    });
+
+    // Advance time past schedule
+    time.advance(30 * 60 * 1000); // 30 minutes
+
+    // Trigger alarm
+    await runtime.handleAlarm();
+
+    // Verify state was updated
+    const result = await runtime.handle({
+      type: "continuous",
+      action: "getState",
+      name: "tokenRefresher",
+      id: "test-user",
+    });
+
+    expect(result.state.accessToken).toBeDefined();
+  });
+});
+```
+
+## Examples
+
+### Daily Report Generator
+
+```ts
+const dailyReport = Continuous.make({
+  stateSchema: Schema.Struct({
+    lastReportDate: Schema.NullOr(Schema.String),
+    totalReports: Schema.Number,
+  }),
+  schedule: Continuous.every("24 hours"),
+  startImmediately: false, // Wait for first schedule
+
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const report = yield* generateReport();
+      yield* sendReport(report);
+
+      ctx.updateState((s) => ({
+        lastReportDate: new Date().toISOString(),
+        totalReports: s.totalReports + 1,
+      }));
+    }),
+});
+```
+
+### Health Check Monitor
+
+```ts
+const healthCheck = Continuous.make({
+  stateSchema: Schema.Struct({
+    status: Schema.Literal("healthy", "degraded", "down"),
+    lastCheck: Schema.Number,
+    consecutiveFailures: Schema.Number,
+  }),
+  schedule: Continuous.every("1 minute"),
+
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const isHealthy = yield* checkHealth();
+
+      ctx.updateState((s) => ({
+        status: isHealthy ? "healthy" : s.consecutiveFailures >= 3 ? "down" : "degraded",
+        lastCheck: Date.now(),
+        consecutiveFailures: isHealthy ? 0 : s.consecutiveFailures + 1,
+      }));
+
+      if (!isHealthy && ctx.state.consecutiveFailures >= 3) {
+        yield* sendAlert("Service is down!");
+      }
+    }),
+});
+```
+
+### Cache Warmer
+
+```ts
+const cacheWarmer = Continuous.make({
+  stateSchema: Schema.Struct({
+    lastWarmTime: Schema.Number,
+    itemsWarmed: Schema.Number,
+  }),
+  schedule: Continuous.every("15 minutes"),
+
+  execute: (ctx) =>
+    Effect.gen(function* () {
+      const items = yield* getPopularItems();
+
+      for (const item of items) {
+        yield* warmCache(item);
+      }
+
+      ctx.setState({
+        lastWarmTime: Date.now(),
+        itemsWarmed: items.length,
+      });
+    }),
+});
+```
+
+## Architecture
+
+The Continuous primitive is built on a thin Durable Object shell that delegates to a swappable runtime:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Worker Code                              │
+│  client.continuous("name").start({ id, input })             │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Durable Object (Thin Shell)                     │
+│                                                              │
+│  • Receives RPC calls                                        │
+│  • Delegates to JobsRuntime                           │
+│  • Handles alarms                                            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Jobs Runtime                         │
+│                                                              │
+│  • Routes requests to handlers                               │
+│  • Manages state via StorageAdapter                         │
+│  • Schedules alarms via SchedulerAdapter                    │
+│  • Executes user functions                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Each instance has its own:
+- **Storage** - Isolated key-value storage for state
+- **Alarm** - Single alarm for scheduling next execution
+- **Instance ID** - Format: `continuous:{name}:{userProvidedId}`
+
+## License
+
+MIT

package/dist/client/client.d.ts

@@ -0,0 +1,34 @@
+import type { AnyUnregisteredDefinition } from "../registry/types";
+import type { TypedJobRegistry } from "../registry/typed";
+import type { JobsClient } from "./types";
+/**
+ * Create a jobs client from a Durable Object binding.
+ *
+ * The client provides typed access to all registered jobs and
+ * handles instance ID resolution and routing.
+ *
+ * @example
+ * ```ts
+ * const client = createJobsClient(env.JOBS, registry);
+ *
+ * // Access continuous job
+ * await client.continuous("tokenRefresher").start({
+ *   id: "user-123",
+ *   input: { refreshToken: "rt_abc" },
+ * });
+ *
+ * // Access debounce job
+ * await client.debounce("webhookDebounce").add({
+ *   id: "contact-456",
+ *   event: { type: "contact.updated", data: {...} },
+ * });
+ *
+ * // Access workerPool job (auto-routes to instance)
+ * await client.workerPool("emailWorkerPool").enqueue({
+ *   id: "email-789",
+ *   event: { to: "user@example.com", template: "welcome" },
+ * });
+ * ```
+ */
+export declare function createJobsClient<T extends Record<string, AnyUnregisteredDefinition>>(binding: DurableObjectNamespace, registry: TypedJobRegistry<T>): JobsClient<TypedJobRegistry<T>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAsB,MAAM,mBAAmB,CAAC;AAE9E,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,SAAS,CAAC;AAyDjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,EAClF,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC5B,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CA2fjC"}