effect-cf 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # effect-cf
 
+## 0.8.0
+
+### Minor Changes
+
+- [#22](https://github.com/danieljvdm/effect-cf/pull/22) [`24c27ee`](https://github.com/danieljvdm/effect-cf/commit/24c27ee2884aacc72ab51ab5a208b795e1fa9738) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Add Effect-native R2 bucket, Hyperdrive, and Cloudflare Images binding tags, including optional hosted Images operations, ArrayBuffer image inputs, and an optional Hyperdrive Postgres SQL layer integration.
+
+- [#22](https://github.com/danieljvdm/effect-cf/pull/22) [`24c27ee`](https://github.com/danieljvdm/effect-cf/commit/24c27ee2884aacc72ab51ab5a208b795e1fa9738) Thanks [@danieljvdm](https://github.com/danieljvdm)! - Remove non-canonical static operation helpers from existing KV and D1 resource bindings. Use yielded binding services for resource operations; D1 keeps `sqlLayer()`.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -32,6 +32,9 @@ Runtime creation belongs at Cloudflare entrypoints, not inside binding helpers.
 - `DurableObjectWebSocket` - WebSocket upgrade helpers for Durable Objects
 - `Kv` - typed KV namespace helper
 - `D1` - typed D1 database binding helper with an `@effect/sql-d1` backed SQL layer
+- `R2` - typed R2 bucket binding helper with Effect-wrapped object and multipart operations
+- `Hyperdrive` - typed Hyperdrive binding helper for connection strings and optional Postgres SQL integration
+- `Images` - typed Cloudflare Images binding helper with transformation APIs and optional hosted image operations
 - `Queue` - typed Queue producer/consumer tags plus client and error types
 - `Workflow` - typed Workflow entrypoints, steps, starter clients, and instance types
 - `Rpc` - Cloudflare RPC type helpers and scoped disposal utilities
@@ -115,6 +118,94 @@ Producers should usually use `const queue = yield* AvatarQueue` and then call `q
 
 Queue handlers run inline failures through Cloudflare's normal retry path. If background work scheduled with `WorkerContext.waitUntil(...)` should also make the batch retry, use `WorkerContext.waitUntilPropagating(...)` or `waitUntil(..., { mode: "propagate" })`; the default `waitUntil` mode observes and logs failures without rejecting the native `waitUntil` promise.
 
+## R2 Example
+
+R2 bucket tags expose Cloudflare object operations as Effects and map nullable reads to `Option`.
+
+```ts
+import { Effect, Layer, Option } from "effect";
+import { R2 } from "effect-cf";
+
+class ArtifactBucket extends R2.Tag<ArtifactBucket>()("ArtifactBucket") {}
+
+export const ArtifactBucketLayer = ArtifactBucket.layer({ binding: "ARTIFACT_BUCKET" });
+
+export const writeArtifact = (key: string, body: string) =>
+  Effect.gen(function* () {
+    const bucket = yield* ArtifactBucket;
+    yield* bucket.put(key, body, {
+      httpMetadata: { contentType: "application/json" },
+    });
+  });
+
+export const readArtifact = (key: string) =>
+  Effect.gen(function* () {
+    const bucket = yield* ArtifactBucket;
+    const object = yield* bucket.get(key);
+    return Option.isSome(object) ? yield* Effect.promise(() => object.value.text()) : undefined;
+  });
+```
+
+Use `createMultipartUpload(...)` or `resumeMultipartUpload(...)` for large objects; returned upload handles wrap `uploadPart`, `complete`, and `abort` in Effect.
+
+## Hyperdrive Example
+
+Hyperdrive tags expose the binding `connectionString` directly on the yielded service.
+
+```ts
+import { Effect } from "effect";
+import { Hyperdrive } from "effect-cf";
+
+class AppDatabase extends Hyperdrive.Tag<AppDatabase>()("AppDatabase") {}
+
+export const AppDatabaseLayer = AppDatabase.layer({ binding: "HYPERDRIVE" });
+
+export const databaseUrl = Effect.gen(function* () {
+  const hyperdrive = yield* AppDatabase;
+  return hyperdrive.connectionString;
+});
+```
+
+If your Worker uses Postgres via `@effect/sql-pg`, install that driver and use the optional subpath integration:
+
+```ts
+import { Hyperdrive } from "effect-cf";
+import * as HyperdrivePg from "effect-cf/hyperdrive-pg";
+
+class AppDatabase extends Hyperdrive.Tag<AppDatabase>()("AppDatabase") {}
+
+export const SqlLive = HyperdrivePg.layer(AppDatabase, { binding: "HYPERDRIVE" });
+```
+
+The Postgres integration builds an Effect `PgClient` from Hyperdrive's generated connection string with `PgClient.makeClient`. It intentionally does not expose app-side pool options; Hyperdrive manages the underlying database pool.
+
+## Images Example
+
+Images tags expose `info`, `input`, optional hosted image operations, and composable transform/draw steps.
+
+```ts
+import { Effect } from "effect";
+import { Images } from "effect-cf";
+
+class AvatarImages extends Images.Tag<AvatarImages>()("AvatarImages") {}
+
+export const AvatarImagesLayer = AvatarImages.layer({ binding: "IMAGES" });
+
+export const resizeAvatar = (image: Images.ImageInputValue) =>
+  Effect.gen(function* () {
+    const images = yield* AvatarImages;
+    const result = yield* images.process(
+      Images.transform(Images.empty, { width: 256, height: 256 }),
+      {
+        stream: image,
+        outputOptions: { format: "image/webp" },
+      },
+    );
+
+    return yield* result.response;
+  });
+```
+
 ## Workflow Example
 
 Workflow definitions type the payload and result. Runtime handlers can access `Workflow.WorkflowEvent`, use durable `Workflow.step(...)`, and use normal binding services inside steps.

package/dist/Hyperdrive-By6DrSS_.d.mts

@@ -0,0 +1,140 @@
+import { Config, ConfigProvider, Context, Effect, Layer } from "effect";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+import * as _$effect_Redacted0 from "effect/Redacted";
+import * as _$effect_Layer0 from "effect/Layer";
+
+//#region src/Environment.d.ts
+/** Cloudflare worker environment object (`env`). */
+type WorkerEnv = Cloudflare.Env;
+declare const WorkerEnvironment_base: Context.ServiceClass<WorkerEnvironment, "effect-cf/WorkerEnvironment", Cloudflare.Env>;
+/**
+ * Context service for reading worker bindings from the current `env` object.
+ */
+declare class WorkerEnvironment extends WorkerEnvironment_base {}
+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.
+ */
+declare namespace WorkerConfig {
+  /** Scalar env value types supported by the typed config key helpers. */
+  type Scalar = ScalarConfigValue;
+  /** Scalar keys available on the current consumer's `Cloudflare.Env`. */
+  type Key = ScalarConfigKey;
+  /** Read a scalar Cloudflare var or secret as a string. */
+  const string: <const Name extends Key>(name: Name) => Config.Config<string>;
+  /** Read a scalar Cloudflare secret as a redacted string. */
+  const redacted: <const Name extends Key>(name: Name) => Config.Config<_$effect_Redacted0.Redacted<string>>;
+  /** Read a scalar Cloudflare var or secret as a number. */
+  const number: <const Name extends Key>(name: Name) => Config.Config<number>;
+  /** Read a scalar Cloudflare var or secret as an integer. */
+  const integer: <const Name extends Key>(name: Name) => Config.Config<number>;
+  /** Read a scalar Cloudflare var or secret as a boolean. */
+  const boolean: <const Name extends Key>(name: Name) => Config.Config<boolean>;
+  /** Build a `ConfigProvider` from a Cloudflare worker `env` object. */
+  const providerFromEnv: (env: WorkerEnv) => ConfigProvider.ConfigProvider;
+  /**
+   * Build a `ConfigProvider` from the current `WorkerEnvironment` with a custom
+   * conversion function.
+   */
+  const providerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => Effect.Effect<ConfigProvider.ConfigProvider, never, WorkerEnvironment>;
+  /** Build a `ConfigProvider` from the current `WorkerEnvironment`. */
+  const provider: Effect.Effect<ConfigProvider.ConfigProvider, never, WorkerEnvironment>;
+  /**
+   * Replace the active Effect `ConfigProvider` with one backed by the current
+   * Cloudflare worker `env` object.
+   */
+  const providerLayer: _$effect_Layer0.Layer<never, never, WorkerEnvironment>;
+  /** Alias for `providerLayer` for concise use in worker layers. */
+  const layer: _$effect_Layer0.Layer<never, never, WorkerEnvironment>;
+  /** Build a `ConfigProvider` layer with a custom `env` conversion function. */
+  const layerWith: (makeProvider: (env: WorkerEnv) => ConfigProvider.ConfigProvider) => _$effect_Layer0.Layer<never, never, WorkerEnvironment>;
+}
+declare namespace Binding_d_exports {
+  export { BindingNotFoundError, BindingService, BindingValidationError, Service, TypeId, layer$1 as layer };
+}
+/** Internal type id marker used by binding helper services. */
+declare const TypeId: "effect-cf/Binding";
+declare const BindingNotFoundError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BindingNotFoundError";
+} & Readonly<A>;
+/** Error raised when a configured binding does not exist on `env`. */
+declare class BindingNotFoundError extends BindingNotFoundError_base<{
+  readonly binding: string;
+}> {}
+declare const BindingValidationError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BindingValidationError";
+} & Readonly<A>;
+/** Error raised when a binding exists but does not match the expected shape. */
+declare class BindingValidationError extends BindingValidationError_base<{
+  readonly binding: string;
+}> {}
+/**
+ * Creates a Context tag + layer for reading and validating a Cloudflare binding.
+ */
+interface BindingService<Self, Id extends string, Service> extends Context.ServiceClass<Self, Id, Service> {
+  readonly [TypeId]: typeof TypeId;
+  readonly binding: string;
+  readonly layer: Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
+}
+declare const layer$1: <Self, Resource, Service = Resource>(tag: Context.Service<Self, Service>, binding: string, isResource: (value: unknown) => value is Resource, wrap?: (resource: Resource) => Service) => Layer.Layer<Self, BindingNotFoundError | BindingValidationError, WorkerEnvironment>;
+declare const Service: <Self>() => <Id extends string, Resource, Service = Resource>(id: Id, binding: string, isResource: (value: unknown) => value is Resource, wrap?: (resource: Resource) => Service) => 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 unsafeRaw: 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, WorkerConfig as c, BindingNotFoundError as i, WorkerEnv as l, LayerOptions as n, BindingValidationError as o, TagClass as r, Binding_d_exports as s, Hyperdrive_d_exports as t, WorkerEnvironment as u };

package/dist/Hyperdrive-LuQaVhXU.mjs

@@ -0,0 +1,86 @@
+import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
+import { Config, ConfigProvider, Context, Data, Effect, Layer } from "effect";
+//#region src/Environment.ts
+/**
+* Context service for reading worker bindings from the current `env` object.
+*/
+var WorkerEnvironment = class extends Context.Service()("effect-cf/WorkerEnvironment") {};
+let WorkerConfig;
+(function(_WorkerConfig) {
+	_WorkerConfig.string = (name) => Config.string(name);
+	_WorkerConfig.redacted = (name) => Config.redacted(name);
+	_WorkerConfig.number = (name) => Config.number(name);
+	_WorkerConfig.integer = (name) => Config.int(name);
+	_WorkerConfig.boolean = (name) => Config.boolean(name);
+	const providerFromEnv = _WorkerConfig.providerFromEnv = (env) => ConfigProvider.fromUnknown(env);
+	const providerWith = _WorkerConfig.providerWith = (makeProvider) => Effect.map(WorkerEnvironment.asEffect(), makeProvider);
+	const provider = _WorkerConfig.provider = providerWith(providerFromEnv);
+	_WorkerConfig.layer = _WorkerConfig.providerLayer = ConfigProvider.layer(provider);
+	_WorkerConfig.layerWith = (makeProvider) => ConfigProvider.layer(providerWith(makeProvider));
+})(WorkerConfig || (WorkerConfig = {}));
+//#endregion
+//#region src/Binding.ts
+var Binding_exports = /* @__PURE__ */ __exportAll({
+	BindingNotFoundError: () => BindingNotFoundError,
+	BindingValidationError: () => BindingValidationError,
+	Service: () => Service,
+	TypeId: () => TypeId,
+	layer: () => layer$1
+});
+/** Internal type id marker used by binding helper services. */
+const TypeId = "effect-cf/Binding";
+/** Error raised when a configured binding does not exist on `env`. */
+var BindingNotFoundError = class extends Data.TaggedError("BindingNotFoundError") {};
+/** Error raised when a binding exists but does not match the expected shape. */
+var BindingValidationError = class extends Data.TaggedError("BindingValidationError") {};
+const isPropertyTarget = (value) => (typeof value === "object" || typeof value === "function") && value !== null;
+const getBinding = (env, binding, isResource) => Effect.gen(function* () {
+	if (!isPropertyTarget(env)) return yield* Effect.fail(new BindingValidationError({ binding }));
+	const resource = Reflect.get(env, binding);
+	if (resource === void 0) return yield* Effect.fail(new BindingNotFoundError({ binding }));
+	if (!isResource(resource)) return yield* Effect.fail(new BindingValidationError({ binding }));
+	return resource;
+});
+const layer$1 = (tag, binding, isResource, wrap) => Layer.effect(tag, Effect.gen(function* () {
+	const resource = yield* getBinding(yield* WorkerEnvironment, binding, isResource);
+	return wrap === void 0 ? resource : wrap(resource);
+}));
+const Service = () => (id, binding, isResource, wrap) => {
+	const tag = Context.Service()(id);
+	const serviceLayer = layer$1(tag, binding, isResource, wrap);
+	return Object.assign(tag, {
+		[TypeId]: TypeId,
+		binding,
+		layer: serviceLayer
+	});
+};
+//#endregion
+//#region src/Hyperdrive.ts
+var Hyperdrive_exports = /* @__PURE__ */ __exportAll({
+	Tag: () => Tag,
+	isHyperdrive: () => isHyperdrive,
+	layer: () => layer,
+	make: () => make,
+	makeClient: () => makeClient
+});
+const isHyperdrive = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	return typeof value.connectionString === "string";
+};
+const makeClient = (definition) => (hyperdrive) => ({
+	definition,
+	connectionString: hyperdrive.connectionString,
+	unsafeRaw: Effect.succeed(hyperdrive)
+});
+const layer = (tag, definition) => layer$1(tag, definition.binding, isHyperdrive, makeClient(definition));
+const make = (id) => Tag()(id);
+const Tag = () => (id) => {
+	const tag = Context.Service()(id);
+	const makeLayer = (definition) => layer(tag, definition);
+	return Object.assign(tag, {
+		id,
+		layer: makeLayer
+	});
+};
+//#endregion
+export { WorkerConfig as a, layer$1 as i, Binding_exports as n, WorkerEnvironment as o, Service as r, Hyperdrive_exports as t };

package/dist/HyperdrivePg.d.mts

@@ -0,0 +1,14 @@
+import { i as BindingNotFoundError, n as LayerOptions, o as BindingValidationError, r as TagClass, u as WorkerEnvironment } from "./Hyperdrive-By6DrSS_.mjs";
+import { Layer } from "effect";
+import { PgClient } from "@effect/sql-pg";
+import * as _$effect_unstable_sql_SqlClient0 from "effect/unstable/sql/SqlClient";
+import * as _$effect_unstable_sql_SqlError0 from "effect/unstable/sql/SqlError";
+import * as _$effect_Scope0 from "effect/Scope";
+
+//#region src/HyperdrivePg.d.ts
+type PgLayerOptions = Omit<PgClient.PgClientConfig & {
+  readonly acquireForStream?: boolean;
+}, "url" | "host" | "port" | "path" | "ssl" | "database" | "username" | "password" | "stream">;
+declare const layer: <Self, Id extends string>(tag: TagClass<Self, Id>, binding: LayerOptions, options?: PgLayerOptions) => Layer.Layer<PgClient.PgClient | _$effect_unstable_sql_SqlClient0.SqlClient, BindingNotFoundError | BindingValidationError | _$effect_unstable_sql_SqlError0.SqlError, WorkerEnvironment | Exclude<Exclude<Self, _$effect_Scope0.Scope>, Self>>;
+//#endregion
+export { PgLayerOptions, layer };

package/dist/HyperdrivePg.mjs

@@ -0,0 +1,13 @@
+import "./Hyperdrive-LuQaVhXU.mjs";
+import { Effect, Layer, Redacted } from "effect";
+import { PgClient } from "@effect/sql-pg";
+//#region src/HyperdrivePg.ts
+const layer = (tag, binding, options) => Layer.unwrap(Effect.gen(function* () {
+	const hyperdrive = yield* tag;
+	return PgClient.layerFrom(PgClient.makeClient({
+		...options,
+		url: Redacted.make(hyperdrive.connectionString)
+	}));
+})).pipe(Layer.provide(tag.layer(binding)));
+//#endregion
+export { layer };