logquill 0.4.0 → 1.0.1

package/README.md

@@ -9,12 +9,15 @@ A logging framework for Node/TypeScript that shares one mental model and one
 JSON log shape with its Python sibling, [`logquill`](https://pypi.org/project/logquill/)
 (repo: `logquill-python`).
 
-Status: pre-release, under active development. The core `Logger`, level
-filtering, a full plugin pipeline (context/redaction/PII/tamper-evidence/
-sampling/alerting), `JSONFormatter`, and a broad transport catalog —
-console/file/HTTP, SQL, NoSQL, message queues, and cloud-native log
-platforms — are implemented; non-blocking async dispatch is not yet — see
-`CHANGELOG.md` for what's landed so far.
+Status: **1.0** — the full core `Logger`, level filtering, non-blocking
+async dispatch with configurable backpressure, a full plugin pipeline
+(context/redaction/PII/tamper-evidence/sampling/rate-limiting/alerting),
+`JSONFormatter`, a broad transport catalog — console/file/HTTP, SQL,
+NoSQL, message queues, and cloud-native log platforms — agentic/harness
+tracing (including `LangChainAdapter`/`LangGraphAdapter` and
+`OtelSpanProcessor`), a separate `logquill/browser` build, and
+`winston`/`pino` migration bridges are all shipped; see `CHANGELOG.md` for
+the full history.
 
 ## Features
 
@@ -28,7 +31,11 @@ platforms — are implemented; non-blocking async dispatch is not yet — see
 - **Dual package** — works via both `require()` (CJS) and `import` (ESM) from the same published package
 - **Tracing & agentic logging** — `.thought()/.action()/.observation()/.decision()`, `Logger.span()` for nested/durationMs-stamped spans, `RunPlugin` (per-run id + step counter), and `TraceContextPlugin` (cross-service `traceId`, OTel-aware) — see [Tracing & agentic logging](#tracing--agentic-logging)
 - **LangChain.js / LangGraph.js adapter** — `LangChainAdapter`, a `BaseCallbackHandler` that maps chain/LLM/tool/agent events onto the calls above with zero manual instrumentation, from a separate `logquill/langchain` entry point — see [Agentic framework adapters](#agentic-framework-adapters)
-- *(planned)* non-blocking async dispatch, `AsyncLocalStorage`-based general context propagation — see `CHANGELOG.md`
+- **OpenTelemetry-native integration** — `OtelSpanProcessor` bridges frameworks that emit OTel spans directly (e.g. the Vercel AI SDK) onto `.action()`/`.observation()`/`.error()`, with zero real dependency on `@opentelemetry/*` — see [OpenTelemetry-native integration](#opentelemetry-native-integration)
+- **Non-blocking async dispatch** — a call returns before its write runs, via a bounded internal queue with a configurable backpressure policy (`dropOldest`/`dropNewest`/`block`); `logger.flush()`, `withLambda`/`withCloudFunction`/`withAzureFunction`, and `installShutdownHandlers` cover draining it before a process pauses or exits — see [Async dispatch & shutdown](#async-dispatch--shutdown)
+- **Request-scoped context propagation** — `bindContext()`, `AsyncLocalStorage`-backed, so a value set once is visible in every nested log call underneath it without threading it through every signature by hand; `RateLimitPlugin` caps a noisy loop without silencing everything else — see [Context propagation & error capture](#context-propagation--error-capture)
+- **Migration bridges** — `LogQuillWinstonTransport` (from `logquill/winston`) and `LogQuillPinoDestination` let an existing `winston`/`pino` app adopt LogQuill's transports/plugins with no call-site changes — see [Migration bridges](#migration-bridges)
+- **Browser build** — a separate `logquill/browser` entry (`Logger`, `JSONFormatter`, the plugin pipeline, `ConsoleTransport`, `BeaconTransport`) with no Node built-ins in its module graph — see [Browser build](#browser-build)
 
 ## Contents
 
@@ -44,8 +51,16 @@ platforms — are implemented; non-blocking async dispatch is not yet — see
   - [PII redaction](#pii-redaction)
   - [Tamper-evident logs](#tamper-evident-logs)
   - [Alerting](#alerting)
+  - [Rate limiting](#rate-limiting)
 - [Tracing & agentic logging](#tracing--agentic-logging)
 - [Agentic framework adapters](#agentic-framework-adapters)
+  - [OpenTelemetry-native integration](#opentelemetry-native-integration)
+- [Async dispatch & shutdown](#async-dispatch--shutdown)
+  - [Kubernetes](#kubernetes)
+- [Context propagation & error capture](#context-propagation--error-capture)
+- [Migration bridges](#migration-bridges)
+- [Browser build](#browser-build)
+- [API reference](#api-reference)
 - [Development](#development)
 - [License](#license)
 
@@ -119,6 +134,7 @@ actually import; nothing is installed on your behalf.
 | Transport | Backend | Peer dependency | Setup |
 |---|---|---|---|
 | `ConsoleTransport` | stdout/stderr via `console.*` | *(none)* | zero-setup, isomorphic |
+| `BeaconTransport` | browser log endpoint, via `navigator.sendBeacon` | *(none, isomorphic)* | zero-setup — see [Browser build](#browser-build) |
 | `FileTransport` | local file, with rotation | *(none)* | zero-setup |
 | `HTTPTransport` | any HTTP log endpoint | *(none, uses `fetch`)* | zero-setup |
 | `SQLiteTransport` | SQLite | `better-sqlite3` | zero-setup (file or `:memory:`) |
@@ -506,6 +522,25 @@ logger.error("payment webhook failed", { orderId: "o-123" });
 inject a `sender`) follow the same shape. Write your own by extending
 `AlertingPlugin` and implementing `sendAlert(record, occurrences)`.
 
+### Rate limiting
+
+`RateLimitPlugin` drops records once a key — by default `(logger, level)`
+— exceeds `maxRecords` within a rolling `perSeconds` window, so a noisy
+loop (a retry logging the same error every iteration) can't drown out a
+logger's other messages. Each key gets its own window, so unrelated keys
+never reset in lockstep; pass `keyFunc` to key on something else, e.g. an
+error message or a `meta` field identifying the caller.
+
+```ts
+import { Logger, RateLimitPlugin } from "logquill";
+
+const logger = new Logger("app", { plugins: [new RateLimitPlugin(5, 60)] }); // at most 5 per key per minute
+
+for (let i = 0; i < 10; i++) {
+  logger.error("db connection failed"); // only the first 5 in any 60s window ship
+}
+```
+
 ## Tracing & agentic logging
 
 `.thought()/.action()/.observation()/.decision()` are `.info()` with
@@ -621,6 +656,278 @@ not the main `"logquill"` import — because `LangChainAdapter` has to
 optional peer dependency) — no separate `@langchain/langgraph` dependency
 is needed for `LangGraphAdapter`.
 
+### OpenTelemetry-native integration
+
+Some frameworks aren't callback-handler-based — the Vercel AI SDK's
+`experimental_telemetry` is the main JS example, emitting OpenTelemetry
+spans directly instead of calling into a handler object like
+`BaseCallbackHandler`. `OtelSpanProcessor` covers that case: register it on
+any OTel tracer provider, and every span becomes one `.action()` call on
+start plus one `.observation()` (or `.error()`, on an error status) call on
+end, carrying the span's own `spanId`/`parentSpanId` — OTel span ids are
+already the same 16-hex-char shape LogQuill's own ids use — plus
+`meta.durationMs` on the end record:
+
+```ts
+import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { Logger, OtelSpanProcessor } from "logquill";
+
+const logger = new Logger("agent");
+const provider = new BasicTracerProvider({
+  spanProcessors: [new OtelSpanProcessor(logger)],
+});
+const tracer = provider.getTracer("my-app");
+
+const span = tracer.startSpan("callLlm");
+span.end();
+// logs two records: one .action() on start, one .observation() on end
+// (or .error() if span.setStatus({ code: SpanStatusCode.ERROR }) was called)
+```
+
+Unlike `LangChainAdapter`, this is exported from the **main** `"logquill"`
+entry point, not a separate subpath — it's fully duck-typed against the
+`Span`/`ReadableSpan` shape, the same approach `TraceContextPlugin` uses
+for its own OTel lookup, so it never imports `@opentelemetry/api` or
+`@opentelemetry/sdk-trace-base` for real. Non-empty span attributes are
+copied onto `meta.attributes` (configurable via `attributesKey`) verbatim;
+mapping onto the OTel `gen_ai.*` semantic conventions is left to the
+planned `OTLPTransport` (v2.0).
+
+## Async dispatch & shutdown
+
+Every `Logger` call returns before the write it triggers actually runs —
+the write (and any plugin `afterLog` hooks) is handed to an internal,
+bounded dispatch queue, drained outside the caller's own call stack:
+
+```ts
+import { CollectingTransport, Logger } from "logquill";
+
+const transport = new CollectingTransport();
+const logger = new Logger("app", { transports: [transport] });
+
+logger.info("hello");
+console.log(transport.records.length); // 0 — still queued
+await logger.flush();
+console.log(transport.records.length); // 1 — now written
+```
+
+The queue has a configurable size and backpressure policy, so a sustained
+burst can't grow memory without bound:
+
+```ts
+const logger = new Logger("app", {
+  transports: [transport],
+  queue: {
+    maxSize: 10_000, // default
+    policy: "dropOldest", // "dropOldest" (default) | "dropNewest" | "block"
+  },
+});
+```
+
+- `"dropOldest"` — once the queue is full, the longest-waiting record is
+  discarded to make room for the new one.
+- `"dropNewest"` — the incoming record is discarded; everything already
+  queued is left alone.
+- `"block"` — nothing is ever dropped: once the queue is full, a call runs
+  its write immediately, on the caller's own stack, instead of queueing it.
+
+Any dropped-record policy calls `onDrop(count, policy)` — rate-limited to
+once per `warnIntervalMs` (default 5000) — so sustained overload is
+visible without flooding your own logs with one warning per drop.
+
+`logger.flush()` waits for every record dispatched so far to reach its
+transports. Note it does *not* force a batching transport (SQL, a queue,
+`HTTPTransport`, ...) to send a batch still under its own threshold early
+— for that, use `withLambda`/`withCloudFunction`/`withAzureFunction`
+(same wrapper, three platform-matching names) around a serverless handler,
+which additionally forces every batching transport's buffer out before
+the wrapped function's result settles — important because a frozen or
+recycled execution environment may never come back to finish a partial
+batch on its own:
+
+```ts
+import { withLambda } from "logquill";
+
+export const handler = withLambda(logger, async (event) => {
+  logger.info("handling request", { requestId: event.requestId });
+  return { statusCode: 200 };
+});
+```
+
+For a long-running process, `installShutdownHandlers` flushes and closes a
+logger once on `SIGTERM`/`SIGINT`/`beforeExit`, so nothing queued is lost
+when the process stops:
+
+```ts
+import { installShutdownHandlers } from "logquill";
+
+installShutdownHandlers(logger); // Node only
+```
+
+### Kubernetes
+
+Default to `ConsoleTransport`, not `FileTransport`, for anything running in
+a container. A container's filesystem is ephemeral and invisible to the
+rest of the cluster — a log file written inside it disappears the moment
+the pod is rescheduled, and nothing aggregates it in the meantime unless
+you also run a sidecar to tail it back out. Writing to stdout/stderr
+instead costs nothing extra: every major container runtime already
+captures both streams, and the node-level log agent your cluster runs
+(Fluentd, Fluent Bit, Vector, or your cloud provider's own) ships them to
+your aggregator without any code on your side that needs to know that
+agent exists:
+
+```ts
+import { ConsoleTransport, Logger } from "logquill";
+
+const logger = new Logger("app", { transports: [new ConsoleTransport()] });
+```
+
+Kubernetes sends `SIGTERM` and then kills the process after
+`terminationGracePeriodSeconds` (30s by default) regardless of whether
+it's finished shutting down, so a record still sitting in the dispatch
+queue at that instant can be lost if nothing catches the signal.
+`installShutdownHandlers(logger)` closes that gap the same way
+`withLambda` closes it for a serverless freeze — call it once, on process
+start, so a pod that's told to stop still flushes and closes the logger
+before Kubernetes kills it.
+
+## Context propagation & error capture
+
+`bindContext()` merges values into a request-scoped context, backed by
+`AsyncLocalStorage`: every `Logger` call underneath it — through any
+number of function calls and `await`s deep — picks them up in `meta`
+automatically, without threading them through every signature by hand.
+Concurrent async operations sharing one `Logger` never see each other's
+bound context.
+
+```ts
+import { bindContext, Logger } from "logquill";
+
+const logger = new Logger("app");
+
+await bindContext({ requestId: "abc123" }, async () => {
+  await handleRequest(); // any logging in here, or in what it calls,
+                         // gets meta.requestId = "abc123" for free
+});
+
+function handleRequest() {
+  logger.info("handled"); // meta: { requestId: "abc123" }
+}
+```
+
+Nested `bindContext()` calls merge, with the inner value winning on key
+collision — the same way an explicit call-site `meta` value always wins
+over anything bound this way.
+
+Pass an `Error` as `meta.err` and it's replaced with a formatted
+`meta.stack`, the same shape `Logger.span()` already produces internally
+for a thrown error:
+
+```ts
+try {
+  await riskyOperation();
+} catch (err) {
+  logger.error("operation failed", { err, orderId: "o-123" });
+  // meta: { orderId: "o-123", stack: "Error: ...\n    at ..." } — no meta.err
+}
+```
+
+## Migration bridges
+
+For an app already using `winston` or `pino`, LogQuill can sit alongside
+either with no call-site changes, so a migration can happen transport by
+transport instead of all at once.
+
+`LogQuillWinstonTransport` (from the separate `logquill/winston` entry
+point, since it has to extend `winston-transport`'s own class) plugs a
+LogQuill `Logger` into an existing `winston.createLogger()` as one more
+transport:
+
+```ts
+import winston from "winston";
+import { Logger } from "logquill";
+import { LogQuillWinstonTransport } from "logquill/winston";
+
+const logquill = new Logger("app");
+const winstonLogger = winston.createLogger({
+  transports: [new LogQuillWinstonTransport(logquill)],
+});
+
+winstonLogger.info("still works exactly as before", { userId: 42 });
+```
+
+`LogQuillPinoDestination` is a pino `destination` — pass it straight into
+`pino()` and pino's own NDJSON output is parsed back into LogQuill calls.
+It needs no dependency on `pino` itself (a destination only has to be
+duck-type compatible with a Node `Writable`), so it ships from the main
+entry point:
+
+```ts
+import pino from "pino";
+import { Logger, LogQuillPinoDestination } from "logquill";
+
+const logquill = new Logger("app");
+const log = pino(new LogQuillPinoDestination(logquill));
+
+log.info({ userId: 42 }, "still works exactly as before");
+```
+
+Both re-filter by the LogQuill `Logger`'s own `level` after the
+source library's own filtering runs — the stricter of the two wins — and
+map that library's levels onto LogQuill's via a `levelMap` option,
+overridable for a non-default level configuration.
+
+## Browser build
+
+`import ... from "logquill/browser"` is a separate entry point shipping
+the same `Logger`, levels, `JSONFormatter`, and plugin pipeline
+(`ContextPlugin`/`RedactPlugin`/`PIIRedactPlugin`/`SamplingPlugin`), plus
+`ConsoleTransport` and `BeaconTransport`. `FileTransport`, `HTTPTransport`,
+every SQL/NoSQL/queue/cloud-native transport, and the LangChain adapters
+are absent from this entry's module graph entirely — not tree-shaken,
+simply never imported — so this bundle never pulls in a Node built-in.
+
+```ts
+import { BeaconTransport, ConsoleTransport, Logger } from "logquill/browser";
+
+const logger = new Logger("app", {
+  transports: [
+    new ConsoleTransport(),
+    new BeaconTransport("https://logs.example.com/ingest", { batchSize: 20 }),
+  ],
+});
+
+logger.info("page loaded", { path: location.pathname });
+window.addEventListener("pagehide", () => logger.close()); // flushes the pending beacon batch
+```
+
+`BeaconTransport` batches formatted records and sends them via
+`navigator.sendBeacon`, which — unlike `fetch` — can complete even after
+the page that queued it starts unloading; it falls back to a `keepalive`
+`fetch` where `sendBeacon` isn't available (a worker, an older browser).
+Keep `batchSize` small — `sendBeacon` payloads are capped (64KB in most
+browsers).
+
+One behavioral difference from the Node build: `Logger.span()`'s
+`parentSpanId` nesting is backed by a plain stack here instead of
+`AsyncLocalStorage` (which browsers don't have), so two spans on the same
+`Logger` running concurrently across an `await` can interleave and stamp
+the wrong `parentSpanId` — fine for the common case of one span in flight
+at a time.
+
+## API reference
+
+Every exported class and function carries a TSDoc comment; the full
+reference, generated from those comments with
+[TypeDoc](https://typedoc.org), is published at
+[nikhilvdev.github.io/logquill-js](https://nikhilvdev.github.io/logquill-js/)
+and rebuilt on every push to `main`. To build it locally:
+
+```sh
+npm run docs   # writes static HTML to site/
+```
+
 ## Development
 
 ```sh
@@ -629,6 +936,7 @@ npm run build      # dist/index.{mjs,cjs,d.ts} via tsup
 npm run lint        # eslint
 npm run typecheck   # tsc --noEmit
 npm run coverage    # vitest run --coverage
+npm run docs        # typedoc -> site/
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR workflow, the