alchemy 2.0.0-beta.2 → 2.0.0-beta.4

package/src/Cloudflare/Workers/DurableObjectStorage.ts

@@ -0,0 +1,256 @@
+import type * as cf from "@cloudflare/workers-types";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+
+// ---------------------------------------------------------------------------
+// SqlStorage — Effect-native wrapper around cf.SqlStorage
+// ---------------------------------------------------------------------------
+
+export type SqlStorageValue = cf.SqlStorageValue;
+
+export interface SqlCursor<
+  T extends Record<string, SqlStorageValue>,
+> extends Stream.Stream<T> {
+  next(): Effect.Effect<
+    { done?: false; value: T } | { done: true; value?: never }
+  >;
+  toArray(): Effect.Effect<T[]>;
+  one(): Effect.Effect<T>;
+  raw<U extends SqlStorageValue[]>(): Stream.Stream<U>;
+  readonly columnNames: string[];
+  readonly rowsRead: Effect.Effect<number>;
+  readonly rowsWritten: Effect.Effect<number>;
+}
+
+export interface SqlStorage {
+  exec<T extends Record<string, SqlStorageValue>>(
+    query: string,
+    ...bindings: any[]
+  ): Effect.Effect<SqlCursor<T>>;
+  readonly databaseSize: number;
+}
+
+const fromSqlCursor = <T extends Record<string, SqlStorageValue>>(
+  cursor: cf.SqlStorageCursor<T>,
+): SqlCursor<T> => {
+  const stream = Stream.fromIterableEffect(Effect.sync(() => cursor));
+  return Object.assign(stream, {
+    next: () => Effect.sync(() => cursor.next()),
+    toArray: () => Effect.sync(() => cursor.toArray()),
+    one: () => Effect.sync(() => cursor.one()),
+    raw: <U extends SqlStorageValue[]>() =>
+      Stream.fromIterableEffect(Effect.sync(() => cursor.raw<U>())),
+    get columnNames() {
+      return cursor.columnNames;
+    },
+    rowsRead: Effect.sync(() => cursor.rowsRead),
+    rowsWritten: Effect.sync(() => cursor.rowsWritten),
+  }) as SqlCursor<T>;
+};
+
+const fromSqlStorage = (sql: cf.SqlStorage): SqlStorage => ({
+  exec: <T extends Record<string, SqlStorageValue>>(
+    query: string,
+    ...bindings: any[]
+  ): Effect.Effect<SqlCursor<T>> =>
+    Effect.sync(() => fromSqlCursor(sql.exec<T>(query, ...bindings))),
+  get databaseSize() {
+    return sql.databaseSize;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// DurableObjectTransaction
+// ---------------------------------------------------------------------------
+
+export interface DurableObjectTransaction {
+  get<T = unknown>(
+    key: string,
+    options?: cf.DurableObjectGetOptions,
+  ): Effect.Effect<T | undefined>;
+  get<T = unknown>(
+    keys: string[],
+    options?: cf.DurableObjectGetOptions,
+  ): Effect.Effect<Map<string, T>>;
+  list<T = unknown>(
+    options?: cf.DurableObjectListOptions,
+  ): Effect.Effect<Map<string, T>>;
+  put<T>(
+    key: string,
+    value: T,
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<void>;
+  put<T>(
+    entries: Record<string, T>,
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<void>;
+  delete(
+    key: string,
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<boolean>;
+  delete(
+    keys: string[],
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<number>;
+  rollback(): Effect.Effect<void>;
+  getAlarm(
+    options?: cf.DurableObjectGetAlarmOptions,
+  ): Effect.Effect<number | null>;
+  setAlarm(
+    scheduledTime: number | Date,
+    options?: cf.DurableObjectSetAlarmOptions,
+  ): Effect.Effect<void>;
+  deleteAlarm(options?: cf.DurableObjectSetAlarmOptions): Effect.Effect<void>;
+}
+
+// ---------------------------------------------------------------------------
+// DurableObjectStorage
+// ---------------------------------------------------------------------------
+
+export interface DurableObjectStorage {
+  get<T = unknown>(
+    key: string,
+    options?: cf.DurableObjectGetOptions,
+  ): Effect.Effect<T | undefined>;
+  get<T = unknown>(
+    keys: string[],
+    options?: cf.DurableObjectGetOptions,
+  ): Effect.Effect<Map<string, T>>;
+  list<T = unknown>(
+    options?: cf.DurableObjectListOptions,
+  ): Effect.Effect<Map<string, T>>;
+  put<T>(
+    key: string,
+    value: T,
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<void>;
+  put<T>(
+    entries: Record<string, T>,
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<void>;
+  delete(
+    key: string,
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<boolean>;
+  delete(
+    keys: string[],
+    options?: cf.DurableObjectPutOptions,
+  ): Effect.Effect<number>;
+  deleteAll(options?: cf.DurableObjectPutOptions): Effect.Effect<void>;
+  transaction<T>(
+    closure: (txn: DurableObjectTransaction) => Effect.Effect<T>,
+  ): Effect.Effect<T>;
+  getAlarm(
+    options?: cf.DurableObjectGetAlarmOptions,
+  ): Effect.Effect<number | null>;
+  setAlarm(
+    scheduledTime: number | Date,
+    options?: cf.DurableObjectSetAlarmOptions,
+  ): Effect.Effect<void>;
+  deleteAlarm(options?: cf.DurableObjectSetAlarmOptions): Effect.Effect<void>;
+  sync(): Effect.Effect<void>;
+  sql: SqlStorage;
+  kv: cf.SyncKvStorage;
+  transactionSync<T>(closure: () => T): T;
+  getCurrentBookmark(): Effect.Effect<string>;
+  getBookmarkForTime(timestamp: number | Date): Effect.Effect<string>;
+  onNextSessionRestoreBookmark(bookmark: string): Effect.Effect<string>;
+}
+
+// ---------------------------------------------------------------------------
+// Constructors from raw Cloudflare types
+// ---------------------------------------------------------------------------
+
+export const fromDurableObjectTransaction = (
+  txn: cf.DurableObjectTransaction,
+): DurableObjectTransaction => ({
+  get: ((keyOrKeys: string | string[], options?: cf.DurableObjectGetOptions) =>
+    Effect.tryPromise(() => txn.get(keyOrKeys as any, options))) as any,
+  list: (options?: cf.DurableObjectListOptions) =>
+    Effect.tryPromise(() => txn.list(options)),
+  put: ((
+    keyOrEntries: string | Record<string, unknown>,
+    valueOrOptions?: unknown,
+    maybeOptions?: cf.DurableObjectPutOptions,
+  ) =>
+    typeof keyOrEntries === "string"
+      ? Effect.tryPromise(() =>
+          txn.put(keyOrEntries, valueOrOptions, maybeOptions),
+        )
+      : Effect.tryPromise(() =>
+          txn.put(
+            keyOrEntries,
+            valueOrOptions as cf.DurableObjectPutOptions | undefined,
+          ),
+        )) as any,
+  delete: ((
+    keyOrKeys: string | string[],
+    options?: cf.DurableObjectPutOptions,
+  ) => Effect.tryPromise(() => txn.delete(keyOrKeys as any, options))) as any,
+  rollback: () => Effect.sync(() => txn.rollback()),
+  getAlarm: (options?: cf.DurableObjectGetAlarmOptions) =>
+    Effect.tryPromise(() => txn.getAlarm(options)),
+  setAlarm: (
+    scheduledTime: number | Date,
+    options?: cf.DurableObjectSetAlarmOptions,
+  ) => Effect.tryPromise(() => txn.setAlarm(scheduledTime, options)),
+  deleteAlarm: (options?: cf.DurableObjectSetAlarmOptions) =>
+    Effect.tryPromise(() => txn.deleteAlarm(options)),
+});
+
+export const fromDurableObjectStorage = (
+  storage: cf.DurableObjectStorage,
+): DurableObjectStorage => ({
+  get: ((keyOrKeys: string | string[], options?: cf.DurableObjectGetOptions) =>
+    Effect.tryPromise(() => storage.get(keyOrKeys as any, options))) as any,
+  list: (options?: cf.DurableObjectListOptions) =>
+    Effect.tryPromise(() => storage.list(options)),
+  put: ((
+    keyOrEntries: string | Record<string, unknown>,
+    valueOrOptions?: unknown,
+    maybeOptions?: cf.DurableObjectPutOptions,
+  ) =>
+    typeof keyOrEntries === "string"
+      ? Effect.tryPromise(() =>
+          storage.put(keyOrEntries, valueOrOptions, maybeOptions),
+        )
+      : Effect.tryPromise(() =>
+          storage.put(
+            keyOrEntries,
+            valueOrOptions as cf.DurableObjectPutOptions | undefined,
+          ),
+        )) as any,
+  delete: ((
+    keyOrKeys: string | string[],
+    options?: cf.DurableObjectPutOptions,
+  ) =>
+    Effect.tryPromise(() => storage.delete(keyOrKeys as any, options))) as any,
+  deleteAll: (options?: cf.DurableObjectPutOptions) =>
+    Effect.tryPromise(() => storage.deleteAll(options)),
+  transaction: <T>(
+    closure: (txn: DurableObjectTransaction) => Effect.Effect<T>,
+  ) =>
+    Effect.tryPromise(() =>
+      storage.transaction((txn) =>
+        Effect.runPromise(closure(fromDurableObjectTransaction(txn))),
+      ),
+    ),
+  getAlarm: (options?: cf.DurableObjectGetAlarmOptions) =>
+    Effect.tryPromise(() => storage.getAlarm(options)),
+  setAlarm: (
+    scheduledTime: number | Date,
+    options?: cf.DurableObjectSetAlarmOptions,
+  ) => Effect.tryPromise(() => storage.setAlarm(scheduledTime, options)),
+  deleteAlarm: (options?: cf.DurableObjectSetAlarmOptions) =>
+    Effect.tryPromise(() => storage.deleteAlarm(options)),
+  sync: () => Effect.tryPromise(() => storage.sync()),
+  sql: fromSqlStorage(storage.sql),
+  kv: storage.kv,
+  transactionSync: <T>(closure: () => T) => storage.transactionSync(closure),
+  getCurrentBookmark: () =>
+    Effect.tryPromise(() => storage.getCurrentBookmark()),
+  getBookmarkForTime: (timestamp: number | Date) =>
+    Effect.tryPromise(() => storage.getBookmarkForTime(timestamp)),
+  onNextSessionRestoreBookmark: (bookmark: string) =>
+    Effect.tryPromise(() => storage.onNextSessionRestoreBookmark(bookmark)),
+});

package/src/Cloudflare/Workers/DynamicWorkerLoader.ts

@@ -70,16 +70,40 @@ export type DynamicWorkerLoader = {
 };
 
 /**
- * Declare a Dynamic Worker loader binding inside a Worker program.
+ * Load and run ephemeral Workers at runtime from inline JavaScript
+ * modules.
  *
- * At deploy time this registers a `worker_loader` binding on the parent
- * Worker. At runtime it exposes an Effect-wrapped interface for loading
- * and calling into dynamic workers.
+ * `DynamicWorkerLoader` registers a `worker_loader` binding on the
+ * parent Worker at deploy time. At runtime you call `.load()` with
+ * inline module source code and get back a fully typed Worker
+ * instance you can `fetch` or call RPC methods on. Each loaded
+ * Worker runs in its own isolate with full sandboxing.
  *
- * @example
+ * This is useful for evaluating user-provided code, running
+ * untrusted plugins, or dynamically generating Workers from
+ * templates.
+ *
+ * @resource
+ *
+ * @section Creating a Loader
+ * Yield `Cloudflare.DynamicWorkerLoader` in your Worker's init
+ * phase to register the binding. The string argument becomes the
+ * binding name on the deployed Worker.
+ *
+ * @example Registering a loader
  * ```typescript
- * const loader = yield* DynamicWorker("LOADER");
+ * // init
+ * const loader = yield* Cloudflare.DynamicWorkerLoader("Loader");
+ * ```
+ *
+ * @section Loading a Worker
+ * Call `loader.load()` with a compatibility date, a main module
+ * name, and a map of module names to source code strings. The
+ * returned instance exposes `.fetch()` for HTTP and RPC methods
+ * for named entrypoints.
  *
+ * @example Loading and calling a dynamic Worker
+ * ```typescript
  * const worker = loader.load({
  *   compatibilityDate: "2026-01-28",
  *   mainModule: "worker.js",
@@ -90,10 +114,45 @@ export type DynamicWorkerLoader = {
  *       }
  *     }`,
  *   },
+ * });
+ *
+ * const response = yield* worker.fetch(
+ *   HttpClientRequest.get("https://worker/"),
+ * );
+ * ```
+ *
+ * @section Sandboxing
+ * Set `globalOutbound` to `null` to block all outbound network
+ * access from the dynamic Worker, or pass an RPC stub to intercept
+ * and proxy outbound requests.
+ *
+ * @example Blocking outbound access
+ * ```typescript
+ * const worker = loader.load({
+ *   compatibilityDate: "2026-01-28",
+ *   mainModule: "worker.js",
+ *   modules: {
+ *     "worker.js": `export default {
+ *       async fetch(req) {
+ *         // fetch() calls from here will fail
+ *         return new Response("sandboxed");
+ *       }
+ *     }`,
+ *   },
  *   globalOutbound: null,
  * });
+ * ```
  *
- * const response = yield* worker.fetch(request);
+ * @section Named Entrypoints
+ * If the dynamic Worker exports named entrypoints, use
+ * `.getEntrypoint(name)` to get a typed stub for calling its
+ * methods.
+ *
+ * @example Calling a named entrypoint
+ * ```typescript
+ * const worker = loader.load({ ... });
+ * const api = worker.getEntrypoint<{ greet: (name: string) => Effect.Effect<string> }>("api");
+ * const greeting = yield* api.greet("world");
  * ```
  */
 export const DynamicWorkerLoader = Effect.fnUntraced(function* (name: string) {

package/src/Cloudflare/Workers/InferEnv.ts

@@ -14,10 +14,14 @@ export type InferEnv<W> = W extends
     }
   : never;
 
-type GetBindingType<T> = T extends Cloudflare.D1Database
-  ? D1Database
-  : T extends Cloudflare.R2Bucket
-    ? R2Bucket
-    : T extends Cloudflare.KVNamespace
-      ? KVNamespace
-      : never;
+type GetBindingType<T> = T extends Cloudflare.Assets
+  ? Service
+  : T extends Cloudflare.D1Database
+    ? D1Database
+    : T extends Cloudflare.R2Bucket
+      ? R2Bucket
+      : T extends Cloudflare.KVNamespace
+        ? KVNamespace
+        : T extends Cloudflare.DurableObjectNamespaceLike
+          ? DurableObjectNamespace<Exclude<T["Shape"], undefined>>
+          : never;

package/src/Cloudflare/Workers/Rpc.ts

@@ -225,7 +225,7 @@ export const makeDurableObjectBridge =
   ) =>
   (className: string) =>
     class DurableObjectBridge extends DurableObject {
-      readonly object: Promise<any>;
+      readonly object: Promise<DurableObjectShape>;
 
       async fetch(request: cf.Request): Promise<cf.Response> {
         const methods = await this.object;
@@ -240,6 +240,13 @@ export const makeDurableObjectBridge =
         }
       }
 
+      async alarm(alarmInfo?: cf.AlarmInvocationInfo) {
+        const methods = await this.object;
+        if (methods.alarm) {
+          await Effect.runPromise(methods.alarm(alarmInfo));
+        }
+      }
+
       async webSocketMessage(ws: cf.WebSocket, message: string | ArrayBuffer) {
         const methods = await this.object;
         if (methods.webSocketMessage) {
@@ -288,7 +295,10 @@ export const makeDurableObjectBridge =
               ? target[prop]
               : async (...args: unknown[]) => {
                   const methods = await this.object;
-                  const value = methods[prop as string](...args);
+                  const method = methods[
+                    prop as keyof DurableObjectShape
+                  ] as any; // TODO(sam): what should the type be? Is it safe to always call it?
+                  const value = method(...args);
                   if (Effect.isEffect(value)) {
                     const exit = await Effect.runPromiseExit(
                       value as Effect.Effect<unknown, never>,
@@ -374,6 +384,7 @@ export const makeWorkflowBridge =
       }
     };
 
+import type { DurableObjectShape } from "./DurableObjectNamespace.ts";
 import {
   WorkflowEvent as WorkflowEventService,
   WorkflowStep,

package/src/Cloudflare/Workers/ScheduledEvents.ts

@@ -0,0 +1,185 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { DurableObjectState } from "./DurableObjectState.ts";
+import type { SqlStorageValue } from "./DurableObjectStorage.ts";
+
+// ---------------------------------------------------------------------------
+// Scheduled Events — SQLite-backed cron/timer for Durable Objects
+// ---------------------------------------------------------------------------
+
+const INIT_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS alchemy_scheduled_events (
+  id TEXT PRIMARY KEY,
+  run_at INTEGER NOT NULL,
+  repeat_ms INTEGER,
+  payload TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_alchemy_scheduled_events_run_at
+  ON alchemy_scheduled_events (run_at);
+`;
+
+const ensureTable = Effect.gen(function* () {
+  const ctx = yield* DurableObjectState;
+  yield* ctx.storage.sql.exec(INIT_TABLE_SQL);
+});
+
+export interface ScheduledEvent {
+  id: string;
+  runAt: Date;
+  repeatMs?: number;
+  payload: unknown;
+}
+
+interface EventRow extends Record<string, SqlStorageValue> {
+  id: string;
+  run_at: number;
+  repeat_ms: number | null;
+  payload: string;
+}
+
+const toScheduledEvent = (row: EventRow): ScheduledEvent => ({
+  id: row.id,
+  runAt: new Date(row.run_at),
+  repeatMs: row.repeat_ms ?? undefined,
+  payload: JSON.parse(row.payload) as unknown,
+});
+
+/**
+ * Schedule (or reschedule) a named event on the current Durable Object.
+ *
+ * The event is persisted in a SQLite table and the DO alarm is set to
+ * the earliest pending `runAt`. If an event with the same `id` already
+ * exists it is replaced (upsert).
+ *
+ * @param id      Stable identifier for the event (used for upsert / cancel).
+ * @param runAt   When the event should fire.
+ * @param payload Arbitrary JSON-serialisable data delivered to the alarm handler.
+ * @param repeatMs If set, the event re-schedules itself this many ms after each fire.
+ */
+export const scheduleEvent = Effect.fnUntraced(function* (
+  id: string,
+  runAt: Date,
+  payload: unknown,
+  repeatMs?: number,
+) {
+  yield* ensureTable;
+  const ctx = yield* DurableObjectState;
+
+  yield* ctx.storage.sql.exec(
+    `INSERT OR REPLACE INTO alchemy_scheduled_events (id, run_at, repeat_ms, payload)
+     VALUES (?, ?, ?, ?)`,
+    id,
+    runAt.getTime(),
+    repeatMs ?? null,
+    JSON.stringify(payload),
+  );
+
+  yield* reconcileAlarm;
+});
+
+/**
+ * Cancel a previously scheduled event by id. No-op if the event does not exist.
+ */
+export const cancelEvent = Effect.fnUntraced(function* (id: string) {
+  yield* ensureTable;
+  const ctx = yield* DurableObjectState;
+
+  yield* ctx.storage.sql.exec(
+    `DELETE FROM alchemy_scheduled_events WHERE id = ?`,
+    id,
+  );
+
+  yield* reconcileAlarm;
+});
+
+/**
+ * List all currently scheduled events, ordered by `runAt` ascending.
+ */
+export const listEvents: Effect.Effect<
+  ScheduledEvent[],
+  never,
+  DurableObjectState
+> = Effect.gen(function* () {
+  yield* ensureTable;
+  const ctx = yield* DurableObjectState;
+
+  const cursor = yield* ctx.storage.sql.exec<EventRow>(
+    `SELECT id, run_at, repeat_ms, payload FROM alchemy_scheduled_events ORDER BY run_at ASC`,
+  );
+
+  return yield* cursor.pipe(Stream.map(toScheduledEvent), Stream.runCollect);
+});
+
+/**
+ * Process all events whose `runAt` <= now. Returns the fired events.
+ *
+ * - One-shot events are deleted after firing.
+ * - Repeating events have their `runAt` bumped by `repeatMs`.
+ * - The DO alarm is re-set to the next pending event (if any).
+ *
+ * Call this from your Durable Object's `alarm` handler:
+ *
+ * ```ts
+ * alarm: () => Effect.gen(function* () {
+ *   const fired = yield* Cloudflare.processScheduledEvents;
+ *   for (const event of fired) {
+ *     // handle each event
+ *   }
+ * })
+ * ```
+ */
+export const processScheduledEvents: Effect.Effect<
+  ScheduledEvent[],
+  never,
+  DurableObjectState
+> = Effect.gen(function* () {
+  yield* ensureTable;
+  const ctx = yield* DurableObjectState;
+  const now = Date.now();
+
+  const cursor = yield* ctx.storage.sql.exec<EventRow>(
+    `SELECT id, run_at, repeat_ms, payload FROM alchemy_scheduled_events WHERE run_at <= ? ORDER BY run_at ASC`,
+    now,
+  );
+
+  const fired = yield* cursor.pipe(
+    Stream.mapEffect((row) =>
+      (row.repeat_ms != null
+        ? ctx.storage.sql.exec(
+            `UPDATE alchemy_scheduled_events SET run_at = ? WHERE id = ?`,
+            now + row.repeat_ms,
+            row.id,
+          )
+        : ctx.storage.sql.exec(
+            `DELETE FROM alchemy_scheduled_events WHERE id = ?`,
+            row.id,
+          )
+      ).pipe(Effect.as(toScheduledEvent(row))),
+    ),
+    Stream.runCollect,
+  );
+
+  yield* reconcileAlarm;
+  return fired;
+});
+
+/**
+ * Set the DO alarm to the earliest pending event, or clear it if none remain.
+ */
+const reconcileAlarm: Effect.Effect<void, never, DurableObjectState> =
+  Effect.gen(function* () {
+    const ctx = yield* DurableObjectState;
+
+    const next = yield* (yield* ctx.storage.sql.exec<{
+      run_at: number;
+    }>(
+      `SELECT run_at FROM alchemy_scheduled_events ORDER BY run_at ASC LIMIT 1`,
+    )).pipe(Stream.take(1), Stream.runHead);
+
+    if (Option.isSome(next)) {
+      yield* ctx.storage.setAlarm(next.value.run_at);
+    } else {
+      yield* ctx.storage.deleteAlarm();
+    }
+  });

package/src/Cloudflare/Workers/WebSocket.ts

@@ -2,7 +2,7 @@ import type * as cf from "@cloudflare/workers-types";
 import * as Effect from "effect/Effect";
 import * as HttpBody from "effect/unstable/http/HttpBody";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
-import { DurableObjectState } from "./DurableObject.ts";
+import { DurableObjectState } from "./DurableObjectState.ts";
 
 export type RawWebSocket = cf.WebSocket;