@fend/firo 0.0.4 → 0.0.6

package/README.md

@@ -54,9 +54,9 @@ deno add jsr:@fend/firo
 ## Quick start
 
 ```ts
-import { createLogger } from '@fend/firo'
+import { createFiro } from '@fend/firo'
 
-const log = createLogger()
+const log = createFiro()
 
 // log() is shorthand for log.info()
 log('Server started')
@@ -79,7 +79,7 @@ Dev output:
 Colored, human-readable. Errors go to `stderr`, everything else to `stdout`.
 
 ```ts
-const log = createLogger({ mode: 'dev' })
+const log = createFiro({ mode: 'dev' })
 ```
 
 ### Prod
@@ -87,7 +87,7 @@ const log = createLogger({ mode: 'dev' })
 Structured NDJSON. Everything goes to `stdout` — let your infrastructure route it.
 
 ```ts
-const log = createLogger({ mode: 'prod' })
+const log = createFiro({ mode: 'prod' })
 
 log.info('Request handled', { status: 200 })
 // {"timestamp":"2024-01-15T14:32:01.204Z","level":"info","message":"Request handled","data":{"status":200}}
@@ -101,9 +101,9 @@ The best way to use **firo** in web frameworks is to store a child logger in `As
 
 ```ts
 import { AsyncLocalStorage } from 'node:util'
-import { createLogger } from '@fend/firo'
+import { createFiro } from '@fend/firo'
 
-const logger = createLogger()
+const logger = createFiro()
 const storage = new AsyncLocalStorage()
 
 // Middleware example
@@ -140,13 +140,13 @@ Debug lines are dimmed in dev mode to reduce visual noise.
 
 ```ts
 // Suppress debug in dev, keep everything in prod
-const log = createLogger({
+const log = createFiro({
   minLevelInDev: 'info',
   minLevelInProd: 'warn',
 })
 
 // Or a single threshold for both modes
-const log = createLogger({ minLevel: 'warn' })
+const log = createFiro({ minLevel: 'warn' })
 ```
 
 ## Context
@@ -154,7 +154,7 @@ const log = createLogger({ minLevel: 'warn' })
 Attach persistent key/value pairs to a logger instance. They appear in every log line.
 
 ```ts
-const log = createLogger()
+const log = createFiro()
 
 log.addContext('service', 'auth')
 log.addContext('env', 'production')
@@ -171,7 +171,7 @@ log.info('Started')
 log.addContext({ key: 'userId', value: 'u-789', omitKey: true })
 // renders as [u-789] instead of [userId:u-789]
 
-// Pin a specific color (0–9)
+// Pin a specific color by palette index (0–29)
 log.addContext({ key: 'region', value: 'west', colorIndex: 3 })
 
 // Use any ANSI color — 256-color, truecolor, anything
@@ -196,7 +196,7 @@ const ctx = log.getContext() // ContextItem[]
 Create a scoped logger that inherits the parent's context at the moment of creation. Parent and child are fully isolated — mutations on one do not affect the other.
 
 ```ts
-const log = createLogger()
+const log = createFiro()
 log.addContext('service', 'api')
 
 const reqLog = log.child({ requestId: 'req-123', method: 'POST' })
@@ -239,7 +239,8 @@ log.error('Payment failed', err, {
 `error()` accepts multiple call signatures:
 
 ```ts
-// Message only
+// 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
@@ -248,6 +249,9 @@ 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)
 ```
@@ -267,7 +271,23 @@ const myTransport: TransportFn = (level, context, msg, data, opts) => {
   // opts:    LogOptions | undefined
 }
 
-const log = createLogger({ transport: myTransport })
+const log = createFiro({ transport: myTransport })
+```
+
+### FiroUtils
+
+`FiroUtils` exposes helper functions useful for building custom transports:
+
+```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)     // wrap text in ANSI color by palette index
+FiroUtils.colorizeLevel(level, t) // wrap text in level color (red/yellow/dim)
 ```
 
 ## Dev transport options
@@ -275,9 +295,9 @@ const log = createLogger({ transport: myTransport })
 Fine-tune the dev transport's timestamp format. For example, to remove seconds and milliseconds:
 
 ```ts
-import { createLogger } from '@fend/firo'
+import { createFiro } from '@fend/firo'
 
-const log = createLogger({
+const log = createFiro({
   devTransportConfig: {
     timeOptions: {
       hour: '2-digit', 
@@ -289,6 +309,45 @@ const log = createLogger({
 })
 ```
 
+## Prod transport options
+
+Configure the prod (JSON) transport's timestamp format:
+
+```ts
+// Epoch ms (faster, same as pino)
+const log = createFiro({
+  mode: 'prod',
+  prodTransportConfig: { timestamp: 'epoch' }
+})
+// {"timestamp":1711100000000,"level":"info","message":"hello"}
+
+// ISO 8601 (default, human-readable)
+const log = createFiro({ mode: 'prod' })
+// {"timestamp":"2024-01-15T14:32:01.204Z","level":"info","message":"hello"}
+```
+
+### Custom destination
+
+By default, prod transport writes to `process.stdout`. You can redirect output to any object with a `.write(string)` method:
+
+```ts
+import { createFiro } from '@fend/firo'
+import { createWriteStream } from 'node:fs'
+
+// Write to a file
+const log = createFiro({
+  mode: 'prod',
+  prodTransportConfig: { 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 }) }
+})
+```
+
 ## Color palette
 
 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.
@@ -297,14 +356,14 @@ Most loggers give you monochrome walls of text. firo gives you **30 handpicked c
 
 ### How it works
 
-By default, firo auto-assigns colors from 10 terminal-safe base colors using a hash of the context key. Similar keys like `user-1` and `user-2` land on different colors automatically.
+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.
 
-But the real fun starts when you reach for `FIRO_COLORS` — a named palette of 30 colors with full IDE autocomplete:
+You can also pin a specific color using `FIRO_COLORS` — a named palette with full IDE autocomplete:
 
 ```ts
-import { createLogger, FIRO_COLORS } from '@fend/firo'
+import { createFiro, FIRO_COLORS } from '@fend/firo'
 
-const log = createLogger()
+const log = createFiro()
 
 log.addContext('region', { value: 'west', color: FIRO_COLORS.coral })
 log.addContext('service', { value: 'auth', color: FIRO_COLORS.skyBlue })
@@ -322,18 +381,12 @@ log.addContext('trace', { value: 'abc', color: '38;5;214' })         // 256-colo
 log.addContext('span', { value: 'xyz', color: '38;2;255;105;180' })  // truecolor pink
 ```
 
-### Use all 30 colors for auto-hash
+### Restrict to safe colors
 
-By default, auto-hash only picks from the 10 basic terminal-safe colors. If your terminal supports 256 colors (most modern terminals do), unleash the full palette:
+If your terminal doesn't support 256 colors, you can restrict auto-hash to 10 basic terminal-safe colors:
 
 ```ts
-const log = createLogger({ useAllColors: true })
-
-// Now every context key auto-gets one of 30 distinct colors
-log.addContext('service', 'api')
-log.addContext('region', 'west')
-log.addContext('pod', 'web-3')
-// Each badge is a different, beautiful color — no configuration needed
+const log = createFiro({ useAllColors: false })
 ```
 
 ## Why not pino?
@@ -354,6 +407,35 @@ The problem with pino is development. Its default output is raw JSON — one gia
 
 In prod it emits clean NDJSON, same as pino. Your log aggregator won't know the difference.
 
+## Performance
+
+Prod mode (NDJSON) with `timestamp: 'epoch'`, Apple M1, Node.js 25. Average time per 100K log lines (lower is better):
+
+| 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  |
+
+For comparison, here's [pino's own benchmark](https://github.com/pinojs/pino/blob/main/docs/benchmarks.md) (100K `"hello world"` logs):
+
+| Logger           | ms     |
+| ---------------- | ------ |
+| pino             | 114.8  |
+| **firo**         | **127.8** |
+| bole             | 172.7  |
+| pino (NodeStream)| 159.2  |
+| debug            | 220.5  |
+| winston          | 270.2  |
+| bunyan           | 377.4  |
+
+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.
+
+Run it yourself: `pnpm bench`
+
 ## API reference
 
 ### Logger methods
@@ -369,8 +451,9 @@ In prod it emits clean NDJSON, same as pino. Your log aggregator won't know the
 | `addContext(item)` | Add a context entry (object form) |
 | `removeFromContext(key)` | Remove a context entry by key |
 | `getContext()` | Return the current context array |
+| `hasInContext(key)` | Check if a context key exists |
 
-### `createLogger(config?)`
+### `createFiro(config?)`
 
 | Option | Type | Default | Description |
 |---|---|---|---|
@@ -380,7 +463,8 @@ In prod it emits clean NDJSON, same as pino. Your log aggregator won't know the
 | `minLevelInProd` | `LogLevel` | — | Overrides `minLevel` in prod mode |
 | `transport` | `TransportFn` | — | Custom transport, overrides `mode` |
 | `devTransportConfig` | `DevTransportConfig` | — | Options for the built-in dev transport |
-| `useAllColors` | `boolean` | `false` | Use all 30 palette colors for auto-hash (instead of 10 safe) |
+| `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) |
 
 ## License
 

package/dist/index.cjs

@@ -31,13 +31,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   FIRO_COLORS: () => FIRO_COLORS,
+  FiroUtils: () => utils_exports,
   createDevTransport: () => createDevTransport,
-  createJsonTransport: () => createJsonTransport,
-  createLogger: () => createLogger
+  createFiro: () => createFiro,
+  createProdTransport: () => createProdTransport
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/utils.ts
+var utils_exports = {};
+__export(utils_exports, {
+  FIRO_COLORS: () => FIRO_COLORS,
+  LOG_LEVELS: () => LOG_LEVELS,
+  colorize: () => colorize,
+  colorizeLevel: () => colorizeLevel,
+  extractMessage: () => extractMessage,
+  getColorIndex: () => getColorIndex,
+  jsonReplacer: () => jsonReplacer,
+  safeStringify: () => safeStringify,
+  serializeError: () => serializeError,
+  wrapToError: () => wrapToError
+});
+var import_node_util = require("util");
 var LOG_LEVELS = {
   debug: 20,
   info: 30,
@@ -92,6 +107,34 @@ var colorize = (text, colorIndex, color) => {
   const code = color ?? (COLORS_LIST[colorIndex] || COLORS_LIST[colorIndex % SAFE_COLORS_COUNT]);
   return `\x1B[${code}m${text}\x1B[0m`;
 };
+var jsonReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
+var safeStringify = (obj) => {
+  try {
+    return JSON.stringify(obj, jsonReplacer);
+  } catch {
+    return (0, import_node_util.inspect)(obj);
+  }
+};
+var wrapToError = (obj) => {
+  if (obj instanceof Error) return obj;
+  return new Error(
+    typeof obj === "object" && obj !== null ? safeStringify(obj) : String(obj)
+  );
+};
+var serializeError = (_err) => {
+  const err = wrapToError(_err);
+  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) {
@@ -109,8 +152,8 @@ var colorizeLevel = (level, text) => {
   }
 };
 
-// src/transports.ts
-var import_node_util = require("util");
+// src/transport_dev.ts
+var import_node_util2 = require("util");
 var import_node_process = __toESM(require("process"), 1);
 var createDevTransport = (config = {}) => {
   const locale = config.locale ?? void 0;
@@ -138,9 +181,9 @@ var createDevTransport = (config = {}) => {
     let dataStr = "";
     if (data !== void 0) {
       const inspectOptions = opts?.pretty ? { compact: false, colors: true, depth: null } : { compact: true, breakLength: Infinity, colors: true, depth: null };
-      dataStr = (0, import_node_util.inspect)(data, inspectOptions);
+      dataStr = (0, import_node_util2.inspect)(data, inspectOptions);
     }
-    const msgStr = typeof msg === "object" && msg !== null ? (0, import_node_util.inspect)(msg, { colors: true, compact: true, breakLength: Infinity }) : String(msg);
+    const msgStr = typeof msg === "object" && msg !== null ? (0, import_node_util2.inspect)(msg, { colors: true, compact: true, breakLength: Infinity }) : String(msg);
     const parts = [
       `[${timestamp}]`,
       // Normal (not dimmed)
@@ -154,42 +197,20 @@ var createDevTransport = (config = {}) => {
   };
   return transport;
 };
-var jsonReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
-var safeStringify = (obj) => {
-  try {
-    return JSON.stringify(obj, jsonReplacer);
-  } catch {
-    return (0, import_node_util.inspect)(obj);
-  }
-};
-var wrapToError = (obj) => {
-  if (obj instanceof Error) return obj;
-  return new Error(
-    typeof obj === "object" && obj !== null ? safeStringify(obj) : String(obj)
-  );
-};
-var serializeError = (_err) => {
-  const err = wrapToError(_err);
-  return {
-    message: err.message,
-    stack: err.stack,
-    name: err.name,
-    ...err
-  };
-};
-var buildRecord = (level, context, msg, data) => {
-  const contextObj = context.reduce((acc, item) => {
-    acc[item.key] = item.value;
-    return acc;
-  }, {});
+
+// src/transport_prod.ts
+var import_node_util3 = require("util");
+var import_node_process2 = __toESM(require("process"), 1);
+var buildRecord = (level, context, msg, getTimestamp, data) => {
   const logRecord = {
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    level,
-    ...contextObj
+    timestamp: getTimestamp(),
+    level
   };
+  for (let i = 0, len = context.length; i < len; i++) {
+    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) {
@@ -200,21 +221,25 @@ var buildRecord = (level, context, msg, 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 createJsonTransport = () => {
+var createProdTransport = (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) => {
-    const record = buildRecord(level, context, msg, data);
+    const record = buildRecord(level, context, msg, getTimestamp, data);
     let line;
     try {
       line = JSON.stringify(record, jsonReplacer) + "\n";
     } catch {
-      if (record.data) record.data = (0, import_node_util.inspect)(record.data);
+      if (record.data) record.data = (0, import_node_util3.inspect)(record.data);
       try {
         line = JSON.stringify(record, jsonReplacer) + "\n";
       } catch {
@@ -226,28 +251,25 @@ var createJsonTransport = () => {
         }) + "\n";
       }
     }
-    import_node_process.default.stdout.write(line);
+    dest.write(line);
   };
 };
 
 // src/index.ts
-var fillContextItem = (item, useAllColors = false) => {
-  return {
+var createFiro = (config = {}, parentContext = []) => {
+  const useAllColors = config.useAllColors ?? true;
+  const fill = (item) => ({
     ...item,
     colorIndex: typeof item.colorIndex === "number" ? item.colorIndex : getColorIndex(item.key, useAllColors),
     color: item.color,
     omitKey: item.omitKey ?? false
-  };
-};
-var createLoggerInternal = (config, parentContext) => {
-  const useAllColors = config.useAllColors ?? false;
-  const fill = (item) => fillContextItem(item, useAllColors);
+  });
   const appendContextWithInvokeContext = (context2, invokeContext) => {
     if (!invokeContext || invokeContext.length === 0) return context2;
     return [...context2, ...invokeContext.map(fill)];
   };
   const context = [...parentContext.map(fill)];
-  const transport = config.transport ?? (config.mode === "prod" ? createJsonTransport() : createDevTransport(config.devTransportConfig));
+  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 minLevel = LOG_LEVELS[minLevelName ?? "debug"];
   const getContext = () => context;
@@ -278,7 +300,7 @@ var createLoggerInternal = (config, parentContext) => {
       }
       return { key, value, colorIndex: getColorIndex(key, useAllColors) };
     });
-    return createLoggerInternal({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
+    return createFiro({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
   };
   const debug = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.debug) return;
@@ -311,13 +333,11 @@ var createLoggerInternal = (config, parentContext) => {
     removeFromContext: removeKeyFromContext
   });
 };
-var createLogger = (config = {}) => {
-  return createLoggerInternal(config, []);
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FIRO_COLORS,
+  FiroUtils,
   createDevTransport,
-  createJsonTransport,
-  createLogger
+  createFiro,
+  createProdTransport
 });

package/dist/index.d.cts

@@ -1,5 +1,12 @@
 /** 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;
+    readonly warn: 40;
+    readonly error: 50;
+};
 /** Primitive types allowed as context values. */
 type ContextValue = string | number | boolean | null | undefined;
 /** Options to customize how a context item is rendered. */
@@ -68,6 +75,44 @@ declare const FIRO_COLORS: {
     readonly tangerine: "38;5;208";
     readonly periwinkle: "38;5;147";
 };
+/** Hash a string to a stable color palette index. Similar strings land on different colors. */
+declare const getColorIndex: (str: string, useAllColors?: 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;
+/** 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 transports. */
+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;
+type utils_ContextItem = ContextItem;
+type utils_ContextItemWithOptions = ContextItemWithOptions;
+type utils_ContextOptions = ContextOptions;
+type utils_ContextValue = ContextValue;
+declare const utils_FIRO_COLORS: typeof FIRO_COLORS;
+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_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.
@@ -86,13 +131,23 @@ type DevTransportConfig = {
  * @returns A `TransportFn` that writes to the console.
  */
 declare const createDevTransport: (config?: DevTransportConfig) => TransportFn;
+
+type TimestampFormat = 'iso' | 'epoch';
+type ProdTransportConfig = {
+    /** 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`. */
+    dest?: {
+        write(s: string): unknown;
+    };
+};
 /**
  * Creates a built-in transport optimized for production.
  * Emits strictly structured NDJSON (Newline Delimited JSON) to stdout.
  *
  * @returns A `TransportFn` that writes JSON to standard output.
  */
-declare const createJsonTransport: () => TransportFn;
+declare const createProdTransport: (config?: ProdTransportConfig) => TransportFn;
 
 /**
  * Configuration options for creating a logger instance.
@@ -110,11 +165,13 @@ type LoggerConfig = {
     transport?: TransportFn;
     /** Options for fine-tuning the built-in development transport (e.g. timestamp format). */
     devTransportConfig?: DevTransportConfig;
-    /** Use the full extended color palette (30 colors including 256-color) for auto-assigned context badges. Defaults to false (safe 10-color palette). */
+    /** 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;
 };
 /**
- * The logger instance returned by `createLogger`.
+ * The logger instance returned by `createFiro`.
  * It is a callable object: calling `log(msg)` is shorthand for `log.info(msg)`.
  */
 interface Firo {
@@ -128,6 +185,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;
     /**
@@ -153,6 +212,6 @@ interface Firo {
  * @param config Optional configuration for log levels, mode, and transports.
  * @returns A fully configured `Firo` instance.
  */
-declare const createLogger: (config?: LoggerConfig) => Firo;
+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, type LogLevel, type LogOptions, type LoggerConfig, type TransportFn, createDevTransport, createJsonTransport, createLogger };
+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 };

package/dist/index.d.ts

@@ -1,5 +1,12 @@
 /** 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;
+    readonly warn: 40;
+    readonly error: 50;
+};
 /** Primitive types allowed as context values. */
 type ContextValue = string | number | boolean | null | undefined;
 /** Options to customize how a context item is rendered. */
@@ -68,6 +75,44 @@ declare const FIRO_COLORS: {
     readonly tangerine: "38;5;208";
     readonly periwinkle: "38;5;147";
 };
+/** Hash a string to a stable color palette index. Similar strings land on different colors. */
+declare const getColorIndex: (str: string, useAllColors?: 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;
+/** 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 transports. */
+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;
+type utils_ContextItem = ContextItem;
+type utils_ContextItemWithOptions = ContextItemWithOptions;
+type utils_ContextOptions = ContextOptions;
+type utils_ContextValue = ContextValue;
+declare const utils_FIRO_COLORS: typeof FIRO_COLORS;
+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_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.
@@ -86,13 +131,23 @@ type DevTransportConfig = {
  * @returns A `TransportFn` that writes to the console.
  */
 declare const createDevTransport: (config?: DevTransportConfig) => TransportFn;
+
+type TimestampFormat = 'iso' | 'epoch';
+type ProdTransportConfig = {
+    /** 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`. */
+    dest?: {
+        write(s: string): unknown;
+    };
+};
 /**
  * Creates a built-in transport optimized for production.
  * Emits strictly structured NDJSON (Newline Delimited JSON) to stdout.
  *
  * @returns A `TransportFn` that writes JSON to standard output.
  */
-declare const createJsonTransport: () => TransportFn;
+declare const createProdTransport: (config?: ProdTransportConfig) => TransportFn;
 
 /**
  * Configuration options for creating a logger instance.
@@ -110,11 +165,13 @@ type LoggerConfig = {
     transport?: TransportFn;
     /** Options for fine-tuning the built-in development transport (e.g. timestamp format). */
     devTransportConfig?: DevTransportConfig;
-    /** Use the full extended color palette (30 colors including 256-color) for auto-assigned context badges. Defaults to false (safe 10-color palette). */
+    /** 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;
 };
 /**
- * The logger instance returned by `createLogger`.
+ * The logger instance returned by `createFiro`.
  * It is a callable object: calling `log(msg)` is shorthand for `log.info(msg)`.
  */
 interface Firo {
@@ -128,6 +185,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;
     /**
@@ -153,6 +212,6 @@ interface Firo {
  * @param config Optional configuration for log levels, mode, and transports.
  * @returns A fully configured `Firo` instance.
  */
-declare const createLogger: (config?: LoggerConfig) => Firo;
+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, type LogLevel, type LogOptions, type LoggerConfig, type TransportFn, createDevTransport, createJsonTransport, createLogger };
+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 };

package/dist/index.js

@@ -1,4 +1,24 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
 // src/utils.ts
+var utils_exports = {};
+__export(utils_exports, {
+  FIRO_COLORS: () => FIRO_COLORS,
+  LOG_LEVELS: () => LOG_LEVELS,
+  colorize: () => colorize,
+  colorizeLevel: () => colorizeLevel,
+  extractMessage: () => extractMessage,
+  getColorIndex: () => getColorIndex,
+  jsonReplacer: () => jsonReplacer,
+  safeStringify: () => safeStringify,
+  serializeError: () => serializeError,
+  wrapToError: () => wrapToError
+});
+import { inspect } from "util";
 var LOG_LEVELS = {
   debug: 20,
   info: 30,
@@ -53,6 +73,34 @@ var colorize = (text, colorIndex, color) => {
   const code = color ?? (COLORS_LIST[colorIndex] || COLORS_LIST[colorIndex % SAFE_COLORS_COUNT]);
   return `\x1B[${code}m${text}\x1B[0m`;
 };
+var jsonReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
+var safeStringify = (obj) => {
+  try {
+    return JSON.stringify(obj, jsonReplacer);
+  } catch {
+    return inspect(obj);
+  }
+};
+var wrapToError = (obj) => {
+  if (obj instanceof Error) return obj;
+  return new Error(
+    typeof obj === "object" && obj !== null ? safeStringify(obj) : String(obj)
+  );
+};
+var serializeError = (_err) => {
+  const err = wrapToError(_err);
+  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) {
@@ -70,8 +118,8 @@ var colorizeLevel = (level, text) => {
   }
 };
 
-// src/transports.ts
-import { inspect } from "util";
+// src/transport_dev.ts
+import { inspect as inspect2 } from "util";
 import process from "process";
 var createDevTransport = (config = {}) => {
   const locale = config.locale ?? void 0;
@@ -99,9 +147,9 @@ var createDevTransport = (config = {}) => {
     let dataStr = "";
     if (data !== void 0) {
       const inspectOptions = opts?.pretty ? { compact: false, colors: true, depth: null } : { compact: true, breakLength: Infinity, colors: true, depth: null };
-      dataStr = inspect(data, inspectOptions);
+      dataStr = inspect2(data, inspectOptions);
     }
-    const msgStr = typeof msg === "object" && msg !== null ? inspect(msg, { colors: true, compact: true, breakLength: Infinity }) : String(msg);
+    const msgStr = typeof msg === "object" && msg !== null ? inspect2(msg, { colors: true, compact: true, breakLength: Infinity }) : String(msg);
     const parts = [
       `[${timestamp}]`,
       // Normal (not dimmed)
@@ -115,42 +163,20 @@ var createDevTransport = (config = {}) => {
   };
   return transport;
 };
-var jsonReplacer = (_key, value) => typeof value === "bigint" ? value.toString() : value;
-var safeStringify = (obj) => {
-  try {
-    return JSON.stringify(obj, jsonReplacer);
-  } catch {
-    return inspect(obj);
-  }
-};
-var wrapToError = (obj) => {
-  if (obj instanceof Error) return obj;
-  return new Error(
-    typeof obj === "object" && obj !== null ? safeStringify(obj) : String(obj)
-  );
-};
-var serializeError = (_err) => {
-  const err = wrapToError(_err);
-  return {
-    message: err.message,
-    stack: err.stack,
-    name: err.name,
-    ...err
-  };
-};
-var buildRecord = (level, context, msg, data) => {
-  const contextObj = context.reduce((acc, item) => {
-    acc[item.key] = item.value;
-    return acc;
-  }, {});
+
+// src/transport_prod.ts
+import { inspect as inspect3 } from "util";
+import process2 from "process";
+var buildRecord = (level, context, msg, getTimestamp, data) => {
   const logRecord = {
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    level,
-    ...contextObj
+    timestamp: getTimestamp(),
+    level
   };
+  for (let i = 0, len = context.length; i < len; i++) {
+    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) {
@@ -161,21 +187,25 @@ var buildRecord = (level, context, msg, 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 createJsonTransport = () => {
+var createProdTransport = (config = {}) => {
+  const getTimestamp = config.timestamp === "epoch" ? () => Date.now() : () => (/* @__PURE__ */ new Date()).toISOString();
+  const dest = config.dest ?? process2.stdout;
   return (level, context, msg, data) => {
-    const record = buildRecord(level, context, msg, data);
+    const record = buildRecord(level, context, msg, getTimestamp, data);
     let line;
     try {
       line = JSON.stringify(record, jsonReplacer) + "\n";
     } catch {
-      if (record.data) record.data = inspect(record.data);
+      if (record.data) record.data = inspect3(record.data);
       try {
         line = JSON.stringify(record, jsonReplacer) + "\n";
       } catch {
@@ -187,28 +217,25 @@ var createJsonTransport = () => {
         }) + "\n";
       }
     }
-    process.stdout.write(line);
+    dest.write(line);
   };
 };
 
 // src/index.ts
-var fillContextItem = (item, useAllColors = false) => {
-  return {
+var createFiro = (config = {}, parentContext = []) => {
+  const useAllColors = config.useAllColors ?? true;
+  const fill = (item) => ({
     ...item,
     colorIndex: typeof item.colorIndex === "number" ? item.colorIndex : getColorIndex(item.key, useAllColors),
     color: item.color,
     omitKey: item.omitKey ?? false
-  };
-};
-var createLoggerInternal = (config, parentContext) => {
-  const useAllColors = config.useAllColors ?? false;
-  const fill = (item) => fillContextItem(item, useAllColors);
+  });
   const appendContextWithInvokeContext = (context2, invokeContext) => {
     if (!invokeContext || invokeContext.length === 0) return context2;
     return [...context2, ...invokeContext.map(fill)];
   };
   const context = [...parentContext.map(fill)];
-  const transport = config.transport ?? (config.mode === "prod" ? createJsonTransport() : createDevTransport(config.devTransportConfig));
+  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 minLevel = LOG_LEVELS[minLevelName ?? "debug"];
   const getContext = () => context;
@@ -239,7 +266,7 @@ var createLoggerInternal = (config, parentContext) => {
       }
       return { key, value, colorIndex: getColorIndex(key, useAllColors) };
     });
-    return createLoggerInternal({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
+    return createFiro({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
   };
   const debug = (msg, data, opts) => {
     if (minLevel > LOG_LEVELS.debug) return;
@@ -272,12 +299,10 @@ var createLoggerInternal = (config, parentContext) => {
     removeFromContext: removeKeyFromContext
   });
 };
-var createLogger = (config = {}) => {
-  return createLoggerInternal(config, []);
-};
 export {
   FIRO_COLORS,
+  utils_exports as FiroUtils,
   createDevTransport,
-  createJsonTransport,
-  createLogger
+  createFiro,
+  createProdTransport
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fend/firo",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Elegant logger for Node.js, Bun and Deno with brilliant DX.",
   "keywords": [
     "firo",
@@ -42,6 +42,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
+    "bumpp": "^11.0.1",
     "tsup": "^8.5.1",
     "tsx": "^4.0.0",
     "typescript": "^5.9.3"
@@ -51,6 +52,8 @@
     "test": "node --import tsx --test test/*.test.ts",
     "check": "tsc --noEmit && node --import tsx --test test/*.test.ts",
     "typecheck": "tsc --noEmit",
-    "demo": "tsx demo.ts"
+    "demo": "tsx demo.ts",
+    "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"
   }
 }