runtime-reporter 0.1.0 → 0.3.0

package/README.md

@@ -1,44 +1,147 @@
 # Runtime Reporter
 
-Runtime messaging that is convenient in development and secure in production
-A lightweight runtime messaging solution that's helpful in dev, secure in production
+Structured runtime events for applications and frameworks. A composable foundation for logging, messaging, and runtime reporting.
 
-### Usage
+## Features
 
-1. Define your messages
+- **Security focused**: Pass an empty message set in production to avoid exposing internal messaging.
+- **Centralized messages**: Define message text once; reference by a unique code everywhere else.
+- **Tokenized templates**: Apply runtime data to messages via templated strings and tokenized variables.
+- **Type-safe**: Autocomplete and compile-time validation for message codes and token names.
+- **Tree-shakeable**: Pass an empty message set in production to reduce your bundle size
+- **Test friendly**: Use `message()` to assert on final output without duplicating message text.
+- **Code-based messaging**: Coded messages make it easy to identify errors to perform debugging tasks.
+- **Small footprint**: Minimal bundle size (~2 KB minified) so it adds negligible weight to your app.
+- **Zero dependencies**: No runtime dependencies; the published package is fully self-contained.
+- **Scalable pattern**: Can scale to fit your specific needs regardless of your project's size.
+
+## Installation
+
+```bash
+npm install runtime-reporter
+```
+
+## Usage
+
+### 1) Define your messages
+
+Define the message “schema” (code + template + tokens), then create a `messages` record keyed by the codes.
 
 ```ts
-import { RuntimeReporterMessages } from "runtime-reporter";
+import type { RuntimeReporterMessages } from "runtime-reporter";
 
-type RuntimeMessages = Array<{
-    code: "ERR01";
-    template: "{{ componentName }} An error occured ...";
-    tokens: ["componentName"];
-}>;
+type MyMessages =
+    | {
+          code: "ERR01";
+          template: "{{ componentName }} failed to mount";
+          tokens: ["componentName"];
+      }
+    | {
+          code: "INFO01";
+          template: "Ready";
+          tokens?: undefined;
+      };
 
-const messages: RuntimeReporterMessages<RuntimeMessages> = {
-    ERR01: "{{ componentName }} An error occured ...",
+const messages: RuntimeReporterMessages<MyMessages> = {
+    ERR01: "{{ componentName }} failed to mount",
+    INFO01: "Ready",
 };
 ```
 
-2. Create the reporter
+### 2) Create the reporter
 
-Create a reporter instance by passing your messages object and optional configuration. In production builds, pass an empty array to enable tree-shaking and remove all message text from your bundle. The optional `scope` parameter prefixes message codes for easier identification (e.g., `MyApp(ERR01)` instead of `(ERR01)`).
+Pass your messages to `createReporter()` to create a reporter instance.
 
 ```ts
-import { createRuntimeReporter } = 'runtime-reporter';
+import { createReporter } from "runtime-reporter";
 
-const reporter = createRuntimeReporter(
-    process.env.NODE_ENV !== 'production' ? messages : ([] as RuntimeMessages)
+export const reporter = createReporter(
+    // Pass an empty object in production for better security and a smaller bundle size
+    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
 );
-
-export default reporter;
 ```
 
-3. Call the reporter methods in your project
+### 3) Use the reporter
 
-```js
-import reporter from "../my-runtime-reporter";
+Call the various reporter methods wherever you need them.
 
+```ts
 reporter.error("ERR01", { componentName: "MyComponent" });
+// logs: "MyComponent failed to mount (ERR01)"
+
+reporter.message("INFO01");
+// returns: "Ready (INFO01)"
+```
+
+## API
+
+### `createReporter(RuntimeReporterMessages, options?: RuntimeReporterOptions): RuntimeReporter`
+
+Takes a list of messages, an optional set of configuration options, and returns a reporter object.
+
+### `RuntimeReporter`
+
+| Method  | Type                                                       | Description                                                                                                                             |
+| ------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| message | `(code: string, tokens:? RuntimeReporterTokens) => string` | Returns the resolved message (no logging); useful for testing environments.                                                             |
+| warn    | `(code: string, tokens:? RuntimeReporterTokens) => void`   | Logs via `console.warn` **only if** the template exists in `messages`.                                                                  |
+| error   | `(code: string, tokens:? RuntimeReporterTokens) => void`   | Logs via `console.error` **only if** the template exists in `messages`.                                                                 |
+| log     | `(code: string, tokens:? RuntimeReporterTokens) => void`   | Logs via `console.log` **only if** the template exists in `messages`.                                                                   |
+| fail    | `(code: string, tokens:? RuntimeReporterTokens) => never`  | Throws `new Error(resolvedMessage)` in **all** environments. Uses the `defaultTemplate` when the template does not exist in `messages`. |
+
+### `RuntimeReporterOptions`
+
+| Property        | Type                                        | Required | Description                                                                                                                                                                                      |
+| --------------- | ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| formatMessage   | `(message: string, code: string) => string` | No       | Customize the final output of every message. By default, messages are in the format: `"<message> (<code>)"`.                                                                                     |
+| defaultTemplate | `string`                                    | No       | Fallback message text used when the code does not exist in `messages`. Defaults to `"An error occurred"`. This is mostly relevant for `fail()` in production when you pass an empty message set. |
+
+### `RuntimeReporterTokens`
+
+| Property | Type                   | Description                                                                                                                  |
+| -------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `string` | `RuntimeReporterToken` | A record of token names along with their replacement value. Supported types include: `string`, `number`, `boolean`, `Error`. |
+
+## Examples
+
+### Custom formatting
+
+You can customize the format of the message by providing a custom `formatMessage` function.
+
+```ts
+const reporter = createReporter(messages, {
+    formatMessage: (msg, code) => `[${code}] ${msg}`,
+});
+
+reporter.message("INFO01");
+// "[INFO01] Ready"
+```
+
+### Using `message()` in tests
+
+The `message` method returns the resolved string without side effects, allowing you to validate precise messaging without duplicating text.
+
+```ts
+import { describe, it, expect, vi } from "vitest";
+import { reporter } from "./reporter";
+
+describe("reporter messages", () => {
+    it("consoles error ERR01 correctly", () => {
+        vi.spyOn(console, "error").mockImplementation(() => {});
+        reporter.error("ERR01", { componentName: "Widget" });
+
+        expect(console.error).toHaveBeenCalledWith(
+            reporter.message("ERR01", { componentName: "Widget" })
+        );
+    });
+});
+```
+
+### CommonJS support
+
+If needed, Common JS imports are also available.
+
+```js
+// CJS
+const { createReporter } = require("runtime-reporter");
 ```

package/dist/index.cjs

@@ -17,10 +17,10 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// index.ts
+// src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createRuntimeReporter: () => createRuntimeReporter
+  createReporter: () => createReporter
 });
 module.exports = __toCommonJS(index_exports);
 var resolveTemplate = function resolveTemplate2(template, tokens) {
@@ -29,13 +29,13 @@ var resolveTemplate = function resolveTemplate2(template, tokens) {
     Object.entries(tokens || {}).forEach((entry) => {
       const [token, value] = entry;
       const replace = value instanceof Error ? value.message : String(value ?? "");
-      const santized = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      message = message.replace(new RegExp(`\\{\\{\\s*${santized}\\s*\\}\\}`, "g"), replace);
+      const sanitized = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      message = message.replace(new RegExp(`\\{\\{\\s*${sanitized}\\s*\\}\\}`, "g"), replace);
     });
   }
   return message;
 };
-function createRuntimeReporter(messages, options = {}) {
+function createReporter(messages, options = {}) {
   const {
     formatMessage = (message, code) => `${message} (${code})`,
     defaultTemplate = "An error occurred"
@@ -70,6 +70,6 @@ function createRuntimeReporter(messages, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createRuntimeReporter
+  createReporter
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../index.ts"],"sourcesContent":["/**\n * The type information for a single runtime reporter message\n * @since v0.1.0\n */\nexport type RuntimeReporterMessage = {\n    code: string;\n    template: string;\n    tokens?: string[];\n};\n\n/**\n * The type for a full list of messages with their associated code and template\n * @since v0.1.0\n */\nexport type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {\n    [K in T[number][\"code\"]]: Extract<T[number], { code: K }>[\"template\"];\n};\n\n/**\n * The type for the supported values of a placeholder token\n * @since v0.1.0\n */\nexport type RuntimeReporterToken = string | number | boolean | Error | null | undefined;\n\n/**\n * A utility type used to determine the second argument of the runtime reporter methods\n * @private\n */\ntype RuntimeReporterTokensArgs<\n    T extends RuntimeReporterMessages<RuntimeReporterMessage[]>,\n    U extends keyof T,\n> =\n    T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage[]>\n        ? Extract<V[number], { code: U }>[\"tokens\"] extends infer Tokens\n            ? Tokens extends readonly string[]\n                ? [tokens: Record<Tokens[number], RuntimeReporterToken>]\n                : []\n            : []\n        : never;\n\n/**\n * The runtime report object with all of it's associated methods; the result\n * of the primary export: `createRuntimeReporter`\n * @private\n */\ninterface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate an of the raw message text._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    message<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): string;\n\n    /**\n     * Logs a warning to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createRuntimeReporter` function\n     * is provided an empty array._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    warn<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs an error to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createRuntimeReporter` function\n     * is provided an empty array._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    error<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs a message to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createRuntimeReporter` function\n     * is provided an empty array._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    log<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Throws an error with the full text of the targeted message in all environments\n     *\n     * _Note: When the `createRuntimeReporter` function is called in production with an empty\n     * array, this method will use the \"defaultTemplate\" option in this format: \"<defaultTemplate> (<code>)\"_\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    fail<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n}\n\nexport interface RuntimeReporterOptions {\n    /**\n     * A hook to format the message text univerally. By default, it\n     * outputs the message in the following format: \"<message> (<code>)\"\n     * @param message The resolved message text; the placeholders have been replaced by their token values\n     * @param code The unique code associated with the message\n     * @returns The final, fully formatted message\n     */\n    formatMessage?: (message: string, code: string) => string;\n\n    /**\n     * The default template to fallback on when a provided code does not\n     * have an associated message. Defaults to \"An error occurred\"\n     *\n     * _Note: This is only used when the `fail` method is called in production\n     * environments when the `createRuntimeReporter` function is provided an empty array._\n     */\n    defaultTemplate?: string;\n}\n\n/**\n * Resolves the message text via the message template and the associated tokens\n * @param template The template string for the reported message\n * @param tokens The token names and values for the instance\n * @returns The resolved message text; returns an empty string if the template is falsy\n */\nconst resolveTemplate = function resolveTemplate(\n    template: string,\n    tokens?: Record<string, RuntimeReporterToken>\n): string {\n    let message = template;\n\n    if (message) {\n        Object.entries(tokens || {}).forEach((entry) => {\n            const [token, value] = entry;\n            const replace = value instanceof Error ? value.message : String(value ?? \"\");\n            const santized = token.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n            message = message.replace(new RegExp(`\\\\{\\\\{\\\\s*${santized}\\\\s*\\\\}\\\\}`, \"g\"), replace);\n        });\n    }\n\n    return message;\n};\n\n/**\n * Creates a reporter object with various helpful runtime methods\n * @param messages The messages record organized by code and template\n * @param options Optional configuration options\n * @returns A runtime report object\n */\nexport function createRuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>>(\n    messages: T,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n\n    /**\n     * Retrieves the final message for a give code and its associated tokens\n     * @param code The unique code associated with the message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     * @returns The fully resolve message or an empty string if there was no template\n     */\n    const getMessage = function getMessage(\n        code: string,\n        ...args: Array<Record<string, RuntimeReporterToken>>\n    ): string {\n        const template = messages[code] || defaultTemplate;\n        const tokens = args[0];\n        const text = resolveTemplate(template, tokens);\n        return formatMessage(text, code);\n    };\n\n    return {\n        message: (code, ...args) => {\n            return getMessage(code, ...args);\n        },\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.log(message);\n        },\n        fail: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            throw new Error(message);\n        },\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA6IA,IAAM,kBAAkB,SAASA,iBAC7B,UACA,QACM;AACN,MAAI,UAAU;AAEd,MAAI,SAAS;AACT,WAAO,QAAQ,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU;AAC5C,YAAM,CAAC,OAAO,KAAK,IAAI;AACvB,YAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,SAAS,EAAE;AAC3E,YAAM,WAAW,MAAM,QAAQ,uBAAuB,MAAM;AAC5D,gBAAU,QAAQ,QAAQ,IAAI,OAAO,aAAa,QAAQ,cAAc,GAAG,GAAG,OAAO;AAAA,IACzF,CAAC;AAAA,EACL;AAEA,SAAO;AACX;AAQO,SAAS,sBACZ,UACA,UAAkC,CAAC,GACjB;AAClB,QAAM;AAAA,IACF,gBAAgB,CAAC,SAAS,SAAS,GAAG,OAAO,KAAK,IAAI;AAAA,IACtD,kBAAkB;AAAA,EACtB,IAAI;AAQJ,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,SAAS,IAAI,KAAK;AACnC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SAAS;AACxB,aAAO,WAAW,MAAM,GAAG,IAAI;AAAA,IACnC;AAAA,IACA,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IAC7C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAC5C;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IAC3C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,YAAM,IAAI,MAAM,OAAO;AAAA,IAC3B;AAAA,EACJ;AACJ;","names":["resolveTemplate","getMessage"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * The type information for a single runtime reporter message\n * @since v0.1.0\n */\nexport type RuntimeReporterMessage = {\n    code: string;\n    template: string;\n    tokens?: string[];\n};\n\n/**\n * The type for a full list of messages with their associated code and template\n * @since v0.1.0\n */\nexport type RuntimeReporterMessages<T extends RuntimeReporterMessage> = {\n    [K in T[\"code\"]]: Extract<T, { code: K }>[\"template\"];\n};\n\n/**\n * The type for the supported values of a placeholder token\n * @since v0.1.0\n */\nexport type RuntimeReporterToken = string | number | boolean | Error | null | undefined;\n\n/**\n * The type for a record of placeholder token names and their values\n * @since v0.2.0\n */\nexport type RuntimeReporterTokens = Record<string, RuntimeReporterToken>;\n\n/**\n * A utility type used to determine the second argument of the runtime reporter methods\n * @private\n */\ntype RuntimeReporterTokensArgs<\n    T extends RuntimeReporterMessages<RuntimeReporterMessage>,\n    U extends keyof T,\n> =\n    T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage>\n        ? Extract<V, { code: U }>[\"tokens\"] extends infer Tokens\n            ? Tokens extends readonly string[]\n                ? [tokens: Record<Tokens[number], RuntimeReporterToken>]\n                : []\n            : []\n        : never;\n\n/**\n * The runtime report object with all of it's associated methods; the result\n * of the primary export: `createReporter`\n * @private\n */\ninterface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate an of the raw message text._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    message<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): string;\n\n    /**\n     * Logs a warning to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createReporter` function\n     * is provided an empty message set._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    warn<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs an error to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createReporter` function\n     * is provided an empty message set._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    error<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs a message to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createReporter` function\n     * is provided an empty message set._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    log<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Throws an error with the full text of the targeted message in all environments\n     *\n     * _Note: When the `createReporter` function is called in production with an empty\n     * message set, this method will use the \"defaultTemplate\" option in this format: \"<defaultTemplate> (<code>)\"_\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    fail<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n}\n\nexport interface RuntimeReporterOptions {\n    /**\n     * A hook to format the message text universally. By default, it\n     * outputs the message in the following format: \"<message> (<code>)\"\n     * @param message The resolved message text; the placeholders have been replaced by their token values\n     * @param code The unique code associated with the message\n     * @returns The final, fully formatted message\n     */\n    formatMessage?: (message: string, code: string) => string;\n\n    /**\n     * The default template to fallback on when a provided code does not\n     * have an associated message. Defaults to \"An error occurred\"\n     *\n     * _Note: This is only used when the `fail` method is called in production\n     * environments when the `createReporter` function is provided an empty message set._\n     */\n    defaultTemplate?: string;\n}\n\n/**\n * Resolves the message text via the message template and the associated tokens\n * @param template The template string for the reported message\n * @param tokens The token names and values for the instance\n * @returns The resolved message text; returns an empty string if the template is falsy\n */\nconst resolveTemplate = function resolveTemplate(\n    template: string,\n    tokens?: Record<string, RuntimeReporterToken>\n): string {\n    let message = template;\n\n    if (message) {\n        Object.entries(tokens || {}).forEach((entry) => {\n            const [token, value] = entry;\n            const replace = value instanceof Error ? value.message : String(value ?? \"\");\n            const sanitized = token.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n            message = message.replace(new RegExp(`\\\\{\\\\{\\\\s*${sanitized}\\\\s*\\\\}\\\\}`, \"g\"), replace);\n        });\n    }\n\n    return message;\n};\n\n/**\n * Creates a reporter object with various helpful runtime methods\n * @param messages The messages record organized by code and template\n * @param options Optional configuration options\n * @returns A runtime report object\n */\nexport function createReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>>(\n    messages: T,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n\n    /**\n     * Retrieves the final message for a give code and its associated tokens\n     * @param code The unique code associated with the message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     * @returns The fully resolve message or an empty string if there was no template\n     */\n    const getMessage = function getMessage(\n        code: string,\n        ...args: Array<Record<string, RuntimeReporterToken>>\n    ): string {\n        const template = messages[code] || defaultTemplate;\n        const tokens = args[0];\n        const text = resolveTemplate(template, tokens);\n        return formatMessage(text, code);\n    };\n\n    return {\n        message: (code, ...args) => {\n            return getMessage(code, ...args);\n        },\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.log(message);\n        },\n        fail: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            throw new Error(message);\n        },\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAmJA,IAAM,kBAAkB,SAASA,iBAC7B,UACA,QACM;AACN,MAAI,UAAU;AAEd,MAAI,SAAS;AACT,WAAO,QAAQ,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU;AAC5C,YAAM,CAAC,OAAO,KAAK,IAAI;AACvB,YAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,SAAS,EAAE;AAC3E,YAAM,YAAY,MAAM,QAAQ,uBAAuB,MAAM;AAC7D,gBAAU,QAAQ,QAAQ,IAAI,OAAO,aAAa,SAAS,cAAc,GAAG,GAAG,OAAO;AAAA,IAC1F,CAAC;AAAA,EACL;AAEA,SAAO;AACX;AAQO,SAAS,eACZ,UACA,UAAkC,CAAC,GACjB;AAClB,QAAM;AAAA,IACF,gBAAgB,CAAC,SAAS,SAAS,GAAG,OAAO,KAAK,IAAI;AAAA,IACtD,kBAAkB;AAAA,EACtB,IAAI;AAQJ,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,SAAS,IAAI,KAAK;AACnC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SAAS;AACxB,aAAO,WAAW,MAAM,GAAG,IAAI;AAAA,IACnC;AAAA,IACA,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IAC7C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAC5C;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IAC3C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,YAAM,IAAI,MAAM,OAAO;AAAA,IAC3B;AAAA,EACJ;AACJ;","names":["resolveTemplate","getMessage"]}

package/dist/index.d.cts

@@ -11,8 +11,8 @@ type RuntimeReporterMessage = {
  * The type for a full list of messages with their associated code and template
  * @since v0.1.0
  */
-type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {
-    [K in T[number]["code"]]: Extract<T[number], {
+type RuntimeReporterMessages<T extends RuntimeReporterMessage> = {
+    [K in T["code"]]: Extract<T, {
         code: K;
     }>["template"];
 };
@@ -21,19 +21,24 @@ type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {
  * @since v0.1.0
  */
 type RuntimeReporterToken = string | number | boolean | Error | null | undefined;
+/**
+ * The type for a record of placeholder token names and their values
+ * @since v0.2.0
+ */
+type RuntimeReporterTokens = Record<string, RuntimeReporterToken>;
 /**
  * A utility type used to determine the second argument of the runtime reporter methods
  * @private
  */
-type RuntimeReporterTokensArgs<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>, U extends keyof T> = T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage[]> ? Extract<V[number], {
+type RuntimeReporterTokensArgs<T extends RuntimeReporterMessages<RuntimeReporterMessage>, U extends keyof T> = T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage> ? Extract<V, {
     code: U;
 }>["tokens"] extends infer Tokens ? Tokens extends readonly string[] ? [tokens: Record<Tokens[number], RuntimeReporterToken>] : [] : [] : never;
 /**
  * The runtime report object with all of it's associated methods; the result
- * of the primary export: `createRuntimeReporter`
+ * of the primary export: `createReporter`
  * @private
  */
-interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>> {
+interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>> {
     /**
      * Retrieves the full text of the targeted message
      *
@@ -47,8 +52,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
      * Logs a warning to the console with the full text of the targeted message in non-production environments
      *
      * _Note: This method will only log when the message associated with the code is found;
-     * meaning it will not be called in production if the `createRuntimeReporter` function
-     * is provided an empty array._
+     * meaning it will not be called in production if the `createReporter` function
+     * is provided an empty message set._
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -57,8 +62,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
      * Logs an error to the console with the full text of the targeted message in non-production environments
      *
      * _Note: This method will only log when the message associated with the code is found;
-     * meaning it will not be called in production if the `createRuntimeReporter` function
-     * is provided an empty array._
+     * meaning it will not be called in production if the `createReporter` function
+     * is provided an empty message set._
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -67,8 +72,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
      * Logs a message to the console with the full text of the targeted message in non-production environments
      *
      * _Note: This method will only log when the message associated with the code is found;
-     * meaning it will not be called in production if the `createRuntimeReporter` function
-     * is provided an empty array._
+     * meaning it will not be called in production if the `createReporter` function
+     * is provided an empty message set._
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -76,8 +81,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
     /**
      * Throws an error with the full text of the targeted message in all environments
      *
-     * _Note: When the `createRuntimeReporter` function is called in production with an empty
-     * array, this method will use the "defaultTemplate" option in this format: "<defaultTemplate> (<code>)"_
+     * _Note: When the `createReporter` function is called in production with an empty
+     * message set, this method will use the "defaultTemplate" option in this format: "<defaultTemplate> (<code>)"_
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -85,7 +90,7 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
 }
 interface RuntimeReporterOptions {
     /**
-     * A hook to format the message text univerally. By default, it
+     * A hook to format the message text universally. By default, it
      * outputs the message in the following format: "<message> (<code>)"
      * @param message The resolved message text; the placeholders have been replaced by their token values
      * @param code The unique code associated with the message
@@ -97,7 +102,7 @@ interface RuntimeReporterOptions {
      * have an associated message. Defaults to "An error occurred"
      *
      * _Note: This is only used when the `fail` method is called in production
-     * environments when the `createRuntimeReporter` function is provided an empty array._
+     * environments when the `createReporter` function is provided an empty message set._
      */
     defaultTemplate?: string;
 }
@@ -107,6 +112,6 @@ interface RuntimeReporterOptions {
  * @param options Optional configuration options
  * @returns A runtime report object
  */
-declare function createRuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>>(messages: T, options?: RuntimeReporterOptions): RuntimeReporter<T>;
+declare function createReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>>(messages: T, options?: RuntimeReporterOptions): RuntimeReporter<T>;
 
-export { type RuntimeReporterMessage, type RuntimeReporterMessages, type RuntimeReporterOptions, type RuntimeReporterToken, createRuntimeReporter };
+export { type RuntimeReporterMessage, type RuntimeReporterMessages, type RuntimeReporterOptions, type RuntimeReporterToken, type RuntimeReporterTokens, createReporter };

package/dist/index.d.ts

@@ -11,8 +11,8 @@ type RuntimeReporterMessage = {
  * The type for a full list of messages with their associated code and template
  * @since v0.1.0
  */
-type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {
-    [K in T[number]["code"]]: Extract<T[number], {
+type RuntimeReporterMessages<T extends RuntimeReporterMessage> = {
+    [K in T["code"]]: Extract<T, {
         code: K;
     }>["template"];
 };
@@ -21,19 +21,24 @@ type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {
  * @since v0.1.0
  */
 type RuntimeReporterToken = string | number | boolean | Error | null | undefined;
+/**
+ * The type for a record of placeholder token names and their values
+ * @since v0.2.0
+ */
+type RuntimeReporterTokens = Record<string, RuntimeReporterToken>;
 /**
  * A utility type used to determine the second argument of the runtime reporter methods
  * @private
  */
-type RuntimeReporterTokensArgs<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>, U extends keyof T> = T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage[]> ? Extract<V[number], {
+type RuntimeReporterTokensArgs<T extends RuntimeReporterMessages<RuntimeReporterMessage>, U extends keyof T> = T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage> ? Extract<V, {
     code: U;
 }>["tokens"] extends infer Tokens ? Tokens extends readonly string[] ? [tokens: Record<Tokens[number], RuntimeReporterToken>] : [] : [] : never;
 /**
  * The runtime report object with all of it's associated methods; the result
- * of the primary export: `createRuntimeReporter`
+ * of the primary export: `createReporter`
  * @private
  */
-interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>> {
+interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>> {
     /**
      * Retrieves the full text of the targeted message
      *
@@ -47,8 +52,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
      * Logs a warning to the console with the full text of the targeted message in non-production environments
      *
      * _Note: This method will only log when the message associated with the code is found;
-     * meaning it will not be called in production if the `createRuntimeReporter` function
-     * is provided an empty array._
+     * meaning it will not be called in production if the `createReporter` function
+     * is provided an empty message set._
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -57,8 +62,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
      * Logs an error to the console with the full text of the targeted message in non-production environments
      *
      * _Note: This method will only log when the message associated with the code is found;
-     * meaning it will not be called in production if the `createRuntimeReporter` function
-     * is provided an empty array._
+     * meaning it will not be called in production if the `createReporter` function
+     * is provided an empty message set._
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -67,8 +72,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
      * Logs a message to the console with the full text of the targeted message in non-production environments
      *
      * _Note: This method will only log when the message associated with the code is found;
-     * meaning it will not be called in production if the `createRuntimeReporter` function
-     * is provided an empty array._
+     * meaning it will not be called in production if the `createReporter` function
+     * is provided an empty message set._
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -76,8 +81,8 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
     /**
      * Throws an error with the full text of the targeted message in all environments
      *
-     * _Note: When the `createRuntimeReporter` function is called in production with an empty
-     * array, this method will use the "defaultTemplate" option in this format: "<defaultTemplate> (<code>)"_
+     * _Note: When the `createReporter` function is called in production with an empty
+     * message set, this method will use the "defaultTemplate" option in this format: "<defaultTemplate> (<code>)"_
      * @param code A direct reference to the unique code for the targeted message
      * @param args The remaining optional argument for the function; a record containing the placeholder token values
      */
@@ -85,7 +90,7 @@ interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessa
 }
 interface RuntimeReporterOptions {
     /**
-     * A hook to format the message text univerally. By default, it
+     * A hook to format the message text universally. By default, it
      * outputs the message in the following format: "<message> (<code>)"
      * @param message The resolved message text; the placeholders have been replaced by their token values
      * @param code The unique code associated with the message
@@ -97,7 +102,7 @@ interface RuntimeReporterOptions {
      * have an associated message. Defaults to "An error occurred"
      *
      * _Note: This is only used when the `fail` method is called in production
-     * environments when the `createRuntimeReporter` function is provided an empty array._
+     * environments when the `createReporter` function is provided an empty message set._
      */
     defaultTemplate?: string;
 }
@@ -107,6 +112,6 @@ interface RuntimeReporterOptions {
  * @param options Optional configuration options
  * @returns A runtime report object
  */
-declare function createRuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>>(messages: T, options?: RuntimeReporterOptions): RuntimeReporter<T>;
+declare function createReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>>(messages: T, options?: RuntimeReporterOptions): RuntimeReporter<T>;
 
-export { type RuntimeReporterMessage, type RuntimeReporterMessages, type RuntimeReporterOptions, type RuntimeReporterToken, createRuntimeReporter };
+export { type RuntimeReporterMessage, type RuntimeReporterMessages, type RuntimeReporterOptions, type RuntimeReporterToken, type RuntimeReporterTokens, createReporter };

package/dist/index.js

@@ -1,17 +1,17 @@
-// index.ts
+// src/index.ts
 var resolveTemplate = function resolveTemplate2(template, tokens) {
   let message = template;
   if (message) {
     Object.entries(tokens || {}).forEach((entry) => {
       const [token, value] = entry;
       const replace = value instanceof Error ? value.message : String(value ?? "");
-      const santized = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      message = message.replace(new RegExp(`\\{\\{\\s*${santized}\\s*\\}\\}`, "g"), replace);
+      const sanitized = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      message = message.replace(new RegExp(`\\{\\{\\s*${sanitized}\\s*\\}\\}`, "g"), replace);
     });
   }
   return message;
 };
-function createRuntimeReporter(messages, options = {}) {
+function createReporter(messages, options = {}) {
   const {
     formatMessage = (message, code) => `${message} (${code})`,
     defaultTemplate = "An error occurred"
@@ -45,6 +45,6 @@ function createRuntimeReporter(messages, options = {}) {
   };
 }
 export {
-  createRuntimeReporter
+  createReporter
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../index.ts"],"sourcesContent":["/**\n * The type information for a single runtime reporter message\n * @since v0.1.0\n */\nexport type RuntimeReporterMessage = {\n    code: string;\n    template: string;\n    tokens?: string[];\n};\n\n/**\n * The type for a full list of messages with their associated code and template\n * @since v0.1.0\n */\nexport type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {\n    [K in T[number][\"code\"]]: Extract<T[number], { code: K }>[\"template\"];\n};\n\n/**\n * The type for the supported values of a placeholder token\n * @since v0.1.0\n */\nexport type RuntimeReporterToken = string | number | boolean | Error | null | undefined;\n\n/**\n * A utility type used to determine the second argument of the runtime reporter methods\n * @private\n */\ntype RuntimeReporterTokensArgs<\n    T extends RuntimeReporterMessages<RuntimeReporterMessage[]>,\n    U extends keyof T,\n> =\n    T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage[]>\n        ? Extract<V[number], { code: U }>[\"tokens\"] extends infer Tokens\n            ? Tokens extends readonly string[]\n                ? [tokens: Record<Tokens[number], RuntimeReporterToken>]\n                : []\n            : []\n        : never;\n\n/**\n * The runtime report object with all of it's associated methods; the result\n * of the primary export: `createRuntimeReporter`\n * @private\n */\ninterface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate an of the raw message text._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    message<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): string;\n\n    /**\n     * Logs a warning to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createRuntimeReporter` function\n     * is provided an empty array._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    warn<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs an error to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createRuntimeReporter` function\n     * is provided an empty array._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    error<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs a message to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createRuntimeReporter` function\n     * is provided an empty array._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    log<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Throws an error with the full text of the targeted message in all environments\n     *\n     * _Note: When the `createRuntimeReporter` function is called in production with an empty\n     * array, this method will use the \"defaultTemplate\" option in this format: \"<defaultTemplate> (<code>)\"_\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    fail<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n}\n\nexport interface RuntimeReporterOptions {\n    /**\n     * A hook to format the message text univerally. By default, it\n     * outputs the message in the following format: \"<message> (<code>)\"\n     * @param message The resolved message text; the placeholders have been replaced by their token values\n     * @param code The unique code associated with the message\n     * @returns The final, fully formatted message\n     */\n    formatMessage?: (message: string, code: string) => string;\n\n    /**\n     * The default template to fallback on when a provided code does not\n     * have an associated message. Defaults to \"An error occurred\"\n     *\n     * _Note: This is only used when the `fail` method is called in production\n     * environments when the `createRuntimeReporter` function is provided an empty array._\n     */\n    defaultTemplate?: string;\n}\n\n/**\n * Resolves the message text via the message template and the associated tokens\n * @param template The template string for the reported message\n * @param tokens The token names and values for the instance\n * @returns The resolved message text; returns an empty string if the template is falsy\n */\nconst resolveTemplate = function resolveTemplate(\n    template: string,\n    tokens?: Record<string, RuntimeReporterToken>\n): string {\n    let message = template;\n\n    if (message) {\n        Object.entries(tokens || {}).forEach((entry) => {\n            const [token, value] = entry;\n            const replace = value instanceof Error ? value.message : String(value ?? \"\");\n            const santized = token.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n            message = message.replace(new RegExp(`\\\\{\\\\{\\\\s*${santized}\\\\s*\\\\}\\\\}`, \"g\"), replace);\n        });\n    }\n\n    return message;\n};\n\n/**\n * Creates a reporter object with various helpful runtime methods\n * @param messages The messages record organized by code and template\n * @param options Optional configuration options\n * @returns A runtime report object\n */\nexport function createRuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>>(\n    messages: T,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n\n    /**\n     * Retrieves the final message for a give code and its associated tokens\n     * @param code The unique code associated with the message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     * @returns The fully resolve message or an empty string if there was no template\n     */\n    const getMessage = function getMessage(\n        code: string,\n        ...args: Array<Record<string, RuntimeReporterToken>>\n    ): string {\n        const template = messages[code] || defaultTemplate;\n        const tokens = args[0];\n        const text = resolveTemplate(template, tokens);\n        return formatMessage(text, code);\n    };\n\n    return {\n        message: (code, ...args) => {\n            return getMessage(code, ...args);\n        },\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.log(message);\n        },\n        fail: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            throw new Error(message);\n        },\n    };\n}\n"],"mappings":";AA6IA,IAAM,kBAAkB,SAASA,iBAC7B,UACA,QACM;AACN,MAAI,UAAU;AAEd,MAAI,SAAS;AACT,WAAO,QAAQ,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU;AAC5C,YAAM,CAAC,OAAO,KAAK,IAAI;AACvB,YAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,SAAS,EAAE;AAC3E,YAAM,WAAW,MAAM,QAAQ,uBAAuB,MAAM;AAC5D,gBAAU,QAAQ,QAAQ,IAAI,OAAO,aAAa,QAAQ,cAAc,GAAG,GAAG,OAAO;AAAA,IACzF,CAAC;AAAA,EACL;AAEA,SAAO;AACX;AAQO,SAAS,sBACZ,UACA,UAAkC,CAAC,GACjB;AAClB,QAAM;AAAA,IACF,gBAAgB,CAAC,SAAS,SAAS,GAAG,OAAO,KAAK,IAAI;AAAA,IACtD,kBAAkB;AAAA,EACtB,IAAI;AAQJ,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,SAAS,IAAI,KAAK;AACnC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SAAS;AACxB,aAAO,WAAW,MAAM,GAAG,IAAI;AAAA,IACnC;AAAA,IACA,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IAC7C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAC5C;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IAC3C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,YAAM,IAAI,MAAM,OAAO;AAAA,IAC3B;AAAA,EACJ;AACJ;","names":["resolveTemplate","getMessage"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * The type information for a single runtime reporter message\n * @since v0.1.0\n */\nexport type RuntimeReporterMessage = {\n    code: string;\n    template: string;\n    tokens?: string[];\n};\n\n/**\n * The type for a full list of messages with their associated code and template\n * @since v0.1.0\n */\nexport type RuntimeReporterMessages<T extends RuntimeReporterMessage> = {\n    [K in T[\"code\"]]: Extract<T, { code: K }>[\"template\"];\n};\n\n/**\n * The type for the supported values of a placeholder token\n * @since v0.1.0\n */\nexport type RuntimeReporterToken = string | number | boolean | Error | null | undefined;\n\n/**\n * The type for a record of placeholder token names and their values\n * @since v0.2.0\n */\nexport type RuntimeReporterTokens = Record<string, RuntimeReporterToken>;\n\n/**\n * A utility type used to determine the second argument of the runtime reporter methods\n * @private\n */\ntype RuntimeReporterTokensArgs<\n    T extends RuntimeReporterMessages<RuntimeReporterMessage>,\n    U extends keyof T,\n> =\n    T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage>\n        ? Extract<V, { code: U }>[\"tokens\"] extends infer Tokens\n            ? Tokens extends readonly string[]\n                ? [tokens: Record<Tokens[number], RuntimeReporterToken>]\n                : []\n            : []\n        : never;\n\n/**\n * The runtime report object with all of it's associated methods; the result\n * of the primary export: `createReporter`\n * @private\n */\ninterface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate an of the raw message text._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    message<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): string;\n\n    /**\n     * Logs a warning to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createReporter` function\n     * is provided an empty message set._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    warn<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs an error to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createReporter` function\n     * is provided an empty message set._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    error<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Logs a message to the console with the full text of the targeted message in non-production environments\n     *\n     * _Note: This method will only log when the message associated with the code is found;\n     * meaning it will not be called in production if the `createReporter` function\n     * is provided an empty message set._\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    log<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n\n    /**\n     * Throws an error with the full text of the targeted message in all environments\n     *\n     * _Note: When the `createReporter` function is called in production with an empty\n     * message set, this method will use the \"defaultTemplate\" option in this format: \"<defaultTemplate> (<code>)\"_\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     */\n    fail<U extends Extract<keyof T, string>>(\n        code: U,\n        ...args: RuntimeReporterTokensArgs<T, U>\n    ): void;\n}\n\nexport interface RuntimeReporterOptions {\n    /**\n     * A hook to format the message text universally. By default, it\n     * outputs the message in the following format: \"<message> (<code>)\"\n     * @param message The resolved message text; the placeholders have been replaced by their token values\n     * @param code The unique code associated with the message\n     * @returns The final, fully formatted message\n     */\n    formatMessage?: (message: string, code: string) => string;\n\n    /**\n     * The default template to fallback on when a provided code does not\n     * have an associated message. Defaults to \"An error occurred\"\n     *\n     * _Note: This is only used when the `fail` method is called in production\n     * environments when the `createReporter` function is provided an empty message set._\n     */\n    defaultTemplate?: string;\n}\n\n/**\n * Resolves the message text via the message template and the associated tokens\n * @param template The template string for the reported message\n * @param tokens The token names and values for the instance\n * @returns The resolved message text; returns an empty string if the template is falsy\n */\nconst resolveTemplate = function resolveTemplate(\n    template: string,\n    tokens?: Record<string, RuntimeReporterToken>\n): string {\n    let message = template;\n\n    if (message) {\n        Object.entries(tokens || {}).forEach((entry) => {\n            const [token, value] = entry;\n            const replace = value instanceof Error ? value.message : String(value ?? \"\");\n            const sanitized = token.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n            message = message.replace(new RegExp(`\\\\{\\\\{\\\\s*${sanitized}\\\\s*\\\\}\\\\}`, \"g\"), replace);\n        });\n    }\n\n    return message;\n};\n\n/**\n * Creates a reporter object with various helpful runtime methods\n * @param messages The messages record organized by code and template\n * @param options Optional configuration options\n * @returns A runtime report object\n */\nexport function createReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage>>(\n    messages: T,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n\n    /**\n     * Retrieves the final message for a give code and its associated tokens\n     * @param code The unique code associated with the message\n     * @param args The remaining optional argument for the function; a record containing the placeholder token values\n     * @returns The fully resolve message or an empty string if there was no template\n     */\n    const getMessage = function getMessage(\n        code: string,\n        ...args: Array<Record<string, RuntimeReporterToken>>\n    ): string {\n        const template = messages[code] || defaultTemplate;\n        const tokens = args[0];\n        const text = resolveTemplate(template, tokens);\n        return formatMessage(text, code);\n    };\n\n    return {\n        message: (code, ...args) => {\n            return getMessage(code, ...args);\n        },\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messages[code]) console.log(message);\n        },\n        fail: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            throw new Error(message);\n        },\n    };\n}\n"],"mappings":";AAmJA,IAAM,kBAAkB,SAASA,iBAC7B,UACA,QACM;AACN,MAAI,UAAU;AAEd,MAAI,SAAS;AACT,WAAO,QAAQ,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU;AAC5C,YAAM,CAAC,OAAO,KAAK,IAAI;AACvB,YAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,SAAS,EAAE;AAC3E,YAAM,YAAY,MAAM,QAAQ,uBAAuB,MAAM;AAC7D,gBAAU,QAAQ,QAAQ,IAAI,OAAO,aAAa,SAAS,cAAc,GAAG,GAAG,OAAO;AAAA,IAC1F,CAAC;AAAA,EACL;AAEA,SAAO;AACX;AAQO,SAAS,eACZ,UACA,UAAkC,CAAC,GACjB;AAClB,QAAM;AAAA,IACF,gBAAgB,CAAC,SAAS,SAAS,GAAG,OAAO,KAAK,IAAI;AAAA,IACtD,kBAAkB;AAAA,EACtB,IAAI;AAQJ,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,SAAS,IAAI,KAAK;AACnC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SAAS;AACxB,aAAO,WAAW,MAAM,GAAG,IAAI;AAAA,IACnC;AAAA,IACA,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IAC7C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAC5C;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAS,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IAC3C;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,YAAM,IAAI,MAAM,OAAO;AAAA,IAC3B;AAAA,EACJ;AACJ;","names":["resolveTemplate","getMessage"]}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "runtime-reporter",
-    "version": "0.1.0",
-    "description": "Runtime messaging that is convenient in development and secure in production",
+    "version": "0.3.0",
+    "description": "Structured runtime events for applications and frameworks. A composable foundation for logging, messaging, and runtime reporting.",
     "type": "module",
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",
@@ -27,7 +27,7 @@
         }
     },
     "scripts": {
-        "build": "tsup index.ts --format cjs,esm --dts --clean --sourcemap",
+        "build": "tsup src/index.ts --format cjs,esm --dts --clean --sourcemap",
         "prepublishOnly": "npm run build",
         "test": "vitest run --coverage",
         "test:watch": "vitest",