voltlog-io 1.0.1 → 1.0.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Rohit Tiwari
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Rohit Tiwari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,65 +1,343 @@
-# VoltLog
-
-#### Structured logger for real-time infrastructure
-
-[![npm version](https://img.shields.io/npm/v/voltlog-io?color=blue)](https://www.npmjs.com/package/voltlog-io)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build & Test](https://github.com/rohittiwari-dev/voltlog-io/actions/workflows/ci.yml/badge.svg)](https://github.com/rohittiwari-dev/voltlog-io/actions)
-
-**VoltLog** is a modern, lightweight, and type-safe structured logger designed specifically for high-throughput, real-time systems like IoT platforms, WebSocket servers (OCPP), and microservices.
-
-## 📚 Full Documentation
-
-For detailed guides, API reference, and advanced usage, please visit:
-
-### [👉 https://ocpp-ws-io.rohittiwari.me/docs/voltlog-io](https://ocpp-ws-io.rohittiwari.me/docs/voltlog-io)
-
----
-
-## ✨ Key Features
-
-- **🚀 Zero-Dependency Core**: Lightweight and fast.
-- **🔒 Secure**: Built-in redaction for sensitive data.
-- **📊 High-Throughput**: Intelligent sampling for cost control.
-- **⚡ Developer Friendly**: Beautiful pretty printing for local dev.
-- **🔌 Flexible**: Works in Node.js, Bun, Deno, and Browsers.
-
-## 📦 Installation
-
-```bash
-npm install voltlog-io
-```
-
-## 🚀 Quick Start
-
-```ts
-import { createLogger, consoleTransport } from "voltlog-io";
-
-const logger = createLogger({
-  level: "INFO",
-  transports: [consoleTransport()],
-});
-
-logger.info("Server started", { port: 3000, env: "production" });
-```
-
-### Local Development
-
-For readable, colored logs during development:
-
-```ts
-import { createLogger, prettyTransport } from "voltlog-io";
-
-const logger = createLogger({
-  level: "DEBUG",
-  transports: [prettyTransport({ colorize: true })],
-});
-```
-
-## 🤝 Contributing
-
-Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md).
-
-## License
-
-[MIT](LICENSE) © [Rohit Tiwari](https://github.com/rohittiwari-dev)
+# VoltLog
+
+#### Structured logger for real-time infrastructure — zero dependencies, type-safe, OCPP-aware
+
+[![npm version](https://img.shields.io/npm/v/voltlog-io?color=blue)](https://www.npmjs.com/package/voltlog-io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build & Test](https://github.com/rohittiwari-dev/voltlog-io/actions/workflows/ci.yml/badge.svg)](https://github.com/rohittiwari-dev/voltlog-io/actions)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/voltlog-io)
+
+**VoltLog** is a modern, lightweight, and type-safe structured logger designed for high-throughput, real-time systems like IoT platforms, WebSocket servers (OCPP), and microservices.
+
+## 📚 Full Documentation
+
+For detailed guides, API reference, and advanced usage:
+
+### [👉 https://ocpp-ws-io.rohittiwari.me/docs/voltlog-io](https://ocpp-ws-io.rohittiwari.me/docs/voltlog-io)
+
+---
+
+## ✨ Why VoltLog?
+
+| Feature                   | Pino         | Winston       | VoltLog       |
+| ------------------------- | ------------ | ------------- | ------------- |
+| Zero dependencies         | ❌ (11 deps) | ❌ (10+ deps) | ✅ **0 deps** |
+| Type-safe generics        | ❌           | ❌            | ✅            |
+| Middleware pipeline       | ❌           | ❌            | ✅            |
+| Built-in redaction        | Plugin       | ❌            | ✅            |
+| Sampling / rate-limit     | ❌           | ❌            | ✅            |
+| Alert rules               | ❌           | ❌            | ✅            |
+| Error cause chain         | ❌           | ❌            | ✅            |
+| Ring buffer               | ❌           | ❌            | ✅            |
+| OCPP-aware                | ❌           | ❌            | ✅            |
+| OpenTelemetry             | Plugin       | Plugin        | ✅ Built-in   |
+| File rotation (date+size) | Plugin       | Plugin        | ✅ Built-in   |
+| HTTP request logging      | Plugin       | Plugin        | ✅ Built-in   |
+| AsyncLocalStorage context | ❌           | ❌            | ✅ Built-in   |
+
+## 📦 Installation
+
+```bash
+npm install voltlog-io
+```
+
+## 🚀 Quick Start
+
+```ts
+import { createLogger, prettyTransport, consoleTransport } from "voltlog-io";
+
+// Development — pretty colored output
+const logger = createLogger({
+  level: "DEBUG",
+  transports: [prettyTransport()],
+});
+
+// Production — structured JSON
+const logger = createLogger({
+  level: "INFO",
+  transports: [consoleTransport()],
+});
+
+logger.info("Server started", { port: 3000, env: "production" });
+logger.error("Connection failed", new Error("ETIMEDOUT"));
+```
+
+## 📖 Features
+
+### Core Logging
+
+```ts
+// All log levels
+logger.trace("Entering function");
+logger.debug("Parsed payload", { bytes: 1024 });
+logger.info("User authenticated", { userId: "u-42" });
+logger.warn("Rate limit approaching", { rate: 95 });
+logger.error("Query failed", { query: "SELECT *" }, new Error("timeout"));
+logger.fatal("Unrecoverable", new Error("OOM"));
+
+// Runtime level control
+logger.setLevel("WARN"); // change at runtime
+logger.getLevel(); // → "WARN"
+logger.isLevelEnabled("DEBUG"); // → false (useful to guard expensive computation)
+
+// Timer helper — auto-logs duration
+const timer = logger.startTimer();
+await doExpensiveWork();
+timer.done("Work completed", { items: 100 });
+// → INFO Work completed { durationMs: 342, items: 100 }
+```
+
+### Child Loggers
+
+```ts
+const cpLogger = logger.child({ chargePointId: "CP-101" });
+cpLogger.info("Connected");
+// → context: { chargePointId: "CP-101" }
+
+const sessionLogger = cpLogger.child({ sessionId: "sess-xyz" });
+sessionLogger.info("Charging started");
+// → context: { chargePointId: "CP-101", sessionId: "sess-xyz" }
+```
+
+### Error Cause Chain (ES2022)
+
+```ts
+const rootCause = new Error("ECONNREFUSED 10.0.0.5:5432");
+const dbError = new Error("DB connection failed", { cause: rootCause });
+const appError = new Error("Request failed", { cause: dbError });
+
+logger.error("Handler crashed", appError);
+// → error.cause.cause.message = "ECONNREFUSED 10.0.0.5:5432" ← root cause preserved!
+```
+
+### Custom ID Generator
+
+```ts
+// Default: crypto.randomUUID() (fast, native)
+const logger = createLogger({ transports: [...] });
+
+// Custom generator
+const logger = createLogger({
+  idGenerator: () => `log-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  transports: [...],
+});
+
+// Disable for max performance
+const logger = createLogger({ idGenerator: false, transports: [...] });
+```
+
+---
+
+## 🔌 Transports (14 Built-in)
+
+### Console & Pretty
+
+```ts
+import { consoleTransport, prettyTransport } from "voltlog-io";
+
+consoleTransport(); // JSON to stdout
+prettyTransport({ colors: true, timestamps: true }); // colored dev output
+```
+
+### File (Daily + Size Rotation)
+
+```ts
+import { fileTransport } from "voltlog-io";
+
+fileTransport({
+  dir: "./logs",
+  filename: "app-%DATE%.log", // daily rotation
+  maxSize: 10_000_000, // 10MB size rotation
+});
+// → logs/app-2026-02-28.log → logs/app-2026-02-28.1.log (at 10MB)
+```
+
+### Ring Buffer (In-Memory Diagnostics)
+
+```ts
+import { ringBufferTransport } from "voltlog-io";
+
+const ring = ringBufferTransport({ maxSize: 500 });
+
+// Query buffered logs
+ring.getEntries({ level: "ERROR" });
+ring.getEntries({ since: Date.now() - 300_000, limit: 20 });
+ring.clear();
+```
+
+### Webhook (with Batching & Retry)
+
+```ts
+import { webhookTransport, batchTransport } from "voltlog-io";
+
+batchTransport(
+  webhookTransport({
+    url: "https://api.example.com/logs",
+    headers: { Authorization: "Bearer token" },
+    retry: true,
+    maxRetries: 3,
+  }),
+  { batchSize: 50, flushIntervalMs: 5000 },
+);
+```
+
+### OpenTelemetry (SigNoz, Jaeger, Grafana)
+
+```ts
+import { otelTransport, otelTraceMiddleware } from "voltlog-io";
+
+const logger = createLogger({
+  middleware: [otelTraceMiddleware()], // auto-picks traceId/spanId
+  transports: [
+    otelTransport({
+      endpoint: "https://ingest.signoz.io",
+      headers: { "signoz-access-token": "YOUR_TOKEN" },
+      serviceName: "my-app",
+      resource: { "deployment.environment": "production" },
+    }),
+  ],
+});
+// Every log auto-includes traceId + spanId from active OTel spans
+```
+
+### Loki (Grafana)
+
+```ts
+import { lokiTransport } from "voltlog-io";
+
+lokiTransport({
+  host: "http://loki:3100",
+  labels: { app: "my-service", env: "prod" },
+  dynamicLabels: (entry) => ({ level: entry.levelName }),
+  includeMetadata: true, // context, error, correlationId
+  retry: true,
+  maxRetries: 3,
+});
+```
+
+### Other Transports
+
+```ts
+import {
+  datadogTransport, // Datadog Logs API
+  sentryTransport, // Sentry (errors + breadcrumbs)
+  slackTransport, // Slack webhook
+  discordTransport, // Discord webhook
+  redisTransport, // Redis Streams
+  jsonStreamTransport, // Node.js WritableStream
+  browserJsonStreamTransport, // Browser WritableStream
+} from "voltlog-io";
+```
+
+---
+
+## 🧩 Middleware (13 Built-in)
+
+### Redaction
+
+```ts
+import { redactionMiddleware } from "voltlog-io";
+
+redactionMiddleware({
+  paths: ["password", "idToken", "authorization"],
+  deep: true, // search nested objects
+  replacement: "[REDACTED]",
+});
+```
+
+### AsyncLocalStorage Context
+
+```ts
+import { asyncContextMiddleware } from "voltlog-io";
+
+const asyncCtx = asyncContextMiddleware();
+
+const logger = createLogger({
+  middleware: [asyncCtx.middleware],
+  transports: [prettyTransport()],
+});
+
+// Set context once — propagates across all async boundaries
+app.use((req, res, next) => {
+  asyncCtx.runInContext({ requestId: req.id, userId: req.user?.id }, next);
+});
+
+// Anywhere downstream — no child() needed
+logger.info("Processing order");
+// → auto-includes { requestId, userId }
+```
+
+### Sampling & Rate Limiting
+
+```ts
+import { samplingMiddleware } from "voltlog-io";
+
+samplingMiddleware({
+  maxPerWindow: 10, // max 10 logs per window
+  windowMs: 60_000, // per minute
+  priorityLevel: 40, // WARN+ always passes
+});
+```
+
+### Other Middleware
+
+```ts
+import {
+  correlationIdMiddleware, // auto-generate/propagate correlation IDs
+  alertMiddleware, // trigger alerts on error spikes
+  deduplicationMiddleware, // suppress repeated logs
+  heapUsageMiddleware, // attach memory stats
+  ipMiddleware, // extract client IP
+  userAgentMiddleware, // extract User-Agent
+  levelOverrideMiddleware, // dynamic level via headers
+  ocppMiddleware, // OCPP protocol enrichment
+  otelTraceMiddleware, // OpenTelemetry trace context
+  createHttpLogger, // HTTP request/response logging
+} from "voltlog-io";
+```
+
+---
+
+## ⚡ Performance
+
+```ts
+// Max performance mode — zero overhead for filtered logs
+const logger = createLogger({
+  level: "WARN",
+  idGenerator: false, // no ID generation
+  transports: [consoleTransport()],
+});
+
+// These cost ~0.02μs each (100x faster than Pino for filtered logs)
+logger.trace("free");
+logger.debug("free");
+logger.info("free");
+
+// Only these execute
+logger.warn("logged");
+logger.error("logged");
+```
+
+| Scenario                                  | VoltLog | Pino   |
+| ----------------------------------------- | ------- | ------ |
+| Filtered log (e.g. DEBUG when level=INFO) | ~0.02μs | ~3-5μs |
+| Simple INFO with 1 transport              | ~2-4μs  | ~3-5μs |
+| 3 middleware + 2 transports               | ~8-15μs | N/A    |
+
+## 🛡️ Graceful Shutdown
+
+```ts
+process.on("SIGTERM", async () => {
+  await logger.flush(); // ensure all buffered logs are sent
+  await logger.close(); // release resources (file handles, connections)
+  process.exit(0);
+});
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © [Rohit Tiwari](https://github.com/rohittiwari-dev)