Open History to see the last commit
1import {
2 InvalidPersistedCollectionConfigError,
3 PersistenceUnavailableError,
4} from '@tanstack/db-sqlite-persistence-core'
5import OPFSWorkerConstructor from './opfs-worker?worker'
6import type { BrowserWASQLiteDatabase } from './wa-sqlite-driver'
7import type {
8 BrowserOPFSWorkerErrorCode,
9 BrowserOPFSWorkerRequest,
10 BrowserOPFSWorkerResponse,
11} from './opfs-worker-protocol'
12
13const DEFAULT_VFS_NAME = `opfs`
14type BrowserOPFSFeatureGlobal = {
15 navigator?: {
16 storage?: {
17 getDirectory?: () => Promise<unknown>
18 }
19 }
20 Worker?: typeof Worker
21}
22
23export type OpenBrowserWASQLiteOPFSDatabaseOptions = {
24 databaseName: string
25 vfsName?: string
26}
27
28type BrowserOPFSWorkerLike = Pick<
29 Worker,
30 `postMessage` | `terminate` | `addEventListener` | `removeEventListener`
31>
32
33type PendingWorkerRequest = {
34 resolve: (value: unknown) => void
35 reject: (error: Error) => void
36}
37
38type BrowserOPFSWorkerRequestWithoutId =
39 BrowserOPFSWorkerRequest extends infer TRequest
40 ? TRequest extends { requestId: string }
41 ? Omit<TRequest, `requestId`>
42 : never
43 : never
44
45class OPFSWorkerRequestError extends Error {
46 constructor(
47 readonly code: BrowserOPFSWorkerErrorCode,
48 message: string,
49 ) {
50 super(message)
51 this.name = `OPFSWorkerRequestError`
52 }
53}
54
55function hasOPFSBrowserPrerequisites(globalObject: unknown): boolean {
56 const candidate = globalObject as BrowserOPFSFeatureGlobal
57 const getDirectory = candidate.navigator?.storage?.getDirectory
58 const WorkerConstructor = candidate.Worker
59
60 return (
61 typeof getDirectory === `function` &&
62 typeof WorkerConstructor === `function`
63 )
64}
65
66function createWorkerError(
67 code: BrowserOPFSWorkerErrorCode,
68 message: string,
69): Error {
70 if (code === `PERSISTENCE_UNAVAILABLE`) {
71 return new PersistenceUnavailableError(message)
72 }
73 if (code === `INVALID_CONFIG`) {
74 return new InvalidPersistedCollectionConfigError(message)
75 }
76 return new OPFSWorkerRequestError(code, message)
77}
78
79function createWorkerRequestIdFactory(): () => string {
80 let sequence = 0
81 const prefix = `opfs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
82
83 return () => {
84 sequence++
85 return `${prefix}-${sequence}`
86 }
87}
88
89function createOPFSWorkerInstance(): BrowserOPFSWorkerLike {
90 const WorkerConstructor = (
91 globalThis as typeof globalThis & { Worker?: typeof Worker }
92 ).Worker
93 if (typeof WorkerConstructor !== `function`) {
94 throw new PersistenceUnavailableError(
95 `Web Worker support is required for browser OPFS persistence`,
96 )
97 }
98
99 return new (OPFSWorkerConstructor as unknown as new () => BrowserOPFSWorkerLike)()
100}
101
102/**
103 * Creates a browser wa-sqlite database handle backed by OPFS and
104 * OPFSCoopSyncVFS.
105 */
106export async function openBrowserWASQLiteOPFSDatabase(
107 options: OpenBrowserWASQLiteOPFSDatabaseOptions,
108): Promise<BrowserWASQLiteDatabase> {
109 const databaseName = options.databaseName.trim()
110 if (databaseName.length === 0) {
111 throw new InvalidPersistedCollectionConfigError(
112 `Browser wa-sqlite databaseName cannot be empty`,
113 )
114 }
115
116 if (!hasOPFSBrowserPrerequisites(globalThis)) {
117 throw new PersistenceUnavailableError(
118 `Browser OPFS prerequisites are not available in this runtime`,
119 )
120 }
121
122 const vfsName = options.vfsName ?? DEFAULT_VFS_NAME
123 const worker = createOPFSWorkerInstance()
124 const nextRequestId = createWorkerRequestIdFactory()
125 const pendingRequests = new Map<string, PendingWorkerRequest>()
126 let disposed = false
127
128 const disposeWorker = (): void => {
129 if (disposed) {
130 return
131 }
132 disposed = true
133 worker.removeEventListener(`message`, onMessage)
134 worker.removeEventListener(`error`, onError)
135 worker.removeEventListener(`messageerror`, onMessageError)
136 worker.terminate()
137 }
138
139 const rejectAllPendingRequests = (error: Error): void => {
140 for (const pendingRequest of pendingRequests.values()) {
141 pendingRequest.reject(error)
142 }
143 pendingRequests.clear()
144 }
145
146 const onMessage = (event: Event): void => {
147 const messageEvent = event as MessageEvent<BrowserOPFSWorkerResponse>
148 const response = messageEvent.data
149
150 const pendingRequest = pendingRequests.get(response.requestId)
151 if (!pendingRequest) {
152 return
153 }
154 pendingRequests.delete(response.requestId)
155
156 if (response.ok) {
157 pendingRequest.resolve(response.rows ?? [])
158 return
159 }
160
161 pendingRequest.reject(createWorkerError(response.code, response.error))
162 }
163
164 const onError = (): void => {
165 rejectAllPendingRequests(
166 new PersistenceUnavailableError(`OPFS worker terminated unexpectedly`),
167 )
168 disposeWorker()
169 }
170
171 const onMessageError = (): void => {
172 rejectAllPendingRequests(
173 new PersistenceUnavailableError(
174 `OPFS worker message serialization failed`,
175 ),
176 )
177 disposeWorker()
178 }
179
180 worker.addEventListener(`message`, onMessage)
181 worker.addEventListener(`error`, onError)
182 worker.addEventListener(`messageerror`, onMessageError)
183
184 const sendWorkerRequest = <T>(
185 request: BrowserOPFSWorkerRequestWithoutId,
186 ): Promise<T> => {
187 if (disposed) {
188 return Promise.reject(
189 new InvalidPersistedCollectionConfigError(
190 `Browser OPFS worker connection is closed`,
191 ),
192 )
193 }
194
195 const requestId = nextRequestId()
196 return new Promise<T>((resolve, reject) => {
197 pendingRequests.set(requestId, {
198 resolve: (value) => {
199 resolve(value as T)
200 },
201 reject,
202 })
203 try {
204 const payload = {
205 ...request,
206 requestId,
207 } as BrowserOPFSWorkerRequest
208 worker.postMessage(payload)
209 } catch (error) {
210 pendingRequests.delete(requestId)
211 reject(
212 new PersistenceUnavailableError(
213 `Failed to send message to OPFS worker: ${(error as Error).message}`,
214 ),
215 )
216 }
217 })
218 }
219
220 try {
221 await sendWorkerRequest<void>({
222 type: `init`,
223 databaseName,
224 vfsName,
225 })
226 } catch (error) {
227 disposeWorker()
228 throw error
229 }
230
231 return {
232 execute: <TRow = unknown>(
233 sql: string,
234 params: ReadonlyArray<unknown> = [],
235 ) =>
236 sendWorkerRequest<ReadonlyArray<TRow>>({
237 type: `execute`,
238 sql,
239 params,
240 }),
241 close: async () => {
242 let closeError: unknown
243 try {
244 await sendWorkerRequest<void>({
245 type: `close`,
246 })
247 } catch (error) {
248 closeError = error
249 } finally {
250 disposeWorker()
251 }
252
253 if (closeError) {
254 throw closeError
255 }
256 },
257 }
258}