@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 537 lines 17.2 KB
Raw
1 /**
2 * Connects Effect SQL to PGlite, the embedded PostgreSQL-compatible database
3 * from `@electric-sql/pglite`.
4 *
5 * This module can create a managed PGlite instance or wrap an existing one and
6 * expose it as both `PgliteClient` and the generic Effect SQL client. The client
7 * runs PostgreSQL-style SQL, adds helpers for JSON values and LISTEN/NOTIFY
8 * messages, can dump the PGlite data directory, and can refresh PGlite array
9 * types. It also provides layers and maps common PostgreSQL-style failures into
10 * Effect SQL errors.
11 *
12 * @stability unstable
13 * @since 4.0.0
14 */
15 import { PGlite, type PGliteInterface, type PGliteOptions } from "@electric-sql/pglite"
16 import * as Config from "effect/Config"
17 import * as Context from "effect/Context"
18 import * as Effect from "effect/Effect"
19 import * as Layer from "effect/Layer"
20 import * as Queue from "effect/Queue"
21 import * as Reactivity from "effect/reactivity/Reactivity"
22 import type * as Scope from "effect/Scope"
23 import * as Semaphore from "effect/Semaphore"
24 import * as Client from "effect/sql/SqlClient"
25 import type { Connection } from "effect/sql/SqlConnection"
26 import {
27 AuthenticationError,
28 AuthorizationError,
29 ConnectionError,
30 ConstraintError,
31 DeadlockError,
32 LockTimeoutError,
33 SerializationError,
34 SqlError,
35 SqlSyntaxError,
36 StatementTimeoutError,
37 UniqueViolation,
38 UnknownError
39 } from "effect/sql/SqlError"
40 import type { Custom, Fragment } from "effect/sql/Statement"
41 import * as Statement from "effect/sql/Statement"
42 import * as Stream from "effect/Stream"
43
44 /**
45 * Runtime type identifier used to mark `PgliteClient` values.
46 *
47 * @stability unstable
48 * @category type IDs
49 * @since 4.0.0
50 */
51 export const TypeId: TypeId = "~@effect/sql-pglite/PgliteClient"
52
53 /**
54 * Type-level identifier used to mark `PgliteClient` values.
55 *
56 * @stability unstable
57 * @category type IDs
58 * @since 4.0.0
59 */
60 export type TypeId = "~@effect/sql-pglite/PgliteClient"
61
62 /**
63 * PGlite-backed PostgreSQL client service, extending `SqlClient` with access to the PGlite instance, JSON fragments, LISTEN/NOTIFY, data directory dumps, and array type refresh.
64 *
65 * @stability unstable
66 * @category services
67 * @since 4.0.0
68 */
69 export interface PgliteClient extends Client.SqlClient {
70 readonly [TypeId]: TypeId
71 readonly config: PgliteClientConfig
72 readonly pglite: PGliteInterface
73 readonly json: (_: unknown) => Fragment
74 /**
75 * Subscribes to a PGlite notification channel.
76 *
77 * **Details**
78 *
79 * The effect completes after the listener is installed. Notifications are
80 * buffered in the returned dequeue, and the subscription remains active
81 * until the required scope closes.
82 */
83 readonly listen: (
84 channel: string
85 ) => Effect.Effect<Queue.Dequeue<string>, SqlError, Scope.Scope>
86 readonly notify: (channel: string, payload: string) => Effect.Effect<void, SqlError>
87 readonly dumpDataDir: (compression?: "none" | "gzip" | "auto") => Effect.Effect<File | Blob, SqlError>
88 readonly refreshArrayTypes: Effect.Effect<void, SqlError>
89 }
90
91 /**
92 * Service tag for the PGlite client service.
93 *
94 * **When to use**
95 *
96 * Use to access or provide a PGlite client through the Effect context.
97 *
98 * @stability unstable
99 * @category services
100 * @since 4.0.0
101 */
102 export const PgliteClient = Context.Service<PgliteClient>("@effect/sql-pglite/PgliteClient")
103
104 /**
105 * Configuration for a PGlite client, either by supplying PGlite creation options or an existing live PGlite client.
106 *
107 * @stability unstable
108 * @category models
109 * @since 4.0.0
110 */
111 export type PgliteClientConfig = PgliteClientConfig.Create | PgliteClientConfig.Live
112
113 /**
114 * Namespace containing the configuration variants for `PgliteClient`.
115 *
116 * @stability unstable
117 * @since 4.0.0
118 */
119 export declare namespace PgliteClientConfig {
120 /**
121 * Shared PGlite client options for span attributes, query/result name transformations, and JSON value transformation.
122 *
123 * @stability unstable
124 * @category models
125 * @since 4.0.0
126 */
127 export interface Base {
128 readonly spanAttributes?: Record<string, unknown> | undefined
129 readonly transformResultNames?: ((str: string) => string) | undefined
130 readonly transformQueryNames?: ((str: string) => string) | undefined
131 readonly transformJson?: boolean | undefined
132 }
133
134 /**
135 * Configuration used to create a managed PGlite instance from PGlite constructor options.
136 *
137 * @stability unstable
138 * @category models
139 * @since 4.0.0
140 */
141 export interface Create extends Base, PGliteOptions {}
142
143 /**
144 * Configuration that uses an existing PGlite client. The supplied `liveClient` is caller-owned and is not closed by the Effect client.
145 *
146 * @stability unstable
147 * @category models
148 * @since 4.0.0
149 */
150 export interface Live extends Base {
151 readonly liveClient: PGliteInterface
152 }
153
154 /**
155 * Config-friendly subset of PGlite creation options, including data directory, username, database, relaxed durability, and shared transform options.
156 *
157 * @stability unstable
158 * @category models
159 * @since 4.0.0
160 */
161 export interface ConfigBase extends Base {
162 readonly dataDir?: string | undefined
163 readonly username?: string | undefined
164 readonly database?: string | undefined
165 readonly relaxedDurability?: boolean | undefined
166 }
167 }
168
169 /**
170 * Creates a scoped PGlite SQL client. When no live client is supplied it creates and closes a PGlite instance; when `liveClient` is supplied, the caller retains ownership.
171 *
172 * @stability unstable
173 * @category constructors
174 * @since 4.0.0
175 */
176 export const make = (
177 options: PgliteClientConfig = {}
178 ): Effect.Effect<PgliteClient, SqlError, Scope.Scope | Reactivity.Reactivity> =>
179 Effect.gen(function*() {
180 const pglite = "liveClient" in options
181 ? options.liveClient
182 : yield* Effect.acquireRelease(
183 Effect.tryPromise({
184 try: async () => {
185 const pg = new PGlite(options)
186 await pg.waitReady
187 return pg
188 },
189 catch: (cause) => new SqlError({ reason: classifyError(cause, "PgliteClient: Failed to connect", "connect") })
190 }),
191 (pg) => Effect.promise(() => pg.close()).pipe(Effect.timeoutOption(1000)),
192 { interruptible: true }
193 )
194
195 return yield* fromClient({ ...options, liveClient: pglite })
196 })
197
198 /**
199 * Builds a `PgliteClient` around an existing PGlite instance, adding SQL client operations, LISTEN/NOTIFY, dump helpers, and serialized access.
200 *
201 * @stability unstable
202 * @category constructors
203 * @since 4.0.0
204 */
205 export const fromClient = (
206 options:
207 & PgliteClientConfig.Base
208 & {
209 readonly liveClient: PGliteInterface
210 }
211 ): Effect.Effect<PgliteClient, SqlError, Scope.Scope | Reactivity.Reactivity> =>
212 Effect.gen(function*() {
213 const pglite = options.liveClient
214 const compiler = makeCompiler(options.transformQueryNames, options.transformJson)
215 const transformRows = options.transformResultNames
216 ? Statement.defaultTransforms(options.transformResultNames, options.transformJson).array
217 : undefined
218
219 const spanAttributes: Array<[string, unknown]> = [
220 ...(options.spanAttributes ? Object.entries(options.spanAttributes) : []),
221 [ATTR_DB_SYSTEM_NAME, "postgresql"]
222 ]
223
224 const connection = new PgliteConnection(pglite)
225 const semaphore = Semaphore.makeUnsafe(1)
226 // Statements, streams and transactions hold the permit until their scope
227 // closes, so no other fiber can use the connection while they run.
228 const acquirer = Effect.as(
229 Effect.acquireRelease(semaphore.take(1), () => semaphore.release(1), { interruptible: true }),
230 connection
231 )
232
233 const config = options as PgliteClientConfig
234 const client = yield* Client.make({
235 driver: "pglite",
236 acquirer,
237 compiler,
238 releaseSavepoint: (name) => `RELEASE SAVEPOINT ${name}`,
239 spanAttributes,
240 transformRows
241 })
242
243 return Object.assign(
244 client,
245 {
246 [TypeId]: TypeId as TypeId,
247 config,
248 pglite,
249 json: (_: unknown) => Statement.fragment([PgJson(_)]),
250 listen: Effect.fnUntraced(function*(channel: string) {
251 const queue = yield* Queue.unbounded<string>()
252 yield* Effect.acquireRelease(
253 Effect.tryPromise({
254 try: () =>
255 pglite.listen(channel, (payload) => {
256 Queue.offerUnsafe(queue, payload)
257 }),
258 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to listen", "listen") })
259 }),
260 (unlisten) => Effect.promise(() => unlisten()),
261 { interruptible: true }
262 )
263 yield* Effect.addFinalizer(() => Queue.shutdown(queue))
264 return queue
265 }),
266 notify: (channel: string, payload: string) =>
267 Effect.tryPromise({
268 try: () => pglite.exec(`NOTIFY ${escape(channel)}, ${escapeLiteral(payload)}`),
269 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to notify", "notify") })
270 }).pipe(
271 semaphore.withPermit,
272 Effect.asVoid
273 ),
274 dumpDataDir: (compression?: "none" | "gzip" | "auto") =>
275 semaphore.withPermit(
276 Effect.tryPromise({
277 try: () => pglite.dumpDataDir(compression),
278 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to dump data dir", "dumpDataDir") })
279 })
280 ),
281 refreshArrayTypes: semaphore.withPermit(
282 Effect.tryPromise({
283 try: () => pglite.refreshArrayTypes(),
284 catch: (cause) =>
285 new SqlError({ reason: classifyError(cause, "Failed to refresh array types", "refreshArrayTypes") })
286 })
287 )
288 }
289 )
290 })
291
292 class PgliteConnection implements Connection {
293 readonly pglite: PGliteInterface
294 constructor(pglite: PGliteInterface) {
295 this.pglite = pglite
296 }
297
298 private run(method: string, sql: string, params: ReadonlyArray<unknown>) {
299 return Effect.map(
300 Effect.tryPromise({
301 try: () => this.pglite.query<any>(sql, params as Array<any>),
302 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", method) })
303 }),
304 (result) => result.rows
305 )
306 }
307 execute(
308 sql: string,
309 params: ReadonlyArray<unknown>,
310 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
311 ) {
312 return transformRows
313 ? Effect.map(this.run("execute", sql, params), transformRows)
314 : this.run("execute", sql, params)
315 }
316 executeRaw(sql: string, params: ReadonlyArray<unknown>) {
317 return Effect.tryPromise({
318 try: () => this.pglite.query<any>(sql, params as Array<any>),
319 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "executeRaw") })
320 })
321 }
322 executeValues(sql: string, params: ReadonlyArray<unknown>) {
323 return Effect.map(
324 Effect.tryPromise({
325 try: () => this.pglite.query<any>(sql, params as Array<any>, { rowMode: "array" }),
326 catch: (cause) => new SqlError({ reason: classifyError(cause, "Failed to execute statement", "executeValues") })
327 }),
328 (result) => result.rows as ReadonlyArray<ReadonlyArray<any>>
329 )
330 }
331 executeValuesUnprepared(sql: string, params: ReadonlyArray<unknown>) {
332 return Effect.map(
333 Effect.tryPromise({
334 try: () => this.pglite.query<any>(sql, params as Array<any>, { rowMode: "array" }),
335 catch: (cause) =>
336 new SqlError({ reason: classifyError(cause, "Failed to execute statement", "executeValuesUnprepared") })
337 }),
338 (result) => result.rows as ReadonlyArray<ReadonlyArray<any>>
339 )
340 }
341 executeUnprepared(
342 sql: string,
343 params: ReadonlyArray<unknown>,
344 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
345 ) {
346 return transformRows
347 ? Effect.map(this.run("executeUnprepared", sql, params), transformRows)
348 : this.run("executeUnprepared", sql, params)
349 }
350 executeStream(
351 sql: string,
352 params: ReadonlyArray<unknown>,
353 transformRows: (<A extends object>(row: ReadonlyArray<A>) => ReadonlyArray<A>) | undefined
354 ) {
355 const eff = transformRows
356 ? Effect.map(this.run("executeStream", sql, params), transformRows)
357 : this.run("executeStream", sql, params)
358 return Stream.fromArrayEffect(eff)
359 }
360 }
361
362 /**
363 * Creates a layer from an effect that acquires a `PgliteClient`, providing both `PgliteClient` and `SqlClient`.
364 *
365 * @stability unstable
366 * @category layers
367 * @since 4.0.0
368 */
369 export const layerFrom = <E, R>(
370 acquire: Effect.Effect<PgliteClient, E, R>
371 ): Layer.Layer<PgliteClient | Client.SqlClient, E, Exclude<R, Scope.Scope | Reactivity.Reactivity>> =>
372 Layer.effectContext(
373 Effect.map(acquire, (client) =>
374 Context.make(PgliteClient, client).pipe(
375 Context.add(Client.SqlClient, client)
376 ))
377 ).pipe(Layer.provide(Reactivity.layer)) as any
378
379 /**
380 * Creates a layer from a `Config`-wrapped PGlite client configuration, providing both `PgliteClient` and `SqlClient`.
381 *
382 * @stability unstable
383 * @category layers
384 * @since 4.0.0
385 */
386 export const layerConfig: (
387 config: Config.Wrap<PgliteClientConfig.ConfigBase>
388 ) => Layer.Layer<PgliteClient | Client.SqlClient, Config.ConfigError | SqlError> = (
389 config: Config.Wrap<PgliteClientConfig.ConfigBase>
390 ): Layer.Layer<PgliteClient | Client.SqlClient, Config.ConfigError | SqlError> =>
391 layerFrom(Effect.flatMap(
392 Config.unwrap(config),
393 (resolved) => make(resolved as PgliteClientConfig)
394 ))
395
396 /**
397 * Creates a layer from a concrete PGlite client configuration, providing both `PgliteClient` and `SqlClient`.
398 *
399 * @stability unstable
400 * @category layers
401 * @since 4.0.0
402 */
403 export const layer = (
404 config?: PgliteClientConfig | undefined
405 ): Layer.Layer<PgliteClient | Client.SqlClient, SqlError> => layerFrom(make(config))
406
407 /**
408 * Creates the PGlite statement compiler, using PostgreSQL `$1` placeholders, double-quoted identifiers, returning clauses, and optional JSON value transformation.
409 *
410 * @stability unstable
411 * @category constructors
412 * @since 4.0.0
413 */
414 export const makeCompiler = (
415 transform?: (_: string) => string,
416 transformJson = true
417 ): Statement.Compiler => {
418 const transformValue = transformJson && transform
419 ? Statement.defaultTransforms(transform).value
420 : undefined
421
422 return Statement.makeCompiler<PgCustom>({
423 dialect: "pg",
424 placeholder(_) {
425 return `$${_}`
426 },
427 onIdentifier: transform ?
428 function(value, withoutTransform) {
429 return withoutTransform ? escape(value) : escape(transform(value))
430 } :
431 escape,
432 onRecordUpdate(placeholders, valueAlias, valueColumns, values, returning) {
433 return [
434 `(values ${placeholders}) AS ${valueAlias}${valueColumns}${returning ? ` RETURNING ${returning[0]}` : ""}`,
435 returning ?
436 values.flat().concat(returning[1]) :
437 values.flat()
438 ]
439 },
440 onCustom(type, placeholder, withoutTransform) {
441 switch (type.kind) {
442 case "PgJson": {
443 const value = withoutTransform || transformValue === undefined
444 ? type.paramA
445 : transformValue(type.paramA)
446 return [
447 placeholder(undefined),
448 [typeof value === "string" ? JSON.stringify(value) : value]
449 ]
450 }
451 }
452 }
453 })
454 }
455
456 const escape = Statement.defaultEscape("\"")
457 const escapeLiteral = (value: string) => `'${value.replace(/'/g, "''")}'`
458
459 /**
460 * PGlite-specific custom statement fragments supported by the compiler, currently JSON parameter fragments.
461 *
462 * @stability unstable
463 * @category models
464 * @since 4.0.0
465 */
466 export type PgCustom = PgJson
467
468 /**
469 * @category models
470 * @since 4.0.0
471 */
472 interface PgJson extends Custom<"PgJson", unknown> {}
473 const PgJson = Statement.custom<PgJson>("PgJson")
474
475 const ATTR_DB_SYSTEM_NAME = "db.system.name"
476
477 const pgCodeFromCause = (cause: unknown): string | undefined => {
478 if (typeof cause !== "object" || cause === null || !("code" in cause)) {
479 return undefined
480 }
481 const code = cause.code
482 return typeof code === "string" ? code : undefined
483 }
484
485 const pgConstraintFromCause = (cause: unknown): string => {
486 if (typeof cause !== "object" || cause === null || !("constraint" in cause)) {
487 return "unknown"
488 }
489 const constraint = cause.constraint
490 if (typeof constraint !== "string") {
491 return "unknown"
492 }
493 const normalized = constraint.trim()
494 return normalized.length === 0 ? "unknown" : normalized
495 }
496
497 const classifyError = (
498 cause: unknown,
499 message: string,
500 operation: string
501 ) => {
502 const props = { cause, message, operation }
503 const code = pgCodeFromCause(cause)
504 if (code !== undefined) {
505 if (code.startsWith("08")) {
506 return new ConnectionError(props)
507 }
508 if (code.startsWith("28")) {
509 return new AuthenticationError(props)
510 }
511 if (code === "42501") {
512 return new AuthorizationError(props)
513 }
514 if (code.startsWith("42")) {
515 return new SqlSyntaxError(props)
516 }
517 if (code === "23505") {
518 return new UniqueViolation({ ...props, constraint: pgConstraintFromCause(cause) })
519 }
520 if (code.startsWith("23")) {
521 return new ConstraintError(props)
522 }
523 if (code === "40P01") {
524 return new DeadlockError(props)
525 }
526 if (code === "40001") {
527 return new SerializationError(props)
528 }
529 if (code === "55P03") {
530 return new LockTimeoutError(props)
531 }
532 if (code === "57014") {
533 return new StatementTimeoutError(props)
534 }
535 }
536 return new UnknownError(props)
537 }