runtime-reporter 0.4.3 → 0.4.5

package/README.md

@@ -1,36 +1,92 @@
 # Runtime Reporter
 
-Structured runtime reporting that is type-safe, centralized, and production-ready — for frameworks and applications
+Structured runtime reporting that is type-safe, centralized, and production-ready — for front-end frameworks and applications.
 
-## Why Runtime Reporter?
+Runtime Reporter replaces ad-hoc logging with structured, code-based messaging.
+
+## Why?
 
-Most projects eventually accumulate:
+Runtime Reporter solves these problems:
 
 - duplicated log messages
 - inconsistent error wording
 - fragile test assertions
 - accidental exposure of sensitive data
 
-Runtime Reporter replaces ad-hoc logging with structured, code-based messaging.
+by introducing these features:
+
+- centralized and standardized error messaging
+- stable error codes for debugging and error tracking
+- test assertions without string duplication
+- safer production output (no sensitive data exposure)
+
+in a lightweight, self-contained package (less than 1 KB).
+
+## Installation
+
+```bash
+npm install runtime-reporter
+```
 
-## Who is Runtime Reporter for?
+## Quick start
 
-Use Runtime Reporter if:
+A copy-and-paste example of how to use Runtime Reporter in your project.
 
-- you're building a framework or library
-- you want to avoid exposing sensitive information in production
-- you want stable error codes for debugging and tracing runtime behavior
-- you want to avoid bloat from verbose console messages
-- you want a lightweight tool (~2 KB minified) that is easy to use
-- you want to avoid duplicating message text in tests
+```ts
+// src/runtime-reporter.ts
+
+import { createReporter, type RuntimeReporterMessages } from "runtime-reporter";
+
+const messages: RuntimeReporterMessages<
+    | {
+          code: "ERR01";
+          template: "{{ componentName }} failed to mount";
+          tokens: "componentName";
+      }
+    | {
+          code: "ERR02";
+          template: "Failed to load configuration";
+      }
+    | {
+          code: "ERR03";
+          template: "Failed to fetch {{ resource }} from {{ url }}";
+          tokens: "resource" | "url";
+      }
+> = {
+    ERR01: "{{ componentName }} failed to mount",
+    ERR02: "Failed to load configuration",
+    ERR03: "Failed to fetch {{ resource }} from {{ url }}",
+};
+
+/** The runtime reporter for <project-name> */
+const reporter = createReporter(messages);
+
+export default reporter;
+```
+
+Once your reporter is created, import and use it wherever you want:
+
+```ts
+// src/my-component.ts
+
+import { reporter } from "./runtime-reporter";
+
+export function MyComponent() {
+    useEffect(() => {
+        reporter.error("ERR01", { componentName: "MyComponent" });
+    }, []);
+
+    return <div>My Component</div>;
+}
+```
 
 ## Features
 
-If you are new to Runtime Reporter, take a moment to explore the its core features.
+If you are new to Runtime Reporter, take a moment to explore its core features.
 
-### Basic usage
+### 1. Basic usage
 
-Getting started is easy. Create a reporter instance with your messages and start logging.
+Create a reporter instance with your messages and start logging.
 
 ```ts
 import { createReporter } from "runtime-reporter";
@@ -42,7 +98,7 @@ const reporter = createReporter({
 reporter.error("ERR01");
 ```
 
-### Code-based messaging
+### 2. Code-based messaging
 
 Replace inline strings with centralized, code-based identifiers.
 
@@ -54,19 +110,19 @@ console.error("MyComponent failed to mount");
 reporter.error("ERR01");
 ```
 
-### Dynamic messages
+### 3. Dynamic messages
 
 Inject runtime data into your messages via message templates and tokenized variables.
 
 ```ts
 const reporter = createReporter({
-    ERR01: "{{ componentName }} failed at {{ phase }}",
+    ERR01: "{{ componentName }} failed to mount",
 });
 
-reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" });
+reporter.error("ERR01", { componentName: "MyComponent" });
 ```
 
-### Type safety
+### 4. Type safety
 
 Annotate your messages to get autocomplete and compile-time validation for message codes and token names.
 
@@ -91,7 +147,7 @@ reporter.error("ERR02", { componentName: "MyComponent" });
 reporter.error("ERR01");
 ```
 
-### Production environments
+### 5. Production environments
 
 Pass an empty object to the `createReporter` function in production environments for better security and a smaller bundle size.
 
@@ -101,7 +157,7 @@ const reporter = createReporter(
 );
 ```
 
-### Test friendly
+### 6. Test friendly
 
 Assert against resolved messages without duplicating message text in your test environment.
 
@@ -117,69 +173,11 @@ it("should log error if component fails to mount", () => {
 });
 ```
 
-## Installation
-
-```bash
-npm install runtime-reporter
-```
-
-## Quick start
-
-A copy-and-paste example of how to use Runtime Reporter in your project.
-
-```ts
-// src/runtime-reporter.ts
-
-import { createReporter, type RuntimeReporterMessages } from "runtime-reporter";
-
-const messages: RuntimeReporterMessages<
-    | {
-          code: "ERR01";
-          template: "{{ componentName }} failed to mount";
-          tokens: "componentName";
-      }
-    | {
-          code: "ERR02";
-          template: "Failed to load configuration";
-      }
-    | {
-          code: "ERR03";
-          template: "Failed to fetch {{ resource }} from {{ url }}";
-          tokens: "resource" | "url";
-      }
-> = {
-    ERR01: "{{ componentName }} failed to mount",
-    ERR02: "Failed to load configuration",
-    ERR03: "Failed to fetch {{ resource }} from {{ url }}",
-};
-
-/** The runtime reporter for <project-name> */
-const reporter = createReporter(messages);
-
-export default reporter;
-```
-
-Once your project's reporter is created, you can import and use it wherever you need it like this:
-
-```ts
-// src/my-component.ts
-
-import { reporter } from "./runtime-reporter";
-
-export function MyComponent() {
-    useEffect(() => {
-        reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" });
-    }, []);
-
-    return <div>My Component</div>;
-}
-```
-
 ## API
 
 ### `createReporter(RuntimeReporterMessages, options?: RuntimeReporterOptions): RuntimeReporter`
 
-Takes a list of messages, an optional set of configuration options, and returns a reporter object.
+Takes a messages object, an optional set of configuration options, and returns a reporter object.
 
 ### `RuntimeReporter`
 
@@ -228,7 +226,7 @@ const reporter = createReporter(
     process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
 );
 
-reporter.fail("ERR01", { componentName: "Router", phase: "mount" });
+reporter.fail("ERR01", { componentName: "Router" });
 // throws: "An error occurred (ERR01)"
 ```
 
@@ -243,7 +241,7 @@ it("should log error if component fails to mount", () => {
     render(<MyComponent />);
 
     expect(console.error).toHaveBeenCalledWith(
-        reporter.message("ERR01", { componentName: "MyComponent", phase: "mount" })
+        reporter.message("ERR01", { componentName: "MyComponent" })
     );
 });
 ```
@@ -256,16 +254,21 @@ You can still get the same benefits as TypeScript by using JSDoc-style type anno
 /**
  * @type {import("runtime-reporter").RuntimeReporterMessages<{
  *     code: "ERR01";
- *     template: "{{ componentName }} failed at {{ phase }}";
- *     tokens: "componentName" | "phase";
+ *     template: "{{ componentName }} failed to mount";
+ *     tokens: "componentName";
+ * } | {
+ *     code: "ERR02";
+ *     template: "Failed to load configuration";
  * } | {
- *     code: "INFO01";
- *     template: "Ready";
+ *     code: "ERR03";
+ *     template: "Failed to fetch {{ resource }} from {{ url }}";
+ *     tokens: "resource" | "url";
  * }>}
  */
 const messages = {
-    ERR01: "{{ componentName }} failed at {{ phase }}",
-    INFO01: "Ready",
+    ERR01: "{{ componentName }} failed to mount",
+    ERR02: "Failed to load configuration",
+    ERR03: "Failed to fetch {{ resource }} from {{ url }}",
 };
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "runtime-reporter",
-    "version": "0.4.3",
+    "version": "0.4.5",
     "description": "Structured runtime reporting that is type-safe, centralized, and production-ready.",
     "type": "module",
     "main": "./dist/index.cjs",