@prestizni-software/server-dem 0.7.4 → 0.7.5

package/AutoUpdateServerManagerClass.js

@@ -0,0 +1,913 @@
+import { AutoUpdateManager } from "./AutoUpdateManagerClass.js";
+import { createAutoUpdatedClass } from "./AutoUpdatedServerObjectClass.js";
+import { globalCache, EVENT_NEW, EVENT_UPDATE, EVENT_DELETE, EVENT_GET, EVENT_STARTUP, EVENT_VERSION, DEM_VERSION, DEM_SERVER_VERSION, DEM_PROTOCOL_VERSION, safeStringify, verifyDEMVersion, DEMError, DEMErrorCode, toDEMError, } from "./CommonTypes.js";
+import { EventEmitter } from "eventemitter3";
+import { getModelForClass } from "@typegoose/typegoose";
+import { ServerChangeTracker, } from "./sync/index.js";
+export var DEMEventTypes;
+(function (DEMEventTypes) {
+    DEMEventTypes["new"] = "new";
+    DEMEventTypes["update"] = "update";
+    DEMEventTypes["delete"] = "delete";
+    DEMEventTypes["get"] = "get";
+    DEMEventTypes["startup"] = "startup";
+})(DEMEventTypes || (DEMEventTypes = {}));
+/**
+ * Configures event whitelisting and permission middleware for the Socket.IO server.
+ *
+ * @param socket_server - Socket.IO server instance.
+ * @param loggers - Logging interfaces.
+ * @param managers - Registry of server managers.
+ * @param _models - Optional models registry.
+ */
+function setupSocketMiddleware(socket_server, loggers, managers, _models) {
+    socket_server.use(async (socket, next) => {
+        socket.use((async (event, nextEvent) => {
+            if (event.length !== 3 ||
+                typeof event[0] !== "string" ||
+                typeof event[2] !== "function") {
+                loggers.warn?.("Invalid event: [" +
+                    event
+                        .map((e) => (typeof e === "object" ? "[object]" : String(e)))
+                        .join("], [") +
+                    "]");
+                return;
+            }
+            if (!socket
+                .eventNames()
+                .some((e) => e.toString() === event[0] ||
+                e.toString() === event[0].slice(0, -24))) {
+                loggers.warn?.("Undefined event: [" +
+                    event
+                        .map((e) => (typeof e === "object" ? "[object]" : String(e)))
+                        .join("], [") +
+                    "]");
+                event[2]({
+                    success: false,
+                    code: DEMErrorCode.UNDEFINED_EVENT,
+                    message: "Undefined event, event: " + event[0] + " not found",
+                });
+                return;
+            }
+            try {
+                const e = event[0];
+                let demEvent;
+                const id = e.slice(-24);
+                switch (true) {
+                    case e.startsWith(EVENT_NEW):
+                        demEvent = {
+                            type: DEMEventTypes.new,
+                            manager: managers[e.replace(EVENT_NEW, "")],
+                            data: event[1],
+                            object: undefined,
+                        };
+                        break;
+                    case e.startsWith(EVENT_UPDATE):
+                        {
+                            const manager = managers[e.replace(EVENT_UPDATE, "").replace(id, "")];
+                            demEvent = {
+                                type: DEMEventTypes.update,
+                                manager: manager,
+                                object: manager.getObject(id),
+                                data: event[1],
+                            };
+                        }
+                        break;
+                    case e.startsWith(EVENT_DELETE):
+                        {
+                            const manager = managers[e.replace(EVENT_DELETE, "")];
+                            const obj = manager.getObject(event[1]);
+                            if (!obj) {
+                                event[2]({
+                                    success: true,
+                                    message: "Object already deleted",
+                                    data: undefined,
+                                });
+                                return;
+                            }
+                            demEvent = {
+                                type: DEMEventTypes.delete,
+                                manager: manager,
+                                object: obj,
+                                data: undefined,
+                            };
+                        }
+                        break;
+                    case e.startsWith(EVENT_GET):
+                        {
+                            const manager = managers[e.replace(EVENT_GET, "").replace(id, "")];
+                            demEvent = {
+                                type: DEMEventTypes.get,
+                                manager: manager,
+                                object: manager.getObject(id),
+                                data: undefined,
+                            };
+                        }
+                        break;
+                    case e.startsWith(EVENT_STARTUP):
+                        demEvent = {
+                            type: DEMEventTypes.startup,
+                            manager: managers[e.replace(EVENT_STARTUP, "")],
+                            object: undefined,
+                            data: undefined,
+                        };
+                        break;
+                    default:
+                        throw new DEMError(DEMErrorCode.UNKNOWN_EVENT, "Unknown event: " +
+                            e +
+                            " - known events: [" +
+                            Object.values(DEMEventTypes).join(", ") +
+                            "]");
+                }
+                try {
+                    await demEvent.manager.options?.accessDefinitions?.eventMiddleware?.(demEvent, managers, socket);
+                    nextEvent();
+                }
+                catch (error) {
+                    loggers.warn?.("Someone got access denied:\nUser (" +
+                        safeStringify(socket.handshake.auth) +
+                        ")\nWith ID: '" +
+                        socket.id +
+                        "'\nFrom: '" +
+                        socket.handshake.address +
+                        "'\nTo the event: '" +
+                        event[0] +
+                        "'\nFor: '" +
+                        (error instanceof Error ? error.message : String(error)) +
+                        "'");
+                    event[2]({
+                        success: false,
+                        code: DEMErrorCode.ACCESS_DENIED,
+                        message: "You were denied access to this event '" +
+                            event[0] +
+                            "' by the server.\n" +
+                            (error instanceof Error ? error.message : String(error)),
+                    });
+                }
+            }
+            catch (error) {
+                const demErr = toDEMError(error, DEMErrorCode.INTERNAL_ERROR);
+                loggers.error?.("Error with event: " +
+                    event[0] +
+                    "\nError: " +
+                    demErr.message);
+                event[2]({
+                    success: false,
+                    code: demErr.code,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                return;
+            }
+        }));
+        next();
+    });
+}
+/**
+ * Inspects database readiness states across all configured server managers.
+ *
+ * @param managers - Registry of server managers to inspect.
+ * @param loggers - Optional logger callbacks.
+ * @param emitter - Optional event emitter for error events.
+ * @throws {DEMError} Throws DEMErrorCode.DB_NOT_CONNECTED if any database is disconnected.
+ */
+export function checkServerDbStates(managers, loggers, emitter) {
+    for (const [key, manager] of Object.entries(managers)) {
+        if (!manager)
+            continue;
+        const status = manager.checkDbState();
+        if (!status.connected) {
+            const err = new DEMError(DEMErrorCode.DB_NOT_CONNECTED, `Server DB state check failed for '${key}': Database is in state '${status.stateName}' (code: ${status.readyState}). Database must be connected before DEM starts loading.`, { manager: key, readyState: status.readyState, stateName: status.stateName });
+            emitter?.emit("error", err);
+            loggers?.error?.(err.message);
+            throw err;
+        }
+    }
+}
+/**
+ * Initializes and starts all server managers, executes DB state assertions, preloads data, and attaches sockets.
+ *
+ * @param defs - Server manager definitions including class constructors and options.
+ * @param loggers_ - Loggers interface.
+ * @param socket - Socket.IO server instance.
+ * @param doDebug - Flag indicating whether debug logging is enabled.
+ * @param emitter - Shared event emitter.
+ * @param models - Optional model registry.
+ * @returns Promise resolving to the map of initialized server managers.
+ */
+export async function AUSManagerFactory(defs, loggers_, socket, doDebug = true, emitter = new EventEmitter(), models) {
+    // Use delegation instead of cloning or direct mutation to ensure late-added spies work
+    const loggers = {
+        info: (s) => loggers_.info?.(s),
+        debug: (s) => (doDebug ? loggers_.debug?.(s) : undefined),
+        error: (s) => loggers_.error?.(s),
+        warn: (s) => loggers_.warn?.(s),
+    };
+    socket.use((socket, next) => {
+        socket.onAny((event) => { });
+        next();
+    });
+    const managers = {};
+    const keys = Object.keys(defs);
+    // 1. Create all managers
+    for (const key of keys) {
+        loggers.debug?.(`Creating manager for ${key}`);
+        const def = defs[key];
+        const model = getModelForClass(def.class);
+        try {
+            const c = new AutoUpdateServerManager(def.class, key, socket, loggers, model, managers, emitter, def.options);
+            managers[key] = c;
+        }
+        catch (error) {
+            loggers.error?.("Error creating manager: " + key);
+            loggers.error?.(error instanceof Error ? error.message : String(error));
+            if (error instanceof Error && error.stack)
+                loggers.error?.(error.stack);
+        }
+    }
+    // 1.5. Inspect database states before loading starts
+    checkServerDbStates(managers, loggers, emitter);
+    // 2. Pre-load all managers in parallel
+    await Promise.all(keys.map(async (key) => {
+        if (!managers[key])
+            return;
+        loggers.debug?.("Loading DB for manager: " + key);
+        try {
+            await managers[key].preLoad();
+        }
+        catch (error) {
+            loggers.error?.("Error loading DB for manager: " + key);
+            loggers.error?.(error instanceof Error ? error.message : String(error));
+            if (error instanceof Error && error.stack)
+                loggers.error?.(error.stack);
+        }
+    }));
+    // 3. Load references for all managers in parallel
+    await Promise.all(Object.values(managers).map(async (manager) => {
+        try {
+            await manager.loadReferences();
+        }
+        catch (error) {
+            loggers.error?.("Error loading DB for manager: " +
+                manager.className +
+                " (loadReferences)");
+            loggers.error?.(error instanceof Error ? error.message : String(error));
+            if (error instanceof Error && error.stack)
+                loggers.error?.(error.stack);
+        }
+    }));
+    socket.on("connection", async (socket) => {
+        loggers.debug?.(`Client connected: ${socket?.id}`);
+        socket?.emit?.(EVENT_VERSION, {
+            version: DEM_VERSION,
+            protocolVersion: DEM_PROTOCOL_VERSION,
+        });
+        for (const manager of Object.values(managers)) {
+            manager.registerSocket(socket);
+        }
+        socket?.on?.("disconnect", () => {
+            loggers.debug?.(`Client disconnected: ${socket?.id}`);
+        });
+    });
+    try {
+        setupSocketMiddleware(socket, loggers, managers, models);
+    }
+    catch (error) {
+        loggers.error?.("Error setting up socket middleware");
+        loggers.error?.(error instanceof Error ? error.message : String(error));
+        if (error instanceof Error && error.stack)
+            loggers.error?.(error.stack);
+    }
+    return managers;
+}
+export class AutoUpdateServerManager extends AutoUpdateManager {
+    model;
+    clientSockets = new Set();
+    knownObjectIdsBySocket = new Map();
+    options;
+    objects_ = {};
+    managers;
+    startupPayloadCache = null;
+    _cachedObjectsArray = null;
+    changeTracker;
+    /**
+     * Initializes an AutoUpdateServerManager instance.
+     *
+     * @param classParam - Target server object class constructor.
+     * @param className - Managed entity class name.
+     * @param socket - Socket.IO Server instance.
+     * @param loggers - Logger callbacks interface.
+     * @param model - Typegoose Mongoose model for database operations.
+     * @param managers - Sibling server managers registry.
+     * @param emitter - Shared event emitter.
+     * @param options - Server manager options including access middlewares and delta sync settings.
+     */
+    constructor(classParam, className, socket, loggers, model, managers, emitter, options) {
+        super(classParam, className, socket, loggers, managers, emitter);
+        this.managers = managers;
+        this.model = model;
+        this.options = options;
+        if (options?.deltaSync) {
+            const deltaOpts = typeof options.deltaSync === "object" ? options.deltaSync : {};
+            if (deltaOpts.enabled !== false) {
+                this.changeTracker = new ServerChangeTracker(this.className, deltaOpts);
+            }
+        }
+    }
+    /**
+     * Inspects current database connection state.
+     *
+     * @returns Object describing connected flag, numeric readyState, and stateName.
+     */
+    checkDbState() {
+        const db = this.model?.db;
+        if (!db || typeof db.readyState !== "number") {
+            return { connected: true, readyState: 1, stateName: "connected" };
+        }
+        const readyState = db.readyState;
+        const stateNames = {
+            0: "disconnected",
+            1: "connected",
+            2: "connecting",
+            3: "disconnecting",
+            99: "uninitialized",
+        };
+        const stateName = stateNames[readyState] ?? "unknown";
+        return {
+            connected: readyState === 1,
+            readyState,
+            stateName,
+        };
+    }
+    /**
+     * Verifies database connection is active.
+     *
+     * @throws {DEMError} Throws DEMErrorCode.DB_NOT_CONNECTED if database is not connected.
+     */
+    assertDbConnected() {
+        const status = this.checkDbState();
+        if (!status.connected) {
+            const err = new DEMError(DEMErrorCode.DB_NOT_CONNECTED, `Database for manager '${this.className}' is in state '${status.stateName}' (code: ${status.readyState}). Database must be connected before DEM starts loading.`, { className: this.className, readyState: status.readyState, stateName: status.stateName });
+            this.emitter.emit("error", err);
+            this.loggers.error?.(err.message);
+            throw err;
+        }
+    }
+    /**
+     * Preloads all database documents into memory for the manager class.
+     *
+     * @param options - Optional batch loading options.
+     * @returns Promise resolving when all entities are loaded and populated in globalCache.
+     */
+    async preLoad(options) {
+        this.assertDbConnected();
+        this.loggers.debug("Loading manager DB " + this.className);
+        const docs = await this.model.find({});
+        // Optimization: Parallelize object creation to ensure all objects are in globalCache
+        // as quickly as possible before reference resolution starts.
+        await Promise.all(docs.map(async (doc) => {
+            const id = doc._id?.toString();
+            if (!id) {
+                this.loggers.debug("Invalid document, no _id: " + (doc?._id ?? "[no id]"));
+                return;
+            }
+            this.objects_[id] =
+                this.objects_[id] ??
+                    (await createAutoUpdatedClass(this.classParam, this.className, this.socket, id, this.loggers, this, this.emitter, doc));
+            globalCache.objects[id] = {
+                className: this.className,
+                object: this.objects_[id],
+            };
+        }));
+        this.startupPayloadCache = null;
+        this._cachedObjectsArray = null;
+        this.loggers.debug("Loaded manager DB " +
+            this.className +
+            " - [" +
+            docs.length +
+            "] entries");
+    }
+    /**
+     * Resolves back-references and pointers across loaded objects.
+     *
+     * @returns Promise resolving when reference resolution completes.
+     */
+    async loadReferences() {
+        // Phase 1: Initial reference resolution (including back-references/createdWithParent)
+        // This MUST happen after all managers have finished preLoad so that all objects exist in globalCache.
+        await Promise.all(this.objectsAsArray.map((object) => object.isPreLoadedAsync()));
+        // Phase 2: Resolve missing references (pointers) and set isLoaded_ = true
+        await super.loadReferences();
+    }
+    /**
+     * Registers a client socket with the manager and binds startup, delete, and new event listeners.
+     *
+     * @param socket - Connected client Socket instance.
+     */
+    registerSocket(socket) {
+        this.clientSockets.add(socket);
+        socket.on(EVENT_STARTUP + this.className, async (req, ack) => {
+            try {
+                const clientVersion = req && typeof req === "object" && typeof req.clientVersion === "string"
+                    ? req.clientVersion
+                    : undefined;
+                if (clientVersion) {
+                    const verResult = verifyDEMVersion(clientVersion, DEM_SERVER_VERSION);
+                    if (!verResult.compatible) {
+                        const errMsg = verResult.message ||
+                            `DEM Version Incompatibility: Client (${clientVersion}) is incompatible with Server (${DEM_SERVER_VERSION})`;
+                        this.loggers.warn?.(`Rejecting client connection from ${socket.id}: ${errMsg}`);
+                        if (typeof ack === "function") {
+                            ack({
+                                success: false,
+                                code: DEMErrorCode.VERSION_MISMATCH,
+                                message: errMsg,
+                            });
+                        }
+                        return;
+                    }
+                }
+                const clientLastRev = req && typeof req === "object" && typeof req.lastRevision === "number"
+                    ? req.lastRevision
+                    : undefined;
+                // Check if delta sync can be fulfilled
+                if (this.changeTracker && typeof clientLastRev === "number") {
+                    let allowedIdsSet = undefined;
+                    if (this.options?.accessDefinitions?.startupMiddleware) {
+                        const allowedObjects = await this.options.accessDefinitions.startupMiddleware(this.objectsAsArray, this.managers, socket);
+                        allowedIdsSet = new Set(allowedObjects.map((obj) => obj._id.toString()).filter(Boolean));
+                        this.knownObjectIdsBySocket.set(socket, new Set(allowedIdsSet));
+                    }
+                    const changesResult = this.changeTracker.getChangesSince(clientLastRev, allowedIdsSet);
+                    if (!changesResult.isExpired) {
+                        if (changesResult.changes.length === 0) {
+                            this.loggers.debug("Client up to date for manager " +
+                                this.className +
+                                " at revision " +
+                                clientLastRev);
+                            if (typeof ack === "function") {
+                                ack({
+                                    data: {
+                                        status: "up-to-date",
+                                        revision: this.changeTracker.getCurrentRevision(),
+                                        ids: [],
+                                        properties: this.properties,
+                                        version: DEM_VERSION,
+                                        protocolVersion: DEM_PROTOCOL_VERSION,
+                                    },
+                                    success: true,
+                                });
+                            }
+                            return;
+                        }
+                        else {
+                            this.loggers.debug("Sending delta startup data (" +
+                                changesResult.changes.length +
+                                " changes) for manager " +
+                                this.className);
+                            if (typeof ack === "function") {
+                                ack({
+                                    data: {
+                                        status: "delta",
+                                        revision: this.changeTracker.getCurrentRevision(),
+                                        changes: changesResult.changes,
+                                        ids: [],
+                                        properties: this.properties,
+                                        version: DEM_VERSION,
+                                        protocolVersion: DEM_PROTOCOL_VERSION,
+                                    },
+                                    success: true,
+                                });
+                            }
+                            return;
+                        }
+                    }
+                }
+                let ids;
+                let objects;
+                if (!this.options?.accessDefinitions?.startupMiddleware && this.startupPayloadCache) {
+                    ids = this.startupPayloadCache.ids;
+                    objects = this.startupPayloadCache.objects ?? [];
+                }
+                else {
+                    const allowedObjects = this.options?.accessDefinitions?.startupMiddleware
+                        ? await this.options.accessDefinitions.startupMiddleware(this.objectsAsArray, this.managers, socket)
+                        : this.objectsAsArray;
+                    ids = allowedObjects.map((obj) => obj._id.toString()).filter(Boolean);
+                    objects = allowedObjects.map((obj) => obj.extractedData).filter(Boolean);
+                    this.knownObjectIdsBySocket.set(socket, new Set(ids));
+                    if (!this.options?.accessDefinitions?.startupMiddleware) {
+                        this.startupPayloadCache = {
+                            ids,
+                            objects,
+                            properties: this.properties,
+                        };
+                    }
+                }
+                this.loggers.debug("Sending startup data for manager " + this.className);
+                if (typeof ack === "function") {
+                    ack({
+                        data: {
+                            status: "full",
+                            revision: this.changeTracker ? this.changeTracker.getCurrentRevision() : 0,
+                            ids,
+                            objects,
+                            properties: this.properties,
+                            version: DEM_VERSION,
+                            protocolVersion: DEM_PROTOCOL_VERSION,
+                        },
+                        success: true,
+                    });
+                }
+            }
+            catch (error) {
+                this.loggers.error("Error sending startup data for manager " +
+                    this.className +
+                    ": " +
+                    (error instanceof Error ? error.message : String(error)));
+                if (error instanceof Error && error.stack)
+                    this.loggers.error(error.stack);
+                const demErr = toDEMError(error, DEMErrorCode.STARTUP_FAILED);
+                if (typeof ack === "function") {
+                    ack({
+                        success: false,
+                        code: demErr.code,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+        socket.on(EVENT_DELETE + this.className, async (id, ack) => {
+            this.loggers.debug("Deleting object from manager " + this.className + " - " + id);
+            try {
+                const res = await this.deleteObject(id);
+                this.startupPayloadCache = null;
+                if (typeof ack === "function") {
+                    if (res && !res.success) {
+                        ack({
+                            success: false,
+                            code: res.code ?? DEMErrorCode.OBJECT_DELETE_FAILED,
+                            message: res.message || "Deletion unsuccessful",
+                        });
+                    }
+                    else {
+                        ack({
+                            success: true,
+                            message: "Deleted successfully",
+                            data: undefined,
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                this.loggers.error("Error deleting object from manager " +
+                    this.className +
+                    " - " +
+                    id +
+                    ": " +
+                    (error instanceof Error ? error.message : String(error)));
+                if (error instanceof Error && error.stack)
+                    this.loggers.error(error.stack);
+                const demErr = toDEMError(error, DEMErrorCode.OBJECT_DELETE_FAILED);
+                if (typeof ack === "function") {
+                    ack({
+                        success: false,
+                        code: demErr.code,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+        socket.on(EVENT_NEW + this.className, async (data, ack) => {
+            this.loggers.debug("Recieved new object creation in manager " + this.className);
+            try {
+                const newDoc = await this.createObject(data);
+                this.startupPayloadCache = null;
+                if (typeof ack === "function") {
+                    ack({
+                        data: newDoc.extractedData,
+                        success: true,
+                        message: "Created successfully",
+                    });
+                }
+            }
+            catch (error) {
+                this.loggers.error("Error creating new object creation in manager " +
+                    this.className +
+                    " - " +
+                    (error instanceof Error ? error.message : String(error)));
+                if (error instanceof Error && error.stack)
+                    this.loggers.error(error.stack);
+                const demErr = toDEMError(error, DEMErrorCode.OBJECT_CREATE_FAILED);
+                if (typeof ack === "function") {
+                    ack({
+                        success: false,
+                        code: demErr.code,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+        // Registered into socket.eventNames() so setupSocketMiddleware can validate and permit dynamic update/get events
+        socket.on(EVENT_UPDATE + this.className, async () => { });
+        socket.on(EVENT_GET + this.className, async () => { });
+        socket.onAny(async (event, data, ack) => {
+            if (event.startsWith(EVENT_UPDATE + this.className) &&
+                event.replace(EVENT_UPDATE + this.className, "").length === 24) {
+                this.loggers.debug("Updating object in manager " +
+                    this.className +
+                    ": " +
+                    event +
+                    " - " +
+                    (typeof data === "object" ? "[object]" : String(data)));
+                try {
+                    const id = event.replace(EVENT_UPDATE + this.className, "");
+                    let obj = this.objects_[id];
+                    if (!obj)
+                        throw new DEMError(DEMErrorCode.OBJECT_GET_FAILED, `Never... failed to get object somehow: ${id}`);
+                    const res = await obj.setValue(data.key, data.value);
+                    if (typeof ack === "function") {
+                        res.success
+                            ? ack({
+                                data: null,
+                                success: res.success,
+                                message: res.msg,
+                            })
+                            : ack({
+                                success: res.success,
+                                code: res.code ?? DEMErrorCode.DB_SAVE_FAILED,
+                                message: res.msg,
+                            });
+                    }
+                }
+                catch (error) {
+                    this.loggers.warn("Failed to update object in manager " + this.className);
+                    const demErr = toDEMError(error, DEMErrorCode.DB_SAVE_FAILED);
+                    if (typeof ack === "function") {
+                        ack({
+                            success: false,
+                            code: demErr.code,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+            else if (event.startsWith(EVENT_GET + this.className) &&
+                event.replace(EVENT_GET + this.className, "").length === 24) {
+                try {
+                    const id = event.replace(EVENT_GET + this.className, "");
+                    let obj = this.objects_[id];
+                    if (!obj)
+                        throw new DEMError(DEMErrorCode.OBJECT_NOT_FOUND, `Object not found: ${id}`);
+                    if (typeof ack === "function") {
+                        ack({
+                            data: obj.extractedData,
+                            success: true,
+                            message: "Updated successfully",
+                        });
+                    }
+                }
+                catch (error) {
+                    this.loggers.error("Error sending startup data for manager " +
+                        this.className +
+                        ": " +
+                        (error instanceof Error ? error.message : String(error)));
+                    if (error instanceof Error && error.stack)
+                        this.loggers.error(error.stack);
+                    const demErr = toDEMError(error, DEMErrorCode.OBJECT_GET_FAILED);
+                    if (typeof ack === "function") {
+                        ack({
+                            success: false,
+                            code: demErr.code,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                }
+            }
+        });
+        socket.on("disconnect", () => {
+            this.clientSockets.delete(socket);
+            this.knownObjectIdsBySocket.delete(socket);
+        });
+    }
+    /**
+     * Retrieves a server managed object by identifier.
+     *
+     * @param _id - Optional entity identifier.
+     * @returns Managed entity instance, null, or undefined.
+     */
+    getObject(_id) {
+        if (!_id)
+            return null;
+        return this.objects_[_id.toString()] || undefined;
+    }
+    /**
+     * Dictionary of all managed entities keyed by their string IDs.
+     *
+     * @returns Map of managed entities.
+     */
+    get objects() {
+        return this.objects_;
+    }
+    /**
+     * Array representation of all managed entities.
+     *
+     * @returns Array containing all managed entities.
+     */
+    get objectsAsArray() {
+        if (!this._cachedObjectsArray) {
+            this._cachedObjectsArray = Object.values(this.objects_);
+        }
+        return this._cachedObjectsArray;
+    }
+    /**
+     * Deletes an entity from database, manager cache, and mutation tracker.
+     *
+     * @param _id - Identifier of entity to delete.
+     * @returns Promise resolving to deletion outcome object.
+     */
+    async deleteObject(_id) {
+        this._cachedObjectsArray = null;
+        const idStr = _id.toString();
+        if (this.changeTracker) {
+            this.changeTracker.recordChange("delete", idStr);
+        }
+        for (const socket of this.clientSockets) {
+            const known = this.knownObjectIdsBySocket.get(socket);
+            if (known) {
+                known.delete(idStr);
+            }
+        }
+        return super.deleteObject(_id);
+    }
+    pendingMissingFetches = new Map();
+    /**
+     * Retrieves an entity missing from memory by querying MongoDB directly.
+     *
+     * @param _id - Identifier of missing entity.
+     * @returns Promise resolving to the retrieved server object.
+     * @throws {DEMError} Throws DEMErrorCode.DOCUMENT_NOT_FOUND or MANAGERS_NOT_INITIALIZED.
+     */
+    async handleGetMissingObject(_id) {
+        const _idStr = _id.toString();
+        if (this.getObject(_idStr))
+            return this.getObject(_idStr);
+        if (this.pendingMissingFetches.has(_idStr)) {
+            return this.pendingMissingFetches.get(_idStr);
+        }
+        const fetchPromise = (async () => {
+            try {
+                const document = await this.model.findById(_idStr);
+                if (!document)
+                    throw new DEMError(DEMErrorCode.DOCUMENT_NOT_FOUND, `No document with id ${_idStr} in DB.`);
+                if (!this.managers)
+                    throw new DEMError(DEMErrorCode.MANAGERS_NOT_INITIALIZED, `No managers.`);
+                const object = await createAutoUpdatedClass(this.classParam, this.className, this.socket, document, this.loggers, this, this.emitter);
+                await object.waitForPreloaded();
+                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();
+                await object.contactChildren();
+                return object;
+            }
+            finally {
+                this.pendingMissingFetches.delete(_idStr);
+            }
+        })();
+        this.pendingMissingFetches.set(_idStr, fetchPromise);
+        return fetchPromise;
+    }
+    /**
+     * Creates a new entity document in MongoDB and instantiates its manager wrapper.
+     * Broadcasts creation event to client sockets with authorized access.
+     *
+     * @param data - Initial entity properties.
+     * @returns Promise resolving to the created server entity.
+     * @throws {DEMError} Throws DEMErrorCode.MANAGERS_NOT_INITIALIZED.
+     */
+    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);
+        const rawRec = { ...data };
+        if (rawRec._id === "" || rawRec._id === null)
+            delete rawRec._id;
+        // Sanitize creation payload to prevent property injection
+        const dataRec = {};
+        for (const key of Object.keys(rawRec)) {
+            if (key !== "__proto__" &&
+                key !== "constructor" &&
+                key !== "prototype" &&
+                (this.properties.includes(key) ||
+                    key === "_id" ||
+                    Boolean(this.model.schema?.path?.(key)))) {
+                const val = rawRec[key];
+                if (val && typeof val === "object") {
+                    if (Array.isArray(val)) {
+                        dataRec[key] = val.map((v) => v && typeof v === "object" && v._id ? v._id.toString() : v);
+                    }
+                    else if (val._id) {
+                        dataRec[key] = val._id.toString();
+                    }
+                    else {
+                        dataRec[key] = val;
+                    }
+                }
+                else {
+                    dataRec[key] = val;
+                }
+            }
+        }
+        const doc = await this.model.create(dataRec);
+        const id = doc._id.toString();
+        const object = await createAutoUpdatedClass(this.classParam, this.className, this.socket, id, this.loggers, this, this.emitter, doc);
+        await object.waitForPreloaded();
+        // Copy virtual references from raw data payload
+        const cleanedData = object.handleDataCleanup(rawRec);
+        for (const key of object.properties) {
+            if (cleanedData[key] !== undefined &&
+                object.data[key] === undefined) {
+                object.data[key] = cleanedData[key];
+            }
+        }
+        this.objects_[id] = object;
+        this._cachedObjectsArray = null;
+        this.startupPayloadCache = null;
+        globalCache.objects[id] = {
+            className: this.className,
+            object: object,
+        };
+        await object.isPreLoadedAsync();
+        await object.loadMissingReferences();
+        await object.contactChildren();
+        if (this.changeTracker) {
+            this.changeTracker.recordChange("create", id, object.extractedData || object.data);
+        }
+        for (const socket of this.clientSockets) {
+            try {
+                const theTruth = this.options?.accessDefinitions?.startupMiddleware
+                    ? await this.options.accessDefinitions.startupMiddleware([object], this.managers, socket)
+                    : [object];
+                if (theTruth.length > 0) {
+                    let known = this.knownObjectIdsBySocket.get(socket);
+                    if (!known) {
+                        known = new Set();
+                        this.knownObjectIdsBySocket.set(socket, known);
+                    }
+                    known.add(id);
+                    this.loggers.debug("Emitting new object " + object._id);
+                    socket.emit("new" + this.className, object._id.toString());
+                }
+            }
+            catch (error) {
+                this.loggers.error("Error when emitting new object to client: " +
+                    (error instanceof Error ? error.name : "Error"));
+                this.loggers.error(error instanceof Error ? error.message : String(error));
+                if (error instanceof Error && error.stack)
+                    this.loggers.error(error.stack);
+            }
+        }
+        return object;
+    }
+    /**
+     * Re-evaluates client socket permissions against dynamic startup middleware rules.
+     * Emits 'new' or 'delete' socket events when client access changes dynamically.
+     *
+     * @param object - Entity to evaluate.
+     */
+    async checkPermissionBoundaries(object) {
+        if (!this.options?.accessDefinitions?.startupMiddleware)
+            return;
+        const id = object._id.toString();
+        for (const socket of this.clientSockets) {
+            try {
+                const theTruth = await this.options.accessDefinitions.startupMiddleware([object], this.managers, socket);
+                const hasAccess = theTruth && theTruth.length > 0;
+                let known = this.knownObjectIdsBySocket.get(socket);
+                if (!known) {
+                    known = new Set();
+                    this.knownObjectIdsBySocket.set(socket, known);
+                }
+                const hadAccess = known.has(id);
+                if (hasAccess && !hadAccess) {
+                    known.add(id);
+                    this.loggers.debug(`Granting dynamic access to ${this.className} ${id} for socket ${socket.id}`);
+                    socket.emit("new" + this.className, id);
+                }
+                else if (!hasAccess && hadAccess) {
+                    known.delete(id);
+                    this.loggers.debug(`Revoking dynamic access to ${this.className} ${id} for socket ${socket.id}`);
+                    socket.emit("delete" + this.className, id);
+                }
+            }
+            catch (error) {
+                this.loggers.error(`Error checking permission boundaries for ${this.className} ${id}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=AutoUpdateServerManagerClass.js.map