loggily 0.7.0 → 0.8.0

package/README.md

@@ -23,7 +23,7 @@ log.debug?.("cache hit", { key: "user:42" })
 log.error?.(new Error("connection lost"))
 ```
 
-Readable, colorized output in development:
+Readable, colorized output in development (colors don't render on GitHub -- run it in a terminal):
 
 ```
 14:32:15 INFO myapp server started {port: 3000}
@@ -55,7 +55,7 @@ log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
 // nothing runs when debug is off — not the function, not the stringify, not the template
 ```
 
-In benchmarks with expensive disabled log arguments, this is [~22x faster](https://beorn.codes/loggily/guide/benchmarks) than a conventional noop logger.
+In benchmarks with expensive disabled log arguments, this is [~22x faster](https://loggily.dev/guide/benchmarks) than a conventional noop logger.
 
 ## Install
 
@@ -75,60 +75,128 @@ Loggily uses `Symbol.dispose` (TC39 Explicit Resource Management) for span clean
 
 ## Features
 
-- **Config pipeline** -- second arg to `createLogger` is a config array: objects configure (`{ level, ns, format }`), arrays branch, values write. Pass `console` for terminal output, `{ file: "/path" }` for file output, or functions for custom stages.
-- **Namespace hierarchy** -- organize logs with `:` separators. `DEBUG=myapp:db` shows only database output, compatible with the same patterns as the `debug` package.
-- **Lightweight spans** -- time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs.
-- **Dev & production** -- colorized console in development, structured JSON in production. Same code, zero config.
-- **Child context** -- `log.child({ requestId })` adds structured fields to every message in the chain.
-- **Automatic async context** -- enable `AsyncLocalStorage`-based propagation and every log in a request's async chain inherits trace/span IDs without passing loggers around.
-- **Lazy messages** -- `log.debug?.(() => expensiveString())` skips the function entirely when disabled.
-- **Error overloads** -- `log.error?.(err)`, `log.error?.(err, "msg")`, and `log.error?.(err, "msg", data)`.
-- **Worker threads** -- forward logs from workers to the main thread with full type safety.
+- **Zero-cost disabled logs** -- `?.` short-circuits the entire call: no string interpolation, no JSON.stringify, no function evaluation. [~22x faster](https://loggily.dev/guide/benchmarks) than noop loggers.
+- **Config pipeline** -- `createLogger("app", [config, console, { file }, stage, [branch]])`. Objects configure, arrays branch, values write.
+- **Namespace hierarchy** -- `DEBUG=myapp:db` shows only database output. Same patterns as the `debug` package.
+- **Spans** -- `using span = log.span("name")`. Duration, parent-child tracking, trace IDs, custom data. Control per-pipeline with `{ spans: true/false }`.
+- **Dev & production** -- colorized console in development, structured JSON in production. Same code.
+- **Child loggers** -- `log.child("auth")` extends namespace, `log.child({ requestId })` adds context.
+- **Async context** -- `AsyncLocalStorage` propagation: every log in a request's async chain inherits trace/span IDs automatically.
+- **Error cause chains** -- `log.error?.(err)` serializes `Error.cause` recursively (up to 3 levels).
+- **Worker threads** -- pipeline-based: `createWorkerLogger(postMessage, "ns")` on worker, `createWorkerLogHandler()` on main. Same events, same pipeline.
+- **OpenTelemetry bridge** -- `toOtel({ api })` stage forwards events to any OTLP backend. Transparent: events pass through to subsequent pipeline elements.
+- **Pino transport compatible** -- works with object-mode writable sinks (compatible with Pino transport interface). Events use Loggily's record shape.
+- **Span metrics** -- `{ metrics: true }` in config auto-creates a collector on `log.metrics` (p50/p95/p99). Or use `withMetrics(collector)` for shared/custom collectors.
+- **Head-based sampling** -- `setSampleRate(0.1)` to sample 10% of traces.
+- **Composable plugins** -- `pipe(baseCreateLogger, withSpans(), myPlugin())` to build custom factories.
+- **Browser support** -- bundlers auto-select the browser entry point via `browser` condition.
+- **~3 KB, zero dependencies.**
+
+## Quick Start
 
-### Config Array
+```typescript
+import { createLogger } from "loggily"
+
+const log = createLogger("myapp", [{ level: "debug" }, console])
+
+log.info?.("server started", { port: 3000 })
+log.debug?.("cache hit", { key: "user:42" })
+log.error?.(new Error("timeout"), "request failed", { url: "/api" })
+
+// Child loggers
+const dbLog = log.child("db", { pool: "main" }) // namespace: "myapp:db"
+
+// Spans -- time any operation
+{
+  using span = dbLog.span("query", { table: "users" })
+  const users = await queryUsers() // your DB call
+  span.spanData.count = users.length
+}
+// → SPAN myapp:db:query (45ms) {count: 100, table: "users"}
+```
+
+## Complete Example
+
+The config array accepts six element types -- here they are in one pipeline:
 
 ```typescript
 import { createLogger } from "loggily"
+import { toOtel } from "loggily/otel"
+import * as otelApi from "@opentelemetry/api"
 
-// Objects configure, arrays branch, values write
 const log = createLogger("myapp", [
-  { level: "debug", ns: "-sql" },
+  // "myapp" -- namespace, filter with DEBUG=myapp
+  { level: "debug", metrics: true }, // config object -- sets scope
+  toOtel({ api: otelApi }), // stage -- transforms/forwards events
+  pinoTransport, // writable -- { write } receives raw Events
+  { file: "/tmp/app.log", format: "json" }, // file sink -- writes formatted strings
+  [{ level: "error" }, { file: "/tmp/err.log" }], // branch -- sub-pipeline with own scope
+  console, // console -- colorized, human-readable
+])
+
+// Custom writable -- any { write } receives raw Event objects
+const log2 = createLogger("ingest", [
+  { write: (event) => fetch("/ingest", { method: "POST", body: JSON.stringify(event) }) },
   console,
-  { file: "/tmp/app.log", level: "error", format: "json" },
 ])
+
+// Custom stage -- functions transform, filter, or enrich events
+const log3 = createLogger("filtered", [
+  (event) => (event.kind === "log" && event.message.includes("secret") ? null : event),
+  (event) => ({ ...event, props: { ...event.props, host: os.hostname() } }),
+  console,
+])
+
+// Metrics -- { metrics: true } auto-creates a collector on log.metrics
+for (const [name, s] of log.metrics.all()) {
+  if (s.p95 > 100) console.warn(`${name} is slow: p95=${s.p95}ms`)
+}
 ```
 
-When no config array is provided, loggily reads `LOG_LEVEL`, `DEBUG`, `LOG_FORMAT`, and `NODE_ENV` from the environment.
+### Composition with plugins
 
-### Spans
+`createLogger` is `pipe(baseCreateLogger, withEnvDefaults(), withSpans(), withConfigMetrics())`. For full manual control:
 
 ```typescript
-{
-  using span = log.span("db:query", { table: "users" })
-  const users = await db.query("SELECT * FROM users")
-  span.spanData.count = users.length
-}
-// SPAN myapp:db:query (45ms) {count: 100, table: "users"}
-
-// Without `using` — call .end() manually
-const span = log.span("db:query")
-try {
-  /* ... */
-} finally {
-  span.end()
-}
+import { baseCreateLogger, pipe, withSpans, withEnvDefaults } from "loggily"
+
+// Custom factory — choose exactly which plugins to include
+const myCreateLogger = pipe(baseCreateLogger, withSpans(), myPlugin())
+const log = myCreateLogger("myapp", [console])
 ```
 
-### Common configuration
+`baseCreateLogger` does NOT include `withSpans()` or `withEnvDefaults()` — loggers it creates cannot create spans and do not read environment variables.
 
-| Variable     | Example                   | Effect                                                 |
-| ------------ | ------------------------- | ------------------------------------------------------ |
-| `DEBUG`      | `myapp:db,-myapp:sql`     | Namespace filter (compatible with the `debug` package) |
-| `LOG_LEVEL`  | `debug`, `info`, `warn`   | Minimum output level                                   |
-| `LOG_FORMAT` | `console`, `json`         | Override output format                                 |
-| `TRACE`      | `1` or namespace prefixes | Enable span output                                     |
+### Test helper
+
+```typescript
+import { createTestLogger } from "loggily"
+const log = createTestLogger("test") // all levels enabled, console output
+```
 
-See the [full environment variable reference](https://beorn.codes/loggily/api/configuration).
+### Environment variables
+
+| Variable            | Values                                  | Default   |
+| ------------------- | --------------------------------------- | --------- |
+| `LOG_LEVEL`         | trace, debug, info, warn, error, silent | `info`    |
+| `LOG_FORMAT`        | console, json                           | `console` |
+| `LOG_FILE`          | file path                               | (none)    |
+| `DEBUG`             | `*`, namespace prefixes, `-prefix`      | (none)    |
+| `TRACE`             | `1`, `true`, namespace prefixes         | (none)    |
+| `TRACE_FORMAT`      | json                                    | (none)    |
+| `TRACE_ID_FORMAT`   | simple, w3c                             | `simple`  |
+| `TRACE_SAMPLE_RATE` | 0.0 -- 1.0                              | `1.0`     |
+| `NODE_ENV`          | production                              | (none)    |
+
+### Namespace filter patterns
+
+| Pattern            | Matches                                                        |
+| ------------------ | -------------------------------------------------------------- |
+| `*`                | Everything                                                     |
+| `myapp`            | Exact match + children (`myapp`, `myapp:db`, `myapp:db:query`) |
+| `myapp:*`          | Same as `myapp` — explicit wildcard                            |
+| `-myapp:sql`       | Exclude `myapp:sql` and its children                           |
+| `myapp,-myapp:sql` | Include myapp, exclude sql subtree                             |
 
 ### Types
 
@@ -142,15 +210,37 @@ Key types exported for power users:
 | `Stage`             | `(event: Event) => Event \| null \| void`                        |
 | `Pipeline`          | `{ dispatch, level, dispose }`                                   |
 | `ConditionalLogger` | Logger with `?.`-compatible methods                              |
-
-`buildPipeline()` and `defaultPipeline()` are exported for direct pipeline construction.
-
-## Compatibility
-
-- **`DEBUG=` compatible** -- uses the same namespace filter patterns as the `debug` package
-- **Works with Pino transports** -- custom stage functions can forward events to any sink
-- **W3C Trace Context** -- `traceparent()` generates standard trace headers
-- **OpenTelemetry compatible** -- span events include `spanId`, `traceId`, `parentId`
+| `ConfigElement`     | Union of all valid config array elements                         |
+| `ConfigObject`      | Scope config: `{ level?, ns?, format?, spans? }`                 |
+| `FileDescriptor`    | File output: `{ file, level?, ns?, format? }`                    |
+| `Writable`          | Any object with `{ write, objectMode? }`                         |
+
+`buildPipeline()` is exported for direct pipeline construction.
+
+### Subpath exports
+
+| Import path       | Contents                                                             |
+| ----------------- | -------------------------------------------------------------------- |
+| `loggily`         | Core API, types, pipeline builder                                    |
+| `loggily/context` | AsyncLocalStorage context propagation (Node.js)                      |
+| `loggily/worker`  | Worker thread logger + message handlers                              |
+| `loggily/otel`    | OpenTelemetry bridge (`toOtel` stage)                                |
+| `loggily/metrics` | Span metrics collection (`{ metrics: true }` or explicit collectors) |
+
+## Compatibility & Destinations
+
+- **OpenTelemetry** -- `toOtel({ api })` forwards to Jaeger, Grafana, Datadog, or any OTLP backend
+- **Sentry** -- capture errors via a 3-line stage function
+- **Pino transports** -- works with object-mode writable sinks (compatible with Pino transport interface)
+- **Elasticsearch / OpenSearch** -- post JSON events directly
+- **AWS CloudWatch** -- writable calling `putLogEvents`
+- **Prometheus** -- expose `log.metrics` as a `/metrics` endpoint
+- **`DEBUG=` patterns** -- same namespace filter syntax as the `debug` package
+- **W3C Trace Context** -- `traceparent()` generates standard headers
+- **Browser** -- bundlers auto-select the browser entry point
+- **Worker threads** -- pipeline-based forwarding via `postMessage`
+
+See the [Destinations guide](https://loggily.dev/guide/destinations) for copy-paste recipes.
 
 ## Why this exists
 
@@ -160,15 +250,16 @@ Loggily was built while developing a terminal UI where disabled debug logs insid
 
 ## When not to use Loggily
 
-- **You need worker-thread transport pipelines with log rotation and dozens of plugins.** [Pino](https://getpino.io/) has a mature transport ecosystem for this.
-- **You need distributed tracing with vendor exporters and auto-instrumentation.** [OpenTelemetry](https://opentelemetry.io/) is the industry standard.
+- **You need auto-instrumentation** (HTTP, database, gRPC). Use OpenTelemetry's SDK directly -- Loggily's OTEL bridge forwards events but doesn't instrument frameworks.
+- **You need log rotation, file compression, or dozens of transport plugins.** Pino's transport ecosystem is deeper. (You can use Pino transports with Loggily's `objectMode` writables, but Pino owns that ecosystem.)
+- **You're not on a modern runtime.** Loggily requires Node.js >= 23.6 or Bun >= 1.0.
 
 ## Documentation
 
-- **[Get Started](https://beorn.codes/loggily/guide/journey)** -- progressive guide from first log to full observability
-- **[Full docs site](https://beorn.codes/loggily/)** -- guides, API reference, migration guides
-- [Comparison](https://beorn.codes/loggily/guide/comparison) -- what Loggily does, compatibility, when to use something else
-- [Migration from debug](https://beorn.codes/loggily/guide/migration-from-debug) -- step-by-step migration guide
+- **[Get Started](https://loggily.dev/guide/journey)** -- progressive guide from first log to full observability
+- **[Full docs site](https://loggily.dev/)** -- guides, API reference, migration guides
+- [Comparison](https://loggily.dev/guide/comparison) -- what Loggily does, compatibility, when to use something else
+- [Migration from debug](https://loggily.dev/guide/migration-from-debug) -- step-by-step migration guide
 
 ## License
 

package/dist/context.mjs

@@ -1,4 +1,4 @@
-import { i as _setContextHooks, n as _clearContextHooks } from "./core-Du3sIje6.mjs";
+import { n as _setContextHooks, t as _clearContextHooks } from "./core-B3pox577.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/context.ts
 /**