arcane-os 0.2.2 → 0.3.0

package/runtime/arcane/modules/RecordReviewStore.js

@@ -1,8 +1,111 @@
+import {createArcaneEventSource} from 'arcane-os/event-manager';
 import {resolveApplicationLocalStorageKey} from './AppDataScope.js';
 
+export const RECORD_REVIEW_STORE_ERROR_CODES=Object.freeze({
+    adapterInvalid:'ARCANE_RECORD_REVIEW_STORE_ADAPTER_INVALID',
+    disposed:'ARCANE_RECORD_REVIEW_STORE_DISPOSED',
+    operationAborted:'ARCANE_RECORD_REVIEW_STORE_OPERATION_ABORTED',
+    operationOptionsInvalid:'ARCANE_RECORD_REVIEW_STORE_OPERATION_OPTIONS_INVALID',
+    recordIdInvalid:'ARCANE_RECORD_REVIEW_ID_INVALID',
+    storedRecordsInvalid:'ARCANE_RECORD_REVIEW_STORED_RECORDS_INVALID'
+});
+
+export const RECORD_REVIEW_STORE_EVENT_TYPES=Object.freeze({
+    change:'record-review-change'
+});
+
+function recordReviewStoreError(code,reason,message,ErrorType=Error,cause){
+    const error=new ErrorType(message);
+    error.code=code;
+    error.reason=reason;
+    if(cause!==undefined) error.cause=cause;
+    return error;
+}
+
+function disposedError(){
+    return recordReviewStoreError(
+        RECORD_REVIEW_STORE_ERROR_CODES.disposed,
+        'record-review-store-disposed',
+        'The record review store has been disposed.'
+    );
+}
+
+function operationAbortedError(reason){
+    const error=recordReviewStoreError(
+        RECORD_REVIEW_STORE_ERROR_CODES.operationAborted,
+        'record-review-operation-aborted',
+        'The record review operation was aborted.',
+        Error,
+        reason
+    );
+    error.name='AbortError';
+    return error;
+}
+
+function isPlainRecord(value){
+    if(!value||typeof value!=='object'||Array.isArray(value)) return false;
+    const prototype=Object.getPrototypeOf(value);
+    return prototype===Object.prototype||prototype===null;
+}
+
+function isAbortSignal(value){
+    return Boolean(value)
+        &&typeof value==='object'
+        &&typeof value.aborted==='boolean'
+        &&typeof value.addEventListener==='function'
+        &&typeof value.removeEventListener==='function';
+}
+
+function normalizeOperationOptions(value={}){
+    if(!isPlainRecord(value)){
+        throw recordReviewStoreError(
+            RECORD_REVIEW_STORE_ERROR_CODES.operationOptionsInvalid,
+            'record-review-operation-options-invalid',
+            'Record review operation options must be a plain object.',
+            TypeError
+        );
+    }
+    const keys=Reflect.ownKeys(value);
+    if(keys.some(function hasUnsupportedRecordReviewOperationOption(key){
+        return key!=='signal';
+    })){
+        throw recordReviewStoreError(
+            RECORD_REVIEW_STORE_ERROR_CODES.operationOptionsInvalid,
+            'record-review-operation-options-invalid',
+            'Record review operation options support only signal.',
+            TypeError
+        );
+    }
+    const signal=value.signal??null;
+    if(signal!==null&&!isAbortSignal(signal)){
+        throw recordReviewStoreError(
+            RECORD_REVIEW_STORE_ERROR_CODES.operationOptionsInvalid,
+            'record-review-operation-signal-invalid',
+            'Record review operation signal must be an AbortSignal.',
+            TypeError
+        );
+    }
+    return Object.freeze({signal});
+}
+
+function setDataProperty(target,key,value){
+    Object.defineProperty(
+        target,
+        key,
+        {configurable:true,enumerable:true,value,writable:true}
+    );
+}
+
 function normalizeRecordId(value=''){
     const id=String(value).trim();
-    if(!id||id.length>160||/[\x00-\x1f]/.test(id)) throw new TypeError('A valid record id is required.');
+    if(!id||id.length>160||/[\x00-\x1f]/.test(id)){
+        throw recordReviewStoreError(
+            RECORD_REVIEW_STORE_ERROR_CODES.recordIdInvalid,
+            'record-review-id-invalid',
+            'A valid record id is required.',
+            TypeError
+        );
+    }
     return id;
 }
 
@@ -13,18 +116,73 @@ function normalizeReview(value={}){
         for(const [key,value] of Object.entries(source.attributes).slice(0,40)){
             const normalizedKey=String(key).replace(/[^a-z0-9._-]/gi,'-').slice(0,80);
             if(!normalizedKey) continue;
-            attributes[normalizedKey]=Array.isArray(value)
-                ?value.slice(0,100).map(item=>String(item).slice(0,500))
-                :String(value??'').slice(0,10000);
+            setDataProperty(
+                attributes,
+                normalizedKey,
+                Array.isArray(value)
+                    ?Object.freeze(value.slice(0,100).map(function normalizeReviewAttributeItem(item){
+                        return String(item).slice(0,500);
+                    }))
+                    :String(value??'').slice(0,10000)
+            );
         }
     }
-    return {
+    return Object.freeze({
         status:String(source.status||'not-reviewed').trim().slice(0,80)||'not-reviewed',
         classification:String(source.classification||'unassigned').trim().slice(0,80)||'unassigned',
-        attributes,
+        attributes:Object.freeze(attributes),
         notes:String(source.notes||'').slice(0,10000),
         updatedAt:source.updatedAt?String(source.updatedAt):null
-    };
+    });
+}
+
+function frozenRecordMap(records){
+    const copy={};
+    for(const [id,review] of Object.entries(records)){
+        setDataProperty(copy,id,normalizeReview(review));
+    }
+    return Object.freeze(copy);
+}
+
+function normalizedStoredRecords(value){
+    if(!isPlainRecord(value)) return Object.freeze({});
+    const records={};
+    for(const [recordId,review] of Object.entries(value)){
+        let id;
+        try{
+            id=normalizeRecordId(recordId);
+        }catch(error){
+            throw recordReviewStoreError(
+                RECORD_REVIEW_STORE_ERROR_CODES.storedRecordsInvalid,
+                'record-review-stored-id-invalid',
+                'Stored record reviews contain an invalid record id.',
+                TypeError,
+                error
+            );
+        }
+        if(Object.prototype.hasOwnProperty.call(records,id)){
+            throw recordReviewStoreError(
+                RECORD_REVIEW_STORE_ERROR_CODES.storedRecordsInvalid,
+                'record-review-stored-id-collision',
+                'Stored record reviews contain colliding record ids.',
+                TypeError
+            );
+        }
+        setDataProperty(records,id,normalizeReview(review));
+    }
+    return Object.freeze(records);
+}
+
+function validateAdapter(adapter){
+    if(!adapter||typeof adapter.get!=='function'||typeof adapter.set!=='function'){
+        throw recordReviewStoreError(
+            RECORD_REVIEW_STORE_ERROR_CODES.adapterInvalid,
+            'record-review-storage-adapter-invalid',
+            'The record review storage adapter must provide get and set methods.',
+            TypeError
+        );
+    }
+    return adapter;
 }
 
 function localAdapter(namespace){
@@ -33,7 +191,11 @@ function localAdapter(namespace){
         async get(){
             const raw=globalThis.localStorage?.getItem(key);
             if(!raw) return {};
-            try{return JSON.parse(raw);}catch{return {};}
+            try{
+                return JSON.parse(raw);
+            }catch{
+                return {};
+            }
         },
         async set(value){
             globalThis.localStorage?.setItem(key,JSON.stringify(value));
@@ -51,24 +213,56 @@ function nativeAdapter(namespace){
             const result=await storage.get(key);
             return result?.value??result??{};
         },
-        async set(value){ await storage.set(key,value); return value; }
+        async set(value){
+            await storage.set(key,value);
+            return value;
+        }
     };
 }
 
 class RecordReviewStore extends EventTarget{
+    #disposed=false;
+    #events;
+    #operationSequence=0;
+    #operationTail=Promise.resolve();
+    #pendingOperations=new Set();
+
     constructor({namespace='records',adapter=null}={}){
         super();
         this.namespace=String(namespace||'records').replace(/[^a-z0-9._-]/gi,'-').slice(0,120);
-        this.adapter=adapter||nativeAdapter(this.namespace)||localAdapter(this.namespace);
-        this.records={};
+        this.adapter=validateAdapter(adapter||nativeAdapter(this.namespace)||localAdapter(this.namespace));
+        this.records=Object.freeze({});
         this.loaded=false;
+        this.#events=createArcaneEventSource(
+            this,
+            {
+                source:'record-review-store',
+                eventTypes:Object.freeze(Object.values(RECORD_REVIEW_STORE_EVENT_TYPES))
+            }
+        );
     }
 
-    async load(){
-        const stored=await this.adapter.get();
-        this.records=stored&&typeof stored==='object'&&!Array.isArray(stored)?stored:{};
-        this.loaded=true;
-        return this.snapshot();
+    addEventListener(type,listener,options){return this.#events.addEventListener(type,listener,options);}
+    removeEventListener(type,listener,options){return this.#events.removeEventListener(type,listener,options);}
+    on(type,listener,options){return this.#events.on(type,listener,options);}
+    dispatchEvent(value){return this.#events.dispatchEvent(value);}
+
+    async load(options={}){
+        const operation=normalizeOperationOptions(options);
+        const operationId=this.#nextOperationId('load');
+        const store=this;
+        return this.#enqueueOperation(
+            async function loadRecordReviews(){
+                const stored=await store.adapter.get(
+                    Object.freeze({operationId,signal:operation.signal})
+                );
+                store.#assertOperationActive(operation.signal);
+                store.records=normalizedStoredRecords(stored);
+                store.loaded=true;
+                return store.snapshot();
+            },
+            operation.signal
+        );
     }
 
     get(recordId){
@@ -76,17 +270,122 @@ class RecordReviewStore extends EventTarget{
         return normalizeReview(this.records[id]);
     }
 
-    async set(recordId,value={}){
+    async set(recordId,value={},options={}){
+        const operation=normalizeOperationOptions(options);
         const id=normalizeRecordId(recordId);
-        const review=normalizeReview({...this.get(id),...value,updatedAt:new Date().toISOString()});
-        this.records={...this.records,[id]:review};
-        await this.adapter.set(this.records);
-        this.dispatchEvent(new CustomEvent('record-review-change',{detail:{recordId:id,review:{...review}}}));
-        return {...review};
+        const operationId=this.#nextOperationId('set');
+        const store=this;
+        return this.#enqueueOperation(
+            async function setRecordReview(){
+                const review=normalizeReview({
+                    ...store.get(id),
+                    ...value,
+                    updatedAt:new Date().toISOString()
+                });
+                const records=frozenRecordMap({...store.records,[id]:review});
+                await store.adapter.set(
+                    records,
+                    Object.freeze({operationId,signal:operation.signal})
+                );
+                store.#assertOperationActive(operation.signal);
+                store.records=records;
+                const detail=Object.freeze({
+                    namespace:store.namespace,
+                    recordId:id,
+                    review:normalizeReview(review)
+                });
+                store.#events.dispatch(
+                    RECORD_REVIEW_STORE_EVENT_TYPES.change,
+                    detail,
+                    {operationId,publicDetail:detail}
+                );
+                return normalizeReview(review);
+            },
+            operation.signal
+        );
     }
 
     snapshot(){
-        return Object.fromEntries(Object.entries(this.records).map(([id,value])=>[id,normalizeReview(value)]));
+        return frozenRecordMap(this.records);
+    }
+
+    dispose(){
+        if(this.#disposed) return false;
+        this.#disposed=true;
+        const error=disposedError();
+        for(const cancel of [...this.#pendingOperations]) cancel(error);
+        return this.#events.dispose();
+    }
+
+    destroy(){return this.dispose();}
+
+    #assertOpen(){
+        if(this.#disposed) throw disposedError();
+    }
+
+    #assertOperationActive(signal){
+        this.#assertOpen();
+        if(signal?.aborted) throw operationAbortedError(signal.reason);
+    }
+
+    #nextOperationId(action){
+        this.#assertOpen();
+        this.#operationSequence+=1;
+        return `${this.#events.instanceId}:${action}:${this.#operationSequence.toString(36)}`;
+    }
+
+    #enqueueOperation(operation,signal){
+        this.#assertOperationActive(signal);
+        const store=this;
+        let abortHandler=null;
+        let rejectResult;
+        let resolveResult;
+        let settled=false;
+        const result=new Promise(function captureRecordReviewOperationSettlement(resolve,reject){
+            resolveResult=resolve;
+            rejectResult=reject;
+        });
+        function cleanupRecordReviewOperation(){
+            signal?.removeEventListener('abort',abortHandler);
+            store.#pendingOperations.delete(cancelRecordReviewOperation);
+        }
+        function settleRecordReviewOperation(handler,value){
+            if(settled) return false;
+            settled=true;
+            cleanupRecordReviewOperation();
+            handler(value);
+            return true;
+        }
+        function cancelRecordReviewOperation(error){
+            return settleRecordReviewOperation(rejectResult,error);
+        }
+        abortHandler=function abortRecordReviewOperation(){
+            cancelRecordReviewOperation(operationAbortedError(signal.reason));
+        };
+        store.#pendingOperations.add(cancelRecordReviewOperation);
+        signal?.addEventListener('abort',abortHandler,{once:true});
+        if(signal?.aborted) abortHandler();
+
+        async function runRecordReviewOperation(){
+            if(settled) return;
+            try{
+                store.#assertOperationActive(signal);
+                const value=await operation();
+                store.#assertOperationActive(signal);
+                settleRecordReviewOperation(resolveResult,value);
+            }catch(error){
+                settleRecordReviewOperation(rejectResult,error);
+            }
+        }
+        const queued=this.#operationTail.then(
+            runRecordReviewOperation,
+            runRecordReviewOperation
+        );
+        this.#operationTail=queued.then(
+            function completeRecordReviewOperationLane(){},
+            function recoverRecordReviewOperationLane(){}
+        );
+        return result;
     }
 }