database.ts (5822B)
1 import { 2 browserDatabaseName, 3 browserSchemaVersion, 4 browserStores, 5 initializeBrowserSchema, 6 validateBrowserSchema, 7 type BrowserStore 8 } from './schema.ts'; 9 10 export type StorageFailure = 11 | 'unavailable' 12 | 'denied' 13 | 'blocked' 14 | 'cancelled' 15 | 'incompatible_version' 16 | 'migration_failed' 17 | 'corrupt_schema' 18 | 'open_failed'; 19 export type BrowserDatabase = Readonly<{ kind: 'browser_database' }>; 20 type Owner = { 21 database: IDBDatabase; 22 close(reason: 'explicit' | 'version_change' | 'connection_closed'): void; 23 snapshot(): Readonly<{ 24 state: 'ready' | 'closed'; 25 reason: 'explicit' | 'version_change' | 'connection_closed' | null; 26 }>; 27 }; 28 const owners = new WeakMap<BrowserDatabase, Owner>(); 29 export type DatabaseOpenResult = 30 | Readonly<{ state: 'ready'; owner: BrowserDatabase }> 31 | Readonly<{ 32 state: 'unavailable'; 33 reason: StorageFailure; 34 message: string; 35 }>; 36 37 function failure(reason: StorageFailure): DatabaseOpenResult { 38 return { 39 state: 'unavailable', 40 reason, 41 message: 42 'Browser storage is unavailable. You can still browse public listings. Existing local data has not been reset.' 43 }; 44 } 45 function classify(error: unknown): StorageFailure { 46 const name = error instanceof DOMException ? error.name : ''; 47 if (name === 'SecurityError' || name === 'NotAllowedError') return 'denied'; 48 if (name === 'VersionError') return 'incompatible_version'; 49 return 'open_failed'; 50 } 51 function ownerOf(owner: BrowserDatabase): Owner { 52 const value = owners.get(owner); 53 if (!value) throw new Error('invalid_database_owner'); 54 return value; 55 } 56 export function closeBrowserDatabase(owner: BrowserDatabase): void { 57 ownerOf(owner).close('explicit'); 58 } 59 export function browserDatabaseState(owner: BrowserDatabase) { 60 return ownerOf(owner).snapshot(); 61 } 62 63 // Explicit call only: importing this module never opens storage, including SSR. 64 export function openBrowserDatabase( 65 signal?: AbortSignal 66 ): Promise<DatabaseOpenResult> { 67 if (signal?.aborted) return Promise.resolve(failure('cancelled')); 68 let request: IDBOpenDBRequest; 69 try { 70 if (typeof indexedDB === 'undefined') 71 return Promise.resolve(failure('unavailable')); 72 request = indexedDB.open(browserDatabaseName, browserSchemaVersion); 73 } catch (error) { 74 return Promise.resolve(failure(classify(error))); 75 } 76 return new Promise((resolve) => { 77 let settled = false; 78 let migrationFailed = false; 79 function finish(result: DatabaseOpenResult): void { 80 if (settled) return; 81 settled = true; 82 signal?.removeEventListener('abort', cancel); 83 resolve(result); 84 } 85 function abortUpgrade(): void { 86 try { 87 request.transaction?.abort(); 88 } catch { 89 // Already completed/aborted; success still closes any late connection. 90 } 91 } 92 function cancel(): void { 93 finish(failure('cancelled')); 94 abortUpgrade(); 95 } 96 signal?.addEventListener('abort', cancel, { once: true }); 97 if (signal?.aborted) cancel(); 98 request.addEventListener('blocked', () => { 99 finish(failure('blocked')); 100 abortUpgrade(); 101 }); 102 request.addEventListener('upgradeneeded', (event) => { 103 if (settled) { 104 abortUpgrade(); 105 return; 106 } 107 try { 108 initializeBrowserSchema( 109 request.result, 110 event.oldVersion, 111 event.newVersion 112 ); 113 } catch { 114 migrationFailed = true; 115 abortUpgrade(); 116 } 117 }); 118 request.addEventListener('error', () => { 119 finish( 120 failure(migrationFailed ? 'migration_failed' : classify(request.error)) 121 ); 122 }); 123 request.addEventListener('success', () => { 124 const database = request.result; 125 if (settled) { 126 database.close(); 127 return; 128 } 129 try { 130 if (!validateBrowserSchema(database)) { 131 database.close(); 132 finish(failure('corrupt_schema')); 133 return; 134 } 135 } catch { 136 database.close(); 137 finish(failure('corrupt_schema')); 138 return; 139 } 140 const owner: BrowserDatabase = Object.freeze({ 141 kind: 'browser_database' 142 }); 143 let state: 'ready' | 'closed' = 'ready'; 144 let reason: 'explicit' | 'version_change' | 'connection_closed' | null = 145 null; 146 const value: Owner = { 147 database, 148 close(selected) { 149 if (state !== 'ready') return; 150 state = 'closed'; 151 reason = selected; 152 database.close(); 153 }, 154 snapshot() { 155 return { state, reason }; 156 } 157 }; 158 owners.set(owner, value); 159 database.addEventListener('versionchange', () => 160 value.close('version_change') 161 ); 162 database.addEventListener('close', () => 163 value.close('connection_closed') 164 ); 165 finish({ state: 'ready', owner }); 166 }); 167 }); 168 } 169 170 // Repositories own record validation and transaction completion/reconciliation. 171 // They must never hold this transaction across a signer or network await. 172 function validStores(value: unknown): value is readonly BrowserStore[] { 173 return ( 174 Array.isArray(value) && 175 value.length > 0 && 176 value.length <= browserStores.length && 177 new Set(value).size === value.length && 178 value.every((name: unknown) => 179 browserStores.some((allowed) => allowed === name) 180 ) 181 ); 182 } 183 export function browserDatabaseTransaction( 184 owner: BrowserDatabase, 185 stores: readonly BrowserStore[], 186 mode: 'readonly' | 'readwrite' 187 ): IDBTransaction { 188 const value = ownerOf(owner); 189 if (value.snapshot().state !== 'ready') throw new Error('database_closed'); 190 if (!validStores(stores) || (mode !== 'readonly' && mode !== 'readwrite')) 191 throw new Error('invalid_database_transaction'); 192 return value.database.transaction([...stores], mode); 193 }