runtime-reporter 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# Runtime Reporter
+
+Runtime messaging that is convenient in development and secure in production
+A lightweight runtime messaging solution that's helpful in dev, secure in production
+
+### Usage
+
+1. Define your messages
+
+```ts
+import { RuntimeReporterMessages } from "runtime-reporter";
+
+type RuntimeMessages = Array<{
+    code: "ERR01";
+    template: "{{ componentName }} An error occured ...";
+    tokens: ["componentName"];
+}>;
+
+const messages: RuntimeReporterMessages<RuntimeMessages> = {
+    ERR01: "{{ componentName }} An error occured ...",
+};
+```
+
+2. Create the reporter
+
+Create a reporter instance by passing your messages object and optional configuration. In production builds, pass an empty array to enable tree-shaking and remove all message text from your bundle. The optional `scope` parameter prefixes message codes for easier identification (e.g., `MyApp(ERR01)` instead of `(ERR01)`).
+
+```ts
+import { createRuntimeReporter } = 'runtime-reporter';
+
+const reporter = createRuntimeReporter(
+    process.env.NODE_ENV !== 'production' ? messages : ([] as RuntimeMessages)
+);
+
+export default reporter;
+```
+
+3. Call the reporter methods in your project
+
+```js
+import reporter from "../my-runtime-reporter";
+
+reporter.error("ERR01", { componentName: "MyComponent" });
+```

package/dist/index.cjs

@@ -0,0 +1,75 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  createRuntimeReporter: () => createRuntimeReporter
+});
+module.exports = __toCommonJS(index_exports);
+var resolveTemplate = function resolveTemplate2(template, tokens) {
+  let message = template;
+  if (message) {
+    Object.entries(tokens || {}).forEach((entry) => {
+      const [token, value] = entry;
+      const replace = value instanceof Error ? value.message : String(value ?? "");
+      const santized = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      message = message.replace(new RegExp(`\\{\\{\\s*${santized}\\s*\\}\\}`, "g"), replace);
+    });
+  }
+  return message;
+};
+function createRuntimeReporter(messages, options = {}) {
+  const {
+    formatMessage = (message, code) => `${message} (${code})`,
+    defaultTemplate = "An error occurred"
+  } = options;
+  const getMessage = function getMessage2(code, ...args) {
+    const template = messages[code] || defaultTemplate;
+    const tokens = args[0];
+    const text = resolveTemplate(template, tokens);
+    return formatMessage(text, code);
+  };
+  return {
+    message: (code, ...args) => {
+      return getMessage(code, ...args);
+    },
+    error: (code, ...args) => {
+      const message = getMessage(code, ...args);
+      if (messages[code]) console.error(message);
+    },
+    warn: (code, ...args) => {
+      const message = getMessage(code, ...args);
+      if (messages[code]) console.warn(message);
+    },
+    log: (code, ...args) => {
+      const message = getMessage(code, ...args);
+      if (messages[code]) console.log(message);
+    },
+    fail: (code, ...args) => {
+      const message = getMessage(code, ...args);
+      throw new Error(message);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createRuntimeReporter
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

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

package/dist/index.d.cts

@@ -0,0 +1,112 @@
+/**
+ * The type information for a single runtime reporter message
+ * @since v0.1.0
+ */
+type RuntimeReporterMessage = {
+    code: string;
+    template: string;
+    tokens?: string[];
+};
+/**
+ * The type for a full list of messages with their associated code and template
+ * @since v0.1.0
+ */
+type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {
+    [K in T[number]["code"]]: Extract<T[number], {
+        code: K;
+    }>["template"];
+};
+/**
+ * The type for the supported values of a placeholder token
+ * @since v0.1.0
+ */
+type RuntimeReporterToken = string | number | boolean | Error | null | undefined;
+/**
+ * A utility type used to determine the second argument of the runtime reporter methods
+ * @private
+ */
+type RuntimeReporterTokensArgs<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>, U extends keyof T> = T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage[]> ? Extract<V[number], {
+    code: U;
+}>["tokens"] extends infer Tokens ? Tokens extends readonly string[] ? [tokens: Record<Tokens[number], RuntimeReporterToken>] : [] : [] : never;
+/**
+ * The runtime report object with all of it's associated methods; the result
+ * of the primary export: `createRuntimeReporter`
+ * @private
+ */
+interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>> {
+    /**
+     * Retrieves the full text of the targeted message
+     *
+     * _Tip: This method is particularly useful in the test environment; allowing you
+     * to make precise assertions without having to duplicate an of the raw message text._
+     * @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
+     */
+    message<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): string;
+    /**
+     * Logs a warning to the console with the full text of the targeted message in non-production environments
+     *
+     * _Note: This method will only log when the message associated with the code is found;
+     * meaning it will not be called in production if the `createRuntimeReporter` function
+     * is provided an empty array._
+     * @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
+     */
+    warn<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+    /**
+     * Logs an error to the console with the full text of the targeted message in non-production environments
+     *
+     * _Note: This method will only log when the message associated with the code is found;
+     * meaning it will not be called in production if the `createRuntimeReporter` function
+     * is provided an empty array._
+     * @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
+     */
+    error<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+    /**
+     * Logs a message to the console with the full text of the targeted message in non-production environments
+     *
+     * _Note: This method will only log when the message associated with the code is found;
+     * meaning it will not be called in production if the `createRuntimeReporter` function
+     * is provided an empty array._
+     * @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
+     */
+    log<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+    /**
+     * Throws an error with the full text of the targeted message in all environments
+     *
+     * _Note: When the `createRuntimeReporter` function is called in production with an empty
+     * array, this method will use the "defaultTemplate" option in this format: "<defaultTemplate> (<code>)"_
+     * @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
+     */
+    fail<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+}
+interface RuntimeReporterOptions {
+    /**
+     * A hook to format the message text univerally. By default, it
+     * outputs the message in the following format: "<message> (<code>)"
+     * @param message The resolved message text; the placeholders have been replaced by their token values
+     * @param code The unique code associated with the message
+     * @returns The final, fully formatted message
+     */
+    formatMessage?: (message: string, code: string) => string;
+    /**
+     * 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 `createRuntimeReporter` function is provided an empty array._
+     */
+    defaultTemplate?: string;
+}
+/**
+ * Creates a reporter object with various helpful runtime methods
+ * @param messages The messages record organized by code and template
+ * @param options Optional configuration options
+ * @returns A runtime report object
+ */
+declare function createRuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>>(messages: T, options?: RuntimeReporterOptions): RuntimeReporter<T>;
+
+export { type RuntimeReporterMessage, type RuntimeReporterMessages, type RuntimeReporterOptions, type RuntimeReporterToken, createRuntimeReporter };

package/dist/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The type information for a single runtime reporter message
+ * @since v0.1.0
+ */
+type RuntimeReporterMessage = {
+    code: string;
+    template: string;
+    tokens?: string[];
+};
+/**
+ * The type for a full list of messages with their associated code and template
+ * @since v0.1.0
+ */
+type RuntimeReporterMessages<T extends RuntimeReporterMessage[]> = {
+    [K in T[number]["code"]]: Extract<T[number], {
+        code: K;
+    }>["template"];
+};
+/**
+ * The type for the supported values of a placeholder token
+ * @since v0.1.0
+ */
+type RuntimeReporterToken = string | number | boolean | Error | null | undefined;
+/**
+ * A utility type used to determine the second argument of the runtime reporter methods
+ * @private
+ */
+type RuntimeReporterTokensArgs<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>, U extends keyof T> = T extends RuntimeReporterMessages<infer V extends RuntimeReporterMessage[]> ? Extract<V[number], {
+    code: U;
+}>["tokens"] extends infer Tokens ? Tokens extends readonly string[] ? [tokens: Record<Tokens[number], RuntimeReporterToken>] : [] : [] : never;
+/**
+ * The runtime report object with all of it's associated methods; the result
+ * of the primary export: `createRuntimeReporter`
+ * @private
+ */
+interface RuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>> {
+    /**
+     * Retrieves the full text of the targeted message
+     *
+     * _Tip: This method is particularly useful in the test environment; allowing you
+     * to make precise assertions without having to duplicate an of the raw message text._
+     * @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
+     */
+    message<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): string;
+    /**
+     * Logs a warning to the console with the full text of the targeted message in non-production environments
+     *
+     * _Note: This method will only log when the message associated with the code is found;
+     * meaning it will not be called in production if the `createRuntimeReporter` function
+     * is provided an empty array._
+     * @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
+     */
+    warn<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+    /**
+     * Logs an error to the console with the full text of the targeted message in non-production environments
+     *
+     * _Note: This method will only log when the message associated with the code is found;
+     * meaning it will not be called in production if the `createRuntimeReporter` function
+     * is provided an empty array._
+     * @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
+     */
+    error<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+    /**
+     * Logs a message to the console with the full text of the targeted message in non-production environments
+     *
+     * _Note: This method will only log when the message associated with the code is found;
+     * meaning it will not be called in production if the `createRuntimeReporter` function
+     * is provided an empty array._
+     * @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
+     */
+    log<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+    /**
+     * Throws an error with the full text of the targeted message in all environments
+     *
+     * _Note: When the `createRuntimeReporter` function is called in production with an empty
+     * array, this method will use the "defaultTemplate" option in this format: "<defaultTemplate> (<code>)"_
+     * @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
+     */
+    fail<U extends Extract<keyof T, string>>(code: U, ...args: RuntimeReporterTokensArgs<T, U>): void;
+}
+interface RuntimeReporterOptions {
+    /**
+     * A hook to format the message text univerally. By default, it
+     * outputs the message in the following format: "<message> (<code>)"
+     * @param message The resolved message text; the placeholders have been replaced by their token values
+     * @param code The unique code associated with the message
+     * @returns The final, fully formatted message
+     */
+    formatMessage?: (message: string, code: string) => string;
+    /**
+     * 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 `createRuntimeReporter` function is provided an empty array._
+     */
+    defaultTemplate?: string;
+}
+/**
+ * Creates a reporter object with various helpful runtime methods
+ * @param messages The messages record organized by code and template
+ * @param options Optional configuration options
+ * @returns A runtime report object
+ */
+declare function createRuntimeReporter<T extends RuntimeReporterMessages<RuntimeReporterMessage[]>>(messages: T, options?: RuntimeReporterOptions): RuntimeReporter<T>;
+
+export { type RuntimeReporterMessage, type RuntimeReporterMessages, type RuntimeReporterOptions, type RuntimeReporterToken, createRuntimeReporter };

package/dist/index.js

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

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,91 @@
+{
+    "name": "runtime-reporter",
+    "version": "0.1.0",
+    "description": "Runtime messaging that is convenient in development and secure in production",
+    "type": "module",
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./dist/index.d.ts",
+                "default": "./dist/index.js"
+            },
+            "require": {
+                "types": "./dist/index.d.cts",
+                "default": "./dist/index.cjs"
+            }
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "config": {
+        "commitizen": {
+            "path": "cz-conventional-changelog"
+        }
+    },
+    "scripts": {
+        "build": "tsup index.ts --format cjs,esm --dts --clean --sourcemap",
+        "prepublishOnly": "npm run build",
+        "test": "vitest run --coverage",
+        "test:watch": "vitest",
+        "lint": "eslint . --format eslint-formatter-compact",
+        "lint:fix": "eslint . --fix --format eslint-formatter-compact",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "commit": "cz",
+        "release": "release-it",
+        "prepare": "husky"
+    },
+    "lint-staged": {
+        "*.ts": [
+            "eslint --fix",
+            "prettier --write"
+        ]
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/marksmccann/runtime-reporter.git"
+    },
+    "keywords": [
+        "runtime",
+        "reporter",
+        "messaging",
+        "console",
+        "error handling"
+    ],
+    "author": {
+        "name": "Mark McCann",
+        "email": "marksmccann@gmail.com"
+    },
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/marksmccann/runtime-reporter/issues"
+    },
+    "homepage": "https://github.com/marksmccann/runtime-reporter#readme",
+    "devDependencies": {
+        "@commitlint/cli": "^20.4.2",
+        "@commitlint/config-conventional": "^20.4.2",
+        "@eslint/js": "^10.0.1",
+        "@release-it/conventional-changelog": "^10.0.5",
+        "@typescript-eslint/eslint-plugin": "^8.56.0",
+        "@typescript-eslint/parser": "^8.56.0",
+        "@vitest/coverage-v8": "^4.0.18",
+        "commitizen": "^4.3.1",
+        "cz-conventional-changelog": "^3.3.0",
+        "eslint": "^10.0.1",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-formatter-compact": "^9.0.1",
+        "eslint-plugin-prettier": "^5.5.5",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.2.7",
+        "prettier": "^3.8.1",
+        "release-it": "^19.2.4",
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.56.0",
+        "vitest": "^4.0.18"
+    }
+}