@aglyn/shared-util-errors 1.0.0-beta.143

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,7 @@
+# @aglyn/shared-util-errors
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test shared-util-errors` to execute the unit tests via [Jest](https://jestjs.io).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aglyn/shared-util-errors",
+  "version": "1.0.0-beta.143",
+  "license": "Apache-2.0",
+  "homepage": "https://aglyn.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aglyn/aglyn.git",
+    "directory": "libs/shared/util/errors"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/lib/*.d.ts",
+      "default": "./src/lib/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@aglyn/shared-data-enums": "1.0.0-beta.143",
+    "@aglyn/shared-util-tools": "1.0.0-beta.143",
+    "@swc/helpers": "0.5.23"
+  },
+  "sideEffects": false,
+  "types": "./src/index.d.ts",
+  "module": "./src/index.js",
+  "main": "./src/index.js"
+}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './lib/errors';

package/src/index.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export * from "./lib/errors.js";
+
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/shared/util/errors/src/index.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport * from './lib/errors'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,cAAc,kBAAc"}

package/src/lib/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './http-response-error';
+export * from './upstream-service-error';
+export * from './ns-error';
+export * from './ns-error-factory';
+export * from './tools';
+export * from './types';

package/src/lib/errors.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export * from "./http-response-error.js";
+export * from "./upstream-service-error.js";
+export * from "./ns-error.js";
+export * from "./ns-error-factory.js";
+export * from "./tools.js";
+export * from "./types.js";
+
+//# sourceMappingURL=errors.js.map

package/src/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/errors.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n\nexport * from './http-response-error'\nexport * from './upstream-service-error'\nexport * from './ns-error'\nexport * from './ns-error-factory'\nexport * from './tools'\nexport * from './types'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,cAAc,2BAAuB;AACrC,cAAc,8BAA0B;AACxC,cAAc,gBAAY;AAC1B,cAAc,wBAAoB;AAClC,cAAc,aAAS;AACvB,cAAc,aAAS"}

package/src/lib/http-response-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { HttpStatusCode } from '@aglyn/shared-data-enums/http';
+export declare class HttpResponseError extends Error {
+    readonly code: HttpStatusCode;
+    readonly name = "HttpResponseError";
+    message: string;
+    constructor(code: HttpStatusCode, message: string);
+}
+export default HttpResponseError;

package/src/lib/http-response-error.js

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { HttpStatusCode } from "@aglyn/shared-data-enums/http";
+export class HttpResponseError extends Error {
+    constructor(code = HttpStatusCode.OK, message){
+        super(message), this.code = code, this.name = 'HttpResponseError';
+        this.message = message;
+        // Fix For ES5
+        // https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
+        Object.setPrototypeOf(this, HttpResponseError.prototype);
+        // Maintains proper stack trace for where our error was thrown.
+        // Only available on V8.
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, HttpResponseError);
+        }
+    }
+}
+export default HttpResponseError;
+
+//# sourceMappingURL=http-response-error.js.map

package/src/lib/http-response-error.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/http-response-error.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {HttpStatusCode} from '@aglyn/shared-data-enums/http'\n\n\nexport class HttpResponseError extends Error {\n  override readonly name = 'HttpResponseError'\n\n  override message: string\n\n  constructor(\n    public readonly code: HttpStatusCode = HttpStatusCode.OK,\n    message: string,\n  ) {\n    super(message)\n    this.message = message\n\n    // Fix For ES5\n    // https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work\n    Object.setPrototypeOf(this, HttpResponseError.prototype)\n\n    // Maintains proper stack trace for where our error was thrown.\n    // Only available on V8.\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, HttpResponseError)\n    }\n  }\n}\n\nexport default HttpResponseError\n"],"names":["HttpStatusCode","HttpResponseError","Error","code","OK","message","name","Object","setPrototypeOf","prototype","captureStackTrace"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAAQA,cAAc,QAAO,gCAA+B;AAG5D,OAAO,MAAMC,0BAA0BC;IAKrC,YACE,AAAgBC,OAAuBH,eAAeI,EAAE,EACxDC,OAAe,CACf;QACA,KAAK,CAACA,eAHUF,OAAAA,WALAG,OAAO;QASvB,IAAI,CAACD,OAAO,GAAGA;QAEf,cAAc;QACd,+IAA+I;QAC/IE,OAAOC,cAAc,CAAC,IAAI,EAAEP,kBAAkBQ,SAAS;QAEvD,+DAA+D;QAC/D,wBAAwB;QACxB,IAAIP,MAAMQ,iBAAiB,EAAE;YAC3BR,MAAMQ,iBAAiB,CAAC,IAAI,EAAET;QAChC;IACF;AACF;AAEA,eAAeA,kBAAiB"}

package/src/lib/ns-error-factory.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { NsError } from './ns-error';
+import type { ErrorPayload, ErrorTagMessages, ErrorTagPayloads, EventFlag } from './types';
+/**
+ * Standardized App Errors
+ *
+ * Usage:
+ * ```typescript
+ *   // Typescript string literals for type-safe codes
+ *   type Err =
+ *     'unknown' |
+ *     'object-not-found'
+ *     ;
+ *
+ *   // Closure enum for type-safe error codes
+ *   // at-enum {string}
+ *   var Err = {
+ *     UNKNOWN: 'unknown',
+ *     OBJECT_NOT_FOUND: 'object-not-found',
+ *   }
+ *
+ *   let : Map<Err, string> = {
+ *     'generic-error': "Unknown error",
+ *     'file-not-found': "Could not find file: {$file}",
+ *   };
+ *
+ *   // Type-safe function - must pass a valid error code as param.
+ *   let error = new ErrorFactory<Err>('scope', 'Service', presets);
+ *
+ *   ...
+ *   throw error.create(Err.GENERIC);
+ *   ...
+ *   throw error.create(Err.FILE_NOT_FOUND, {'file': fileName});
+ *   ...
+ *   // Service: Could not file file: foo.txt (scope/file-not-found).
+ *
+ *   catch (e) {
+ *     assert(e.message === "Could not find file: foo.txt.");
+ *     if (e.code === 'scope/file-not-found') {
+ *       console.log("Could not read file: " + e['file']);
+ *     }
+ *   }
+ * ```
+ * @see inspired by:
+ *   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Custom_Error_Types
+ */
+export declare class NsErrorFactory<T extends string = EventFlag, U extends ErrorTagPayloads = ErrorTagPayloads> {
+    private readonly scope;
+    private readonly namespace;
+    private readonly templates;
+    private readonly nsDelimiter;
+    private readonly scopeDelimiter;
+    private readonly defaultMessage;
+    private buildNamespace;
+    constructor(scope: string, namespace: string, templates: ErrorTagMessages<T>, nsDelimiter?: string, scopeDelimiter?: string, defaultMessage?: string);
+    protected makeShortCode<K extends T>(flag: K): string;
+    protected makeFullCode(shortCode: string): string;
+    protected makeShortMessage<K extends T>(flag: K, payload?: ErrorPayload): string;
+    protected makeFullMessage(shortCode: string, shortMessage: string): string;
+    /**
+     * Build a new throwable
+     * @example
+     * ```
+     * let age: string | number = 101
+     * const errorFactory = new NsErrorFactory('domain', 'my-lib', {
+     *   ['bad-string']: "Provided an invalid string '{$str}'"
+     * })
+     * if (typeof age !== 'string') {
+     *   throw errorFactory.create('bad-string', {str: age})
+     *   // Out = domain - Provided an invalid string '101' (my-lib/bad-string)
+     *   // Full Code = domain::my-lib/bad-string
+     * }
+     * ```
+     *
+     * @param flag - error event identifier
+     * @param payload - payload data to set template variable values
+     * @returns NsError
+     */
+    create<K extends T>(flag: K, ...payload: K extends keyof U ? [U[K]] : []): NsError;
+    childFactory<T extends string, U extends ErrorTagPayloads<T>>(childNamespace: string, templates?: ErrorTagMessages<T>): NsErrorFactory<T, U>;
+}

package/src/lib/ns-error-factory.js

@@ -0,0 +1,160 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _isArr } from "@aglyn/shared-util-tools";
+import { NsError } from "./ns-error.js";
+import { replaceTemplate } from "./tools.js";
+const DEFAULT_TEMPLATE = `{$scope} {$code} {$message}`;
+function namespaceFactory(options) {
+    const { scope, namespace, nsDelimiter, scopeDelimiter, template, defaultMessage } = options;
+    function makeShortCode(flag) {
+        return [
+            namespace,
+            flag
+        ].join(nsDelimiter);
+    }
+    function makeFullCode(flag) {
+        return [
+            scope,
+            makeShortCode(flag)
+        ].join(scopeDelimiter);
+    }
+    function buildNamespace(message, code) {
+        const tmp = template || DEFAULT_TEMPLATE;
+        return replaceTemplate(tmp, {
+            scope,
+            code
+        });
+    }
+    const builders = new Map();
+    return (flag, msg = defaultMessage)=>{
+        if (!builders.has(flag)) {
+            const code = makeFullCode(flag);
+            builders.set(flag, code);
+        }
+        return buildNamespace(msg, builders.get(flag));
+    };
+}
+/**
+ * Standardized App Errors
+ *
+ * Usage:
+ * ```typescript
+ *   // Typescript string literals for type-safe codes
+ *   type Err =
+ *     'unknown' |
+ *     'object-not-found'
+ *     ;
+ *
+ *   // Closure enum for type-safe error codes
+ *   // at-enum {string}
+ *   var Err = {
+ *     UNKNOWN: 'unknown',
+ *     OBJECT_NOT_FOUND: 'object-not-found',
+ *   }
+ *
+ *   let : Map<Err, string> = {
+ *     'generic-error': "Unknown error",
+ *     'file-not-found': "Could not find file: {$file}",
+ *   };
+ *
+ *   // Type-safe function - must pass a valid error code as param.
+ *   let error = new ErrorFactory<Err>('scope', 'Service', presets);
+ *
+ *   ...
+ *   throw error.create(Err.GENERIC);
+ *   ...
+ *   throw error.create(Err.FILE_NOT_FOUND, {'file': fileName});
+ *   ...
+ *   // Service: Could not file file: foo.txt (scope/file-not-found).
+ *
+ *   catch (e) {
+ *     assert(e.message === "Could not find file: foo.txt.");
+ *     if (e.code === 'scope/file-not-found') {
+ *       console.log("Could not read file: " + e['file']);
+ *     }
+ *   }
+ * ```
+ * @see inspired by:
+ *   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Custom_Error_Types
+ */ export class NsErrorFactory {
+    makeShortCode(flag) {
+        return [
+            this.namespace,
+            flag
+        ].join(this.nsDelimiter);
+    }
+    makeFullCode(shortCode) {
+        return [
+            this.scope,
+            shortCode
+        ].join(this.scopeDelimiter);
+    }
+    makeShortMessage(flag, payload) {
+        const template = this.templates[flag];
+        return template ? replaceTemplate(template, payload) : this.defaultMessage;
+    }
+    makeFullMessage(shortCode, shortMessage) {
+        // Scope - Error message (namespace/flag).
+        // return `[${this.scope}] - ${shortMessage} (${shortCode}).`
+        return this.buildNamespace(shortCode, shortMessage);
+    }
+    /**
+   * Build a new throwable
+   * @example
+   * ```
+   * let age: string | number = 101
+   * const errorFactory = new NsErrorFactory('domain', 'my-lib', {
+   *   ['bad-string']: "Provided an invalid string '{$str}'"
+   * })
+   * if (typeof age !== 'string') {
+   *   throw errorFactory.create('bad-string', {str: age})
+   *   // Out = domain - Provided an invalid string '101' (my-lib/bad-string)
+   *   // Full Code = domain::my-lib/bad-string
+   * }
+   * ```
+   *
+   * @param flag - error event identifier
+   * @param payload - payload data to set template variable values
+   * @returns NsError
+   */ create(flag, ...payload) {
+        const data = _isArr(payload) && payload[0] || {}, shortCode = this.makeShortCode(flag), fullCode = this.makeFullCode(shortCode), shortMessage = this.makeShortMessage(flag, data), fullMessage = this.makeFullMessage(fullCode, shortMessage);
+        return new NsError(shortCode, fullMessage, data);
+    }
+    childFactory(childNamespace, templates) {
+        return new NsErrorFactory(this.scope, [
+            this.namespace,
+            childNamespace
+        ].join(this.nsDelimiter), templates || this.templates, this.nsDelimiter, this.scopeDelimiter, this.defaultMessage);
+    }
+    constructor(scope, namespace, templates, nsDelimiter = '/', scopeDelimiter = ':', defaultMessage = 'Error'){
+        this.scope = scope;
+        this.namespace = namespace;
+        this.templates = templates;
+        this.nsDelimiter = nsDelimiter;
+        this.scopeDelimiter = scopeDelimiter;
+        this.defaultMessage = defaultMessage;
+        this.create = this.create.bind(this);
+        this.buildNamespace = namespaceFactory({
+            scope,
+            namespace,
+            nsDelimiter,
+            scopeDelimiter,
+            defaultMessage
+        });
+    }
+}
+
+//# sourceMappingURL=ns-error-factory.js.map

package/src/lib/ns-error-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/ns-error-factory.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { _isArr } from '@aglyn/shared-util-tools'\nimport { NsError } from './ns-error'\nimport { replaceTemplate } from './tools'\nimport type {\n  ErrorPayload,\n  ErrorTagMessages,\n  ErrorTagPayloads,\n  EventFlag,\n} from './types'\n\nconst DEFAULT_TEMPLATE = `{$scope} {$code} {$message}`\ntype DEFAULT_TEMPLATE = string & typeof DEFAULT_TEMPLATE\ninterface NamespaceOptions {\n  scope: string\n  namespace: string\n  nsDelimiter: string\n  scopeDelimiter: string\n  template?: string | DEFAULT_TEMPLATE\n  defaultMessage?: string\n}\n\nfunction namespaceFactory(options?: NamespaceOptions) {\n  const {\n    scope,\n    namespace,\n    nsDelimiter,\n    scopeDelimiter,\n    template,\n    defaultMessage,\n  } = options\n  function makeShortCode<K extends string>(flag: K): string {\n    return [namespace, flag].join(nsDelimiter)\n  }\n  function makeFullCode<K extends string>(flag: K): string {\n    return [scope, makeShortCode(flag)].join(scopeDelimiter)\n  }\n  function buildNamespace(message: string, code: string) {\n    const tmp = template || DEFAULT_TEMPLATE\n    return replaceTemplate(tmp, {\n      scope,\n      code,\n    })\n  }\n  const builders = new Map<string, string>()\n\n  return <T extends string>(flag: T, msg: string = defaultMessage) => {\n    if (!builders.has(flag)) {\n      const code = makeFullCode(flag)\n      builders.set(flag, code)\n    }\n    return buildNamespace(msg, builders.get(flag))\n  }\n}\n\n/**\n * Standardized App Errors\n *\n * Usage:\n * ```typescript\n *   // Typescript string literals for type-safe codes\n *   type Err =\n *     'unknown' |\n *     'object-not-found'\n *     ;\n *\n *   // Closure enum for type-safe error codes\n *   // at-enum {string}\n *   var Err = {\n *     UNKNOWN: 'unknown',\n *     OBJECT_NOT_FOUND: 'object-not-found',\n *   }\n *\n *   let : Map<Err, string> = {\n *     'generic-error': \"Unknown error\",\n *     'file-not-found': \"Could not find file: {$file}\",\n *   };\n *\n *   // Type-safe function - must pass a valid error code as param.\n *   let error = new ErrorFactory<Err>('scope', 'Service', presets);\n *\n *   ...\n *   throw error.create(Err.GENERIC);\n *   ...\n *   throw error.create(Err.FILE_NOT_FOUND, {'file': fileName});\n *   ...\n *   // Service: Could not file file: foo.txt (scope/file-not-found).\n *\n *   catch (e) {\n *     assert(e.message === \"Could not find file: foo.txt.\");\n *     if (e.code === 'scope/file-not-found') {\n *       console.log(\"Could not read file: \" + e['file']);\n *     }\n *   }\n * ```\n * @see inspired by:\n *   https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Custom_Error_Types\n */\nexport class NsErrorFactory<\n  T extends string = EventFlag,\n  U extends ErrorTagPayloads = ErrorTagPayloads,\n> {\n  private buildNamespace: <T extends string>(flag: T, msg?: string) => string\n\n  constructor(\n    private readonly scope: string,\n    private readonly namespace: string,\n    private readonly templates: ErrorTagMessages<T>,\n    private readonly nsDelimiter = '/',\n    private readonly scopeDelimiter = ':',\n    private readonly defaultMessage = 'Error',\n  ) {\n    this.create = this.create.bind(this)\n    this.buildNamespace = namespaceFactory({\n      scope,\n      namespace,\n      nsDelimiter,\n      scopeDelimiter,\n      defaultMessage,\n    })\n  }\n\n  protected makeShortCode<K extends T>(flag: K): string {\n    return [this.namespace, flag].join(this.nsDelimiter)\n  }\n  protected makeFullCode(shortCode: string): string {\n    return [this.scope, shortCode].join(this.scopeDelimiter)\n  }\n  protected makeShortMessage<K extends T>(\n    flag: K,\n    payload?: ErrorPayload,\n  ): string {\n    const template = this.templates[flag]\n    return template ? replaceTemplate(template, payload) : this.defaultMessage\n  }\n  protected makeFullMessage(shortCode: string, shortMessage: string): string {\n    // Scope - Error message (namespace/flag).\n    // return `[${this.scope}] - ${shortMessage} (${shortCode}).`\n    return this.buildNamespace(shortCode, shortMessage)\n  }\n\n  /**\n   * Build a new throwable\n   * @example\n   * ```\n   * let age: string | number = 101\n   * const errorFactory = new NsErrorFactory('domain', 'my-lib', {\n   *   ['bad-string']: \"Provided an invalid string '{$str}'\"\n   * })\n   * if (typeof age !== 'string') {\n   *   throw errorFactory.create('bad-string', {str: age})\n   *   // Out = domain - Provided an invalid string '101' (my-lib/bad-string)\n   *   // Full Code = domain::my-lib/bad-string\n   * }\n   * ```\n   *\n   * @param flag - error event identifier\n   * @param payload - payload data to set template variable values\n   * @returns NsError\n   */\n  public create<K extends T>(\n    flag: K,\n    ...payload: K extends keyof U ? [U[K]] : []\n  ): NsError {\n    const data: ErrorPayload = (_isArr(payload) && payload[0]) || {},\n      shortCode = this.makeShortCode(flag),\n      fullCode = this.makeFullCode(shortCode),\n      shortMessage = this.makeShortMessage(flag, data),\n      fullMessage = this.makeFullMessage(fullCode, shortMessage)\n\n    return new NsError(shortCode, fullMessage, data)\n  }\n\n  public childFactory<T extends string, U extends ErrorTagPayloads<T>>(\n    childNamespace: string,\n    templates?: ErrorTagMessages<T>,\n  ) {\n    return new NsErrorFactory<T, U>(\n      this.scope,\n      [this.namespace, childNamespace].join(this.nsDelimiter),\n      (templates || this.templates) as ErrorTagMessages<T>,\n      this.nsDelimiter,\n      this.scopeDelimiter,\n      this.defaultMessage,\n    )\n  }\n}\n"],"names":["_isArr","NsError","replaceTemplate","DEFAULT_TEMPLATE","namespaceFactory","options","scope","namespace","nsDelimiter","scopeDelimiter","template","defaultMessage","makeShortCode","flag","join","makeFullCode","buildNamespace","message","code","tmp","builders","Map","msg","has","set","get","NsErrorFactory","shortCode","makeShortMessage","payload","templates","makeFullMessage","shortMessage","create","data","fullCode","fullMessage","childFactory","childNamespace","bind"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,MAAM,QAAQ,2BAA0B;AACjD,SAASC,OAAO,QAAQ,gBAAY;AACpC,SAASC,eAAe,QAAQ,aAAS;AAQzC,MAAMC,mBAAmB,CAAC,2BAA2B,CAAC;AAWtD,SAASC,iBAAiBC,OAA0B;IAClD,MAAM,EACJC,KAAK,EACLC,SAAS,EACTC,WAAW,EACXC,cAAc,EACdC,QAAQ,EACRC,cAAc,EACf,GAAGN;IACJ,SAASO,cAAgCC,IAAO;QAC9C,OAAO;YAACN;YAAWM;SAAK,CAACC,IAAI,CAACN;IAChC;IACA,SAASO,aAA+BF,IAAO;QAC7C,OAAO;YAACP;YAAOM,cAAcC;SAAM,CAACC,IAAI,CAACL;IAC3C;IACA,SAASO,eAAeC,OAAe,EAAEC,IAAY;QACnD,MAAMC,MAAMT,YAAYP;QACxB,OAAOD,gBAAgBiB,KAAK;YAC1Bb;YACAY;QACF;IACF;IACA,MAAME,WAAW,IAAIC;IAErB,OAAO,CAAmBR,MAASS,MAAcX,cAAc;QAC7D,IAAI,CAACS,SAASG,GAAG,CAACV,OAAO;YACvB,MAAMK,OAAOH,aAAaF;YAC1BO,SAASI,GAAG,CAACX,MAAMK;QACrB;QACA,OAAOF,eAAeM,KAAKF,SAASK,GAAG,CAACZ;IAC1C;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CC,GACD,OAAO,MAAMa;IAwBDd,cAA2BC,IAAO,EAAU;QACpD,OAAO;YAAC,IAAI,CAACN,SAAS;YAAEM;SAAK,CAACC,IAAI,CAAC,IAAI,CAACN,WAAW;IACrD;IACUO,aAAaY,SAAiB,EAAU;QAChD,OAAO;YAAC,IAAI,CAACrB,KAAK;YAAEqB;SAAU,CAACb,IAAI,CAAC,IAAI,CAACL,cAAc;IACzD;IACUmB,iBACRf,IAAO,EACPgB,OAAsB,EACd;QACR,MAAMnB,WAAW,IAAI,CAACoB,SAAS,CAACjB,KAAK;QACrC,OAAOH,WAAWR,gBAAgBQ,UAAUmB,WAAW,IAAI,CAAClB,cAAc;IAC5E;IACUoB,gBAAgBJ,SAAiB,EAAEK,YAAoB,EAAU;QACzE,0CAA0C;QAC1C,6DAA6D;QAC7D,OAAO,IAAI,CAAChB,cAAc,CAACW,WAAWK;IACxC;IAEA;;;;;;;;;;;;;;;;;;GAkBC,GACD,AAAOC,OACLpB,IAAO,EACP,GAAGgB,OAAwC,EAClC;QACT,MAAMK,OAAqB,AAAClC,OAAO6B,YAAYA,OAAO,CAAC,EAAE,IAAK,CAAC,GAC7DF,YAAY,IAAI,CAACf,aAAa,CAACC,OAC/BsB,WAAW,IAAI,CAACpB,YAAY,CAACY,YAC7BK,eAAe,IAAI,CAACJ,gBAAgB,CAACf,MAAMqB,OAC3CE,cAAc,IAAI,CAACL,eAAe,CAACI,UAAUH;QAE/C,OAAO,IAAI/B,QAAQ0B,WAAWS,aAAaF;IAC7C;IAEOG,aACLC,cAAsB,EACtBR,SAA+B,EAC/B;QACA,OAAO,IAAIJ,eACT,IAAI,CAACpB,KAAK,EACV;YAAC,IAAI,CAACC,SAAS;YAAE+B;SAAe,CAACxB,IAAI,CAAC,IAAI,CAACN,WAAW,GACrDsB,aAAa,IAAI,CAACA,SAAS,EAC5B,IAAI,CAACtB,WAAW,EAChB,IAAI,CAACC,cAAc,EACnB,IAAI,CAACE,cAAc;IAEvB;IAjFA,YACE,AAAiBL,KAAa,EAC9B,AAAiBC,SAAiB,EAClC,AAAiBuB,SAA8B,EAC/C,AAAiBtB,cAAc,GAAG,EAClC,AAAiBC,iBAAiB,GAAG,EACrC,AAAiBE,iBAAiB,OAAO,CACzC;aANiBL,QAAAA;aACAC,YAAAA;aACAuB,YAAAA;aACAtB,cAAAA;aACAC,iBAAAA;aACAE,iBAAAA;QAEjB,IAAI,CAACsB,MAAM,GAAG,IAAI,CAACA,MAAM,CAACM,IAAI,CAAC,IAAI;QACnC,IAAI,CAACvB,cAAc,GAAGZ,iBAAiB;YACrCE;YACAC;YACAC;YACAC;YACAE;QACF;IACF;AAkEF"}

package/src/lib/ns-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ErrorPayload } from './types';
+export declare class NsError extends Error {
+    readonly code: string;
+    payload: ErrorPayload;
+    readonly name = "NsError";
+    message: string;
+    constructor(code: string, message: string, payload: ErrorPayload);
+}

package/src/lib/ns-error.js

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { NsErrorFactory } from "./ns-error-factory.js";
+export class NsError extends Error {
+    constructor(code, message, payload){
+        super(message), this.code = code, this.payload = payload, this.name = 'NsError';
+        this.message = message;
+        // Fix For ES5
+        // https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work
+        Object.setPrototypeOf(this, NsError.prototype);
+        // Maintains proper stack trace for where our error was thrown.
+        // Only available on V8.
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, NsErrorFactory.prototype.create);
+        }
+    }
+}
+
+//# sourceMappingURL=ns-error.js.map

package/src/lib/ns-error.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/ns-error.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { NsErrorFactory } from './ns-error-factory'\nimport type { ErrorPayload } from './types'\n\nexport class NsError extends Error {\n  override readonly name = 'NsError'\n  override message: string\n\n  constructor(\n    public readonly code: string,\n    message: string,\n    public payload: ErrorPayload,\n  ) {\n    super(message)\n    this.message = message\n    // Fix For ES5\n    // https://github.com/Microsoft/TypeScript-wiki/blob/master/Breaking-Changes.md#extending-built-ins-like-error-array-and-map-may-no-longer-work\n    Object.setPrototypeOf(this, NsError.prototype)\n\n    // Maintains proper stack trace for where our error was thrown.\n    // Only available on V8.\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, NsErrorFactory.prototype.create)\n    }\n  }\n}\n"],"names":["NsErrorFactory","NsError","Error","code","message","payload","name","Object","setPrototypeOf","prototype","captureStackTrace","create"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,cAAc,QAAQ,wBAAoB;AAGnD,OAAO,MAAMC,gBAAgBC;IAI3B,YACE,AAAgBC,IAAY,EAC5BC,OAAe,EACf,AAAOC,OAAqB,CAC5B;QACA,KAAK,CAACD,eAJUD,OAAAA,WAETE,UAAAA,cANSC,OAAO;QASvB,IAAI,CAACF,OAAO,GAAGA;QACf,cAAc;QACd,+IAA+I;QAC/IG,OAAOC,cAAc,CAAC,IAAI,EAAEP,QAAQQ,SAAS;QAE7C,+DAA+D;QAC/D,wBAAwB;QACxB,IAAIP,MAAMQ,iBAAiB,EAAE;YAC3BR,MAAMQ,iBAAiB,CAAC,IAAI,EAAEV,eAAeS,SAAS,CAACE,MAAM;QAC/D;IACF;AACF"}

package/src/lib/tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ErrorPayload } from './types';
+export type ReplaceTemplateOptions = {
+    pattern?: RegExp | string;
+};
+export declare const DEFAULT_REPLACER_REGEX: RegExp;
+/**
+ * Replaces var placeholders in template string with matching keys in payload
+ * @example
+ * replaceTemplate("Illegal app name: '{$appName}'", {appName: "Foo App"})
+ * @param template - template to replace e.g., "Illegal app name: '{$appName}'"
+ * @param payload - dictionary of placeholder keys mapped to dynamic values
+ * @param options - override replacement pattern strategy
+ */
+export declare function replaceTemplate(template: string, payload?: ErrorPayload, options?: ReplaceTemplateOptions): string;
+export default replaceTemplate;

package/src/lib/tools.js

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export const DEFAULT_REPLACER_REGEX = /\{\$([^}]+)}/g;
+/**
+ * Replaces var placeholders in template string with matching keys in payload
+ * @example
+ * replaceTemplate("Illegal app name: '{$appName}'", {appName: "Foo App"})
+ * @param template - template to replace e.g., "Illegal app name: '{$appName}'"
+ * @param payload - dictionary of placeholder keys mapped to dynamic values
+ * @param options - override replacement pattern strategy
+ */ export function replaceTemplate(template, payload, options) {
+    const { pattern = DEFAULT_REPLACER_REGEX } = options || {};
+    return String(template).replace(pattern, (_, key)=>{
+        const value = payload == null ? void 0 : payload[key];
+        return value !== null ? String(value) : `<${key}?>`;
+    });
+}
+export default replaceTemplate;
+
+//# sourceMappingURL=tools.js.map

package/src/lib/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/tools.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {ErrorPayload} from './types'\n\n\nexport type ReplaceTemplateOptions = {\n  pattern?: RegExp | string\n}\n\nexport const DEFAULT_REPLACER_REGEX = /\\{\\$([^}]+)}/g\n\n/**\n * Replaces var placeholders in template string with matching keys in payload\n * @example\n * replaceTemplate(\"Illegal app name: '{$appName}'\", {appName: \"Foo App\"})\n * @param template - template to replace e.g., \"Illegal app name: '{$appName}'\"\n * @param payload - dictionary of placeholder keys mapped to dynamic values\n * @param options - override replacement pattern strategy\n */\nexport function replaceTemplate(\n  template: string,\n  payload?: ErrorPayload,\n  options?: ReplaceTemplateOptions,\n): string {\n  const {pattern = DEFAULT_REPLACER_REGEX} = options || {}\n  return String(template).replace(pattern, (_, key) => {\n    const value = payload?.[key]\n    return value !== null ? String(value) : `<${key}?>`\n  })\n}\n\nexport default replaceTemplate\n"],"names":["DEFAULT_REPLACER_REGEX","replaceTemplate","template","payload","options","pattern","String","replace","_","key","value"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GASD,OAAO,MAAMA,yBAAyB,gBAAe;AAErD;;;;;;;CAOC,GACD,OAAO,SAASC,gBACdC,QAAgB,EAChBC,OAAsB,EACtBC,OAAgC;IAEhC,MAAM,EAACC,UAAUL,sBAAsB,EAAC,GAAGI,WAAW,CAAC;IACvD,OAAOE,OAAOJ,UAAUK,OAAO,CAACF,SAAS,CAACG,GAAGC;QAC3C,MAAMC,QAAQP,2BAAAA,OAAS,CAACM,IAAI;QAC5B,OAAOC,UAAU,OAAOJ,OAAOI,SAAS,CAAC,CAAC,EAAED,IAAI,EAAE,CAAC;IACrD;AACF;AAEA,eAAeR,gBAAe"}

package/src/lib/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2021 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export type EventFlag = string;
+export type EventMessage = string;
+export type Key = string;
+export type VarSyntax<T extends Key> = `{$${T}}`;
+export type ErrorPayload<K extends keyof any = keyof any, T = unknown> = Partial<Record<K, T>>;
+export type ErrorTagMessages<T extends EventFlag = string> = Record<T, EventMessage>;
+export type ErrorTagPayloads<T extends Key = string> = Record<T, ErrorPayload>;

package/src/lib/types.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2021 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export { };
+
+//# sourceMappingURL=types.js.map

package/src/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/types.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2021 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport type EventFlag = string\nexport type EventMessage = string\nexport type Key = string\nexport type VarSyntax<T extends Key> = `{$${T}}`\nexport type ErrorPayload<K extends keyof any = keyof any, T = unknown> = Partial<Record<K, T>>\n\nexport type ErrorTagMessages<T extends EventFlag = string> = Record<T, EventMessage>\nexport type ErrorTagPayloads<T extends Key = string> = Record<T, ErrorPayload>\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GASD,WAA8E"}

package/src/lib/upstream-service-error.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A non-2xx answer from a vendor the platform calls on a customer's behalf
+ * — a model provider, a payment processor, a mail relay.
+ *
+ * `message` is a fixed, customer-safe sentence the caller chose; the
+ * vendor's own words describe OUR account with them (a key, a rate limit, a
+ * balance) and name the vendor to a white-label org's users, so they go to
+ * the log beside `requestId` and never travel in this object.
+ */
+export declare class UpstreamServiceError extends Error {
+    readonly name: string;
+    /** The vendor's HTTP status, or null when the failure had none. */
+    readonly status: number | null;
+    /**
+     * Whether the vendor said "come back later" rather than "this request is
+     * wrong": a rate limit or an overload. Everything else — a bad request,
+     * an authentication failure, a vendor fault — is not, and a caller must
+     * not retry it in a loop.
+     */
+    readonly retryable: boolean;
+    /** The vendor's request id, when it sent one — the log's join key. */
+    readonly requestId: string | null;
+    constructor(message: string, options: {
+        status: number | null;
+        retryable: boolean;
+        requestId?: string | null;
+    });
+}
+export default UpstreamServiceError;

package/src/lib/upstream-service-error.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * A non-2xx answer from a vendor the platform calls on a customer's behalf
+ * — a model provider, a payment processor, a mail relay.
+ *
+ * `message` is a fixed, customer-safe sentence the caller chose; the
+ * vendor's own words describe OUR account with them (a key, a rate limit, a
+ * balance) and name the vendor to a white-label org's users, so they go to
+ * the log beside `requestId` and never travel in this object.
+ */ export class UpstreamServiceError extends Error {
+    constructor(message, options){
+        var _options_requestId;
+        super(message), this.name = 'UpstreamServiceError';
+        this.status = options.status;
+        this.retryable = options.retryable;
+        this.requestId = (_options_requestId = options.requestId) != null ? _options_requestId : null;
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
+    }
+}
+export default UpstreamServiceError;
+
+//# sourceMappingURL=upstream-service-error.js.map

package/src/lib/upstream-service-error.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/errors/src/lib/upstream-service-error.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * A non-2xx answer from a vendor the platform calls on a customer's behalf\n * — a model provider, a payment processor, a mail relay.\n *\n * `message` is a fixed, customer-safe sentence the caller chose; the\n * vendor's own words describe OUR account with them (a key, a rate limit, a\n * balance) and name the vendor to a white-label org's users, so they go to\n * the log beside `requestId` and never travel in this object.\n */\nexport class UpstreamServiceError extends Error {\n  override readonly name: string = 'UpstreamServiceError'\n  /** The vendor's HTTP status, or null when the failure had none. */\n  readonly status: number | null\n  /**\n   * Whether the vendor said \"come back later\" rather than \"this request is\n   * wrong\": a rate limit or an overload. Everything else — a bad request,\n   * an authentication failure, a vendor fault — is not, and a caller must\n   * not retry it in a loop.\n   */\n  readonly retryable: boolean\n  /** The vendor's request id, when it sent one — the log's join key. */\n  readonly requestId: string | null\n\n  constructor(\n    message: string,\n    options: { status: number | null; retryable: boolean; requestId?: string | null },\n  ) {\n    super(message)\n    this.status = options.status\n    this.retryable = options.retryable\n    this.requestId = options.requestId ?? null\n    Object.setPrototypeOf(this, new.target.prototype)\n    if (Error.captureStackTrace) Error.captureStackTrace(this, new.target)\n  }\n}\n\nexport default UpstreamServiceError\n"],"names":["UpstreamServiceError","Error","message","options","name","status","retryable","requestId","Object","setPrototypeOf","prototype","captureStackTrace"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,GACD,OAAO,MAAMA,6BAA6BC;IAcxC,YACEC,OAAe,EACfC,OAAiF,CACjF;YAIiBA;QAHjB,KAAK,CAACD,eAjBUE,OAAe;QAkB/B,IAAI,CAACC,MAAM,GAAGF,QAAQE,MAAM;QAC5B,IAAI,CAACC,SAAS,GAAGH,QAAQG,SAAS;QAClC,IAAI,CAACC,SAAS,IAAGJ,qBAAAA,QAAQI,SAAS,YAAjBJ,qBAAqB;QACtCK,OAAOC,cAAc,CAAC,IAAI,EAAE,WAAWC,SAAS;QAChD,IAAIT,MAAMU,iBAAiB,EAAEV,MAAMU,iBAAiB,CAAC,IAAI,EAAE;IAC7D;AACF;AAEA,eAAeX,qBAAoB"}