@effect/platform-cloudflare 0.0.0 → 4.1.3

package/ai-docs/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../tsconfig.base.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    "composite": false,
+    "incremental": false,
+    "types": ["node"],
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "effectFn": ["untraced"],
+        "namespaceImportPackages": [],
+        "diagnosticSeverity": {
+          "floatingEffect": "off",
+          "globalJson": "off",
+          "globalJsonInEffect": "off",
+          "unstableApiUsage": "off",
+          "effectFnOpportunity": "error"
+        }
+      }
+    ]
+  }
+}

package/dist/AlchemyCloudflareCluster.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Deploys the Cloudflare cluster with Alchemy v2 ("Infrastructure as
+ * Effects").
+ *
+ * `make` runs inside an Effect-native `Cloudflare.Worker` init program. It
+ * registers the four cluster Durable Object classes on the hosting Worker
+ * (bindings, class exports, and SQLite migrations are all owned by Alchemy),
+ * builds the cluster layer together with the user's handler layer into the
+ * isolate-lifetime scope, and returns a handle for wiring the built context
+ * into the Worker's handlers. The user never declares or re-exports Durable
+ * Object classes.
+ *
+ * The Wrangler path (`CloudflareDurableObjects` + `CloudflareCluster.layer`)
+ * never imports this module; `@alchemy.run/cloudflare` is an optional peer
+ * dependency needed only here.
+ *
+ * **Example** (Declaring a cluster)
+ *
+ * ```ts
+ * import * as Cloudflare from "@alchemy.run/cloudflare"
+ * import { Effect, Layer } from "effect"
+ * import { make } from "@effect/platform-cloudflare/AlchemyCloudflareCluster"
+ * import { CloudflareCluster } from "@effect/platform-cloudflare"
+ *
+ * export default Cloudflare.Worker("MyApp", {
+ *   main: import.meta.url
+ * }, Effect.gen(function*() {
+ *   const cluster = yield* make({
+ *     entities: [Counter],
+ *     layer: Layer.mergeAll(CounterLayer, MaintenanceLayer, NightlyReport)
+ *   })
+ *
+ *   yield* Cloudflare.Workers.cron("0 * * * *", cluster.wake("hourly-maintenance"))
+ *   // A ClusterCron fires only after a Cron Trigger wakes its seed singleton
+ *   yield* Cloudflare.Workers.cron(
+ *     "30 * * * *",
+ *     cluster.wake(CloudflareCluster.clusterCronSingletonName("nightly-report"))
+ *   )
+ *
+ *   return {
+ *     fetch: cluster.provide(handler)
+ *   }
+ * }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)))
+ * ```
+ *
+ * @stability experimental
+ * @since 4.1.3
+ */
+import * as Cloudflare from "@alchemy.run/cloudflare";
+import type * as Entity from "effect/cluster/Entity";
+import type { Sharding } from "effect/cluster/Sharding";
+import type * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import type { PersistedQueueFactory } from "effect/persistence/PersistedQueue";
+import type { WorkflowEngine } from "effect/workflow/WorkflowEngine";
+import type { Cluster } from "./internal/cluster.ts";
+declare global {
+    var __ALCHEMY_RUNTIME__: boolean | undefined;
+}
+/**
+ * The services `make` builds on top of the user layer: the cluster `Sharding`
+ * service, the workflow engine, and the persisted queue factory.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.1.3
+ */
+export type ClusterServices = Sharding | WorkflowEngine | PersistedQueueFactory;
+export type { 
+/**
+ * The handle returned by {@link make}.
+ *
+ * **Gotchas**
+ *
+ * Namespace bindings and `context` are available only in the deployed runtime.
+ * Reading them during plan evaluation throws a diagnostic; `provide` and
+ * `wake` remain inert during planning.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.1.3
+ */
+Cluster } from "./internal/cluster.ts";
+/**
+ * The entity definitions and handler layer the cluster is built from.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.1.3
+ */
+export interface MakeOptions<ROut, E, RIn> {
+    /**
+     * The complete set of entity definitions the Worker serves, as in
+     * `CloudflareCluster.LayerOptions`.
+     */
+    readonly entities: ReadonlyArray<Entity.Entity<any, any>>;
+    /**
+     * The user's merged handler layers: entity handlers, singletons, workflow
+     * handlers, and any services they need.
+     */
+    readonly layer: Layer.Layer<ROut, E, RIn>;
+    /**
+     * Interval of the entity keep-alive heartbeat alarm, as in
+     * `CloudflareCluster.LayerOptions`. Defaults to 30 seconds.
+     */
+    readonly keepAliveHeartbeat?: Duration.Input | undefined;
+}
+/**
+ * Builds the Cloudflare cluster inside an Effect-native Alchemy Worker.
+ *
+ * **Details**
+ *
+ * Always registers all four Durable Object classes (entity, workflow, durable
+ * queue, singleton) on the hosting Worker, so Alchemy owns their bindings and
+ * SQLite migrations across deploys. At runtime it builds
+ * `CloudflareCluster.layer` merged with the user's handler layer into the
+ * isolate-lifetime Scope — the Scope is never closed, so do not wrap the
+ * Worker init program in `Effect.provide(layer)` for cluster services.
+ *
+ * The returned handle exposes `provide` for the Worker's handlers, `wake` for
+ * user-declared Cron Triggers
+ * (`Cloudflare.Workers.cron(expr, cluster.wake("name"))`), and the four
+ * native namespace bindings as escape hatches.
+ *
+ * A `ClusterCron` fires only after a Cron Trigger wakes its seed singleton.
+ * Pass `CloudflareCluster.clusterCronSingletonName(name)` to `wake` for it.
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.1.3
+ */
+export declare const make: <ROut, E, RIn>(options: MakeOptions<ROut, E, RIn>) => Effect.Effect<Cluster<ROut | ClusterServices>, E, Cloudflare.Worker | Exclude<RIn, ClusterServices>>;
+//# sourceMappingURL=AlchemyCloudflareCluster.d.ts.map

package/dist/AlchemyCloudflareCluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlchemyCloudflareCluster.d.ts","sourceRoot":"","sources":["../src/AlchemyCloudflareCluster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,UAAU,MAAM,yBAAyB,CAAA;AACrD,OAAO,KAAK,KAAK,MAAM,MAAM,uBAAuB,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACvD,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AASpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAEpD,OAAO,CAAC,MAAM,CAAC;IAGb,IAAI,mBAAmB,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,cAAc,GAAG,qBAAqB,CAAA;AAE/E,YAAY;AACV;;;;;;;;;;;;GAYG;AACH,OAAO,EACR,MAAM,uBAAuB,CAAA;AAE9B;;;;;;GAMG;AACH,MAAM,WAAW,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG;IACvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACzD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACzD;AA+CD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAC9B,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,KAC/B,MAAM,CAAC,MAAM,CAChB,OAAO,CAAC,IAAI,GAAG,eAAe,CAAC,EAC/B,CAAC,EACD,UAAU,CAAC,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,CAC9B,CAAA"}

package/dist/AlchemyCloudflareCluster.js

@@ -0,0 +1,111 @@
+/**
+ * Deploys the Cloudflare cluster with Alchemy v2 ("Infrastructure as
+ * Effects").
+ *
+ * `make` runs inside an Effect-native `Cloudflare.Worker` init program. It
+ * registers the four cluster Durable Object classes on the hosting Worker
+ * (bindings, class exports, and SQLite migrations are all owned by Alchemy),
+ * builds the cluster layer together with the user's handler layer into the
+ * isolate-lifetime scope, and returns a handle for wiring the built context
+ * into the Worker's handlers. The user never declares or re-exports Durable
+ * Object classes.
+ *
+ * The Wrangler path (`CloudflareDurableObjects` + `CloudflareCluster.layer`)
+ * never imports this module; `@alchemy.run/cloudflare` is an optional peer
+ * dependency needed only here.
+ *
+ * **Example** (Declaring a cluster)
+ *
+ * ```ts
+ * import * as Cloudflare from "@alchemy.run/cloudflare"
+ * import { Effect, Layer } from "effect"
+ * import { make } from "@effect/platform-cloudflare/AlchemyCloudflareCluster"
+ * import { CloudflareCluster } from "@effect/platform-cloudflare"
+ *
+ * export default Cloudflare.Worker("MyApp", {
+ *   main: import.meta.url
+ * }, Effect.gen(function*() {
+ *   const cluster = yield* make({
+ *     entities: [Counter],
+ *     layer: Layer.mergeAll(CounterLayer, MaintenanceLayer, NightlyReport)
+ *   })
+ *
+ *   yield* Cloudflare.Workers.cron("0 * * * *", cluster.wake("hourly-maintenance"))
+ *   // A ClusterCron fires only after a Cron Trigger wakes its seed singleton
+ *   yield* Cloudflare.Workers.cron(
+ *     "30 * * * *",
+ *     cluster.wake(CloudflareCluster.clusterCronSingletonName("nightly-report"))
+ *   )
+ *
+ *   return {
+ *     fetch: cluster.provide(handler)
+ *   }
+ * }).pipe(Effect.provide(Cloudflare.Workers.CronEventSourceLive)))
+ * ```
+ *
+ * @stability experimental
+ * @since 4.1.3
+ */
+import * as Cloudflare from "@alchemy.run/cloudflare";
+import * as Effect from "effect/Effect";
+import { makeClusterDurableQueueProgram, makeClusterEntityProgram, makeClusterSingletonProgram, makeClusterWorkflowProgram } from "./CloudflareDurableObjectPrograms.js";
+import { inertClusterHandle, makeClusterHandle } from "./internal/alchemyCluster.js";
+// One alchemy Durable Object class per cluster program. The outer effect
+// resolves the instance state; the inner effect runs per activation, under
+// alchemy's blockConcurrencyWhile, once the shared isolate init (and so the
+// user's handler registrations) has completed. The program handle is the RPC
+// shape: every method returns an Effect and `alarm` matches alchemy's hook.
+// `fetch` is omitted on purpose: cluster RPCs use the native bindings, so
+// alchemy's default 404 stands in for the Wrangler classes' rejection.
+const durableObject = (className, program) => Cloudflare.DurableObject()(className, Effect.map(Cloudflare.DurableObjectState, state => program(state.raw)));
+const ClusterEntity = /*#__PURE__*/durableObject("ClusterEntity", makeClusterEntityProgram);
+const ClusterWorkflow = /*#__PURE__*/durableObject("ClusterWorkflow", makeClusterWorkflowProgram);
+const ClusterDurableQueue = /*#__PURE__*/durableObject("ClusterDurableQueue", makeClusterDurableQueueProgram);
+const ClusterSingleton = /*#__PURE__*/durableObject("ClusterSingleton", makeClusterSingletonProgram);
+const makeUnsafe = /*#__PURE__*/Effect.fnUntraced(function* (options) {
+  // Register the four Durable Object classes on the hosting Worker. At plan
+  // time this declares the bindings and class exports Alchemy deploys; at
+  // runtime it resolves the same bindings in every isolate, Worker and
+  // Durable Object alike.
+  yield* ClusterEntity;
+  yield* ClusterWorkflow;
+  yield* ClusterDurableQueue;
+  yield* ClusterSingleton;
+  if (!globalThis.__ALCHEMY_RUNTIME__) {
+    // Plan/deploy evaluation only discovers the declarations above.
+    return inertClusterHandle();
+  }
+  const env = yield* Cloudflare.WorkerEnvironment;
+  return yield* makeClusterHandle({
+    entities: options.entities,
+    layer: options.layer,
+    env,
+    keepAliveHeartbeat: options.keepAliveHeartbeat
+  });
+});
+/**
+ * Builds the Cloudflare cluster inside an Effect-native Alchemy Worker.
+ *
+ * **Details**
+ *
+ * Always registers all four Durable Object classes (entity, workflow, durable
+ * queue, singleton) on the hosting Worker, so Alchemy owns their bindings and
+ * SQLite migrations across deploys. At runtime it builds
+ * `CloudflareCluster.layer` merged with the user's handler layer into the
+ * isolate-lifetime Scope — the Scope is never closed, so do not wrap the
+ * Worker init program in `Effect.provide(layer)` for cluster services.
+ *
+ * The returned handle exposes `provide` for the Worker's handlers, `wake` for
+ * user-declared Cron Triggers
+ * (`Cloudflare.Workers.cron(expr, cluster.wake("name"))`), and the four
+ * native namespace bindings as escape hatches.
+ *
+ * A `ClusterCron` fires only after a Cron Trigger wakes its seed singleton.
+ * Pass `CloudflareCluster.clusterCronSingletonName(name)` to `wake` for it.
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.1.3
+ */
+export const make = makeUnsafe;
+//# sourceMappingURL=AlchemyCloudflareCluster.js.map

package/dist/AlchemyCloudflareCluster.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlchemyCloudflareCluster.js","names":[],"sources":["../src/AlchemyCloudflareCluster.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,OAAO,KAAK,UAAU,MAAM,yBAAyB;AAIrD,OAAO,KAAK,MAAM,MAAM,eAAe;AAIvC,SAEE,8BAA8B,EAC9B,wBAAwB,EACxB,2BAA2B,EAC3B,0BAA0B,QACrB,sCAAsC;AAC7C,SAAS,kBAAkB,EAAE,iBAAiB,QAAQ,8BAA8B;AA6DpF;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAM,aAAa,GAAG,CACpB,SAAiB,EACjB,OAAmE,KAEnE,UAAU,CAAC,aAAa,EAAS,CAC/B,SAAS,EACT,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,kBAAkB,EAAG,KAAK,IAAK,OAAO,CAAC,KAAK,CAAC,GAAgC,CAAC,CAAC,CACtG;AAEH,MAAM,aAAa,gBAAG,aAAa,CAAC,eAAe,EAAE,wBAAwB,CAAC;AAC9E,MAAM,eAAe,gBAAG,aAAa,CAAC,iBAAiB,EAAE,0BAA0B,CAAC;AACpF,MAAM,mBAAmB,gBAAG,aAAa,CAAC,qBAAqB,EAAE,8BAA8B,CAAC;AAChG,MAAM,gBAAgB,gBAAG,aAAa,CAAC,kBAAkB,EAAE,2BAA2B,CAAC;AAEvF,MAAM,UAAU,gBAAG,MAAM,CAAC,UAAU,CAAC,WAAU,OAAmC;EAChF;EACA;EACA;EACA;EACA,OAAO,aAAa;EACpB,OAAO,eAAe;EACtB,OAAO,mBAAmB;EAC1B,OAAO,gBAAgB;EAEvB,IAAI,CAAC,UAAU,CAAC,mBAAmB,EAAE;IACnC;IACA,OAAO,kBAAkB,EAAE;EAC7B;EAEA,MAAM,GAAG,GAAG,OAAO,UAAU,CAAC,iBAAiB;EAC/C,OAAO,OAAO,iBAAiB,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;IAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;IACpB,GAAG;IACH,kBAAkB,EAAE,OAAO,CAAC;GAC7B,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,MAAM,IAAI,GAMb,UAAiB","ignoreList":[]}

package/dist/CloudflareCluster.d.ts

@@ -0,0 +1,196 @@
+import type * as Entity from "effect/cluster/Entity";
+import { Sharding } from "effect/cluster/Sharding";
+import * as Context from "effect/Context";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { PersistedQueueFactory } from "effect/persistence/PersistedQueue";
+import type * as SqlClient from "effect/sql/SqlClient";
+import type { WorkflowEngine } from "effect/workflow/WorkflowEngine";
+/**
+ * A Durable Object name decoded back into its entity address parts.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.1.3
+ */
+export interface ClusterName {
+    readonly type: string;
+    readonly id: string;
+}
+/**
+ * Encodes an entity address into the Durable Object name used with
+ * `getByName`.
+ *
+ * **Details**
+ *
+ * The name is the entity type length-prefixed as `` `${type.length}:${type}${id}` ``,
+ * which keeps `(type, id)` pairs collision-free without restricting the
+ * characters an entity id may contain. Workflow, queue, and singleton names use
+ * the same scheme on their own namespaces.
+ *
+ * @stability experimental
+ * @category encoding
+ * @since 4.1.3
+ */
+export declare const encodeName: (type: string, id: string) => string;
+/**
+ * Decodes a Durable Object name produced by {@link encodeName} back into its
+ * entity address parts.
+ *
+ * **Details**
+ *
+ * Returns `undefined` for names that were not produced by {@link encodeName},
+ * including non-canonical length prefixes. A Durable Object uses this to
+ * recover its own address from `ctx.id.name`.
+ *
+ * @stability experimental
+ * @category decoding
+ * @since 4.1.3
+ */
+export declare const decodeName: (name: string) => ClusterName | undefined;
+/**
+ * Returns the singleton name of the seed singleton that `ClusterCron.make`
+ * registers for the cron job with the given name.
+ *
+ * **When to use**
+ *
+ * Use to wake a `ClusterCron` from a Worker Cron Trigger, by passing the
+ * result to `cluster.wake` with Alchemy or by prefixing it with `Singleton/`
+ * for `getByName` on the singleton namespace with Wrangler.
+ *
+ * **Details**
+ *
+ * The result is `"ClusterCron/<name>"`, the singleton name without the
+ * `Singleton/` Durable Object name prefix.
+ *
+ * **Gotchas**
+ *
+ * A singleton runs only when its Durable Object is woken, so a `ClusterCron`
+ * never schedules its first run until a Cron Trigger wakes this singleton.
+ * Each later run is scheduled through a destination alarm.
+ *
+ * @stability experimental
+ * @category encoding
+ * @since 4.1.3
+ */
+export declare const clusterCronSingletonName: (name: string) => string;
+/**
+ * The Durable Object namespace bindings and entity definitions the cluster
+ * layer is built from.
+ *
+ * **Details**
+ *
+ * `entities` is the complete set of entity definitions the Worker serves.
+ * Handlers are attached per entity type with `Entity.toLayer`; a client or
+ * handler registration for an entity type outside this set fails at the
+ * Worker, before any Durable Object is contacted.
+ *
+ * `keepAliveHeartbeat` (default 30 seconds) is the interval of the alarm an
+ * entity Durable Object keeps armed while it holds `Entity.keepAlive` or runs
+ * a persisted request. Cloudflare never re-creates an evicted object on its
+ * own, so this alarm is what rebuilds a kept-alive entity and replays an
+ * interrupted request after a restart or deploy. It bounds recovery latency;
+ * it is not a liveness check.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.1.3
+ */
+export interface LayerOptions {
+    readonly entities: ReadonlyArray<Entity.Entity<any, any>>;
+    readonly entityNamespace: DurableObjectNamespace;
+    readonly workflowNamespace: DurableObjectNamespace;
+    readonly queueNamespace: DurableObjectNamespace;
+    readonly singletonNamespace: DurableObjectNamespace;
+    readonly keepAliveHeartbeat?: Duration.Input | undefined;
+}
+/**
+ * Builds the cluster on Cloudflare Durable Objects.
+ *
+ * **Details**
+ *
+ * Provides the cluster `Sharding` service on top of the four same-Worker
+ * Durable Object namespace bindings, plus the `WorkflowEngine` backed by the
+ * workflow class and the `PersistedQueueFactory` backed by the queue class, so
+ * the `DurableQueue` user API works out of the box. `Entity.client` resolves
+ * an entity to its Durable Object by
+ * encoding `(type, id)` with {@link encodeName} and calling `getByName`; an
+ * unknown entity type or a bad encode fails at the Worker before any Durable
+ * Object is contacted. Entity handlers registered with `Entity.toLayer` are
+ * recorded per `EntityType` at Worker init and built once per Durable Object
+ * wake; workflow handlers registered with `Workflow.toLayer` follow the same
+ * pattern on the workflow class.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.1.3
+ */
+export declare const layer: (options: LayerOptions) => Layer.Layer<Sharding | WorkflowEngine | PersistedQueueFactory>;
+declare const DurableObjectSqlClient_base: Context.ServiceClass<DurableObjectSqlClient, "@effect/platform-cloudflare/CloudflareCluster/DurableObjectSqlClient", SqlClient.SqlClient>;
+/**
+ * An `SqlClient` on the current entity Durable Object's own SQLite storage.
+ *
+ * **When to use**
+ *
+ * Use to keep rows next to the entity's mailbox from an entity handler build
+ * or handler, such as state that must survive eviction and commit atomically
+ * with each step. Register the handlers with `Entity.toLayer` and read the
+ * client with {@link DurableObjectSqlClient.orDie} in the build.
+ *
+ * **Details**
+ *
+ * Each entity Durable Object provides this service, an `@effect/sql-sqlite-do`
+ * client, to its handler build and handlers, including handlers registered
+ * with `Entity.toLayerQueue`. Yielding the tag directly leaves it as a layer
+ * requirement; `orDie` has none. It is a separate tag, so any
+ * `SqlClient` from the Worker layer (a D1 database, say) stays reachable inside
+ * the handlers. To run code written against `SqlClient.SqlClient`, provide this
+ * client as that service locally.
+ *
+ * `withTransaction` uses the object's storage transaction, so several rows
+ * commit or roll back together. Rows live and die with the entity's Durable
+ * Object and cannot be queried from outside it.
+ *
+ * **Gotchas**
+ *
+ * - Outside an entity Durable Object, `orDie` dies on the first handler build.
+ *   In tests, provide this service from any SQL layer.
+ * - Table names starting with `cluster_` are reserved for the entity mailbox.
+ * - A row, like an encoded message, cannot exceed 2 MB.
+ * - A storage transaction closes the Durable Object's input gate until it
+ *   finishes, so timers and I/O awaited inside `withTransaction` never
+ *   resume. Keep transactions to SQL work.
+ * - Mailbox writes wait for an open transaction to finish, so a rollback never
+ *   takes another handler's stored reply with it.
+ *
+ * **Example** (Storing rows from entity handlers)
+ *
+ * ```ts
+ * import { CloudflareCluster } from "@effect/platform-cloudflare"
+ * import { Effect } from "effect"
+ *
+ * const JournalLayer = Journal.toLayer(Effect.gen(function*() {
+ *   const sql = yield* CloudflareCluster.DurableObjectSqlClient.orDie
+ *   yield* sql`CREATE TABLE IF NOT EXISTS journal (entry TEXT NOT NULL)`.pipe(Effect.orDie)
+ *   return Journal.of({
+ *     Append: ({ payload }) => sql`INSERT INTO journal (entry) VALUES (${payload.entry})`.pipe(Effect.orDie)
+ *   })
+ * }))
+ * ```
+ *
+ * @stability experimental
+ * @category services
+ * @since 4.1.3
+ */
+export declare class DurableObjectSqlClient extends DurableObjectSqlClient_base {
+    /**
+     * Gets the current entity's SQL client, or dies if no client is provided.
+     *
+     * @stability experimental
+     * @since 4.1.3
+     */
+    static readonly orDie: Effect.Effect<SqlClient.SqlClient>;
+}
+export {};
+//# sourceMappingURL=CloudflareCluster.d.ts.map

package/dist/CloudflareCluster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudflareCluster.d.ts","sourceRoot":"","sources":["../src/CloudflareCluster.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAKpD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAClD,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAO9E,OAAO,KAAK,KAAK,SAAS,MAAM,sBAAsB,CAAA;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAepE;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,MAA4B,CAAA;AAEnF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,SAA+B,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,SAAU,MAAM,KAAG,MAA+B,CAAA;AAEvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACzD,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAA;IAClD,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAA;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,sBAAsB,CAAA;IACnD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;CACzD;AAybD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,KAAK,YACP,YAAY,KACpB,KAAK,CAAC,KAAK,CAAC,QAAQ,GAAG,cAAc,GAAG,qBAAqB,CAK7D,CAAA;;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,qBAAa,sBAAuB,SAAQ,2BAE3C;IACC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAWxD;CACF"}