@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 429 lines 14.1 KB
Raw
1 /**
2 * Cloudflare D1 client implementation for Effect SQL, backed by a Workers `D1Database` binding.
3 *
4 * This module adapts a Cloudflare D1 database binding into both the
5 * D1-specific `D1Client` service and the generic Effect `SqlClient` service.
6 * It uses the SQLite statement compiler, caches prepared statements, maps D1
7 * failures to `SqlError`, and provides direct or config-backed layers.
8 * Transactions, streaming queries, and `updateValues` are not supported by this
9 * driver.
10 *
11 * @stability unstable
12 * @since 4.0.0
13 */
14 import type { D1Database, D1PreparedStatement, D1Result } from "@cloudflare/workers-types"
15 import * as Cache from "effect/Cache"
16 import * as Config from "effect/Config"
17 import * as Context from "effect/Context"
18 import * as Duration from "effect/Duration"
19 import * as Effect from "effect/Effect"
20 import { identity } from "effect/Function"
21 import * as Layer from "effect/Layer"
22 import * as Reactivity from "effect/reactivity/Reactivity"
23 import type * as Scope from "effect/Scope"
24 import * as Client from "effect/sql/SqlClient"
25 import type { Connection } from "effect/sql/SqlConnection"
26 import { SqlError, UnknownError } from "effect/sql/SqlError"
27 import * as Statement from "effect/sql/Statement"
28 import * as Stream from "effect/Stream"
29
30 const ATTR_DB_SYSTEM_NAME = "db.system.name"
31 const ATTR_DB_OPERATION_NAME = "db.operation.name"
32 const ATTR_DB_OPERATION_BATCH_SIZE = "db.operation.batch.size"
33 const ATTR_DB_QUERY_TEXT = "db.query.text"
34
35 const classifyError = (cause: unknown, message: string, operation: string) =>
36 new UnknownError({ cause, message, operation })
37
38 /**
39 * Unique runtime identifier used to tag `D1Client` values.
40 *
41 * @stability unstable
42 * @category type IDs
43 * @since 4.0.0
44 */
45 export const TypeId: TypeId = "~@effect/sql-d1/D1Client"
46
47 /**
48 * Type-level literal for the `D1Client` runtime identifier.
49 *
50 * @stability unstable
51 * @category type IDs
52 * @since 4.0.0
53 */
54 export type TypeId = "~@effect/sql-d1/D1Client"
55
56 /**
57 * Cloudflare D1 SQL client service, extending `SqlClient` with its D1 configuration and no `updateValues` support.
58 *
59 * @stability unstable
60 * @category services
61 * @since 4.0.0
62 */
63 export interface D1Client extends Client.SqlClient {
64 readonly [TypeId]: TypeId
65 readonly config: D1ClientConfig
66
67 /**
68 * Executes SQL statements as a single atomic D1 batch and returns their row results in order.
69 *
70 * **When to use**
71 *
72 * Use when you have a fixed collection of statements that should run in one
73 * request and roll back together if any statement fails.
74 *
75 * **Gotchas**
76 *
77 * Each statement uses the query and result name transformations from the
78 * client that created it. Mixing clients can produce differently shaped row
79 * results within the same batch.
80 *
81 * @since 4.0.0
82 */
83 readonly batch: <const Statements extends ReadonlyArray<Statement.Statement<any>>>(
84 statements: Statements
85 ) => Effect.Effect<
86 {
87 readonly [K in keyof Statements]: Effect.Success<Statements[K]>
88 },
89 SqlError
90 >
91
92 /** Not supported in d1 */
93 readonly updateValues: never
94 }
95
96 /**
97 * Service tag for the Cloudflare D1 SQL client.
98 *
99 * **When to use**
100 *
101 * Use to access or provide a Cloudflare D1 SQL client through the Effect
102 * context.
103 *
104 * @stability unstable
105 * @category services
106 * @since 4.0.0
107 */
108 export const D1Client = Context.Service<D1Client>("@effect/sql-d1/D1Client")
109
110 /**
111 * Configuration for a Cloudflare D1 client, including the `D1Database`, prepared statement cache settings, span attributes, and query/result name transforms.
112 *
113 * @stability unstable
114 * @category models
115 * @since 4.0.0
116 */
117 export interface D1ClientConfig {
118 readonly db: D1Database
119 readonly prepareCacheSize?: number | undefined
120 readonly prepareCacheTTL?: Duration.Input | undefined
121 readonly spanAttributes?: Record<string, unknown> | undefined
122
123 readonly transformResultNames?: ((str: string) => string) | undefined
124 readonly transformQueryNames?: ((str: string) => string) | undefined
125 }
126
127 type TransformRows = <A extends object>(rows: ReadonlyArray<A>) => ReadonlyArray<A>
128
129 type BatchResults<Statements extends ReadonlyArray<Statement.Statement<any>>> = {
130 readonly [K in keyof Statements]: Effect.Success<Statements[K]>
131 }
132
133 interface StatementWithTransformRows extends Statement.Statement<any> {
134 readonly transformRows: TransformRows | undefined
135 }
136
137 const batchSpanName = (spanAttributes: ReadonlyArray<readonly [string, unknown]>): string => {
138 const target = Statement.spanTarget(spanAttributes)
139 return target === undefined ? "BATCH" : `BATCH ${target}`
140 }
141
142 const makeBatch = (options: {
143 readonly db: D1Database
144 readonly prepareCache: Cache.Cache<string, D1PreparedStatement, SqlError>
145 readonly spanAttributes: ReadonlyArray<readonly [string, unknown]>
146 readonly getClient: () => D1Client
147 }): D1Client["batch"] =>
148 <const Statements extends ReadonlyArray<Statement.Statement<any>>>(
149 statements: Statements
150 ) => {
151 if (statements.length === 0) {
152 return Effect.succeed([] as unknown as BatchResults<Statements>)
153 }
154 const isBatch = statements.length > 1
155 return Effect.useSpan(
156 isBatch ? batchSpanName(options.spanAttributes) : Statement.spanName(options.spanAttributes),
157 { kind: "client" },
158 (span) =>
159 Effect.withFiber(Effect.fnUntraced(function*(fiber) {
160 const transformer = fiber.getRef(Statement.CurrentTransformer)
161 const prepared: Array<D1PreparedStatement> = []
162 const transforms: Array<TransformRows | undefined> = []
163 const queryTexts: Array<string> = []
164
165 for (const original of statements) {
166 const statement = transformer === undefined
167 ? original
168 : yield* transformer(original, options.getClient(), fiber, span)
169 const [sql, params] = statement.compile()
170 queryTexts.push(sql)
171 transforms.push((statement as StatementWithTransformRows).transformRows)
172 prepared.push((yield* Cache.get(options.prepareCache, sql)).bind(...params))
173 }
174
175 for (const [key, value] of options.spanAttributes) {
176 span.attribute(key, value)
177 }
178 if (isBatch) {
179 span.attribute(ATTR_DB_OPERATION_NAME, "BATCH")
180 span.attribute(ATTR_DB_OPERATION_BATCH_SIZE, statements.length)
181 }
182 span.attribute(ATTR_DB_QUERY_TEXT, queryTexts.join("; "))
183
184 // D1 batches execute on the binding directly and intentionally cannot participate in SqlClient transactions.
185 const responses = yield* Effect.tryPromise({
186 try: () =>
187 options.db.batch<Record<string, unknown>>(prepared).then((responses) => {
188 for (const response of responses) {
189 if (response.error) {
190 throw response.error
191 }
192 }
193 return responses
194 }),
195 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute batch", "execute") })
196 })
197
198 const results = responses.map((response, index) => {
199 const rows = response.results || []
200 const transformRows = transforms[index]
201 return transformRows ? transformRows(rows) : rows
202 })
203 return results as BatchResults<Statements>
204 }))
205 )
206 }
207
208 /**
209 * Creates a scoped Cloudflare D1 SQL client. Prepared statements are cached, while transactions and streaming queries are not supported by this driver.
210 *
211 * @stability unstable
212 * @category constructors
213 * @since 4.0.0
214 */
215 export const make = (
216 options: D1ClientConfig
217 ): Effect.Effect<D1Client, never, Scope.Scope | Reactivity.Reactivity> =>
218 Effect.gen(function*() {
219 const compiler = Statement.makeCompilerSqlite(options.transformQueryNames)
220 const transformRows = options.transformResultNames ?
221 Statement.defaultTransforms(options.transformResultNames).array :
222 undefined
223 const spanAttributes: Array<readonly [string, unknown]> = [
224 ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
225 [ATTR_DB_SYSTEM_NAME, "sqlite"]
226 ]
227
228 const makeConnection = Effect.gen(function*() {
229 const db = options.db
230
231 const prepareCache = yield* Cache.make({
232 capacity: options.prepareCacheSize ?? 200,
233 timeToLive: options.prepareCacheTTL ?? Duration.minutes(10),
234 lookup: (sql: string) =>
235 Effect.try({
236 try: () => db.prepare(sql),
237 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to prepare statement", "prepare") })
238 })
239 })
240
241 const runStatementRaw = (
242 statement: D1PreparedStatement,
243 params: ReadonlyArray<unknown> = []
244 ): Effect.Effect<D1Result, SqlError, never> =>
245 Effect.tryPromise({
246 try: async () => {
247 const response = await statement.bind(...params).all()
248 if (response.error) {
249 throw response.error
250 }
251 return response
252 },
253 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
254 })
255
256 const runStatement = (
257 statement: D1PreparedStatement,
258 params: ReadonlyArray<unknown> = []
259 ): Effect.Effect<ReadonlyArray<any>, SqlError, never> =>
260 Effect.map(runStatementRaw(statement, params), (response) => response.results || [])
261
262 const runRaw = (
263 sql: string,
264 params: ReadonlyArray<unknown> = []
265 ) => runStatementRaw(db.prepare(sql), params)
266
267 const runCached = (
268 sql: string,
269 params: ReadonlyArray<unknown> = []
270 ) => Effect.flatMap(Cache.get(prepareCache, sql), (s) => runStatement(s, params))
271
272 const runUncached = (
273 sql: string,
274 params: ReadonlyArray<unknown> = []
275 ) => runStatement(db.prepare(sql), params)
276
277 const runValues = (
278 sql: string,
279 params: ReadonlyArray<unknown>
280 ) =>
281 Effect.flatMap(
282 Cache.get(prepareCache, sql),
283 (statement) =>
284 Effect.tryPromise({
285 try: () => {
286 return statement.bind(...params).raw() as Promise<
287 ReadonlyArray<
288 ReadonlyArray<unknown>
289 >
290 >
291 },
292 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
293 })
294 )
295
296 const runValuesUncached = (
297 sql: string,
298 params: ReadonlyArray<unknown>
299 ) =>
300 Effect.tryPromise({
301 try: () => {
302 return db.prepare(sql).bind(...params).raw() as Promise<
303 ReadonlyArray<
304 ReadonlyArray<unknown>
305 >
306 >
307 },
308 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "execute") })
309 })
310
311 const connection = identity<Connection>({
312 execute(sql, params, transformRows) {
313 return transformRows
314 ? Effect.map(runCached(sql, params), transformRows)
315 : runCached(sql, params)
316 },
317 executeRaw(sql, params) {
318 return runRaw(sql, params)
319 },
320 executeValues(sql, params) {
321 return runValues(sql, params)
322 },
323 executeValuesUnprepared(sql, params) {
324 return runValuesUncached(sql, params)
325 },
326 executeUnprepared(sql, params, transformRows) {
327 return transformRows
328 ? Effect.map(runUncached(sql, params), transformRows)
329 : runUncached(sql, params)
330 },
331 executeStream(_sql, _params) {
332 return Stream.die("executeStream not implemented")
333 }
334 })
335 return { connection, prepareCache } as const
336 })
337
338 const { connection, prepareCache } = yield* makeConnection
339 const acquirer = Effect.succeed(connection)
340 const transactionAcquirer = Effect.die("transactions are not supported in D1")
341
342 let client!: D1Client
343 client = Object.assign(
344 (yield* Client.make({
345 driver: "d1",
346 acquirer,
347 compiler,
348 transactionAcquirer,
349 spanAttributes,
350 transformRows
351 })) as D1Client,
352 {
353 [TypeId]: TypeId as TypeId,
354 config: options,
355 batch: makeBatch({
356 db: options.db,
357 prepareCache,
358 spanAttributes,
359 getClient: () => client
360 })
361 }
362 )
363
364 if (options.transformQueryNames !== undefined || transformRows !== undefined) {
365 const clientWithoutTransformsBase = yield* Client.make({
366 driver: "d1",
367 acquirer: Effect.succeed(connection),
368 compiler: compiler.withoutTransform,
369 transactionAcquirer,
370 spanAttributes,
371 transformRows: undefined
372 })
373 let clientWithoutTransforms!: D1Client
374 clientWithoutTransforms = Object.assign(clientWithoutTransformsBase as D1Client, {
375 [TypeId]: TypeId as TypeId,
376 config: options,
377 batch: makeBatch({
378 db: options.db,
379 prepareCache,
380 spanAttributes,
381 getClient: () => clientWithoutTransforms
382 }),
383 withoutTransforms: () => clientWithoutTransforms
384 })
385 Object.assign(client, {
386 withoutTransforms: () => clientWithoutTransforms
387 })
388 }
389
390 return client
391 })
392
393 /**
394 * Creates a layer from a `Config`-wrapped D1 client configuration, providing both `D1Client` and `SqlClient`.
395 *
396 * @stability unstable
397 * @category layers
398 * @since 4.0.0
399 */
400 export const layerConfig = (
401 config: Config.Wrap<D1ClientConfig>
402 ): Layer.Layer<D1Client | Client.SqlClient, Config.ConfigError> =>
403 Layer.effectContext(
404 Config.unwrap(config).pipe(
405 Effect.flatMap(make),
406 Effect.map((client) =>
407 Context.make(D1Client, client).pipe(
408 Context.add(Client.SqlClient, client)
409 )
410 )
411 )
412 ).pipe(Layer.provide(Reactivity.layer))
413
414 /**
415 * Creates a layer from a concrete D1 client configuration, providing both `D1Client` and `SqlClient`.
416 *
417 * @stability unstable
418 * @category layers
419 * @since 4.0.0
420 */
421 export const layer = (
422 config: D1ClientConfig
423 ): Layer.Layer<D1Client | Client.SqlClient, Config.ConfigError> =>
424 Layer.effectContext(
425 Effect.map(make(config), (client) =>
426 Context.make(D1Client, client).pipe(
427 Context.add(Client.SqlClient, client)
428 ))
429 ).pipe(Layer.provide(Reactivity.layer))