@rapidrest/core 1.0.1

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (C) 2020-2026 Jean-Philippe Steinmetz <caskater47@gmail.com>
+Copyright (C) 2020-2026 Arthur Thompson
+Copyright (C) 2024 Thomas Buscaglia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.rst

@@ -0,0 +1,37 @@
+=======================
+RapidREST: Core Library
+=======================
+
+A set of common utilities shared amongst all RapidREST based applications and servers.
+
+Features
+========
+
+* Alert & Notification System
+* Class Loader
+* File management utilities
+* JSON Web Token utilities
+* Object Factory
+* OpenAPI utilities
+* String utilities
+* Telemetry utilities
+* Thread-pool Manager
+* User authentication utilities
+* Validation utilities
+
+Getting Started
+===============
+
+Yarn
+~~~~
+
+```
+yarn add @rapidrest/core
+```
+
+NPM
+~~~
+
+```
+npm i @rapidrest/core
+```

package/dist/lib/AlertUtils.js

@@ -0,0 +1,239 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2020-2026 Jean-Philippe Steinmetz
+///////////////////////////////////////////////////////////////////////////////
+import axios from "axios";
+import FormData from "form-data";
+import handlebars from "handlebars";
+import JSZip from "jszip";
+import { sleep } from "./sleep.js";
+const MAX_ATTEMPTS = 60;
+const MAX_CHARS_ALIAS = 512;
+const MAX_CHARS_DESCRIPTION = 15000;
+const MAX_CHARS_ENTITY = 512;
+const MAX_CHARS_MESSAGE = 130;
+const MAX_CHARS_NOTE = 25000;
+const MAX_CHARS_SOURCE = 100;
+const MAX_CHARS_TAGS = 50;
+const MAX_TAGS = 20;
+/**
+ * Describes the level of priority for a given alert and an importance for triaging the problem.
+ */
+export var AlertPriority;
+(function (AlertPriority) {
+    /** Describes an alert that affects critical operating functionality or infrastructure. */
+    AlertPriority["Critical"] = "P1";
+    /** Describes an alert that affects key systems that have great impact on end-user experiences. */
+    AlertPriority["Severe"] = "P2";
+    /** Describes an alert that affects basic systems that may create a poor end-user experience. */
+    AlertPriority["Important"] = "P3";
+    /** Describes an alert that has no material affect on the end-user experience but with potential to escalate. */
+    AlertPriority["Warning"] = "P4";
+    /** Describes an alert that has no material affect on end-user experience and no potential for escalation. */
+    AlertPriority["Notice"] = "P5";
+})(AlertPriority || (AlertPriority = {}));
+/**
+ * The `AlertUtils` class is used to send alerts about important system events that have occurred
+ * and require further monitoring or intervention.
+ */
+export class AlertUtils {
+    /** The logging utility to use. */
+    logger;
+    /** The value of the Authorization header to apply to all outgoing HTTP requests. */
+    auth;
+    /** The full url of the REST API service that alerts will be sent to. */
+    serviceUrl;
+    /**
+     * Creates a new instance of `AuthUtils` with the provided defaults.
+     * @param options The configuration options to use.
+     */
+    constructor(options) {
+        this.auth = options.auth;
+        this.logger = options.logger;
+        this.serviceUrl = options.serviceUrl;
+    }
+    /**
+     * Attempts to close the existing alert with the given identifier.
+     * @param id The unique identifier of the alert to close.
+     * @returns True if the operation was successful, otherwise false.
+     */
+    async close(id, data = {}) {
+        try {
+            if (data.note) {
+                data.note = data.note.substring(0, MAX_CHARS_NOTE);
+            }
+            if (data.source) {
+                data.source = data.source.substring(0, MAX_CHARS_SOURCE);
+            }
+            const url = `${this.serviceUrl}/${id}/close`;
+            const response = await axios.post(url, data, {
+                headers: {
+                    Authorization: this.auth,
+                }
+            });
+            return response.status >= 200 && response.status < 300;
+        }
+        catch (err) {
+            this.logger.error("Failed to close alert with id " + id);
+            this.logger.error(err.message);
+            return false;
+        }
+    }
+    /**
+     * Attempts to retrieve the existing alert with the given identifier.
+     * @param id The unique identifier of the alert to retrieve.
+     * @returns The retrieved alert if successful, otherwise `null`.
+     */
+    async get(id) {
+        try {
+            const url = `${this.serviceUrl}/${id}`;
+            const response = await axios.get(url, {
+                headers: {
+                    Authorization: this.auth,
+                }
+            });
+            return response.status >= 200 && response.status < 300 ? response.data : null;
+        }
+        catch (err) {
+            this.logger.error("Failed to retrieve alert with id " + id);
+            this.logger.error(err.message);
+            return null;
+        }
+    }
+    /**
+     * Sends the provided alert to the configured monitoring service.
+     *
+     * @param alert The alert to send.
+     * @param vars A map of vars to perform replacement on for the alert's various properties.
+     * @param attachments The attachments to upload along with the alert.
+     * @returns The unique identifier of the created alert if the operation was successful, otherwise `null`.
+     */
+    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);
+            }
+            alert.message = alert.message.substring(0, MAX_CHARS_MESSAGE);
+            if (alert.note) {
+                alert.note = alert.note.substring(0, MAX_CHARS_NOTE);
+            }
+            alert.source = alert.source.substring(0, MAX_CHARS_SOURCE);
+            if (alert.tags) {
+                let tags = [];
+                for (let i = 0; i < MAX_TAGS; i++) {
+                    const tag = alert.tags[i];
+                    tags.push(tag.substring(0, MAX_CHARS_TAGS));
+                }
+                alert.tags = tags;
+            }
+            // Process properties as templates
+            let template = handlebars.compile(alert.description);
+            alert.description = template(vars);
+            template = handlebars.compile(alert.message);
+            alert.message = template(vars);
+            if (alert.note) {
+                template = handlebars.compile(alert.note);
+                alert.note = template(vars);
+            }
+            let response = await axios.post(this.serviceUrl, alert, {
+                headers: {
+                    Authorization: this.auth,
+                }
+            });
+            const requestId = response.status >= 200 && response.status < 300 ? response.data.requestId : null;
+            if (!requestId) {
+                return null;
+            }
+            // Query the API for the final alert id
+            let id = null;
+            let count = 0;
+            while (!id && count < MAX_ATTEMPTS) {
+                try {
+                    const url = `${this.serviceUrl}/requests/${requestId}}`;
+                    const response = await axios.get(url, {
+                        headers: {
+                            Authorization: this.auth,
+                        }
+                    });
+                    if (response.status >= 200 && response.status < 300) {
+                        if (response.data.success && response.data.alertId) {
+                            id = response.data.alertId;
+                        }
+                    }
+                }
+                catch (err) {
+                    // We get here when the request isn't finished processing yet. OpsGenie's API is... meh.
+                    // Wait a second before retrying
+                    await sleep(1000);
+                }
+                count++;
+            }
+            // Now upload any attachments if they were provided
+            if (id && attachments) {
+                if (attachments.zip) {
+                    // Package all attachments into a single zip file for upload
+                    const zip = new JSZip();
+                    for (const file of attachments.files) {
+                        zip.file(file.filename, file.data);
+                    }
+                    const data = await zip.generateAsync({ type: "nodebuffer" });
+                    await this.addAttachment(id, {
+                        contentType: "application/zip",
+                        data,
+                        filename: `${id}.zip`,
+                        size: data.length
+                    }, attachments.indexFile);
+                }
+                else {
+                    // Upload each attachment individually
+                    for (const file of attachments.files) {
+                        await this.addAttachment(id, file, attachments.indexFile);
+                    }
+                }
+            }
+            return id;
+        }
+        catch (err) {
+            this.logger?.error("Failed to send alert.");
+            this.logger?.error(err.response?.data?.message || err.message);
+            return null;
+        }
+    }
+    /**
+     * Uploads a single attachment to the alert with the given unique identifier.
+     * @param id The unique identifier of the alert to add an attachment for.
+     * @param attachment The file to upload as an attachment.
+     * @param indexFile Sets the indexFile parameter of the request.
+     * @returns True if the operation was successful, otherwise false.
+     */
+    async addAttachment(id, attachment, indexFile) {
+        try {
+            const form = new FormData();
+            form.append("file", attachment.data, {
+                contentType: attachment.contentType,
+                filename: attachment.filename,
+                knownLength: attachment.size
+            });
+            let url = `${this.serviceUrl}/${id}/attachments`;
+            if (indexFile) {
+                url += "&indexFile=" + indexFile;
+            }
+            const response = await axios.post(url, form, {
+                headers: {
+                    Authorization: this.auth,
+                    "Content-Type": "multipart/form-data"
+                }
+            });
+            return response.status >= 200 && response.status < 300;
+        }
+        catch (err) {
+            // Don't fail the rest of the request if attachments fail
+            this.logger?.error(`Failed to upload attachment ${attachment.filename} to alert ${id}.`);
+            this.logger?.error(err.response?.data?.message || err.message);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=AlertUtils.js.map

package/dist/lib/AlertUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertUtils.js","sourceRoot":"","sources":["../../src/AlertUtils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kDAAkD;AAClD,+EAA+E;AAC/E,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,QAAQ,MAAM,WAAW,CAAC;AAEjC,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,YAAY,GAAW,EAAE,CAAC;AAChC,MAAM,eAAe,GAAW,GAAG,CAAC;AACpC,MAAM,qBAAqB,GAAW,KAAK,CAAC;AAC5C,MAAM,gBAAgB,GAAW,GAAG,CAAC;AACrC,MAAM,iBAAiB,GAAW,GAAG,CAAC;AACtC,MAAM,cAAc,GAAW,KAAK,CAAC;AACrC,MAAM,gBAAgB,GAAW,GAAG,CAAC;AACrC,MAAM,cAAc,GAAW,EAAE,CAAC;AAClC,MAAM,QAAQ,GAAW,EAAE,CAAC;AAE5B;;GAEG;AACH,MAAM,CAAN,IAAY,aAWX;AAXD,WAAY,aAAa;IACrB,0FAA0F;IAC1F,gCAAe,CAAA;IACf,kGAAkG;IAClG,8BAAa,CAAA;IACb,gGAAgG;IAChG,iCAAgB,CAAA;IAChB,gHAAgH;IAChH,+BAAc,CAAA;IACd,6GAA6G;IAC7G,8BAAa,CAAA;AACjB,CAAC,EAXW,aAAa,KAAb,aAAa,QAWxB;AA6ED;;;GAGG;AACH,MAAM,OAAO,UAAU;IACnB,kCAAkC;IAC1B,MAAM,CAAM;IACpB,oFAAoF;IAC5E,IAAI,CAAS;IACrB,wEAAwE;IAChE,UAAU,CAAS;IAE3B;;;OAGG;IACH,YAAY,OAA0B;QAClC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,KAAK,CAAC,EAAU,EAAE,OAAmB,EAAE;QAChD,IAAI,CAAC;YACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACZ,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;YACvD,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;YAC7D,CAAC;YAED,MAAM,GAAG,GAAW,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,QAAQ,CAAC;YACrD,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE;gBACxD,OAAO,EAAE;oBACL,aAAa,EAAE,IAAI,CAAC,IAAI;iBAC3B;aACJ,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;YACzD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC/B,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,GAAG,CAAC,EAAU;QACvB,IAAI,CAAC;YACD,MAAM,GAAG,GAAW,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YAC/C,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;gBACjD,OAAO,EAAE;oBACL,aAAa,EAAE,IAAI,CAAC,IAAI;iBAC3B;aACJ,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,GAAG,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,IAAI,CAAC,KAAY,EAAE,OAAY,EAAE,EAAE,WAAyC;QACrF,IAAI,CAAC;YACD,6GAA6G;YAC7G,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;YACxD,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;YAC1E,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACf,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;YAC/D,CAAC;YACD,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;YAC9D,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACb,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;YACzD,CAAC;YACD,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;YAC3D,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACb,IAAI,IAAI,GAAa,EAAE,CAAC;gBACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;oBAChC,MAAM,GAAG,GAAW,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;oBAClC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;gBAChD,CAAC;gBACD,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;YACtB,CAAC;YAED,kCAAkC;YAClC,IAAI,QAAQ,GAAgC,UAAU,CAAC,OAAO,CAC1D,KAAK,CAAC,WAAW,CACpB,CAAC;YACF,KAAK,CAAC,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YACnC,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7C,KAAK,CAAC,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACb,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;YAED,IAAI,QAAQ,GAAkB,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE;gBACnE,OAAO,EAAE;oBACL,aAAa,EAAE,IAAI,CAAC,IAAI;iBAC3B;aACJ,CAAC,CAAC;YACH,MAAM,SAAS,GAAkB,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;YAClH,IAAI,CAAC,SAAS,EAAE,CAAC;gBACb,OAAO,IAAI,CAAC;YAChB,CAAC;YAED,uCAAuC;YACvC,IAAI,EAAE,GAAkB,IAAI,CAAC;YAC7B,IAAI,KAAK,GAAW,CAAC,CAAC;YACtB,OAAO,CAAC,EAAE,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;gBACjC,IAAI,CAAC;oBACD,MAAM,GAAG,GAAW,GAAG,IAAI,CAAC,UAAU,aAAa,SAAS,GAAG,CAAC;oBAChE,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;wBACjD,OAAO,EAAE;4BACL,aAAa,EAAE,IAAI,CAAC,IAAI;yBAC3B;qBACJ,CAAC,CAAC;oBACH,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAK,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;wBACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;4BACjD,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;wBAC/B,CAAC;oBACL,CAAC;gBACL,CAAC;gBAAC,OAAO,GAAQ,EAAE,CAAC;oBAChB,wFAAwF;oBACxF,gCAAgC;oBAChC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;gBACtB,CAAC;gBAED,KAAK,EAAE,CAAC;YACZ,CAAC;YAED,mDAAmD;YACnD,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;gBACpB,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC;oBAClB,4DAA4D;oBAC5D,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;oBACxB,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;wBACnC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;oBACvC,CAAC;oBACD,MAAM,IAAI,GAAW,MAAM,GAAG,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;oBACrE,MAAM,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE;wBACzB,WAAW,EAAE,iBAAiB;wBAC9B,IAAI;wBACJ,QAAQ,EAAE,GAAG,EAAE,MAAM;wBACrB,IAAI,EAAE,IAAI,CAAC,MAAM;qBACpB,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;gBAC9B,CAAC;qBAAM,CAAC;oBACJ,sCAAsC;oBACtC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;wBACnC,MAAM,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;oBAC9D,CAAC;gBACL,CAAC;YACL,CAAC;YAED,OAAO,EAAE,CAAC;QACd,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,uBAAuB,CAAC,CAAC;YAC5C,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;YAC/D,OAAO,IAAI,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,aAAa,CAAC,EAAU,EAAE,UAA2B,EAAE,SAAkB;QAClF,IAAI,CAAC;YACD,MAAM,IAAI,GAAa,IAAI,QAAQ,EAAE,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI,EAAE;gBACjC,WAAW,EAAE,UAAU,CAAC,WAAW;gBACnC,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,WAAW,EAAE,UAAU,CAAC,IAAI;aAC/B,CAAC,CAAC;YAEH,IAAI,GAAG,GAAW,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,cAAc,CAAC;YACzD,IAAI,SAAS,EAAE,CAAC;gBACZ,GAAG,IAAI,aAAa,GAAG,SAAS,CAAC;YACrC,CAAC;YACD,MAAM,QAAQ,GAAkB,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE;gBACxD,OAAO,EAAE;oBACL,aAAa,EAAE,IAAI,CAAC,IAAI;oBACxB,cAAc,EAAE,qBAAqB;iBACxC;aACJ,CAAC,CAAC;YAEH,OAAO,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,yDAAyD;YACzD,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,+BAA+B,UAAU,CAAC,QAAQ,aAAa,EAAE,GAAG,CAAC,CAAC;YACzF,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;YAC/D,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;CACJ"}

package/dist/lib/ApiError.js

@@ -0,0 +1,34 @@
+import { StringUtils } from "./StringUtils.js";
+/**
+ * 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
+ * the error.
+ */
+export class ApiError extends Error {
+    /** The unique code of the error. */
+    code;
+    /** The HTTP status associated with the error. */
+    status;
+    ApiMessageTemplate(message, templateVariables) {
+        if (!message) {
+            return "";
+        }
+        if (message && templateVariables) {
+            return StringUtils.findAndReplace(message, templateVariables);
+        }
+        return message;
+    }
+    constructor(code, status, message, templateVariables) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        try {
+            this.message = this.ApiMessageTemplate(message, templateVariables);
+        }
+        catch (error) {
+            // NO-OP 
+        }
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+}
+//# sourceMappingURL=ApiError.js.map

package/dist/lib/ApiError.js.map

@@ -0,0 +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;IAC/B,oCAAoC;IAC7B,IAAI,CAAS;IACpB,iDAAiD;IAC1C,MAAM,CAAS;IAEf,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"}

package/dist/lib/ClassLoader.js

@@ -0,0 +1,159 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2020-2026 Jean-Philippe Steinmetz
+///////////////////////////////////////////////////////////////////////////////
+import fs from "fs";
+import path from "path";
+/**
+ * The *ClassLoader* provides a container for dynamically loading classes at runtime using C#/Java style namespaces.
+ * Namespaces are determined from the folder structure relative to the root.
+ *
+ * Class names are derived either directly from the modules export name or inferred from the module's file path when
+ * the `default` export is used.
+ *
+ * For example, given the following example TypeScript module at relative path `com/company/MyClass.ts` would register
+ * a class with fully qualified name `com.company.MyClass`.
+ *
+ * ```javascript
+ * export default class MyClass {
+ *     // ...
+ * }
+ * ```
+ *
+ * In the event that multiple exports are defined, the fully qualified name will take on the export name instead of the
+ * module name. Thus, the following example module at relative path `com/company/MyClasses.ts` would register the following
+ * classes.
+ * - `com.company.MyClass`
+ * - `com.company.MyEnum`
+ *
+ * ```javascript
+ * export class MyClass {
+ *     // ...
+ * }
+ *
+ * export enum MyEnum {
+ *     // ...
+ * }
+ * ```
+ *
+ * **IMPORTANT**: If you use *ClassLoader* to dynamically load TypeScript files (.ts, .cts, .mts, etc.) at runtime using
+ * 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.
+ *
+ * ```
+ * node --loader ts-node/esm <module>
+ * ```
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export class ClassLoader {
+    /** The map containnig all loaded classes. */
+    classes = new Map();
+    ignore = [];
+    /** Indicates if TypeScript classes should be loaded. */
+    includeTypeScript = true;
+    /** Indicates if JavaScript classes should be loaded. */
+    includeJavaScript = true;
+    /** The path to the root directory containing all classes on disk. */
+    rootDir = ".";
+    /**
+     * Creates a new instance of `ClassLoader` with the specified defaults.
+     *
+     * @param rootDir The root directory to load all classes from.
+     * @param includeJavaScript Set to `true` to load all TypeScript classes from the given `rootDir`, otherwise set to `false.
+     * @param includeTypeScript Set to `true` to load all JavaScript classes from the given `rootDir`, otherwise set to `false.
+     * @param ignore A list of regex pattern of file paths to ignore.
+     */
+    constructor(rootDir, includeJavaScript = true, includeTypeScript = true, ignore = []) {
+        this.rootDir = path.resolve(rootDir);
+        this.includeJavaScript = includeJavaScript;
+        this.includeTypeScript = includeTypeScript;
+        this.ignore = ignore;
+    }
+    /**
+     * Returns the class with the specified fully qualified name.
+     *
+     * @param fqn The fully qualified name of the class to return.
+     * @returns The class definition for the given fully qualified name if found, otherwise `undefined`.
+     */
+    getClass(fqn) {
+        return this.classes.get(fqn);
+    }
+    /**
+     * Returns the map containing all classes that have been loaded.
+     */
+    getClasses() {
+        return this.classes;
+    }
+    /**
+     * Returns `true` if a class exists with the specified fully qualified name.
+     *
+     * @param fqn The fully qualified name of the class to search.
+     * @returns `true` if a class definition exists for the given fully qualified name, otherwise `false`.
+     */
+    hasClass(fqn) {
+        return this.classes.get(fqn) ? true : false;
+    }
+    /**
+     * 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.
+     *
+     * @param dir The directory, relative to `rootDir`, containing modules to load.
+     */
+    async load(dir = "") {
+        let fqp = path.resolve(path.join(this.rootDir, dir));
+        let files = fs.readdirSync(fqp, { withFileTypes: true });
+        for (let file of files) {
+            // Is the file in the ignore list?
+            let skipFile = false;
+            for (const iPath of this.ignore) {
+                if (file.name.match(iPath)) {
+                    skipFile = true;
+                    break;
+                }
+            }
+            if (skipFile) {
+                continue;
+            }
+            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(new RegExp("\\" + path.sep, "g"), ".");
+            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(fullpath);
+                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);
+                }
+            }
+            else if (this.includeTypeScript && extension.match(/^\.(ts|cts|mts|tsx)$/)) {
+                const mod = await import(fullpath);
+                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);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=ClassLoader.js.map

package/dist/lib/ClassLoader.js.map

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