loggily 0.3.0 → 0.4.0

package/docs/migration-from-debug.md

@@ -1,310 +0,0 @@
-# Migration from debug
-
-Step-by-step guide for migrating from the `debug` package to `loggily`.
-
-## Why Migrate?
-
-| Feature            | debug               | loggily                                     |
-| ------------------ | ------------------- | ------------------------------------------- |
-| Log levels         | No (namespace only) | Yes (trace, debug, info, warn, error)       |
-| Structured data    | No (printf-style)   | Yes (JSON objects)                          |
-| Performance        | Good                | Better (conditional logging skips arg eval) |
-| Timing/spans       | No                  | Built-in spans with auto-timing             |
-| JSON output        | No                  | Yes (production/TRACE_FORMAT=json)          |
-| Zero-cost disabled | No                  | Yes (optional chaining pattern)             |
-
-## Quick Migration
-
-### Before (debug)
-
-```typescript
-import createDebug from "debug"
-
-const debug = createDebug("myapp")
-const debugDb = createDebug("myapp:db")
-
-debug("starting server on port %d", 3000)
-debugDb("query: %s, params: %o", sql, params)
-```
-
-### After (loggily)
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("myapp")
-const dbLog = log.logger("db")
-
-log.info("starting server", { port: 3000 })
-dbLog.debug("query", { sql, params })
-```
-
-## Pattern Mapping
-
-### Basic Logging
-
-```typescript
-// debug
-debug("message")
-debug("message %s", value)
-debug("message %d items", count)
-debug("object: %o", obj)
-debug("json: %j", data)
-
-// loggily
-log.debug("message")
-log.debug(`message ${value}`)
-log.debug("message", { items: count })
-log.debug("object", { obj })
-log.debug("data", { data })
-```
-
-### Namespaces
-
-```typescript
-// debug - separate instances
-const debug = createDebug("myapp")
-const debugDb = createDebug("myapp:db")
-const debugCache = createDebug("myapp:cache")
-
-// loggily - hierarchy via .logger()
-const log = createLogger("myapp")
-const dbLog = log.logger("db") // myapp:db
-const cacheLog = log.logger("cache") // myapp:cache
-```
-
-### Environment Variables
-
-| debug            | loggily           | Effect                                 |
-| ---------------- | ----------------- | -------------------------------------- |
-| `DEBUG=*`        | `DEBUG=*`         | Enable all debug output                |
-| `DEBUG=myapp*`   | `DEBUG=myapp`     | Enable debug for namespace             |
-| `DEBUG=myapp:db` | `DEBUG=myapp:db`  | Enable specific namespace              |
-| `DEBUG=*,-noisy` | `DEBUG=*,-noisy`  | Exclude specific namespace             |
-| N/A              | `LOG_LEVEL=debug` | Set log level without namespace filter |
-| N/A              | `TRACE=1`         | Enable span timing                     |
-| N/A              | `TRACE=myapp:db`  | Enable spans for namespace             |
-
-### Conditional Enabling
-
-```typescript
-// debug - checks if enabled
-if (debug.enabled) {
-  debug("expensive: %o", computeExpensive())
-}
-
-// loggily - optional chaining (cleaner, faster)
-log.debug?.(`expensive: ${computeExpensive()}`)
-```
-
-## Common Patterns
-
-### Printf-style to Template Literals
-
-```typescript
-// debug (printf-style)
-debug("user %s logged in from %s", username, ip)
-debug("processed %d items in %dms", count, duration)
-
-// loggily (template literals or structured)
-log.info(`user ${username} logged in from ${ip}`)
-// or structured (preferred)
-log.info("user logged in", { username, ip })
-```
-
-### Objects and JSON
-
-```typescript
-// debug
-debug("config: %O", config) // multi-line
-debug("data: %o", data) // single-line
-debug("json: %j", obj) // JSON
-
-// loggily (always structured JSON)
-log.debug("config", { config })
-log.debug("data", { data })
-log.debug("obj", { obj })
-```
-
-### Error Logging
-
-```typescript
-// debug
-debug("error: %s", err.message)
-debug("stack: %s", err.stack)
-
-// loggily (Error objects handled automatically)
-log.error(err) // Extracts message, stack, code
-log.error(err, { context: "additional info" })
-```
-
-### Timing Operations
-
-```typescript
-// debug (manual timing)
-const start = Date.now()
-await doWork()
-debug("operation took %dms", Date.now() - start)
-
-// loggily (built-in spans)
-{
-  using span = log.span("operation")
-  await doWork()
-}
-// Automatic: SPAN myapp:operation (234ms)
-
-// With data
-{
-  using span = log.span("import", { file: "data.csv" })
-  span.spanData.rowCount = await importFile()
-}
-// SPAN myapp:import (1234ms) {rowCount: 500, file: "data.csv"}
-```
-
-### Extending/Inheriting
-
-```typescript
-// debug - new instance required
-const debug = createDebug("myapp")
-const debugReq = createDebug("myapp:request")
-
-// loggily - props inherited
-const log = createLogger("myapp", { version: "1.0" })
-const reqLog = log.logger("request", { requestId: "abc" })
-// reqLog has both version and requestId
-```
-
-## Migration Checklist
-
-### 1. Update Dependencies
-
-```bash
-# Remove debug
-bun remove debug @types/debug
-
-# Add loggily
-bun add loggily
-```
-
-### 2. Update Imports
-
-```typescript
-// Before
-import createDebug from "debug"
-
-// After
-import { createLogger } from "loggily"
-```
-
-### 3. Replace Debug Instances
-
-```typescript
-// Before
-const debug = createDebug("myapp")
-
-// After
-const log = createLogger("myapp")
-```
-
-### 4. Update Log Calls
-
-| Pattern     | Before                       | After                      |
-| ----------- | ---------------------------- | -------------------------- |
-| Simple      | `debug('msg')`               | `log.debug('msg')`         |
-| With values | `debug('msg %s', v)`         | `log.debug(\`msg ${v}\`)`  |
-| Structured  | `debug('data %o', d)`        | `log.debug('data', { d })` |
-| Error       | `debug('err %s', e.message)` | `log.error(e)`             |
-
-### 5. Update Environment
-
-```bash
-# Before
-DEBUG=myapp* node app.js
-
-# After (DEBUG env var still works)
-DEBUG=myapp node app.js
-# Or set level globally without namespace filter
-LOG_LEVEL=debug node app.js
-# Or for spans
-TRACE=1 LOG_LEVEL=debug node app.js
-```
-
-### 6. Add Log Levels
-
-Debug package has only on/off. Add appropriate levels:
-
-```typescript
-// Choose appropriate level based on purpose
-log.trace("...") // Very verbose, hot paths
-log.debug("...") // Development debugging
-log.info("...") // Normal operation
-log.warn("...") // Recoverable issues
-log.error("...") // Failures
-```
-
-### 7. Convert Timing to Spans
-
-```typescript
-// Before
-const start = Date.now()
-await operation()
-debug("done in %dms", Date.now() - start)
-
-// After
-{
-  using span = log.span("operation")
-  await operation()
-}
-```
-
-### 8. Use Optional Chaining (Recommended)
-
-`createLogger()` returns `undefined` for disabled levels -- just use `?.`:
-
-```typescript
-const log = createLogger("myapp")
-
-// Optional chaining skips argument evaluation when level is disabled
-log.debug?.(`expensive: ${computeState()}`)
-log.trace?.(() => `very expensive: ${JSON.stringify(bigObj)}`)
-```
-
-## Verification
-
-After migration, verify:
-
-1. **Development output works**: `LOG_LEVEL=debug bun run app`
-2. **Production JSON works**: `NODE_ENV=production bun run app`
-3. **Spans work**: `TRACE=1 bun run app`
-4. **Level filtering works**: `LOG_LEVEL=warn bun run app` (should hide info/debug)
-
-## Gotchas
-
-### Namespace Filtering
-
-loggily supports `DEBUG=myapp` for namespace filtering (like the `debug` package). It also supports negative patterns: `DEBUG=myapp,-myapp:noisy`. For span-specific namespace filtering, use `TRACE=myapp:db`.
-
-### Printf Format Strings
-
-debug uses printf-style `%s`, `%d`, `%o`. loggily uses template literals or structured data. Search for `%s`, `%d`, `%o`, `%j`, `%O` to find calls that need conversion.
-
-### No Automatic Coloring by Namespace
-
-debug auto-assigns colors to namespaces. loggily uses level-based colors. If you need namespace distinction, include it in the log output or use the `name` property.
-
-### enabled Property
-
-debug has `.enabled` property. loggily uses level comparison:
-
-```typescript
-// debug
-if (debug.enabled) { ... }
-
-// loggily
-import { getLogLevel } from 'loggily'
-const LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, silent: 5 }
-if (LEVELS.debug >= LEVELS[getLogLevel()]) { ... }
-
-// Or use conditional logger with optional chaining (preferred)
-log.debug?.('msg')
-```

package/docs/migration-from-pino.md

@@ -1,178 +0,0 @@
-# Migration from Pino
-
-Step-by-step guide for migrating from Pino to loggily.
-
-## Why Migrate?
-
-| Feature                   | Pino                   | loggily                       |
-| ------------------------- | ---------------------- | ----------------------------- |
-| Log levels                | Yes (7 levels)         | Yes (5 levels + silent)       |
-| Structured data           | Yes (JSON)             | Yes (JSON + pretty console)   |
-| Disabled call overhead    | ~0.5ns (noop)          | ~2.5ns (?. proxy)             |
-| Disabled + expensive args | 129ns (args evaluated) | **3.6ns (args skipped)**      |
-| Built-in spans/tracing    | No                     | Yes (with `using` keyword)    |
-| Child loggers             | Yes                    | Yes                           |
-| Pretty print              | Via pino-pretty        | Built-in                      |
-| Bundle size               | ~14KB + transports     | ~3KB                          |
-| Browser support           | Via pino/browser       | Built-in (conditional export) |
-
-## Quick Migration
-
-### Before (Pino)
-
-```typescript
-import pino from "pino"
-
-const logger = pino({ level: "info" })
-const child = logger.child({ module: "db" })
-
-logger.info({ port: 3000 }, "server started")
-child.debug({ query: sql, params }, "executing query")
-```
-
-### After (loggily)
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("myapp")
-const dbLog = log.logger("db")
-
-log.info?.("server started", { port: 3000 })
-dbLog.debug?.("executing query", { query: sql, params })
-```
-
-## Pattern Mapping
-
-### Logger Creation
-
-```typescript
-// Pino
-const logger = pino()
-const logger = pino({ level: "debug" })
-const logger = pino({ name: "myapp" })
-
-// loggily
-const log = createLogger("myapp")
-setLogLevel("debug") // Global level
-```
-
-### Log Calls
-
-```typescript
-// Pino — data object first, then message
-logger.info({ userId: 42 }, "user logged in")
-logger.info("simple message")
-logger.error({ err }, "request failed")
-logger.error(err, "request failed") // Error serialization
-
-// loggily — message first, then data
-log.info?.("user logged in", { userId: 42 })
-log.info?.("simple message")
-log.error?.(err, { context: "request" }) // Error object handled
-log.error?.(err) // Extracts message, stack, code
-```
-
-### Child Loggers
-
-```typescript
-// Pino
-const child = logger.child({ requestId: "abc" })
-child.info("handling request")
-
-// loggily — two patterns
-// 1. Context fields (like Pino's child)
-const child = log.child({ requestId: "abc" })
-child.info?.("handling request") // includes requestId
-
-// 2. Namespace (extends the logger name)
-const dbLog = log.logger("db") // name: "myapp:db"
-```
-
-### Levels
-
-| Pino Level | Value | loggily Level             |
-| ---------- | ----: | ------------------------- |
-| trace      |    10 | trace                     |
-| debug      |    20 | debug                     |
-| info       |    30 | info                      |
-| warn       |    40 | warn                      |
-| error      |    50 | error                     |
-| fatal      |    60 | error (no separate fatal) |
-| silent     |     ∞ | silent                    |
-
-### Transports / Writers
-
-```typescript
-// Pino transports
-const logger = pino({
-  transport: {
-    target: "pino/file",
-    options: { destination: "/tmp/app.log" },
-  },
-})
-
-// loggily writers
-import { addWriter, createFileWriter } from "loggily"
-
-const writer = createFileWriter("/tmp/app.log")
-addWriter((formatted) => writer.write(formatted))
-```
-
-### Serializers
-
-```typescript
-// Pino serializers
-const logger = pino({
-  serializers: {
-    req: pino.stdSerializers.req,
-    err: pino.stdSerializers.err,
-  },
-})
-
-// loggily — handle in data parameter
-log.info?.("request", {
-  method: req.method,
-  url: req.url,
-  statusCode: res.statusCode,
-})
-log.error?.(err) // Built-in Error serialization
-```
-
-### Timing
-
-```typescript
-// Pino (manual)
-const start = Date.now()
-await operation()
-logger.info({ duration: Date.now() - start }, "operation complete")
-
-// loggily (built-in spans)
-{
-  using span = log.span("operation")
-  await operation()
-  span.spanData.rowCount = 500
-}
-// Automatic: SPAN myapp:operation (234ms) {rowCount: 500}
-```
-
-## Environment Variables
-
-| Pino                  | loggily               | Effect                                |
-| --------------------- | --------------------- | ------------------------------------- |
-| `LOG_LEVEL=debug`     | `LOG_LEVEL=debug`     | Set minimum level                     |
-| N/A                   | `DEBUG=myapp`         | Namespace filter (auto-enables debug) |
-| N/A                   | `TRACE=1`             | Enable span output                    |
-| N/A                   | `LOG_FORMAT=json`     | Force JSON output                     |
-| `NODE_ENV=production` | `NODE_ENV=production` | Auto-enable JSON                      |
-
-## Migration Checklist
-
-1. **Update dependencies**: `bun remove pino pino-pretty && bun add loggily`
-2. **Update imports**: `import pino from "pino"` → `import { createLogger } from "loggily"`
-3. **Swap argument order**: Pino uses `(data, message)`, loggily uses `(message, data)`
-4. **Replace `logger.child()`** with `.child()` (context) or `.logger()` (namespace)
-5. **Convert transports** to writers via `addWriter()`
-6. **Add `?.`** to all log calls for zero-overhead disabled logging
-7. **Convert manual timing** to spans with `using`
-8. **Replace `fatal`** with `error` (add a custom label in data if needed)

package/docs/migration-from-winston.md

@@ -1,179 +0,0 @@
-# Migration from Winston
-
-Step-by-step guide for migrating from Winston to loggily.
-
-## Why Migrate?
-
-| Feature                   | Winston                 | loggily                       |
-| ------------------------- | ----------------------- | ----------------------------- |
-| Log levels                | Customizable            | 5 fixed levels + silent       |
-| Structured data           | Yes (metadata)          | Yes (data parameter)          |
-| Disabled call overhead    | ~372ns                  | **~2.5ns** (?. pattern)       |
-| Disabled + expensive args | ~741ns (args evaluated) | **~3.6ns (args skipped)**     |
-| Built-in spans/tracing    | No                      | Yes (with `using` keyword)    |
-| Transports                | Rich ecosystem          | Writers + file writer         |
-| Pretty print              | Via formats             | Built-in                      |
-| Bundle size               | ~60KB + transports      | ~3KB                          |
-| Browser support           | Via browser transport   | Built-in (conditional export) |
-
-## Quick Migration
-
-### Before (Winston)
-
-```typescript
-import winston from "winston"
-
-const logger = winston.createLogger({
-  level: "info",
-  format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
-  transports: [new winston.transports.Console()],
-})
-
-logger.info("server started", { port: 3000 })
-logger.error("request failed", { error: err.message })
-```
-
-### After (loggily)
-
-```typescript
-import { createLogger } from "loggily"
-
-const log = createLogger("myapp")
-
-log.info?.("server started", { port: 3000 })
-log.error?.(err) // Automatic Error handling
-```
-
-## Pattern Mapping
-
-### Logger Creation
-
-```typescript
-// Winston
-const logger = winston.createLogger({
-  level: "info",
-  format: winston.format.json(),
-  transports: [new winston.transports.Console()],
-})
-
-// loggily
-const log = createLogger("myapp")
-// Level, format, and output configured via env vars or API:
-// LOG_LEVEL=info, LOG_FORMAT=json, NODE_ENV=production
-```
-
-### Log Calls
-
-```typescript
-// Winston — message first, metadata spread or second arg
-logger.info("starting", { port: 3000 })
-logger.info({ message: "starting", port: 3000 })
-logger.error("failed", { error: err.message, stack: err.stack })
-
-// loggily — message + optional data
-log.info?.("starting", { port: 3000 })
-log.error?.(err) // Error: auto-extracts message, stack, code
-log.error?.(err, { context: "startup" }) // With extra context
-```
-
-### Levels
-
-| Winston Level | loggily Level           |
-| ------------- | ----------------------- |
-| error         | error                   |
-| warn          | warn                    |
-| info          | info                    |
-| http          | info (no separate http) |
-| verbose       | debug                   |
-| debug         | debug                   |
-| silly         | trace                   |
-
-### Child Loggers
-
-```typescript
-// Winston — child loggers via defaultMeta
-const childLogger = logger.child({ requestId: "abc" })
-childLogger.info("processing")
-
-// loggily — two patterns
-const child = log.child({ requestId: "abc" }) // Context fields
-const dbLog = log.logger("db") // Namespace: myapp:db
-```
-
-### Transports / Writers
-
-```typescript
-// Winston transports
-const logger = winston.createLogger({
-  transports: [new winston.transports.Console(), new winston.transports.File({ filename: "app.log" })],
-})
-
-// loggily writers
-import { addWriter, createFileWriter } from "loggily"
-
-// Console output is built-in (default)
-// File output via createFileWriter
-const writer = createFileWriter("/tmp/app.log")
-const unsub = addWriter((formatted) => writer.write(formatted))
-
-// Custom writer (e.g., send to external service)
-addWriter((formatted, level) => {
-  if (level === "error") sendToAlertService(formatted)
-})
-```
-
-### Formats
-
-```typescript
-// Winston — format combinators
-const logger = winston.createLogger({
-  format: winston.format.combine(
-    winston.format.timestamp(),
-    winston.format.colorize(),
-    winston.format.printf(({ timestamp, level, message }) => `${timestamp} ${level}: ${message}`),
-  ),
-})
-
-// loggily — built-in formats
-// Development: colorized console with timestamp (default)
-// Production: JSON (NODE_ENV=production or LOG_FORMAT=json)
-// No configuration needed
-```
-
-### Timing
-
-```typescript
-// Winston (manual profiling)
-logger.profile("operation")
-await doWork()
-logger.profile("operation") // logs duration
-
-// loggily (built-in spans)
-{
-  using span = log.span("operation")
-  await doWork()
-}
-// Automatic: SPAN myapp:operation (234ms)
-```
-
-## Environment Variables
-
-| Winston                  | loggily               | Effect             |
-| ------------------------ | --------------------- | ------------------ |
-| N/A (configured in code) | `LOG_LEVEL=debug`     | Set minimum level  |
-| N/A                      | `DEBUG=myapp`         | Namespace filter   |
-| N/A                      | `TRACE=1`             | Enable span output |
-| N/A                      | `LOG_FORMAT=json`     | Force JSON output  |
-| `NODE_ENV=production`    | `NODE_ENV=production` | Auto-enable JSON   |
-
-## Migration Checklist
-
-1. **Update dependencies**: `bun remove winston` and `bun add loggily`
-2. **Update imports**: `import winston from "winston"` → `import { createLogger } from "loggily"`
-3. **Replace `createLogger()`**: Winston's options → `createLogger("name")` + env vars
-4. **Convert transports** to `addWriter()` + optional `createFileWriter()`
-5. **Remove format configuration** — built-in formats handle dev/prod automatically
-6. **Add `?.`** to all log calls for zero-overhead disabled logging
-7. **Map custom levels**: http→info, verbose→debug, silly→trace
-8. **Convert `logger.profile()`** to spans with `using`
-9. **Replace `logger.child()`** with `.child()` (context) or `.logger()` (namespace)