logan-logger 2.0.0 → 2.0.2

package/README.md

@@ -4,441 +4,119 @@
 [![npm](https://img.shields.io/npm/v/logan-logger)](https://www.npmjs.com/package/logan-logger)
 [![JSR](https://jsr.io/badges/@logan/logger)](https://jsr.io/@logan/logger)
 
-A universal TypeScript logging library that works consistently across all JavaScript runtimes: Node.js, Deno, Bun, browsers, and WebAssembly environments.
+One logging API for Node.js, Deno, Bun and the browser. No dependencies.
 
-> **Upgrading from 1.x?** See the [2.0 migration guide](./docs/migration-2.0.md).
-> Winston is gone, file logging is opt-in, and repeated object references are no
-> longer reported as `[Circular]`.
-
-## Features
-
-- 🌐 **Universal Runtime Support** - Works in Node.js, Deno, Bun, browsers, and WebAssembly
-- ⚛️ **Next.js Ready** - Full compatibility with App Router, Server Components, and API Routes
-- 🪶 **Zero Dependencies** - No dependencies at all, required or optional, on any runtime
-- ⚡ **Performance First** - Lazy evaluation, zero-allocation logging, minimal memory footprint
-- 🎯 **TypeScript Native** - Full type safety with comprehensive type definitions
-- 🔧 **Flexible Configuration** - Environment-based auto-configuration or manual setup
-- 🔒 **Safe Serialization** - Handles circular references, Error objects, and sensitive data filtering
-- 🎨 **Rich Browser Support** - Console styling, performance marks, grouping
-- 📊 **Structured Logging** - Rich metadata support with child loggers
-
-## Quick Start
-
-```bash
-# NPM
-npm install logan-logger
-# or
-pnpm add logan-logger
-# or
-yarn add logan-logger
-
-# JSR (Deno/Node.js)
-deno add @logan/logger
-# or
-npx jsr add @logan/logger
-```
-
-### Basic Usage
-
-```typescript
+```ts
 import { createLogger, LogLevel } from 'logan-logger';
 
-// Create logger with automatic environment configuration
-const logger = createLogger({
-  level: LogLevel.DEBUG,
-  colorize: true
-});
+const logger = createLogger({ level: LogLevel.DEBUG });
 
-// Basic logging
 logger.info('Application started');
-logger.warn('Configuration missing', { file: 'config.json' });
-logger.error('Database connection failed', { error: new Error('Connection failed') });
+logger.warn('Config missing', { file: 'config.json' });
+logger.error('Query failed', { err: new Error('timeout') });
 
-// Child loggers with additional context
-const requestLogger = logger.child({ 
-  requestId: 'req-123', 
-  userId: 'user-456' 
-});
+// Context that follows every record, without threading it through your code
+const request = logger.child({ requestId: 'req-123' });
+request.info('Processing', { endpoint: '/api/users' });
 
-requestLogger.info('Processing request', { endpoint: '/api/users' });
+// Costs nothing when the level filters it out - the function is never called
+logger.debug(() => `Expensive: ${computeHeavyValue()}`);
 ```
 
-Use named imports from `logan-logger` and its runtime subpaths. Default imports
-are not part of the public API.
-
-### Next.js Integration
-
-Logan Logger is fully compatible with Next.js 13+ App Router, including Server Components, Client Components, and API Routes.
-
-#### Server Components
-```typescript
-import { createLogger, LogLevel } from 'logan-logger';
-
-const logger = createLogger({
-  level: process.env.NODE_ENV === 'development' ? LogLevel.DEBUG : LogLevel.INFO,
-  format: 'json'
-});
-
-export default async function ServerComponent() {
-  logger.info('Server component rendered');
-  
-  // Server-side data fetching
-  const data = await fetchData();
-  logger.debug('Data fetched', { recordCount: data.length });
-  
-  return <div>Server content</div>;
-}
 ```
-
-#### Client Components
-```typescript
-'use client';
-
-import { createLogger, LogLevel } from 'logan-logger';
-
-const logger = createLogger({
-  level: LogLevel.INFO,
-  colorize: true
-});
-
-export default function ClientComponent() {
-  const handleClick = () => {
-    logger.info('User interaction', { action: 'button_click' });
-  };
-
-  return <button onClick={handleClick}>Click me</button>;
-}
-```
-
-#### API Routes
-```typescript
-// app/api/users/route.ts
-import { NextResponse } from 'next/server';
-import { createLogger } from 'logan-logger';
-
-const logger = createLogger({
-  format: 'json',
-  metadata: { service: 'api' }
-});
-
-export async function GET() {
-  const start = Date.now();
-  logger.info('API request started', { endpoint: '/api/users' });
-  
-  try {
-    const users = await getUsers();
-    const duration = Date.now() - start;
-    
-    logger.info('API request completed', { 
-      statusCode: 200, 
-      duration,
-      userCount: users.length 
-    });
-    
-    return NextResponse.json(users);
-  } catch (error) {
-    const duration = Date.now() - start;
-    logger.error('API request failed', { 
-      statusCode: 500, 
-      duration,
-      error: error instanceof Error ? error.message : 'Unknown error'
-    });
-    
-    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
-  }
-}
-```
-
-> **📋 See [Next.js Compatibility Guide](./docs/nextjs-compatibility.md) for complete setup instructions, advanced patterns, and troubleshooting.**
-
-### Advanced Features
-
-#### Lazy Evaluation for Performance
-```typescript
-// Function is only called if debug level is enabled
-logger.debug(() => `Expensive computation: ${computeHeavyValue()}`);
-```
-
-#### Environment-Based Configuration
-```typescript
-import { createLoggerForEnvironment } from 'logan-logger';
-
-// Automatically configures based on NODE_ENV
-const logger = createLoggerForEnvironment();
-// Production: ERROR level, JSON format
-// Development: DEBUG level, colored console
-// Test: WARN level
+[2026-08-22T16:31:25.870Z] INFO: Application started
+[2026-08-22T16:31:25.871Z] WARN: Config missing {"file":"config.json"}
+[2026-08-22T16:31:25.872Z] ERROR: Query failed {"err":{"name":"Error","message":"timeout","stack":"..."}}
+[2026-08-22T16:31:25.873Z] INFO: Processing {"requestId":"req-123","endpoint":"/api/users"}
 ```
 
-#### Runtime-Specific Imports
-
-Logan Logger provides runtime-specific entry points for optimal bundling and type safety:
+Switch to `format: 'json'` and the same calls emit a structured envelope your log
+aggregator can parse.
 
-**🟢 Node.js with file logging:**
-```typescript
-import { createLogger, LogLevel, NodeLogger, createMorganStream } from 'logan-logger/node';
-
-const logger = new NodeLogger({
-  transports: [
-    { type: 'console', options: {} },
-    {
-      type: 'file',
-      level: LogLevel.ERROR,
-      options: { filename: 'logs/error.log', maxsize: 5_242_880, maxFiles: 5 }
-    }
-  ]
-});
-
-// Express/Morgan integration
-app.use(morgan('combined', { stream: createMorganStream(logger) }));
-```
+## Why this one
 
-File logging is **opt-in**: with no `transports` configured a logger writes to the
-console and nowhere else, whatever `NODE_ENV` says. The log directory is created
-lazily on the first write, so a logger that is configured but never used touches
-the disk zero times.
+- **No dependencies.** Not "few" — `dependencies` and `peerDependencies` are both
+  empty in the published package.
+- **The same code runs everywhere.** One import, one API. The library detects
+  Node, Deno, Bun, the browser or a web worker and picks an implementation.
+- **Browser-safe by construction.** The main entry contains no `node:` specifier
+  at all, so bundling it for the browser cannot fail on an unresolvable built-in.
+  That is enforced by where the code lives, not by a bundler shim.
+- **Serialization that does not lose your data.** Circular references, `Error`
+  objects with their own properties, `BigInt`, `Symbol`, functions and deep
+  nesting all survive — as markers where they must, in full where they can.
+- **TypeScript native**, with correct ESM and CJS types on every entry point.
 
-The `file` transport is registered by the `logan-logger/node` and
-`logan-logger/bun` entry points. It is deliberately absent from the main
-`logan-logger` entry so that `node:fs` never reaches a browser bundle — configure
-a file transport from the main entry and you get a warning telling you which
-entry point to import instead.
+## Install
 
-**🌐 Browser-Optimized (Webpack/Vite-Safe):**
-```typescript
-import { createLogger, BrowserLogger, PerformanceLogger } from 'logan-logger/browser';
-
-const logger = new PerformanceLogger();
-
-logger.mark('api-start');
-// ... API call
-logger.measure('api-duration', 'api-start');
-```
-
-**🦕 Deno-Optimized:**
-```typescript
-import { createLogger, BrowserLogger } from 'logan-logger/deno';
-
-const logger = createLogger({ colorize: true });
-logger.info('Deno application started');
-```
-
-**🥟 Bun-Optimized:**
-```typescript
-import { createLogger, NodeLogger } from 'logan-logger/bun';
-
-const logger = createLogger({ level: LogLevel.DEBUG });
-logger.info('Bun application started');
-```
-
-**🔧 Auto-Detection (Generic):**
-```typescript
-import { createLogger } from 'logan-logger';
-
-// Automatically selects appropriate logger based on runtime
-const logger = createLogger();
-```
-
-#### Safe Data Handling
-```typescript
-import { filterSensitiveData } from 'logan-logger';
-
-const userData = {
-  name: 'John Doe',
-  email: 'john@example.com',
-  password: 'secret123',  // Will be filtered
-  apiKey: 'sk_live_...'   // Will be filtered
-};
-
-const safeData = filterSensitiveData(userData);
-logger.info('User processed', safeData);
-// Logs: { name: 'John Doe', email: 'john@example.com', password: '[REDACTED]', apiKey: '[REDACTED]' }
-```
-
-## Runtime Support & Import Paths
-
-| Runtime | Import Path | Status | Implementation | Features |
-|---------|-------------|--------|----------------|----------|
-| **Next.js 13+** | `logan-logger` | ✅ **Full** | **Auto-detection** | **Server/Client Components, API Routes, Edge Runtime** |
-| Node.js 20+ | `logan-logger/node` | ✅ Full | Console + File transports | File logging with size rotation, custom transports, Morgan integration |
-| Bun | `logan-logger/bun` | ✅ Full | NodeLogger adapter | Same as Node.js |
-| Browser | `logan-logger/browser` | ✅ Full | Console API | CSS styling, performance marks, grouping |
-| Deno | `@logan/logger/deno` (JSR) | ✅ Basic | BrowserLogger adapter | Console logging (native implementation planned) |
-| WebWorker | `logan-logger/browser` | ✅ Basic | Console adapter | Basic console logging |
-| Auto-detect | `logan-logger` | ✅ Basic | Runtime detection | Automatic adapter selection |
-
-## Configuration
-
-### Log Levels
-```typescript
-enum LogLevel {
-  DEBUG = 0,    // Most verbose
-  INFO = 1,     // General information  
-  WARN = 2,     // Warning messages
-  ERROR = 3,    // Error messages
-  SILENT = 4    // No output
-}
-```
-
-### Environment Variables
 ```bash
-LOG_LEVEL=debug      # debug, info, warn, error, silent
-LOG_FORMAT=json      # json, text
-LOG_TIMESTAMP=true   # true/1/yes/on, false/0/no/off
-LOG_COLOR=false      # true/1/yes/on, false/0/no/off
+npm install logan-logger      # or pnpm add / yarn add
+deno add jsr:@logan/logger    # or npx jsr add @logan/logger
 ```
 
-These sit at the **top** of the precedence chain — above configuration passed to
-`createLogger()` — so an operator can change logging on a running service without
-a deploy. Opt out with `createLogger({ ..., ignoreEnvironment: true })`. A value
-that does not parse is ignored with a warning rather than silently resolving to a
-default.
-
-> **📋 See [Environment Variables Documentation](./docs/environment-variables.md) for complete details, examples, and runtime-specific considerations.**
-
-### Configuration Options
-```typescript
-interface LoggerConfig {
-  level: LogLevel;
-  format: 'json' | 'text' | 'custom';
-  timestamp: boolean;
-  colorize: boolean;
-  metadata: Record<string, any>;
-  transports?: TransportConfig[];
-}
-```
+Use named imports. There is no default export.
 
-`timestamp` and `colorize` apply to the **text** form only. The JSON envelope
-always carries a timestamp and is never colorized, so a structured log stream
-stays parseable. `colorize` additionally defers to the terminal: ANSI escapes are
-suppressed when stdout is not a TTY, and the `NO_COLOR` / `FORCE_COLOR`
-conventions are honored.
-
-### Transports
-
-`transports` lists exactly where records go, in order. Omit it and you get the
-console alone.
-
-```typescript
-import { LogLevel, NodeLogger } from 'logan-logger/node';
+> **Upgrading from 1.x?** See the [migration guide](./docs/migration-2.0.md).
+> Winston is gone, file logging is opt-in, and repeated object references are no
+> longer reported as `[Circular]`.
 
-const logger = new NodeLogger({
-  transports: [
-    { type: 'console', options: { format: 'text', colorize: true } },
-    { type: 'file', level: LogLevel.ERROR, options: { filename: 'logs/error.log' } }
-  ]
-});
-```
+## Runtimes
 
-| Type | Available from | Options |
+| Runtime | Import | Notes |
 |---|---|---|
-| `console` | everywhere | `format`, `timestamp`, `colorize` |
-| `file` | `logan-logger/node`, `logan-logger/bun` | `filename`, `maxsize`, `maxFiles`, `format`, `timestamp` |
-| `custom` | everywhere | `transport` — any object with a `write(entry)` method |
-
-Each transport is constructed behind its own guard: one failing to initialize
-warns and is dropped, and the rest keep working. The same applies at write time.
+| Auto-detect | `logan-logger` | Also the right choice for Next.js and other isomorphic frameworks |
+| Node.js 20+ | `logan-logger/node` | Adds the file transport and Morgan integration |
+| Bun | `logan-logger/bun` | Same as Node |
+| Browser / WebWorker | `logan-logger/browser` | CSS-styled console, performance marks, grouping |
+| Deno | `jsr:@logan/logger` | Console; native implementation planned |
 
-A child logger **shares** its parent's transport instances, so
-`logger.child({ requestId })` per request costs no extra file handles.
+Details and examples: [docs/runtimes.md](./docs/runtimes.md).
 
-Plug in your own destination either inline:
+## Configuring
 
-```typescript
-const logger = new NodeLogger({
-  transports: [{ type: 'custom', options: { transport: { type: 'syslog', write(entry) { /* … */ } } } }]
+```ts
+createLogger({
+  level: LogLevel.INFO,
+  format: 'json',                    // or 'text'
+  timestamp: true,                   // text form only
+  colorize: false,                   // text form only, and only on a TTY
+  metadata: { service: 'api' },      // attached to every record
+  transports: [                      // omit for console only
+    { type: 'console', options: {} },
+    { type: 'file', level: LogLevel.ERROR, options: { filename: 'logs/error.log' } },
+  ],
 });
 ```
 
-or by name, so it can be selected from configuration:
-
-```typescript
-import { registerTransport } from 'logan-logger';
-
-registerTransport('syslog', (config, context) => new SyslogTransport(config.options));
-```
-
-## API Reference
-
-### Core Methods
-```typescript
-interface ILogger {
-  debug(message: string | (() => string), metadata?: any): void;
-  info(message: string | (() => string), metadata?: any): void;
-  warn(message: string | (() => string), metadata?: any): void;
-  error(message: string | (() => string), metadata?: any): void;
-  
-  setLevel(level: LogLevel): void;
-  getLevel(): LogLevel;
-  child(metadata: Record<string, any>): ILogger;
-}
-```
-
-### Factory Functions
-```typescript
-// Create logger with explicit configuration
-createLogger(config?: Partial<LoggerConfig>): ILogger;
-
-// Create logger based on environment
-createLoggerForEnvironment(): ILogger;
-```
-
-## Development
+`LOG_LEVEL`, `LOG_FORMAT`, `LOG_TIMESTAMP` and `LOG_COLOR` override this at
+runtime, so an operator can turn up verbosity without a deploy. Libraries that
+need to pin their own logging set `ignoreEnvironment: true`.
 
-### Setup
-```bash
-git clone <repository>
-cd logan-logger-ts
-pnpm install
-```
+Every field, every transport option, and the serialization rules:
+[docs/configuration.md](./docs/configuration.md).
 
-### Commands
-```bash
-# Development
-pnpm dev                    # Run with bun
-pnpm test                   # Test watch mode
-pnpm test:run              # Single test run
-pnpm test:ui               # Test UI
-
-# Building
-pnpm build                 # Full build
-pnpm typecheck            # Type checking
-pnpm lint                  # Code linting
-
-# Specific tests
-vitest run tests/logger.test.ts
-```
+## Documentation
 
-## Architecture
+[**Full documentation index**](./docs/README.md)
 
-Logan Logger uses a **Factory + Adapter pattern**:
+- [Configuration reference](./docs/configuration.md)
+- [Runtimes and entry points](./docs/runtimes.md)
+- [Environment variables](./docs/environment-variables.md)
+- [Next.js](./docs/nextjs-compatibility.md) · [Bundlers](./docs/webpack-bundler-compatibility.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Migrating from 1.x](./docs/migration-2.0.md)
 
-1. **Runtime Detection** - Automatically detects the current JavaScript environment
-2. **Factory Creation** - Creates the appropriate logger implementation
-3. **Runtime Adapters** - Optimized implementations for each environment
-4. **Unified Interface** - Consistent API across all runtimes
-
-### File Structure
-```
-src/
-├── core/           # Core interfaces and factory
-├── runtime/        # Runtime-specific implementations  
-├── utils/          # Utilities (serialization, config, runtime detection)
-└── index.ts        # Main exports
-```
+API documentation is generated from source on [JSR](https://jsr.io/@logan/logger/doc).
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass: `pnpm test:run`
-5. Submit a pull request
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, architecture and the release
+process.
 
-## License
-
-MIT License - see LICENSE file for details.
+This library is the reference implementation of
+[Treering](https://github.com/llbbl/treering), a language-neutral logging
+specification with a conformance suite.
 
-## Credits
+## License
 
-Created by Logan Lindquist Land
+MIT © Logan Lindquist Land

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logan-logger",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "packageManager": "pnpm@11.9.0",
   "description": "Universal TypeScript logging library for all JavaScript runtimes",
   "main": "dist/index.cjs",