@prestizni-software/server-dem 0.7.3 → 0.7.5

package/AutoUpdatedClientObjectClass.js

@@ -0,0 +1,911 @@
+import "reflect-metadata";
+import _ from "lodash";
+import { EVENT_INTERNAL_PRE_LOADED, EVENT_DELETE, EVENT_GET, EVENT_NEW, EVENT_UPDATE, globalCache, DEMError, DEMErrorCode, toDEMError, } from "./CommonTypes.js";
+import { ObjectId } from "bson";
+export class AutoUpdatedClientObject {
+    entry;
+    socket;
+    data;
+    isServer = false;
+    loggers;
+    isLoading = true;
+    loadError;
+    isLoadingReferences = true;
+    checkedMissingProperties;
+    emitter;
+    properties;
+    classParam;
+    className;
+    parentManager;
+    static _emitterCounter = 0;
+    EmitterID = `dem_e_${++AutoUpdatedClientObject._emitterCounter}`;
+    toChangeOnParents;
+    callbacks;
+    loadReferencesAsync = async () => {
+        try {
+            if (!this.isLoaded) {
+                await this.waitForPreloaded();
+            }
+            this.generateSettersAndGetters();
+            if (this.isServer) {
+                await this.loadForceReferences();
+                if (this.toChangeOnParents) {
+                    for (const thing of this.toChangeOnParents) {
+                        await this.setValue__(thing.key, thing.value, true, false, false, true);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Fix 3: Enhanced diagnostics with stack trace
+            this.loggers.error?.("Error loading references: " +
+                (error instanceof Error ? error.message + "\n" + error.stack : String(error)));
+        }
+        finally {
+            this.isLoadingReferences = false;
+        }
+    };
+    /**
+     * Initializes an AutoUpdatedClientObject instance.
+     *
+     * @param classParam - Constructor of the client object entity.
+     * @param socket - Socket.IO client socket connection.
+     * @param data - Entity identifier string or initial data object.
+     * @param loggers - Logging interfaces.
+     * @param className - Managed entity class name.
+     * @param parentManager - Host client manager.
+     * @param callback - Event callbacks interface.
+     * @param emitter - Shared event emitter.
+     * @param isServer - Flag indicating whether running on server runtime.
+     * @throws {DEMError} Throws DEMErrorCode.MISSING_ARGUMENT when required parameters are omitted.
+     */
+    constructor(classParam, socket, data, loggers, className, parentManager, callback, emitter, isServer = false) {
+        if (!classParam ||
+            !socket ||
+            !data ||
+            !loggers ||
+            !className ||
+            !parentManager ||
+            !emitter) {
+            this.classParam = classParam;
+            this.socket = socket;
+            this.data = data;
+            this.loggers = loggers;
+            this.className = className;
+            this.parentManager = parentManager;
+            this.callbacks = callback;
+            this.emitter = emitter;
+            this.properties = undefined;
+            if (!classParam &&
+                !socket &&
+                !data &&
+                !loggers &&
+                !className &&
+                !parentManager &&
+                !callback &&
+                !emitter)
+                return;
+            else
+                throw new DEMError(DEMErrorCode.MISSING_ARGUMENT, "Missing arguments for AutoUpdatedClientObject: " + className);
+        }
+        this.classParam = classParam;
+        this.socket = socket;
+        this.isServer = isServer;
+        this.emitter = emitter;
+        this.isLoadingReferences = true;
+        this.isLoading = true;
+        this.parentManager = parentManager;
+        this.className = className;
+        if (classParam) {
+            const meta = setupClassAccessors(classParam);
+            this.properties = meta.properties;
+        }
+        else {
+            this.properties = [];
+        }
+        this.callbacks = callback;
+        this.loggers = {
+            debug: (s) => loggers.debug?.(`[DEM - ${this.className}: ${this.data?._id ?? this._id ?? "not loaded"}] ${s}`),
+            info: (s) => loggers.info?.(`[DEM - ${this.className}: ${this.data?._id ?? this._id ?? "not loaded"}] ${s}`),
+            warn: (s) => loggers.warn?.(`[DEM - ${this.className}: ${this.data?._id ?? this._id ?? "not loaded"}] ${s}`),
+            error: (s) => loggers.error?.(`[DEM - ${this.className}: ${this.data?._id ?? this._id ?? "not loaded"}] ${s}`),
+        };
+        if (typeof data === "string") {
+            this.data = { _id: data };
+            if (this.isServer) {
+                this.isLoading = false;
+                this.generateSettersAndGetters();
+                return;
+            }
+            this.socket.emit(EVENT_GET + this.className + data, null, (res) => {
+                if (!res.success) {
+                    this.isLoading = false;
+                    this.loadError = res.message;
+                    this.loggers.error?.("Could not load data from server: " + res.message);
+                    this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, true, res.message);
+                    return;
+                }
+                this.data = this.handleDataCleanup(res.data);
+                this.generateSettersAndGetters();
+                this.isLoading = false;
+                this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID);
+                this.openSockets();
+            });
+        }
+        else {
+            this.isLoading = true;
+            this.data = this.handleDataCleanup(data);
+            if ((!this.data._id || this.data._id === "") && !this.isServer) {
+                this.handleNewObject(this.data);
+            }
+            else {
+                this.isLoading = false;
+                if (!this.isServer)
+                    this.openSockets();
+            }
+        }
+        this.generateSettersAndGetters();
+        Promise.resolve().then(() => {
+            this.generateSettersAndGetters();
+        });
+    }
+    /**
+     * Normalizes reference fields in entity data into string IDs.
+     *
+     * @param data - Entity data payload.
+     * @returns Cleaned entity data payload.
+     */
+    handleDataCleanup(data) {
+        if (!data || typeof data !== "object")
+            return data;
+        const meta = this.classParam ? setupClassAccessors(this.classParam) : null;
+        const refProps = meta ? meta.refProps : null;
+        if (!refProps || refProps.size === 0)
+            return data;
+        const dataAsRecord = data;
+        for (const key of refProps) {
+            const val = dataAsRecord[key];
+            if (!val)
+                continue;
+            if (Array.isArray(val)) {
+                let needsNormalization = false;
+                for (let i = 0; i < val.length; i++) {
+                    const item = val[i];
+                    if (item && typeof item === "object") {
+                        needsNormalization = true;
+                        break;
+                    }
+                }
+                if (needsNormalization) {
+                    dataAsRecord[key] = val.map((obj) => obj?._id?.toString() ??
+                        obj?.toString());
+                }
+            }
+            else if (typeof val === "object") {
+                dataAsRecord[key] =
+                    val?._id?.toString() ??
+                        val?.toString();
+            }
+        }
+        return data;
+    }
+    /**
+     * Pauses execution until the object finishes asynchronous preloading.
+     *
+     * @param timeoutMs - Maximum milliseconds to wait before rejecting.
+     * @throws {DEMError} Throws DEMErrorCode.PRELOAD_TIMEOUT on timeout or OBJECT_LOAD_FAILED on failure.
+     */
+    async waitForPreloaded(timeoutMs = 15000) {
+        if (this.loadError)
+            throw new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, this.loadError);
+        if (this.isLoaded)
+            return;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const errorMsg = `Timeout waiting for object preloading (${this.className})`;
+                this.loadError = errorMsg;
+                this.isLoading = false;
+                reject(new DEMError(DEMErrorCode.PRELOAD_TIMEOUT, errorMsg));
+            }, timeoutMs);
+            this.emitter.once(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, (failed, reason) => {
+                clearTimeout(timer);
+                if (failed)
+                    reject(new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, reason));
+                else
+                    resolve();
+            });
+        });
+    }
+    /**
+     * Emits creation event to the server socket and awaits populated entity response.
+     *
+     * @param data - Initial data payload.
+     */
+    handleNewObject(data) {
+        this.isLoading = true;
+        if (!this.socket) {
+            const errorMsg = `Cannot create ${this.className}: Socket is missing.`;
+            this.loadError = errorMsg;
+            this.isLoading = false;
+            this.loggers.error?.(errorMsg);
+            this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, true, errorMsg);
+            return;
+        }
+        let payload = data;
+        try {
+            if (data && typeof data === "object") {
+                payload = JSON.parse(JSON.stringify(data));
+            }
+        }
+        catch (err) {
+            this.loggers.warn?.(`Failed to JSON-serialize creation payload for ${this.className}, falling back to raw data: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        this.socket.emit(EVENT_NEW + this.className, payload, (res) => {
+            if (this.loadError)
+                return;
+            if (!res) {
+                const errorMsg = `No response received from server when creating ${this.className}`;
+                this.isLoading = false;
+                this.loadError = errorMsg;
+                this.loggers.error?.(errorMsg);
+                this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, true, errorMsg);
+                return;
+            }
+            if (!res.success) {
+                this.isLoading = false;
+                this.loadError = res.message;
+                this.loggers.error?.("Could not create data on server: " + res.message);
+                this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID, true, res.message);
+                return;
+            }
+            this.data = res.data;
+            this.generateSettersAndGetters();
+            this.isLoading = false;
+            this.emitter.emit(EVENT_INTERNAL_PRE_LOADED + this.EmitterID);
+            if (!this.isServer)
+                this.openSockets();
+        });
+    }
+    /**
+     * Returns a deep clone of the entity's extracted data with reference objects converted to IDs.
+     *
+     * @returns Serialized entity representation.
+     */
+    get extractedData() {
+        const extracted = processIsRefProperties(this.data, this, null, [], {}, this.loggers).newData;
+        return _.cloneDeep(extracted);
+    }
+    /**
+     * Indicates whether the entity has finished loading its data.
+     *
+     * @returns True if loaded.
+     */
+    get isLoaded() {
+        return !this.isLoading;
+    }
+    /**
+     * Asynchronously awaits preloading and loads all missing reference links.
+     *
+     * @returns Promise resolving to true when completed.
+     */
+    async isPreLoadedAsync() {
+        await this.loadReferencesAsync();
+        this.generateSettersAndGetters();
+        return true;
+    }
+    /**
+     * Identifies and connects missing cross-entity references on server startup.
+     */
+    async loadMissingReferences() {
+        if (!this.isServer)
+            return;
+        this.checkedMissingProperties = {};
+        await this.checkForMissingRefs();
+        this.generateSettersAndGetters();
+    }
+    openSockets() {
+        const id = this.data?._id ?? this._id;
+        const event = EVENT_UPDATE + this.className + id.toString();
+        this.socket.on(event, async (update, ack) => {
+            const res = await this.handleUpdateRequest(update);
+            if (ack && typeof ack === "function")
+                ack(res);
+            return res;
+        });
+    }
+    async handleUpdateRequest(update) {
+        try {
+            await this.setValue__(update.key, update.value, true);
+            if (this.isLoaded)
+                this.callbacks.update(this, update.key);
+            return { success: true, data: undefined, message: "" };
+        }
+        catch (error) {
+            this.loggers.error?.(`[${this.data._id}] Error applying patch: ${error instanceof Error ? error.message : String(error)}`);
+            return {
+                success: false,
+                message: "Error applying update: " +
+                    (error instanceof Error ? error.message : String(error)),
+            };
+        }
+    }
+    _gettersGenerated = false;
+    writeQueue = Promise.resolve();
+    get updateEventName() {
+        const id = this.data?._id ?? this._id;
+        return EVENT_UPDATE + this.className + (id ? id.toString() : "");
+    }
+    getRawId(key) {
+        if (!this.data)
+            return undefined;
+        const val = this.data[key];
+        if (!val)
+            return undefined;
+        if (typeof val === "string")
+            return val;
+        if (typeof val === "object" && val !== null && val._id) {
+            return val._id.toString();
+        }
+        return String(val);
+    }
+    generateSettersAndGetters() {
+        if (this.classParam) {
+            setupClassAccessors(this.classParam);
+        }
+        if (this.properties) {
+            for (const key of this.properties) {
+                if (typeof key === "string" && Object.hasOwn(this, key)) {
+                    delete this[key];
+                }
+            }
+        }
+    }
+    getValue(key_) {
+        const key = key_;
+        const parts = key.split(".");
+        let value = this;
+        for (const part of parts) {
+            if (value === undefined || value === null)
+                return undefined;
+            const nextValue = value[part];
+            if (nextValue !== undefined) {
+                value = nextValue;
+            }
+            else if (value.data &&
+                value.data[part] !== undefined) {
+                value = value.data[part];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return value;
+    }
+    /**
+     * Resolves reference pointer ID to instantiated entity instance across caches and managers.
+     *
+     * @param id - Entity ID or ObjectId.
+     * @param key - Property key referencing the entity.
+     * @returns Resolved entity instance or undefined.
+     */
+    findReference(id, key) {
+        if (!id)
+            return undefined;
+        const idStr = typeof id === "string" ? id : id.toString();
+        const cached = globalCache.objects[idStr];
+        if (cached?.object)
+            return cached.object;
+        const cacheKey = `${this.className}:${key}`;
+        const cachedManager = this.parentManager?.cache?.references?.[cacheKey];
+        if (cachedManager) {
+            const res = cachedManager.getObject(idStr);
+            if (res)
+                return res;
+        }
+        if (this.parentManager?.managers) {
+            for (const manager of Object.values(this.parentManager.managers)) {
+                const result = manager.getObject(idStr);
+                if (result) {
+                    if (this.parentManager.cache?.references) {
+                        this.parentManager.cache.references[cacheKey] = manager;
+                    }
+                    return result;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Mutates property value and synchronizes change to the server via socket.
+     *
+     * @param key - Property key to modify.
+     * @param val - Value to assign.
+     * @returns Promise resolving to modification result.
+     */
+    async setValue(key, val) {
+        return await this.setValue__(key, val);
+    }
+    /**
+     * Internal setter with writeQueue serialization ensuring sequential updates.
+     *
+     * @param key - Property key.
+     * @param val - Value to assign.
+     * @param silent - Whether socket broadcast is bypassed.
+     * @param noGet - Whether local update bypasses get.
+     * @param noUpdate - Whether onUpdate hook is bypassed.
+     * @param isParentUpdate - Whether mutation originated from parent.
+     * @returns Promise resolving to operation outcome.
+     */
+    async setValue__(key, val, silent = false, noGet = false, noUpdate = false, isParentUpdate = false) {
+        this.writeQueue = this.writeQueue
+            .catch(() => { })
+            .then(() => this.setValueQueueInternal(key, val, silent, noGet, noUpdate, isParentUpdate));
+        return this.writeQueue;
+    }
+    async setValueQueueInternal(key, val, silent = false, noGet = false, noUpdate = false, isParentUpdate = false) {
+        const rootProp = key.split(".")[0];
+        if (key === "__proto__" ||
+            key === "constructor" ||
+            key === "prototype" ||
+            (this.properties && !this.properties.includes(rootProp) && rootProp !== "_id")) {
+            return { success: false, msg: `Invalid property key: ${key}` };
+        }
+        try {
+            const isRef = getMetadataRecursive("isRef", this, key);
+            const pointer = getMetadataRecursive("refsTo", this, key);
+            if (pointer && !isParentUpdate && !silent && !this.isServer) {
+                throw new DEMError(DEMErrorCode.CANNOT_SET_REF_DIRECTLY, "Cannot set value of a reference pointer directly.");
+            }
+            let valueToStore = val;
+            if (isRef) {
+                valueToStore = Array.isArray(val)
+                    ? val.map((v) => v?._id?.toString() ??
+                        v?.toString() ??
+                        v)
+                    : (val?._id?.toString() ??
+                        val?.toString() ??
+                        val);
+            }
+            const currentVal = this.getValue(key);
+            const currentValId = Array.isArray(currentVal)
+                ? currentVal.map((v) => v?._id?.toString() ??
+                    v?.toString() ??
+                    v)
+                : (currentVal?._id?.toString() ??
+                    currentVal?.toString());
+            if (_.isEqual(currentValId, valueToStore))
+                return { success: true, msg: "Successfully set " + key + " to " + val };
+            const path = key.split(".");
+            if (path.length > 1) {
+                let obj = this.data;
+                for (let i = 0; i < path.length - 1; i++) {
+                    const currentKey = path[i];
+                    const valAtKey = obj[currentKey];
+                    if (typeof valAtKey === "string" ||
+                        (valAtKey && ObjectId.isValid(valAtKey))) {
+                        const ref = await this.resolveReference(String(valAtKey));
+                        if (!ref)
+                            throw new DEMError(DEMErrorCode.REFERENCE_RESOLUTION_FAILED, "Could not resolve reference on path: " + key);
+                        return await ref.setValue(path.slice(i + 1).join("."), val);
+                    }
+                    obj = obj[currentKey];
+                }
+            }
+            const res = await this.setValueInternal(key, valueToStore, silent, noUpdate);
+            if (res.success) {
+                const pathArr = key.split(".");
+                let obj = this.data;
+                for (let i = 0; i < pathArr.length - 1; i++) {
+                    obj = obj[pathArr[i]];
+                }
+                obj[pathArr[pathArr.length - 1]] = valueToStore;
+                if (this.isServer) {
+                    await this.findAndLoadReferences(key, valueToStore);
+                    if (isRef && this.parentManager.isLoaded)
+                        await this.contactChildren();
+                }
+                if (this.isLoaded) {
+                    this.callbacks.update(this, key);
+                    await this.onUpdate(noUpdate, key);
+                }
+            }
+            return {
+                ...res,
+                msg: res.msg ?? "Successfully set " + key + " to " + val,
+            };
+        }
+        catch (error) {
+            this.loggers.error?.(`Error setting value ${key}: ${error instanceof Error ? error.message : String(error)}`);
+            const demErr = error instanceof DEMError
+                ? error
+                : toDEMError(error, DEMErrorCode.DB_SAVE_FAILED);
+            return {
+                success: false,
+                code: demErr.code,
+                msg: demErr.message,
+            };
+        }
+    }
+    async setValueInternal(key, value, silent = false, noUpdate = false) {
+        if (silent)
+            return { success: true, msg: "Silent" };
+        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"),
+                });
+            });
+        });
+    }
+    makeUpdate(key, value) {
+        const id = this.data?._id ?? this._id;
+        if (!id) {
+            this.loggers.error?.(`Probably missing the identifier ['_id'] again: ${key} = ${value}`);
+            throw new DEMError(DEMErrorCode.MISSING_ID, `Cannot make update for ${this.className} because _id is missing.`);
+        }
+        return { _id: id.toString(), key, value };
+    }
+    async resolveReference(id) {
+        for (const manager of Object.values(this.parentManager.managers)) {
+            const obj = manager.getObject(id);
+            if (obj)
+                return obj;
+        }
+        return null;
+    }
+    async findAndLoadReferences(lastPath, value) {
+        const isRef = getMetadataRecursive("isRef", this, lastPath);
+        if (isRef) {
+            for (const id of Array.isArray(value) ? value : [value]) {
+                if (!id)
+                    continue;
+                let result;
+                for (const manager of Object.values(this.parentManager.managers)) {
+                    result = manager.getObject(id?.toString());
+                    if (result)
+                        break;
+                }
+                if (result && result.parentManager.isLoaded && typeof result.loadMissingReferences === "function") {
+                    await result.loadMissingReferences();
+                }
+            }
+        }
+    }
+    async wipeSelf() {
+        if (this.data.Wiped)
+            return;
+        const id = this.data?._id ?? this._id;
+        const _id = id ? id.toString() : "unknown";
+        for (const key of Object.keys(this.data)) {
+            delete this.data[key];
+        }
+        this.data = { Wiped: true };
+        this.loggers.info?.(`[${_id}] ${this.className} object wiped`);
+    }
+    destroyImmediate() {
+        this.wipeSelf();
+    }
+    async loadForceReferences(obj = this.data, proto = this, alreadySeen = new Set()) {
+        const meta = this.classParam ? setupClassAccessors(this.classParam) : null;
+        const props = obj === this.data && this.properties
+            ? this.properties
+            : Reflect.getMetadata("props", proto) ||
+                Reflect.getMetadata("props", Object.getPrototypeOf(proto)) ||
+                [];
+        for (const key of props) {
+            if (typeof key !== "string")
+                continue;
+            const pointer = meta?.refsToMap.get(key) ||
+                Reflect.getMetadata("refsTo", proto, key) ||
+                (proto ? Reflect.getMetadata("refsTo", Object.getPrototypeOf(proto), key) : undefined);
+            if (pointer &&
+                obj === (this.data) &&
+                obj[key] &&
+                !alreadySeen.has(obj)) {
+                await this.createdWithParent(pointer.split(":"), obj[key]);
+            }
+            if (obj[key] && !alreadySeen.has(obj[key]))
+                alreadySeen.add(obj[key]);
+            const val = obj[key];
+            if (val &&
+                typeof val === "object" &&
+                !(val instanceof Date) &&
+                !(val instanceof ObjectId)) {
+                const nestedProto = Object.getPrototypeOf(val);
+                if (nestedProto && !alreadySeen.has(val)) {
+                    alreadySeen.add(val);
+                    await this.loadForceReferences(val, nestedProto, alreadySeen);
+                }
+            }
+        }
+    }
+    async createdWithParent(pointer, parent) {
+        if (pointer.length !== 2)
+            return;
+        const parentId = parent._id?.toString() ?? parent.toString();
+        const manager = this.parentManager.managers[pointer[0]];
+        if (!manager) {
+            this.loggers.warn?.(`createdWithParent: Manager not found for ${pointer[0]}.`);
+            return;
+        }
+        const obj = manager.getObject(parentId);
+        if (!obj) {
+            this.loggers.warn?.(`createdWithParent: Parent object not found for ID ${parentId} in manager ${pointer[0]}`);
+            return;
+        }
+        const myId = this.data._id?.toString?.() ?? String(this.data._id);
+        const rawData = obj.data;
+        const rawVal = rawData ? rawData[pointer[1]] : undefined;
+        if (Array.isArray(rawVal)) {
+            let alreadyIncluded = false;
+            for (let i = 0; i < rawVal.length; i++) {
+                const item = rawVal[i];
+                const idStr = item?._id?.toString?.() ?? item?.toString?.();
+                if (idStr === myId) {
+                    alreadyIncluded = true;
+                    break;
+                }
+            }
+            if (!alreadyIncluded) {
+                this.loggers.debug?.(`createdWithParent: Adding myId to parent array`);
+                await obj.setValue__(pointer[1], [...rawVal, myId], false, false, false, true);
+            }
+        }
+        else {
+            const currentIdStr = rawVal?._id?.toString?.() ?? rawVal?.toString?.();
+            if (currentIdStr !== myId) {
+                this.loggers.debug?.(`createdWithParent: Setting myId to parent field`);
+                await obj.setValue__(pointer[1], myId, false, false, false, true);
+            }
+        }
+    }
+    /**
+     * Destroys the entity and notifies server socket of deletion.
+     *
+     * @param once - Internal flag preventing infinite recursion.
+     * @returns Promise resolving to deletion outcome.
+     */
+    async destroy(once = false) {
+        if (!once)
+            return await this.parentManager.deleteObject(this.data._id.toString());
+        return new Promise((resolve) => {
+            this.socket.emit(EVENT_DELETE + this.className, this.data._id, (res) => {
+                resolve({
+                    success: res.success,
+                    code: res.code,
+                    message: res.message ?? "",
+                });
+            });
+        });
+    }
+    async checkForMissingRefs() {
+        for (const prop of this.properties) {
+            const pointer = getMetadataRecursive("refsTo", this, prop.toString());
+            if (pointer && !this.data?.[prop]) {
+                const parts = pointer.split(":");
+                if (parts.length === 2)
+                    await this.findMissingObjectReference(prop, parts);
+            }
+        }
+    }
+    async findMissingObjectReference(prop, pointer) {
+        this.checkedMissingProperties ??= {};
+        if (this.checkedMissingProperties[prop])
+            return;
+        this.checkedMissingProperties[prop] = true;
+        const ac = this.parentManager.managers[pointer[0]];
+        if (!ac)
+            return;
+        const targetId = this.data._id?.toString?.() ?? String(this.data._id);
+        const allObjects = ac.objectsAsArray;
+        for (let i = 0; i < allObjects.length; i++) {
+            const obj = allObjects[i];
+            const rawData = obj.data;
+            if (!rawData)
+                continue;
+            const val = rawData[pointer[1]];
+            if (!val)
+                continue;
+            if (Array.isArray(val)) {
+                for (let j = 0; j < val.length; j++) {
+                    const id = val[j]?._id?.toString?.() ?? val[j]?.toString?.();
+                    if (id === targetId) {
+                        this.data[prop] = obj._id;
+                        return;
+                    }
+                }
+            }
+            else {
+                const id = val?._id?.toString?.() ?? val?.toString?.();
+                if (id === targetId) {
+                    this.data[prop] = obj._id;
+                    return;
+                }
+            }
+        }
+    }
+    /**
+     * Triggers missing reference resolution on all child referenced entities.
+     */
+    async contactChildren() {
+        if (!this.isServer)
+            return;
+        for (const prop of this.properties) {
+            const isRef = getMetadataRecursive("isRef", this, prop.toString());
+            const pointer = getMetadataRecursive("refsTo", this, prop.toString());
+            if (!isRef || pointer)
+                continue;
+            const obj = this.getValue(prop);
+            if (!obj)
+                continue;
+            const children = Array.isArray(obj) ? obj : [obj];
+            for (const child of children) {
+                if (child &&
+                    typeof child
+                        .loadMissingReferences === "function") {
+                    await child.loadMissingReferences();
+                }
+            }
+        }
+        this.generateSettersAndGetters();
+    }
+    async onUpdate(noUpdate = false, key) {
+        // Placeholder for server-side override
+    }
+    async onDeletion() {
+        // Placeholder for server-side override
+    }
+}
+/**
+ * Traverses entity object and transforms referenced objects into string identifiers.
+ *
+ * @param instance - Raw entity data record.
+ * @param target - Reflection prototype target.
+ * @param prefix - Dot-notated property key prefix.
+ * @param allProps - Accumulated array of discovered property paths.
+ * @param newData - Output object receiving sanitized data.
+ * @param loggers - Logging interfaces.
+ * @returns Object containing all property paths and transformed newData.
+ */
+export function processIsRefProperties(instance, target, prefix, allProps, newData, loggers) {
+    const props = Reflect.getMetadata("props", target) || [];
+    for (const prop of props) {
+        const path = prefix ? `${prefix}.${prop}` : prop;
+        allProps.push(path);
+        newData[prop] =
+            instance[prop] && ObjectId.isValid(instance[prop])
+                ? instance[prop]?.toString()
+                : instance[prop];
+        if (Reflect.getMetadata("isRef", target, prop)) {
+            if (Array.isArray(instance[prop]))
+                newData[prop] = instance[prop]
+                    .map((item) => item?._id?.toString() ??
+                    item?.toString())
+                    .filter(Boolean);
+            else
+                newData[prop] =
+                    instance[prop]?._id?.toString() ??
+                        instance[prop]?.toString();
+        }
+        const type = Reflect.getMetadata("design:type", target, prop);
+        if (type?.prototype) {
+            const nestedProps = Reflect.getMetadata("props", type.prototype);
+            if (nestedProps && instance[prop]) {
+                newData[prop] = processIsRefProperties(instance[prop], type.prototype, path, allProps, {}, loggers).newData;
+            }
+        }
+    }
+    return { allProps, newData };
+}
+/**
+ * Compiles V8 fast-shape property getters and setters on the class prototype.
+ *
+ * @param classParam - Constructor function of the target entity class.
+ * @returns Cached metadata object with properties list, refProps set, and refsToMap.
+ */
+export function setupClassAccessors(classParam) {
+    if (!classParam) {
+        return { properties: [], refProps: new Set(), refsToMap: new Map() };
+    }
+    if (classParam.__metaCache) {
+        return classParam.__metaCache;
+    }
+    const allProps = new Set();
+    const refProps = new Set();
+    const refsToMap = new Map();
+    let proto_ = classParam.prototype;
+    while (proto_ && proto_ !== Object.prototype) {
+        const props = Reflect.getMetadata("props", proto_) ||
+            Reflect.getOwnMetadata("props", proto_) ||
+            [];
+        for (const p of props) {
+            if (typeof p === "string") {
+                allProps.add(p);
+                const isRef = Reflect.getMetadata("isRef", proto_, p) || Reflect.getOwnMetadata("isRef", proto_, p);
+                if (isRef)
+                    refProps.add(p);
+                const refsTo = Reflect.getMetadata("refsTo", proto_, p) || Reflect.getOwnMetadata("refsTo", proto_, p);
+                if (refsTo)
+                    refsToMap.set(p, refsTo);
+            }
+        }
+        proto_ = Object.getPrototypeOf(proto_);
+    }
+    const properties = Array.from(allProps);
+    for (const key of properties) {
+        const isRef = refProps.has(key);
+        Object.defineProperty(classParam.prototype, key, {
+            get() {
+                if (!this.data)
+                    return undefined;
+                let val = this.data[key];
+                if (val === null)
+                    val = undefined;
+                if (isRef && val) {
+                    if (Array.isArray(val)) {
+                        const result = [];
+                        for (let i = 0; i < val.length; i++) {
+                            const item = val[i];
+                            if (item) {
+                                const ref = this.findReference(item, key);
+                                if (ref)
+                                    result.push(ref);
+                            }
+                        }
+                        return result;
+                    }
+                    else {
+                        return this.findReference(val, key);
+                    }
+                }
+                return val;
+            },
+            set(v) {
+                if (this.data) {
+                    let valueToSet = v;
+                    if (isRef && v) {
+                        if (Array.isArray(v)) {
+                            valueToSet = v.map((item) => item && item._id
+                                ? item._id.toString()
+                                : item?.toString());
+                        }
+                        else {
+                            valueToSet = v._id
+                                ? v._id.toString()
+                                : v.toString();
+                        }
+                    }
+                    this.data[key] = valueToSet;
+                }
+            },
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    const meta = { properties, refProps, refsToMap };
+    classParam.__metaCache = meta;
+    classParam.__propsCache = properties;
+    classParam.__refPropsCache = Array.from(refProps);
+    return meta;
+}
+/**
+ * Traverses prototype chain recursively to resolve metadata key.
+ *
+ * @param metaKey - Reflection metadata key.
+ * @param proto - Prototype object.
+ * @param prop - Property name on prototype.
+ * @returns Metadata value or undefined.
+ */
+export function getMetadataRecursive(metaKey, proto, prop) {
+    while (proto) {
+        const meta = Reflect.getMetadata(metaKey, proto, prop);
+        if (meta)
+            return meta;
+        proto = Object.getPrototypeOf(proto);
+    }
+    return undefined;
+}
+//# sourceMappingURL=AutoUpdatedClientObjectClass.js.map