@prestizni-software/client-dem 0.10.2 → 0.11.0

package/AutoUpdatedClientObjectClass.js

@@ -47,6 +47,157 @@ export function createReadOnlyArrayProxy(rawArray, propertyName) {
         },
     });
 }
+/**
+ * Constructs a reactive DEMArray Proxy wrapper around entity array properties.
+ * Exposes synchronous queries on committed local state and asynchronous mutation Promises.
+ *
+ * @param parent - The entity object containing this array.
+ * @param propertyName - The name identifier of the array property.
+ * @param isRef - Whether this property holds cross-entity reference pointers.
+ * @param getItems - Function returning the currently resolved array items.
+ * @returns Reactive DEMArray proxy instance.
+ */
+export function createDEMArray(parent, propertyName, isRef, getItems) {
+    const dummyTarget = [];
+    return new Proxy(dummyTarget, {
+        get(_target, prop, receiver) {
+            if (prop === DEM_RAW_ARRAY) {
+                return parent.data?.[propertyName] ?? [];
+            }
+            if (prop === "push") {
+                return async (...items) => {
+                    return parent.mutateArrayQueue(propertyName, { op: "push", items }, isRef);
+                };
+            }
+            if (prop === "pop") {
+                return async () => {
+                    return parent.mutateArrayQueue(propertyName, { op: "pop" }, isRef);
+                };
+            }
+            if (prop === "shift") {
+                return async () => {
+                    return parent.mutateArrayQueue(propertyName, { op: "shift" }, isRef);
+                };
+            }
+            if (prop === "unshift") {
+                return async (...items) => {
+                    return parent.mutateArrayQueue(propertyName, { op: "unshift", items }, isRef);
+                };
+            }
+            if (prop === "splice") {
+                return async (start, deleteCount, ...items) => {
+                    const current = getItems();
+                    const actualDeleteCount = deleteCount !== undefined ? deleteCount : Math.max(0, current.length - start);
+                    const targetIds = [];
+                    for (let i = start; i < start + actualDeleteCount && i < current.length; i++) {
+                        const el = current[i];
+                        if (el && typeof el === "object" && "_id" in el) {
+                            targetIds.push(String(el._id));
+                        }
+                        else if (el) {
+                            targetIds.push(String(el));
+                        }
+                    }
+                    const targetId = targetIds[0];
+                    return parent.mutateArrayQueue(propertyName, {
+                        op: "splice",
+                        index: start,
+                        deleteCount: actualDeleteCount,
+                        items,
+                        targetId,
+                        targetIds,
+                    }, isRef);
+                };
+            }
+            if (prop === "set") {
+                return async (index, item) => {
+                    const current = getItems();
+                    const targetEl = current[index];
+                    const targetId = targetEl && typeof targetEl === "object" && "_id" in targetEl
+                        ? String(targetEl._id)
+                        : targetEl
+                            ? String(targetEl)
+                            : undefined;
+                    return parent.mutateArrayQueue(propertyName, { op: "set", index, items: [item], targetId }, isRef);
+                };
+            }
+            if (prop === "reverse") {
+                return async () => {
+                    return parent.mutateArrayQueue(propertyName, { op: "reverse" }, isRef);
+                };
+            }
+            if (prop === "sort") {
+                return async (compareFn) => {
+                    return parent.mutateArrayQueue(propertyName, { op: "sort" }, isRef);
+                };
+            }
+            if (prop === "clear") {
+                return async () => {
+                    return parent.mutateArrayQueue(propertyName, { op: "clear" }, isRef);
+                };
+            }
+            if (prop === "ensureLoaded") {
+                return async (options) => {
+                    if (!isRef)
+                        return receiver;
+                    const current = getItems();
+                    await Promise.all(current.map(async (item) => {
+                        if (item &&
+                            typeof item.ensureLoaded === "function" &&
+                            item.isLazyStub) {
+                            await item.ensureLoaded(options);
+                        }
+                    }));
+                    return receiver;
+                };
+            }
+            if (MUTATING_ARRAY_METHODS.has(prop)) {
+                throw new DEMError(DEMErrorCode.CANNOT_SET_REF_DIRECTLY, `Cannot mutate DEMArray '${propertyName}' synchronously via ${String(prop)}(). Use await array.${String(prop)}(...).`);
+            }
+            const current = getItems();
+            if (prop === "length") {
+                return current.length;
+            }
+            if (typeof prop === "string" && !isNaN(Number(prop))) {
+                return current[Number(prop)];
+            }
+            const val = Reflect.get(current, prop);
+            if (typeof val === "function") {
+                return val.bind(current);
+            }
+            return val;
+        },
+        set(_target, prop) {
+            if (prop === "length" || !isNaN(Number(prop))) {
+                throw new DEMError(DEMErrorCode.CANNOT_SET_REF_DIRECTLY, `Cannot assign index directly on DEMArray '${propertyName}'. Use await array.set(index, value) or await array.splice(...).`);
+            }
+            return false;
+        },
+        deleteProperty(_target, prop) {
+            throw new DEMError(DEMErrorCode.CANNOT_SET_REF_DIRECTLY, `Cannot delete elements directly from DEMArray '${propertyName}'. Use await array.splice(...) or await array.clear().`);
+        },
+        has(_target, prop) {
+            const current = getItems();
+            return Reflect.has(current, prop);
+        },
+        ownKeys(_target) {
+            const current = getItems();
+            return Reflect.ownKeys(current);
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            const current = getItems();
+            if (prop === "length") {
+                _target.length = current.length;
+                return Reflect.getOwnPropertyDescriptor(_target, "length");
+            }
+            const desc = Reflect.getOwnPropertyDescriptor(current, prop);
+            if (desc) {
+                return { ...desc, configurable: true };
+            }
+            return undefined;
+        },
+    });
+}
 export class AutoUpdatedClientObject {
     entry;
     _refArrayCache;
@@ -85,6 +236,7 @@ export class AutoUpdatedClientObject {
         }
     }
     EmitterID = `dem_e_${++AutoUpdatedClientObject._emitterCounter}`;
+    _preloadTimers = new Set();
     toChangeOnParents;
     callbacks;
     loadReferencesAsync = async () => {
@@ -275,15 +427,21 @@ export class AutoUpdatedClientObject {
             throw new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, this.loadError);
         if (this.isLoaded)
             return;
+        if (this.parentManager?._isClosed) {
+            throw new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, "Manager is closed");
+        }
         await new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
+                this._preloadTimers.delete(timer);
                 const errorMsg = `Timeout waiting for object preloading (${this.className})`;
                 this.loadError = errorMsg;
                 this.isLoading = false;
                 reject(new DEMError(DEMErrorCode.PRELOAD_TIMEOUT, errorMsg));
             }, timeoutMs);
+            this._preloadTimers.add(timer);
             this.emitter.once(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, (failed, reason) => {
                 clearTimeout(timer);
+                this._preloadTimers.delete(timer);
                 if (failed)
                     reject(new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, reason));
                 else
@@ -348,6 +506,9 @@ export class AutoUpdatedClientObject {
      */
     get extractedData() {
         const extracted = processIsRefProperties(this.data, this, null, [], {}, this.loggers).newData;
+        if (this.data?._id && !extracted._id) {
+            extracted._id = this.data._id?.toString?.() ?? String(this.data._id);
+        }
         return _.cloneDeep(extracted);
     }
     /**
@@ -516,8 +677,16 @@ export class AutoUpdatedClientObject {
             return undefined;
         const idStr = typeof id === "string" ? id : id.toString();
         const cached = globalCache.objects[idStr];
-        if (cached?.object)
-            return cached.object;
+        if (cached?.object) {
+            const isSameClient = !this.parentManager ||
+                !this.parentManager.managers ||
+                Object.keys(this.parentManager.managers).length === 0 ||
+                cached.object.parentManager === this.parentManager ||
+                Object.values(this.parentManager.managers).includes(cached.object.parentManager);
+            if (isSameClient) {
+                return cached.object;
+            }
+        }
         const cacheKey = `${this.className}:${key}`;
         const cachedManager = this.parentManager?.cache?.references?.[cacheKey];
         if (cachedManager) {
@@ -571,7 +740,11 @@ export class AutoUpdatedClientObject {
             key === "constructor" ||
             key === "prototype" ||
             (this.properties && !this.properties.includes(rootProp) && rootProp !== "_id")) {
-            return { success: false, msg: `Invalid property key: ${key}` };
+            return {
+                success: false,
+                code: DEMErrorCode.INVALID_ARGUMENT,
+                msg: `Invalid property key: ${key}`,
+            };
         }
         try {
             const isRef = getMetadataRecursive("isRef", this, key);
@@ -614,6 +787,7 @@ export class AutoUpdatedClientObject {
                     obj = obj[currentKey];
                 }
             }
+            const prevRawVal = this.data?.[key];
             const res = await this.setValueInternal(key, valueToStore, silent, noUpdate);
             if (res.success) {
                 if (valueToStore === undefined) {
@@ -642,6 +816,66 @@ export class AutoUpdatedClientObject {
                     if (isRef && this.parentManager.isLoaded)
                         await this.contactChildren();
                 }
+                else if (isRef) {
+                    const parentId = (this.data?._id ?? this._id)?.toString();
+                    if (Array.isArray(valueToStore)) {
+                        const nextIds = valueToStore.map((v) => v && typeof v === "object" && "_id" in v
+                            ? String(v._id)
+                            : String(v));
+                        const prevIds = Array.isArray(prevRawVal)
+                            ? prevRawVal.map((v) => v && typeof v === "object" && "_id" in v
+                                ? String(v._id)
+                                : String(v))
+                            : [];
+                        const addedIds = nextIds.filter((id) => !prevIds.includes(id));
+                        const removedIds = prevIds.filter((id) => !nextIds.includes(id));
+                        for (const id of nextIds) {
+                            const child = this.findReference(id, key);
+                            if (child && typeof child === "object") {
+                                const props = child.properties || [];
+                                for (const cp of props) {
+                                    const refsTo = Reflect.getMetadata("refsTo", child, cp) ||
+                                        Reflect.getMetadata("refsTo", Object.getPrototypeOf(child), cp);
+                                    if (refsTo === this.className ||
+                                        refsTo?.startsWith?.(this.className + ":")) {
+                                        child[cp] = parentId;
+                                        if (child.data) {
+                                            child.data[cp] = parentId;
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                        for (const id of removedIds) {
+                            if (nextIds.includes(id))
+                                continue;
+                            const child = this.findReference(id, key);
+                            if (child && typeof child === "object") {
+                                const props = child.properties || [];
+                                for (const cp of props) {
+                                    const refsTo = Reflect.getMetadata("refsTo", child, cp) ||
+                                        Reflect.getMetadata("refsTo", Object.getPrototypeOf(child), cp);
+                                    if (refsTo === this.className ||
+                                        refsTo?.startsWith?.(this.className + ":")) {
+                                        const childParentVal = child[cp];
+                                        const childParentId = childParentVal && typeof childParentVal === "object" && "_id" in childParentVal
+                                            ? String(childParentVal._id)
+                                            : String(childParentVal);
+                                        if (childParentId === parentId ||
+                                            childParentVal === parentId ||
+                                            childParentVal === this) {
+                                            child[cp] = undefined;
+                                        }
+                                        if (child.data?.[cp] === parentId ||
+                                            child.data?.[cp]?.toString?.() === parentId) {
+                                            delete child.data[cp];
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
                 if (this.isLoaded) {
                     this.callbacks.update(this, key);
                     await this.onUpdate(noUpdate, key);
@@ -667,17 +901,248 @@ export class AutoUpdatedClientObject {
     async setValueInternal(key, value, silent = false, noUpdate = false) {
         if (silent)
             return { success: true, msg: "Silent" };
+        const id = this.data?._id ?? this._id;
+        if (!id) {
+            throw new DEMError(DEMErrorCode.MISSING_ID, `Cannot update object ${this.className} because _id is missing.`);
+        }
         return new Promise((resolve) => {
-            const id = this.data?._id ?? this._id;
             this.socket.emit(EVENT_UPDATE + this.className + id, { _id: id.toString(), key, value }, (res) => {
                 resolve({
-                    success: res.success,
-                    code: res.code,
-                    msg: res.message ?? (res.success ? "Success" : "Error"),
+                    success: res?.success ?? false,
+                    code: res?.code,
+                    msg: res?.message ?? (res?.success ? "Success" : "Error"),
                 });
             });
         });
     }
+    /**
+     * Enqueues an array mutation in the entity write queue to ensure sequential execution.
+     *
+     * @param key - Target array property key.
+     * @param req - Array mutation request payload.
+     * @param isRef - Whether the target property is a relational reference array.
+     * @returns Promise resolving to the mutation result.
+     */
+    async mutateArrayQueue(key, req, isRef) {
+        this.writeQueue = this.writeQueue
+            .catch(() => { })
+            .then(() => this.mutateArrayInternal(key, req, isRef));
+        return this.writeQueue;
+    }
+    /**
+     * Internal execution handler for array mutations following pessimistic convergence semantics.
+     * Transmits mutation request to server, awaits acknowledgment, and updates local state.
+     *
+     * @param key - Target array property key.
+     * @param req - Array mutation parameters payload.
+     * @param isRef - Whether the target property holds relational entities.
+     * @returns Promise resolving to the operator return value or updated array.
+     * @throws {DEMError} Throws when server rejects mutation or write fails.
+     */
+    async mutateArrayInternal(key, req, isRef) {
+        const rawVal = this.data?.[key];
+        const currentRawArray = Array.isArray(rawVal) ? [...rawVal] : [];
+        // Capture items prior to mutation for pop/shift/splice return values
+        let removedEntities = [];
+        if (isRef) {
+            if (req.op === "pop" && currentRawArray.length > 0) {
+                const lastId = currentRawArray[currentRawArray.length - 1];
+                removedEntities = [this.findReference(lastId, key) || lastId];
+            }
+            else if (req.op === "shift" && currentRawArray.length > 0) {
+                const firstId = currentRawArray[0];
+                removedEntities = [this.findReference(firstId, key) || firstId];
+            }
+            else if (req.op === "splice" && req.index !== undefined) {
+                const count = req.deleteCount ?? currentRawArray.length - req.index;
+                for (let i = req.index; i < req.index + count && i < currentRawArray.length; i++) {
+                    const id = currentRawArray[i];
+                    removedEntities.push(this.findReference(id, key) || id);
+                }
+            }
+            else if (req.op === "clear") {
+                for (const id of currentRawArray) {
+                    removedEntities.push(this.findReference(id, key) || id);
+                }
+            }
+        }
+        else {
+            if (req.op === "pop" && currentRawArray.length > 0) {
+                removedEntities = [currentRawArray[currentRawArray.length - 1]];
+            }
+            else if (req.op === "shift" && currentRawArray.length > 0) {
+                removedEntities = [currentRawArray[0]];
+            }
+            else if (req.op === "splice" && req.index !== undefined) {
+                const count = req.deleteCount ?? currentRawArray.length - req.index;
+                removedEntities = currentRawArray.slice(req.index, req.index + count);
+            }
+            else if (req.op === "clear") {
+                removedEntities = [...currentRawArray];
+            }
+        }
+        // Compute baseHash
+        const baseHash = isRef
+            ? currentRawArray
+                .map((item) => item && typeof item === "object" && "_id" in item
+                ? String(item._id)
+                : String(item))
+                .join(",")
+            : JSON.stringify(currentRawArray);
+        // Extract raw string IDs for relational items
+        let rawItemsToPersist = req.items || [];
+        const resolvedEntities = [];
+        if (isRef && req.items) {
+            rawItemsToPersist = req.items.map((item) => {
+                const isEntityInstance = item instanceof AutoUpdatedClientObject ||
+                    (item &&
+                        typeof item === "object" &&
+                        "className" in item &&
+                        "data" in item);
+                if (isEntityInstance) {
+                    resolvedEntities.push(item);
+                    return String(item._id);
+                }
+                const resolved = this.findReference(item, key);
+                if (resolved) {
+                    resolvedEntities.push(resolved);
+                }
+                return String(item && item.toString ? item.toString() : item);
+            });
+        }
+        const payload = {
+            ...req,
+            key,
+            items: rawItemsToPersist,
+            baseHash,
+            clientTimestamp: typeof this.parentManager?.getSynchronizedTime === "function"
+                ? this.parentManager.getSynchronizedTime()
+                : Date.now(),
+        };
+        let res;
+        if (this.isServer) {
+            res = await this.executeServerArrayMutation(key, payload, isRef);
+        }
+        else {
+            const id = this.data?._id ?? this._id;
+            if (!id) {
+                throw new DEMError(DEMErrorCode.MISSING_ID, `Cannot mutate array on ${this.className} because _id is missing.`);
+            }
+            res = await new Promise((resolve) => {
+                this.socket.emit(EVENT_UPDATE + this.className + id, { _id: id.toString(), key, mutation: payload }, (response) => {
+                    resolve(response);
+                });
+            });
+        }
+        if (!res || !res.success) {
+            throw new DEMError(res?.code ?? DEMErrorCode.ARRAY_MUTATION_FAILED, res?.message || `Array mutation '${req.op}' on '${key}' failed on server.`);
+        }
+        const updatedArray = res.updatedArray ?? [];
+        this.data[key] = updatedArray;
+        this._refArrayCache?.delete(key);
+        if (Object.hasOwn(this, key)) {
+            delete this[key];
+        }
+        // Synchronize child back-references
+        if (isRef) {
+            const parentId = (this.data?._id ?? this._id)?.toString();
+            const currentIds = updatedArray.map((v) => v && typeof v === "object" && "_id" in v
+                ? String(v._id)
+                : String(v));
+            for (const id of currentIds) {
+                const child = this.findReference(id, key);
+                if (child && typeof child === "object") {
+                    const props = child.properties || [];
+                    for (const cp of props) {
+                        const refsTo = Reflect.getMetadata("refsTo", child, cp) ||
+                            Reflect.getMetadata("refsTo", Object.getPrototypeOf(child), cp);
+                        if (refsTo === this.className ||
+                            refsTo?.startsWith?.(this.className + ":")) {
+                            child[cp] = parentId;
+                            if (child.data) {
+                                child.data[cp] = parentId;
+                            }
+                        }
+                    }
+                }
+            }
+            for (const entity of resolvedEntities) {
+                if (entity && typeof entity === "object") {
+                    const props = entity.properties || [];
+                    for (const cp of props) {
+                        const refsTo = Reflect.getMetadata("refsTo", entity, cp) ||
+                            Reflect.getMetadata("refsTo", Object.getPrototypeOf(entity), cp);
+                        if (refsTo === this.className ||
+                            refsTo?.startsWith?.(this.className + ":")) {
+                            entity[cp] = parentId;
+                            if (entity.data) {
+                                entity.data[cp] = parentId;
+                            }
+                        }
+                    }
+                }
+            }
+            if (req.op === "pop" ||
+                req.op === "shift" ||
+                req.op === "splice" ||
+                req.op === "clear") {
+                for (const entity of removedEntities) {
+                    if (entity && typeof entity === "object") {
+                        const entId = entity._id?.toString() ??
+                            entity.data?._id?.toString();
+                        if (entId && currentIds.includes(entId))
+                            continue;
+                        const props = entity.properties || [];
+                        for (const cp of props) {
+                            const refsTo = Reflect.getMetadata("refsTo", entity, cp) ||
+                                Reflect.getMetadata("refsTo", Object.getPrototypeOf(entity), cp);
+                            if (refsTo === this.className ||
+                                refsTo?.startsWith?.(this.className + ":")) {
+                                const childParentVal = entity[cp];
+                                const childParentId = childParentVal &&
+                                    typeof childParentVal === "object" &&
+                                    "_id" in childParentVal
+                                    ? String(childParentVal._id)
+                                    : String(childParentVal);
+                                if (childParentId === parentId ||
+                                    childParentVal === parentId ||
+                                    childParentVal === this) {
+                                    entity[cp] = undefined;
+                                }
+                                if (entity.data?.[cp] === parentId ||
+                                    entity.data?.[cp]?.toString?.() === parentId) {
+                                    delete entity.data[cp];
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if (this.isLoaded) {
+            this.callbacks.update(this, key);
+            await this.onUpdate(false, key);
+        }
+        switch (req.op) {
+            case "push":
+            case "unshift":
+                return updatedArray.length;
+            case "pop":
+            case "shift":
+                return removedEntities[0];
+            case "splice":
+                return removedEntities;
+            case "set":
+                return req.items?.[0];
+            case "reverse":
+            case "sort":
+                return this[key];
+            case "clear":
+                return undefined;
+            default:
+                return updatedArray;
+        }
+    }
     makeUpdate(key, value) {
         const id = this.data?._id ?? this._id;
         if (!id) {
@@ -714,6 +1179,11 @@ export class AutoUpdatedClientObject {
     }
     async wipeSelf() {
         this._refArrayCache?.clear();
+        for (const timer of this._preloadTimers) {
+            clearTimeout(timer);
+        }
+        this._preloadTimers.clear();
+        this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, true, "Object destroyed");
         if (this.data.Wiped)
             return;
         const id = this.data?._id ?? this._id;
@@ -1003,7 +1473,8 @@ export function setupClassAccessors(classParam) {
                         }
                         const cached = this._refArrayCache.get(key);
                         if (cached && cached.rawIdsHash === idsHash) {
-                            const hasStaleChild = cached.proxy.some((child) => {
+                            const childrenToCheck = cached.resolvedChildren || cached.proxy;
+                            const hasStaleChild = childrenToCheck.some((child) => {
                                 if (!child)
                                     return true;
                                 if (child.data?.Wiped)
@@ -1020,23 +1491,54 @@ export function setupClassAccessors(classParam) {
                             }
                             this._refArrayCache.delete(key);
                         }
-                        const rawResult = [];
-                        for (let i = 0; i < val.length; i++) {
-                            const item = val[i];
-                            if (item) {
-                                const ref = this.findReference(item, key);
-                                if (ref)
-                                    rawResult.push(ref);
+                        const getResolvedItems = () => {
+                            const rawList = this.data?.[key];
+                            if (!Array.isArray(rawList))
+                                return [];
+                            const rawResult = [];
+                            for (let i = 0; i < rawList.length; i++) {
+                                const item = rawList[i];
+                                if (item) {
+                                    const ref = this.findReference(item, key);
+                                    if (ref &&
+                                        !ref.data?.Wiped &&
+                                        (!ref._id || globalCache.objects[ref._id.toString()])) {
+                                        rawResult.push(ref);
+                                    }
+                                }
                             }
-                        }
-                        const proxy = createReadOnlyArrayProxy(rawResult, key);
-                        this._refArrayCache.set(key, { rawIdsHash: idsHash, proxy });
+                            return rawResult;
+                        };
+                        const resolvedChildren = getResolvedItems();
+                        const proxy = createDEMArray(this, key, true, getResolvedItems);
+                        this._refArrayCache.set(key, {
+                            rawIdsHash: idsHash,
+                            proxy: proxy,
+                            resolvedChildren,
+                        });
                         return proxy;
                     }
                     else {
                         return this.findReference(val, key);
                     }
                 }
+                if (Array.isArray(val)) {
+                    const idsHash = JSON.stringify(val);
+                    if (!this._refArrayCache) {
+                        this._refArrayCache = new Map();
+                    }
+                    const cached = this._refArrayCache.get(key);
+                    if (cached && cached.rawIdsHash === idsHash) {
+                        return cached.proxy;
+                    }
+                    const getPrimitiveItems = () => {
+                        const raw = this.data?.[key];
+                        return Array.isArray(raw) ? raw : [];
+                    };
+                    const proxy = createDEMArray(this, key, false, getPrimitiveItems);
+                    this._refArrayCache.set(key, { rawIdsHash: idsHash, proxy: proxy });
+                    return proxy;
+                }
                 return val;
             },
             set(v) {