@unhingged/logit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zoltán Balogh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @unhingged/logit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Structured logging for Node.js, Next.js, Bun and the edge, in the mould of Serilog: you write a **message template**, the logger captures the **values** by name, and every sink — console, file, Seq, OTLP, your own — sees the same structured event.
+
+```bash
+npm install @unhingged/logit
+```
+
+```ts
+import { log } from '@unhingged/logit';
+
+log.info('Order {OrderId} shipped to {@Address} in {Elapsed:0.0} ms', 1042, { city: 'Budapest', zip: '1011' }, 83.2);
+```
+
+On a terminal:
+
+```
+08:12:03.123 INF Order 1042 shipped to { city: "Budapest", zip: "1011" } in 83.2 ms
+```
+
+In a container, on Vercel, or anywhere stdout is not a TTY:
+
+```json
+{"timestamp":"2026-10-08T08:12:03.123Z","level":"info","message":"Order 1042 shipped to { city: \"Budapest\", zip: \"1011\" } in 83.2 ms","template":"Order {OrderId} shipped to {@Address} in {Elapsed:0.0} ms","OrderId":1042,"Address":{"city":"Budapest","zip":"1011"},"Elapsed":83.2}
+```
+
+The template is part of the event, so "every shipment slower than 500 ms" is a query, not a regex.
+
+**Docs:** https://logit.unhingged.com/docs · **Roadmap:** https://logit.unhingged.com/roadmap
+
+## What you get
+
+- **Message templates** ([messagetemplates.org](https://messagetemplates.org)) with `@` to destructure, `$` to stringify, `:format` and `,alignment`.
+- **Capture rules that fit JS**: plain objects and arrays are data; class instances print their name unless you `@` them; errors are always structured, `cause` chains included. Depth, string and collection limits; key-based **redaction**; transforming policies.
+- **Six levels** (`verbose` … `fatal`), per-source **overrides** (`'next': 'warn'`), a **`LevelSwitch`** you can flip at runtime, `LOGIT_LEVEL` from the environment.
+- **Ambient context**: `LogContext.run({ requestId }, …)` on `AsyncLocalStorage`, `using _ = LogContext.push(…)`, enrichers for fixed, computed and process properties.
+- **Sinks**: console (pretty / JSON / CLEF / output template), rolling file, batching HTTP with retry, Seq, OTLP/HTTP, an OpenTelemetry bridge, memory, callback — plus conditional, restricted, audit and map wrappers, and sub-loggers.
+- **Formats**: Serilog output templates (`{Timestamp:HH:mm:ss} [{Level:u3}] {Message:lj}{NewLine}{Exception}`), flat JSON with configurable keys, CLEF with the `@i` event-type hash.
+- **Request logging** for Next.js route handlers, middleware and `instrumentation.ts`, and for Express — one completion event per request with a diagnostic context, like `UseSerilogRequestLogging`.
+- **Timed operations**: `log.timed('Sync {Count} rows', () => …)` → `Sync 42 rows completed in 12.3 ms`.
+- **Zero dependencies**, ESM + CJS, TypeScript types, isomorphic core (Node ≥ 20.16, Bun, Deno, the Next.js edge runtime, browsers).
+
+## Configure
+
+```ts
+import { configure, consoleSink, seqSink, withEnvironment } from '@unhingged/logit';
+import { fileSink, withMachineName, closeOnExit } from '@unhingged/logit/node';
+
+const log = configure({
+  minimumLevel: 'debug',
+  overrides: { next: 'warn', 'app.db': 'verbose' },
+  enrichers: [withEnvironment(), withMachineName()],
+  destructuring: { redact: ['password', 'headers.authorization'] },
+  sinks: [
+    consoleSink(),
+    fileSink({ path: 'logs/app.log', rolling: 'day', retainedFileCount: 14 }),
+    seqSink({ serverUrl: 'http://localhost:5341' }),
+  ],
+});
+
+closeOnExit(log);
+```
+
+Or, if you have Serilog in your fingers:
+
+```ts
+import { LoggerConfiguration } from '@unhingged/logit';
+
+const log = new LoggerConfiguration()
+  .minimumLevel.debug()
+  .minimumLevel.override('next', 'warn')
+  .enrich.withProperty('Application', 'shop')
+  .writeTo.console()
+  .createLogger();
+```
+
+## Next.js
+
+```ts
+// instrumentation.ts
+import { createOnRequestError } from '@unhingged/logit/next';
+
+export async function register() {
+  // Literal check: Next inlines NEXT_RUNTIME at build time and drops this
+  // branch — and its Node-only import — from the edge bundle.
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { configure, consoleSink } = await import('@unhingged/logit/node');
+    configure({ sinks: [consoleSink()] });
+  }
+}
+
+export const onRequestError = createOnRequestError();
+```
+
+```ts
+// app/api/orders/route.ts
+import { log, withLogging } from '@unhingged/logit/next';
+
+export const GET = withLogging(async () => {
+  log.info('Listing orders');
+  return Response.json([]);
+});
+// → HTTP GET /api/orders responded 200 in 1.8321 ms
+```
+
+## Entry points
+
+| Import | For |
+|---|---|
+| `@unhingged/logit` | The logger, templates, context, enrichers, filters, formatters, console / stream / memory / HTTP / Seq sinks. Isomorphic. |
+| `@unhingged/logit/node` | Rolling `fileSink`, `withMachineName`, `withProcessId`, `interceptConsole`, `closeOnExit`. |
+| `@unhingged/logit/next` | `withLogging`, `createOnRequestError`, `requestDiagnostics`. Edge-safe. |
+| `@unhingged/logit/express` | `requestLogger`, `errorLogger`. |
+| `@unhingged/logit/otel` | `otlpHttpSink`, `otelBridgeSink`, `encodeOtlpLogs`. |
+
+Every entry re-exports the root, so one import is enough.
+
+## Performance
+
+`scripts/bench.mjs` in the repository, Node 20, JSON to a null stream, 200 000 events each (2026-10-08, Apple Silicon laptop):
+
+| | logit | pino | winston |
+|---|---|---|---|
+| `info('Order {OrderId} shipped', id)` | 1.48 M events/s | 1.91 M | 0.78 M |
+| …with a nested object and `{Elapsed:0.0}` | 0.59 M events/s | 1.11 M | 0.54 M |
+| Capture only (null sink) | 3.2 M events/s | | |
+| Level disabled | 33 M calls/s | | |
+
+pino is faster because it does less per event — no template rendering, no capture rules. logit's capture is cheap; the formatting path is where the difference lives, and in practice both are far ahead of what any file, socket or HTTP sink can absorb.
+
+## License
+
+MIT — an [unhingged.com](https://unhingged.com) project.