runtime-reporter 0.5.0 → 0.6.0

package/README.md

@@ -2,24 +2,22 @@
 
 Replace ad-hoc logging with structured, code-based messaging.
 
-Runtime Reporter provides centralized, type-safe reporting that is convenient in development and secure in production.
+Runtime Reporter is an extremely lightweight and self-contained package that provides centralized, type-safe runtime reporting that is convenient in development and secure in production.
 
 ```ts
 // ./src/my-reporter.ts
-
 import { createReporter } from "runtime-reporter";
 
-export const reporter = createReporter({
+export default createReporter({
     ERR01: "Something went wrong",
 });
 
 // ./src/MyComponent.ts
-
-import { reporter } from "./my-reporter";
+import myReporter from "./my-reporter";
 
 export function MyComponent() {
     useEffect(() => {
-        reporter.error("ERR01");
+        myReporter.error("ERR01");
     }, []);
 }
 ```
@@ -40,8 +38,6 @@ by introducing these features:
 - test assertions without string duplication
 - safer production output (no sensitive data exposure)
 
-in a lightweight, self-contained package (less than 1 KB gzipped).
-
 ## Who is this for?
 
 - Front-end frameworks and libraries
@@ -84,7 +80,9 @@ const messages: RuntimeReporterMessages<
 };
 
 /** The runtime reporter for <project-name> */
-const reporter = createReporter(messages);
+const reporter = createReporter(
+    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
+);
 
 export default reporter;
 ```
@@ -120,7 +118,7 @@ reporter.error("ERR01", { componentName: "MyComponent" });
 // ✅ Logs: "MyComponent failed to mount (ERR01)"
 ```
 
-### 3. Development vs. production
+### 3. Production-ready
 
 Pass an empty object to the `createReporter` function in production environments for better security and a smaller bundle size.
 
@@ -203,7 +201,7 @@ reporter.error("ERR01");
 // ✅ Sends a POST request with the following payload:
 // {
 //     code: "ERR01",
-//     message: "MyComponent failed to mount (ERR01)",
+//     message: "MyComponent failed to mount",
 //     level: "error",
 // }
 ```
@@ -228,7 +226,7 @@ Takes a messages object, an optional set of configuration options, and returns a
 
 | 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>)"`.                                                                                     |
+| formatMessage   | `(message: string, code: string) => string`       | No       | Customize the final output of every message. By default, messages are in the format: `"<message> (<code>)"`. This option does not affect the message provided to the `onReport` hook.            |
 | 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. |
 | onReport        | `(payload: RuntimeReporterReportPayload) => void` | No       | A hook to perform custom actions when a report is made via `error`, `warn`, `log`, or `fail`.                                                                                                    |
 
@@ -240,11 +238,11 @@ Takes a messages object, an optional set of configuration options, and returns a
 
 ### `RuntimeReporterReportPayload`
 
-| Property  | Type     | Description                                                                           |
-| --------- | -------- | ------------------------------------------------------------------------------------- | ----- | ------- | --------------------------------- |
-| `code`    | `string` | The unique code associated with the message.                                          |
-| `message` | `string` | The resolved message text; the placeholders have been replaced by their token values. |
-| `level`   | `"error" | "warn"                                                                                | "log" | "fail"` | The severity level of the report. |
+| Property  | Type                                   | Description                                                                                                                                        |
+| --------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code`    | `string`                               | The unique code associated with the message.                                                                                                       |
+| `message` | `string`                               | The resolved message text; the placeholders have been replaced by their token values but, it has not been formatted by the `formatMessage` option. |
+| `level`   | `"error" \| "warn" \| "log" \| "fail"` | The severity level of the report.                                                                                                                  |
 
 ## Examples
 

package/dist/index.cjs

@@ -42,33 +42,40 @@ function createReporter(messages, options = {}) {
     onReport
   } = options;
   const messagesByCode = messages;
-  const getMessage = function getMessage2(code, ...args) {
+  const resolveMessage = function getMessage(code, ...args) {
     const template = messagesByCode[code] || defaultTemplate;
     const tokens = args[0];
-    const text = resolveTemplate(template, tokens);
-    return formatMessage(text, code);
+    return resolveTemplate(template, tokens);
   };
   return {
-    message: (code, ...args) => getMessage(code, ...args),
+    message: (code, ...args) => {
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
+      return formattedMessage;
+    },
     error: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "error" });
-      if (messagesByCode[code]) console.error(message);
+      if (messagesByCode[code]) console.error(formattedMessage);
     },
     warn: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "warn" });
-      if (messagesByCode[code]) console.warn(message);
+      if (messagesByCode[code]) console.warn(formattedMessage);
     },
     log: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "log" });
-      if (messagesByCode[code]) console.log(message);
+      if (messagesByCode[code]) console.log(formattedMessage);
     },
     fail: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "fail" });
-      throw new Error(message);
+      throw new Error(formattedMessage);
     }
   };
 }

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;\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: \"&lt;defaultTemplate> (&lt;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>): never;\n}\n\n/**\n * The payload for the onReport hook\n */\nexport type RuntimeReporterReportPayload = {\n    /**\n     * The unique code associated with the message\n     */\n    code: string;\n\n    /**\n     * The resolved message text; the placeholders have been replaced by their token values\n     */\n    message: string;\n\n    /**\n     * The severity level of the report\n     */\n    level: \"error\" | \"warn\" | \"log\" | \"fail\";\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 that is logged to the console. By default, it\n     * outputs the message in the following format: \"&lt;message> (&lt;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     * A hook to perform custom actions when any of the report methods (minus the\n     * `message` method) are called. This is useful for logging to a remote service,\n     * or for performing other actions based on the report.\n     * @param payload The payload for the report\n     */\n    onReport?: (payload: RuntimeReporterReportPayload) => void;\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        onReport,\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 (onReport) onReport({ code, message, level: \"error\" });\n            if (messagesByCode[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (onReport) onReport({ code, message, level: \"warn\" });\n            if (messagesByCode[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (onReport) onReport({ code, message, level: \"log\" });\n            if (messagesByCode[code]) console.log(message);\n        },\n        fail: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (onReport) onReport({ code, message, level: \"fail\" });\n            throw new Error(message);\n        },\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAqLA,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,IAClB;AAAA,EACJ,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,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,QAAQ,CAAC;AACxD,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IACnD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAClD;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,MAAM,CAAC;AACtD,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IACjD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,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\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 A record containing the placeholder token values for the message\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\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 A record containing the placeholder token values for the message\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\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 A record containing the placeholder token values for the message\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: \"&lt;defaultTemplate> (&lt;code>)\"_\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args A record containing the placeholder token values for the message\n     */\n    fail<U extends T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): never;\n}\n\n/**\n * The payload for the onReport hook\n */\nexport type RuntimeReporterReportPayload = {\n    /**\n     * The unique code associated with the message\n     */\n    code: string;\n\n    /**\n     * The resolved message text; the placeholders have been replaced by their token values\n     * but, it has not been formatted by the `formatMessage` option.\n     */\n    message: string;\n\n    /**\n     * The severity level of the report\n     */\n    level: \"error\" | \"warn\" | \"log\" | \"fail\";\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 that is logged to the console. By default, it\n     * outputs the message in the following format: \"&lt;message> (&lt;code>)\".\n     *\n     * _Note: This option does not affect the message provided to the `onReport` hook._\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    defaultTemplate?: string;\n\n    /**\n     * A hook to perform custom actions when any of the report methods (minus the\n     * `message` method) are called. This is useful for logging to a remote service,\n     * or for performing other actions based on the report.\n     * @param payload The payload for the report\n     */\n    onReport?: (payload: RuntimeReporterReportPayload) => void;\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        onReport,\n    } = options;\n    const messagesByCode = messages as Record<string, string>;\n\n    /**\n     * Retrieves the resolved message text for a given code and its associated tokens\n     * @param code The unique code associated with the message\n     * @param args The record containing the placeholder token values\n     * @returns The fully resolved message\n     */\n    const resolveMessage = 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        return resolveTemplate(template, tokens);\n    };\n\n    return {\n        message: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            return formattedMessage as MessageReturnType<T, typeof code & T[\"code\"]>;\n        },\n        error: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"error\" });\n            if (messagesByCode[code]) console.error(formattedMessage);\n        },\n        warn: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"warn\" });\n            if (messagesByCode[code]) console.warn(formattedMessage);\n        },\n        log: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"log\" });\n            if (messagesByCode[code]) console.log(formattedMessage);\n        },\n        fail: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"fail\" });\n            throw new Error(formattedMessage);\n        },\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAqLA,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,IAClB;AAAA,EACJ,IAAI;AACJ,QAAM,iBAAiB;AAQvB,QAAM,iBAAiB,SAAS,WAC5B,SACG,MACG;AACN,UAAM,WAAW,eAAe,IAAI,KAAK;AACzC,UAAM,SAAS,KAAK,CAAC;AACrB,WAAO,gBAAgB,UAAU,MAAM;AAAA,EAC3C;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SAAS;AACxB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,aAAO;AAAA,IACX;AAAA,IACA,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,QAAQ,CAAC;AACxD,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,gBAAgB;AAAA,IAC5D;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,gBAAgB;AAAA,IAC3D;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,MAAM,CAAC;AACtD,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,gBAAgB;AAAA,IAC1D;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,YAAM,IAAI,MAAM,gBAAgB;AAAA,IACpC;AAAA,EACJ;AACJ;","names":["resolveTemplate"]}

package/dist/index.d.cts

@@ -63,33 +63,33 @@ interface RuntimeReporter<T extends RuntimeReporterMessage> {
      */
     message<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): MessageReturnType<T, U>;
     /**
-     * Logs a warning to the console with the full text of the targeted message in non-production environments
+     * Logs a warning to the console with the full text of the targeted message
      *
      * _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 `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
+     * @param args A record containing the placeholder token values for the message
      */
     warn<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
     /**
-     * Logs an error to the console with the full text of the targeted message in non-production environments
+     * Logs an error to the console with the full text of the targeted message
      *
      * _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 `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
+     * @param args A record containing the placeholder token values for the message
      */
     error<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
     /**
-     * Logs a message to the console with the full text of the targeted message in non-production environments
+     * Logs a message to the console with the full text of the targeted message
      *
      * _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 `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
+     * @param args A record containing the placeholder token values for the message
      */
     log<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
     /**
@@ -98,7 +98,7 @@ interface RuntimeReporter<T extends RuntimeReporterMessage> {
      * _Note: When the `createReporter` function is called in production with an empty
      * message set, this method will use the "defaultTemplate" option in this format: "&lt;defaultTemplate> (&lt;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
+     * @param args A record containing the placeholder token values for the message
      */
     fail<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): never;
 }
@@ -112,6 +112,7 @@ type RuntimeReporterReportPayload = {
     code: string;
     /**
      * The resolved message text; the placeholders have been replaced by their token values
+     * but, it has not been formatted by the `formatMessage` option.
      */
     message: string;
     /**
@@ -126,7 +127,9 @@ type RuntimeReporterReportPayload = {
 interface RuntimeReporterOptions {
     /**
      * A hook to format the message text that is logged to the console. By default, it
-     * outputs the message in the following format: "&lt;message> (&lt;code>)"
+     * outputs the message in the following format: "&lt;message> (&lt;code>)".
+     *
+     * _Note: This option does not affect the message provided to the `onReport` hook._
      * @param message The resolved message text; the placeholders have been replaced by their token values
      * @param code The unique code associated with the message
      * @returns The final, fully formatted message
@@ -135,9 +138,6 @@ interface RuntimeReporterOptions {
     /**
      * The default template to fallback on when a provided code does not
      * 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 `createReporter` function is provided an empty message set._
      */
     defaultTemplate?: string;
     /**

package/dist/index.d.ts

@@ -63,33 +63,33 @@ interface RuntimeReporter<T extends RuntimeReporterMessage> {
      */
     message<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): MessageReturnType<T, U>;
     /**
-     * Logs a warning to the console with the full text of the targeted message in non-production environments
+     * Logs a warning to the console with the full text of the targeted message
      *
      * _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 `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
+     * @param args A record containing the placeholder token values for the message
      */
     warn<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
     /**
-     * Logs an error to the console with the full text of the targeted message in non-production environments
+     * Logs an error to the console with the full text of the targeted message
      *
      * _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 `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
+     * @param args A record containing the placeholder token values for the message
      */
     error<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
     /**
-     * Logs a message to the console with the full text of the targeted message in non-production environments
+     * Logs a message to the console with the full text of the targeted message
      *
      * _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 `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
+     * @param args A record containing the placeholder token values for the message
      */
     log<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): void;
     /**
@@ -98,7 +98,7 @@ interface RuntimeReporter<T extends RuntimeReporterMessage> {
      * _Note: When the `createReporter` function is called in production with an empty
      * message set, this method will use the "defaultTemplate" option in this format: "&lt;defaultTemplate> (&lt;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
+     * @param args A record containing the placeholder token values for the message
      */
     fail<U extends T["code"]>(code: U, ...args: ReporterTokensArgs<T, U>): never;
 }
@@ -112,6 +112,7 @@ type RuntimeReporterReportPayload = {
     code: string;
     /**
      * The resolved message text; the placeholders have been replaced by their token values
+     * but, it has not been formatted by the `formatMessage` option.
      */
     message: string;
     /**
@@ -126,7 +127,9 @@ type RuntimeReporterReportPayload = {
 interface RuntimeReporterOptions {
     /**
      * A hook to format the message text that is logged to the console. By default, it
-     * outputs the message in the following format: "&lt;message> (&lt;code>)"
+     * outputs the message in the following format: "&lt;message> (&lt;code>)".
+     *
+     * _Note: This option does not affect the message provided to the `onReport` hook._
      * @param message The resolved message text; the placeholders have been replaced by their token values
      * @param code The unique code associated with the message
      * @returns The final, fully formatted message
@@ -135,9 +138,6 @@ interface RuntimeReporterOptions {
     /**
      * The default template to fallback on when a provided code does not
      * 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 `createReporter` function is provided an empty message set._
      */
     defaultTemplate?: string;
     /**

package/dist/index.js

@@ -18,33 +18,40 @@ function createReporter(messages, options = {}) {
     onReport
   } = options;
   const messagesByCode = messages;
-  const getMessage = function getMessage2(code, ...args) {
+  const resolveMessage = function getMessage(code, ...args) {
     const template = messagesByCode[code] || defaultTemplate;
     const tokens = args[0];
-    const text = resolveTemplate(template, tokens);
-    return formatMessage(text, code);
+    return resolveTemplate(template, tokens);
   };
   return {
-    message: (code, ...args) => getMessage(code, ...args),
+    message: (code, ...args) => {
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
+      return formattedMessage;
+    },
     error: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "error" });
-      if (messagesByCode[code]) console.error(message);
+      if (messagesByCode[code]) console.error(formattedMessage);
     },
     warn: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "warn" });
-      if (messagesByCode[code]) console.warn(message);
+      if (messagesByCode[code]) console.warn(formattedMessage);
     },
     log: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "log" });
-      if (messagesByCode[code]) console.log(message);
+      if (messagesByCode[code]) console.log(formattedMessage);
     },
     fail: (code, ...args) => {
-      const message = getMessage(code, ...args);
+      const message = resolveMessage(code, ...args);
+      const formattedMessage = formatMessage(message, code);
       if (onReport) onReport({ code, message, level: "fail" });
-      throw new Error(message);
+      throw new Error(formattedMessage);
     }
   };
 }

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;\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: \"&lt;defaultTemplate> (&lt;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>): never;\n}\n\n/**\n * The payload for the onReport hook\n */\nexport type RuntimeReporterReportPayload = {\n    /**\n     * The unique code associated with the message\n     */\n    code: string;\n\n    /**\n     * The resolved message text; the placeholders have been replaced by their token values\n     */\n    message: string;\n\n    /**\n     * The severity level of the report\n     */\n    level: \"error\" | \"warn\" | \"log\" | \"fail\";\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 that is logged to the console. By default, it\n     * outputs the message in the following format: \"&lt;message> (&lt;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     * A hook to perform custom actions when any of the report methods (minus the\n     * `message` method) are called. This is useful for logging to a remote service,\n     * or for performing other actions based on the report.\n     * @param payload The payload for the report\n     */\n    onReport?: (payload: RuntimeReporterReportPayload) => void;\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        onReport,\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 (onReport) onReport({ code, message, level: \"error\" });\n            if (messagesByCode[code]) console.error(message);\n        },\n        warn: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (onReport) onReport({ code, message, level: \"warn\" });\n            if (messagesByCode[code]) console.warn(message);\n        },\n        log: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (onReport) onReport({ code, message, level: \"log\" });\n            if (messagesByCode[code]) console.log(message);\n        },\n        fail: (code, ...args) => {\n            const message = getMessage(code, ...args);\n            if (onReport) onReport({ code, message, level: \"fail\" });\n            throw new Error(message);\n        },\n    };\n}\n"],"mappings":";AAqLA,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,IAClB;AAAA,EACJ,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,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,QAAQ,CAAC;AACxD,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,OAAO;AAAA,IACnD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,OAAO;AAAA,IAClD;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,MAAM,CAAC;AACtD,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,OAAO;AAAA,IACjD;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,WAAW,MAAM,GAAG,IAAI;AACxC,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,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\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 A record containing the placeholder token values for the message\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\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 A record containing the placeholder token values for the message\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\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 A record containing the placeholder token values for the message\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: \"&lt;defaultTemplate> (&lt;code>)\"_\n     * @param code A direct reference to the unique code for the targeted message\n     * @param args A record containing the placeholder token values for the message\n     */\n    fail<U extends T[\"code\"]>(code: U, ...args: ReporterTokensArgs<T, U>): never;\n}\n\n/**\n * The payload for the onReport hook\n */\nexport type RuntimeReporterReportPayload = {\n    /**\n     * The unique code associated with the message\n     */\n    code: string;\n\n    /**\n     * The resolved message text; the placeholders have been replaced by their token values\n     * but, it has not been formatted by the `formatMessage` option.\n     */\n    message: string;\n\n    /**\n     * The severity level of the report\n     */\n    level: \"error\" | \"warn\" | \"log\" | \"fail\";\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 that is logged to the console. By default, it\n     * outputs the message in the following format: \"&lt;message> (&lt;code>)\".\n     *\n     * _Note: This option does not affect the message provided to the `onReport` hook._\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    defaultTemplate?: string;\n\n    /**\n     * A hook to perform custom actions when any of the report methods (minus the\n     * `message` method) are called. This is useful for logging to a remote service,\n     * or for performing other actions based on the report.\n     * @param payload The payload for the report\n     */\n    onReport?: (payload: RuntimeReporterReportPayload) => void;\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        onReport,\n    } = options;\n    const messagesByCode = messages as Record<string, string>;\n\n    /**\n     * Retrieves the resolved message text for a given code and its associated tokens\n     * @param code The unique code associated with the message\n     * @param args The record containing the placeholder token values\n     * @returns The fully resolved message\n     */\n    const resolveMessage = 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        return resolveTemplate(template, tokens);\n    };\n\n    return {\n        message: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            return formattedMessage as MessageReturnType<T, typeof code & T[\"code\"]>;\n        },\n        error: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"error\" });\n            if (messagesByCode[code]) console.error(formattedMessage);\n        },\n        warn: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"warn\" });\n            if (messagesByCode[code]) console.warn(formattedMessage);\n        },\n        log: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"log\" });\n            if (messagesByCode[code]) console.log(formattedMessage);\n        },\n        fail: (code, ...args) => {\n            const message = resolveMessage(code, ...args);\n            const formattedMessage = formatMessage(message, code);\n            if (onReport) onReport({ code, message, level: \"fail\" });\n            throw new Error(formattedMessage);\n        },\n    };\n}\n"],"mappings":";AAqLA,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,IAClB;AAAA,EACJ,IAAI;AACJ,QAAM,iBAAiB;AAQvB,QAAM,iBAAiB,SAAS,WAC5B,SACG,MACG;AACN,UAAM,WAAW,eAAe,IAAI,KAAK;AACzC,UAAM,SAAS,KAAK,CAAC;AACrB,WAAO,gBAAgB,UAAU,MAAM;AAAA,EAC3C;AAEA,SAAO;AAAA,IACH,SAAS,CAAC,SAAS,SAAS;AACxB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,aAAO;AAAA,IACX;AAAA,IACA,OAAO,CAAC,SAAS,SAAS;AACtB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,QAAQ,CAAC;AACxD,UAAI,eAAe,IAAI,EAAG,SAAQ,MAAM,gBAAgB;AAAA,IAC5D;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,UAAI,eAAe,IAAI,EAAG,SAAQ,KAAK,gBAAgB;AAAA,IAC3D;AAAA,IACA,KAAK,CAAC,SAAS,SAAS;AACpB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,MAAM,CAAC;AACtD,UAAI,eAAe,IAAI,EAAG,SAAQ,IAAI,gBAAgB;AAAA,IAC1D;AAAA,IACA,MAAM,CAAC,SAAS,SAAS;AACrB,YAAM,UAAU,eAAe,MAAM,GAAG,IAAI;AAC5C,YAAM,mBAAmB,cAAc,SAAS,IAAI;AACpD,UAAI,SAAU,UAAS,EAAE,MAAM,SAAS,OAAO,OAAO,CAAC;AACvD,YAAM,IAAI,MAAM,gBAAgB;AAAA,IACpC;AAAA,EACJ;AACJ;","names":["resolveTemplate"]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "runtime-reporter",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "Replace ad-hoc logging with structured, code-based messaging",
     "type": "module",
     "main": "./dist/index.cjs",