@prestizni-software/server-dem 0.7.4 → 0.9.0

package/AutoUpdateClientManagerClass.js

@@ -0,0 +1,820 @@
+import { AutoUpdateManager } from "./AutoUpdateManagerClass.js";
+import { globalCache, EVENT_GET, EVENT_UPDATE, DEM_CLIENT_VERSION, verifyDEMVersion, DEMError, DEMErrorCode, } from "./CommonTypes.js";
+import { EventEmitter } from "eventemitter3";
+import { ClientStateReconciler, } from "./sync/index.js";
+const inFlightFactories = new WeakMap();
+/**
+ * Factory function initializing a dictionary of AutoUpdateClientManager instances.
+ * Verifies versions, executes startup handshakes, and parallelizes reference resolution.
+ *
+ * @param defs - Dictionary mapping entity class names to their client constructor classes.
+ * @param loggers - Logger callbacks interface.
+ * @param socket - Socket.IO client socket connection.
+ * @param doDebug - Flag indicating whether debug logs are emitted.
+ * @param emitter - Shared event emitter for lifecycle notifications.
+ * @param callbacks - Optional event callbacks (new, update, delete, progress).
+ * @param versionOptions - Version compatibility validation options.
+ * @param deltaSyncOptions - Delta sync storage and caching configuration.
+ * @returns Promise resolving to the initialized client manager map.
+ */
+export async function AUCManagerFactory(defs, loggers, socket, doDebug = false, emitter = new EventEmitter(), callbacks = {}, versionOptions, deltaSyncOptions, lazyLoadingOptions) {
+    if (socket && inFlightFactories.has(socket)) {
+        loggers.debug?.("[DEM:FACTORY] Concurrent AUCManagerFactory detected on socket, reusing in-flight initialization promise.");
+        return inFlightFactories.get(socket);
+    }
+    const factoryPromise = (async () => {
+        const defaultCallbacks = {
+            new: callbacks.new ?? ((_x) => { }),
+            update: callbacks.update ??
+                ((_x, _y) => { }),
+            delete: callbacks.delete ?? ((_x) => { }),
+            progress: callbacks.progress ?? ((_x) => { }),
+        };
+        if (!doDebug) {
+            loggers.debug = (_) => { };
+        }
+        const managerKeys = Object.keys(defs);
+        const numberOfManagers = managerKeys.length || 1;
+        const progressUpdater = callbacks.progress ?? ((_x) => { });
+        // Immediately report initial 0 progress
+        progressUpdater(0);
+        const managerProgressMap = new Map();
+        for (const key of managerKeys) {
+            managerProgressMap.set(key, 0);
+        }
+        let lastReportedProgress = 0;
+        const updateOverallProgress = (managerKey, fraction) => {
+            const clampedFraction = Math.max(0, Math.min(1, fraction));
+            managerProgressMap.set(managerKey, clampedFraction);
+            let sum = 0;
+            for (const val of managerProgressMap.values()) {
+                sum += val;
+            }
+            const overall = sum / numberOfManagers;
+            if (overall >= lastReportedProgress || overall === 1) {
+                lastReportedProgress = overall;
+                progressUpdater(overall);
+            }
+        };
+        const managers = {};
+        const startStartTime = Date.now();
+        let startTime = Date.now();
+        for (const key in defs) {
+            try {
+                const Model = defs[key];
+                if (typeof Model !== "function") {
+                    throw new DEMError(DEMErrorCode.INVALID_CONSTRUCTOR, `Invalid model constructor for manager: ${key}`);
+                }
+                const managerLazyOpts = typeof lazyLoadingOptions === "object" &&
+                    lazyLoadingOptions !== null &&
+                    key in lazyLoadingOptions
+                    ? lazyLoadingOptions[key]
+                    : lazyLoadingOptions;
+                const c = new AutoUpdateClientManager(Model, key, socket, loggers, managers, emitter, {
+                    ...defaultCallbacks,
+                    ...callbacks[key],
+                    progress: (fraction) => {
+                        callbacks[key]?.progress?.(fraction);
+                        updateOverallProgress(key, fraction);
+                    },
+                }, versionOptions, deltaSyncOptions, managerLazyOpts);
+                managers[key] = c;
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.includes("Local type does not match server type for manager"))
+                    throw error;
+                let message = `Creating manager for: ${key}`;
+                message += "\n Error creating manager: " + key;
+                message +=
+                    "\n " + (error instanceof Error ? error.message : String(error));
+                loggers.error?.(message);
+                if (error instanceof Error && error.stack)
+                    loggers.error?.(error.stack);
+                continue;
+            }
+        }
+        loggers.debug?.("Created all managers in " + (Date.now() - startTime) + "ms");
+        startTime = Date.now();
+        const loadPromises = Object.keys(defs).map(async (key) => {
+            let temp2 = { s: Date.now(), f: 0 };
+            try {
+                const manager = managers[key];
+                if (!manager) {
+                    loggers.warn?.(`Manager ${key} was not created due to previous error`);
+                    return;
+                }
+                await manager.loadFromServer(temp2);
+                loggers.debug?.("Loaded data from server for manager: " +
+                    key +
+                    " in " +
+                    (temp2.f - temp2.s) +
+                    "ms");
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.includes("Local type does not match server type for manager"))
+                    throw error;
+                let message = "Error loading data from server for manager: " + key;
+                message +=
+                    "\n " + (error instanceof Error ? error.message : String(error));
+                message += "\n Failed in " + (temp2.f - temp2.s) + "ms";
+                loggers.error?.(message);
+                if (error instanceof Error && error.stack)
+                    loggers.error?.(message + "\n" + error.stack);
+            }
+        });
+        await Promise.all(loadPromises);
+        // Ensure 100% progress emitted when all loaders finish
+        if (lastReportedProgress < 1) {
+            progressUpdater(1);
+        }
+        // Generate getters and setters for all client objects now that everything is loaded
+        for (const manager of Object.values(managers)) {
+            for (const obj of manager.objectsAsArray) {
+                obj.generateSettersAndGetters();
+            }
+        }
+        loggers.debug?.("Loaded data from server for all managers in " +
+            (Date.now() - startTime) +
+            "ms");
+        loggers.info?.("Loaded all managers in " + (Date.now() - startStartTime) + "ms");
+        return managers;
+    })();
+    if (socket) {
+        inFlightFactories.set(socket, factoryPromise);
+    }
+    try {
+        return await factoryPromise;
+    }
+    finally {
+        if (socket) {
+            inFlightFactories.delete(socket);
+        }
+    }
+}
+export class AutoUpdateClientManager extends AutoUpdateManager {
+    objects_ = {};
+    managers;
+    callbacks;
+    socket;
+    versionOptions;
+    deltaSyncOptions;
+    storageAdapter;
+    deltaSyncEnabled;
+    lazyLoadingOptions;
+    isLazyLoadingEnabled;
+    defaultHydrationDepth = 2;
+    manifest = [];
+    lastRevision = 0;
+    totalObjects = 0;
+    loadedObjects = 0;
+    pendingMissingFetches = new Map();
+    pendingHydrations = new Map();
+    _cachedObjectsArray = null;
+    _reconnectHandler;
+    /**
+     * Initializes an AutoUpdateClientManager instance.
+     *
+     * @param classParam - Constructor of the client object entity.
+     * @param className - Managed entity class name.
+     * @param socket - Socket.IO client socket connection.
+     * @param loggers - Logging interfaces.
+     * @param managers - Registry of sibling client managers.
+     * @param emitter - Shared event emitter.
+     * @param callbacks - Client event callbacks.
+     * @param versionOptions - Version compatibility options.
+     * @param deltaSyncOptions - Delta sync storage adapter configuration.
+     * @param lazyLoadingOptions - Lazy loading manifest and hydration configuration.
+     */
+    constructor(classParam, className, socket, loggers, managers, emitter, callbacks, versionOptions, deltaSyncOptions, lazyLoadingOptions) {
+        if (!classParam)
+            throw new DEMError(DEMErrorCode.MISSING_ARGUMENT, "Missing required argument: classParam");
+        if (!className)
+            throw new DEMError(DEMErrorCode.MISSING_ARGUMENT, "Missing required argument: className");
+        if (!socket)
+            throw new DEMError(DEMErrorCode.MISSING_ARGUMENT, "Missing required argument: socket");
+        super(classParam, className, socket, loggers, managers, emitter);
+        this.socket = socket;
+        this.managers = managers;
+        this.callbacks = callbacks;
+        this.versionOptions = versionOptions;
+        this.lazyLoadingOptions = lazyLoadingOptions;
+        if (typeof lazyLoadingOptions === "object") {
+            this.isLazyLoadingEnabled = lazyLoadingOptions.enabled !== false;
+            this.defaultHydrationDepth = lazyLoadingOptions.defaultDepth ?? 2;
+        }
+        else {
+            this.isLazyLoadingEnabled = Boolean(lazyLoadingOptions);
+            this.defaultHydrationDepth = 2;
+        }
+        if (deltaSyncOptions) {
+            this.deltaSyncEnabled = true;
+            if (typeof deltaSyncOptions === "object") {
+                this.deltaSyncOptions = deltaSyncOptions;
+                this.storageAdapter = deltaSyncOptions.storage;
+            }
+        }
+        else {
+            this.deltaSyncEnabled = false;
+        }
+        this._reconnectHandler = async () => {
+            this.loggers.info?.("Socket reconnected, reloading manager data from server...");
+            try {
+                await this.loadFromServer();
+            }
+            catch (err) {
+                this.loggers.error?.("Error reloading on reconnect: " +
+                    (err instanceof Error ? err.message : String(err)));
+            }
+        };
+        this.socket?.on?.("reconnect", this._reconnectHandler);
+    }
+    /**
+     * Normalizes loaded object count against total objects into a 0 to 1 progress fraction.
+     *
+     * @param loaded - Number of loaded objects.
+     * @param total - Total count of expected objects.
+     * @returns Normalized progress value between 0 and 1.
+     */
+    normalizeProgress(loaded, total) {
+        if (!total || total <= 0)
+            return 1;
+        const ratio = loaded / total;
+        return Math.max(0, Math.min(1, ratio));
+    }
+    /**
+     * Registers socket event listeners for entity creation and deletion broadcasts.
+     */
+    startSocketListeners() {
+        this.socket.off("new" + this.className);
+        this.socket.off("delete" + this.className);
+        this.socket.on("new" + this.className, async (payload) => {
+            const id = typeof payload === "string" ? payload : payload._id;
+            if (this.getObject(id))
+                return;
+            this.loggers.debug("Applying new object from manager " + this.className + " - " + id);
+            try {
+                if (this.isLazyLoadingEnabled) {
+                    const description = typeof payload === "object" && payload.description
+                        ? payload.description
+                        : id;
+                    this.manifest.push({ _id: id, description });
+                    const stub = new this.classParam(this.classParam, this.socket, { _id: id, __isLazyStub: true, descriptor: description }, this.loggers, this.className, this, this.callbacks, this.emitter);
+                    stub.descriptor = description;
+                    this.objects_[id] = stub;
+                    globalCache.objects[id] = {
+                        className: this.className,
+                        object: stub,
+                    };
+                    this._cachedObjectsArray = null;
+                    this.totalObjects += 1;
+                    this.loadedObjects += 1;
+                    this.callbacks.new(stub);
+                    return;
+                }
+                this.totalObjects += 1;
+                await this.handleGetMissingObject(id);
+                this.loadedObjects += 1;
+                if (this.storageAdapter) {
+                    await ClientStateReconciler.persistToStorage(this, this.lastRevision, this.storageAdapter);
+                }
+            }
+            catch (error) {
+                this.loggers.error("Error loading object " +
+                    id +
+                    " from manager " +
+                    this.className +
+                    " - " +
+                    (error instanceof Error ? error.message : String(error)));
+                if (error instanceof Error && error.stack)
+                    this.loggers.error(error.stack);
+            }
+        });
+        this.socket.on("delete" + this.className, async (id) => {
+            if (!this.getObject(id))
+                return;
+            this.loggers.debug("Applying object deletion from manager " + this.className + " - " + id);
+            try {
+                this.totalObjects -= 1;
+                this.loadedObjects -= 1;
+                await this.deleteObject(id);
+            }
+            catch (error) {
+                this.loggers.error("Error applying object deletion from manager " +
+                    this.className +
+                    " - " +
+                    id);
+                this.loggers.error(error instanceof Error ? error.message : String(error));
+                if (error instanceof Error && error.stack)
+                    this.loggers.error(error.stack);
+            }
+        });
+    }
+    /**
+     * Deletes an object by ID from local cache, socket events, and persistent storage adapter.
+     *
+     * @param _id - Identifier of object to delete.
+     * @returns Promise resolving to deletion outcome.
+     */
+    async deleteObject(_id) {
+        const _idStr = _id.toString();
+        this.socket.off(EVENT_UPDATE + this.className + _idStr);
+        this._cachedObjectsArray = null;
+        const res = await super.deleteObject(_id);
+        if (this.storageAdapter) {
+            await ClientStateReconciler.persistToStorage(this, this.lastRevision, this.storageAdapter);
+        }
+        return res;
+    }
+    /**
+     * Fetches startup data from the server or applies delta updates from local storage.
+     *
+     * @param t - Optional benchmark timer tracking object.
+     * @returns Promise resolving when data has been loaded and initialized.
+     */
+    async loadFromServer(t) {
+        let hasRestoredFromStorage = false;
+        if (this.storageAdapter && Object.keys(this.objects_).length === 0) {
+            const restored = await ClientStateReconciler.restoreFromStorage(this, this.storageAdapter);
+            if (restored.restored) {
+                hasRestoredFromStorage = true;
+                this.lastRevision = restored.revision;
+                this.loggers.debug?.(`Restored ${restored.count} objects from storage for ${this.className} (revision: ${this.lastRevision})`);
+            }
+        }
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new DEMError(DEMErrorCode.TIMEOUT, `Timeout waiting for startup data from server for ${this.className}`));
+            }, 5000);
+            const startupPayload = {
+                clientVersion: DEM_CLIENT_VERSION,
+            };
+            if (this.deltaSyncEnabled && hasRestoredFromStorage) {
+                startupPayload.lastRevision = this.lastRevision;
+            }
+            this.socket.emit("startup" + this.className, startupPayload, async (res) => {
+                clearTimeout(timer);
+                if (!res || !res.success) {
+                    const err = res?.message || "Failed to load startup data";
+                    this.loggers.error("Error loading ids from server for manager");
+                    this.loggers.error(err);
+                    reject(new DEMError(res?.code ?? DEMErrorCode.STARTUP_FAILED, err));
+                    return;
+                }
+                const data = res.data;
+                // DEM Version Verification
+                if (data.version) {
+                    const verResult = verifyDEMVersion(DEM_CLIENT_VERSION, data.version, this.versionOptions);
+                    if (!verResult.compatible) {
+                        const errMsg = verResult.message ||
+                            `DEM Version Incompatibility: Client (${DEM_CLIENT_VERSION}) is incompatible with Server (${data.version})`;
+                        this.loggers.error?.(errMsg);
+                        this.versionOptions?.onVersionMismatch?.(DEM_CLIENT_VERSION, data.version, errMsg);
+                        reject(new DEMError(DEMErrorCode.VERSION_MISMATCH, errMsg));
+                        return;
+                    }
+                    else if (verResult.status !== "match") {
+                        this.loggers.warn?.(verResult.message);
+                        this.versionOptions?.onVersionMismatch?.(DEM_CLIENT_VERSION, data.version, verResult.message);
+                    }
+                }
+                else {
+                    this.loggers.debug?.(`Connected to DEM server for ${this.className} without version payload.`);
+                    if (this.versionOptions?.strictVersionMatch) {
+                        const errMsg = `Strict DEM version match required for ${this.className}, but server did not provide a version.`;
+                        this.loggers.error?.(errMsg);
+                        reject(new DEMError(DEMErrorCode.VERSION_MISMATCH, errMsg));
+                        return;
+                    }
+                }
+                if (data.status === "up-to-date") {
+                    this.lastRevision = data.revision ?? this.lastRevision;
+                    this.callbacks.progress?.(1);
+                    this.startSocketListeners();
+                    this.isLoaded_ = true;
+                    if (t)
+                        t.f = Date.now();
+                    resolve();
+                    return;
+                }
+                if (data.status === "delta" && data.changes) {
+                    this.lastRevision = data.revision ?? this.lastRevision;
+                    await ClientStateReconciler.applyDelta(this, data, this.storageAdapter);
+                    this.callbacks.progress?.(1);
+                    this.startSocketListeners();
+                    this.isLoaded_ = true;
+                    if (t)
+                        t.f = Date.now();
+                    resolve();
+                    return;
+                }
+                if (data.status === "lazy") {
+                    this.lastRevision = data.revision ?? this.lastRevision;
+                    this.manifest = data.manifest ?? [];
+                    // Clear old objects before populating new stubs
+                    for (const oldId of Object.keys(this.objects_)) {
+                        delete globalCache.objects[oldId];
+                    }
+                    this.objects_ = {};
+                    this._cachedObjectsArray = null;
+                    const descMap = new Map();
+                    if (data.manifest) {
+                        for (const entry of data.manifest) {
+                            descMap.set(String(entry._id), entry.description);
+                        }
+                    }
+                    for (const id of data.ids) {
+                        const description = descMap.get(String(id));
+                        const stub = new this.classParam(this.classParam, this.socket, { _id: id, __isLazyStub: true, descriptor: description }, this.loggers, this.className, this, this.callbacks, this.emitter);
+                        stub.descriptor = description;
+                        this.objects_[id] = stub;
+                        globalCache.objects[id] = {
+                            className: this.className,
+                            object: stub,
+                        };
+                    }
+                    this.totalObjects = data.ids.length;
+                    this.loadedObjects = data.ids.length;
+                    this.callbacks.progress?.(1);
+                    this.startSocketListeners();
+                    this.isLoaded_ = true;
+                    if (t)
+                        t.f = Date.now();
+                    resolve();
+                    return;
+                }
+                // Full sync handling
+                const serverPropsCopy = [...data.properties];
+                let extraProperties = [];
+                for (const property of this.properties) {
+                    if (typeof property !== "string")
+                        throw new DEMError(DEMErrorCode.INVALID_ARGUMENT, "Only string keys allowed. Not this shit: " + String(property));
+                    if (property === "_id")
+                        continue;
+                    if (serverPropsCopy.includes(property)) {
+                        serverPropsCopy.splice(serverPropsCopy.indexOf(property), 1);
+                    }
+                    else {
+                        extraProperties.push(property);
+                    }
+                }
+                let { allowedToLoad, errorMessage } = this.checkLoadability(extraProperties, { properties: serverPropsCopy });
+                if (!allowedToLoad) {
+                    this.loggers.error?.(errorMessage);
+                    reject(new DEMError(DEMErrorCode.STARTUP_FAILED, errorMessage));
+                    return;
+                }
+                this.loggers.debug("Loading manager DB " +
+                    this.className +
+                    " - [" +
+                    data.ids.length +
+                    "] entries");
+                if (this.loggers.debug && this.loggers.debug.toString().length > 15) {
+                    this.loggers.debug(data.ids.join(", "));
+                }
+                // Clear old objects before populating new ones on full reload
+                for (const oldId of Object.keys(this.objects_)) {
+                    delete globalCache.objects[oldId];
+                }
+                this.objects_ = {};
+                this._cachedObjectsArray = null;
+                this.totalObjects = data.ids.length;
+                this.loadedObjects = 0;
+                this.lastRevision = data.revision ?? 0;
+                if (data.ids.length === 0) {
+                    this.callbacks.progress?.(1);
+                    this.startSocketListeners();
+                    this.isLoaded_ = true;
+                    if (this.storageAdapter) {
+                        await ClientStateReconciler.persistToStorage(this, this.lastRevision, this.storageAdapter);
+                    }
+                    if (t)
+                        t.f = Date.now();
+                    resolve();
+                    return;
+                }
+                const objectMap = new Map();
+                if (data.objects) {
+                    for (const objData of data.objects) {
+                        if (objData?._id) {
+                            objectMap.set(objData._id.toString(), objData);
+                        }
+                    }
+                }
+                for (const id of data.ids) {
+                    try {
+                        const objData = objectMap.get(id);
+                        this.objects_[id] = new this.classParam(this.classParam, this.socket, objData || id, this.loggers, this.className, this, this.callbacks, this.emitter);
+                        globalCache.objects[id] = {
+                            className: this.className,
+                            object: this.objects_[id],
+                        };
+                    }
+                    catch (error) {
+                        this.loggers.error("Error loading object " +
+                            id +
+                            " from manager " +
+                            this.className +
+                            " - " +
+                            (error instanceof Error ? error.message : String(error)));
+                        if (error instanceof Error && error.stack)
+                            this.loggers.error(error.stack);
+                    }
+                }
+                const objectPromises = Object.keys(this.objects_).map(async (id) => {
+                    const obj = this.objects_[id];
+                    try {
+                        await obj.isPreLoadedAsync();
+                        await obj.loadMissingReferences();
+                        this.loadedObjects += 1;
+                        if (this.totalObjects < 100 ||
+                            this.loadedObjects % Math.ceil(this.totalObjects / 100) === 0 ||
+                            this.loadedObjects === this.totalObjects) {
+                            this.callbacks.progress(this.normalizeProgress(this.loadedObjects, this.totalObjects));
+                        }
+                    }
+                    catch (error) {
+                        this.loggers.error("Error loading object " +
+                            id +
+                            " from manager " +
+                            this.className +
+                            " - " +
+                            (error instanceof Error ? error.message : String(error)));
+                        if (error instanceof Error && error.stack)
+                            this.loggers.error(error.stack);
+                    }
+                });
+                await Promise.all(objectPromises);
+                if (this.storageAdapter) {
+                    await ClientStateReconciler.persistToStorage(this, this.lastRevision, this.storageAdapter);
+                }
+                this.loggers.info("Loaded " +
+                    this.className +
+                    " - [" +
+                    Object.keys(this.objects_).length +
+                    "] entries");
+                this.startSocketListeners();
+                this.isLoaded_ = true;
+                resolve();
+            });
+        });
+        if (t)
+            t.f = Date.now();
+    }
+    /**
+     * Verifies structural schema compatibility between client and server class definitions.
+     *
+     * @param extraProperties - Properties present on client class but absent on server.
+     * @param data - Server schema containing registered server property names.
+     * @returns Object indicating whether manager is allowed to load and descriptive error message.
+     */
+    checkLoadability(extraProperties, data) {
+        let allowedToLoad = true;
+        let errorMessage = "Local type does not match server type for manager " + this.className;
+        if (extraProperties.length > 0) {
+            allowedToLoad = false;
+            errorMessage +=
+                "\n\nLocal type has " +
+                    (extraProperties.length > 1
+                        ? "these extra properties"
+                        : "this extra property") +
+                    ":\n" +
+                    extraProperties.join("\n");
+        }
+        const filteredProperties = data.properties.filter((p) => p !== "_id");
+        if (filteredProperties.length > 0) {
+            allowedToLoad = false;
+            errorMessage +=
+                "\n\nLocal type is missing " +
+                    (filteredProperties.length > 1 ? "these properties" : "this property") +
+                    ":\n" +
+                    filteredProperties.join("\n");
+        }
+        return { allowedToLoad, errorMessage };
+    }
+    /**
+     * Retrieves an object from local memory by identifier.
+     *
+     * @param _id - Entity identifier.
+     * @returns Managed object instance, null, or undefined.
+     */
+    getObject(_id) {
+        if (!_id)
+            return null;
+        return this.objects_[_id.toString()] || undefined;
+    }
+    /**
+     * Dictionary map containing all managed object instances keyed by ID string.
+     *
+     * @returns Object dictionary keyed by string IDs.
+     */
+    get objects() {
+        return this.objects_;
+    }
+    /**
+     * Array representation of all managed object instances, cached for fast reads.
+     *
+     * @returns Array containing all managed object instances.
+     */
+    get objectsAsArray() {
+        if (!this._cachedObjectsArray) {
+            this._cachedObjectsArray = Object.values(this.objects_);
+        }
+        return this._cachedObjectsArray;
+    }
+    /**
+     * Loads and hydrates an unhydrated entity on demand up to a designated reference depth.
+     * Deduplicates concurrent in-flight hydration requests.
+     *
+     * @param _id - Unique identifier of the entity to hydrate.
+     * @param options - Hydration options containing target reference depth.
+     * @returns Promise resolving to the hydrated entity instance.
+     */
+    async loadObject(_id, options) {
+        const _idStr = _id.toString();
+        const existing = this.objects_[_idStr];
+        if (existing && !existing.isLazyStub && existing.isLoaded) {
+            return existing;
+        }
+        if (this.pendingHydrations.has(_idStr)) {
+            return this.pendingHydrations.get(_idStr);
+        }
+        const depth = options?.depth ??
+            (typeof this.lazyLoadingOptions === "object"
+                ? this.lazyLoadingOptions.defaultDepth
+                : undefined) ??
+            this.defaultHydrationDepth ??
+            2;
+        const hydrationPromise = (async () => {
+            try {
+                const response = await new Promise((resolve, reject) => {
+                    this.socket.emit(EVENT_GET + this.className + _idStr, { depth }, (res) => {
+                        if (!res || !res.success) {
+                            const errMsg = res?.message || `Failed to fetch lazy object ${_idStr}`;
+                            reject(new DEMError(res?.code ?? DEMErrorCode.OBJECT_LOAD_FAILED, errMsg));
+                            return;
+                        }
+                        resolve(res);
+                    });
+                });
+                const rootData = response.data;
+                let rootObj = this.objects_[_idStr];
+                const existingDescriptor = rootObj?.descriptor ?? this.manifest.find((m) => String(m._id) === _idStr)?.description;
+                if (rootObj && typeof rootObj.hydrateFromData === "function") {
+                    rootObj.hydrateFromData(rootData);
+                }
+                else {
+                    rootObj = new this.classParam(this.classParam, this.socket, rootData, this.loggers, this.className, this, this.callbacks, this.emitter);
+                    this.objects_[_idStr] = rootObj;
+                    globalCache.objects[_idStr] = {
+                        className: this.className,
+                        object: rootObj,
+                    };
+                }
+                if (existingDescriptor) {
+                    rootObj.descriptor = existingDescriptor;
+                }
+                // Hydrate related entities into respective sibling managers
+                if (response.related && typeof response.related === "object") {
+                    for (const [targetClassName, entityList] of Object.entries(response.related)) {
+                        const targetManager = this.managers?.[targetClassName];
+                        if (targetManager && Array.isArray(entityList)) {
+                            for (const entityData of entityList) {
+                                if (!entityData?._id)
+                                    continue;
+                                const entityIdStr = entityData._id.toString();
+                                let targetObj = targetManager.objects_[entityIdStr];
+                                if (targetObj && typeof targetObj.hydrateFromData === "function") {
+                                    targetObj.hydrateFromData(entityData);
+                                }
+                                else if (!targetObj) {
+                                    targetObj = new targetManager.classParam(targetManager.classParam, targetManager.socket, entityData, targetManager.loggers, targetManager.className, targetManager, targetManager.callbacks, targetManager.emitter);
+                                    targetManager.objects_[entityIdStr] = targetObj;
+                                    globalCache.objects[entityIdStr] = {
+                                        className: targetManager.className,
+                                        object: targetObj,
+                                    };
+                                }
+                            }
+                        }
+                    }
+                }
+                // Resolve references on root object
+                await rootObj.isPreLoadedAsync();
+                await rootObj.loadMissingReferences();
+                this._cachedObjectsArray = null;
+                return rootObj;
+            }
+            finally {
+                this.pendingHydrations.delete(_idStr);
+            }
+        })();
+        this.pendingHydrations.set(_idStr, hydrationPromise);
+        return hydrationPromise;
+    }
+    /**
+     * Fetches an object missing from local client memory on demand from the server.
+     * Deduplicates concurrent in-flight requests for the same entity ID.
+     *
+     * @param _id - Entity identifier of the missing object.
+     * @returns Promise resolving to the retrieved object instance.
+     * @throws {DEMError} Throws DEMErrorCode.MISSING_ID or MANAGERS_NOT_INITIALIZED.
+     */
+    async handleGetMissingObject(_id) {
+        const _idStr = _id.toString();
+        if (this.getObject(_idStr))
+            return this.getObject(_idStr);
+        if (!_idStr)
+            throw new DEMError(DEMErrorCode.MISSING_ID, "No id.");
+        if (!this.managers)
+            throw new DEMError(DEMErrorCode.MANAGERS_NOT_INITIALIZED, `No managers.`);
+        if (this.objects_[_idStr])
+            return this.objects_[_idStr];
+        if (this.pendingMissingFetches.has(_idStr)) {
+            return this.pendingMissingFetches.get(_idStr);
+        }
+        const fetchPromise = (async () => {
+            try {
+                const object = new this.classParam(this.classParam, this.socket, _idStr, this.loggers, this.className, this, this.callbacks, this.emitter);
+                await object.waitForPreloaded();
+                if (object.loadError)
+                    throw new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, object.loadError);
+                this.objects_[object._id.toString()] = object;
+                this._cachedObjectsArray = null;
+                globalCache.objects[object._id.toString()] = {
+                    className: this.className,
+                    object: object,
+                };
+                await object.isPreLoadedAsync();
+                await object.loadMissingReferences();
+                this.callbacks.new(object);
+                return object;
+            }
+            finally {
+                this.pendingMissingFetches.delete(_idStr);
+            }
+        })();
+        this.pendingMissingFetches.set(_idStr, fetchPromise);
+        return fetchPromise;
+    }
+    /**
+     * Creates a new object instance on the server and registers it in local manager state.
+     *
+     * @param data - Object property payload omitting `_id`.
+     * @returns Promise resolving to the newly created client entity.
+     * @throws {DEMError} Throws DEMErrorCode.OBJECT_CREATE_FAILED on failure.
+     */
+    async createObject(data) {
+        if (!this.managers)
+            throw new DEMError(DEMErrorCode.MANAGERS_NOT_INITIALIZED, `No managers.`);
+        this.loggers.debug("Creating new object from manager " + this.className);
+        let createdId = null;
+        try {
+            const object = new this.classParam(this.classParam, this.socket, data, this.loggers, this.className, this, this.callbacks, this.emitter);
+            await object.waitForPreloaded();
+            const id = object._id?.toString() ?? object.data?._id?.toString();
+            if (!id) {
+                throw new DEMError(DEMErrorCode.OBJECT_CREATE_FAILED, `Failed to create ${this.className}: Object _id is missing after preload.`);
+            }
+            createdId = id;
+            this.objects_[id] = object;
+            this._cachedObjectsArray = null;
+            globalCache.objects[id] = {
+                className: this.className,
+                object: object,
+            };
+            await this.objects_[id].isPreLoadedAsync();
+            await this.objects_[id].loadMissingReferences();
+            await this.objects_[id].contactChildren();
+            this.callbacks.new(this.objects_[id]);
+            return this.objects_[id];
+        }
+        catch (error) {
+            if (createdId) {
+                delete this.objects_[createdId];
+                delete globalCache.objects[createdId];
+                this._cachedObjectsArray = null;
+            }
+            this.loggers.error("Error creating new object from manager " + this.className);
+            this.loggers.error(error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+    }
+    /**
+     * Closes the manager and unbinds all socket event listeners.
+     */
+    close() {
+        if (this._reconnectHandler) {
+            this.socket?.off?.("reconnect", this._reconnectHandler);
+            this._reconnectHandler = undefined;
+        }
+        this.socket?.off?.("new" + this.className);
+        this.socket?.off?.("delete" + this.className);
+        for (const id of this.objectIDs) {
+            this.socket?.off?.(EVENT_UPDATE + this.className + id);
+        }
+        super.close();
+    }
+}
+//# sourceMappingURL=AutoUpdateClientManagerClass.js.map