tslog: Instructions file for Codex

Project Overview

tslog is a TypeScript logger for browsers, Node.js, Deno, and Bun, React Native, and workers. It supports JSON and pretty-printed output, stack traces, error formatting, custom transports, and sub-loggers. v5 adds an always-pretty default type (colorization and pretty.passObjectsNatively — on by default in real browsers — are the env-aware parts, never the format), flat fields-first JSON, async-context correlation, path/regex masking, a middleware chain, and pino/otel/genai presets. Current version: 5.x (the 5 line; _logMeta.v in JSON output is 5).

Settings are grouped (v5)

There are no flat settings keys. Configuration is organized into groups passed to new Logger({ ... }):

• Top-level: type ("json" | "pretty" | "hidden", defaults to "pretty"), name, minLevel (name or 0..6), prefix, customLevels, strictConfig, clock (injectable () => Date).
• mask: { keys, paths, regex, caseInsensitive, placeholder, censor } — redact secrets/PII/prompts by key, dotted path (* = one segment), or regex.
• json: { messageKey, levelKey, levelIdKey, timeKey, time, errorKey, numericLevel, stableKeyOrder } — structured-output key names/shape (time: "iso" | "epoch" | false | fn).
• pretty: { enabled, template, errorTemplate, style, timeZone, styles, levelMethod, inspectOptions, ... }.
• stack: { capture: "off" | "lazy" | "auto" | "full", internalFramePatterns }.
• meta: { property, attachContext }.

New runtime surface: getSubLogger/child (aliases), runInContext/getContext (AsyncLocalStorage correlation), attachTransport, use (middleware), flush, addLevel, isLevelEnabled, [Symbol.asyncDispose]/[Symbol.dispose], Logger.fromEnv, and the defineConfig helper. Presets ship as subpaths: tslog/presets/pino, tslog/otel, tslog/presets/genai; transports as tslog/transports/{file,http,ringbuffer}.

Quick Reference

npm install          # Install dependencies
npm test             # Run Vitest test suite
npm run test:browser # Run Playwright browser tests (Chromium, Firefox, WebKit)
npm run test:bun     # Run Vitest under Bun
npm run test:deno    # Build + run Deno test adapter
npm run build        # Full build: types → ESM → browser IIFE bundle → prepare dist
npm run lint         # Biome lint check
npm run format       # Biome format all files
npm run check        # Biome lint + format (write)
npm run coverage     # Run tests with coverage report
npm run test:e2e-apps # Framework E2E: real Next.js (Turbopack) + TanStack Start dev servers (needs network + prior build)