@fend/firo 0.0.5 → 0.0.7

package/README.md

@@ -7,11 +7,11 @@
 [![Build](https://github.com/fend25/firo/actions/workflows/publish.yml/badge.svg)](https://github.com/fend25/firo/actions/workflows/publish.yml)
 [![Best logger ever](https://img.shields.io/badge/best_logger-ever-166FFF)](https://github.com/fend25/firo)
 
-**Spruce up your logs!** 
+**Spruce up your logs!**
 
 The logger for Node.js, Bun and Deno you've been looking for.
 
-Beautiful **dev** output - out of the box. Structured NDJSON for **prod**.
+Beautiful **dev** output - out of the box. Fast, structured NDJSON for **prod**.
 
 Think of it as pino, but with brilliant DX.
 
@@ -93,36 +93,6 @@ log.info('Request handled', { status: 200 })
 // {"timestamp":"2024-01-15T14:32:01.204Z","level":"info","message":"Request handled","data":{"status":200}}
 ```
 
-## Best practices
-
-### AsyncLocalStorage (Traceability)
-
-The best way to use **firo** in web frameworks is to store a child logger in `AsyncLocalStorage`. This gives you automatic traceability (e.g. `requestId`) across your entire call stack without passing the logger as an argument.
-
-```ts
-import { AsyncLocalStorage } from 'node:util'
-import { createFiro } from '@fend/firo'
-
-const logger = createFiro()
-const storage = new AsyncLocalStorage()
-
-// Middleware example
-function middleware(req, res, next) {
-  const reqLog = logger.child({ 
-    requestId: req.headers['x-request-id'] || 'gen-123',
-    method: req.method
-  })
-  storage.run(reqLog, next)
-}
-
-// Deeply nested function
-function someService() {
-  const log = storage.getStore() ?? logger
-  log.info('Service action performed') 
-  // Output: [requestId:gen-123] [method:GET] Service action performed
-}
-```
-
 ## Log levels
 
 Four levels, in order: `debug` → `info` → `warn` → `error`.
@@ -139,16 +109,31 @@ Debug lines are dimmed in dev mode to reduce visual noise.
 ### Filtering
 
 ```ts
-// Suppress debug in dev, keep everything in prod
-const log = createFiro({
-  minLevelInDev: 'info',
-  minLevelInProd: 'warn',
-})
-
-// Or a single threshold for both modes
 const log = createFiro({ minLevel: 'warn' })
 ```
 
+## Error signatures
+
+`error()` accepts multiple call signatures:
+
+```ts
+// Message only will be automatically wrapped in an Error object to intentionally capture and preserve the stack trace
+// because stack trace with a couple of extra levels of indirection is definitely better than no stack trace at all
+log.error('Something went wrong')
+
+// Message + Error object
+log.error('Query failed', new Error('timeout'))
+
+// Error object only
+log.error(new Error('Unhandled'))
+
+// Error + extra data
+log.error(new Error('DB down'), { query: 'SELECT ...', reqId: 123 })
+
+// Anything — will be coerced to Error
+log.error(someUnknownThing)
+```
+
 ## Context
 
 Attach persistent key/value pairs to a logger instance. They appear in every log line.
@@ -166,29 +151,47 @@ log.info('Started')
 
 ### Context options
 
+Three ways to add context:
+
+```ts
+// 1. Simple key-value — just the basics
+log.addContext('service', 'auth')
+
+// 2. Key + value with options — when you need control
+log.addContext('traceId', { value: 'abc-123-xyz', hideIn: 'dev' })
+log.addContext('region', { value: 'west', color: '38;5;214' })
+
+// 3. Object form — everything in one object
+log.addContext({ key: 'userId', value: 'u-789', omitKey: true })
+log.addContext({ key: 'span', value: 'xyz', color: '38;2;255;100;0' })
+```
+
+Available options (styles 2 and 3):
+
 ```ts
-// Hide the key, show only the value — useful for IDs
+// Hide the key, show only the value: [u-789] instead of [userId:u-789]
 log.addContext({ key: 'userId', value: 'u-789', omitKey: true })
-// renders as [u-789] instead of [userId:u-789]
 
 // Pin a specific color by palette index (0–29)
-log.addContext({ key: 'region', value: 'west', colorIndex: 3 })
+log.addContext('region', { value: 'west', colorIndex: 3 })
 
 // Use any ANSI color — 256-color, truecolor, anything
-log.addContext({ key: 'trace', value: 'abc', color: '38;5;214' })       // 256-color orange
+log.addContext('trace', { value: 'abc', color: '38;5;214' })       // 256-color orange
 log.addContext({ key: 'span', value: 'xyz', color: '38;2;255;100;0' })  // truecolor
-```
 
-### Remove context
+// Hide in dev — useful for traceIds that clutter the terminal
+log.addContext('traceId', { value: 'abc-123-xyz', hideIn: 'dev' })
 
-```ts
-log.removeFromContext('env')
+// Hide in prod — dev-only debugging context
+log.addContext('debugTag', { value: 'perf-test', hideIn: 'prod' })
 ```
 
-### Read context
+### Context API
 
 ```ts
-const ctx = log.getContext() // ContextItem[]
+log.getContext()        // ContextItem[]
+log.hasInContext('key') // boolean
+log.removeFromContext('env')
 ```
 
 ## Child loggers
@@ -234,85 +237,75 @@ log.error('Payment failed', err, {
 })
 ```
 
-## Error signatures
+## Dev formatter options
 
-`error()` accepts multiple call signatures:
+Fine-tune the dev formatter's timestamp format. For example, to remove seconds and milliseconds:
 
 ```ts
-// Message only
-log.error('Something went wrong')
+import { createFiro } from '@fend/firo'
 
-// Message + Error object
-log.error('Query failed', new Error('timeout'))
+const log = createFiro({
+  devFormatterConfig: {
+    timeOptions: {
+      hour: '2-digit',
+      minute: '2-digit',
+      second: undefined,
+      fractionalSecondDigits: undefined
+    }
+  }
+})
+```
 
-// Error object only
-log.error(new Error('Unhandled'))
+## Color palette
 
-// Anything — will be coerced to Error
-log.error(someUnknownThing)
-```
+Most loggers give you monochrome walls of text. Firo gives you **30 handpicked colors** that make context badges instantly scannable — you stop reading and start seeing.
 
-## Custom transport
+![firo color palette](https://github.com/fend25/firo/blob/main/img/color_madness.png?raw=true)
+
+### How it works
+
+By default, firo auto-assigns colors from all 30 palette colors using a hash of the context key. Similar keys like `user-1` and `user-2` land on different colors automatically.
 
-Provide your own transport function to take full control of output:
+You can also pin a specific color using `FIRO_COLORS` — a named palette with full IDE autocomplete:
 
 ```ts
-import type { TransportFn } from '@fend/firo'
+import { createFiro, FIRO_COLORS } from '@fend/firo'
 
-const myTransport: TransportFn = (level, context, msg, data, opts) => {
-  // level:   'debug' | 'info' | 'warn' | 'error'
-  // context: ContextItemWithOptions[]
-  // msg:     string | Error | unknown
-  // data:    Error | unknown
-  // opts:    LogOptions | undefined
-}
+const log = createFiro()
 
-const log = createFiro({ transport: myTransport })
+log.addContext('region', { value: 'west', color: FIRO_COLORS.coral })
+log.addContext('service', { value: 'auth', color: FIRO_COLORS.skyBlue })
+log.addContext('env', { value: 'staging', color: FIRO_COLORS.lavender })
 ```
 
-### FiroUtils
+Available colors: `cyan`, `green`, `yellow`, `magenta`, `blue`, `brightCyan`, `brightGreen`, `brightYellow`, `brightMagenta`, `brightBlue`, `orange`, `pink`, `lilac`, `skyBlue`, `mint`, `salmon`, `lemon`, `lavender`, `sage`, `coral`, `teal`, `rose`, `pistachio`, `mauve`, `aqua`, `gold`, `thistle`, `seafoam`, `tangerine`, `periwinkle`.
 
-`FiroUtils` exposes helper functions useful for building custom transports:
+### Want even more variety?
 
-```ts
-import { FiroUtils } from '@fend/firo'
+You can also pass any raw ANSI code as a string — 256-color, truecolor, go wild:
 
-FiroUtils.wrapToError(value)      // coerce unknown → Error
-FiroUtils.serializeError(err)     // Error → plain object { message, stack, name }
-FiroUtils.safeStringify(obj)      // JSON.stringify with bigint support + fallback
-FiroUtils.jsonReplacer            // replacer for JSON.stringify (handles bigint)
-FiroUtils.colorize(text, idx)     // wrap text in ANSI color by palette index
-FiroUtils.colorizeLevel(level, t) // wrap text in level color (red/yellow/dim)
+```ts
+log.addContext('trace', { value: 'abc', color: '38;5;214' })         // 256-color
+log.addContext('span', { value: 'xyz', color: '38;2;255;105;180' })  // truecolor pink
 ```
 
-## Dev transport options
+### Restrict to safe colors
 
-Fine-tune the dev transport's timestamp format. For example, to remove seconds and milliseconds:
+If your terminal doesn't support 256 colors, you can restrict auto-hash to 10 basic terminal-safe colors:
 
 ```ts
-import { createFiro } from '@fend/firo'
-
-const log = createFiro({
-  devTransportConfig: {
-    timeOptions: {
-      hour: '2-digit', 
-      minute: '2-digit', 
-      second: undefined, 
-      fractionalSecondDigits: undefined 
-    }
-  }
-})
+const log = createFiro({ useSafeColors: true })
 ```
 
-## Prod transport options
+## Prod formatter options
 
-Configure the prod (JSON) transport's timestamp format:
+Configure the prod (JSON) formatter's timestamp format:
 
 ```ts
 // Epoch ms (faster, same as pino)
 const log = createFiro({
   mode: 'prod',
-  prodTransportConfig: { timestamp: 'epoch' }
+  prodFormatterConfig: { timestamp: 'epoch' }
 })
 // {"timestamp":1711100000000,"level":"info","message":"hello"}
 
@@ -323,7 +316,7 @@ const log = createFiro({ mode: 'prod' })
 
 ### Custom destination
 
-By default, prod transport writes to `process.stdout`. You can redirect output to any object with a `.write(string)` method:
+By default, prod formatter writes to `process.stdout`. You can redirect output to any object with a `.write(string)` method:
 
 ```ts
 import { createFiro } from '@fend/firo'
@@ -332,63 +325,89 @@ import { createWriteStream } from 'node:fs'
 // Write to a file
 const log = createFiro({
   mode: 'prod',
-  prodTransportConfig: { dest: createWriteStream('/var/log/app.log') }
+  prodFormatterConfig: { dest: createWriteStream('/var/log/app.log') }
 })
 
 // Use SonicBoom for async buffered writes (same as pino)
 import SonicBoom from 'sonic-boom'
 const log = createFiro({
   mode: 'prod',
-  prodTransportConfig: { dest: new SonicBoom({ fd: 1 }) }
+  prodFormatterConfig: { dest: new SonicBoom({ fd: 1 }) }
 })
 ```
 
-## Color palette
+## Custom formatter
 
-Most loggers give you monochrome walls of text. firo gives you **30 handpicked colors** that make context badges instantly scannable — you stop reading and start seeing.
+If for some reason all the options are not enough and you need to take full control of the output, you can provide your own formatter function.
 
-![firo color palette](https://github.com/fend25/firo/blob/main/img/color_madness.png?raw=true)
+```ts
+import type { FormatterFn } from '@fend/firo'
 
-### How it works
+const myFormatter: FormatterFn = (level, context, msg, data, opts) => {
+  // level:   'debug' | 'info' | 'warn' | 'error'
+  // context: ContextItemWithOptions[]
+  // msg:     string | Error | unknown
+  // data:    Error | unknown
+  // opts:    LogOptions | undefined
+}
 
-By default, firo auto-assigns colors from all 30 palette colors using a hash of the context key. Similar keys like `user-1` and `user-2` land on different colors automatically.
+const log = createFiro({ formatter: myFormatter })
+```
 
-You can also pin a specific color using `FIRO_COLORS` — a named palette with full IDE autocomplete:
+You don't have to start from scratch — all the helpers we use internally are yours too:
 
-```ts
-import { createFiro, FIRO_COLORS } from '@fend/firo'
+#### FiroUtils
 
-const log = createFiro()
+`FiroUtils` exposes helper functions useful for building custom formatters:
 
-log.addContext('region', { value: 'west', color: FIRO_COLORS.coral })
-log.addContext('service', { value: 'auth', color: FIRO_COLORS.skyBlue })
-log.addContext('env', { value: 'staging', color: FIRO_COLORS.lavender })
+```ts
+import { FiroUtils } from '@fend/firo'
+
+FiroUtils.wrapToError(value)      // coerce unknown → Error
+FiroUtils.serializeError(err)     // Error → plain object { message, stack, name, cause?, ... }
+FiroUtils.safeStringify(obj)      // JSON.stringify with bigint support + fallback
+FiroUtils.jsonReplacer            // replacer for JSON.stringify (handles bigint)
+FiroUtils.extractMessage(msg)     // extract message string from string | Error | unknown
+FiroUtils.colorize(text, idx, c?) // wrap text in ANSI color by palette index or raw code
+FiroUtils.colorizeLevel(level, t) // wrap text in level color (red/yellow/dim)
 ```
 
-Available colors: `cyan`, `green`, `yellow`, `magenta`, `blue`, `brightCyan`, `brightGreen`, `brightYellow`, `brightMagenta`, `brightBlue`, `orange`, `pink`, `lilac`, `skyBlue`, `mint`, `salmon`, `lemon`, `lavender`, `sage`, `coral`, `teal`, `rose`, `pistachio`, `mauve`, `aqua`, `gold`, `thistle`, `seafoam`, `tangerine`, `periwinkle`.
+## Best practices
 
-### Want even more variety?
+### AsyncLocalStorage (Traceability)
 
-You can also pass any raw ANSI code as a string — 256-color, truecolor, go wild:
+The best way to use **firo** in web frameworks is to store a child logger in `AsyncLocalStorage`. This gives you automatic traceability (e.g. `requestId`) across your entire call stack without passing the logger as an argument.
 
 ```ts
-log.addContext('trace', { value: 'abc', color: '38;5;214' })         // 256-color
-log.addContext('span', { value: 'xyz', color: '38;2;255;105;180' })  // truecolor pink
-```
+import { AsyncLocalStorage } from 'node:util'
+import { createFiro } from '@fend/firo'
 
-### Restrict to safe colors
+const logger = createFiro()
+const storage = new AsyncLocalStorage()
 
-If your terminal doesn't support 256 colors, you can restrict auto-hash to 10 basic terminal-safe colors:
+// Middleware — traceId is essential in prod logs but noisy in dev terminal
+function middleware(req, res, next) {
+  const reqLog = logger.child({
+    traceId: { value: req.headers['x-trace-id'] || crypto.randomUUID(), hideIn: 'dev' },
+    method: req.method
+  })
+  storage.run(reqLog, next)
+}
 
-```ts
-const log = createFiro({ useAllColors: false })
+// Deeply nested function — no logger passing needed
+function someService() {
+  const log = storage.getStore() ?? logger
+  log.info('Service action performed')
+  // dev:  [method:GET] Service action performed
+  // prod: {"traceId":"a1b2c3","method":"GET","message":"Service action performed"}
+}
 ```
 
 ## Why not pino?
 
-**Pino** is Italian for *Pine*. It's a great, sturdy tree, especially in production. 
+**Pino** is Italian for *Pine*. It's a great, sturdy tree, especially in production.
 
-But sometimes you need to **Spruce** up your development experience. 
+But sometimes you need to **Spruce** up your development experience.
 
 The problem with pino is development. Its default output is raw JSON — one giant line per log entry, completely unreadable. You reach for `pino-pretty`, and suddenly you're maintaining infrastructure just to see what your app is doing.
 
@@ -400,36 +419,35 @@ The problem with pino is development. Its default output is raw JSON — one gia
 - **Visual hierarchy:** Debug lines are dimmed; high-signal logs stay readable.
 - **Zero config:** Beautiful output from the first second.
 
-In prod it emits clean NDJSON, same as pino. Your log aggregator won't know the difference.
+In prod it emits clean NDJSON, same as pino. Your log aggregator won't know the difference. And the speed tax? Smaller than you'd think.
 
 ## Performance
 
-Prod mode (NDJSON) with `timestamp: 'epoch'`, Apple M1, Node.js 25. Average time per 100K log lines (lower is better):
+Firo vs [pino](https://github.com/pinojs/pino) — head-to-head, both writing to stdout, same machine, same conditions.
+
+| Scenario                       | pino ops/sec | firo ops/sec | pino ms | firo ms |  diff    |
+| ------------------------------ | -----------: | -----------: | ------: | ------: | -------: |
+| simple string                  |      941,986 |      812,970 |   106.2 |   123.0 |  +15.82% |
+| string + small obj             |      749,782 |      673,332 |   133.4 |   148.5 |  +11.32% |
+| string + bigger obj            |      582,000 |      523,643 |   171.8 |   191.0 |  +11.18% |
+| with 3 context items           |      818,123 |      589,433 |   122.2 |   169.7 |  +38.87% |
+| child logger (2 ctx)           |      807,551 |      592,472 |   123.8 |   168.8 |  +36.35% |
+| deep child (7 ctx) + rich data |      408,246 |      314,244 |   245.0 |   318.2 |  +29.88% |
+| error with Error obj           |      389,665 |      458,247 |   256.6 |   218.2 |  -14.96% |
+
+<sub>Apple M1, Node.js 25, 10 runs × 100K logs per scenario.</sub>
+
+Pino is backed by 10 years of relentless optimization: [SonicBoom](https://github.com/pinojs/sonic-boom) async writer, [fast-json-stringify](https://github.com/fastify/fast-json-stringify) with schema-compiled serialization, pre-serialized child context stored as raw JSON fragments, C++ worker threads. It is an obsessively optimized piece of engineering and fully deserves its reputation as the fastest logger in Node.js.
 
-| Scenario               | ops/sec | ms     |
-| ---------------------- | ------- | ------ |
-| simple string          | 782,488 | 127.8  |
-| string + small obj     | 656,512 | 152.3  |
-| string + bigger obj    | 513,087 | 194.9  |
-| with 3 context items   | 570,441 | 175.3  |
-| child logger (2 ctx)   | 568,977 | 175.8  |
-| error with Error obj   | 470,758 | 212.4  |
+Firo uses the most vanilla tools imaginable — `JSON.stringify` and `process.stdout.write`, shipping since 2009. Zero dependencies. Zero tricks. ~30% behind pino on a realistic deep-child scenario with nested payloads. 15% ahead on error serialization.
 
-For comparison, here's [pino's own benchmark](https://github.com/pinojs/pino/blob/main/docs/benchmarks.md) (100K `"hello world"` logs):
+For context, here's where the other loggers stand according to [pino's own benchmarks](https://github.com/pinojs/pino/blob/main/docs/benchmarks.md) (basic "hello world", same machine): winston 174ms, bunyan 228ms, bole 107ms. firo's 123ms puts it comfortably ahead of winston and bunyan, neck and neck with bole — and all of that with a DX that none of them can match.
 
-| Logger           | ms     |
-| ---------------- | ------ |
-| pino             | 114.8  |
-| **firo**         | **127.8** |
-| bole             | 172.7  |
-| pino (NodeStream)| 159.2  |
-| debug            | 220.5  |
-| winston          | 270.2  |
-| bunyan           | 377.4  |
+So yes — if you're looking for a pino alternative with gorgeous DX, structured context, and beautiful dev output, firo is right there performance-wise. Almost a drop-in replacement.*
 
-Pino is faster thanks to [SonicBoom](https://github.com/pinojs/sonic-boom) — an optimized async writer with buffering and [fast-json-stringify](https://github.com/fastify/fast-json-stringify) for schema-compiled serialization. firo uses plain `JSON.stringify` + `process.stdout.write` and lands within 8% of pino — a difference of ~130 nanoseconds per log line.
+<sub>* Okay, not exactly drop-in — we put the message first and the data second, like normal humans. `log.info("hello", data)` instead of `log.info(data, "hello")`. We'll let you decide which API sparks more joy.</sub>
 
-Run it yourself: `pnpm bench`
+Run the benchmark yourself: `pnpm bench`
 
 ## API reference
 
@@ -452,14 +470,21 @@ Run it yourself: `pnpm bench`
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `mode` | `'dev' \| 'prod'` | `'dev'` | Selects the built-in transport |
-| `minLevel` | `LogLevel` | `'debug'` | Minimum level for both modes |
-| `minLevelInDev` | `LogLevel` | — | Overrides `minLevel` in dev mode |
-| `minLevelInProd` | `LogLevel` | — | Overrides `minLevel` in prod mode |
-| `transport` | `TransportFn` | — | Custom transport, overrides `mode` |
-| `devTransportConfig` | `DevTransportConfig` | — | Options for the built-in dev transport |
-| `prodTransportConfig` | `ProdTransportConfig` | — | Options for the built-in JSON prod transport |
-| `useAllColors` | `boolean` | `true` | Use all 30 palette colors for auto-hash (set `false` for 10 safe colors) |
+| `mode` | `'dev' \| 'prod'` | `'dev'` | Selects the built-in formatter |
+| `minLevel` | `LogLevel` | `'debug'` | Minimum log level |
+| `formatter` | `FormatterFn` | — | Custom formatter, overrides `mode` |
+| `devFormatterConfig` | `DevFormatterConfig` | — | Options for the built-in dev formatter |
+| `prodFormatterConfig` | `ProdFormatterConfig` | — | Options for the built-in JSON prod formatter |
+| `useSafeColors` | `boolean` | `false` | Restrict auto-hash to 10 terminal-safe colors (set `true` for basic terminals) |
+
+### Context options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `colorIndex` | `number` | auto | Color palette index (0–29) |
+| `color` | `string` | — | Raw ANSI color code (e.g. `'38;5;214'`). Takes priority over `colorIndex` |
+| `omitKey` | `boolean` | `false` | Hide the key, show only the value as `[value]` |
+| `hideIn` | `'dev' \| 'prod'` | — | Hide this context item in dev or prod mode |
 
 ## License
 

package/dist/index.cjs

@@ -32,9 +32,9 @@ var index_exports = {};
 __export(index_exports, {
   FIRO_COLORS: () => FIRO_COLORS,
   FiroUtils: () => utils_exports,
-  createDevTransport: () => createDevTransport,
+  createDevFormatter: () => createDevFormatter,
   createFiro: () => createFiro,
-  createProdTransport: () => createProdTransport
+  createProdFormatter: () => createProdFormatter
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -45,6 +45,7 @@ __export(utils_exports, {
   LOG_LEVELS: () => LOG_LEVELS,
   colorize: () => colorize,
   colorizeLevel: () => colorizeLevel,
+  extractMessage: () => extractMessage,
   getColorIndex: () => getColorIndex,
   jsonReplacer: () => jsonReplacer,
   safeStringify: () => safeStringify,
@@ -94,12 +95,12 @@ var FIRO_COLORS = {
 };
 var COLORS_LIST = Object.values(FIRO_COLORS);
 var SAFE_COLORS_COUNT = 10;
-var getColorIndex = (str, useAllColors = false) => {
+var getColorIndex = (str, useSafeColors = false) => {
   let hash = 0;
   for (let i = 0, len = str.length; i < len; i++) {
     hash = str.charCodeAt(i) + ((hash << 5) - hash);
   }
-  const range = useAllColors ? COLORS_LIST.length : SAFE_COLORS_COUNT;
+  const range = useSafeColors ? SAFE_COLORS_COUNT : COLORS_LIST.length;
   return Math.abs(hash % range);
 };
 var colorize = (text, colorIndex, color) => {
@@ -122,13 +123,18 @@ var wrapToError = (obj) => {
 };
 var serializeError = (_err) => {
   const err = wrapToError(_err);
-  return {
+  const result = {
     message: err.message,
     stack: err.stack,
     name: err.name,
     ...err
   };
+  if (err.cause !== void 0) {
+    result.cause = err.cause instanceof Error ? serializeError(err.cause) : err.cause;
+  }
+  return result;
 };
+var extractMessage = (msg) => typeof msg === "string" ? msg : msg instanceof Error ? msg.message : typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
 var colorizeLevel = (level, text) => {
   if (level === "info") return text;
   switch (level) {
@@ -146,10 +152,10 @@ var colorizeLevel = (level, text) => {
   }
 };
 
-// src/transport_dev.ts
+// src/formatter_dev.ts
 var import_node_util2 = require("util");
 var import_node_process = __toESM(require("process"), 1);
-var createDevTransport = (config = {}) => {
+var createDevFormatter = (config = {}) => {
   const locale = config.locale ?? void 0;
   const timeOpts = {
     hour12: false,
@@ -159,10 +165,10 @@ var createDevTransport = (config = {}) => {
     fractionalSecondDigits: 3,
     ...config.timeOptions || {}
   };
-  const transport = (level, context, msg, data, opts) => {
+  const formatter = (level, context, msg, data, opts) => {
     const now = /* @__PURE__ */ new Date();
     const timestamp = now.toLocaleTimeString(locale, timeOpts);
-    const contextStr = context.map((ctx) => {
+    const contextStr = context.filter((ctx) => ctx.hideIn !== "dev").map((ctx) => {
       const key = ctx.omitKey ? "" : `${ctx.key}:`;
       const content = `${key}${ctx.value}`;
       return colorize(`[${content}]`, ctx.colorIndex, ctx.color);
@@ -189,25 +195,23 @@ var createDevTransport = (config = {}) => {
     if (level === "error") import_node_process.default.stderr.write(finalLine);
     else import_node_process.default.stdout.write(finalLine);
   };
-  return transport;
+  return formatter;
 };
 
-// src/transport_prod.ts
+// src/formatter_prod.ts
 var import_node_util3 = require("util");
 var import_node_process2 = __toESM(require("process"), 1);
 var buildRecord = (level, context, msg, getTimestamp, data) => {
-  const contextObj = context.reduce((acc, item) => {
-    acc[item.key] = item.value;
-    return acc;
-  }, {});
   const logRecord = {
     timestamp: getTimestamp(),
-    level,
-    ...contextObj
+    level
   };
+  for (let i = 0, len = context.length; i < len; i++) {
+    if (context[i].hideIn === "prod") continue;
+    logRecord[context[i].key] = context[i].value;
+  }
+  logRecord.message = extractMessage(msg);
   if (level === "error") {
-    const message = typeof msg === "string" ? msg : msg instanceof Error ? msg.message : typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
-    logRecord.message = message;
     if (data instanceof Error) {
       logRecord.error = serializeError(data);
     } else if (msg instanceof Error) {
@@ -218,14 +222,16 @@ var buildRecord = (level, context, msg, getTimestamp, data) => {
       if (data !== void 0) logRecord.data = data;
     }
   } else {
-    logRecord.message = typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
+    if (msg instanceof Error) {
+      logRecord.error = serializeError(msg);
+    }
     if (data !== void 0) {
       logRecord.data = data instanceof Error ? serializeError(data) : data;
     }
   }
   return logRecord;
 };
-var createProdTransport = (config = {}) => {
+var createProdFormatter = (config = {}) => {
   const getTimestamp = config.timestamp === "epoch" ? () => Date.now() : () => (/* @__PURE__ */ new Date()).toISOString();
   const dest = config.dest ?? import_node_process2.default.stdout;
   return (level, context, msg, data) => {
@@ -252,10 +258,10 @@ var createProdTransport = (config = {}) => {
 
 // src/index.ts
 var createFiro = (config = {}, parentContext = []) => {
-  const useAllColors = config.useAllColors ?? true;
+  const useSafeColors = config.useSafeColors ?? false;
   const fill = (item) => ({
     ...item,
-    colorIndex: typeof item.colorIndex === "number" ? item.colorIndex : getColorIndex(item.key, useAllColors),
+    colorIndex: typeof item.colorIndex === "number" ? item.colorIndex : getColorIndex(item.key, useSafeColors),
     color: item.color,
     omitKey: item.omitKey ?? false
   });
@@ -264,8 +270,8 @@ var createFiro = (config = {}, parentContext = []) => {
     return [...context2, ...invokeContext.map(fill)];
   };
   const context = [...parentContext.map(fill)];
-  const transport = config.transport ?? (config.mode === "prod" ? createProdTransport(config.prodTransportConfig) : createDevTransport(config.devTransportConfig));
-  const minLevelName = config.mode === "prod" ? config.minLevelInProd ?? config.minLevel : config.minLevelInDev ?? config.minLevel;
+  const formatter = config.formatter ?? (config.mode === "prod" ? createProdFormatter(config.prodFormatterConfig) : createDevFormatter(config.devFormatterConfig));
+  const minLevelName = config.minLevel;
   const minLevel = LOG_LEVELS[minLevelName ?? "debug"];
   const getContext = () => context;
   const hasInContext = (key) => context.some((ctx) => ctx.key === key);
@@ -293,25 +299,25 @@ var createFiro = (config = {}, parentContext = []) => {
         const { value: extValue, ...opts } = value;
         return { key, value: extValue, ...opts };
       }
-      return { key, value, colorIndex: getColorIndex(key, useAllColors) };
+      return { key, value, colorIndex: getColorIndex(key, useSafeColors) };
     });
-    return createFiro({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
+    return createFiro({ formatter, minLevel: minLevelName, useSafeColors }, [...context, ...newItems]);
   };
   const debug = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.debug) return;
-    transport("debug", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+    formatter("debug", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
   };
   const info = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.info) return;
-    transport("info", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+    formatter("info", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
   };
   const warn = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.warn) return;
-    transport("warn", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+    formatter("warn", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
   };
   const error = (msgOrError, err, opts) => {
     if (minLevel > LOG_LEVELS.error) return;
-    transport("error", appendContextWithInvokeContext(context, opts?.ctx), msgOrError, err, opts);
+    formatter("error", appendContextWithInvokeContext(context, opts?.ctx), msgOrError, err, opts);
   };
   const logInstance = ((msg, data, opts) => {
     info(msg, data, opts);
@@ -332,7 +338,7 @@ var createFiro = (config = {}, parentContext = []) => {
 0 && (module.exports = {
   FIRO_COLORS,
   FiroUtils,
-  createDevTransport,
+  createDevFormatter,
   createFiro,
-  createProdTransport
+  createProdFormatter
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 /** Available log severity levels. */
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Numeric severity values for each log level, used for threshold filtering. */
 declare const LOG_LEVELS: {
     readonly debug: 20;
     readonly info: 30;
@@ -16,6 +17,8 @@ type ContextOptions = {
     color?: string;
     /** If true, the key name is hidden, and only the value is printed. */
     omitKey?: boolean;
+    /** Hide this context item in 'dev' or 'prod' mode. Useful for keeping traceIds out of dev output. */
+    hideIn?: 'dev' | 'prod';
 };
 /** A single key-value context entry. */
 type ContextItem = {
@@ -31,6 +34,7 @@ type ContextItemWithOptions = ContextItem & {
     colorIndex: number;
     omitKey: boolean;
     color?: string;
+    hideIn?: 'dev' | 'prod';
 };
 /** Options that can be passed to a single log call. */
 type LogOptions = {
@@ -40,7 +44,7 @@ type LogOptions = {
     ctx?: ContextItem[];
 };
 /** The signature of a function responsible for formatting and emitting log records. */
-type TransportFn = (level: LogLevel, context: ContextItemWithOptions[], message: string | Error | unknown, data?: Error | unknown, options?: LogOptions) => void;
+type FormatterFn = (level: LogLevel, context: ContextItemWithOptions[], message: string | Error | unknown, data?: Error | unknown, options?: LogOptions) => void;
 /** Named color palette for context badges. Use with `color` option: `{ color: FIRO_COLORS.skyBlue }` */
 declare const FIRO_COLORS: {
     readonly cyan: "36";
@@ -74,12 +78,21 @@ declare const FIRO_COLORS: {
     readonly tangerine: "38;5;208";
     readonly periwinkle: "38;5;147";
 };
-declare const getColorIndex: (str: string, useAllColors?: boolean) => number;
+/** Hash a string to a stable color palette index. Similar strings land on different colors. */
+declare const getColorIndex: (str: string, useSafeColors?: boolean) => number;
+/** Wrap text in an ANSI color escape sequence by palette index or raw ANSI code. */
 declare const colorize: (text: string, colorIndex: number, color?: string) => string;
+/** JSON.stringify replacer that converts BigInt values to strings. */
 declare const jsonReplacer: (_key: string, value: unknown) => unknown;
+/** Safely stringify any value to JSON with BigInt support. Falls back to `util.inspect` on circular references. */
 declare const safeStringify: (obj: unknown) => string;
+/** Coerce any value to an Error instance. If already an Error, returns as-is. */
 declare const wrapToError: (obj: unknown) => Error;
-declare const serializeError: (_err: unknown) => any;
+/** Serialize an error-like value to a plain object with `message`, `stack`, `name`, and recursively serialized `cause`. */
+declare const serializeError: (_err: unknown) => Record<string, unknown>;
+/** Extract a human-readable message string from any log input. Useful for building custom formatters. */
+declare const extractMessage: (msg: string | Error | unknown) => string;
+/** Wrap text in an ANSI color based on log level: red for error, yellow for warn, dim for debug. */
 declare const colorizeLevel: (level: LogLevel, text: string) => string;
 
 type utils_ContextExtension = ContextExtension;
@@ -88,41 +101,42 @@ type utils_ContextItemWithOptions = ContextItemWithOptions;
 type utils_ContextOptions = ContextOptions;
 type utils_ContextValue = ContextValue;
 declare const utils_FIRO_COLORS: typeof FIRO_COLORS;
+type utils_FormatterFn = FormatterFn;
 declare const utils_LOG_LEVELS: typeof LOG_LEVELS;
 type utils_LogLevel = LogLevel;
 type utils_LogOptions = LogOptions;
-type utils_TransportFn = TransportFn;
 declare const utils_colorize: typeof colorize;
 declare const utils_colorizeLevel: typeof colorizeLevel;
+declare const utils_extractMessage: typeof extractMessage;
 declare const utils_getColorIndex: typeof getColorIndex;
 declare const utils_jsonReplacer: typeof jsonReplacer;
 declare const utils_safeStringify: typeof safeStringify;
 declare const utils_serializeError: typeof serializeError;
 declare const utils_wrapToError: typeof wrapToError;
 declare namespace utils {
-  export { type utils_ContextExtension as ContextExtension, type utils_ContextItem as ContextItem, type utils_ContextItemWithOptions as ContextItemWithOptions, type utils_ContextOptions as ContextOptions, type utils_ContextValue as ContextValue, utils_FIRO_COLORS as FIRO_COLORS, utils_LOG_LEVELS as LOG_LEVELS, type utils_LogLevel as LogLevel, type utils_LogOptions as LogOptions, type utils_TransportFn as TransportFn, utils_colorize as colorize, utils_colorizeLevel as colorizeLevel, utils_getColorIndex as getColorIndex, utils_jsonReplacer as jsonReplacer, utils_safeStringify as safeStringify, utils_serializeError as serializeError, utils_wrapToError as wrapToError };
+  export { type utils_ContextExtension as ContextExtension, type utils_ContextItem as ContextItem, type utils_ContextItemWithOptions as ContextItemWithOptions, type utils_ContextOptions as ContextOptions, type utils_ContextValue as ContextValue, utils_FIRO_COLORS as FIRO_COLORS, type utils_FormatterFn as FormatterFn, utils_LOG_LEVELS as LOG_LEVELS, type utils_LogLevel as LogLevel, type utils_LogOptions as LogOptions, utils_colorize as colorize, utils_colorizeLevel as colorizeLevel, utils_extractMessage as extractMessage, utils_getColorIndex as getColorIndex, utils_jsonReplacer as jsonReplacer, utils_safeStringify as safeStringify, utils_serializeError as serializeError, utils_wrapToError as wrapToError };
 }
 
 /**
- * Configuration options for the development transport.
+ * Configuration options for the development formatter.
  */
-type DevTransportConfig = {
+type DevFormatterConfig = {
     /** The locale used for formatting the timestamp. Defaults to the system locale. */
     locale?: string;
     /** Standard Intl.DateTimeFormatOptions to customize the timestamp output. */
     timeOptions?: Intl.DateTimeFormatOptions;
 };
 /**
- * Creates a built-in transport optimized for local development.
+ * Creates a built-in formatter optimized for local development.
  * Emits colored, human-readable strings to stdout/stderr.
  *
- * @param config Optional configuration for the transport, like timestamp formats.
- * @returns A `TransportFn` that writes to the console.
+ * @param config Optional configuration for the formatter, like timestamp formats.
+ * @returns A `FormatterFn` that writes to the console.
  */
-declare const createDevTransport: (config?: DevTransportConfig) => TransportFn;
+declare const createDevFormatter: (config?: DevFormatterConfig) => FormatterFn;
 
 type TimestampFormat = 'iso' | 'epoch';
-type ProdTransportConfig = {
+type ProdFormatterConfig = {
     /** Timestamp format: 'iso' (default) for ISO 8601 string, 'epoch' for ms since Unix epoch. */
     timestamp?: TimestampFormat;
     /** Output destination. Any object with a `.write(string)` method. Defaults to `process.stdout`. */
@@ -131,33 +145,29 @@ type ProdTransportConfig = {
     };
 };
 /**
- * Creates a built-in transport optimized for production.
+ * Creates a built-in formatter optimized for production.
  * Emits strictly structured NDJSON (Newline Delimited JSON) to stdout.
  *
- * @returns A `TransportFn` that writes JSON to standard output.
+ * @returns A `FormatterFn` that writes JSON to standard output.
  */
-declare const createProdTransport: (config?: ProdTransportConfig) => TransportFn;
+declare const createProdFormatter: (config?: ProdFormatterConfig) => FormatterFn;
 
 /**
  * Configuration options for creating a logger instance.
  */
 type LoggerConfig = {
-    /** The minimum log level for both modes. Overridden by mode-specific thresholds. */
+    /** The minimum log level. */
     minLevel?: LogLevel;
-    /** Minimum log level to emit in 'dev' mode. */
-    minLevelInDev?: LogLevel;
-    /** Minimum log level to emit in 'prod' mode. */
-    minLevelInProd?: LogLevel;
-    /** Specifies the built-in transport to use. Defaults to 'dev'. */
+    /** Selects the built-in formatter. Defaults to 'dev'. */
     mode?: 'dev' | 'prod';
-    /** Provide a custom transport function to override the built-in behaviors. */
-    transport?: TransportFn;
-    /** Options for fine-tuning the built-in development transport (e.g. timestamp format). */
-    devTransportConfig?: DevTransportConfig;
-    /** Options for the built-in prod transport (e.g. timestamp format). */
-    prodTransportConfig?: ProdTransportConfig;
-    /** Use the full extended color palette (30 colors including 256-color) for auto-assigned context badges. Defaults to true. Set to false to restrict to 10 terminal-safe colors. */
-    useAllColors?: boolean;
+    /** Provide a custom formatter function to override the built-in behaviors. */
+    formatter?: FormatterFn;
+    /** Options for fine-tuning the built-in development formatter (e.g. timestamp format). */
+    devFormatterConfig?: DevFormatterConfig;
+    /** Options for the built-in prod formatter (e.g. timestamp format). */
+    prodFormatterConfig?: ProdFormatterConfig;
+    /** Restrict auto-assigned context badge colors to 10 terminal-safe colors. Defaults to false (all 30 palette colors are used). */
+    useSafeColors?: boolean;
 };
 /**
  * The logger instance returned by `createFiro`.
@@ -174,6 +184,8 @@ interface Firo {
     warn: (msg: string, data?: unknown, opts?: LogOptions) => void;
     /** Log an error object directly. */
     error(err: Error | unknown): void;
+    /** Log an error object with additional data. */
+    error(err: Error, data?: unknown, opts?: LogOptions): void;
     /** Log a message alongside an error or custom data object. */
     error(msg: string, err?: Error | unknown, opts?: LogOptions): void;
     /**
@@ -196,9 +208,9 @@ interface Firo {
 /**
  * Creates a new logger instance with the specified configuration.
  *
- * @param config Optional configuration for log levels, mode, and transports.
+ * @param config Optional configuration for log levels, format, and formatters.
  * @returns A fully configured `Firo` instance.
  */
 declare const createFiro: (config?: LoggerConfig, parentContext?: ContextItem[]) => Firo;
 
-export { type ContextExtension, type ContextItem, type ContextItemWithOptions, type ContextOptions, type ContextValue, type DevTransportConfig, FIRO_COLORS, type Firo, utils as FiroUtils, type LogLevel, type LogOptions, type LoggerConfig, type ProdTransportConfig, type TimestampFormat, type TransportFn, createDevTransport, createFiro, createProdTransport };
+export { type ContextExtension, type ContextItem, type ContextItemWithOptions, type ContextOptions, type ContextValue, type DevFormatterConfig, FIRO_COLORS, type Firo, utils as FiroUtils, type FormatterFn, type LogLevel, type LogOptions, type LoggerConfig, type ProdFormatterConfig, type TimestampFormat, createDevFormatter, createFiro, createProdFormatter };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 /** Available log severity levels. */
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Numeric severity values for each log level, used for threshold filtering. */
 declare const LOG_LEVELS: {
     readonly debug: 20;
     readonly info: 30;
@@ -16,6 +17,8 @@ type ContextOptions = {
     color?: string;
     /** If true, the key name is hidden, and only the value is printed. */
     omitKey?: boolean;
+    /** Hide this context item in 'dev' or 'prod' mode. Useful for keeping traceIds out of dev output. */
+    hideIn?: 'dev' | 'prod';
 };
 /** A single key-value context entry. */
 type ContextItem = {
@@ -31,6 +34,7 @@ type ContextItemWithOptions = ContextItem & {
     colorIndex: number;
     omitKey: boolean;
     color?: string;
+    hideIn?: 'dev' | 'prod';
 };
 /** Options that can be passed to a single log call. */
 type LogOptions = {
@@ -40,7 +44,7 @@ type LogOptions = {
     ctx?: ContextItem[];
 };
 /** The signature of a function responsible for formatting and emitting log records. */
-type TransportFn = (level: LogLevel, context: ContextItemWithOptions[], message: string | Error | unknown, data?: Error | unknown, options?: LogOptions) => void;
+type FormatterFn = (level: LogLevel, context: ContextItemWithOptions[], message: string | Error | unknown, data?: Error | unknown, options?: LogOptions) => void;
 /** Named color palette for context badges. Use with `color` option: `{ color: FIRO_COLORS.skyBlue }` */
 declare const FIRO_COLORS: {
     readonly cyan: "36";
@@ -74,12 +78,21 @@ declare const FIRO_COLORS: {
     readonly tangerine: "38;5;208";
     readonly periwinkle: "38;5;147";
 };
-declare const getColorIndex: (str: string, useAllColors?: boolean) => number;
+/** Hash a string to a stable color palette index. Similar strings land on different colors. */
+declare const getColorIndex: (str: string, useSafeColors?: boolean) => number;
+/** Wrap text in an ANSI color escape sequence by palette index or raw ANSI code. */
 declare const colorize: (text: string, colorIndex: number, color?: string) => string;
+/** JSON.stringify replacer that converts BigInt values to strings. */
 declare const jsonReplacer: (_key: string, value: unknown) => unknown;
+/** Safely stringify any value to JSON with BigInt support. Falls back to `util.inspect` on circular references. */
 declare const safeStringify: (obj: unknown) => string;
+/** Coerce any value to an Error instance. If already an Error, returns as-is. */
 declare const wrapToError: (obj: unknown) => Error;
-declare const serializeError: (_err: unknown) => any;
+/** Serialize an error-like value to a plain object with `message`, `stack`, `name`, and recursively serialized `cause`. */
+declare const serializeError: (_err: unknown) => Record<string, unknown>;
+/** Extract a human-readable message string from any log input. Useful for building custom formatters. */
+declare const extractMessage: (msg: string | Error | unknown) => string;
+/** Wrap text in an ANSI color based on log level: red for error, yellow for warn, dim for debug. */
 declare const colorizeLevel: (level: LogLevel, text: string) => string;
 
 type utils_ContextExtension = ContextExtension;
@@ -88,41 +101,42 @@ type utils_ContextItemWithOptions = ContextItemWithOptions;
 type utils_ContextOptions = ContextOptions;
 type utils_ContextValue = ContextValue;
 declare const utils_FIRO_COLORS: typeof FIRO_COLORS;
+type utils_FormatterFn = FormatterFn;
 declare const utils_LOG_LEVELS: typeof LOG_LEVELS;
 type utils_LogLevel = LogLevel;
 type utils_LogOptions = LogOptions;
-type utils_TransportFn = TransportFn;
 declare const utils_colorize: typeof colorize;
 declare const utils_colorizeLevel: typeof colorizeLevel;
+declare const utils_extractMessage: typeof extractMessage;
 declare const utils_getColorIndex: typeof getColorIndex;
 declare const utils_jsonReplacer: typeof jsonReplacer;
 declare const utils_safeStringify: typeof safeStringify;
 declare const utils_serializeError: typeof serializeError;
 declare const utils_wrapToError: typeof wrapToError;
 declare namespace utils {
-  export { type utils_ContextExtension as ContextExtension, type utils_ContextItem as ContextItem, type utils_ContextItemWithOptions as ContextItemWithOptions, type utils_ContextOptions as ContextOptions, type utils_ContextValue as ContextValue, utils_FIRO_COLORS as FIRO_COLORS, utils_LOG_LEVELS as LOG_LEVELS, type utils_LogLevel as LogLevel, type utils_LogOptions as LogOptions, type utils_TransportFn as TransportFn, utils_colorize as colorize, utils_colorizeLevel as colorizeLevel, utils_getColorIndex as getColorIndex, utils_jsonReplacer as jsonReplacer, utils_safeStringify as safeStringify, utils_serializeError as serializeError, utils_wrapToError as wrapToError };
+  export { type utils_ContextExtension as ContextExtension, type utils_ContextItem as ContextItem, type utils_ContextItemWithOptions as ContextItemWithOptions, type utils_ContextOptions as ContextOptions, type utils_ContextValue as ContextValue, utils_FIRO_COLORS as FIRO_COLORS, type utils_FormatterFn as FormatterFn, utils_LOG_LEVELS as LOG_LEVELS, type utils_LogLevel as LogLevel, type utils_LogOptions as LogOptions, utils_colorize as colorize, utils_colorizeLevel as colorizeLevel, utils_extractMessage as extractMessage, utils_getColorIndex as getColorIndex, utils_jsonReplacer as jsonReplacer, utils_safeStringify as safeStringify, utils_serializeError as serializeError, utils_wrapToError as wrapToError };
 }
 
 /**
- * Configuration options for the development transport.
+ * Configuration options for the development formatter.
  */
-type DevTransportConfig = {
+type DevFormatterConfig = {
     /** The locale used for formatting the timestamp. Defaults to the system locale. */
     locale?: string;
     /** Standard Intl.DateTimeFormatOptions to customize the timestamp output. */
     timeOptions?: Intl.DateTimeFormatOptions;
 };
 /**
- * Creates a built-in transport optimized for local development.
+ * Creates a built-in formatter optimized for local development.
  * Emits colored, human-readable strings to stdout/stderr.
  *
- * @param config Optional configuration for the transport, like timestamp formats.
- * @returns A `TransportFn` that writes to the console.
+ * @param config Optional configuration for the formatter, like timestamp formats.
+ * @returns A `FormatterFn` that writes to the console.
  */
-declare const createDevTransport: (config?: DevTransportConfig) => TransportFn;
+declare const createDevFormatter: (config?: DevFormatterConfig) => FormatterFn;
 
 type TimestampFormat = 'iso' | 'epoch';
-type ProdTransportConfig = {
+type ProdFormatterConfig = {
     /** Timestamp format: 'iso' (default) for ISO 8601 string, 'epoch' for ms since Unix epoch. */
     timestamp?: TimestampFormat;
     /** Output destination. Any object with a `.write(string)` method. Defaults to `process.stdout`. */
@@ -131,33 +145,29 @@ type ProdTransportConfig = {
     };
 };
 /**
- * Creates a built-in transport optimized for production.
+ * Creates a built-in formatter optimized for production.
  * Emits strictly structured NDJSON (Newline Delimited JSON) to stdout.
  *
- * @returns A `TransportFn` that writes JSON to standard output.
+ * @returns A `FormatterFn` that writes JSON to standard output.
  */
-declare const createProdTransport: (config?: ProdTransportConfig) => TransportFn;
+declare const createProdFormatter: (config?: ProdFormatterConfig) => FormatterFn;
 
 /**
  * Configuration options for creating a logger instance.
  */
 type LoggerConfig = {
-    /** The minimum log level for both modes. Overridden by mode-specific thresholds. */
+    /** The minimum log level. */
     minLevel?: LogLevel;
-    /** Minimum log level to emit in 'dev' mode. */
-    minLevelInDev?: LogLevel;
-    /** Minimum log level to emit in 'prod' mode. */
-    minLevelInProd?: LogLevel;
-    /** Specifies the built-in transport to use. Defaults to 'dev'. */
+    /** Selects the built-in formatter. Defaults to 'dev'. */
     mode?: 'dev' | 'prod';
-    /** Provide a custom transport function to override the built-in behaviors. */
-    transport?: TransportFn;
-    /** Options for fine-tuning the built-in development transport (e.g. timestamp format). */
-    devTransportConfig?: DevTransportConfig;
-    /** Options for the built-in prod transport (e.g. timestamp format). */
-    prodTransportConfig?: ProdTransportConfig;
-    /** Use the full extended color palette (30 colors including 256-color) for auto-assigned context badges. Defaults to true. Set to false to restrict to 10 terminal-safe colors. */
-    useAllColors?: boolean;
+    /** Provide a custom formatter function to override the built-in behaviors. */
+    formatter?: FormatterFn;
+    /** Options for fine-tuning the built-in development formatter (e.g. timestamp format). */
+    devFormatterConfig?: DevFormatterConfig;
+    /** Options for the built-in prod formatter (e.g. timestamp format). */
+    prodFormatterConfig?: ProdFormatterConfig;
+    /** Restrict auto-assigned context badge colors to 10 terminal-safe colors. Defaults to false (all 30 palette colors are used). */
+    useSafeColors?: boolean;
 };
 /**
  * The logger instance returned by `createFiro`.
@@ -174,6 +184,8 @@ interface Firo {
     warn: (msg: string, data?: unknown, opts?: LogOptions) => void;
     /** Log an error object directly. */
     error(err: Error | unknown): void;
+    /** Log an error object with additional data. */
+    error(err: Error, data?: unknown, opts?: LogOptions): void;
     /** Log a message alongside an error or custom data object. */
     error(msg: string, err?: Error | unknown, opts?: LogOptions): void;
     /**
@@ -196,9 +208,9 @@ interface Firo {
 /**
  * Creates a new logger instance with the specified configuration.
  *
- * @param config Optional configuration for log levels, mode, and transports.
+ * @param config Optional configuration for log levels, format, and formatters.
  * @returns A fully configured `Firo` instance.
  */
 declare const createFiro: (config?: LoggerConfig, parentContext?: ContextItem[]) => Firo;
 
-export { type ContextExtension, type ContextItem, type ContextItemWithOptions, type ContextOptions, type ContextValue, type DevTransportConfig, FIRO_COLORS, type Firo, utils as FiroUtils, type LogLevel, type LogOptions, type LoggerConfig, type ProdTransportConfig, type TimestampFormat, type TransportFn, createDevTransport, createFiro, createProdTransport };
+export { type ContextExtension, type ContextItem, type ContextItemWithOptions, type ContextOptions, type ContextValue, type DevFormatterConfig, FIRO_COLORS, type Firo, utils as FiroUtils, type FormatterFn, type LogLevel, type LogOptions, type LoggerConfig, type ProdFormatterConfig, type TimestampFormat, createDevFormatter, createFiro, createProdFormatter };

package/dist/index.js

@@ -11,6 +11,7 @@ __export(utils_exports, {
   LOG_LEVELS: () => LOG_LEVELS,
   colorize: () => colorize,
   colorizeLevel: () => colorizeLevel,
+  extractMessage: () => extractMessage,
   getColorIndex: () => getColorIndex,
   jsonReplacer: () => jsonReplacer,
   safeStringify: () => safeStringify,
@@ -60,12 +61,12 @@ var FIRO_COLORS = {
 };
 var COLORS_LIST = Object.values(FIRO_COLORS);
 var SAFE_COLORS_COUNT = 10;
-var getColorIndex = (str, useAllColors = false) => {
+var getColorIndex = (str, useSafeColors = false) => {
   let hash = 0;
   for (let i = 0, len = str.length; i < len; i++) {
     hash = str.charCodeAt(i) + ((hash << 5) - hash);
   }
-  const range = useAllColors ? COLORS_LIST.length : SAFE_COLORS_COUNT;
+  const range = useSafeColors ? SAFE_COLORS_COUNT : COLORS_LIST.length;
   return Math.abs(hash % range);
 };
 var colorize = (text, colorIndex, color) => {
@@ -88,13 +89,18 @@ var wrapToError = (obj) => {
 };
 var serializeError = (_err) => {
   const err = wrapToError(_err);
-  return {
+  const result = {
     message: err.message,
     stack: err.stack,
     name: err.name,
     ...err
   };
+  if (err.cause !== void 0) {
+    result.cause = err.cause instanceof Error ? serializeError(err.cause) : err.cause;
+  }
+  return result;
 };
+var extractMessage = (msg) => typeof msg === "string" ? msg : msg instanceof Error ? msg.message : typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
 var colorizeLevel = (level, text) => {
   if (level === "info") return text;
   switch (level) {
@@ -112,10 +118,10 @@ var colorizeLevel = (level, text) => {
   }
 };
 
-// src/transport_dev.ts
+// src/formatter_dev.ts
 import { inspect as inspect2 } from "util";
 import process from "process";
-var createDevTransport = (config = {}) => {
+var createDevFormatter = (config = {}) => {
   const locale = config.locale ?? void 0;
   const timeOpts = {
     hour12: false,
@@ -125,10 +131,10 @@ var createDevTransport = (config = {}) => {
     fractionalSecondDigits: 3,
     ...config.timeOptions || {}
   };
-  const transport = (level, context, msg, data, opts) => {
+  const formatter = (level, context, msg, data, opts) => {
     const now = /* @__PURE__ */ new Date();
     const timestamp = now.toLocaleTimeString(locale, timeOpts);
-    const contextStr = context.map((ctx) => {
+    const contextStr = context.filter((ctx) => ctx.hideIn !== "dev").map((ctx) => {
       const key = ctx.omitKey ? "" : `${ctx.key}:`;
       const content = `${key}${ctx.value}`;
       return colorize(`[${content}]`, ctx.colorIndex, ctx.color);
@@ -155,25 +161,23 @@ var createDevTransport = (config = {}) => {
     if (level === "error") process.stderr.write(finalLine);
     else process.stdout.write(finalLine);
   };
-  return transport;
+  return formatter;
 };
 
-// src/transport_prod.ts
+// src/formatter_prod.ts
 import { inspect as inspect3 } from "util";
 import process2 from "process";
 var buildRecord = (level, context, msg, getTimestamp, data) => {
-  const contextObj = context.reduce((acc, item) => {
-    acc[item.key] = item.value;
-    return acc;
-  }, {});
   const logRecord = {
     timestamp: getTimestamp(),
-    level,
-    ...contextObj
+    level
   };
+  for (let i = 0, len = context.length; i < len; i++) {
+    if (context[i].hideIn === "prod") continue;
+    logRecord[context[i].key] = context[i].value;
+  }
+  logRecord.message = extractMessage(msg);
   if (level === "error") {
-    const message = typeof msg === "string" ? msg : msg instanceof Error ? msg.message : typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
-    logRecord.message = message;
     if (data instanceof Error) {
       logRecord.error = serializeError(data);
     } else if (msg instanceof Error) {
@@ -184,14 +188,16 @@ var buildRecord = (level, context, msg, getTimestamp, data) => {
       if (data !== void 0) logRecord.data = data;
     }
   } else {
-    logRecord.message = typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
+    if (msg instanceof Error) {
+      logRecord.error = serializeError(msg);
+    }
     if (data !== void 0) {
       logRecord.data = data instanceof Error ? serializeError(data) : data;
     }
   }
   return logRecord;
 };
-var createProdTransport = (config = {}) => {
+var createProdFormatter = (config = {}) => {
   const getTimestamp = config.timestamp === "epoch" ? () => Date.now() : () => (/* @__PURE__ */ new Date()).toISOString();
   const dest = config.dest ?? process2.stdout;
   return (level, context, msg, data) => {
@@ -218,10 +224,10 @@ var createProdTransport = (config = {}) => {
 
 // src/index.ts
 var createFiro = (config = {}, parentContext = []) => {
-  const useAllColors = config.useAllColors ?? true;
+  const useSafeColors = config.useSafeColors ?? false;
   const fill = (item) => ({
     ...item,
-    colorIndex: typeof item.colorIndex === "number" ? item.colorIndex : getColorIndex(item.key, useAllColors),
+    colorIndex: typeof item.colorIndex === "number" ? item.colorIndex : getColorIndex(item.key, useSafeColors),
     color: item.color,
     omitKey: item.omitKey ?? false
   });
@@ -230,8 +236,8 @@ var createFiro = (config = {}, parentContext = []) => {
     return [...context2, ...invokeContext.map(fill)];
   };
   const context = [...parentContext.map(fill)];
-  const transport = config.transport ?? (config.mode === "prod" ? createProdTransport(config.prodTransportConfig) : createDevTransport(config.devTransportConfig));
-  const minLevelName = config.mode === "prod" ? config.minLevelInProd ?? config.minLevel : config.minLevelInDev ?? config.minLevel;
+  const formatter = config.formatter ?? (config.mode === "prod" ? createProdFormatter(config.prodFormatterConfig) : createDevFormatter(config.devFormatterConfig));
+  const minLevelName = config.minLevel;
   const minLevel = LOG_LEVELS[minLevelName ?? "debug"];
   const getContext = () => context;
   const hasInContext = (key) => context.some((ctx) => ctx.key === key);
@@ -259,25 +265,25 @@ var createFiro = (config = {}, parentContext = []) => {
         const { value: extValue, ...opts } = value;
         return { key, value: extValue, ...opts };
       }
-      return { key, value, colorIndex: getColorIndex(key, useAllColors) };
+      return { key, value, colorIndex: getColorIndex(key, useSafeColors) };
     });
-    return createFiro({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
+    return createFiro({ formatter, minLevel: minLevelName, useSafeColors }, [...context, ...newItems]);
   };
   const debug = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.debug) return;
-    transport("debug", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+    formatter("debug", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
   };
   const info = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.info) return;
-    transport("info", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+    formatter("info", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
   };
   const warn = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.warn) return;
-    transport("warn", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+    formatter("warn", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
   };
   const error = (msgOrError, err, opts) => {
     if (minLevel > LOG_LEVELS.error) return;
-    transport("error", appendContextWithInvokeContext(context, opts?.ctx), msgOrError, err, opts);
+    formatter("error", appendContextWithInvokeContext(context, opts?.ctx), msgOrError, err, opts);
   };
   const logInstance = ((msg, data, opts) => {
     info(msg, data, opts);
@@ -297,7 +303,7 @@ var createFiro = (config = {}, parentContext = []) => {
 export {
   FIRO_COLORS,
   utils_exports as FiroUtils,
-  createDevTransport,
+  createDevFormatter,
   createFiro,
-  createProdTransport
+  createProdFormatter
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fend/firo",
-  "version": "0.0.5",
-  "description": "Elegant logger for Node.js, Bun and Deno with brilliant DX.",
+  "version": "0.0.7",
+  "description": "Elegant logger for Node.js, Bun and Deno with brilliant DX and pino-grade speed",
   "keywords": [
     "firo",
     "logger",
@@ -42,6 +42,8 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "bumpp": "^11.0.1",
+    "pino": "^10.3.1",
     "tsup": "^8.5.1",
     "tsx": "^4.0.0",
     "typescript": "^5.9.3"
@@ -52,6 +54,7 @@
     "check": "tsc --noEmit && node --import tsx --test test/*.test.ts",
     "typecheck": "tsc --noEmit",
     "demo": "tsx demo.ts",
-    "bench": "tsx benchmark/prod.ts > /dev/null"
+    "bench": "tsx benchmark/prod.ts > /dev/null",
+    "bump": "bumpp --files package.json --files jsr.json --execute \"pnpm check && pnpm build && npm publish --dry-run --access public && deno publish --dry-run\" --commit \"v%s\" --no-push"
   }
 }