@prestizni-software/client-dem 0.7.2 → 0.7.5

package/dist/AutoUpdateManagerClass.js

@@ -1,4 +1,4 @@
-import { globalCache, } from "./CommonTypes.js";
+import { globalCache, DEMError, DEMErrorCode, } from "./CommonTypes.js";
 import "reflect-metadata";
 export class AutoUpdateManager {
     isLoaded_ = false;
@@ -19,9 +19,21 @@ export class AutoUpdateManager {
         warn: () => { },
     };
     emitter;
+    /**
+     * Initializes the base AutoUpdateManager instance.
+     * Extracts registered property metadata from the class prototype.
+     *
+     * @param classParam - The constructor function of the managed object class.
+     * @param className - The name identifier of the managed class.
+     * @param socket - The socket instance (client Socket.IO or server Server).
+     * @param loggers - Logging interfaces for info, debug, warn, and error levels.
+     * @param managers - Registry of sibling managers.
+     * @param emitter - Event emitter for manager and lifecycle events.
+     * @throws {DEMError} Throws DEMErrorCode.MISSING_ARGUMENT when classParam is omitted.
+     */
     constructor(classParam, className, socket, loggers, managers, emitter) {
         if (!classParam)
-            throw new Error("Missing required argument: classParam");
+            throw new DEMError(DEMErrorCode.MISSING_ARGUMENT, "Missing required argument: classParam");
         this.className = className;
         this.managers = managers;
         this.emitter = emitter;
@@ -43,9 +55,17 @@ export class AutoUpdateManager {
         this.loggers.error = (s) => loggers.error?.("[DEM - " + className + " MANAGER] " + s);
         this.loggers.warn = (s) => loggers.warn?.("[DEM - " + className + " MANAGER] " + s);
     }
+    /**
+     * Indicates whether the manager has completed its initialization and reference loading.
+     *
+     * @returns True when the manager is fully loaded.
+     */
     get isLoaded() {
         return this.isLoaded_;
     }
+    /**
+     * Closes the manager, purges cached objects, and disconnects the underlying socket.
+     */
     close() {
         for (const id of this.objectIDs) {
             delete this.objects_[id];
@@ -55,10 +75,22 @@ export class AutoUpdateManager {
             this.socket.disconnectSockets?.(true);
         this.loggers.info("Goodbye, see you next time!");
     }
+    /**
+     * Asynchronously loads unresolved references across all managed objects.
+     * Marks the manager as loaded upon completion.
+     *
+     * @returns A promise that resolves when all references are loaded.
+     */
     async loadReferences() {
         await Promise.all(this.objectsAsArray.map((obj) => obj.loadMissingReferences()));
         this.isLoaded_ = true;
     }
+    /**
+     * Deletes an object by its identifier, destroys the instance, and clears global caches.
+     *
+     * @param _id - The unique identifier of the object to delete.
+     * @returns A promise resolving to the deletion result object.
+     */
     async deleteObject(_id) {
         const _idStr = _id.toString();
         const o = this.objects_[_idStr];
@@ -73,6 +105,11 @@ export class AutoUpdateManager {
         o?.callbacks?.delete?.(this);
         return res ?? { success: true, message: "Already gone" };
     }
+    /**
+     * Retrieves an array of all managed object string identifiers.
+     *
+     * @returns Array of object ID strings.
+     */
     get objectIDs() {
         return Object.keys(this.objects_);
     }

package/dist/AutoUpdateManagerClass.js.map

@@ -1 +1 @@
-{"version":3,"file":"AutoUpdateManagerClass.js","sourceRoot":"","sources":["../AutoUpdateManagerClass.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AutoUpdateManagerClass.js","sourceRoot":"","sources":["../AutoUpdateManagerClass.ts"],"names":[],"mappings":"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"}

package/dist/AutoUpdatedClientObjectClass.d.ts

@@ -1,5 +1,5 @@
 import "reflect-metadata";
-import { Constructor, EventEmitter3, IsData, LoggersType, PathValueOf, ServerUpdateRequest, Paths, ExtractedData, MongoId, IAutoUpdatedClientObject, IAutoUpdatedClientObjectBase, IAutoUpdateManager, DEMCache } from "./CommonTypes.js";
+import { Constructor, EventEmitter3, IsData, LoggersType, PathValueOf, ServerUpdateRequest, Paths, ExtractedData, MongoId, IAutoUpdatedClientObject, IAutoUpdatedClientObjectBase, IAutoUpdateManager, DEMCache, DEMErrorCode } from "./CommonTypes.js";
 import { ObjectId } from "bson";
 import { Socket } from "socket.io-client";
 export type DEMClientCallbacks<T extends object> = {
@@ -36,13 +36,62 @@ export declare abstract class AutoUpdatedClientObject<T extends IAutoUpdatedClie
     }[];
     callbacks: DEMClientCallbacks<T>;
     private readonly loadReferencesAsync;
+    /**
+     * 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?: Constructor<T>, socket?: SocketType, data?: string | IsData<T>, loggers?: LoggersType, className?: string, parentManager?: IAutoUpdateManager<IAutoUpdatedClientObject<any>>, callback?: DEMClientCallbacks<T>, emitter?: EventEmitter3, isServer?: boolean);
+    /**
+     * Normalizes reference fields in entity data into string IDs.
+     *
+     * @param data - Entity data payload.
+     * @returns Cleaned entity data payload.
+     */
     protected handleDataCleanup(data: IsData<T>): IsData<T>;
+    /**
+     * 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.
+     */
     waitForPreloaded(timeoutMs?: number): Promise<void>;
+    /**
+     * Emits creation event to the server socket and awaits populated entity response.
+     *
+     * @param data - Initial data payload.
+     */
     protected handleNewObject(data: IsData<T>): void;
+    /**
+     * Returns a deep clone of the entity's extracted data with reference objects converted to IDs.
+     *
+     * @returns Serialized entity representation.
+     */
     get extractedData(): ExtractedData<T, IAutoUpdatedClientObject<any>>;
+    /**
+     * Indicates whether the entity has finished loading its data.
+     *
+     * @returns True if loaded.
+     */
     get isLoaded(): boolean;
+    /**
+     * Asynchronously awaits preloading and loads all missing reference links.
+     *
+     * @returns Promise resolving to true when completed.
+     */
     isPreLoadedAsync(): Promise<boolean>;
+    /**
+     * Identifies and connects missing cross-entity references on server startup.
+     */
     loadMissingReferences(): Promise<void>;
     private openSockets;
     private handleUpdateRequest;
@@ -51,21 +100,55 @@ export declare abstract class AutoUpdatedClientObject<T extends IAutoUpdatedClie
     get updateEventName(): string;
     getRawId(key: string): string | undefined;
     generateSettersAndGetters(): void;
+    /**
+     * Retrieves a property value by dot-notated or shallow key path.
+     *
+     * @param key_ - Property key or dot-delimited path.
+     * @returns Value at the requested path.
+     */
     getValue<K extends Paths<T, IAutoUpdatedClientObject<any>>>(key_: K): PathValueOf<T, K>;
     getValue(key_: string): any;
+    /**
+     * 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: string | ObjectId, key: string): IAutoUpdatedClientObject<any> | 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.
+     */
     setValue<K extends string>(key: K, val: PathValueOf<IsData<T>, K>): Promise<{
         success: boolean;
         msg: string;
+        code?: DEMErrorCode;
     }>;
+    /**
+     * 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.
+     */
     protected setValue__(key: string, val: unknown, silent?: boolean, noGet?: boolean, noUpdate?: boolean, isParentUpdate?: boolean): Promise<{
         success: boolean;
         msg: string;
+        code?: DEMErrorCode;
     }>;
     private setValueQueueInternal;
     protected setValueInternal(key: string, value: unknown, silent?: boolean, noUpdate?: boolean): Promise<{
         success: boolean;
         msg: string;
+        code?: DEMErrorCode;
     }>;
     protected makeUpdate(key: string, value: unknown): ServerUpdateRequest<T>;
     protected resolveReference(id: string): Promise<IAutoUpdatedClientObject<any> | null>;
@@ -74,24 +157,59 @@ export declare abstract class AutoUpdatedClientObject<T extends IAutoUpdatedClie
     destroyImmediate(): void;
     private loadForceReferences;
     protected createdWithParent(pointer: string[], parent: Record<string, unknown>): Promise<void>;
+    /**
+     * Destroys the entity and notifies server socket of deletion.
+     *
+     * @param once - Internal flag preventing infinite recursion.
+     * @returns Promise resolving to deletion outcome.
+     */
     destroy(once?: boolean): Promise<{
         success: boolean;
         message: string;
+        code?: DEMErrorCode;
     }>;
     private checkForMissingRefs;
     private findMissingObjectReference;
+    /**
+     * Triggers missing reference resolution on all child referenced entities.
+     */
     contactChildren(): Promise<void>;
     protected onUpdate(noUpdate?: boolean, key?: string): Promise<void>;
     protected onDeletion(): Promise<void>;
 }
+/**
+ * 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 declare function processIsRefProperties(instance: Record<string, unknown>, target: object, prefix: string | null, allProps: string[], newData: Record<string, unknown>, loggers: LoggersType): {
     allProps: string[];
     newData: Record<string, unknown>;
 };
+/**
+ * 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 declare function setupClassAccessors(classParam: Constructor<any>): {
     properties: string[];
     refProps: Set<string>;
     refsToMap: Map<string, string>;
 };
+/**
+ * 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 declare function getMetadataRecursive(metaKey: string, proto: object | null, prop: string): unknown;
 export {};

package/dist/AutoUpdatedClientObjectClass.js

@@ -1,6 +1,6 @@
 import "reflect-metadata";
 import _ from "lodash";
-import { EVENT_INTERNAL_PRE_LOADED, EVENT_DELETE, EVENT_GET, EVENT_NEW, EVENT_UPDATE, globalCache, } from "./CommonTypes.js";
+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;
@@ -45,6 +45,20 @@ export class AutoUpdatedClientObject {
             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 ||
@@ -72,7 +86,7 @@ export class AutoUpdatedClientObject {
                 !emitter)
                 return;
             else
-                throw new Error("Missing arguments???");
+                throw new DEMError(DEMErrorCode.MISSING_ARGUMENT, "Missing arguments for AutoUpdatedClientObject: " + className);
         }
         this.classParam = classParam;
         this.socket = socket;
@@ -135,6 +149,12 @@ export class AutoUpdatedClientObject {
             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;
@@ -169,9 +189,15 @@ export class AutoUpdatedClientObject {
         }
         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 Error(this.loadError);
+            throw new DEMError(DEMErrorCode.OBJECT_LOAD_FAILED, this.loadError);
         if (this.isLoaded)
             return;
         await new Promise((resolve, reject) => {
@@ -179,17 +205,22 @@ export class AutoUpdatedClientObject {
                 const errorMsg = `Timeout waiting for object preloading (${this.className})`;
                 this.loadError = errorMsg;
                 this.isLoading = false;
-                reject(new Error(errorMsg));
+                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 Error(reason));
+                    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) {
@@ -235,18 +266,36 @@ export class AutoUpdatedClientObject {
                 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;
@@ -332,6 +381,13 @@ export class AutoUpdatedClientObject {
         }
         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;
@@ -359,9 +415,27 @@ export class AutoUpdatedClientObject {
         }
         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(() => { })
@@ -380,7 +454,7 @@ export class AutoUpdatedClientObject {
             const isRef = getMetadataRecursive("isRef", this, key);
             const pointer = getMetadataRecursive("refsTo", this, key);
             if (pointer && !isParentUpdate && !silent && !this.isServer) {
-                throw new Error("Cannot set value of a reference pointer directly.");
+                throw new DEMError(DEMErrorCode.CANNOT_SET_REF_DIRECTLY, "Cannot set value of a reference pointer directly.");
             }
             let valueToStore = val;
             if (isRef) {
@@ -411,7 +485,7 @@ export class AutoUpdatedClientObject {
                         (valAtKey && ObjectId.isValid(valAtKey))) {
                         const ref = await this.resolveReference(String(valAtKey));
                         if (!ref)
-                            throw new Error("Could not resolve reference on path: " + key);
+                            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];
@@ -442,9 +516,13 @@ export class AutoUpdatedClientObject {
         }
         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,
-                msg: error instanceof Error ? error.message : String(error),
+                code: demErr.code,
+                msg: demErr.message,
             };
         }
     }
@@ -456,6 +534,7 @@ export class AutoUpdatedClientObject {
             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"),
                 });
             });
@@ -465,7 +544,7 @@ export class AutoUpdatedClientObject {
         const id = this.data?._id ?? this._id;
         if (!id) {
             this.loggers.error?.(`Probably missing the identifier ['_id'] again: ${key} = ${value}`);
-            throw new Error(`Cannot make update for ${this.className} because _id is missing.`);
+            throw new DEMError(DEMErrorCode.MISSING_ID, `Cannot make update for ${this.className} because _id is missing.`);
         }
         return { _id: id.toString(), key, value };
     }
@@ -583,12 +662,22 @@ export class AutoUpdatedClientObject {
             }
         }
     }
+    /**
+     * 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, message: res.message ?? "" });
+                resolve({
+                    success: res.success,
+                    code: res.code,
+                    message: res.message ?? "",
+                });
             });
         });
     }
@@ -638,6 +727,9 @@ export class AutoUpdatedClientObject {
             }
         }
     }
+    /**
+     * Triggers missing reference resolution on all child referenced entities.
+     */
     async contactChildren() {
         if (!this.isServer)
             return;
@@ -667,6 +759,17 @@ export class AutoUpdatedClientObject {
         // 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) {
@@ -697,6 +800,12 @@ export function processIsRefProperties(instance, target, prefix, allProps, newDa
     }
     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() };
@@ -782,6 +891,14 @@ export function setupClassAccessors(classParam) {
     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);