@rapidrest/core 1.15.0 → 2.0.0

package/dist/lib/AlertUtils.js

@@ -45,6 +45,12 @@ export class AlertUtils {
         this.logger = options.logger;
         this.serviceUrl = options.serviceUrl;
     }
+    /** Returns `true` if `status` is a 2XX HTTP success code. Shared by every method below that inspects a
+     * response's status, so a future change to what counts as "success" (e.g. also accepting 304) only needs
+     * to be made in one place. */
+    static isSuccess(status) {
+        return status >= 200 && status < 300;
+    }
     /**
      * Attempts to close the existing alert with the given identifier.
      * @param id The unique identifier of the alert to close.
@@ -52,19 +58,22 @@ export class AlertUtils {
      */
     async close(id, data = {}) {
         try {
-            if (data.note) {
-                data.note = data.note.substring(0, MAX_CHARS_NOTE);
+            // Truncate into a copy rather than the caller's object, so `data` isn't silently modified out from
+            // under a caller that reuses it after this call returns.
+            const payload = { ...data };
+            if (payload.note) {
+                payload.note = payload.note.substring(0, MAX_CHARS_NOTE);
             }
-            if (data.source) {
-                data.source = data.source.substring(0, MAX_CHARS_SOURCE);
+            if (payload.source) {
+                payload.source = payload.source.substring(0, MAX_CHARS_SOURCE);
             }
             const url = `${this.serviceUrl}/${encodeURIComponent(id)}/close`;
-            const response = await axios.post(url, data, {
+            const response = await axios.post(url, payload, {
                 headers: {
                     Authorization: this.auth,
                 }
             });
-            return response.status >= 200 && response.status < 300;
+            return AlertUtils.isSuccess(response.status);
         }
         catch (err) {
             this.logger?.error("Failed to close alert with id " + id);
@@ -87,9 +96,7 @@ export class AlertUtils {
             });
             // axios's default validateStatus already rejects (throws) any non-2xx response before we get here, so
             // the alternate branch below is unreachable under normal operation; kept as defense in depth.
-            return response.status >= 200 && response.status < 300
-                ? response.data
-                : /* v8 ignore next */ null;
+            return AlertUtils.isSuccess(response.status) ? response.data : /* v8 ignore next */ null;
         }
         catch (err) {
             this.logger?.error("Failed to retrieve alert with id " + id);
@@ -107,41 +114,50 @@ export class AlertUtils {
      */
     async send(alert, vars = {}, attachments) {
         try {
-            // Truncate the various properties to the maximimum allowed by the most restrictive known API (e.g. OpsGenie)
-            alert.alias = alert.alias.substring(0, MAX_CHARS_ALIAS);
-            alert.description = alert.description.substring(0, MAX_CHARS_DESCRIPTION);
-            if (alert.entity) {
-                alert.entity = alert.entity.substring(0, MAX_CHARS_ENTITY);
+            // Substitute/truncate into a copy rather than the caller's `alert` object. `Alert` is a natural
+            // template to define once and reuse across multiple send() calls with different `vars` - mutating it
+            // in place would leave later calls with no "{{placeholder}}" left to substitute, since the first call
+            // already overwrote them with the first call's resolved values.
+            const payload = { ...alert };
+            // Perform variable substitution on the alert's text fields *before* truncating them below. Note:
+            // these fields are treated as plain data, never as a template to compile/execute, since
+            // `description`/`message`/`note` frequently originate from untrusted event or exception text and
+            // must not be interpretable as code.
+            payload.description = StringUtils.findAndReplace(payload.description, vars);
+            payload.message = StringUtils.findAndReplace(payload.message, vars);
+            if (payload.note) {
+                payload.note = StringUtils.findAndReplace(payload.note, vars);
+            }
+            // Truncate the various properties to the maximimum allowed by the most restrictive known API (e.g.
+            // OpsGenie). Done *after* substitution above - substituting into an already-truncated string could
+            // expand a short placeholder (e.g. a long exception message) past the API's limit, defeating the
+            // truncation this is meant to guarantee.
+            payload.alias = payload.alias.substring(0, MAX_CHARS_ALIAS);
+            payload.description = payload.description.substring(0, MAX_CHARS_DESCRIPTION);
+            if (payload.entity) {
+                payload.entity = payload.entity.substring(0, MAX_CHARS_ENTITY);
             }
-            alert.message = alert.message.substring(0, MAX_CHARS_MESSAGE);
-            if (alert.note) {
-                alert.note = alert.note.substring(0, MAX_CHARS_NOTE);
+            payload.message = payload.message.substring(0, MAX_CHARS_MESSAGE);
+            if (payload.note) {
+                payload.note = payload.note.substring(0, MAX_CHARS_NOTE);
             }
-            alert.source = alert.source.substring(0, MAX_CHARS_SOURCE);
-            if (alert.tags) {
+            payload.source = payload.source.substring(0, MAX_CHARS_SOURCE);
+            if (payload.tags) {
                 let tags = [];
-                for (let i = 0; i < Math.min(MAX_TAGS, alert.tags.length); i++) {
-                    const tag = alert.tags[i];
+                for (let i = 0; i < Math.min(MAX_TAGS, payload.tags.length); i++) {
+                    const tag = payload.tags[i];
                     tags.push(tag.substring(0, MAX_CHARS_TAGS));
                 }
-                alert.tags = tags;
+                payload.tags = tags;
             }
-            // Perform variable substitution on the alert's text fields. Note: these fields are treated as plain
-            // data, never as a template to compile/execute, since `description`/`message`/`note` frequently
-            // originate from untrusted event or exception text and must not be interpretable as code.
-            alert.description = StringUtils.findAndReplace(alert.description, vars);
-            alert.message = StringUtils.findAndReplace(alert.message, vars);
-            if (alert.note) {
-                alert.note = StringUtils.findAndReplace(alert.note, vars);
-            }
-            let response = await axios.post(this.serviceUrl, alert, {
+            let response = await axios.post(this.serviceUrl, payload, {
                 headers: {
                     Authorization: this.auth,
                 }
             });
             // axios's default validateStatus already rejects (throws) any non-2xx response before we get here, so
             // the alternate branch below is unreachable under normal operation; kept as defense in depth.
-            const requestId = response.status >= 200 && response.status < 300
+            const requestId = AlertUtils.isSuccess(response.status)
                 ? response.data.requestId
                 : /* v8 ignore next */ null;
             if (!requestId) {
@@ -191,10 +207,10 @@ export class AlertUtils {
                     }, attachments.indexFile);
                 }
                 else {
-                    // Upload each attachment individually
-                    for (const file of attachments.files) {
-                        await this.addAttachment(id, file, attachments.indexFile);
-                    }
+                    // Upload each attachment individually and concurrently - they're independent uploads to
+                    // different destinations, so there's no need to serialize them and pay N round-trips of
+                    // latency on this alerting path where fast delivery matters most.
+                    await Promise.all(attachments.files.map((file) => this.addAttachment(id, file, attachments.indexFile)));
                 }
             }
             return id;
@@ -230,7 +246,7 @@ export class AlertUtils {
                     Authorization: this.auth
                 }
             });
-            return response.status >= 200 && response.status < 300;
+            return AlertUtils.isSuccess(response.status);
         }
         catch (err) {
             // Don't fail the rest of the request if attachments fail

package/dist/lib/AlertUtils.js.map

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

package/dist/lib/ApiError.js

@@ -1,4 +1,6 @@
+import { Logger } from "./Logger.js";
 import { StringUtils } from "./StringUtils.js";
+const logger = Logger();
 /**
  * Describes an error that originates from a API service. This class extends the standard `Error` class to include
  * a unique code that can be used to trace an error to source code as well as the HTTP response status returned with
@@ -22,7 +24,12 @@ export class ApiError extends Error {
             this.message = this.ApiMessageTemplate(message, templateVariables);
         }
         catch (error) {
-            // NO-OP 
+            // Falls back to the raw, unsubstituted `message` (already set via `super(message)` above) rather
+            // than propagating - a malformed template/templateVariables shouldn't prevent the error itself from
+            // being constructed and thrown. Logged rather than silently swallowed so a caller-supplied template
+            // bug is still discoverable.
+            logger.warn(`Failed to apply template variables to ApiError message: ${code}`);
+            logger.debug(error);
         }
         Object.setPrototypeOf(this, ApiError.prototype);
     }

package/dist/lib/ApiError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../src/ApiError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAMxB,kBAAkB,CAAC,OAA2B,EAAE,iBAAuB;QAC1E,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,EAAE,CAAC;QACd,CAAC;QACD,IAAI,OAAO,IAAI,iBAAiB,EAAE,CAAC;YAC/B,OAAO,WAAW,CAAC,cAAc,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,YAAY,IAAY,EAAE,MAAc,EAAE,OAAgB,EAAE,iBAAuB;QAC/E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,SAAS;QACb,CAAC;QACD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACJ"}
+{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../src/ApiError.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC;AAExB;;;;GAIG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAMxB,kBAAkB,CAAC,OAA2B,EAAE,iBAAuB;QAC1E,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,EAAE,CAAC;QACd,CAAC;QACD,IAAI,OAAO,IAAI,iBAAiB,EAAE,CAAC;YAC/B,OAAO,WAAW,CAAC,cAAc,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,YAAY,IAAY,EAAE,MAAc,EAAE,OAAgB,EAAE,iBAAuB;QAC/E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,iGAAiG;YACjG,oGAAoG;YACpG,oGAAoG;YACpG,6BAA6B;YAC7B,MAAM,CAAC,IAAI,CAAC,2DAA2D,IAAI,EAAE,CAAC,CAAC;YAC/E,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;QACD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACJ"}

package/dist/lib/CacheUtils.js

@@ -0,0 +1,23 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Utility functions for working with bounded in-memory caches.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class CacheUtils {
+    /**
+     * Evicts the oldest inserted entry from `map`, if any. A `Map` preserves insertion order, so this removes
+     * whatever entry was `set()` least recently among those still present.
+     *
+     * @param map The map to evict the oldest entry from.
+     */
+    static evictOldest(map) {
+        const oldestKey = map.keys().next().value;
+        if (oldestKey !== undefined) {
+            map.delete(oldestKey);
+        }
+    }
+}
+//# sourceMappingURL=CacheUtils.js.map

package/dist/lib/CacheUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheUtils.js","sourceRoot":"","sources":["../../src/CacheUtils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,+EAA+E;AAE/E;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACnB;;;;;OAKG;IACI,MAAM,CAAC,WAAW,CAAO,GAAc;QAC1C,MAAM,SAAS,GAAkB,GAAG,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QACzD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;IACL,CAAC;CACJ"}

package/dist/lib/ClassLoader.js

@@ -41,6 +41,10 @@ const sepRegex = new RegExp("\\" + path.sep, "g");
  * an ESM-only project you must use the `ts-node/esm` module loader. This can be specified by passing the `--loader` to
  * node at runtime.
  *
+ * Also, this code intentionally does not perform path-containment and symlink checks during it's load process as the
+ * purpose of this utility is never to be exposed to a client-facing API or process. Doing so would never make sense
+ * anyway. The lack of containment checks here is to eliminate real performance costs that such containment introduces.
+ *
  * ```
  * node --loader ts-node/esm <module>
  * ```
@@ -95,6 +99,34 @@ export class ClassLoader {
     hasClass(fqn) {
         return this.classes.get(fqn) ? true : false;
     }
+    /**
+     * Imports the module at `fullpath` and registers each of its exports as a class under its fully qualified
+     * name, shared by both the JavaScript and TypeScript loading branches of `load()` so a future change to
+     * how exports are turned into registered classes only needs to be made in one place.
+     */
+    async registerModule(fullpath, pkg, fileName) {
+        const mod = await import(pathToFileURL(fullpath).href);
+        /* v8 ignore else -- unreachable: dynamic `import()` either resolves to a truthy namespace object or rejects, it never resolves to a falsy value. */
+        if (mod) {
+            for (let name in mod) {
+                let clazz = mod[name];
+                // Skip primitive-valued exports (string/number/boolean/etc.) rather than registering them: ES
+                // modules run in strict mode, so `clazz.fqn = fqn` below would throw `TypeError: Cannot create
+                // property 'fqn' on <primitive>` for a module that exports e.g. `export const VERSION = "1.0.0"`
+                // alongside its classes, aborting the load of the entire directory. Enums compile to plain
+                // objects (typeof "object"), so they're still registered as before.
+                if (clazz === null || (typeof clazz !== "function" && typeof clazz !== "object")) {
+                    continue;
+                }
+                let fqn = `${pkg.length > 0 ? pkg + "." : ""}${name === "default" ? path.basename(fileName, path.extname(fileName)) : name}`;
+                clazz.fqn = fqn;
+                this.classes.set(fqn, clazz);
+            }
+        }
+        else {
+            throw new Error("Failed to load module file: " + fullpath);
+        }
+    }
     /**
      * Loads all modules exports contained in the directory specified. The folder must be a child
      * directory to the `rootDir` parameter passed in to the constructor.
@@ -103,79 +135,40 @@ export class ClassLoader {
      */
     async load(dir = "") {
         let fqp = path.resolve(path.join(this.rootDir, dir));
-        // Ensure the resolved directory is still contained within rootDir. Prevents a caller-supplied `dir`
-        // (e.g. containing "../") from escaping rootDir and dynamically importing/executing arbitrary modules
-        // found elsewhere on disk.
-        const rel = path.relative(this.rootDir, fqp);
-        if (rel !== "" && (rel.startsWith("..") || path.isAbsolute(rel))) {
-            throw new Error(`Directory "${dir}" escapes the allowed root directory "${this.rootDir}".`);
-        }
         let files = await fs.promises.readdir(fqp, { withFileTypes: true });
-        for (let file of files) {
+        // Processed concurrently via `Promise.all` since sibling entries in a directory are independent of one
+        // another; `Promise.all` still `await`s every entry (and propagates the first rejection) before `load()`
+        // itself resolves, so parallelizing here only shortens cold-start time rather than changing behavior.
+        await Promise.all(files.map(async (file) => {
             // Is the file in the ignore list?
-            let skipFile = false;
             for (const iPath of this.ignore) {
                 if (file.name.match(iPath)) {
-                    skipFile = true;
-                    break;
+                    return;
                 }
             }
-            if (skipFile) {
-                continue;
-            }
+            let relpath = path.relative(this.rootDir, fqp);
+            let pkg = relpath.replace(sepRegex, ".");
+            let fullpath = path.join(fqp, file.name);
             let extension = path.extname(file.name);
             if (!extension) {
                 extension = file.name;
             }
-            let relpath = path.relative(this.rootDir, fqp);
-            let fullpath = path.resolve(path.join(this.rootDir, relpath, file.name));
-            let pkg = relpath.replace(sepRegex, ".");
-            // `fs.Dirent.isDirectory()`/extension matching below reflect the directory entry itself, not
-            // what it points to. Without resolving symlinks here, a symlink placed inside the scanned tree
-            // could point at an arbitrary file or directory outside rootDir and still be recursed into or
-            // dynamically imported below, defeating the containment check performed on `dir` above.
-            if (file.isSymbolicLink()) {
-                const realpath = await fs.promises.realpath(fullpath);
-                const relReal = path.relative(this.rootDir, realpath);
-                if (relReal !== "" && (relReal.startsWith("..") || path.isAbsolute(relReal))) {
-                    throw new Error(`Symlink "${fullpath}" escapes the allowed root directory "${this.rootDir}".`);
-                }
-            }
+            // `Dirent.isDirectory()` reflects the directory entry itself, not what it points to, so a
+            // symlinked directory falls through to the extension-matching branches below rather than being
+            // recursed into - deliberate: following it here (e.g. via `fs.statSync().isDirectory()`) would
+            // let a symlink that points back at one of its own ancestors send `load()` into unbounded
+            // recursion.
             if (file.isDirectory()) {
                 let subdir = path.join(dir, file.name);
                 await this.load(subdir);
             }
             else if (this.includeJavaScript && extension.match(/^\.(js|cjs|mjs)$/)) {
-                const mod = await import(pathToFileURL(fullpath).href);
-                /* v8 ignore else -- unreachable: dynamic `import()` either resolves to a truthy namespace object or rejects, it never resolves to a falsy value. */
-                if (mod) {
-                    for (let name in mod) {
-                        let clazz = mod[name];
-                        let fqn = `${pkg.length > 0 ? pkg + "." : ""}${name === "default" ? file.name.split(".")[0] : name}`;
-                        clazz.fqn = fqn;
-                        this.classes.set(fqn, clazz);
-                    }
-                }
-                else {
-                    throw new Error("Failed to load module file: " + fullpath);
-                }
+                await this.registerModule(fullpath, pkg, file.name);
             }
             else if (this.includeTypeScript && extension.match(/^\.(ts|cts|mts|tsx)$/)) {
-                const mod = await import(pathToFileURL(fullpath).href);
-                /* v8 ignore else -- unreachable: dynamic `import()` either resolves to a truthy namespace object or rejects, it never resolves to a falsy value. */
-                if (mod) {
-                    for (let name in mod) {
-                        let clazz = mod[name];
-                        let fqn = `${pkg.length > 0 ? pkg + "." : ""}${name === "default" ? file.name.split(".")[0] : name}`;
-                        clazz.fqn = fqn;
-                        this.classes.set(fqn, clazz);
-                    }
-                }
-                else {
-                    throw new Error("Failed to load module file: " + fullpath);
-                }
+                await this.registerModule(fullpath, pkg, file.name);
             }
-        }
+        }));
     }
 }
 //# sourceMappingURL=ClassLoader.js.map

package/dist/lib/ClassLoader.js.map

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