draft-controller.ts (9542B)
1 import type { 2 PublicDraftForm, 3 PublicDraftRecord 4 } from '../contracts/local-records.ts'; 5 import { 6 capturePublicDraftCreate, 7 capturePublicDraftSave, 8 commitPublicDraftWrite, 9 observePublicDraftWrite, 10 publicDraftFormSnapshot, 11 publicDraftWriteSnapshot, 12 publicDraftRepositoryOwner, 13 readPublicDraft, 14 type PublicDraftRepository, 15 type PublicDraftWrite, 16 type DraftFailure 17 } from '../persistence/drafts.ts'; 18 19 declare const controllerBrand: unique symbol; 20 export type PublicDraftController = Readonly<{ [controllerBrand]: true }>; 21 export type DraftControllerSnapshot = Readonly<{ 22 form: PublicDraftForm; 23 editVersion: number; 24 savedEditVersion: number; 25 draft: PublicDraftRecord | null; 26 state: 'editing' | 'saving' | 'saved' | 'failed' | 'closed'; 27 failure: DraftFailure | null; 28 }>; 29 export type PublicDraftControllerOwnership = Readonly<{ 30 repository: PublicDraftRepository; 31 current( 32 this: void, 33 expectedWire: string, 34 expectedEditVersion: number 35 ): boolean; 36 }>; 37 type Controller = { 38 edit(form: unknown): boolean; 39 flush(): Promise<boolean>; 40 retry(): Promise<boolean>; 41 saveClose(): Promise<boolean>; 42 close(): void; 43 snapshot(): DraftControllerSnapshot; 44 ownership(): PublicDraftControllerOwnership; 45 }; 46 const controllers = new WeakMap<PublicDraftController, Controller>(); 47 export async function createPublicDraftController( 48 repository: PublicDraftRepository, 49 initialForm: unknown, 50 existingId?: string 51 ): Promise<PublicDraftController | undefined> { 52 if (!publicDraftRepositoryOwner(repository)) return undefined; 53 const initial = publicDraftFormSnapshot(initialForm); 54 if (!initial || !publicDraftRepositoryOwner(repository)) return undefined; 55 let saved: PublicDraftRecord | null = null; 56 if (existingId !== undefined) { 57 const read = await readPublicDraft(repository, existingId); 58 if (!read.ok || !publicDraftRepositoryOwner(repository)) return undefined; 59 saved = read.value; 60 } 61 let form = saved ? saved.form : initial; 62 let editVersion = 0, 63 savedEditVersion = saved ? 0 : -1; 64 let state: DraftControllerSnapshot['state'] = saved ? 'saved' : 'editing'; 65 let failure: DraftFailure | null = null; 66 let closed = false; 67 let active: Promise<void> | undefined; 68 let attempted: 69 Readonly<{ capturedWrite: PublicDraftWrite; version: number }> | undefined; 70 // Exactly one captured attempt survives unknown receipts. Pending form is 71 // separate; acknowledging a prior attempt never replaces that current form. 72 async function resolveAttempt(): Promise<boolean> { 73 const current = attempted; 74 if (!current || closed) return false; 75 state = 'saving'; 76 const expected = publicDraftWriteSnapshot( 77 repository, 78 current.capturedWrite 79 ); 80 if (!expected) { 81 failure = 'invalid_scope'; 82 state = 'failed'; 83 return false; 84 } 85 const result = await commitPublicDraftWrite( 86 repository, 87 current.capturedWrite 88 ); 89 if (closed) return false; 90 let receipt: PublicDraftRecord | undefined; 91 if (result.ok && JSON.stringify(result.value) === JSON.stringify(expected)) 92 receipt = result.value; 93 else if (!result.ok && result.reason === 'unknown_completion') { 94 const observed = await observePublicDraftWrite( 95 repository, 96 current.capturedWrite 97 ); 98 if (closed) return false; 99 if ( 100 observed.state === 'committed' && 101 JSON.stringify(observed.value) === JSON.stringify(expected) 102 ) 103 receipt = observed.value; 104 else 105 failure = 106 observed.state === 'conflict' 107 ? 'conflict' 108 : observed.state === 'unavailable' 109 ? observed.reason 110 : 'unknown_completion'; 111 } else failure = result.ok ? 'unknown_completion' : result.reason; 112 if (!receipt) { 113 state = 'failed'; 114 return false; 115 } 116 saved = receipt; 117 savedEditVersion = current.version; 118 attempted = undefined; 119 failure = null; 120 state = savedEditVersion === editVersion ? 'saved' : 'editing'; 121 return true; 122 } 123 async function pump(): Promise<void> { 124 while (!closed && failure === null && savedEditVersion !== editVersion) { 125 if (!attempted) { 126 const capturedVersion = editVersion; 127 const capturedForm = form; 128 const captured = saved 129 ? capturePublicDraftSave( 130 repository, 131 saved.id, 132 saved.revision, 133 capturedForm 134 ) 135 : capturePublicDraftCreate(repository, capturedForm); 136 if (closed) return; 137 if (!captured.ok) { 138 failure = captured.reason; 139 state = 'failed'; 140 return; 141 } 142 attempted = { capturedWrite: captured.value, version: capturedVersion }; 143 } 144 if (!(await resolveAttempt())) return; 145 } 146 } 147 function start(): Promise<void> { 148 if (active) return active; 149 // Queue one owned worker so synchronous edits coalesce before capture. 150 const work = Promise.resolve() 151 .then(pump) 152 .catch(() => { 153 if (!closed) { 154 failure = 'unknown_completion'; 155 state = 'failed'; 156 } 157 }) 158 .finally(() => { 159 active = undefined; 160 if (!closed && failure === null && savedEditVersion !== editVersion) 161 void start(); 162 }); 163 active = work; 164 return work; 165 } 166 const value: Controller = { 167 ownership() { 168 return { 169 repository, 170 current(expectedWire, expectedEditVersion) { 171 return ( 172 !closed && 173 failure === null && 174 state === 'saved' && 175 publicDraftRepositoryOwner(repository) !== undefined && 176 savedEditVersion === editVersion && 177 editVersion === expectedEditVersion && 178 saved !== null && 179 JSON.stringify(saved) === expectedWire 180 ); 181 } 182 }; 183 }, 184 edit(input) { 185 if (closed || editVersion === Number.MAX_SAFE_INTEGER) return false; 186 const next = publicDraftFormSnapshot(input); 187 if (!next || closed || editVersion === Number.MAX_SAFE_INTEGER) 188 return false; 189 form = next; 190 editVersion++; 191 if (failure === null) { 192 state = 'editing'; 193 void start(); 194 } 195 return true; 196 }, 197 async flush() { 198 if (closed || failure !== null) return false; 199 while (!closed && failure === null && savedEditVersion !== editVersion) 200 await start(); 201 return !closed && failure === null && savedEditVersion === editVersion; 202 }, 203 async retry() { 204 if (closed) return false; 205 if (active) await active; 206 if (closed) return false; 207 failure = null; 208 // Retained attempt is committed/read back as originally captured, never 209 // replaced with a new ID, time or payload during uncertain recovery. 210 while (!closed && failure === null && savedEditVersion !== editVersion) 211 await start(); 212 return !closed && failure === null && savedEditVersion === editVersion; 213 }, 214 async saveClose() { 215 while (await value.flush()) { 216 // The await permits a pending edit or lifecycle close. Check the exact 217 // current version and close together without another asynchronous gap. 218 if (closed || failure !== null) return false; 219 if (savedEditVersion !== editVersion) continue; 220 value.close(); 221 return true; 222 } 223 return false; 224 }, 225 close() { 226 if (closed) return; 227 closed = true; 228 state = 'closed'; 229 // A native transaction already submitted may complete; its late result 230 // cannot alter this closed controller or trigger another write. 231 attempted = undefined; 232 }, 233 snapshot() { 234 return { 235 form: { ...form }, 236 editVersion, 237 savedEditVersion, 238 draft: saved 239 ? (JSON.parse(JSON.stringify(saved)) as PublicDraftRecord) 240 : null, 241 state, 242 failure 243 }; 244 } 245 }; 246 const handle = Object.freeze({}) as PublicDraftController; 247 controllers.set(handle, value); 248 return handle; 249 } 250 export function editPublicDraft( 251 controller: PublicDraftController, 252 form: unknown 253 ): boolean { 254 return controllers.get(controller)?.edit(form) ?? false; 255 } 256 export function publicDraftControllerSnapshot( 257 controller: PublicDraftController 258 ): DraftControllerSnapshot | undefined { 259 return controllers.get(controller)?.snapshot(); 260 } 261 // Original controller/repository custody, not a copied saved-state boolean. 262 // This grants only an observation of the exact acknowledged draft revision. 263 export function publicDraftControllerOwnership( 264 controller: PublicDraftController 265 ): PublicDraftControllerOwnership | undefined { 266 return controllers.get(controller)?.ownership(); 267 } 268 export function flushPublicDraft( 269 controller: PublicDraftController 270 ): Promise<boolean> { 271 return controllers.get(controller)?.flush() ?? Promise.resolve(false); 272 } 273 export function retryPublicDraft( 274 controller: PublicDraftController 275 ): Promise<boolean> { 276 return controllers.get(controller)?.retry() ?? Promise.resolve(false); 277 } 278 // Ordinary save-close is gated by a successful flush. Lifecycle/identity 279 // teardown uses explicit close instead and makes no successful-save claim. 280 export function saveAndClosePublicDraft( 281 controller: PublicDraftController 282 ): Promise<boolean> { 283 return controllers.get(controller)?.saveClose() ?? Promise.resolve(false); 284 } 285 export function closePublicDraftController( 286 controller: PublicDraftController 287 ): void { 288 controllers.get(controller)?.close(); 289 }