@hardlydifficult/logger 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/logger
 
-Plugin-based structured logger with Console, Discord, and File output plugins.
+Plugin-based structured logger with configurable log levels and extensible output handlers for Console, File, and Discord.
 
 ## Installation
 
@@ -8,97 +8,161 @@ Plugin-based structured logger with Console, Discord, and File output plugins.
 npm install @hardlydifficult/logger
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-import { Logger, ConsolePlugin, FilePlugin, DiscordPlugin } from "@hardlydifficult/logger";
-
-const discord = new DiscordPlugin();
+import { Logger, ConsolePlugin, FilePlugin } from "@hardlydifficult/logger";
 
 const logger = new Logger("info")
   .use(new ConsolePlugin())
-  .use(new FilePlugin("/var/log/app.log"))
-  .use(discord);
-
-// Wire up Discord sender once the bot is ready
-discord.setSender((msg) => channel.send(msg));
+  .use(new FilePlugin("./app.log"));
 
 logger.info("Server started", { port: 3000 });
-logger.warn("High memory usage", { usage: "85%" });
-logger.error("Request failed", { url: "/api/data", status: 500 });
-
-// Out-of-band notification (goes to plugins that support notify)
-logger.notify("Deployment complete");
+// Output to console: [2025-01-15T10:30:00.000Z] INFO: Server started {"port":3000}
+// Output to file: {"level":"info","message":"Server started","timestamp":"2025-01-15T10:30:00.000Z","context":{"port":3000}}
 ```
 
-## API
+## Core Logger
 
-### `Logger`
+The `Logger` class dispatches log entries to registered plugins based on a minimum log level.
 
 ```typescript
-new Logger(minLevel?: LogLevel) // default: "info"
+import { Logger } from "@hardlydifficult/logger";
+
+const logger = new Logger("info"); // default: "info"
 ```
 
+### Log Levels
+
+Log levels in order of severity: `debug` < `info` < `warn` < `error`. Entries below the logger's `minLevel` are filtered out before reaching plugins.
+
+### Methods
+
 | Method | Description |
 |--------|-------------|
-| `use(plugin)` | Register a plugin (returns `this` for chaining) |
+| `use(plugin, options?)` | Register a plugin; returns `this` for chaining. Optional `minLevel` filters entries per-plugin. |
 | `debug(message, context?)` | Log at debug level |
 | `info(message, context?)` | Log at info level |
 | `warn(message, context?)` | Log at warn level |
 | `error(message, context?)` | Log at error level |
 | `notify(message)` | Send out-of-band notification to plugins that support it |
 
-Log levels: `debug` < `info` < `warn` < `error`. Entries below `minLevel` are filtered out.
+### Plugin-Level Filtering
+
+Each plugin can have its own minimum log level, independent of the logger's global level:
+
+```typescript
+const logger = new Logger("debug")
+  .use(new ConsolePlugin()) // receives all levels
+  .use(new FilePlugin("./errors.log"), { minLevel: "error" }); // only errors
+
+logger.debug("This goes to console only");
+logger.error("This goes to both console and file");
+```
+
+## Console Plugin
+
+Outputs formatted log entries to the console, routing to `console.log`, `console.warn`, or `console.error` based on log level.
+
+```typescript
+import { Logger, ConsolePlugin } from "@hardlydifficult/logger";
+
+const logger = new Logger("info").use(new ConsolePlugin());
 
-### Plugins
+logger.info("Server started", { port: 3000 });
+// Output: [2025-01-15T10:30:00.000Z] INFO: Server started {"port":3000}
+```
 
-#### `ConsolePlugin`
+### Format
 
-Logs to `console.log`/`console.warn`/`console.error` with formatted timestamps.
+The `formatEntry` function is also exported for custom formatting:
 
 ```typescript
-new ConsolePlugin()
+import { formatEntry } from "@hardlydifficult/logger";
+
+const entry = {
+  level: "warn",
+  message: "High memory",
+  timestamp: "2025-01-15T10:30:00.000Z",
+  context: { usage: "85%" },
+};
+
+console.log(formatEntry(entry));
+// Output: [2025-01-15T10:30:00.000Z] WARN: High memory {"usage":"85%"}
 ```
 
-#### `FilePlugin`
+## File Plugin
 
-Appends JSON log entries to a file (one entry per line). Creates the directory if needed.
+Appends JSON-serialized log entries to a file (one entry per line, JSONL format). Creates parent directories automatically.
 
 ```typescript
-new FilePlugin(filePath: string)
+import { Logger, FilePlugin } from "@hardlydifficult/logger";
+
+const logger = new Logger("info").use(new FilePlugin("./logs/app.log"));
+
+logger.info("Request processed", { method: "GET", path: "/api/users" });
+// Appends: {"level":"info","message":"Request processed","timestamp":"2025-01-15T10:30:00.000Z","context":{"method":"GET","path":"/api/users"}}
 ```
 
-#### `DiscordPlugin`
+## Discord Plugin
 
-Sends warn/error logs and notifications to Discord. The sender is set lazily since the Discord connection may not be ready at logger creation time.
+Forwards warn/error log entries and notifications to Discord via a configurable sender function. Useful for alerting on critical issues.
 
 ```typescript
+import { Logger, DiscordPlugin } from "@hardlydifficult/logger";
+
 const discord = new DiscordPlugin();
+const logger = new Logger("info").use(discord);
+
+// Set the sender once your Discord bot is ready
 discord.setSender((msg) => channel.send(msg));
+
+logger.warn("High memory usage", { usage: "85%" });
+// Sends to Discord: ⚠️ **WARN**: High memory usage
+// ```json
+// {
+//   "usage": "85%"
+// }
+// ```
+
+logger.notify("Deployment complete");
+// Sends to Discord: Deployment complete
 ```
 
-### Custom Plugins
+### Behavior
+
+| Behavior | Description |
+|----------|-------------|
+| Only `warn` and `error` log entries are sent (debug/info are filtered) | |
+| Warn entries use ⚠️ emoji; error entries use 🚨 emoji | |
+| Context is formatted as a JSON code block when present | |
+| `notify()` sends messages directly without level filtering | |
+| If `setSender` is not called, entries are silently dropped | |
+
+## Custom Plugins
 
-Implement the `LoggerPlugin` interface:
+Implement the `LoggerPlugin` interface to create custom output handlers:
 
 ```typescript
 import type { LoggerPlugin, LogEntry } from "@hardlydifficult/logger";
+import { Logger } from "@hardlydifficult/logger";
 
-class MyPlugin implements LoggerPlugin {
+class SlackPlugin implements LoggerPlugin {
   log(entry: LogEntry): void {
-    // Handle log entry
+    if (entry.level === "error") {
+      // Send to Slack
+    }
   }
 
-  // Optional: handle notify() calls
   notify?(message: string): void {
-    // Handle notification
+    // Send notification to Slack
   }
 }
 
-logger.use(new MyPlugin());
+const logger = new Logger("info").use(new SlackPlugin());
 ```
 
-### Types
+## Types
 
 ```typescript
 type LogLevel = "debug" | "info" | "warn" | "error";
@@ -106,7 +170,7 @@ type LogLevel = "debug" | "info" | "warn" | "error";
 interface LogEntry {
   readonly level: LogLevel;
   readonly message: string;
-  readonly timestamp: string;
+  readonly timestamp: string; // ISO 8601 format
   readonly context?: Readonly<Record<string, unknown>>;
 }
 
@@ -114,4 +178,18 @@ interface LoggerPlugin {
   log(entry: LogEntry): void;
   notify?(message: string): void;
 }
+
+type DiscordSender = (message: string) => void;
 ```
+
+## Error Handling
+
+All plugins are isolated—if one plugin throws an error, it does not affect other plugins or the logger itself. Errors are silently swallowed to ensure logging never crashes your application.
+
+```typescript
+const logger = new Logger("info")
+  .use(new ConsolePlugin()) // works fine
+  .use(brokenPlugin); // throws, but doesn't break the logger
+
+logger.info("This still works"); // ConsolePlugin receives it
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/logger",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [