effect-cf 0.0.1

package/src/Entry.ts

@@ -0,0 +1,259 @@
+import { WorkerEntrypoint as CloudflareWorkerEntrypoint } from "cloudflare:workers";
+import { Cause, Context, Effect, Exit, Layer, ManagedRuntime, type Scope } from "effect";
+import { HttpServerRequest } from "effect/unstable/http";
+
+import { WorkerEnvironment, type WorkerEnv } from "./Environment";
+
+/**
+ * Access to Cloudflare's native `ExecutionContext`.
+ */
+export class ExecutionContext extends Context.Service<
+  ExecutionContext,
+  globalThis.ExecutionContext
+>()("effect-cf/ExecutionContext") {}
+
+/**
+ * Options for {@link WorkerContextService.waitUntil}.
+ */
+export interface WorkerContextWaitUntilOptions<E, R> {
+  /** Custom failure handler for the background effect. */
+  readonly onFailure?: (cause: Cause.Cause<E>) => Effect.Effect<void, never, R>;
+}
+
+/**
+ * Effect wrapper around `ExecutionContext` background APIs.
+ */
+export interface WorkerContextService {
+  readonly raw: globalThis.ExecutionContext;
+  waitUntil<A, E, R, R2 = never>(
+    effect: Effect.Effect<A, E, R>,
+    options?: WorkerContextWaitUntilOptions<E, R2>,
+  ): Effect.Effect<void, never, R | R2>;
+  readonly passThroughOnException: Effect.Effect<void>;
+}
+
+/**
+ * Service used inside handlers to schedule background work via `waitUntil`.
+ *
+ * @example
+ * ```ts
+ * const handler = Effect.gen(function* () {
+ *   const ctx = yield* WorkerContext;
+ *   yield* ctx.waitUntil(Effect.log("flush analytics"));
+ *   return new Response("ok");
+ * });
+ * ```
+ */
+export class WorkerContext extends Context.Service<WorkerContext, WorkerContextService>()(
+  "effect-cf/WorkerContext",
+) {}
+
+type RunWaitUntilEffect = <A, E>(
+  effect: Effect.Effect<A, E, never>,
+) => Promise<Exit.Exit<A, unknown>>;
+
+const fromExecutionContext = (
+  ctx: globalThis.ExecutionContext,
+  runPromiseExit: RunWaitUntilEffect,
+): WorkerContextService => ({
+  raw: ctx,
+  waitUntil: <A, E, R, R2 = never>(
+    effect: Effect.Effect<A, E, R>,
+    options?: WorkerContextWaitUntilOptions<E, R2>,
+  ) =>
+    Effect.context<R | R2>().pipe(
+      Effect.flatMap((context) =>
+        Effect.sync(() => {
+          const observed = Effect.exit(effect).pipe(
+            Effect.flatMap((exit) => {
+              if (Exit.isSuccess(exit)) {
+                return Effect.void;
+              }
+
+              const handleFailure =
+                options?.onFailure?.(exit.cause) ??
+                Effect.logError("WorkerContext.waitUntil failed", Cause.pretty(exit.cause));
+
+              return handleFailure.pipe(
+                Effect.catchCause((handlerCause) =>
+                  Effect.logError(
+                    "WorkerContext.waitUntil failure handler failed",
+                    Cause.pretty(exit.cause),
+                    Cause.pretty(handlerCause),
+                  ),
+                ),
+              );
+            }),
+          );
+
+          ctx.waitUntil(
+            runPromiseExit(Effect.scoped(Effect.provideContext(observed, context))).then((exit) => {
+              if (Exit.isFailure(exit)) {
+                console.error(
+                  "WorkerContext.waitUntil failure handler failed",
+                  Cause.pretty(exit.cause),
+                );
+              }
+            }),
+          );
+        }),
+      ),
+    ),
+  passThroughOnException: Effect.sync(() => ctx.passThroughOnException()),
+});
+
+/**
+ * Access to the incoming `Request` currently handled by a worker or Durable Object fetch.
+ */
+export class NativeRequest extends Context.Service<NativeRequest, Request>()(
+  "effect-cf/NativeRequest",
+) {}
+
+/**
+ * Returns `true` when the request is a websocket upgrade request.
+ */
+export const isWebSocketUpgrade = (request: Request): boolean =>
+  request.headers.get("Upgrade")?.toLowerCase() === "websocket";
+
+type RequestServices = ExecutionContext | WorkerContext | WorkerEnvironment;
+
+type HandlerContext<ROut> =
+  | ExecutionContext
+  | WorkerContext
+  | WorkerEnvironment
+  | NativeRequest
+  | HttpServerRequest.HttpServerRequest
+  | ROut
+  | Scope.Scope;
+
+type RuntimeContext<ROut> = RequestServices | ROut;
+type RpcContext<ROut> = RuntimeContext<ROut> | Scope.Scope;
+
+const RunSymbol = Symbol.for("effect-cf/Worker/run");
+
+/**
+ * Effect type for `fetch` handlers executed by {@link make}.
+ */
+export type WorkerHandler<ROut, A = unknown> = Effect.Effect<A, unknown, HandlerContext<ROut>>;
+
+/**
+ * Effect type for worker RPC handlers.
+ */
+export type WorkerRpcHandler<ROut, A = unknown> = Effect.Effect<A, unknown, RpcContext<ROut>>;
+
+/**
+ * Shape of worker RPC handlers passed to {@link make}.
+ */
+export type WorkerRpc<ROut> = Record<string, (...args: Array<any>) => WorkerRpcHandler<ROut>>;
+
+export type WorkerRpcShape<Rpc extends WorkerRpc<ROut>, ROut> = {
+  readonly [Key in keyof Rpc]: Rpc[Key] extends (
+    ...args: infer Args
+  ) => Effect.Effect<infer A, unknown, RpcContext<ROut>>
+    ? (...args: Args) => Promise<A>
+    : never;
+};
+
+export type RpcHandlers<ROut, Api> = {
+  readonly [Key in keyof Api as Key extends keyof CloudflareWorkerEntrypoint
+    ? never
+    : Key extends string
+      ? [Api[Key]] extends [never]
+        ? never
+        : Api[Key] extends (...args: Array<any>) => Promise<unknown>
+          ? Key
+          : never
+      : never]: Api[Key] extends (...args: infer Args) => Promise<infer A>
+    ? (...args: Args) => WorkerRpcHandler<ROut, A>
+    : never;
+};
+
+/**
+ * Options for creating a worker class with Effect handlers.
+ */
+export interface WorkerOptions<ROut, Rpc extends WorkerRpc<ROut>> {
+  /** Main request handler. */
+  readonly fetch: Effect.Effect<Response, unknown, HandlerContext<ROut>>;
+  /** Optional RPC methods exposed as class instance methods. */
+  readonly rpc?: Rpc;
+}
+
+/**
+ * Cloudflare `WorkerEntrypoint` constructor produced by {@link make}.
+ */
+export type WorkerClass<Rpc extends WorkerRpc<ROut>, ROut> = new (
+  ctx: globalThis.ExecutionContext,
+  env: WorkerEnv,
+) => CloudflareWorkerEntrypoint<WorkerEnv> & WorkerRpcShape<Rpc, ROut>;
+
+/**
+ * Creates a Cloudflare worker class backed by a single managed Effect runtime.
+ *
+ * @example
+ * ```ts
+ * const Worker = Entry.make(Layer.empty, {
+ *   fetch: Effect.succeed(new Response("ok")),
+ * });
+ * ```
+ */
+export const make = <ROut, LayerError, const Rpc extends WorkerRpc<ROut> = Record<never, never>>(
+  layer: Layer.Layer<ROut, LayerError, RequestServices>,
+  options: WorkerOptions<ROut, Rpc>,
+): WorkerClass<Rpc, ROut> => {
+  class EffectWorker extends CloudflareWorkerEntrypoint<WorkerEnv> {
+    readonly runtime: ManagedRuntime.ManagedRuntime<RuntimeContext<ROut>, LayerError>;
+
+    constructor(ctx: globalThis.ExecutionContext, env: WorkerEnv) {
+      super(ctx, env);
+
+      let runWaitUntilEffect: RunWaitUntilEffect = () =>
+        Promise.resolve(Exit.die(new Error("WorkerContext runtime is not initialized")));
+
+      const services = Layer.mergeAll(
+        Layer.succeed(ExecutionContext, ctx),
+        Layer.succeed(
+          WorkerContext,
+          fromExecutionContext(ctx, (effect) => runWaitUntilEffect(effect)),
+        ),
+        Layer.succeed(WorkerEnvironment, env),
+      );
+
+      const runtimeLayer = layer.pipe(Layer.provideMerge(services)) as Layer.Layer<
+        RuntimeContext<ROut>,
+        LayerError,
+        never
+      >;
+
+      this.runtime = ManagedRuntime.make(runtimeLayer);
+      runWaitUntilEffect = <A, E>(effect: Effect.Effect<A, E, never>) =>
+        this.runtime.runPromiseExit(effect as Effect.Effect<A, E, RuntimeContext<ROut>>);
+    }
+
+    [RunSymbol]<A, E>(effect: Effect.Effect<A, E, RuntimeContext<ROut> | Scope.Scope>): Promise<A> {
+      return this.runtime.runPromise(Effect.scoped(effect));
+    }
+
+    fetch(request: Request): Promise<Response> {
+      return this[RunSymbol](
+        options.fetch.pipe(
+          Effect.provideService(NativeRequest, request),
+          Effect.provideService(
+            HttpServerRequest.HttpServerRequest,
+            HttpServerRequest.fromWeb(request),
+          ),
+        ),
+      );
+    }
+  }
+
+  for (const [key, method] of Object.entries(options.rpc ?? {})) {
+    Object.defineProperty(EffectWorker.prototype, key, {
+      enumerable: true,
+      value(this: EffectWorker, ...args: Array<any>) {
+        return this[RunSymbol](Effect.suspend(() => method(...args)));
+      },
+    });
+  }
+
+  return EffectWorker as WorkerClass<Rpc, ROut>;
+};

package/src/Environment.ts

@@ -0,0 +1,86 @@
+import { Config, ConfigProvider, Context, Effect } from "effect";
+
+/** Cloudflare worker environment object (`env`). */
+export type WorkerEnv = Cloudflare.Env;
+
+/**
+ * Context service for reading worker bindings from the current `env` object.
+ */
+export class WorkerEnvironment extends Context.Service<WorkerEnvironment, WorkerEnv>()(
+  "effect-cf/WorkerEnvironment",
+) {}
+
+type ScalarConfigValue = string | number | boolean;
+
+type ScalarConfigKey = Extract<
+  {
+    readonly [Key in keyof Cloudflare.Env]-?: NonNullable<
+      Cloudflare.Env[Key]
+    > extends ScalarConfigValue
+      ? Key
+      : never;
+  }[keyof Cloudflare.Env],
+  string
+>;
+
+/**
+ * Effect `Config` helpers for scalar Cloudflare vars and secrets declared on
+ * `Cloudflare.Env` / generated `worker-configuration.d.ts`.
+ *
+ * Users still author their app config explicitly with Effect `Config`:
+ *
+ * ```ts
+ * import { Config, Effect } from "effect";
+ * import { WorkerConfig } from "effect-cf";
+ *
+ * const AppConfig = Config.all({
+ *   databaseUrl: WorkerConfig.redacted("DATABASE_URL"),
+ *   port: WorkerConfig.integer("PORT").pipe(Config.withDefault(8787)),
+ * });
+ *
+ * const program = Effect.gen(function* () {
+ *   const config = yield* AppConfig;
+ *   // ...
+ * }).pipe(Effect.provide(WorkerConfig.layer));
+ * ```
+ *
+ * Keys are constrained to scalar `Cloudflare.Env` properties (`string`,
+ * `number`, or `boolean`, including optional scalar properties). Binding
+ * objects such as `KVNamespace`, `DurableObjectNamespace`, and service
+ * bindings are intentionally excluded; keep using the package binding helpers
+ * for those live resources.
+ */
+export namespace WorkerConfig {
+  /** Scalar env value types supported by the typed config key helpers. */
+  export type Scalar = ScalarConfigValue;
+
+  /** Scalar keys available on the current consumer's `Cloudflare.Env`. */
+  export type Key = ScalarConfigKey;
+
+  /** Read a scalar Cloudflare var or secret as a string. */
+  export const string = <const Name extends Key>(name: Name) => Config.string(name);
+
+  /** Read a scalar Cloudflare secret as a redacted string. */
+  export const redacted = <const Name extends Key>(name: Name) => Config.redacted(name);
+
+  /** Read a scalar Cloudflare var or secret as a number. */
+  export const number = <const Name extends Key>(name: Name) => Config.number(name);
+
+  /** Read a scalar Cloudflare var or secret as an integer. */
+  export const integer = <const Name extends Key>(name: Name) => Config.int(name);
+
+  /** Read a scalar Cloudflare var or secret as a boolean. */
+  export const boolean = <const Name extends Key>(name: Name) => Config.boolean(name);
+
+  /** Build a `ConfigProvider` from the current `WorkerEnvironment`. */
+  export const provider = Effect.map(WorkerEnvironment.asEffect(), ConfigProvider.fromUnknown);
+
+  /**
+   * Replace the active Effect `ConfigProvider` with one backed by the current
+   * Cloudflare worker `env` object.
+   */
+  export const providerLayer = ConfigProvider.layer(provider);
+
+  /** Alias for `providerLayer` for concise use in worker layers. */
+  export const layer = providerLayer;
+}

package/src/Kv.ts

@@ -0,0 +1,244 @@
+import { Data, Effect, Option, Schema as S } from "effect";
+
+import * as Binding from "./Binding";
+
+const TypeId = "effect-cf/Kv" as const;
+
+/** Error raised when a KV operation fails. */
+export class KvOperationError extends Data.TaggedError("KvOperationError")<{
+  readonly binding: string;
+  readonly operation: string;
+  readonly cause: unknown;
+}> {}
+
+/** `KVNamespace.put` options. */
+export type KvPutOptions = globalThis.KVNamespacePutOptions;
+/** `KVNamespace.list` options with optional metadata decoding schema. */
+export type KvListOptions<Metadata = unknown> = globalThis.KVNamespaceListOptions & {
+  readonly metadataSchema?: S.Codec<Metadata, unknown>;
+};
+
+/** Successful value returned by `getWithMetadata`. */
+export interface KvWithMetadata<Value, Metadata> {
+  readonly value: Value;
+  readonly metadata: Option.Option<Metadata>;
+  readonly cacheStatus: Option.Option<string>;
+}
+
+/** Decoded key entry returned by `list`. */
+export interface KvListKey<Key, Metadata = unknown> {
+  readonly name: Key;
+  readonly expiration: Option.Option<number>;
+  readonly metadata: Option.Option<Metadata>;
+}
+
+/** Decoded result returned by `list`. */
+export interface KvListResult<Key, Metadata = unknown> {
+  readonly keys: ReadonlyArray<KvListKey<Key, Metadata>>;
+  readonly listComplete: boolean;
+  readonly cursor: Option.Option<string>;
+  readonly cacheStatus: Option.Option<string>;
+}
+
+/**
+ * Typed KV binding definition.
+ */
+export interface KvDefinition<Key, Value, EncodedValue> {
+  /** Binding name as configured in `wrangler.jsonc`. */
+  readonly binding: string;
+  /** Codec used to encode/decode keys. */
+  readonly key: S.Codec<Key, string>;
+  /** Codec used to encode/decode values. */
+  readonly value: S.Codec<Value, EncodedValue>;
+}
+
+declare const KvServiceTypeId: unique symbol;
+
+/** Nominal service marker for KV services created with {@link make}. */
+export interface KvService<Id extends string, Key, Value, EncodedValue> {
+  readonly [KvServiceTypeId]: {
+    readonly id: Id;
+    readonly key: Key;
+    readonly value: Value;
+    readonly encodedValue: EncodedValue;
+  };
+}
+
+const maybeString = (value: string | null | undefined): Option.Option<string> =>
+  value == null ? Option.none() : Option.some(value);
+
+const maybeNumber = (value: number | undefined): Option.Option<number> =>
+  value === undefined ? Option.none() : Option.some(value);
+
+const kvError = (binding: string, operation: string, cause: unknown) =>
+  new KvOperationError({ binding, operation, cause });
+
+const tryKvPromise = <A>(
+  binding: string,
+  operation: string,
+  evaluate: () => Promise<A>,
+): Effect.Effect<A, KvOperationError> =>
+  Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => kvError(binding, operation, cause),
+  });
+
+/**
+ * Creates a typed KV service tag plus Effect helpers.
+ */
+export const make = <Id extends string, Key, Value, EncodedValue>(
+  id: Id,
+  definition: KvDefinition<Key, Value, EncodedValue>,
+) =>
+  Service<KvService<Id, Key, Value, EncodedValue>>()<Id, Key, Value, EncodedValue>(id, definition);
+
+/**
+ * Builds a KV service around a Cloudflare KV namespace binding.
+ *
+ * Returned service includes schema-aware `put`, `get`, `getWithMetadata`,
+ * `list`, and `remove` helpers.
+ *
+ * @example
+ * ```ts
+ * const Sessions = Kv.make("Sessions", {
+ *   binding: "SESSIONS",
+ *   key: Schema.String,
+ *   value: Schema.Struct({ userId: Schema.String }),
+ * });
+ *
+ * const program = Effect.gen(function* () {
+ *   yield* Sessions.put("abc", { userId: "u_1" });
+ *   return yield* Sessions.get("abc");
+ * });
+ * ```
+ */
+export const Service =
+  <Self>() =>
+  <Id extends string, Key, Value, EncodedValue>(
+    id: Id,
+    definition: KvDefinition<Key, Value, EncodedValue>,
+  ) => {
+    const tag = Binding.Service<Self>()(id, definition.binding, (value): value is KVNamespace => {
+      if (typeof value !== "object" || value === null) {
+        return false;
+      }
+
+      const resource = value as Record<string, unknown>;
+
+      return (
+        typeof resource.get === "function" &&
+        typeof resource.put === "function" &&
+        typeof resource.delete === "function" &&
+        typeof resource.getWithMetadata === "function" &&
+        typeof resource.list === "function"
+      );
+    });
+
+    const encodeKey = S.encodeEffect(definition.key);
+    const decodeKey = S.decodeUnknownEffect(definition.key);
+    const encodeValue = S.encodeEffect(S.fromJsonString(S.toCodecJson(definition.value)));
+    const decodeValue = S.decodeUnknownEffect(S.fromJsonString(S.toCodecJson(definition.value)));
+
+    const put = Effect.fnUntraced(function* (key: Key, value: Value, options?: KvPutOptions) {
+      const kv = yield* tag;
+      const keyEncoded = yield* encodeKey(key);
+      const valueEncoded = yield* encodeValue(value);
+      yield* tryKvPromise(definition.binding, "put", () =>
+        kv.put(keyEncoded, valueEncoded, options),
+      );
+    });
+
+    const get = Effect.fnUntraced(function* (key: Key) {
+      const kv = yield* tag;
+      const keyEncoded = yield* encodeKey(key);
+      const valueEncoded = yield* tryKvPromise(definition.binding, "get", () => kv.get(keyEncoded));
+
+      if (valueEncoded === null) {
+        return Option.none();
+      }
+
+      return yield* decodeValue(valueEncoded).pipe(Effect.map(Option.some));
+    });
+
+    const getWithMetadata = Effect.fnUntraced(function* <Metadata>(
+      key: Key,
+      metadataSchema: S.Codec<Metadata, unknown>,
+    ) {
+      const kv = yield* tag;
+      const keyEncoded = yield* encodeKey(key);
+      const result = yield* tryKvPromise(definition.binding, "getWithMetadata", () =>
+        kv.getWithMetadata<Metadata>(keyEncoded),
+      );
+
+      if (result.value === null) {
+        return Option.none();
+      }
+
+      const value = yield* decodeValue(result.value);
+      const metadata =
+        result.metadata === null
+          ? Option.none<Metadata>()
+          : Option.some(yield* S.decodeUnknownEffect(metadataSchema)(result.metadata));
+
+      return Option.some({
+        value,
+        metadata,
+        cacheStatus: maybeString(result.cacheStatus),
+      });
+    });
+
+    const list = Effect.fnUntraced(function* <Metadata = unknown>(
+      options?: KvListOptions<Metadata>,
+    ) {
+      const kv = yield* tag;
+      const { metadataSchema, ...kvOptions } = options ?? {};
+      const result = yield* tryKvPromise(definition.binding, "list", () =>
+        kv.list<Metadata>(kvOptions),
+      );
+      const keys: Array<KvListKey<Key, Metadata>> = [];
+
+      for (const key of result.keys) {
+        const decodedName = yield* decodeKey(key.name);
+        const decodedMetadata =
+          key.metadata === undefined
+            ? Option.none<Metadata>()
+            : metadataSchema === undefined
+              ? Option.some(key.metadata as Metadata)
+              : Option.some(yield* S.decodeUnknownEffect(metadataSchema)(key.metadata));
+
+        keys.push({
+          name: decodedName,
+          expiration: maybeNumber(key.expiration),
+          metadata: decodedMetadata,
+        });
+      }
+
+      return {
+        keys,
+        listComplete: result.list_complete,
+        cursor: maybeString("cursor" in result ? result.cursor : undefined),
+        cacheStatus: maybeString(result.cacheStatus),
+      };
+    });
+
+    const remove = Effect.fnUntraced(function* (key: Key) {
+      const kv = yield* tag;
+      const keyEncoded = yield* encodeKey(key);
+      yield* tryKvPromise(definition.binding, "delete", () => kv.delete(keyEncoded));
+    });
+
+    const unsafeRaw = Effect.fnUntraced(function* () {
+      return yield* tag;
+    });
+
+    return Object.assign(tag, {
+      [TypeId]: TypeId,
+      definition,
+      put,
+      get,
+      getWithMetadata,
+      list,
+      remove,
+      unsafeRaw,
+    });
+  };