runtime-reporter 0.4.0 → 0.4.2

package/README.md

@@ -1,19 +1,116 @@
 # Runtime Reporter
 
-Structured runtime events for applications and frameworks. A composable foundation for logging, messaging, and runtime reporting.
+Structured runtime reporting that is type-safe, centralized, and production-ready — for frameworks and applications
+
+## Why Runtime Reporter?
+
+Most projects eventually accumulate:
+
+- duplicated log messages
+- inconsistent error wording
+- fragile test assertions
+- accidental exposure of sensitive data
+
+Runtime Reporter replaces ad-hoc logging with structured, code-based messaging.
+
+## Who is Runtime Reporter for?
+
+Use Runtime Reporter if:
+
+- you're building a framework or library
+- you want to avoid exposing sensitive information in production
+- you want stable error codes for debugging and tracing runtime behavior
+- you want to avoid bloat from verbose console messages
+- you want a lightweight tool (~2 KB minified) that is easy to use
+- you want to avoid duplicating message text in tests
 
 ## Features
 
-- **Security focused**: Pass an empty message set in production to avoid exposing internal messaging.
-- **Centralized messages**: Define message text once; reference by a unique code everywhere else.
-- **Tokenized templates**: Apply runtime data to messages via templated strings and tokenized variables.
-- **Type-safe**: Autocomplete and compile-time validation for message codes and token names.
-- **Tree-shakeable**: Pass an empty message set in production to reduce your bundle size
-- **Test friendly**: Use `message()` to assert on final output without duplicating message text.
-- **Code-based messaging**: Coded messages make it easy to identify errors to perform debugging tasks.
-- **Small footprint**: Minimal bundle size (~2 KB minified) so it adds negligible weight to your app.
-- **Zero dependencies**: No runtime dependencies; the published package is fully self-contained.
-- **Scalable pattern**: Can scale to fit your specific needs regardless of your project's size.
+If you are new to Runtime Reporter, take a moment to explore the its core features.
+
+### Basic usage
+
+Getting started is easy. Create a reporter instance with your messages and start logging.
+
+```ts
+import { createReporter } from "runtime-reporter";
+
+const reporter = createReporter({
+    ERR01: "MyComponent failed at mount",
+});
+
+reporter.error("ERR01");
+```
+
+### Code-based messaging
+
+Replace inline strings with centralized, code-based identifiers.
+
+```ts
+// Without runtime-reporter (logs "MyComponent failed at mount")
+console.error("MyComponent failed at mount");
+
+// With runtime-reporter (logs "MyComponent failed at mount (ERR01)")
+reporter.error("ERR01");
+```
+
+### Dynamic messages
+
+Inject runtime data into your messages via message templates and tokenized variables.
+
+```ts
+const reporter = createReporter({
+    ERR01: "{{ componentName }} failed at {{ phase }}",
+});
+
+reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" });
+```
+
+### Type safety
+
+Annotate your messages to get autocomplete and compile-time validation for message codes and token names.
+
+```ts
+const messages: RuntimeReporterMessages<{
+    code: "ERR01";
+    template: "{{ componentName }} failed at {{ phase }}";
+    tokens: "componentName" | "phase";
+}> = {
+    ERR01: "{{ componentName }} failed at {{ phase }}",
+};
+
+const reporter = createReporter(messages);
+
+reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" }); // ✅ Autocomplete
+reporter.error("ERR01", { componentName: "MyComponent" }); // ❌ TypeScript Error: "phase" is required
+reporter.error("ERR02", { componentName: "MyComponent", phase: "mount" }); // ❌ TypeScript Error: "ERR02" is not a valid message code
+```
+
+### Production builds
+
+Pass an empty object to the `createReporter` function in production for better security and a smaller bundle size.
+
+```ts
+const reporter = createReporter(
+    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
+);
+```
+
+### Test friendly
+
+Assert against resolved messages without duplicating message text in your test environment.
+
+```ts
+it("should log error if component fails to mount", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+
+    render(<MyComponent />);
+
+    expect(console.error).toHaveBeenCalledWith(
+        reporter.message("ERR01", { componentName: "MyComponent", phase: "mount" })
+    );
+});
+```
 
 ## Installation
 
@@ -21,14 +118,14 @@ Structured runtime events for applications and frameworks. A composable foundati
 npm install runtime-reporter
 ```
 
-## Usage
-
-### 1) Define your messages
+## Quick start
 
-Define your messages by creating an object with the message "schema" (code + template + tokens) and keyed by their codes.
+A copy-and-paste example of how to use Runtime Reporter in your project.
 
 ```ts
-import type { RuntimeReporterMessages } from "runtime-reporter";
+// src/runtime-reporter.ts
+
+import { createReporter, type RuntimeReporterMessages } from "runtime-reporter";
 
 const messages: RuntimeReporterMessages<
     | {
@@ -37,38 +134,34 @@ const messages: RuntimeReporterMessages<
           tokens: "componentName" | "phase";
       }
     | {
-          code: "INFO01";
-          template: "Ready";
+          code: "ERR02";
+          template: "Failed to load configuration";
       }
 > = {
     ERR01: "{{ componentName }} failed at {{ phase }}",
-    INFO01: "Ready",
+    ERR02: "Failed to load configuration",
 };
-```
-
-### 2) Create the reporter
-
-Pass your messages to `createReporter()` to create a reporter instance.
 
-```ts
-import { createReporter } from "runtime-reporter";
+/** The runtime reporter for <project-name> */
+const reporter = createReporter(messages);
 
-export const reporter = createReporter(
-    // Pass an empty object in production for better security and a smaller bundle size
-    process.env.NODE_ENV === "production" ? ({} as typeof messages) : messages
-);
+export default reporter;
 ```
 
-### 3) Use the reporter
-
-Call the various reporter methods wherever you need them.
+Once your project's reporter is created, you can import and use it wherever you need it.
 
 ```ts
-reporter.error("ERR01", { componentName: "Router", phase: "mount" });
-// logs: "Router failed at mount (ERR01)"
+// src/my-component.ts
 
-reporter.message("INFO01");
-// returns: "Ready (INFO01)"
+import { reporter } from "./runtime-reporter";
+
+export function MyComponent() {
+    useEffect(() => {
+        reporter.error("ERR01", { componentName: "MyComponent", phase: "mount" });
+    }, []);
+
+    return <div>My Component</div>;
+}
 ```
 
 ## API
@@ -146,37 +239,20 @@ reporter.error("ERR01", { componentName: "Router", phase: "mount" });
 The `message` method returns the resolved string without side effects, allowing you to validate precise messaging without duplicating text.
 
 ```ts
-import { describe, it, expect, vi } from "vitest";
-import { reporter } from "./reporter";
-
-describe("reporter messages", () => {
-    it("consoles error ERR01 correctly", () => {
-        vi.spyOn(console, "error").mockImplementation(() => {});
-        reporter.error("ERR01", { componentName: "Widget" });
-
-        expect(console.error).toHaveBeenCalledWith(
-            reporter.message("ERR01", { componentName: "Widget" })
-        );
-    });
-});
-```
-
-### Using the reporter without TypeScript
-
-You can use the reporter without TypeScript, you will just lose the type safety and autocomplete.
+it("should log error if component fails to mount", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
 
-```js
-import { createReporter } from "runtime-reporter";
+    render(<MyComponent />);
 
-const reporter = createReporter({
-    ERR01: "{{ componentName }} failed at {{ phase }}",
+    expect(console.error).toHaveBeenCalledWith(
+        reporter.message("ERR01", { componentName: "MyComponent", phase: "mount" })
+    );
 });
-
-reporter.error("ERR01", { componentName: "Router", phase: "mount" });
-// logs: "Router failed at mount (ERR01)"
 ```
 
-However, you can still get the same benefits as TypeScript by using JSDoc-style type annotations.
+### Type safety without TypeScript
+
+You can still get the same benefits as TypeScript by using JSDoc-style type annotations.
 
 ```js
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "runtime-reporter",
-    "version": "0.4.0",
-    "description": "Structured runtime events for applications and frameworks. A composable foundation for logging, messaging, and runtime reporting.",
+    "version": "0.4.2",
+    "description": "Structured runtime reporting that is type-safe, centralized, and production-ready.",
     "type": "module",
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",