The best way to control Claude Code, Codex and more from any computer or phone

main
ts 134 lines 4.82 KB
Raw
1 import type * as runtime from "@cloudflare/workers-types";
2 import * as Binding from "alchemy/Binding";
3 import type { RuntimeContext } from "alchemy/RuntimeContext";
4 import * as Effect from "effect/Effect";
5 import type { Database } from "./Database.ts";
6
7 /**
8 * Bind a {@link Database} to a Worker and obtain the Effect-native D1
9 * connection client (`prepare`, `exec`, `batch`, `raw`).
10 *
11 * `QueryDatabase` is a single identifier that is simultaneously the binding's
12 * Context tag, its type, and the callable —
13 * `yield* Cloudflare.D1.QueryDatabase(db)`.
14 *
15 * **Example:** Querying a database inside a Worker
16 * ```typescript
17 * const db = yield* Cloudflare.D1.QueryDatabase(MyDatabase);
18 * const rows = yield* db.prepare("SELECT * FROM users").all();
19 * ```
20 *
21 * @binding
22 * @product D1
23 * @category Storage & Databases
24 */
25 export interface QueryDatabase extends Binding.Service<
26 QueryDatabase,
27 "Cloudflare.D1.QueryDatabase",
28 (database: Database) => Effect.Effect<QueryDatabaseClient>
29 > {}
30
31 export const QueryDatabase = Binding.Service<QueryDatabase>("Cloudflare.D1.QueryDatabase");
32
33 /**
34 * Effect-native wrapper around a Cloudflare D1 prepared statement.
35 *
36 * Construction (`prepare`) and binding (`bind`) are synchronous —
37 * they're plan builders and don't touch D1. Only the executors
38 * (`all`, `first`, `run`, `raw`) round-trip to the database, and
39 * those return Effects so they participate in the Effect runtime.
40 */
41 export class PreparedStatement {
42 /** @internal */
43 constructor(
44 private readonly query: string,
45 private readonly binds: ReadonlyArray<unknown>,
46 private readonly rawEff: Effect.Effect<runtime.D1Database>,
47 ) {}
48
49 /**
50 * Return a new prepared statement bound to `values`. Subsequent
51 * calls replace the previous binding, matching the underlying
52 * Cloudflare runtime semantics.
53 */
54 bind(...values: unknown[]): PreparedStatement {
55 return new PreparedStatement(this.query, values, this.rawEff);
56 }
57
58 /** Run the query and return all matching rows. */
59 all<T = unknown>(): Effect.Effect<runtime.D1Result<T>, never, RuntimeContext> {
60 return this.withRuntime((stmt) => stmt.all<T>());
61 }
62
63 /** Run the query and return the first row, or `null` if no rows. */
64 first<T = unknown>(): Effect.Effect<T | null, never, RuntimeContext>;
65 first<T = unknown>(column: string): Effect.Effect<T | null, never, RuntimeContext>;
66 first<T = unknown>(column?: string): Effect.Effect<T | null, never, RuntimeContext> {
67 return this.withRuntime((stmt) =>
68 column !== undefined ? stmt.first<T>(column) : stmt.first<T>(),
69 );
70 }
71
72 /** Run the query as a mutation; returns row metadata. */
73 run<T = unknown>(): Effect.Effect<runtime.D1Result<T>, never, RuntimeContext> {
74 return this.withRuntime((stmt) => stmt.run<T>());
75 }
76
77 /** Run the query and return rows as flat arrays. */
78 raw<T = unknown[]>(): Effect.Effect<T[], never, RuntimeContext>;
79 raw<T = unknown[]>(options: {
80 columnNames: true;
81 }): Effect.Effect<[string[], ...T[]], never, RuntimeContext>;
82 raw<T = unknown[]>(options?: {
83 columnNames: true;
84 }): Effect.Effect<T[] | [string[], ...T[]], never, RuntimeContext> {
85 return this.withRuntime((stmt) =>
86 options ? stmt.raw<T>(options) : (stmt.raw<T>() as Promise<T[] | [string[], ...T[]]>),
87 );
88 }
89
90 /**
91 * Materialize the underlying Cloudflare prepared statement against
92 * a concrete D1 binding. Used by `QueryDatabaseClient.batch` to
93 * collect statements for a single transactional call.
94 *
95 * @internal
96 */
97 _build(raw: runtime.D1Database): runtime.D1PreparedStatement {
98 const stmt = raw.prepare(this.query);
99 return this.binds.length > 0 ? stmt.bind(...this.binds) : stmt;
100 }
101
102 private withRuntime<A>(
103 fn: (stmt: runtime.D1PreparedStatement) => Promise<A>,
104 ): Effect.Effect<A, never, RuntimeContext> {
105 return Effect.flatMap(this.rawEff, (raw) =>
106 Effect.promise(() => fn(this._build(raw))),
107 ) as Effect.Effect<A, never, RuntimeContext>;
108 }
109 }
110
111 export interface QueryDatabaseClient {
112 /**
113 * An Effect that resolves to the raw underlying Cloudflare D1Database binding.
114 * Use this when you need direct access for libraries like Better Auth.
115 */
116 raw: Effect.Effect<runtime.D1Database, never, RuntimeContext>;
117 /**
118 * Prepare a SQL statement. Returns synchronously — the network
119 * round-trip happens when you yield one of the statement's
120 * executors (`all`, `first`, `run`, `raw`).
121 */
122 prepare: (query: string) => PreparedStatement;
123 /**
124 * Execute raw SQL without prepared statements.
125 */
126 exec: (query: string) => Effect.Effect<runtime.D1ExecResult, never, RuntimeContext>;
127 /**
128 * Send multiple prepared statements in a single call.
129 * Statements execute sequentially and are rolled back on failure.
130 */
131 batch: <T = unknown>(
132 statements: PreparedStatement[],
133 ) => Effect.Effect<runtime.D1Result<T>[], never, RuntimeContext>;
134 }