@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 665 lines 19.1 KB
Raw
1 /**
2 * Builds and opens typed IndexedDB databases from versioned schema migrations.
3 *
4 * This module turns an `IndexedDbVersion` migration chain into an
5 * `IndexedDbDatabase` layer. The layer opens the browser database, runs any
6 * pending upgrade migrations, provides a query builder for the current schema,
7 * and exposes a `rebuild` effect that deletes and reopens the database.
8 * Migration transactions can create or delete object stores and indexes, and
9 * database failures are represented as `IndexedDbDatabaseError` values.
10 *
11 * @stability unstable
12 * @since 4.0.0
13 */
14 import * as Context from "effect/Context"
15 import * as Data from "effect/Data"
16 import * as Effect from "effect/Effect"
17 import * as Effectable from "effect/Effectable"
18 import * as Fiber from "effect/Fiber"
19 import * as Layer from "effect/Layer"
20 import * as MutableRef from "effect/MutableRef"
21 import * as Reactivity from "effect/reactivity/Reactivity"
22 import * as Semaphore from "effect/Semaphore"
23 import * as IndexedDb from "./IndexedDb.ts"
24 import * as IndexedDbQueryBuilder from "./IndexedDbQueryBuilder.ts"
25 import type * as IndexedDbTable from "./IndexedDbTable.ts"
26 import type * as IndexedDbVersion from "./IndexedDbVersion.ts"
27
28 const TypeId = "~@effect/platform-browser/IndexedDbDatabase"
29 const ErrorTypeId = "~@effect/platform-browser/IndexedDbDatabase/IndexedDbDatabaseError"
30
31 const SchemaProto = {
32 [TypeId]: {
33 _A: (_: never) => _
34 },
35 get getQueryBuilder() {
36 const self = this as unknown as IndexedDbSchema<any, any, any>
37 return IndexedDbDatabase.useSync(({ database, IDBKeyRange, reactivity }) =>
38 IndexedDbQueryBuilder.make({
39 database,
40 IDBKeyRange,
41 tables: self.version.tables,
42 reactivity
43 })
44 )
45 },
46 ...Effectable.Prototype<IndexedDbSchema<any, any, any>>({
47 label: "IndexedDbSchema",
48 evaluate() {
49 return this.getQueryBuilder
50 }
51 }),
52 add<Version extends IndexedDbVersion.AnyWithProps>(
53 this: IndexedDbSchema<any, any, any>,
54 version: Version,
55 migrate: (
56 fromQuery: Transaction<any>,
57 toQuery: Transaction<Version>
58 ) => Effect.Effect<void, Error>
59 ) {
60 return makeMigration({
61 fromVersion: this.version,
62 version,
63 migrate,
64 previous: this
65 })
66 },
67 layer(this: IndexedDbSchema<any, any, any>, databaseName: string) {
68 return layer(databaseName, this)
69 }
70 }
71
72 /**
73 * String union describing the failure categories for IndexedDB database opening, migration, and schema operations.
74 *
75 * @stability unstable
76 * @category errors
77 * @since 4.0.0
78 */
79 export type ErrorReason =
80 | "TransactionError"
81 | "MissingTable"
82 | "OpenError"
83 | "UpgradeError"
84 | "Aborted"
85 | "Blocked"
86 | "MissingIndex"
87
88 /**
89 * Tagged error for IndexedDB database operations, carrying a database error reason and the original cause.
90 *
91 * @stability unstable
92 * @category errors
93 * @since 4.0.0
94 */
95 export class IndexedDbDatabaseError extends Data.TaggedError(
96 "IndexedDbDatabaseError"
97 )<{
98 reason: ErrorReason
99 cause: unknown
100 }> {
101 /**
102 * Marks this value as an IndexedDB database error for runtime guards.
103 *
104 * @since 4.0.0
105 */
106 readonly [ErrorTypeId]: typeof ErrorTypeId = ErrorTypeId
107 override readonly message = this.reason
108 }
109
110 /**
111 * Service tag for an open IndexedDB database, its `IDBKeyRange` constructor, reactivity service, and rebuild effect.
112 *
113 * **When to use**
114 *
115 * Use when you need access to the live database service after an
116 * `IndexedDbSchema` layer has been provided, especially for `rebuild` or
117 * lower-level database primitives.
118 *
119 * **Details**
120 *
121 * `database` is a mutable reference to the current `IDBDatabase`. `IDBKeyRange`
122 * and `reactivity` are shared with query builders created from the schema.
123 *
124 * **Gotchas**
125 *
126 * `rebuild` closes and deletes the browser database, then reopens it and reruns
127 * migrations. Records not recreated by migrations are removed.
128 *
129 * @see {@link IndexedDb.IndexedDb} for the lower-level browser IndexedDB primitives
130 * @see {@link make} for creating a schema that provides this service as a layer
131 *
132 * @stability unstable
133 * @category services
134 * @since 4.0.0
135 */
136 export class IndexedDbDatabase extends Context.Service<
137 IndexedDbDatabase,
138 {
139 readonly database: MutableRef.MutableRef<globalThis.IDBDatabase>
140 readonly IDBKeyRange: typeof globalThis.IDBKeyRange
141 readonly reactivity: Reactivity.Reactivity
142 readonly rebuild: Effect.Effect<void, IndexedDbDatabaseError>
143 }
144 >()(TypeId) {}
145
146 /**
147 * Describes an IndexedDB schema version and its migrations, and acts as an effect that yields a query builder for the target version.
148 *
149 * @stability unstable
150 * @category models
151 * @since 4.0.0
152 */
153 export interface IndexedDbSchema<
154 in out FromVersion extends IndexedDbVersion.AnyWithProps,
155 in out ToVersion extends IndexedDbVersion.AnyWithProps,
156 out Error = never
157 > extends
158 Effect.Effect<
159 IndexedDbQueryBuilder.IndexedDbQueryBuilder<ToVersion>,
160 never,
161 IndexedDbDatabase
162 >
163 {
164 new(_: never): {}
165
166 readonly previous: [FromVersion] extends [never] ? undefined
167 : IndexedDbSchema<never, FromVersion, Error>
168 readonly fromVersion: FromVersion
169 readonly version: ToVersion
170
171 readonly migrate: [FromVersion] extends [never] ? (query: Transaction<ToVersion>) => Effect.Effect<void, Error>
172 : (
173 fromQuery: Transaction<FromVersion>,
174 toQuery: Transaction<ToVersion>
175 ) => Effect.Effect<void, Error>
176
177 readonly add: <Version extends IndexedDbVersion.AnyWithProps, MigrationError>(
178 version: Version,
179 migrate: (
180 fromQuery: Transaction<ToVersion>,
181 toQuery: Transaction<Version>
182 ) => Effect.Effect<void, MigrationError>
183 ) => IndexedDbSchema<ToVersion, Version, MigrationError | Error>
184
185 readonly getQueryBuilder: Effect.Effect<
186 IndexedDbQueryBuilder.IndexedDbQueryBuilder<ToVersion>,
187 never,
188 IndexedDbDatabase
189 >
190
191 readonly layer: (
192 databaseName: string
193 ) => Layer.Layer<
194 IndexedDbDatabase,
195 IndexedDbDatabaseError,
196 IndexedDb.IndexedDb
197 >
198 }
199
200 /**
201 * Query builder available during a database migration, extended with object-store and index management helpers for the active `IDBTransaction`.
202 *
203 * @stability unstable
204 * @category models
205 * @since 4.0.0
206 */
207 export interface Transaction<
208 Source extends IndexedDbVersion.AnyWithProps = never
209 > extends Omit<IndexedDbQueryBuilder.IndexedDbQueryBuilder<Source>, "transaction"> {
210 readonly transaction: globalThis.IDBTransaction
211
212 readonly createObjectStore: <
213 A extends IndexedDbTable.TableName<IndexedDbVersion.Tables<Source>>
214 >(
215 table: A
216 ) => Effect.Effect<globalThis.IDBObjectStore, IndexedDbDatabaseError>
217
218 readonly deleteObjectStore: <
219 A extends IndexedDbTable.TableName<IndexedDbVersion.Tables<Source>>
220 >(
221 table: A
222 ) => Effect.Effect<void, IndexedDbDatabaseError>
223
224 readonly createIndex: <
225 Name extends IndexedDbTable.TableName<IndexedDbVersion.Tables<Source>>
226 >(
227 table: Name,
228 indexName: IndexFromTableName<Source, Name>,
229 options?: IDBIndexParameters
230 ) => Effect.Effect<globalThis.IDBIndex, IndexedDbDatabaseError>
231
232 readonly deleteIndex: <
233 Name extends IndexedDbTable.TableName<IndexedDbVersion.Tables<Source>>
234 >(
235 table: Name,
236 indexName: IndexFromTableName<Source, Name>
237 ) => Effect.Effect<void, IndexedDbDatabaseError>
238 }
239
240 /**
241 * Extracts the string-literal index names defined by an `IndexedDbTable`.
242 *
243 * @stability unstable
244 * @category utility types
245 * @since 4.0.0
246 */
247 export type IndexFromTable<Table extends IndexedDbTable.AnyWithProps> = IsStringLiteral<
248 Extract<keyof IndexedDbTable.Indexes<Table>, string>
249 > extends true ? Extract<keyof IndexedDbTable.Indexes<Table>, string>
250 : never
251
252 /**
253 * Extracts the valid index names for a table name within an IndexedDB version.
254 *
255 * @stability unstable
256 * @category utility types
257 * @since 4.0.0
258 */
259 export type IndexFromTableName<
260 Version extends IndexedDbVersion.AnyWithProps,
261 Table extends string
262 > = IndexFromTable<
263 IndexedDbTable.WithName<IndexedDbVersion.Tables<Version>, Table>
264 >
265
266 /**
267 * Type-erased IndexedDB schema shape used when traversing schema migration chains.
268 *
269 * @stability unstable
270 * @category models
271 * @since 4.0.0
272 */
273 export interface Any {
274 readonly previous?: Any | undefined
275 readonly layer: (
276 databaseName: string
277 ) => Layer.Layer<
278 IndexedDbDatabase,
279 IndexedDbDatabaseError,
280 IndexedDb.IndexedDb
281 >
282 }
283
284 /**
285 * Type-erased `IndexedDbSchema` covering any source version, target version, and migration error type.
286 *
287 * @stability unstable
288 * @category models
289 * @since 4.0.0
290 */
291 export type AnySchema = IndexedDbSchema<
292 IndexedDbVersion.AnyWithProps,
293 IndexedDbVersion.AnyWithProps,
294 any
295 >
296
297 /**
298 * Creates the initial `IndexedDbSchema` from a version and an initialization migration run during database upgrade.
299 *
300 * @stability unstable
301 * @category constructors
302 * @since 4.0.0
303 */
304 export const make = <
305 InitialVersion extends IndexedDbVersion.AnyWithProps,
306 Error
307 >(
308 initialVersion: InitialVersion,
309 init: (toQuery: Transaction<InitialVersion>) => Effect.Effect<void, Error>
310 ): IndexedDbSchema<never, InitialVersion, Error> => {
311 // oxlint-disable-next-line typescript/no-extraneous-class
312 function Initial() {}
313 Object.setPrototypeOf(Initial, SchemaProto)
314 ;(Initial as any).version = initialVersion
315 ;(Initial as any).migrate = init
316 return Initial as any
317 }
318
319 const makeMigration = <
320 FromVersion extends IndexedDbVersion.AnyWithProps,
321 ToVersion extends IndexedDbVersion.AnyWithProps,
322 Error
323 >(options: {
324 readonly previous:
325 | IndexedDbSchema<FromVersion, ToVersion, Error>
326 | IndexedDbSchema<never, FromVersion, Error>
327 readonly fromVersion: FromVersion
328 readonly version: ToVersion
329 readonly migrate: (
330 fromQuery: Transaction<FromVersion>,
331 toQuery: Transaction<ToVersion>
332 ) => Effect.Effect<void, Error>
333 }): IndexedDbSchema<FromVersion, ToVersion, Error> => {
334 // oxlint-disable-next-line typescript/no-extraneous-class
335 function Migration() {}
336 Object.setPrototypeOf(Migration, SchemaProto)
337 ;(Migration as any).previous = options.previous
338 ;(Migration as any).fromVersion = options.fromVersion
339 ;(Migration as any).version = options.version
340 ;(Migration as any).migrate = options.migrate
341
342 return Migration as any
343 }
344
345 const layer = <DatabaseName extends string>(
346 databaseName: DatabaseName,
347 migration: Any
348 ) =>
349 Layer.effect(
350 IndexedDbDatabase,
351 Effect.gen(function*() {
352 const { IDBKeyRange, indexedDB } = yield* IndexedDb.IndexedDb
353 const reactivity = yield* Reactivity.Reactivity
354 const context = yield* Effect.context()
355 const runForkWith = Effect.runForkWith(context)
356
357 let oldVersion = 0
358 const migrations: Array<Any> = []
359 let current = migration
360 while (current) {
361 migrations.unshift(current)
362 current = (current as unknown as AnySchema).previous as any
363 }
364
365 const version = migrations.length
366 const database = MutableRef.make<globalThis.IDBDatabase>(null as any)
367
368 const open = Effect.callback<
369 void,
370 IndexedDbDatabaseError
371 >((resume) => {
372 const request = indexedDB.open(databaseName, version)
373
374 request.onblocked = (event) => {
375 resume(
376 Effect.fail(
377 new IndexedDbDatabaseError({
378 reason: "Blocked",
379 cause: event
380 })
381 )
382 )
383 }
384
385 request.onerror = (event) => {
386 const idbRequest = event.target as IDBRequest<IDBDatabase>
387
388 resume(
389 Effect.fail(
390 new IndexedDbDatabaseError({
391 reason: "OpenError",
392 cause: idbRequest.error
393 })
394 )
395 )
396 }
397
398 let fiber: Fiber.Fiber<void, IndexedDbDatabaseError> | undefined
399 request.onupgradeneeded = (event) => {
400 const idbRequest = event.target as IDBRequest<IDBDatabase>
401 const db = idbRequest.result
402 const transaction = idbRequest.transaction
403 oldVersion = event.oldVersion
404
405 MutableRef.set(database, db)
406
407 if (transaction === null) {
408 return resume(
409 Effect.fail(
410 new IndexedDbDatabaseError({
411 reason: "TransactionError",
412 cause: null
413 })
414 )
415 )
416 }
417
418 transaction.onabort = (event) => {
419 resume(
420 Effect.fail(
421 new IndexedDbDatabaseError({
422 reason: "Aborted",
423 cause: event
424 })
425 )
426 )
427 }
428
429 transaction.onerror = (event) => {
430 resume(
431 Effect.fail(
432 new IndexedDbDatabaseError({
433 reason: "TransactionError",
434 cause: event
435 })
436 )
437 )
438 }
439
440 const effect = Effect.forEach(
441 migrations.slice(oldVersion),
442 (untypedMigration) => {
443 if (untypedMigration.previous === undefined) {
444 const migration = untypedMigration as any as AnySchema
445 const api = makeTransactionProto({
446 database,
447 IDBKeyRange,
448 tables: migration.version.tables,
449 transaction,
450 reactivity
451 })
452 return (migration as any).migrate(api) as Effect.Effect<
453 void,
454 IndexedDbDatabaseError
455 >
456 } else if (untypedMigration.previous) {
457 const migration = untypedMigration as any as AnySchema
458 const fromApi = makeTransactionProto({
459 database,
460 IDBKeyRange,
461 tables: migration.fromVersion.tables,
462 transaction,
463 reactivity
464 })
465 const toApi = makeTransactionProto({
466 database,
467 IDBKeyRange,
468 tables: migration.version.tables,
469 transaction,
470 reactivity
471 })
472 return migration.migrate(fromApi, toApi) as Effect.Effect<
473 void,
474 IndexedDbDatabaseError
475 >
476 }
477
478 return Effect.die(new Error("Invalid migration"))
479 },
480 { discard: true }
481 ).pipe(
482 Effect.mapError(
483 (cause) =>
484 new IndexedDbDatabaseError({
485 reason: "UpgradeError",
486 cause
487 })
488 ),
489 Effect.provideService(IndexedDbQueryBuilder.IndexedDbTransaction, transaction)
490 )
491 fiber = runForkWith(effect)
492 fiber.addObserver((exit) => {
493 if (exit._tag === "Failure") {
494 transaction.abort()
495 resume(exit)
496 }
497 })
498 fiber.currentDispatcher.flush()
499 }
500
501 request.onsuccess = (event) => {
502 const idbRequest = event.target as IDBRequest<IDBDatabase>
503 const db = idbRequest.result
504 MutableRef.set(database, db)
505 if (fiber) {
506 // ensure migration errors are propagated
507 resume(Effect.asVoid(Fiber.join(fiber)))
508 } else {
509 resume(Effect.void)
510 }
511 }
512 })
513
514 yield* Effect.addFinalizer(() => {
515 database.current?.close()
516 return Effect.void
517 })
518 yield* open
519
520 const rebuildLock = Semaphore.makeUnsafe(1).withPermit
521 const rebuild = Effect.callback<void, IndexedDbDatabaseError>((resume) => {
522 database.current?.close()
523 const request = indexedDB.deleteDatabase(databaseName)
524 request.onerror = (_) => {
525 resume(
526 Effect.fail(
527 new IndexedDbDatabaseError({
528 reason: "OpenError",
529 cause: request.error
530 })
531 )
532 )
533 }
534 request.onsuccess = () => {
535 resume(Effect.void)
536 }
537 }).pipe(
538 Effect.flatMap(() => open),
539 rebuildLock
540 )
541
542 return IndexedDbDatabase.of({ database, IDBKeyRange, rebuild, reactivity })
543 })
544 ).pipe(
545 Layer.provide(Reactivity.layer)
546 )
547
548 // -----------------------------------------------------------------------------
549 // Internal
550 // -----------------------------------------------------------------------------
551
552 type IsStringLiteral<T> = T extends string ? string extends T ? false
553 : true
554 : false
555
556 const makeTransactionProto = <Source extends IndexedDbVersion.AnyWithProps>({
557 IDBKeyRange,
558 database,
559 tables,
560 transaction,
561 reactivity
562 }: {
563 readonly database: MutableRef.MutableRef<globalThis.IDBDatabase>
564 readonly IDBKeyRange: typeof globalThis.IDBKeyRange
565 readonly tables: ReadonlyMap<string, IndexedDbVersion.Tables<Source>>
566 readonly transaction: globalThis.IDBTransaction
567 readonly reactivity: Reactivity.Reactivity
568 }): Transaction<Source> => {
569 const migration = IndexedDbQueryBuilder.make({
570 database,
571 IDBKeyRange,
572 tables,
573 reactivity
574 }) as any
575
576 migration.transaction = transaction
577
578 migration.createObjectStore = Effect.fnUntraced(function*(table: string) {
579 const createTable = yield* Effect.fromNullishOr(tables.get(table)).pipe(
580 Effect.mapError(
581 (cause) =>
582 new IndexedDbDatabaseError({
583 reason: "MissingTable",
584 cause
585 })
586 )
587 )
588
589 return yield* Effect.try({
590 try: () =>
591 database.current.createObjectStore(createTable.tableName, {
592 keyPath: createTable.keyPath,
593 autoIncrement: createTable.autoIncrement
594 }),
595 catch: (cause) =>
596 new IndexedDbDatabaseError({
597 reason: "TransactionError",
598 cause
599 })
600 })
601 })
602
603 migration.deleteObjectStore = Effect.fnUntraced(function*(table: string) {
604 const createTable = yield* Effect.fromNullishOr(tables.get(table)).pipe(
605 Effect.mapError(
606 (cause) =>
607 new IndexedDbDatabaseError({
608 reason: "MissingTable",
609 cause
610 })
611 )
612 )
613
614 return yield* Effect.try({
615 try: () => database.current.deleteObjectStore(createTable.tableName),
616 catch: (cause) =>
617 new IndexedDbDatabaseError({
618 reason: "TransactionError",
619 cause
620 })
621 })
622 })
623
624 migration.createIndex = Effect.fnUntraced(function*(
625 table: string,
626 indexName: string,
627 options?: IDBIndexParameters
628 ) {
629 const store = transaction.objectStore(table)
630 const sourceTable = tables.get(table)!
631
632 const keyPath = yield* Effect.fromNullishOr(
633 sourceTable.indexes[indexName]
634 ).pipe(
635 Effect.mapError(
636 (cause) =>
637 new IndexedDbDatabaseError({
638 reason: "MissingIndex",
639 cause
640 })
641 )
642 )
643
644 return yield* Effect.try({
645 try: () => store.createIndex(indexName, keyPath, options),
646 catch: (cause) =>
647 new IndexedDbDatabaseError({
648 reason: "TransactionError",
649 cause
650 })
651 })
652 })
653
654 migration.deleteIndex = (table: string, indexName: string) =>
655 Effect.try({
656 try: () => transaction.objectStore(table).deleteIndex(indexName),
657 catch: (cause) =>
658 new IndexedDbDatabaseError({
659 reason: "TransactionError",
660 cause
661 })
662 })
663
664 return migration
665 }