runtime-reporter 0.4.4 → 0.4.6

package/README.md

@@ -1,60 +1,108 @@
 # Runtime Reporter
 
-Structured runtime reporting that is type-safe, centralized, and production-ready — for frameworks and applications
+Replace ad-hoc logging with structured, code-based messaging that is also type-safe, centralized, and production-ready.
 
-## Why Runtime Reporter?
+```ts
+// ./src/runtime-reporter.ts
+
+import { createReporter } from "runtime-reporter";
+
+export const reporter = createReporter({
+    ERR01: "Something went wrong",
+});
 
-Most projects eventually accumulate:
+// ./src/MyComponent.ts
+
+import { reporter } from "./runtime-reporter";
+
+export function MyComponent() {
+    useEffect(() => {
+        reporter.error("ERR01");
+    }, []);
+}
+```
+
+## Why?
+
+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:
 
-## Who is Runtime Reporter for?
+- 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)
 
-Use Runtime Reporter if:
+in a lightweight, self-contained package (less than 1 KB gzipped).
 
-- 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
+## Who is this for?
 
-## Features
+Runtime Reporter is ideal for front-end frameworks and libraries. However, it is ultimately useful for any project looking for standardized console messaging.
 
-If you are new to Runtime Reporter, take a moment to explore the its core features.
+## Installation
 
-### Basic usage
+```bash
+npm install runtime-reporter
+```
+
+## Quick start
 
-Getting started is easy. Create a reporter instance with your messages and start logging.
+A full, copy-and-paste example of how to use Runtime Reporter in your project:
 
 ```ts
-import { createReporter } from "runtime-reporter";
+import { createReporter, type RuntimeReporterMessages } from "runtime-reporter";
 
-const reporter = createReporter({
-    ERR01: "MyComponent failed to mount",
-});
+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 }}",
+};
 
-reporter.error("ERR01");
+/** The runtime reporter for <project-name> */
+const reporter = createReporter(messages);
+
+export default reporter;
 ```
 
-### Code-based messaging
+## Features
+
+If you are new to Runtime Reporter, take a moment to explore its core features.
+
+### 1. Code-based messaging
 
 Replace inline strings with centralized, code-based identifiers.
 
 ```ts
-// Without runtime-reporter (logs "MyComponent failed to mount")
-console.error("MyComponent failed to mount");
+// Without runtime-reporter
+console.log("Something went wrong");
+// ❌ Logs: "Something went wrong"
 
-// With runtime-reporter (logs "MyComponent failed to mount (ERR01)")
-reporter.error("ERR01");
+// With runtime-reporter
+reporter.log("ERR01");
+// ✅ Logs: "Something went wrong (ERR01)"
 ```
 
-### Dynamic messages
+### 2. Dynamic messages
 
 Inject runtime data into your messages via message templates and tokenized variables.
 
@@ -64,9 +112,32 @@ const reporter = createReporter({
 });
 
 reporter.error("ERR01", { componentName: "MyComponent" });
+// Logs: "MyComponent failed to mount (ERR01)"
+```
+
+### 3. Development vs. production
+
+Pass an empty object to the `createReporter` function in production environments for better security and a smaller bundle size.
+
+```ts
+const reporter = createReporter(
+    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
+);
+```
+
+Development environments get detailed messaging, while production environments get as little as possible.
+
+```ts
+reporter.error("ERR01");
+// In development, it logs: "Something went wrong (ERR01)"
+// In production, it does not log
+
+reporter.fail("ERR01");
+// In development, it throws: "Something went wrong (ERR01)"
+// In production, it throws: "An error occurred (ERR01)"
 ```
 
-### Type safety
+### 4. Type safety
 
 Annotate your messages to get autocomplete and compile-time validation for message codes and token names.
 
@@ -91,17 +162,7 @@ reporter.error("ERR02", { componentName: "MyComponent" });
 reporter.error("ERR01");
 ```
 
-### Production environments
-
-Pass an empty object to the `createReporter` function in production environments for better security and a smaller bundle size.
-
-```ts
-const reporter = createReporter(
-    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
-);
-```
-
-### Test friendly
+### 5. Test friendly
 
 Assert against resolved messages without duplicating message text in your test environment.
 
@@ -117,69 +178,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" });
-    }, []);
-
-    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`
 
@@ -268,7 +271,7 @@ You can still get the same benefits as TypeScript by using JSDoc-style type anno
  * }>}
  */
 const messages = {
-    ERR01: "{{ componentName }} failed at {{ phase }}",
+    ERR01: "{{ componentName }} failed to mount",
     ERR02: "Failed to load configuration",
     ERR03: "Failed to fetch {{ resource }} from {{ url }}",
 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "runtime-reporter",
-    "version": "0.4.4",
-    "description": "Structured runtime reporting that is type-safe, centralized, and production-ready.",
+    "version": "0.4.6",
+    "description": "Replace ad-hoc logging with structured, code-based messaging that is also type-safe, centralized, and production-ready",
     "type": "module",
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",