@alchemy.run/modal 0.0.0 → 2.0.0-beta.87

package/src/Queue.ts

@@ -0,0 +1,258 @@
+import * as queue from "@distilled.cloud/modal/queue";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import {
+  type EnvironmentInput,
+  envNameOf,
+  environmentNames,
+  environmentOf,
+  isGeneratedName,
+  listAll,
+  objectName,
+} from "./internal.ts";
+import { declarable } from "./internal/Declared.ts";
+import type { Providers } from "./Providers.ts";
+import { isRuntimeName } from "./RuntimeOwner.ts";
+
+export class QueueUnexpectedResponse extends Data.TaggedError("Modal.QueueUnexpectedResponse")<{
+  readonly message: string;
+}> {}
+
+export interface QueueProps {
+  /**
+   * Queue name, unique per environment. If omitted, a unique name is
+   * generated from the stack, stage and logical ID. Changing it replaces the
+   * queue (Modal can't rename queues).
+   */
+  name?: string;
+  /**
+   * Environment the queue lives in. Changing it replaces the queue.
+   * @default the workspace's default environment
+   */
+  environment?: EnvironmentInput;
+}
+
+export interface QueueAttributes {
+  /** Queue ID (`qu-…`). */
+  queueId: string;
+  /** Queue name. */
+  name: string;
+  /** Environment name, or `undefined` for the workspace default. */
+  environment: string | undefined;
+}
+
+/**
+ * A Modal Queue: a distributed FIFO queue shared by every container, Sandbox
+ * and client in the workspace, with optional named partitions. Items expire
+ * 24 hours after they are put (partitions can set their own TTL).
+ *
+ * Bind it with {@link WriteQueue} to put items, {@link ReadQueue} to take
+ * them, or {@link ReadWriteQueue} for both, from a Worker, Lambda or any
+ * other runtime. Values travel as bytes: the bindings encode them as JSON by
+ * default.
+ *
+ * Modal queues have no tags. Ownership is inferred from Alchemy state: a
+ * queue found under an explicit `name` without prior state is reported as
+ * unowned.
+ *
+ * ### Creating a Queue
+ * **Example:** A queue with a generated name
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Jobs = Modal.Queue("Jobs", {});
+ * ```
+ *
+ * **Example:** A named queue in an environment
+ * ```typescript
+ * import * as Modal from "@alchemy.run/modal";
+ *
+ * export const Agents = Modal.Environment("Agents", {});
+ * export const Tasks = Modal.Queue("Tasks", { name: "tasks", environment: Agents });
+ * ```
+ *
+ * ### Producing from a Worker
+ * **Example:** Bind write access and put a job
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Jobs } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const jobs = yield* Modal.WriteQueue(Jobs);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* jobs.put({ repo: "alchemy-run/alchemy", command: "pnpm test" });
+ *         return HttpServerResponse.text("queued");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.WriteQueueHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Looking up an existing queue
+ * `Queue.lookup` references a queue Alchemy doesn't manage (created with
+ * the Modal CLI or by another stack). It is read during plan/deploy, never
+ * created, updated or deleted.
+ *
+ * **Example:** Reference an existing queue
+ * ```typescript
+ * const jobs = Modal.Queue.lookup({ name: "jobs" });
+ * ```
+ *
+ * @resource
+ * @product Queue
+ */
+export const Queue = declarable<Queue>()(Resource<Queue>("Modal.Queue"));
+
+export type Queue = Resource<
+  "Modal.Queue",
+  QueueProps,
+  QueueAttributes,
+  never,
+  Providers,
+  QueueLookup
+>;
+
+/**
+ * Props for {@link Queue.lookup}: find a queue this stack
+ * doesn't manage by its name.
+ */
+export interface QueueLookup {
+  /** Queue name. */
+  name: string;
+  /**
+   * Modal environment the object lives in.
+   * @default the workspace's default environment
+   */
+  environment?: string;
+}
+
+/** A queue by name, or `undefined` when missing. */
+export const lookupQueue = Effect.fn(function* (
+  getOrCreate: Effect.Success<typeof queue.queueGetOrCreate>,
+  name: string,
+  env: string | undefined,
+) {
+  const found = yield* getOrCreate({
+    deploymentName: name,
+    environmentName: environmentOf(env),
+    objectCreationType: "OBJECT_CREATION_TYPE_UNSPECIFIED",
+  }).pipe(Effect.catchTag("QueueNotFound", () => Effect.undefined));
+  if (!found?.queueId) return undefined;
+  return { queueId: found.queueId, name, environment: env } satisfies QueueAttributes;
+});
+
+/**
+ * Get a queue by name, creating it when missing: the one implementation behind
+ * {@link Queue}'s reconcile and the runtime {@link CreateQueue} client.
+ */
+export const ensureQueue = Effect.fn(function* (
+  getOrCreate: Effect.Success<typeof queue.queueGetOrCreate>,
+  name: string,
+  env: string | undefined,
+) {
+  const created = yield* getOrCreate({
+    deploymentName: name,
+    environmentName: environmentOf(env),
+    objectCreationType: "OBJECT_CREATION_TYPE_CREATE_IF_MISSING",
+  });
+  if (!created.queueId) {
+    return yield* new QueueUnexpectedResponse({
+      message: `Modal returned no id for queue ${name}`,
+    });
+  }
+  return { queueId: created.queueId, name, environment: env } satisfies QueueAttributes;
+});
+
+export const QueueProvider = () =>
+  Provider.effect(
+    Queue,
+    Effect.gen(function* () {
+      const observe = Effect.fn(function* (
+        queueId: string | undefined,
+        name: string,
+        env: string | undefined,
+      ) {
+        if (queueId !== undefined) {
+          const byId = yield* queue
+            .queueGetById({ queueId })
+            .pipe(Effect.catchTag("QueueNotFound", () => Effect.undefined));
+          if (byId?.queueId) {
+            return {
+              queueId: byId.queueId,
+              name: byId.metadata?.name ?? name,
+              environment: env,
+            } satisfies QueueAttributes;
+          }
+        }
+        return yield* lookupQueue(yield* queue.queueGetOrCreate, name, env);
+      });
+
+      return {
+        stables: ["queueId", "name", "environment"],
+        diff: Effect.fn(function* ({ id, news, olds, output }) {
+          if (!isResolved(news)) return undefined;
+          if (envNameOf(news.environment) !== envNameOf(olds?.environment))
+            return { action: "replace" } as const;
+          const name = yield* objectName(id, news.name);
+          if (output !== undefined && name !== output.name) return { action: "replace" } as const;
+          return undefined;
+        }),
+        lookup: Effect.fn(function* ({ name, environment }) {
+          return yield* observe(undefined, name, environment);
+        }),
+
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.name ?? (yield* objectName(id, olds?.name));
+          const observed = yield* observe(output?.queueId, name, envNameOf(olds?.environment));
+          if (!observed) return undefined;
+          return output !== undefined || olds?.name === undefined ? observed : Unowned(observed);
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const name = output?.name ?? (yield* objectName(id, news.name));
+          const current = yield* observe(output?.queueId, name, envNameOf(news.environment));
+          if (current) return current;
+          yield* session.note(`Creating queue ${name}...`);
+          return yield* ensureQueue(
+            yield* queue.queueGetOrCreate,
+            name,
+            envNameOf(news.environment),
+          );
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* queue
+            .deleteQueue({ queueId: output.queueId })
+            .pipe(Effect.catchTag("QueueNotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+          const envs = yield* environmentNames;
+          const all: QueueAttributes[] = [];
+          for (const env of envs) {
+            const items = yield* listAll(
+              (pagination) =>
+                queue
+                  .listQueue({ environmentName: env, pagination })
+                  .pipe(Effect.map((response) => response.queues ?? [])),
+              (item) => item.createdAt,
+            );
+            for (const item of items) {
+              if (!item.queueId || !(isGeneratedName(item.name) || isRuntimeName(item.name)))
+                continue;
+              all.push({ queueId: item.queueId, name: item.name ?? "", environment: env });
+            }
+          }
+          return all;
+        }),
+      };
+    }),
+  );

package/src/QueueClient.ts

@@ -0,0 +1,149 @@
+import * as queue from "@distilled.cloud/modal/queue";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import { decodeJson, encodeJson, type ModalValueNotJson } from "./BindingHttp.ts";
+import { type OpError, operations, seconds } from "./internal.ts";
+
+/** The queue operations the clients call, resolved by `ModalBindings.withCredentials`. */
+export const QueueOps = operations({
+  clearQueue: queue.clearQueue,
+  getQueue: queue.getQueue,
+  putQueue: queue.putQueue,
+  queueLen: queue.queueLen,
+  queueNextItems: queue.queueNextItems,
+});
+
+export type QueueOps = Effect.Success<typeof QueueOps>;
+
+/** A queue call's error: the operation's typed errors, and items that aren't JSON. */
+export type QueueError<K extends keyof QueueOps> = OpError<QueueOps, K> | ModalValueNotJson;
+
+/** Which partition of a queue a call uses; omitted means the default partition. */
+export interface QueuePartitionOptions {
+  readonly partition?: string;
+}
+
+/**
+ * Take items from one queue. Items are JSON (the bytes of `JSON.stringify`),
+ * so Python consumers read them with `json.loads`.
+ */
+export interface ReadQueueClient {
+  readonly queueId: Effect.Effect<string>;
+  /**
+   * Remove and return up to `count` items, waiting up to `timeout` for the
+   * first one (an empty array when none arrived).
+   */
+  take<A = unknown>(
+    options?: QueuePartitionOptions & {
+      readonly count?: number;
+      readonly timeout?: number | string;
+    },
+  ): Effect.Effect<ReadonlyArray<A>, QueueError<"getQueue">, RuntimeContext>;
+  /** Items currently in the queue, without removing them. */
+  peek<A = unknown>(
+    options?: QueuePartitionOptions,
+  ): Effect.Effect<ReadonlyArray<A>, QueueError<"queueNextItems">, RuntimeContext>;
+  /** Number of items in a partition (or, with `total`, in every partition). */
+  len(
+    options?: QueuePartitionOptions & { readonly total?: boolean },
+  ): Effect.Effect<number, OpError<QueueOps, "queueLen">, RuntimeContext>;
+}
+
+/** Put items into one queue. */
+export interface WriteQueueClient {
+  readonly queueId: Effect.Effect<string>;
+  /** Append one item. */
+  put(
+    value: unknown,
+    options?: QueuePartitionOptions & { readonly partitionTtl?: number | string },
+  ): Effect.Effect<void, OpError<QueueOps, "putQueue">, RuntimeContext>;
+  /** Append many items in order. */
+  putMany(
+    values: Iterable<unknown>,
+    options?: QueuePartitionOptions & { readonly partitionTtl?: number | string },
+  ): Effect.Effect<void, OpError<QueueOps, "putQueue">, RuntimeContext>;
+  /** Remove every item of a partition (or of all partitions). */
+  clear(
+    options?: QueuePartitionOptions & { readonly all?: boolean },
+  ): Effect.Effect<void, OpError<QueueOps, "clearQueue">, RuntimeContext>;
+}
+
+/** Put and take items. */
+export interface ReadWriteQueueClient extends ReadQueueClient, WriteQueueClient {}
+
+export const makeReadQueueClient = (
+  queueId: Effect.Effect<string>,
+  ops: QueueOps,
+): ReadQueueClient => ({
+  queueId,
+  take: <A>(options: Parameters<ReadQueueClient["take"]>[0] = {}) =>
+    Effect.gen(function* () {
+      const id = yield* queueId;
+      const { values } = yield* ops.getQueue({
+        queueId: id,
+        partitionKey: options.partition,
+        nValues: options.count ?? 1,
+        timeout: seconds(options.timeout) ?? 0,
+      });
+      return yield* Effect.forEach(values ?? [], (value) => decodeJson<A>(value));
+    }),
+  peek: <A>(options: QueuePartitionOptions = {}) =>
+    Effect.gen(function* () {
+      const id = yield* queueId;
+      const { items } = yield* ops.queueNextItems({
+        queueId: id,
+        partitionKey: options.partition,
+        itemPollTimeout: 0,
+      });
+      return yield* Effect.forEach(items ?? [], (item) => decodeJson<A>(item.value ?? ""));
+    }),
+  len: (options = {}) =>
+    Effect.gen(function* () {
+      const id = yield* queueId;
+      const response = yield* ops.queueLen({
+        queueId: id,
+        partitionKey: options.partition,
+        total: options.total,
+      });
+      return response.len ?? 0;
+    }),
+});
+
+export const makeWriteQueueClient = (
+  queueId: Effect.Effect<string>,
+  ops: QueueOps,
+): WriteQueueClient => {
+  const putMany: WriteQueueClient["putMany"] = (values, options = {}) =>
+    Effect.gen(function* () {
+      const id = yield* queueId;
+      const encoded = yield* Effect.forEach([...values], (value) => encodeJson(value));
+      yield* ops.putQueue({
+        queueId: id,
+        values: encoded,
+        partitionKey: options.partition,
+        partitionTtlSeconds: seconds(options.partitionTtl),
+      });
+    });
+  return {
+    queueId,
+    put: (value, options) => putMany([value], options),
+    putMany,
+    clear: (options = {}) =>
+      Effect.gen(function* () {
+        const id = yield* queueId;
+        yield* ops.clearQueue({
+          queueId: id,
+          partitionKey: options.partition,
+          allPartitions: options.all,
+        });
+      }),
+  };
+};
+
+export const makeReadWriteQueueClient = (
+  queueId: Effect.Effect<string>,
+  ops: QueueOps,
+): ReadWriteQueueClient => ({
+  ...makeReadQueueClient(queueId, ops),
+  ...makeWriteQueueClient(queueId, ops),
+});

package/src/ReadApp.ts

@@ -0,0 +1,101 @@
+import type * as app from "@distilled.cloud/modal/app";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { App } from "./App.ts";
+import type { OpError } from "./internal.ts";
+import type { ReadAppOps } from "./ReadAppHttp.ts";
+import type { TimeRange } from "./ReadFunction.ts";
+
+/** One log line. */
+export interface AppLogLine {
+  readonly data: string;
+  /** Epoch seconds. */
+  readonly timestamp: number | undefined;
+  readonly stream: "stdout" | "stderr" | "info" | undefined;
+  readonly functionId: string | undefined;
+  readonly functionCallId: string | undefined;
+  readonly containerId: string | undefined;
+  readonly sandboxId: string | undefined;
+}
+
+/** Filters for an App's logs. */
+export interface AppLogFilter {
+  readonly functionId?: string;
+  readonly functionCallId?: string;
+  readonly containerId?: string;
+  readonly sandboxId?: string;
+  readonly search?: string;
+  readonly stream?: "stdout" | "stderr" | "info";
+}
+
+/** Observe an App: logs, functions, and deployment history. */
+export interface AppReader {
+  /** Log lines in a time range, oldest first. */
+  logs(
+    query: TimeRange & AppLogFilter & { readonly limit?: number },
+  ): Effect.Effect<ReadonlyArray<AppLogLine>, OpError<ReadAppOps, "fetchLogs">, RuntimeContext>;
+  /**
+   * Follow the App's logs: lines after `cursor` (or the latest), waiting up
+   * to `timeout` for new ones. Pass the returned cursor to the next call.
+   */
+  tail(
+    query?: AppLogFilter & { readonly cursor?: string; readonly timeout?: number },
+  ): Effect.Effect<
+    { readonly lines: ReadonlyArray<AppLogLine>; readonly cursor: string | undefined },
+    OpError<ReadAppOps, "getLogs">,
+    RuntimeContext
+  >;
+  /** Log lines per time bucket. */
+  logCount(
+    query: TimeRange & AppLogFilter & { readonly bucketSecs?: number },
+  ): Effect.Effect<app.AppCountLogsResponse, OpError<ReadAppOps, "countLogs">, RuntimeContext>;
+  /** The App's metadata and a summary of each function. */
+  info(): Effect.Effect<app.AppGetInfoResponse, OpError<ReadAppOps, "info">, RuntimeContext>;
+  /** When the App was created, deployed and stopped, and by whom. */
+  lifecycle(): Effect.Effect<
+    app.AppLifecycle | undefined,
+    OpError<ReadAppOps, "lifecycle">,
+    RuntimeContext
+  >;
+  /** The functions and classes the App serves, by name. */
+  layout(): Effect.Effect<
+    { readonly functionIds: Record<string, string>; readonly classIds: Record<string, string> },
+    OpError<ReadAppOps, "layout">,
+    RuntimeContext
+  >;
+  /** Every deployed version, and the version in production. */
+  deployments(): Effect.Effect<
+    app.AppDeploymentHistoryResponse,
+    OpError<ReadAppOps, "deployments">,
+    RuntimeContext
+  >;
+}
+
+/**
+ * Read a Modal App from any runtime: its logs (every function, server and
+ * sandbox in it), function summaries and deployment history.
+ *
+ * ### Logs
+ * **Example:** Errors from the last hour
+ * ```typescript
+ * const backend = yield* Modal.ReadApp(Backend);
+ * const lines = yield* backend.logs({ since: new Date(Date.now() - 3_600_000), stream: "stderr" });
+ * ```
+ *
+ * ### Deployments
+ * **Example:** The version in production
+ * ```typescript
+ * const { productionAppVersion } = yield* backend.deployments();
+ * ```
+ *
+ * @binding
+ * @product App
+ */
+export interface ReadApp extends Binding.Service<
+  ReadApp,
+  "Modal.ReadApp",
+  (app: App) => Effect.Effect<AppReader>
+> {}
+
+export const ReadApp = Binding.Service<ReadApp>("Modal.ReadApp");

package/src/ReadAppHttp.ts

@@ -0,0 +1,142 @@
+import * as app from "@distilled.cloud/modal/app";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { App } from "./App.ts";
+import { makeModalBinding } from "./BindingHttp.ts";
+import { operations, stringMap, timestampOf } from "./internal.ts";
+import { ReadApp, type AppLogFilter, type AppLogLine, type AppReader } from "./ReadApp.ts";
+
+const STREAM = {
+  stdout: "FILE_DESCRIPTOR_STDOUT",
+  stderr: "FILE_DESCRIPTOR_STDERR",
+  info: "FILE_DESCRIPTOR_INFO",
+} as const;
+
+const streamOf = (fd: string | undefined): AppLogLine["stream"] =>
+  fd === STREAM.stdout
+    ? "stdout"
+    : fd === STREAM.stderr
+      ? "stderr"
+      : fd === STREAM.info
+        ? "info"
+        : undefined;
+
+const filterOf = (filter: AppLogFilter) => ({
+  functionId: filter.functionId,
+  functionCallId: filter.functionCallId,
+  taskId: filter.containerId,
+  sandboxId: filter.sandboxId,
+  searchText: filter.search,
+  source: filter.stream ? STREAM[filter.stream] : undefined,
+});
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+const ReadAppOps = operations({
+  fetchLogs: app.appFetchLogs,
+  getLogs: app.appGetLogs,
+  countLogs: app.appCountLogs,
+  info: app.appGetInfo,
+  lifecycle: app.appGetLifecycle,
+  layout: app.appGetLayout,
+  deployments: app.appDeploymentHistory,
+});
+
+export type ReadAppOps = Effect.Success<typeof ReadAppOps>;
+
+/**
+ * {@link ReadApp} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `viewer` role on the App's environment.
+ *
+ * @layer
+ * @product App
+ * @provides Modal.ReadApp
+ */
+export const ReadAppHttp = Layer.effect(
+  ReadApp,
+  makeModalBinding({
+    tag: "Modal.ReadApp",
+    operations: ReadAppOps,
+    role: "viewer",
+    make: Effect.fn(function* (target: App, ops) {
+      const appId = yield* target.appId;
+      return {
+        logs: (query) =>
+          Effect.flatMap(appId, (id) =>
+            ops.fetchLogs({
+              appId: id,
+              since: timestampOf(query.since),
+              until: timestampOf(query.until ?? Date.now()),
+              limit: query.limit,
+              ...filterOf(query),
+            }),
+          ).pipe(
+            Effect.map((response) =>
+              (response.batches ?? []).flatMap((batch) =>
+                (batch.items ?? []).map((line) => ({
+                  data: line.data ?? "",
+                  timestamp: line.timestamp,
+                  stream: streamOf(line.fileDescriptor),
+                  functionId: batch.functionId,
+                  functionCallId: line.functionCallId,
+                  containerId: line.containerId ?? batch.taskId,
+                  sandboxId: batch.sandboxId,
+                })),
+              ),
+            ),
+          ),
+        tail: (query = {}) =>
+          Effect.flatMap(appId, (id) =>
+            ops.getLogs({
+              appId: id,
+              timeout: query.timeout ?? 10,
+              lastEntryId: query.cursor,
+              functionId: query.functionId,
+              functionCallId: query.functionCallId,
+              taskId: query.containerId,
+              sandboxId: query.sandboxId,
+              searchText: query.search,
+              fileDescriptor: query.stream ? STREAM[query.stream] : undefined,
+            }),
+          ).pipe(
+            Effect.map(({ items }) => ({
+              lines: items.flatMap((batch) =>
+                (batch.items ?? []).map((line) => ({
+                  data: line.data ?? "",
+                  timestamp: line.timestamp,
+                  stream: streamOf(line.fileDescriptor),
+                  functionId: batch.functionId,
+                  functionCallId: line.functionCallId,
+                  containerId: line.containerId ?? batch.taskId,
+                  sandboxId: batch.sandboxId,
+                })),
+              ),
+              cursor: items.findLast((batch) => batch.entryId)?.entryId ?? query.cursor,
+            })),
+          ),
+        logCount: (query) =>
+          Effect.flatMap(appId, (id) =>
+            ops.countLogs({
+              appId: id,
+              since: timestampOf(query.since),
+              until: timestampOf(query.until ?? Date.now()),
+              bucketSecs: query.bucketSecs,
+              ...filterOf(query),
+            }),
+          ),
+        info: () => Effect.flatMap(appId, (id) => ops.info({ appId: id })),
+        lifecycle: () =>
+          Effect.flatMap(appId, (id) => ops.lifecycle({ appId: id })).pipe(
+            Effect.map((response) => response.lifecycle),
+          ),
+        layout: () =>
+          Effect.flatMap(appId, (id) => ops.layout({ appId: id })).pipe(
+            Effect.map(({ appLayout }) => ({
+              functionIds: stringMap(appLayout?.functionIds),
+              classIds: stringMap(appLayout?.classIds),
+            })),
+          ),
+        deployments: () => Effect.flatMap(appId, (id) => ops.deployments({ appId: id })),
+      } satisfies AppReader;
+    }),
+  }),
+);

package/src/ReadDict.ts

@@ -0,0 +1,44 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Dict } from "./Dict.ts";
+import type { ReadDictClient } from "./DictClient.ts";
+
+export type { ReadDictClient } from "./DictClient.ts";
+
+/**
+ * Read a Modal Dict from any runtime: get, contains, len and entries. Keys and values are JSON.
+ *
+ * ### Bind a dict
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Results } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const dict = yield* Modal.ReadDict(Results);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const last = yield* dict.get("last-run");
+ *         return yield* HttpServerResponse.json(last ?? null);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.ReadDictHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Dict
+ */
+export interface ReadDict extends Binding.Service<
+  ReadDict,
+  "Modal.ReadDict",
+  (dict: Dict) => Effect.Effect<ReadDictClient>
+> {}
+
+export const ReadDict = Binding.Service<ReadDict>("Modal.ReadDict");