V5 Release

.github/workflows/ci.yml

@@ -2,21 +2,21 @@ name: CI
 
 on:
   push:
-    branches: [master, v4, development]
+    branches: [master, v4, v5, development]
   pull_request:
-    branches: [master, development]
+    branches: [master, v4, v5, development]
 
 jobs:
     test-node:
         runs-on: ubuntu-latest
 
         strategy:
+            fail-fast: false
             matrix:
-                node-version: [20.x]
+                node-version: ['20', '22', '24', '26', 'latest']
 
         env:
             CI: true
-            COVERAGE: ${{ matrix.node-version == '20.x' && true || false }}
 
         steps:
             - uses: actions/checkout@v5
@@ -26,10 +26,27 @@ jobs:
                   node-version: ${{ matrix.node-version }}
             - run: npm ci
 
-            # Node test suite + coverage.
-            - name: Run coverage
+            # Fail fast if the AI-facing docs (llms.txt/RECIPES.md) drifted from the source.
+            - name: Check doc sync
+              run: npm run check-doc-sync
+
+            # Guard the gzip budgets of the slim and full browser bundles.
+            - name: Check bundle size
+              run: npm run check-bundle-size
+
+            # Run the full test suite on every supported Node version.
+            # Coverage + Codecov report only on the minimum supported version (20)
+            # to avoid redundant uploads and overhead.
+            - name: Run tests (with coverage)
+              if: matrix.node-version == '20'
               run: npm run coverage
+
+            - name: Run tests
+              if: matrix.node-version != '20'
+              run: npm test
+
             - name: Report coverage
+              if: matrix.node-version == '20'
               uses: codecov/codecov-action@v5
               with:
                   token: ${{ secrets.CODECOV_TOKEN }}
@@ -46,7 +63,7 @@ jobs:
             - uses: actions/checkout@v5
             - uses: actions/setup-node@v5
               with:
-                  node-version: 20.x
+                  node-version: 22
             - run: npm ci
             - name: Install Playwright ${{ matrix.browser }}
               run: npx playwright install --with-deps ${{ matrix.browser }}
@@ -59,7 +76,7 @@ jobs:
             - uses: actions/checkout@v5
             - uses: actions/setup-node@v5
               with:
-                  node-version: 20.x
+                  node-version: 22
             - uses: oven-sh/setup-bun@v2
               with:
                   bun-version: latest
@@ -73,7 +90,7 @@ jobs:
             - uses: actions/checkout@v5
             - uses: actions/setup-node@v5
               with:
-                  node-version: 20.x
+                  node-version: 22
             - uses: denoland/setup-deno@v2
               with:
                   deno-version: v2.x

.github/workflows/docs.yml

@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - name: Install docs dependencies
         run: npm ci
         working-directory: docs

.gitignore

@@ -90,6 +90,9 @@ bower_components
 # Playwright test results
 /test-results/
 
+# Deno lockfile (written by the deno test adapter run; jsr deps are pinned per-run in CI)
+/deno.lock
+
 # Agent config
 # AGENTS.md and CLAUDE.md are shared with contributors (committed).
 # Personal, machine-local overrides go in CLAUDE.local.md (never committed).

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "js/ts.tsdk.path": "node_modules/@typescript/native-preview"
+}

AGENTS.md

@@ -1,8 +1,19 @@
-# AGENTS.md — tslog
-
 ## Project Overview
 
-tslog is a TypeScript logger for Node.js, browsers, Deno, and Bun. It supports JSON and pretty-printed output, stack traces, error formatting, custom transports, and sub-loggers. Current version: 4.10.2.
+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
 
@@ -12,30 +23,30 @@ 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/CJS → browser bundle → prepare dist
+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 dev-ts       # Watch mode (nodemon + ts-node on examples)
 ```
 
 ## Build System
 
-- **TypeScript (tsc)** for ESM (`dist/esm/`) and CJS (`dist/cjs/`) builds
-- **esbuild** (`build.js`) for browser IIFE bundle (`dist/browser/`)
-- **Type declarations** generated separately to `dist/types/`
-- Dual ESM/CJS publishing with conditional exports in package.json
-- `"type": "module"` — project uses ESM by default
+- **ESM-only.** There is no CJS build and no `require("tslog")` — v5 dropped dual publishing.
+- **tsgo** (`@typescript/native-preview`, the TypeScript 7 native compiler) emits the ESM output (`dist/esm/`) and the declaration files (`dist/types/`).
+- **esbuild** (`build.js`) bundles the browser IIFE (`dist/browser/index.js`, global `tslog`) from `src/index.browser.ts`.
+- `"type": "module"` — the project is ESM throughout.
+- `npm run build` = `build-types` → `build-esm` → `build-browser` → `prepare-publish`.
+- **Conditional exports** in `package.json` pick the entry per runtime: `node` → `index.node.js`, `browser`/`worker` → `index.browser.js`, `deno`/`bun`/`react-native`/`default` → `index.universal.js`. Subpaths (`tslog/transports/*`, `tslog/presets/*`, `tslog/otel`, `tslog/serializers`, `tslog/lite`, `tslog/slim`, `tslog/console`, `tslog/testing`, `tslog/pretty/box`, `tslog/throttle`, `tslog/cli`) are individually mapped and tree-shakeable (`sideEffects: false`, audited by `npm run audit-sideeffects`; gzip budgets for the slim/full browser bundles enforced by `npm run check-bundle-size`).
+- The `tslog` bin (NDJSON pretty-printer) is `dist/esm/subpaths/cli.js`.
 
 ### Build configs
 
 | Config | Purpose |
 |---|---|
-| `tsconfig.json` | Base (ES2020, strict, NodeNext) |
-| `tsconfig.esm.json` | ESM output |
-| `tsconfig.cjs.json` | CJS output |
-| `tsconfig.types.json` | Declaration files only |
+| `tsconfig.json` | Base (ES2022, strict, NodeNext) |
+| `tsconfig.esm.json` | ESM output (`dist/esm/`) |
+| `tsconfig.types.json` | Declaration files only (`dist/types/`) |
 
 ## Testing
 
@@ -61,25 +72,68 @@ npm run dev-ts       # Watch mode (nodemon + ts-node on examples)
 
 ## Source Architecture
 
+v5 is organized into `core/` (runtime-agnostic logic), `env/` (per-runtime environment providers), `internal/` (small shared helpers), `render/` (output), and `subpaths/` (tree-shakeable add-ons). The entry points differ only in which environment factory they bind; the `Logger` class itself is shared.
+
 ```
 src/
-├── BaseLogger.ts          # Core logger: settings, masking, formatting, transports
-├── index.ts               # Logger class (extends BaseLogger), default log levels
-├── index.browser.ts       # Browser entry point (Safari detection, CSS styling)
-├── interfaces.ts          # All TypeScript interfaces and types
-├── formatTemplate.ts      # Template string replacement
-├── prettyLogStyles.ts     # Default pretty-print styles
-└── internal/
-    ├── environment.ts     # Runtime detection (Node, browser, Deno, Bun, worker)
-    ├── stackTrace.ts      # Stack trace parsing
-    ├── errorUtils.ts      # Error chain collection
-    ├── metaFormatting.ts  # Metadata formatting for pretty output
-    └── jsonStringifyRecursive.ts  # Circular-safe JSON serialization
+├── index.ts                  # Logger class (extends BaseLogger) + shared exports
+├── index.node.ts             # Node entry — binds createNodeEnvironment
+├── index.universal.ts        # Deno/Bun/React Native/default entry
+├── index.browser.ts          # Browser/worker entry (Safari detect, CSS styling)
+├── BaseLogger.ts             # Core logger plumbing
+├── interfaces.ts             # All TypeScript interfaces and types
+├── formatTemplate.ts         # Template string replacement
+├── formatNumberAddZeros.ts   # Zero-padding for template date/time parts
+├── urlToObj.ts               # URL → plain-object serialization
+├── core/                     # Runtime-agnostic logic
+│   ├── settings.ts           # Grouped-settings normalization/merge + v4-key migration warnings
+│   ├── config.ts             # defineConfig + TslogConfigError
+│   ├── pipeline.ts           # log() → mask → logObj → meta → format → transport
+│   ├── masking.ts            # keys / paths / regex / censor masking
+│   ├── logObj.ts             # Build the structured log object
+│   ├── meta.ts               # _logMeta assembly
+│   ├── levels.ts             # DefaultLogLevels + custom levels
+│   ├── transports.ts         # Transport registry + isolation
+│   ├── asyncContext.ts       # runInContext / getContext (AsyncLocalStorage)
+│   ├── fromEnv.ts            # Logger.fromEnv (TSLOG_LEVEL/TYPE/NAME)
+│   ├── levelPersistence.ts   # persistLevel (browser localStorage)
+│   ├── features.ts           # CoreFeatures seam (what a build ships: masking, JSON renderer, …)
+│   └── features.full.ts      # Full feature set injected by the standard entries
+├── env/                      # Per-runtime environment providers
+│   ├── environment.ts        # EnvironmentProvider contract + factory types
+│   ├── environment.node.ts   # createNodeEnvironment
+│   ├── environment.browser.ts# createBrowserEnvironment
+│   ├── environment.universal.ts # createUniversalEnvironment / selectEnvironment
+│   ├── environment.slim.ts   # Minimal provider for tslog/slim
+│   ├── providerBase.ts       # Shared provider base (meta markup, transport formatting)
+│   ├── shared.ts             # Helpers shared across providers (paths, meta text)
+│   ├── stackTrace.ts         # Stack capture/parse
+│   ├── sourceMap.node.ts     # Source-map error-position resolution (Node/Bun/Deno)
+│   └── stdoutSink.node.ts    # Buffered stdout sink (Node JSON output)
+├── internal/                 # Small shared helpers
+│   ├── environment.ts        # Runtime detection, TTY/color probing, resolveDefaultType
+│   ├── errorUtils.ts         # Error introspection helpers
+│   ├── exitHooks.ts          # Process/page exit flushing for transports
+│   ├── jsonStringifyRecursive.ts # Circular-safe JSON stringify
+│   ├── metaFormatting.ts     # Pretty meta template rendering
+│   ├── nativeConsole.ts      # Untouched console method access
+│   └── InspectOptions.interface.ts # Runtime-free InspectOptions type
+├── render/                   # Output formatting
+│   ├── json.ts               # JSON serialization (flat, fields-first, _logMeta.v)
+│   ├── inspect.ts            # native util.inspect (Node)
+│   ├── inspect.polyfill.ts   # off-Node inspect polyfill
+│   └── styles.ts             # pretty styling
+└── subpaths/                 # Tree-shakeable add-ons (each its own export)
+    ├── presets/{pino,otel,genai}.ts
+    ├── transports/{file,http,ringBuffer,worker,worker.runner}.ts
+    ├── serializers/std.ts    ├── pretty/box.ts
+    ├── lite.ts   ├── slim.ts   ├── testing.ts   ├── throttle.ts
+    ├── wrapConsole.ts        └── cli.ts   # tslog bin (NDJSON pretty-printer)
 ```
 
-**Log lifecycle:** `log()` → mask → toLogObj → addMeta → format → transport
+**Log lifecycle:** `log()` → mask → build logObj → attach `_logMeta` → middleware (`use`) → format → transports (`render/` formats; per-transport `format` can override).
 
-**7 log levels:** silly(0), trace(1), debug(2), info(3), warn(4), error(5), fatal(6)
+**7 default log levels:** silly(0), trace(1), debug(2), info(3), warn(4), error(5), fatal(6). Add more via the `customLevels` setting or `addLevel()`.
 
 ## Git Workflow
 
@@ -92,15 +146,15 @@ src/
 
 - Uses **np** for releases (`npm run release`)
 - Publishes from `dist/` directory (`publishConfig.directory: "dist"`)
-- `scripts/prepare-publish.mjs` copies package.json/LICENSE/README into dist with adjusted paths
-- Supports: Node.js (ESM/CJS), browsers (IIFE), Deno, Bun, React Native
+- `scripts/prepare-publish.mjs` writes a dist-relative `package.json` and copies `LICENSE`, `README.md`, `llms.txt`, `RECIPES.md`, and `MIGRATION_v4_to_v5.md` into `dist/`
+- Supports: Node.js (ESM), browsers (IIFE), Deno, Bun, React Native — all ESM, no CJS
 
 ## Key Conventions
 
-- Node.js 16+ required (`.nvmrc`)
+- Node.js 20+ required (`package.json` `engines`); ES2022 target
 - npm only (engine-strict in `.npmrc`)
-- No additional runtime dependencies
-- TypeScript strict mode throughout
+- Zero runtime dependencies
+- TypeScript 7 (tsgo) strict mode throughout; ESM-only
 - Tests are numbered by feature area (e.g., `1_json_loglevel`, `5_pretty_Log_Types`)
 - Browser-specific code isolated in `index.browser.ts` and `tests/support/`
 
@@ -109,4 +163,10 @@ src/
 - Target **100% test coverage** — but only with meaningful tests, no padding
 - Every new feature **must** have corresponding tests
 - Every new feature **must** be reflected in the docs (`docs/`)
-- Don't write tests just to hit coverage numbers; each test should verify real behavior
+- Don't write tests just to hit coverage numbers; each test should verify real behavior
+
+### AI-facing docs (`llms.txt`, `RECIPES.md`)
+
+- `llms.txt` (machine-readable API surface for code generation) and `RECIPES.md` (copy-paste patterns) are published with the package and must stay consistent with each other and with the public API. When you change a public setting/method or one of these files, update both — and the README — in the same change.
+- `npm run check-doc-sync` (part of `npm run check`, run by the pre-commit hook and CI) enforces the mechanical invariants: every setting/symbol named in the docs exists in the source, the masking examples don't conflict, and relative links resolve.
+- The script only checks structural drift. For semantic accuracy/completeness, run the deeper `audit-ai-docs` workflow before a release.