@controlium/utils 1.0.1 → 1.0.2-alpha.2

package/dist/esm/detokeniser/detokeniser.js

@@ -31,9 +31,6 @@ const MockUtils = {
  * - **expression** — what to compute (type-specific)
  * - **format** — how to format the result (type-specific, often optional)
  *
- * The delimiter `|` and the `[[` / `]]` endstops are configurable via {@link Detokeniser.delimiter} and
- * {@link Detokeniser.tokenStartEndChars}, but the defaults cover the vast majority of use cases.
- *
  * ---
  * ## Built-in token types
  *
@@ -138,77 +135,21 @@ const MockUtils = {
  *
  * ---
  * ## Extending with callbacks
- * Custom token types are registered via {@link Detokeniser.addCallbackSync} (for sync processing) or
- * {@link Detokeniser.addCallbackAsync} (for async processing). Callbacks are tried in registration
- * order; return `undefined` to pass to the next callback. If all callbacks return `undefined` and no
- * built-in handler matched, an error is thrown.
+ * Custom token types are registered via {@link Detokeniser.addCallback}. Both sync and async handlers
+ * share the same registration method and callback list. Callbacks are tried in registration order;
+ * return `undefined` to pass to the next callback. If all callbacks return `undefined` and no built-in
+ * handler matched, an error is thrown.
+ *
+ * Async callbacks are silently skipped when {@link Detokeniser.do} (sync) is used — use
+ * {@link Detokeniser.doAsync} if your callback returns a Promise.
  *
- * @see {@link Detokeniser.addCallbackSync}
- * @see {@link Detokeniser.addCallbackAsync}
+ * @see {@link Detokeniser.addCallback}
  * @see {@link Detokeniser.do}
  * @see {@link Detokeniser.doAsync}
  */
 export class Detokeniser {
-    /**
-     * Gets the current single-character delimiter used to separate token parts.
-     * Default: `|`
-     */
-    static get delimiter() {
-        return this._delimiter;
-    }
-    /**
-     * Sets the single-character delimiter used to separate token parts.
-     * The new value applies to all subsequent {@link Detokeniser.do} / {@link Detokeniser.doAsync} calls.
-     * @param newDelimiter - Exactly one character
-     * @throws If `newDelimiter` is not exactly one character
-     * @example
-     * Detokeniser.delimiter = ':';
-     * Detokeniser.do('[[random:digits:6]]'); // → e.g. '482910'
-     * Detokeniser.reset();                   // restore default '|'
-     */
-    static set delimiter(newDelimiter) {
-        if (newDelimiter.length !== 1) {
-            const errTxt = `Invalid delimiter [${newDelimiter}].  Must be exactly 1 character!`;
-            Log.writeLine(LogLevels.Error, errTxt);
-            throw new Error(errTxt);
-        }
-        else {
-            this._delimiter = newDelimiter;
-        }
-    }
-    /**
-     * Sets the start and end token sequences.
-     * @param startEndChars - An even-length string whose first half is the start sequence and second half the end sequence.
-     * @example Detokeniser.tokenStartEndChars = "[[]]"; // start = "[[", end = "]]"
-     * @remarks Start and end sequences must differ. Minimum total length is 2 (one char each).
-     */
-    static set tokenStartEndChars(startEndChars) {
-        if (startEndChars.length < 2 || startEndChars.length % 2 !== 0) {
-            const errTxt = `Invalid start/end chars [${startEndChars}]. Must be an even number of characters (minimum 2) — first half as start sequence, second half as end sequence!`;
-            Log.writeLine(LogLevels.Error, errTxt);
-            throw new Error(errTxt);
-        }
-        const half = startEndChars.length / 2;
-        const start = startEndChars.substring(0, half);
-        const end = startEndChars.substring(half);
-        if (start === end) {
-            const errTxt = `Invalid start/end chars — start sequence [${start}] must differ from end sequence [${end}]!`;
-            Log.writeLine(LogLevels.Error, errTxt);
-            throw new Error(errTxt);
-        }
-        this._startTokenChar = start;
-        this._endTokenChar = end;
-    }
-    /**
-     * Gets the current token start/end sequences concatenated (e.g. `"[[]]"`).
-     */
-    static get tokenStartEndChars() {
-        return this._startTokenChar + this._endTokenChar;
-    }
     /**
      * Resets the Detokeniser to factory defaults:
-     * - Token endstops restored to `[[` / `]]`
-     * - Delimiter restored to `|`
      * - Escape char restored to `/`
      * - All registered sync and async callbacks cleared
      *
@@ -217,121 +158,58 @@ export class Detokeniser {
      * afterEach(() => Detokeniser.reset());
      */
     static reset() {
-        this._endTokenChar = "]]";
-        this._startTokenChar = "[[";
         this.EscapeChar = "/";
-        this._delimiter = "|";
-        if (this._syncCallbacks) {
-            this._syncCallbacks = [];
-        }
-        if (this._asyncCallbacks) {
-            this._asyncCallbacks = [];
-        }
-        this._asyncCallbacks = undefined;
-        this._syncCallbacks = undefined;
+        this._callbacks = undefined;
     }
     /**
-     * Registers a synchronous custom token handler.
+     * Registers a custom token handler. Both sync and async handlers are registered via this method
+     * and share the same callback list.
      *
-     * When {@link Detokeniser.do} encounters a token not handled by the built-in set, it invokes each
-     * registered sync callback in registration order. The first to return a non-`undefined` string wins.
-     * Return `undefined` to pass to the next callback. If all callbacks return `undefined`, an error is thrown.
+     * Callbacks are tried in registration order. The first to return a non-`undefined` value wins.
+     * Return `undefined` to pass to the next callback. If all callbacks return `undefined` and no
+     * built-in handler matched, an error is thrown.
      *
-     * @param callback - `(delimiter: string, token: string) => string | undefined`
-     *   - `delimiter` — current delimiter character (default `|`)
-     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"`
+     * Async callbacks (those returning a `Promise`) are silently skipped when {@link Detokeniser.do}
+     * is used — register an async callback only if you intend to call {@link Detokeniser.doAsync}.
+     *
+     * @param callback - `(token: string) => string | undefined | Promise<string | undefined>`
+     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"` (delimiter is always `|`)
      *
      * @example
-     * // Handle [[env|VAR_NAME]] tokens
-     * Detokeniser.addCallbackSync((delimiter, token) => {
-     *   const [type, name] = token.split(delimiter);
-     *   if (type.toLowerCase() !== 'env') return undefined;
+     * // Sync handler for [[env|VAR_NAME]] tokens
+     * Detokeniser.addCallback((token) => {
+     *   const [type, name] = token.split('|');
+     *   if (type !== 'env') return undefined;
      *   return process.env[name] ?? '';
      * });
      * Detokeniser.do('Path: [[env|HOME]]'); // → 'Path: /home/user'
      *
      * @example
-     * // Multiple callbacks — each handles one type, passes on the rest
-     * Detokeniser.addCallbackSync((delimiter, token) => {
-     *   const [type, value] = token.split(delimiter);
-     *   if (type === 'upper') return value.toUpperCase();
-     *   return undefined;
-     * });
-     * Detokeniser.addCallbackSync((delimiter, token) => {
-     *   const [type, value] = token.split(delimiter);
-     *   if (type === 'lower') return value.toLowerCase();
-     *   return undefined;
-     * });
-     * Detokeniser.do('[[upper|hello]] [[lower|WORLD]]'); // → 'HELLO world'
-     *
-     * @see {@link Detokeniser.resetSyncCallbacks} to remove all sync callbacks
-     * @see {@link Detokeniser.addCallbackAsync} for async token handlers
-     */
-    static addCallbackSync(callback) {
-        if (!this._syncCallbacks) {
-            this._syncCallbacks = new Array();
-        }
-        this._syncCallbacks.push(callback);
-    }
-    /**
-     * Registers an asynchronous custom token handler.
-     *
-     * Works identically to {@link Detokeniser.addCallbackSync} but is invoked by {@link Detokeniser.doAsync}.
-     * Async callbacks are tried in registration order; the first to return a non-`undefined` value wins.
-     * Return `undefined` to pass to the next callback.
-     *
-     * @param asyncCallback - `(delimiter: string, token: string) => Promise<string | undefined>`
-     *   - `delimiter` — current delimiter character (default `|`)
-     *   - `token` — full token body without `[[` / `]]`, e.g. `"mytype|arg1|arg2"`
-     *
-     * @example
-     * // Handle [[db|table|column|whereClause]] tokens
-     * Detokeniser.addCallbackAsync(async (delimiter, token) => {
-     *   const [type, table, column, where] = token.split(delimiter);
-     *   if (type.toLowerCase() !== 'db') return undefined;
+     * // Async handler for [[db|table|column|where]] tokens
+     * Detokeniser.addCallback(async (token) => {
+     *   const [type, table, column, where] = token.split('|');
+     *   if (type !== 'db') return undefined;
      *   const row = await db.query(`SELECT ${column} FROM ${table} WHERE ${where} LIMIT 1`);
      *   return String(row[column]);
      * });
      * const result = await Detokeniser.doAsync('ID: [[db|users|id|active=1]]');
      *
-     * @example
-     * // Combine with nested tokens — inner tokens resolve before the callback is called
-     * Detokeniser.addCallbackAsync(async (delimiter, token) => {
-     *   const [type, key] = token.split(delimiter);
-     *   if (type !== 'cache') return undefined;
-     *   return await redis.get(key);
-     * });
-     * // [[random|digits|8]] resolves first, then [[cache|...]] receives the result
-     * await Detokeniser.doAsync('Val: [[cache|prefix-[[random|digits|8]]]]');
-     *
-     * @see {@link Detokeniser.resetAsyncCallbacks} to remove all async callbacks
-     * @see {@link Detokeniser.addCallbackSync} for synchronous token handlers
+     * @see {@link Detokeniser.resetCallbacks} to remove all registered callbacks
+     * @see {@link Detokeniser.doAsync} for async token resolution
      */
-    static addCallbackAsync(asyncCallback) {
-        if (!this._asyncCallbacks) {
-            this._asyncCallbacks = new Array();
+    static addCallback(callback) {
+        if (!this._callbacks) {
+            this._callbacks = new Array();
         }
-        this._asyncCallbacks?.push(asyncCallback);
+        this._callbacks.push(callback);
     }
     /**
-     * Removes all registered sync callbacks. Built-in token handlers are unaffected.
+     * Removes all registered callbacks. Built-in token handlers are unaffected.
      * Use between tests or scenarios to ensure callback isolation.
-     * @see {@link Detokeniser.reset} to also clear async callbacks and restore all defaults
+     * @see {@link Detokeniser.reset} to also restore all defaults
      */
-    static resetSyncCallbacks() {
-        if (this._syncCallbacks) {
-            this._syncCallbacks = [];
-        }
-    }
-    /**
-     * Removes all registered async callbacks. Built-in token handlers are unaffected.
-     * Use between tests or scenarios to ensure callback isolation.
-     * @see {@link Detokeniser.reset} to also clear sync callbacks and restore all defaults
-     */
-    static resetAsyncCallbacks() {
-        if (this._asyncCallbacks) {
-            this._asyncCallbacks = [];
-        }
+    static resetCallbacks() {
+        this._callbacks = undefined;
     }
     /**
      * Synchronously resolves all tokens in the given string and returns the result.
@@ -418,8 +296,8 @@ export class Detokeniser {
      *
      * @example
      * // Async callback for database-driven tokens
-     * Detokeniser.addCallbackAsync(async (delim, token) => {
-     *   const [type, key] = token.split(delim);
+     * Detokeniser.addCallbackAsync(async (token) => {
+     *   const [type, key] = token.split('|');
      *   if (type !== 'db') return undefined;
      *   return await fetchFromDatabase(key);
      * });
@@ -553,9 +431,12 @@ export class Detokeniser {
         //
         try {
             if (Utils.isNullOrUndefined(processedToken)) {
-                if (typeof this._syncCallbacks != "undefined") {
-                    this._syncCallbacks.every((callback) => {
-                        processedToken = callback(this._delimiter, token);
+                if (typeof this._callbacks != "undefined") {
+                    this._callbacks.every((callback) => {
+                        const result = callback(token);
+                        if (result instanceof Promise)
+                            return true; // skip async callbacks in sync context
+                        processedToken = result;
                         return Utils.isNullOrUndefined(processedToken);
                     });
                 }
@@ -586,9 +467,9 @@ export class Detokeniser {
         //
         try {
             if (Utils.isNullOrUndefined(processedToken)) {
-                if (typeof this._asyncCallbacks != "undefined") {
-                    for (let i = 0; i < this._asyncCallbacks.length; i++) {
-                        processedToken = await this._asyncCallbacks[i](this._delimiter, token);
+                if (typeof this._callbacks != "undefined") {
+                    for (const callback of this._callbacks) {
+                        processedToken = await Promise.resolve(callback(token));
                         if (!Utils.isNullOrUndefined(processedToken))
                             break;
                     }
@@ -834,7 +715,7 @@ export class Detokeniser {
             case "addhours":
                 returnDate = addHours(date, this.getParsedDateOffset(dateTokenPrep.params, dateTokenPrep.errParseDateOffset)).getTime();
                 break;
-            case "addMinutes":
+            case "addminutes":
                 returnDate = addMinutes(date, this.getParsedDateOffset(dateTokenPrep.params, dateTokenPrep.errParseDateOffset)).getTime();
                 break;
             case "followingday": {
@@ -1060,8 +941,7 @@ Detokeniser._endTokenChar = "]]";
 Detokeniser._startTokenChar = "[[";
 Detokeniser.EscapeChar = "/";
 Detokeniser._delimiter = "|";
-Detokeniser._asyncCallbacks = undefined;
-Detokeniser._syncCallbacks = undefined;
+Detokeniser._callbacks = undefined;
 class InnermostToken {
     constructor(inputString, StartTokenChar, EndTokenChar, EscapeChar) {
         let startIndex = -1;

package/dist/esm/index.js

@@ -4,3 +4,4 @@ export const LogLevels = Logger.Levels;
 export { JsonUtils } from "./jsonUtils/jsonUtils";
 export { StringUtils } from "./stringUtils/stringUtils";
 export { Utils, ExistingFileWriteActions } from "./utils/utils";
+export { Mock } from "./mock/mock";

package/dist/esm/logger/logger.js

@@ -485,7 +485,7 @@ export class Logger {
         const stackObj = {};
         Error.captureStackTrace(stackObj, this.writeLine);
         const stack = stackObj?.stack ?? "[Unknown]";
-        const callingMethodDetails = this.callingMethodDetails(stack);
+        const callingMethodDetails = this.callingMethodDetails(stack, options?.stackOffset ?? 0);
         const maxLines = options?.maxLines ?? this.options.writeLine.maxLines;
         const suppressAllPreamble = options?.suppressAllPreamble ??
             this.options.writeLine.suppressAllPreamble;
@@ -705,7 +705,7 @@ export class Logger {
                 return this.pad(levelOfWrite, WRITE_TYPE_PAD_WIDTH);
         }
     }
-    static callingMethodDetails(methodBase) {
+    static callingMethodDetails(methodBase, stackOffset = 0) {
         let methodName = "<Unknown>";
         let typeName = "";
         if (methodBase) {
@@ -717,7 +717,9 @@ export class Logger {
                     .findIndex((item) => !item.includes(LOGGER_STACK_FRAME_MARKER));
                 indexOfFirstNonLogLine =
                     indexOfFirstNonLogLine === -1 ? 1 : indexOfFirstNonLogLine + 1;
-                methodName = methodBaseLines[indexOfFirstNonLogLine]
+                const safeOffset = Math.max(0, stackOffset);
+                const targetIndex = Math.min(indexOfFirstNonLogLine + safeOffset, methodBaseLines.length - 1);
+                methodName = methodBaseLines[targetIndex]
                     .replace(/\s\s+/g, " ")
                     .trim();
                 if (methodName.startsWith("at ")) {