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

main
ts 337 lines 10.2 KB
Raw
1 /**
2 * IndexedDB-backed persistence layers for browser Effect programs.
3 *
4 * This module provides a low-level `BackingPersistence` layer and a higher-level
5 * `Persistence` layer that store object values in IndexedDB. Values are stored
6 * by persistence store id and key, and reads check TTL expiration before
7 * returning stored data. The database name can be customized and defaults to
8 * `"effect_persistence"`.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13 import type * as Arr from "effect/Array"
14 import * as Clock from "effect/Clock"
15 import type * as Duration from "effect/Duration"
16 import * as Effect from "effect/Effect"
17 import * as Layer from "effect/Layer"
18 import * as Persistence from "effect/persistence/Persistence"
19
20 /**
21 * Creates a `BackingPersistence` layer backed by IndexedDB, optionally using the provided database name.
22 *
23 * **When to use**
24 *
25 * Use when composing persistence manually and the lower-level
26 * `BackingPersistence` service should be backed by browser IndexedDB.
27 *
28 * **Details**
29 *
30 * The database name defaults to `"effect_persistence"`. Entries are stored by
31 * persistence store id and key in a shared object store, and TTL expiration is
32 * checked when values are read.
33 *
34 * **Gotchas**
35 *
36 * Opening the database is defected during layer acquisition if IndexedDB is
37 * unavailable or cannot be opened. Store operations report `PersistenceError`
38 * for IndexedDB request, transaction, quota, and structured-clone failures.
39 *
40 * @see {@link layerIndexedDb} for providing the higher-level `Persistence` service
41 *
42 * @stability unstable
43 * @category layers
44 * @since 4.0.0
45 */
46 export const layerBackingIndexedDb = (options?: {
47 readonly database?: string | undefined
48 }): Layer.Layer<Persistence.BackingPersistence> =>
49 Layer.effect(Persistence.BackingPersistence)(Effect.gen(function*() {
50 const db = yield* Effect.acquireRelease(
51 openDatabase(options?.database ?? defaultDatabase),
52 (db) => Effect.sync(() => db.close())
53 ).pipe(Effect.orDie)
54
55 return Persistence.BackingPersistence.of({
56 make: Effect.fnUntraced(function*(storeId) {
57 const clock = yield* Clock.Clock
58 return {
59 get: (key) => get(db, clock, storeId, key),
60 getMany: (keys) => getMany(db, clock, storeId, keys),
61 set: (key, value, ttl) => set(db, clock, storeId, key, value, ttl),
62 setMany: (entries) => setMany(db, clock, storeId, entries),
63 remove: (key) => remove(db, storeId, key),
64 clear: clear(db, storeId)
65 }
66 })
67 })
68 }))
69
70 const defaultDatabase = "effect_persistence"
71 const databaseVersion = 1
72 const entriesStoreName = "entries"
73 const storeIdIndexName = "storeId"
74
75 /**
76 * Creates a `Persistence` layer backed by IndexedDB, optionally using the provided database name.
77 *
78 * @stability unstable
79 * @category layers
80 * @since 4.0.0
81 */
82 export const layerIndexedDb = (options?: {
83 readonly database?: string | undefined
84 }): Layer.Layer<Persistence.Persistence> =>
85 Persistence.layer.pipe(
86 Layer.provide(layerBackingIndexedDb(options))
87 )
88
89 const openDatabase = (database: string): Effect.Effect<IDBDatabase, Persistence.PersistenceError> =>
90 Effect.gen(function*() {
91 const openRequest = yield* Effect.try({
92 try: () => globalThis.indexedDB.open(database, databaseVersion),
93 catch: (cause) =>
94 new Persistence.PersistenceError({
95 message: "Failed to open backing store database",
96 cause
97 })
98 })
99
100 openRequest.onupgradeneeded = () => {
101 const db = openRequest.result
102 const entries = db.objectStoreNames.contains(entriesStoreName)
103 ? openRequest.transaction?.objectStore(entriesStoreName)
104 : db.createObjectStore(entriesStoreName, { keyPath: ["storeId", "id"] })
105 if (entries && !entries.indexNames.contains(storeIdIndexName)) {
106 entries.createIndex(storeIdIndexName, storeIdIndexName, { unique: false })
107 }
108 }
109
110 return yield* idbRequest("Failed to open backing store database", () => openRequest)
111 })
112
113 interface EntryRow {
114 readonly storeId: string
115 readonly id: string
116 readonly value: object
117 readonly expires: number | null
118 }
119
120 const isExpired = (row: EntryRow, now: number): boolean => row.expires !== null && row.expires <= now
121
122 const get = (
123 db: IDBDatabase,
124 clock: Clock.Clock,
125 storeId: string,
126 key: string
127 ): Effect.Effect<object | undefined, Persistence.PersistenceError> =>
128 withEntriesTransaction<object | undefined>(
129 db,
130 "readwrite",
131 `Failed to get key ${key} from backing store`,
132 (
133 entries,
134 setResult,
135 fail
136 ) => {
137 const now = clock.currentTimeMillisUnsafe()
138 const id: [string, string] = [storeId, key]
139 const request = entries.get(id)
140 request.onerror = () => fail(request.error)
141 request.onsuccess = () => {
142 const row = request.result as EntryRow | undefined
143 if (!row || !isExpired(row, now)) {
144 setResult(row?.value)
145 return
146 }
147
148 const deleteRequest = entries.delete(id)
149 deleteRequest.onerror = () => fail(deleteRequest.error)
150 deleteRequest.onsuccess = () => setResult(undefined)
151 }
152 }
153 )
154
155 const getMany = (
156 db: IDBDatabase,
157 clock: Clock.Clock,
158 storeId: string,
159 keys: Arr.NonEmptyArray<string>
160 ): Effect.Effect<Arr.NonEmptyArray<object | undefined>, Persistence.PersistenceError> =>
161 withEntriesTransaction(
162 db,
163 "readwrite",
164 "Failed to getMany from backing store",
165 (entries, setResult, fail) => {
166 const now = clock.currentTimeMillisUnsafe()
167 const results = new Array<object | undefined>(keys.length)
168 setResult(results as any)
169
170 for (let i = 0; i < keys.length; i++) {
171 const key = keys[i]
172 const keyPath = [storeId, key]
173 const request = entries.get(keyPath)
174 request.onerror = () => fail(request.error)
175 request.onsuccess = () => {
176 const row = request.result as EntryRow | undefined
177 if (!row) return
178 else if (!isExpired(row, now)) {
179 results[i] = row.value
180 return
181 }
182 const deleteRequest = entries.delete(keyPath)
183 deleteRequest.onerror = () => fail(deleteRequest.error)
184 }
185 }
186 }
187 )
188
189 const set = (
190 db: IDBDatabase,
191 clock: Clock.Clock,
192 storeId: string,
193 key: string,
194 value: object,
195 ttl: Duration.Duration | undefined
196 ): Effect.Effect<void, Persistence.PersistenceError> =>
197 withEntriesTransaction(
198 db,
199 "readwrite",
200 `Failed to set key ${key} in backing store`,
201 (entries, setResult, fail) => {
202 const request = entries.put(
203 {
204 storeId,
205 id: key,
206 value,
207 expires: Persistence.unsafeTtlToExpires(clock, ttl)
208 } satisfies EntryRow
209 )
210 request.onerror = () => fail(request.error)
211 request.onsuccess = () => setResult(undefined)
212 }
213 )
214
215 const setMany = (
216 db: IDBDatabase,
217 clock: Clock.Clock,
218 storeId: string,
219 entries: Arr.NonEmptyArray<readonly [key: string, value: object, ttl: Duration.Duration | undefined]>
220 ): Effect.Effect<void, Persistence.PersistenceError> =>
221 withEntriesTransaction(
222 db,
223 "readwrite",
224 "Failed to setMany in backing store",
225 (store, setResult, fail) => {
226 for (const [key, value, ttl] of entries) {
227 const request = store.put(
228 {
229 storeId,
230 id: key,
231 value,
232 expires: Persistence.unsafeTtlToExpires(clock, ttl)
233 } satisfies EntryRow
234 )
235 request.onerror = () => fail(request.error)
236 request.onsuccess = () => setResult(undefined)
237 }
238 }
239 )
240
241 const remove = (
242 db: IDBDatabase,
243 storeId: string,
244 key: string
245 ): Effect.Effect<void, Persistence.PersistenceError> =>
246 withEntriesTransaction(
247 db,
248 "readwrite",
249 `Failed to remove key ${key} from backing store`,
250 (entries, setResult, fail) => {
251 const request = entries.delete([storeId, key])
252 request.onerror = () => fail(request.error)
253 request.onsuccess = () => setResult(undefined)
254 }
255 )
256
257 const clear = (db: IDBDatabase, storeId: string): Effect.Effect<void, Persistence.PersistenceError> =>
258 withEntriesTransaction(db, "readwrite", "Failed to clear backing store", (entries, setResult, fail) => {
259 const index = entries.index(storeIdIndexName)
260 const cursorRequest = index.openCursor(storeId)
261 cursorRequest.onerror = () => fail(cursorRequest.error)
262 cursorRequest.onsuccess = () => {
263 const cursor = cursorRequest.result
264 if (!cursor) {
265 setResult(undefined)
266 return
267 }
268 const deleteRequest = cursor.delete()
269 deleteRequest.onerror = () => fail(deleteRequest.error)
270 deleteRequest.onsuccess = () => cursor.continue()
271 }
272 })
273
274 const withEntriesTransaction = <A>(
275 db: IDBDatabase,
276 mode: IDBTransactionMode,
277 message: string,
278 run: (
279 entries: IDBObjectStore,
280 onResult: (result: A) => void,
281 fail: (cause: unknown) => void
282 ) => void
283 ): Effect.Effect<A, Persistence.PersistenceError> =>
284 Effect.callback<A, Persistence.PersistenceError>((resume) => {
285 const tx = db.transaction(entriesStoreName, mode)
286 const entries = tx.objectStore(entriesStoreName)
287
288 let result: A | undefined
289 let setResult = false
290 let done = false
291
292 const fail = (cause: unknown) => {
293 done = true
294 resume(Effect.fail(new Persistence.PersistenceError({ message, cause })))
295 }
296
297 tx.oncomplete = () => {
298 done = true
299 if (setResult) resume(Effect.succeed(result!))
300 }
301 tx.onerror = () => {
302 done = true
303 fail(tx.error)
304 }
305 tx.onabort = () => {
306 done = true
307 fail(tx.error)
308 }
309
310 run(entries, (next) => {
311 if (done) return resume(Effect.succeed(next))
312 setResult = true
313 result = next
314 }, fail)
315
316 return Effect.sync(() => {
317 tx.abort()
318 })
319 })
320
321 const idbRequest = <A>(
322 message: string,
323 evaluate: () => IDBRequest<A>
324 ): Effect.Effect<A, Persistence.PersistenceError> =>
325 Effect.callback<A, Persistence.PersistenceError>((resume) => {
326 const request = evaluate()
327 const fail = (cause: unknown) => {
328 resume(Effect.fail(new Persistence.PersistenceError({ message, cause })))
329 }
330 if (request.readyState === "done") {
331 resume(Effect.succeed(request.result))
332 }
333 request.onsuccess = () => {
334 resume(Effect.succeed(request.result))
335 }
336 request.onerror = () => fail(request.error)
337 })