runtime-reporter 0.4.1 → 0.4.3

package/README.md

@@ -1,21 +1,121 @@
 # Runtime Reporter
 
-Structured runtime events for applications and frameworks. A composable foundation for logging, messaging, and runtime reporting.
+Structured runtime reporting that is type-safe, centralized, and production-ready — for frameworks and applications
 
-Modern applications often rely on complex logging solutions or ad-hoc messaging systems to understand runtime behavior. These approaches can be difficult to integrate or are tightly coupled to specific environments. Runtime Reporter provides a lightweight, structured runtime event layer designed to simplify logging and messaging while remaining performant, secure, and framework-agnostic.
+## Why Runtime Reporter?
+
+Most projects eventually accumulate:
+
+- duplicated log messages
+- inconsistent error wording
+- fragile test assertions
+- accidental exposure of sensitive data
+
+Runtime Reporter replaces ad-hoc logging with structured, code-based messaging.
+
+## Who is Runtime Reporter for?
+
+Use Runtime Reporter if:
+
+- you're building a framework or library
+- you want to avoid exposing sensitive information in production
+- you want stable error codes for debugging and tracing runtime behavior
+- you want to avoid bloat from verbose console messages
+- you want a lightweight tool (~2 KB minified) that is easy to use
+- you want to avoid duplicating message text in tests
 
 ## Features
 
-- **Centralized messages**: Define message text once and reference it everywhere using stable message codes.
-- **Code-based messaging**: Structured message identifiers make debugging and tracing runtime behavior easier.
-- **Security conscious**: Prevent accidental exposure of sensitive data by omitting message definitions in production.
-- **Type-safe**: Autocomplete and compile-time validation for message codes and template tokens.
-- **Tokenized templates**: Inject runtime data using structured, reusable message templates.
-- **Test friendly**: Assert against resolved messages without duplicating message text in tests.
-- **Tree-shakeable**: Ship an empty message set in production to minimize bundle size.
-- **Small footprint**: ~2 KB minified with negligible runtime overhead.
-- **Zero dependencies**: Fully self-contained with no runtime dependencies.
-- **Scales with your application**: Works equally well for small projects and large frameworks.
+If you are new to Runtime Reporter, take a moment to explore the its core features.
+
+### Basic usage
+
+Getting started is easy. Create a reporter instance with your messages and start logging.
+
+```ts
+import { createReporter } from "runtime-reporter";
+
+const reporter = createReporter({
+    ERR01: "MyComponent failed to mount",
+});
+
+reporter.error("ERR01");
+```
+
+### Code-based messaging
+
+Replace inline strings with centralized, code-based identifiers.
+
+```ts
+// Without runtime-reporter (logs "MyComponent failed to mount")
+console.error("MyComponent failed to mount");
+
+// With runtime-reporter (logs "MyComponent failed to mount (ERR01)")
+reporter.error("ERR01");
+```
+
+### Dynamic messages
+
+Inject runtime data into your messages via message templates and tokenized variables.
+
+```ts
+const reporter = createReporter({
+    ERR01: "{{ componentName }} failed at {{ phase }}",
+});
+
+reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" });
+```
+
+### Type safety
+
+Annotate your messages to get autocomplete and compile-time validation for message codes and token names.
+
+```ts
+const messages: RuntimeReporterMessages<{
+    code: "ERR01";
+    template: "{{ componentName }} failed to mount";
+    tokens: "componentName";
+}> = {
+    ERR01: "{{ componentName }} failed to mount",
+};
+
+const reporter = createReporter(messages);
+
+// ✅ Autocomplete
+reporter.error("ERR01", { componentName: "MyComponent" });
+
+// ❌ TypeScript Error: "ERR02" is not a valid message code
+reporter.error("ERR02", { componentName: "MyComponent" });
+
+// ❌ TypeScript Error: "componentName" token is required
+reporter.error("ERR01");
+```
+
+### Production environments
+
+Pass an empty object to the `createReporter` function in production environments for better security and a smaller bundle size.
+
+```ts
+const reporter = createReporter(
+    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
+);
+```
+
+### Test friendly
+
+Assert against resolved messages without duplicating message text in your test environment.
+
+```ts
+it("should log error if component fails to mount", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+
+    render(<MyComponent />);
+
+    expect(console.error).toHaveBeenCalledWith(
+        reporter.message("ERR01", { componentName: "MyComponent" })
+    );
+});
+```
 
 ## Installation
 
@@ -23,54 +123,56 @@ Modern applications often rely on complex logging solutions or ad-hoc messaging
 npm install runtime-reporter
 ```
 
-## Usage
-
-### 1) Define your messages
+## Quick start
 
-Define your messages by creating an object with the message "schema" (code + template + tokens) and keyed by their codes.
+A copy-and-paste example of how to use Runtime Reporter in your project.
 
 ```ts
-import type { RuntimeReporterMessages } from "runtime-reporter";
+// src/runtime-reporter.ts
+
+import { createReporter, type RuntimeReporterMessages } from "runtime-reporter";
 
 const messages: RuntimeReporterMessages<
     | {
           code: "ERR01";
-          template: "{{ componentName }} failed at {{ phase }}";
-          tokens: "componentName" | "phase";
+          template: "{{ componentName }} failed to mount";
+          tokens: "componentName";
+      }
+    | {
+          code: "ERR02";
+          template: "Failed to load configuration";
       }
     | {
-          code: "INFO01";
-          template: "Ready";
+          code: "ERR03";
+          template: "Failed to fetch {{ resource }} from {{ url }}";
+          tokens: "resource" | "url";
       }
 > = {
-    ERR01: "{{ componentName }} failed at {{ phase }}",
-    INFO01: "Ready",
+    ERR01: "{{ componentName }} failed to mount",
+    ERR02: "Failed to load configuration",
+    ERR03: "Failed to fetch {{ resource }} from {{ url }}",
 };
-```
 
-### 2) Create the reporter
+/** The runtime reporter for <project-name> */
+const reporter = createReporter(messages);
 
-Pass your messages to `createReporter()` to create a reporter instance.
-
-```ts
-import { createReporter } from "runtime-reporter";
-
-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) Use the reporter
-
-Call the various reporter methods wherever you need them.
+Once your project's reporter is created, you can import and use it wherever you need it like this:
 
 ```ts
-reporter.error("ERR01", { componentName: "Router", phase: "mount" });
-// logs: "Router failed at mount (ERR01)"
+// src/my-component.ts
+
+import { reporter } from "./runtime-reporter";
 
-reporter.message("INFO01");
-// returns: "Ready (INFO01)"
+export function MyComponent() {
+    useEffect(() => {
+        reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" });
+    }, []);
+
+    return <div>My Component</div>;
+}
 ```
 
 ## API
@@ -113,17 +215,16 @@ const reporter = createReporter(messages, {
     formatMessage: (msg, code) => `[${code}] ${msg}`,
 });
 
-reporter.message("INFO01");
-// "[INFO01] Ready"
+reporter.message("ERR01", { componentName: "MyComponent" });
+// "[ERR01] MyComponent failed to mount"
 ```
 
-### Using the reporter in production
+### Calling `fail()` in production
 
-When the `createReporter` function is called in production with an empty message set, the `fail` method will use the customizable `defaultTemplate` option which defaults to "An error occurred". This message is intended to be generic so that it does not reveal sensitive information about the system, while still providing a code for debugging purposes.
+When the `createReporter` function provided an empty message set in production, the `fail` method will use the customizable `defaultTemplate` option which defaults to "An error occurred". This message is intended to be generic so that it does not reveal sensitive information about the system, while still providing a code for debugging purposes.
 
 ```ts
 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
 );
 
@@ -131,54 +232,25 @@ reporter.fail("ERR01", { componentName: "Router", phase: "mount" });
 // throws: "An error occurred (ERR01)"
 ```
 
-The remaining reporter methods will not log anything in production when the code is missing from the message set.
-
-```ts
-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
-);
-
-reporter.error("ERR01", { componentName: "Router", phase: "mount" });
-// does not log anything
-```
-
 ### 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" })
-        );
-    });
-});
-```
+it("should log error if component fails to mount", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
 
-### Using the reporter without TypeScript
+    render(<MyComponent />);
 
-You can use the reporter without TypeScript, you will just lose the type safety and autocomplete.
-
-```js
-import { createReporter } from "runtime-reporter";
-
-const reporter = createReporter({
-    ERR01: "{{ componentName }} failed at {{ phase }}",
+    expect(console.error).toHaveBeenCalledWith(
+        reporter.message("ERR01", { componentName: "MyComponent", phase: "mount" })
+    );
 });
-
-reporter.error("ERR01", { componentName: "Router", phase: "mount" });
-// logs: "Router failed at mount (ERR01)"
 ```
 
-However, you can still get the same benefits as TypeScript by using JSDoc-style type annotations.
+### Type safety without TypeScript
+
+You can still get the same benefits as TypeScript by using JSDoc-style type annotations.
 
 ```js
 /**

package/dist/index.cjs.map

@@ -1 +1 @@
-{"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 ReporterTokensArgs<T extends RuntimeReporterMessage, U extends T[\"code\"]> = Extract<\n    T,\n    { code: U }\n>[\"tokens\"] extends infer Tokens\n    ? [Tokens] extends [string]\n        ? [tokens: Record<Tokens, RuntimeReporterToken>]\n        : []\n    : [];\n\n/**\n * Return type for message(); displays the template + code in default format on hover.\n * The runtime value is the resolved string (tokens substituted); the type is for DX only.\n * @private\n */\ntype MessageReturnType<T extends RuntimeReporterMessage, U extends T[\"code\"]> =\n    Extract<T, { code: U }> extends { template: infer Template }\n        ? Template extends string\n            ? `${Template} (${U})`\n            : string\n        : string;\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 RuntimeReporterMessage> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Note: As a convenience, the return type will attempt to show the literal type of the template\n     * pattern and code suffix (in the default format) for the message on hover; the actual output may\n     * vary based on the tokens provided and the `formatMessage` option._\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate any 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 T[\"code\"]>(\n        code: U,\n        ...args: ReporterTokensArgs<T, U>\n    ): MessageReturnType<T, U>;\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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 RuntimeReporterMessage>(\n    messages: RuntimeReporterMessages<T>,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n    const messagesByCode = messages as Record<string, string>;\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 = messagesByCode[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            getMessage(code, ...args) as MessageReturnType<T, typeof code & T[\"code\"]>,\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[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;AAoJA,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;AACJ,QAAM,iBAAiB;AAQvB,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,eAAe,IAAI,KAAK;AACzC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SACf,WAAW,MAAM,GAAG,IAAI;AAAA,IAC5B,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IACnD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAClD;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IACjD;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 ReporterTokensArgs<T extends RuntimeReporterMessage, U extends T[\"code\"]> = Extract<\n    T,\n    { code: U }\n>[\"tokens\"] extends infer Tokens\n    ? [Tokens] extends [string]\n        ? [tokens: Record<Tokens, RuntimeReporterToken>]\n        : []\n    : [];\n\n/**\n * Return type for message(); displays the template + code in default format on hover.\n * The runtime value is the resolved string (tokens substituted); the type is for DX only.\n * @private\n */\ntype MessageReturnType<T extends RuntimeReporterMessage, U extends T[\"code\"]> =\n    Extract<T, { code: U }> extends { template: infer Template }\n        ? Template extends string\n            ? `${Template} (${U})`\n            : string\n        : string;\n\n/**\n * The runtime report object with all of it's associated methods;\n * the result of the primary export: `createReporter`\n * @private\n */\ninterface RuntimeReporter<T extends RuntimeReporterMessage> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Note: As a convenience, the return type will attempt to show the literal type of the template\n     * pattern and code suffix (in the default format) for the message on hover; the actual output may\n     * vary based on the tokens provided and the `formatMessage` option._\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate any 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 T[\"code\"]>(\n        code: U,\n        ...args: ReporterTokensArgs<T, U>\n    ): MessageReturnType<T, U>;\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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;\n}\n\n/**\n * The configuration options for createReporter()\n * @since v0.1.0\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 * @private\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 new runtime reporter object with all of it's associated 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 * @since v0.1.0\n */\nexport function createReporter<T extends RuntimeReporterMessage>(\n    messages: RuntimeReporterMessages<T>,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n    const messagesByCode = messages as Record<string, string>;\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 = messagesByCode[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            getMessage(code, ...args) as MessageReturnType<T, typeof code & T[\"code\"]>,\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[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;AAyJA,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;AASO,SAAS,eACZ,UACA,UAAkC,CAAC,GACjB;AAClB,QAAM;AAAA,IACF,gBAAgB,CAAC,SAAS,SAAS,GAAG,OAAO,KAAK,IAAI;AAAA,IACtD,kBAAkB;AAAA,EACtB,IAAI;AACJ,QAAM,iBAAiB;AAQvB,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,eAAe,IAAI,KAAK;AACzC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SACf,WAAW,MAAM,GAAG,IAAI;AAAA,IAC5B,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IACnD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAClD;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IACjD;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

@@ -44,8 +44,8 @@ type MessageReturnType<T extends RuntimeReporterMessage, U extends T["code"]> =
     template: infer Template;
 } ? Template extends string ? `${Template} (${U})` : string : string;
 /**
- * The runtime report object with all of it's associated methods; the result
- * of the primary export: `createReporter`
+ * The runtime report object with all of it's associated methods;
+ * the result of the primary export: `createReporter`
  * @private
  */
 interface RuntimeReporter<T extends RuntimeReporterMessage> {
@@ -102,6 +102,10 @@ interface RuntimeReporter<T extends RuntimeReporterMessage> {
      */
     fail<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
 }
+/**
+ * The configuration options for createReporter()
+ * @since v0.1.0
+ */
 interface RuntimeReporterOptions {
     /**
      * A hook to format the message text universally. By default, it
@@ -121,10 +125,11 @@ interface RuntimeReporterOptions {
     defaultTemplate?: string;
 }
 /**
- * Creates a reporter object with various helpful runtime methods
+ * Creates a new runtime reporter object with all of it's associated methods
  * @param messages The messages record organized by code and template
  * @param options Optional configuration options
  * @returns A runtime report object
+ * @since v0.1.0
  */
 declare function createReporter<T extends RuntimeReporterMessage>(messages: RuntimeReporterMessages<T>, options?: RuntimeReporterOptions): RuntimeReporter<T>;
 

package/dist/index.d.ts

@@ -44,8 +44,8 @@ type MessageReturnType<T extends RuntimeReporterMessage, U extends T["code"]> =
     template: infer Template;
 } ? Template extends string ? `${Template} (${U})` : string : string;
 /**
- * The runtime report object with all of it's associated methods; the result
- * of the primary export: `createReporter`
+ * The runtime report object with all of it's associated methods;
+ * the result of the primary export: `createReporter`
  * @private
  */
 interface RuntimeReporter<T extends RuntimeReporterMessage> {
@@ -102,6 +102,10 @@ interface RuntimeReporter<T extends RuntimeReporterMessage> {
      */
     fail<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
 }
+/**
+ * The configuration options for createReporter()
+ * @since v0.1.0
+ */
 interface RuntimeReporterOptions {
     /**
      * A hook to format the message text universally. By default, it
@@ -121,10 +125,11 @@ interface RuntimeReporterOptions {
     defaultTemplate?: string;
 }
 /**
- * Creates a reporter object with various helpful runtime methods
+ * Creates a new runtime reporter object with all of it's associated methods
  * @param messages The messages record organized by code and template
  * @param options Optional configuration options
  * @returns A runtime report object
+ * @since v0.1.0
  */
 declare function createReporter<T extends RuntimeReporterMessage>(messages: RuntimeReporterMessages<T>, options?: RuntimeReporterOptions): RuntimeReporter<T>;
 

package/dist/index.js.map

@@ -1 +1 @@
-{"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 ReporterTokensArgs<T extends RuntimeReporterMessage, U extends T[\"code\"]> = Extract<\n    T,\n    { code: U }\n>[\"tokens\"] extends infer Tokens\n    ? [Tokens] extends [string]\n        ? [tokens: Record<Tokens, RuntimeReporterToken>]\n        : []\n    : [];\n\n/**\n * Return type for message(); displays the template + code in default format on hover.\n * The runtime value is the resolved string (tokens substituted); the type is for DX only.\n * @private\n */\ntype MessageReturnType<T extends RuntimeReporterMessage, U extends T[\"code\"]> =\n    Extract<T, { code: U }> extends { template: infer Template }\n        ? Template extends string\n            ? `${Template} (${U})`\n            : string\n        : string;\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 RuntimeReporterMessage> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Note: As a convenience, the return type will attempt to show the literal type of the template\n     * pattern and code suffix (in the default format) for the message on hover; the actual output may\n     * vary based on the tokens provided and the `formatMessage` option._\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate any 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 T[\"code\"]>(\n        code: U,\n        ...args: ReporterTokensArgs<T, U>\n    ): MessageReturnType<T, U>;\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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 RuntimeReporterMessage>(\n    messages: RuntimeReporterMessages<T>,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n    const messagesByCode = messages as Record<string, string>;\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 = messagesByCode[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            getMessage(code, ...args) as MessageReturnType<T, typeof code & T[\"code\"]>,\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[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":";AAoJA,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;AACJ,QAAM,iBAAiB;AAQvB,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,eAAe,IAAI,KAAK;AACzC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SACf,WAAW,MAAM,GAAG,IAAI;AAAA,IAC5B,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IACnD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAClD;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IACjD;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 ReporterTokensArgs<T extends RuntimeReporterMessage, U extends T[\"code\"]> = Extract<\n    T,\n    { code: U }\n>[\"tokens\"] extends infer Tokens\n    ? [Tokens] extends [string]\n        ? [tokens: Record<Tokens, RuntimeReporterToken>]\n        : []\n    : [];\n\n/**\n * Return type for message(); displays the template + code in default format on hover.\n * The runtime value is the resolved string (tokens substituted); the type is for DX only.\n * @private\n */\ntype MessageReturnType<T extends RuntimeReporterMessage, U extends T[\"code\"]> =\n    Extract<T, { code: U }> extends { template: infer Template }\n        ? Template extends string\n            ? `${Template} (${U})`\n            : string\n        : string;\n\n/**\n * The runtime report object with all of it's associated methods;\n * the result of the primary export: `createReporter`\n * @private\n */\ninterface RuntimeReporter<T extends RuntimeReporterMessage> {\n    /**\n     * Retrieves the full text of the targeted message\n     *\n     * _Note: As a convenience, the return type will attempt to show the literal type of the template\n     * pattern and code suffix (in the default format) for the message on hover; the actual output may\n     * vary based on the tokens provided and the `formatMessage` option._\n     *\n     * _Tip: This method is particularly useful in the test environment; allowing you\n     * to make precise assertions without having to duplicate any 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 T[\"code\"]>(\n        code: U,\n        ...args: ReporterTokensArgs<T, U>\n    ): MessageReturnType<T, U>;\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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): 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 T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;\n}\n\n/**\n * The configuration options for createReporter()\n * @since v0.1.0\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 * @private\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 new runtime reporter object with all of it's associated 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 * @since v0.1.0\n */\nexport function createReporter<T extends RuntimeReporterMessage>(\n    messages: RuntimeReporterMessages<T>,\n    options: RuntimeReporterOptions = {}\n): RuntimeReporter<T> {\n    const {\n        formatMessage = (message, code) => `${message} (${code})`,\n        defaultTemplate = \"An error occurred\",\n    } = options;\n    const messagesByCode = messages as Record<string, string>;\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 = messagesByCode[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            getMessage(code, ...args) as MessageReturnType<T, typeof code & T[\"code\"]>,\n        error: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (messagesByCode[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":";AAyJA,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;AASO,SAAS,eACZ,UACA,UAAkC,CAAC,GACjB;AAClB,QAAM;AAAA,IACF,gBAAgB,CAAC,SAAS,SAAS,GAAG,OAAO,KAAK,IAAI;AAAA,IACtD,kBAAkB;AAAA,EACtB,IAAI;AACJ,QAAM,iBAAiB;AAQvB,QAAM,aAAa,SAASC,YACxB,SACG,MACG;AACN,UAAM,WAAW,eAAe,IAAI,KAAK;AACzC,UAAM,SAAS,KAAK,CAAC;AACrB,UAAM,OAAO,gBAAgB,UAAU,MAAM;AAC7C,WAAO,cAAc,MAAM,IAAI;AAAA,EACnC;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SACf,WAAW,MAAM,GAAG,IAAI;AAAA,IAC5B,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IACnD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAClD;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IACjD;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.4.1",
-    "description": "Structured runtime events for applications and frameworks. A composable foundation for logging, messaging, and runtime reporting.",
+    "version": "0.4.3",
+    "description": "Structured runtime reporting that is type-safe, centralized, and production-ready.",
     "type": "module",
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",