improve binding errors and module structure (#413)

harrysolovay · web-flow · commit 9583d0e8d84f · 2026-04-23T13:54:50.000-04:00
diff --git a/.changeset/modern-plants-rush.md b/.changeset/modern-plants-rush.md
@@ -0,0 +1,7 @@
+---
+"liminal-cloudflare": patch
+"liminal": patch
+"liminal-browser": patch
+---
+
+Rework the module structure for bindings.
diff --git a/docs/pages/cloudflare/assets.mdx b/docs/pages/cloudflare/assets.mdx
@@ -63,7 +63,7 @@ If you need lower-level behavior than `forward`, you can use the raw asset bindi
 Effect.gen(function* () {
   // ...
 
-  const assets = yield* Assets
+  const assets = yield* Assets.Assets
   const response = yield* Effect.promise(() => assets.fetch(request))
 })
 ```
diff --git a/docs/pages/cloudflare/hyperdrive.mdx b/docs/pages/cloudflare/hyperdrive.mdx
@@ -17,23 +17,16 @@ const HyperdriveLive = Hyperdrive.layer("HYPERDRIVE")
 
 ## What the wrapper gives you
 
-- `.layer(binding)` — build a layer from the Cloudflare env binding name
-- `.connectionString` as `Effect<Redacted<string>, never, Hyperdrive>`
+- `Hyperdrive.layer(binding)` — build a layer from the Cloudflare env binding name
+- `Hyperdrive.connectionString` — an `Effect<Redacted<string>, never, Hyperdrive.Hyperdrive>` that yields the binding's
+  connection string as a `Redacted<string>`
 
 ```ts
 import { Hyperdrive } from "liminal-cloudflare/bindings"
 
-const connectionString = Hyperdrive.connectionString
+Hyperdrive.connectionString
 ```
 
-Internally, that is just:
-
-```ts
-Hyperdrive.asEffect().pipe(Effect.map(({ connectionString }) => Redacted.make(connectionString)))
-```
-
-So the wrapper is a thin typed shell over the raw Hyperdrive binding.
-
 ## Why the connection string is redacted
 
 The raw Hyperdrive connection string is sensitive configuration.
diff --git a/docs/pages/cloudflare/kv.mdx b/docs/pages/cloudflare/kv.mdx
@@ -1,12 +1,12 @@
 # Cloudflare KV
 
-`Kv(...)` is the `liminal-cloudflare` wrapper for Cloudflare KV.
+`Kv.Kv(...)` is the `liminal-cloudflare` wrapper for Cloudflare KV.
 
 It turns a KV namespace into a typed Effect service with schema-driven key encoding and value encoding/decoding.
 
 ## Define a KV service
 
-`Kv(...)` needs two things:
+`Kv.Kv(...)` needs two things:
 
 - a schema whose encoded form is a string key
 - a schema for the stored value
@@ -22,7 +22,7 @@ const SessionValue = S.Struct({
   expiresAt: S.Date,
 })
 
-export class SessionKv extends Kv<SessionKv>()("SessionKv", {
+export class SessionKv extends Kv.Kv<SessionKv>()("SessionKv", {
   key: SessionId,
   value: SessionValue,
 }) {}
diff --git a/examples/tictactoe/api/main.ts b/examples/tictactoe/api/main.ts
@@ -31,7 +31,7 @@ export default Worker.make({
     Layer.provide(HttpServer.layerServices),
     HttpRouter.toHttpEffect,
     Effect.flatMap((v) => v),
-    Effect.provide(Layer.mergeAll(KvLive, TicTacToeRegistry.layer("TICTACTOE_REGISTRY"), Assets.layer("ASSETS"))),
+    Effect.provide(Layer.mergeAll(KvLive, TicTacToeRegistry.layer("TICTACTOE"), Assets.layer("ASSETS"))),
     Effect.catchCause(() => Effect.succeed(HttpServerResponse.empty({ status: 500 }))),
   ),
   prelude: Layer.empty,
diff --git a/examples/tictactoe/app/wrangler.jsonc b/examples/tictactoe/app/wrangler.jsonc
@@ -29,7 +29,7 @@
   "durable_objects": {
     "bindings": [
       {
-        "name": "TIC_TAC_TOE",
+        "name": "TICTACTOE",
         "class_name": "TicTacToeRegistry",
       },
     ],
@@ -43,11 +43,4 @@
   "vars": {
     "DEV": true,
   },
-  "d1_databases": [
-    {
-      "binding": "TIC_TAC_TOE_D1",
-      "database_name": "tictactoe",
-      "database_id": "4257ef71-66f7-498c-8a41-e4d9acebf667",
-    },
-  ],
 }
diff --git a/liminal-cloudflare/ActorRegistry.ts b/liminal-cloudflare/ActorRegistry.ts
@@ -24,13 +24,11 @@ import { logCause } from "liminal/_util/logCause"
 import * as Mutex from "liminal/_util/Mutex"
 import { type TopFromString, encodeJsonString, decodeJsonString } from "liminal/_util/schema"
 
-import { Binding, DurableObjectState, NativeRequest } from "./bindings/index.ts"
+import { DoState, NativeRequest, Binding } from "./bindings/index.ts"
 import { close } from "./close.ts"
 
 const { debug, span } = Diagnostic.module("cloudflare.ActorRegistry")
 
-const TypeId = "~liminal/cloudflare/ActorRegistry" as const
-
 export interface ActorRegistryDefinition<
   ActorSelf,
   ActorId extends string,
@@ -91,11 +89,9 @@ export interface ActorRegistry<
   PreludeE,
   RunROut,
   RunE,
-> extends Binding<RegistrySelf, RegistryId, DurableObjectNamespace, never, never, never> {
+> extends Context.Service<RegistrySelf, DurableObjectNamespace> {
   new (state: globalThis.DurableObjectState<{}>): Context.ServiceClass.Shape<RegistryId, DurableObjectNamespace>
 
-  readonly [TypeId]: typeof TypeId
-
   readonly definition: ActorRegistryDefinition<
     ActorSelf,
     ActorId,
@@ -113,7 +109,9 @@ export interface ActorRegistry<
   readonly upgrade: (
     name: Name["Type"],
     attachments: S.Struct<AttachmentFields>["Type"],
-  ) => Effect.Effect<HttpServerResponse.HttpServerResponse, S.SchemaError, RegistrySelf | NativeRequest>
+  ) => Effect.Effect<HttpServerResponse.HttpServerResponse, S.SchemaError, RegistrySelf | NativeRequest.NativeRequest>
+
+  readonly layer: (binding: string) => Layer.Layer<RegistrySelf, S.SchemaError, never>
 }
 
 export const Service =
@@ -194,13 +192,13 @@ export const Service =
         encodeAttachments(attachments).pipe(Effect.andThen((v) => Effect.sync(() => socket.serializeAttachment(v)))),
     }
 
-    class tag extends Binding<RegistrySelf>()(id, (value): value is DurableObjectNamespace => "getByName" in value) {
+    const tag = class tag extends Context.Service<RegistrySelf, DurableObjectNamespace>()(id) {
       readonly runtime
       readonly directory = ClientDirectory.make(actor, transport)
 
-      constructor(state: globalThis.DurableObjectState<{}>, env: unknown) {
-        // @ts-ignore
-        super(state, env)
+      constructor(...args: [never]) {
+        super(...args)
+        const [state, env] = args as never as [state: globalThis.DurableObjectState<{}>, env: unknown]
 
         if (hibernation) {
           Option.andThen(
@@ -212,7 +210,7 @@ export const Service =
         const baseLayer = Layer.mergeAll(
           prelude.pipe(Layer.provideMerge(ConfigProvider.layer(ConfigProvider.fromUnknown(env)))),
           FetchHttpClient.layer,
-          Layer.succeed(DurableObjectState, state),
+          Layer.succeed(DoState.DoState, state),
           Mutex.layer,
         )
 
@@ -242,12 +240,12 @@ export const Service =
           const attachments = yield* decodeAttachmentsString(url.searchParams.get("__liminal_attachments"))
           if (!this.#name) {
             this.#name = name
-            const state = yield* DurableObjectState
+            const state = yield* DoState.DoState
             const encoded = yield* S.encodeEffect(Name)(name)
             yield* Effect.promise(() => state.storage.put("__liminal_name", encoded))
           }
           const { 0: webSocket, 1: server } = new WebSocketPair()
-          const state = yield* DurableObjectState
+          const state = yield* DoState.DoState
           state.acceptWebSocket(server)
           server.send(yield* encodeAuditionSuccess({ _tag: "Audition.Success" }))
           const currentClient = yield* this.directory.register(server, attachments)
@@ -330,7 +328,7 @@ export const Service =
       const namespace = yield* tag
       const nameEncoded = yield* encodeName(name)
       const stub = namespace.getByName(nameEncoded)
-      const request = yield* NativeRequest
+      const request = yield* NativeRequest.NativeRequest
       const protocols = yield* Effect.fromNullishOr(request.headers.get(SecWebSocketProtocol)).pipe(
         Effect.map(flow(String.split(","), Array.map(String.trim))),
       )
@@ -353,5 +351,7 @@ export const Service =
       return yield* Effect.promise(() => stub.fetch(new Request(url, request))).pipe(Effect.map(HttpServerResponse.raw))
     }, span("upgrade"))
 
-    return Object.assign(tag, { [TypeId]: TypeId, definition, upgrade }) as never
+    const layer = Binding.layer(tag, ["getByName"])
+
+    return Object.assign(tag, { definition, upgrade, layer }) as never
   }
diff --git a/liminal-cloudflare/asset_forwarding.ts b/liminal-cloudflare/asset_forwarding.ts
@@ -1,7 +1,7 @@
 import { Effect, Layer } from "effect"
 import { HttpServerResponse } from "effect/unstable/http"
 
-import { Assets } from "./bindings/Assets.ts"
+import * as Assets from "./bindings/Assets.ts"
 import * as Worker from "./bindings/Worker.ts"
 
 export default Worker.make({
diff --git a/liminal-cloudflare/bindings/Ai.ts b/liminal-cloudflare/bindings/Ai.ts
@@ -1,3 +1,7 @@
-import { Binding } from "./Binding.ts"
+import { Context } from "effect"
 
-export class Ai extends Binding<Ai>()("liminal/cloudflare/Ai", (v): v is globalThis.Ai => "run" in v) {}
+import * as Binding from "./Binding.ts"
+
+export class Ai extends Context.Service<Ai, globalThis.Ai>()("liminal/cloudflare/Ai") {}
+
+export const layer = Binding.layer(Ai, ["run"])
diff --git a/liminal-cloudflare/bindings/Assets.ts b/liminal-cloudflare/bindings/Assets.ts
@@ -1,17 +1,21 @@
-import { Effect } from "effect"
+import { Effect, Context } from "effect"
 import { HttpServerResponse } from "effect/unstable/http"
 
-import { Binding } from "./Binding.ts"
+import * as Binding from "./Binding.ts"
 import { NativeRequest } from "./NativeRequest.ts"
 
-export class Assets extends Binding<Assets>()(
-  "liminal/cloudflare/Assets",
-  (value): value is { fetch: typeof fetch } => "fetch" in value,
-) {
-  static readonly forward = Effect.gen({ self: this }, function* () {
-    const assets = yield* this
-    const request = yield* NativeRequest
-    const response = yield* Effect.promise(() => assets.fetch(request))
-    return HttpServerResponse.fromWeb(response)
-  })
-}
+export class Assets extends Context.Service<
+  Assets,
+  {
+    readonly fetch: typeof fetch
+  }
+>()("liminal/cloudflare/Assets") {}
+
+export const layer = Binding.layer(Assets, ["fetch"])
+
+export const forward = Effect.gen({ self: this }, function* () {
+  const assets = yield* Assets
+  const request = yield* NativeRequest
+  const response = yield* Effect.promise(() => assets.fetch(request))
+  return HttpServerResponse.fromWeb(response)
+})
diff --git a/liminal-cloudflare/bindings/Binding.ts b/liminal-cloudflare/bindings/Binding.ts
@@ -1,42 +1,40 @@
 import { env } from "cloudflare:workers"
-import { Data, Context, Layer, Effect } from "effect"
+import { Context, Layer, Effect, Schema as S, SchemaIssue } from "effect"
 
-const TypeId = "~liminal/cloudflare/Binding" as const
-
-export class BindingMissingError extends Data.TaggedError("BindingMissingError")<{
-  readonly missing: string
-}> {}
-
-export class BindingInvalidError extends Data.TaggedError("BindingInvalidError")<{
-  readonly invalid: string
-}> {}
-
-export interface Binding<Self, Id extends string, A, ROut, E, RIn> extends Context.Service<Self, A> {
-  new (_: never): Context.ServiceClass.Shape<Id, A>
-
-  readonly [TypeId]: typeof TypeId
-
-  readonly layer: (binding: string) => Layer.Layer<Self | ROut, BindingMissingError | BindingInvalidError | E, RIn>
-}
-
-export const Binding =
-  <Self>() =>
-  <Id extends string, A extends object, ROut = never, E = never, RIn = never>(
-    id: Id,
-    is: (value: object) => value is A,
-    makeLayer: (resource: A) => Layer.Layer<ROut, E, RIn> = () => Layer.empty as never,
-  ): Binding<Self, Id, A, ROut, E, RIn> => {
-    const tag = Context.Service<Self, A>()(id)
-    const layer = (binding: string) =>
-      Effect.gen(function* () {
-        const v = (env as never)[binding]
-        if (!v) {
-          return yield* new BindingMissingError({ missing: binding })
-        }
-        if (!is(v)) {
-          return yield* new BindingInvalidError({ invalid: binding })
+export const layer =
+  <Self, Identifier extends string, Shape, ROut = never, E = never, RIn = never>(
+    tag: Context.ServiceClass<Self, Identifier, Shape>,
+    keys: ReadonlyArray<string>,
+    derive?: (resource: Shape) => Layer.Layer<ROut, E, RIn> | undefined,
+  ) =>
+  (binding: string) =>
+    Effect.gen(function* () {
+      const resolved = (env as never)[binding]
+      if (!resolved) {
+        return yield* Effect.fail(
+          new S.SchemaError(
+            new SchemaIssue.Pointer(
+              [binding],
+              new SchemaIssue.MissingKey({
+                messageMissingKey: `Missing binding "${binding}" on env`,
+              }),
+            ),
+          ),
+        )
+      }
+      for (const key of keys) {
+        if (!(key in resolved)) {
+          return yield* Effect.fail(
+            new S.SchemaError(
+              new SchemaIssue.Pointer(
+                [key],
+                new SchemaIssue.MissingKey({
+                  messageMissingKey: `Expected key \`${key}\` on binding \`${binding}\``,
+                }),
+              ),
+            ),
+          )
         }
-        return Layer.mergeAll(Layer.succeed(tag, v), makeLayer(v))
-      }).pipe(Layer.unwrap)
-    return Object.assign(tag, { [TypeId]: TypeId, layer })
-  }
+      }
+      return Layer.mergeAll(Layer.succeed(tag, resolved), derive?.(resolved) ?? Layer.empty)
+    }).pipe(Layer.unwrap)
diff --git a/liminal-cloudflare/bindings/D1.ts b/liminal-cloudflare/bindings/D1.ts
@@ -1,9 +1,8 @@
 import { D1Client } from "@effect/sql-d1"
+import { Context } from "effect"
 
-import { Binding } from "./Binding.ts"
+import * as Binding from "./Binding.ts"
 
-export class D1 extends Binding<D1>()(
-  "liminal/cloudflare/D1",
-  (v): v is D1Database => "exec" in v,
-  (db) => D1Client.layer({ db }),
-) {}
+export class D1 extends Context.Service<D1, D1Database>()("liminal/bindings/D1") {}
+
+export const layer = Binding.layer(D1, ["exec"], (db) => D1Client.layer({ db }))
diff --git a/liminal-cloudflare/bindings/DoState.ts b/liminal-cloudflare/bindings/DoState.ts
@@ -0,0 +1,5 @@
+import { Context } from "effect"
+
+export class DoState extends Context.Service<DoState, globalThis.DurableObjectState<{}>>()(
+  "liminal/cloudflare/DoState",
+) {}
diff --git a/liminal-cloudflare/bindings/DurableObjectState.ts b/liminal-cloudflare/bindings/DurableObjectState.ts
diff --git a/liminal-cloudflare/bindings/ExecutionContext.ts b/liminal-cloudflare/bindings/ExecutionContext.ts
diff --git a/liminal-cloudflare/bindings/Hyperdrive.ts b/liminal-cloudflare/bindings/Hyperdrive.ts
@@ -1,12 +1,13 @@
-import { Effect, Redacted } from "effect"
-
-import { Binding } from "./Binding.ts"
-
-export class Hyperdrive extends Binding<Hyperdrive>()(
-  "liminal/cloudflare/Hyperdrive",
-  (v): v is globalThis.Hyperdrive => "connectionString" in v,
-) {
-  static readonly connectionString: Effect.Effect<Redacted.Redacted<string>, never, Hyperdrive> = this.asEffect().pipe(
-    Effect.map(({ connectionString }) => Redacted.make(connectionString)),
-  )
-}
+import { Effect, Redacted, Context } from "effect"
+
+import * as Binding from "./Binding.ts"
+
+export class Hyperdrive extends Context.Service<Hyperdrive, globalThis.Hyperdrive>()(
+  "liminal-cloudflare/bindings/Hyperdrive",
+) {}
+
+export const layer = Binding.layer(Hyperdrive, ["connectionString"])
+
+export const connectionString = Hyperdrive.asEffect().pipe(
+  Effect.map(({ connectionString }) => Redacted.make(connectionString)),
+)
diff --git a/liminal-cloudflare/bindings/Kv.ts b/liminal-cloudflare/bindings/Kv.ts
diff --git a/liminal-cloudflare/bindings/R2.ts b/liminal-cloudflare/bindings/R2.ts
diff --git a/liminal-cloudflare/bindings/Worker.ts b/liminal-cloudflare/bindings/Worker.ts
diff --git a/liminal-cloudflare/bindings/WorkerLoader.ts b/liminal-cloudflare/bindings/WorkerLoader.ts
diff --git a/liminal-cloudflare/bindings/index.ts b/liminal-cloudflare/bindings/index.ts
