effect-cf 0.23.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # effect-cf
 
+## 0.25.0
+
+### Minor Changes
+
+- [#85](https://github.com/danieljvdm/effect-cf/pull/85) [`2c46f9d`](https://github.com/danieljvdm/effect-cf/commit/2c46f9d64774edb7994e3879313077e2a203777a) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Remove compatibility APIs. Use `WorkerConfig.providerLayer`,
+  `AnalyticsEngine.writeDataPoint` or `writeDataPoints`, and
+  `DurableObjectAlarm.processDue`; Email sends now require structured builder messages.
+
+### Patch Changes
+
+- [#87](https://github.com/danieljvdm/effect-cf/pull/87) [`6d6fdfa`](https://github.com/danieljvdm/effect-cf/commit/6d6fdfaaf4812bb46c49b49aad3fd2ca50af76f6) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Allow compatible Effect releases in package development dependency ranges.
+
+## 0.24.0
+
+### Minor Changes
+
+- [#82](https://github.com/danieljvdm/effect-cf/pull/82) [`877f289`](https://github.com/danieljvdm/effect-cf/commit/877f289a19ff15bdca1e7f9320aee3be1cffb3de) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add an `effect-cf/vitest` entrypoint with Effect-native Workers environment, fetch, queue, execution-context, and scoped Workflow testing helpers for Cloudflare's Vitest Workers pool.
+
+- [#84](https://github.com/danieljvdm/effect-cf/pull/84) [`9bbd554`](https://github.com/danieljvdm/effect-cf/commit/9bbd5543ca463447d0eb6a08d6441c7b72086b40) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add Effect-native scheduled and Pages runners, Durable Object test controls, D1 migrations, binding reset helpers, Workflow introspectors, and a Secrets Store admin client to `effect-cf/vitest`. The optional `@cloudflare/vitest-pool-workers` peer dependency now requires `^0.21.3`.
+
 ## 0.23.1
 
 ### Patch Changes

package/README.md

@@ -4,18 +4,18 @@ Effect-native Cloudflare primitives for Workers, Durable Objects, Containers, bi
 
 ## Install
 
-`effect-cf` currently targets Effect 4 beta.
+`effect-cf` targets Effect `^4.0.0-beta.105`.
 
 ```bash
-bun add effect-cf "effect@^4.0.0-beta.65"
+bun add effect-cf "effect@^4.0.0-beta.105"
 ```
 
 ```bash
-pnpm add effect-cf "effect@^4.0.0-beta.65"
+pnpm add effect-cf "effect@^4.0.0-beta.105"
 ```
 
 ```bash
-npm install effect-cf "effect@^4.0.0-beta.65"
+npm install effect-cf "effect@^4.0.0-beta.105"
 ```
 
 ## Goal
@@ -43,6 +43,157 @@ Runtime creation belongs at Cloudflare entrypoints, not inside binding helpers.
 - `Workflow` - typed Workflow entrypoints, steps, starter clients, and instance types
 - `Rpc` - Cloudflare RPC type helpers and scoped disposal utilities
 - `WorkerConfig` - Effect `Config` helpers backed by Cloudflare `env`
+- `effect-cf/vitest` - Effect-native runners and scoped test helpers for Cloudflare's Vitest Workers pool
+
+## Vitest Workers Pool
+
+Install and configure a `^0.21.3` release of
+[`@cloudflare/vitest-pool-workers`](https://github.com/cloudflare/workers-sdk/tree/main/packages/vitest-pool-workers#readme),
+then import the test-only helpers from `effect-cf/vitest`. The `fetch` runner
+constructs the Worker with the current test environment and waits for all
+`waitUntil` work before completing the Effect.
+
+```ts
+import { assert, it } from "@effect/vitest";
+import { Config, Effect } from "effect";
+import * as PoolWorkers from "effect-cf/vitest";
+
+import WorkerEntrypoint from "../src/index";
+
+it.effect("serves a request", () =>
+  Effect.gen(function* () {
+    const response = yield* PoolWorkers.fetch(
+      WorkerEntrypoint,
+      new Request("https://worker.test/health"),
+    );
+
+    assert.strictEqual(response.status, 200);
+  }),
+);
+
+it.effect("reads Wrangler vars", () =>
+  Config.string("APP_NAME").pipe(
+    Effect.tap((appName) => assert.strictEqual(appName, "test-app")),
+    Effect.provide(PoolWorkers.layer),
+  ),
+);
+```
+
+Queue consumers can be invoked with typed message bodies while retaining the
+pool's acknowledgement and retry result:
+
+```ts
+it.effect("acknowledges a job", () =>
+  Effect.gen(function* () {
+    const { result } = yield* PoolWorkers.queue(MyQueueConsumer, "jobs", [
+      {
+        id: "job-1",
+        timestamp: new Date(),
+        attempts: 1,
+        body: { accountId: "account-1" },
+      },
+    ]);
+
+    assert.deepStrictEqual(result.explicitAcks, ["job-1"]);
+  }),
+);
+```
+
+Scheduled handlers and Pages Functions use the same lifecycle behavior: their
+Effects complete only after the event's `waitUntil` work has settled. Pages
+tests must configure the `ASSETS` binding required by Pool Workers.
+
+```ts
+it.effect("runs the cron handler", () =>
+  PoolWorkers.scheduled(worker.scheduled, {
+    cron: "30 * * * *",
+    scheduledTime: new Date("2030-01-01T00:00:00Z"),
+  }),
+);
+
+it.effect("runs a Pages Function", () =>
+  Effect.gen(function* () {
+    const response = yield* PoolWorkers.pages(onRequest, {
+      request: new Request("https://pages.test/users/dan"),
+      params: { user: "dan" },
+      data: { authenticated: true },
+    });
+
+    assert.strictEqual(response.status, 200);
+  }),
+);
+```
+
+`runInDurableObject` carries the test's Effect context into the Durable Object
+I/O context and provides the same wrapped `DurableObjectState` service used by
+production handlers. Typed failures remain in the Effect error channel.
+
+```ts
+it.effect("seeds a Durable Object", () =>
+  Effect.gen(function* () {
+    const stub = env.COUNTERS.getByName("home");
+
+    yield* PoolWorkers.runInDurableObject(stub, () =>
+      Effect.gen(function* () {
+        const state = yield* DurableObjectState;
+        yield* state.storage.put("count", 41);
+      }),
+    );
+
+    assert.strictEqual(yield* PoolWorkers.runDurableObjectAlarm(stub), true);
+
+    // Recreate in-memory state while preserving Durable Object storage.
+    yield* PoolWorkers.evictDurableObject(stub);
+  }),
+);
+```
+
+The subpath also exposes Effects for `listDurableObjectIds`, `reset`,
+`abortAllDurableObjects`, `evictAllDurableObjects`, and `applyD1Migrations`.
+`adminSecretsStore` returns an Effect-native admin client whose `create`,
+`update`, `duplicate`, `delete`, `list`, and `get` operations are Effects.
+
+`withExecutionContext` supports lower-level tests that need a native
+`ExecutionContext`. Workflow introspectors and all of their modifiers and query
+operations are Effect-native. They are disposed with the current Effect scope,
+and modifier callbacks carry the caller's Effect context and typed failures.
+
+```ts
+it.effect("controls a Workflow instance", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const instanceId = crypto.randomUUID();
+      const instance = yield* PoolWorkers.introspectWorkflowInstance(
+        env.REPORT_WORKFLOW,
+        instanceId,
+      );
+
+      yield* instance.modify((modifier) =>
+        Effect.gen(function* () {
+          yield* modifier.disableSleeps();
+          yield* modifier.mockStepResult({ name: "render-report" }, "reports/test.json");
+        }),
+      );
+      yield* Effect.promise(() =>
+        env.REPORT_WORKFLOW.create({
+          id: instanceId,
+          params: { reportId: "test", requestedBy: "dan@example.com" },
+        }),
+      );
+
+      yield* instance.waitForStatus("complete");
+      assert.deepStrictEqual(yield* instance.getOutput, {
+        objectKey: "reports/test.json",
+        notified: true,
+      });
+    }),
+  ),
+);
+```
+
+Use `introspectWorkflow` when the instance ID is not known before creation. Its
+`modifyAll` and `get` operations are Effects, and each instance returned by
+`get` uses the same Effect-native interface shown above.
 
 ## Worker Example
 
@@ -340,7 +491,7 @@ Onboard the sending domain under **Compute > Email Service > Email Sending**, th
 }
 ```
 
-Messages that violate a documented limit fail with `EmailValidationError` carrying every violation, without calling the binding. Use `layer({ binding, send: { validate: false } })` to skip validation and let Cloudflare reject the message instead. Raw RFC 5322 `EmailMessage` values are always passed through untouched, so the legacy `cloudflare:email` API keeps working.
+Messages that violate a documented limit fail with `EmailValidationError` carrying every violation, without calling the binding. Use `layer({ binding, send: { validate: false } })` to skip validation and let Cloudflare reject the message instead.
 
 Cloudflare's total message size limit is exposed as `Email.sendLimits.maxMessageBytes` but is not enforced, because the encoded MIME size is only known once Cloudflare composes the message. Oversized messages fail at the binding with `E_CONTENT_TOO_LARGE`.
 
@@ -360,7 +511,6 @@ export const RequestAnalyticsLayer = RequestAnalytics.layer({
   binding: "REQUEST_ANALYTICS",
   write: {
     onInvalid: "error",
-    batchSize: 100,
   },
 });
 
@@ -375,7 +525,7 @@ export const recordPageView = (request: Request) =>
       doubles: [1],
     });
 
-    yield* analytics.writeBatch(
+    yield* analytics.writeDataPoints(
       [
         {
           indexes: [url.hostname],

package/dist/{Hyperdrive-COyg7R26.d.mts → Binding-DI7u3fEY.d.mts}

@@ -29,7 +29,7 @@ type ScalarConfigKey = Extract<{ readonly [Key in keyof Cloudflare.Env]-?: NonNu
  * const program = Effect.gen(function* () {
  *   const config = yield* AppConfig;
  *   // ...
- * }).pipe(Effect.provide(WorkerConfig.layer));
+ * }).pipe(Effect.provide(WorkerConfig.providerLayer));
  * ```
  *
  * Keys are constrained to scalar `Cloudflare.Env` properties (`string`,
@@ -82,13 +82,11 @@ declare namespace WorkerConfig {
    * Cloudflare worker `env` object.
    */
   const providerLayer: Layer.Layer<never, never, WorkerEnvironment>;
-  /** Alias for `providerLayer` for concise use in worker layers. */
-  const layer: Layer.Layer<never, never, WorkerEnvironment>;
   /** Build a `ConfigProvider` layer with a custom `env` conversion function. */
   const layerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => Layer.Layer<never, never, WorkerEnvironment>;
 }
 declare namespace Binding_d_exports {
-  export { BindingNotFoundError, BindingService, BindingValidationError, Service, TypeId, ValidationOptions, layer$1 as layer };
+  export { BindingNotFoundError, BindingService, BindingValidationError, Service, TypeId, ValidationOptions, layer };
 }
 /** Internal type id marker used by binding helper services. */
 declare const TypeId: "~effect-cf/Binding";
@@ -127,43 +125,11 @@ interface BindingService<Self, Id extends string, Service> extends Context.Servi
   readonly binding: string;
   readonly layer: Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
 }
-declare function layer$1<Self, Resource>(tag: Context.Service<Self, Resource>, binding: string, isResource: (value: unknown) => value is Resource, wrap?: undefined, options?: ValidationOptions): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
-declare function layer$1<Self, Resource, Service>(tag: Context.Service<Self, Service>, binding: string, isResource: (value: unknown) => value is Resource, wrap: (resource: Resource) => Service, options?: ValidationOptions): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
+declare function layer<Self, Resource>(tag: Context.Service<Self, Resource>, binding: string, isResource: (value: unknown) => value is Resource, wrap?: undefined, options?: ValidationOptions): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
+declare function layer<Self, Resource, Service>(tag: Context.Service<Self, Service>, binding: string, isResource: (value: unknown) => value is Resource, wrap: (resource: Resource) => Service, options?: ValidationOptions): Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
 declare const Service: <Self>() => {
   <Id extends string, Resource>(id: Id, binding: string, isResource: (value: unknown) => value is Resource, wrap?: undefined, options?: ValidationOptions): BindingService<Self, Id, Resource>;
   <Id extends string, Resource, Service>(id: Id, binding: string, isResource: (value: unknown) => value is Resource, wrap: (resource: Resource) => Service, options?: ValidationOptions): BindingService<Self, Id, Service>;
 };
-declare namespace Hyperdrive_d_exports {
-  export { HyperdriveClient, HyperdriveDefinition, HyperdriveService, LayerOptions, Tag, TagClass, isHyperdrive, layer, make, makeClient };
-}
-/** Typed Hyperdrive binding definition. */
-interface HyperdriveDefinition {
-  /** Binding name as configured in `wrangler.jsonc`. */
-  readonly binding: string;
-}
-interface HyperdriveClient {
-  readonly connectionString: string;
-  readonly rawUnsafe: Effect.Effect<Hyperdrive>;
-  readonly definition: HyperdriveDefinition;
-}
-declare const HyperdriveServiceTypeId: unique symbol;
-/** Nominal service marker for Hyperdrive services created with {@link make}. */
-interface HyperdriveService<Id extends string> {
-  readonly [HyperdriveServiceTypeId]: {
-    readonly id: Id;
-  };
-}
-type LayerOptions = {
-  readonly binding: string;
-};
-interface TagClass<Self, Id extends string> extends Context.ServiceClass<Self, Id, HyperdriveClient> {
-  readonly id: Id;
-  readonly layer: (options: LayerOptions) => Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
-}
-declare const isHyperdrive: (value: unknown) => value is Hyperdrive;
-declare const makeClient: (definition: HyperdriveDefinition) => (hyperdrive: Hyperdrive) => HyperdriveClient;
-declare const layer: <Self>(tag: Context.Service<Self, HyperdriveClient>, definition: HyperdriveDefinition) => Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
-declare const make: <Id extends string>(id: Id) => TagClass<HyperdriveService<Id>, Id>;
-declare const Tag: <Self>() => <Id extends string>(id: Id) => TagClass<Self, Id>;
 //#endregion
-export { BindingService as a, Environment_d_exports as c, WorkerEnvironment as d, BindingNotFoundError as i, WorkerConfig as l, LayerOptions as n, BindingValidationError as o, TagClass as r, Binding_d_exports as s, Hyperdrive_d_exports as t, WorkerEnv as u };
+export { Environment_d_exports as a, WorkerEnvironment as c, Binding_d_exports as i, BindingService as n, WorkerConfig as o, BindingValidationError as r, WorkerEnv as s, BindingNotFoundError as t };