@leyyo/common 1.3.19 → 1.3.20

package/dist/common/error.common.js

@@ -3,6 +3,7 @@ import * as stackTraceParser from "stacktrace-parser";
 import { FQN } from "../internal.js";
 import { KEY_ERROR_DEFAULT_MESSAGE, KEY_ERROR_EMIT, KEY_ERROR_EMITTED, KEY_ERROR_I18N, KEY_ERROR_RAISED, VAL_ERROR_UNKNOWN_MESSAGE, VAL_ERROR_UNKNOWN_NAME, } from "../const/index.js";
 const where = `${FQN}.ErrorCommon`;
+// noinspection JSUnusedGlobalSymbols
 export class ErrorCommon {
     leyyo;
     _knownPackages;
@@ -11,6 +12,16 @@ export class ErrorCommon {
     constructor(leyyo) {
         this.leyyo = leyyo;
     }
+    // region private
+    /**
+     * Transform error as a bare object
+     *
+     * @param {Error} err - error instance
+     * @param {Opt} existing - existing parameters
+     * @param {boolean} ignoreNameMessage - ignore name & message?
+     * @param {WeakSet} weakSet - weak set to prevent duplicates
+     * @return {Opt?} - bare error object
+     * */
     _toErrorJson(err, existing, ignoreNameMessage, weakSet) {
         if (!(err instanceof Error)) {
             return undefined;
@@ -67,6 +78,12 @@ export class ErrorCommon {
             }
         }
     }
+    /**
+     * Build error info part as `<part1/part2>`
+     *
+     * @param {Array<string|number>} parts - parts for info
+     * @return {string}
+     * */
     _buildTextParts(parts) {
         parts = parts
             .map((p) => {
@@ -84,6 +101,9 @@ export class ErrorCommon {
             .filter(Boolean);
         return parts.length > 0 ? "<" + parts.join("/") + "> " : "";
     }
+    // endregion private
+    // region public
+    /** @inheritDoc */
     setConfigItem(clazz, conf) {
         if (!isClass(clazz)) {
             throw new this.leyyo.developerError("Invalid package name", testCase(FQN, 230), where);
@@ -101,6 +121,7 @@ export class ErrorCommon {
             setSymbol(clazz, KEY_ERROR_I18N, conf.i18n);
         }
     }
+    /** @inheritDoc */
     getConfigItem(clazz) {
         return {
             message: getSymbol(clazz, KEY_ERROR_DEFAULT_MESSAGE),
@@ -108,20 +129,25 @@ export class ErrorCommon {
             i18n: getSymbol(clazz, KEY_ERROR_I18N),
         };
     }
+    /** @inheritDoc */
     emit(err) {
         if (!(err instanceof Error)) {
             return;
         }
+        // already emitted
         if (getSymbol(err, KEY_ERROR_EMITTED)) {
             return;
         }
         const clazz = err.constructor;
+        // error does not support to emit
         if (!getSymbol(clazz, KEY_ERROR_EMIT)) {
             return;
         }
+        // prevent duplicated emits
         setSymbol(err, KEY_ERROR_EMITTED, true);
         this.leyyo.eventCommon.emit("error:emit", err);
     }
+    /** @inheritDoc */
     buildStack(source, force) {
         const err = source;
         if (!force && Array.isArray(err.stackTrace)) {
@@ -188,14 +214,18 @@ export class ErrorCommon {
             }
         }
         catch (e) {
+            // none
         }
     }
+    /** @inheritDoc */
     toJsonBasic(err, existing) {
         return this._toErrorJson(err, existing, true, new WeakSet());
     }
+    /** @inheritDoc */
     toJsonFull(err, existing) {
         return this._toErrorJson(err, existing, false, new WeakSet());
     }
+    /** @inheritDoc */
     cast(e, params) {
         if (!(e instanceof Error)) {
             return new this.leyyo.leyyoError(secureJson(e));
@@ -208,6 +238,7 @@ export class ErrorCommon {
         err.causedBy = e;
         return err;
     }
+    /** @inheritDoc */
     forcedCast(clazz, e, params) {
         if (!(e instanceof Error)) {
             return new this.leyyo.leyyoError(secureJson(e));
@@ -223,6 +254,7 @@ export class ErrorCommon {
         err.causedBy = e;
         return err;
     }
+    /** @inheritDoc */
     addKnownPackage(packageName, shortName) {
         if (!isText(packageName)) {
             throw new this.leyyo.developerError("Invalid package name", testCase(FQN, 230), where);
@@ -238,6 +270,7 @@ export class ErrorCommon {
         }
         this._knownPackages.set(packageName, shortName);
     }
+    /** @inheritDoc */
     bareObj(err) {
         if (err instanceof Error) {
             return {
@@ -250,6 +283,7 @@ export class ErrorCommon {
             message: VAL_ERROR_UNKNOWN_MESSAGE,
         };
     }
+    /** @inheritDoc */
     text(err, ...parts) {
         const info = parts.length > 0 ? this._buildTextParts(parts) : "";
         if (err instanceof Error) {
@@ -257,6 +291,7 @@ export class ErrorCommon {
         }
         return `${info}[err:${VAL_ERROR_UNKNOWN_NAME}] => ^/${VAL_ERROR_UNKNOWN_MESSAGE}/$`;
     }
+    /** @inheritDoc */
     addStat(p1) {
         let num = -1;
         try {
@@ -288,9 +323,11 @@ export class ErrorCommon {
             this._stats.set(clazz, num);
         }
         catch (e) {
+            // nothing
         }
         return num;
     }
+    /** @inheritDoc */
     getStat(p1) {
         try {
             let clazz;
@@ -309,15 +346,18 @@ export class ErrorCommon {
             return this._stats.get(clazz) ?? 0;
         }
         catch (e) {
+            // nothing
         }
         return 0;
     }
+    /** @inheritDoc */
     clearStats() {
         if (!this._stats) {
             return;
         }
         this._stats.clear();
     }
+    /** @inheritDoc */
     listStats() {
         if (!this._stats) {
             return {};

package/dist/common/error.pool.d.ts

@@ -1,13 +1,22 @@
 import { Inert } from "./inert.js";
 import { ErrorPoolItem, ErrorPoolLike, ErrorPoolOpt } from "./index.types.js";
 import { ClassLike, LeyyoLike } from "../base/index.js";
+/**
+ * Error pool for call with name and lazy loading
+ * */
 export declare class ErrorPool extends Inert<ErrorPoolItem, ClassLike, ErrorPoolOpt> implements ErrorPoolLike {
     protected leyyo: LeyyoLike;
     constructor(leyyo: LeyyoLike);
+    /** @inheritDoc */
     protected _getName(target: ClassLike): string;
+    /** @inheritDoc */
     protected _nextLoad(_item: ErrorPoolItem): Promise<void>;
+    /** @inheritDoc */
     protected _setName(target: ClassLike, _name: string): string;
+    /** @inheritDoc */
     protected _afterTargetFound(item: ErrorPoolItem): void;
+    /** @inheritDoc */
     protected _validate(target: ClassLike): boolean;
+    /** @inheritDoc */
     define(fqn: string, target: ClassLike, opt?: Omit<ErrorPoolOpt, "name" | "target" | "lazyTarget" | "fqn">): void;
 }

package/dist/common/error.pool.js

@@ -1,18 +1,26 @@
 import { Inert } from "./inert.js";
 import { isClass } from "../function/index.js";
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Error pool for call with name and lazy loading
+ * */
 export class ErrorPool extends Inert {
     leyyo;
     constructor(leyyo) {
         super(leyyo, "error", { anonymousName: "Error" });
         this.leyyo = leyyo;
     }
+    /** @inheritDoc */
     _getName(target) {
         return target?.name;
     }
+    /** @inheritDoc */
     async _nextLoad(_item) { }
+    /** @inheritDoc */
     _setName(target, _name) {
         return target?.name;
     }
+    /** @inheritDoc */
     _afterTargetFound(item) {
         if (item.lazyTarget) {
             delete item.lazyTarget;
@@ -23,9 +31,11 @@ export class ErrorPool extends Inert {
             i18n: item.i18n,
         });
     }
+    /** @inheritDoc */
     _validate(target) {
         return isClass(target);
     }
+    /** @inheritDoc */
     define(fqn, target, opt) {
         this.register({ ...(opt ?? {}), fqn, target });
     }

package/dist/common/event.common.d.ts

@@ -1,5 +1,8 @@
 import { EventCommonLike, EventType } from "./index.types.js";
 import { Fnc, LeyyoLike } from "../base/index.js";
+/**
+ * Event common interface
+ * */
 export declare class EventCommon<T extends string> implements EventCommonLike<T> {
     private leyyo;
     private readonly _emitter;
@@ -8,9 +11,14 @@ export declare class EventCommon<T extends string> implements EventCommonLike<T>
     private readonly _removedEvents;
     private readonly _deactivatedEvents;
     constructor(leyyo: LeyyoLike);
+    /** @inheritDoc */
     fork<F extends string>(): EventCommonLike<T | F>;
+    /** @inheritDoc */
     emit(name: T, ...values: Array<unknown>): boolean;
+    /** @inheritDoc */
     listen<T extends string = string>(name: EventType | T, callback: Fnc): void;
+    /** @inheritDoc */
     deactivate(name: string): boolean;
+    /** @inheritDoc */
     activate(name: string): boolean;
 }

package/dist/common/event.common.js

@@ -2,12 +2,16 @@ import { FQN } from "../internal.js";
 import { isText, testCase } from "../function/index.js";
 import EventEmitter from "node:events";
 const where = `${FQN}.EventCommon`;
+// noinspection JSUnusedGlobalSymbols
+/**
+ * Event common interface
+ * */
 export class EventCommon {
     leyyo;
     _emitter = new EventEmitter();
     _listenedEvents;
     _waitingEvents;
-    _removedEvents;
+    _removedEvents; // stored, emitted
     _deactivatedEvents;
     constructor(leyyo) {
         this.leyyo = leyyo;
@@ -16,14 +20,17 @@ export class EventCommon {
         this._removedEvents = this.leyyo.repoCommon.newMap(`${where}.removedEvents`);
         this._deactivatedEvents = this.leyyo.repoCommon.newSet(`${where}.deactivatedEvents`);
     }
+    /** @inheritDoc */
     fork() {
         return this;
     }
+    /** @inheritDoc */
     emit(name, ...values) {
         if (!isText(name)) {
             throw new this.leyyo.developerError("Invalid event name", testCase(FQN, 130), where);
         }
         if (!this._emitter.emit(name, ...values)) {
+            // It is deactivated, no collect it anymore
             if (this._deactivatedEvents.has(name)) {
                 return true;
             }
@@ -44,20 +51,22 @@ export class EventCommon {
                     this._removedEvents.set(name, parts);
                 }
                 else if (parts[0] >= 10_000) {
+                    // there are too many events, and there is no any listener, close it
                     if (parts[1] > 50_000) {
                         this.deactivate(name);
                         return false;
                     }
+                    // clear half of it
                     parts[0] = 5_000;
                     item.splice(0, 5_000);
-                    parts[1]++;
+                    parts[1]++; // increment emitted
                     this.leyyo.logger.warn(`Removed all messages. name: ${name}, times: ${parts[1]}`, {
                         where,
                         eventName: name,
                     });
                 }
                 else {
-                    parts[1]++;
+                    parts[1]++; // increment emitted
                     item.shift();
                 }
             }
@@ -66,6 +75,7 @@ export class EventCommon {
         }
         return true;
     }
+    /** @inheritDoc */
     listen(name, callback) {
         if (!isText(name)) {
             throw new this.leyyo.developerError("Invalid event name", testCase(FQN, 130), where);
@@ -78,6 +88,7 @@ export class EventCommon {
             this._emitter.removeAllListeners(name);
         }
         this._emitter.on(name, callback);
+        // if there is a listener, event will be activated automatically
         this.activate(name);
         this._listenedEvents.set(name, callback);
         if (!exists) {
@@ -89,6 +100,7 @@ export class EventCommon {
             }
         }
     }
+    /** @inheritDoc */
     deactivate(name) {
         if (!isText(name)) {
             throw new this.leyyo.developerError("Invalid event name", testCase(FQN, 132), where);
@@ -109,6 +121,7 @@ export class EventCommon {
         this._deactivatedEvents.add(name);
         return true;
     }
+    /** @inheritDoc */
     activate(name) {
         if (!isText(name)) {
             throw new this.leyyo.developerError("Invalid event name", testCase(FQN, 133), where);