app

Local-first trade for farms and co-ops
git clone https://radroots.dev/git/app.git
Log | Files | Refs | README | LICENSE

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 }