@tanngo11/log 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+## 0.3.0
+
+Added:
+- `@tanngo11/log/prisma`: `prismaLogging(log)` Prisma Client extension (Prisma 5 and 6). Logs
+  `db.slow_query` with model, operation, rows and duration, and optionally `db.error`. It never
+  logs SQL or arguments. Tested against a real Prisma client on SQLite.
+- Custom redaction: `redactKeys` accepts RegExp, `redactValues` masks value patterns in every
+  string, and the `redact(key, value)` hook can replace or drop fields. Opt-in
+  `REDACT_PATTERNS`: `phoneVN`, `paymentCard`, `ipv4`.
+- NestJS on the Fastify adapter. `setupNestLogging(app, log)` configures either adapter in one
+  call.
+
+## 0.2.0
+
+Breaking:
+- `installProcessHandlers` no longer listens to SIGTERM/SIGINT. Call `logShutdown(log)` from your
+  own shutdown handler to log `app.stopping`. The old behavior could kill an app in the middle of
+  its graceful shutdown.
+- On a crash the exit is deferred (`exitDelayMs`, default 1000 ms), so other crash handlers
+  (Sentry, APM) still run.
+- When the route is unknown, the `http.request` message is `"<METHOD> <status>"` (no raw path).
+
+Fixes:
+- Secrets were not redacted inside arrays, objects nested deeper than 3 levels, or non-error `err`
+  values. Camel-case keys were not redacted when `snakeCase: false`.
+- Many secret key names were missing: connection strings, DSNs, JWTs, session ids, credentials.
+  Keys are now matched on any snake_case part.
+- Credentials in URLs, Bearer tokens, JWTs and emails are masked inside any string.
+- `withLogging` accepts handlers typed with `NextRequest`. Non-object throws are logged once.
+- Express keeps the mount prefix in `http_route` when a sub-router fails.
+- `addContext` / `recordError` inside nested contexts reach the request's summary line.
+- Fastify logs `499` when the client aborts.
+- `NestLogger` keeps extra arguments (objects become fields, others go to `nest_args`).
+- `loggedProcessor` forwards all BullMQ arguments and logs `UnrecoverableError` at error level.
+
+Added:
+- `patchConsole(log)`: routes `console.*` through the logger.
+- `withAction`: wraps a Next.js server action (`action.completed` / `action.failed`).
+- `jobData(data)`: adds the current `request_id` to a job payload.
+- `logShutdown(log)`.
+
+## 0.1.0
+
+- Core logger implementing log contract v1: normalization, redaction, size limits, async context.
+- Adapters: Express, Fastify, NestJS, Next.js (route handlers, onRequestError, edge request id), BullMQ.
+- Helpers: createFetch (http.outbound), runJob (job.*), process lifecycle (app.*).

package/CONTRACT.md

@@ -0,0 +1,135 @@
+# Log contract v1
+
+The rules every server-side service follows so its logs read the same way to people and to AI
+agents. `@tanngo11/log` implements them for Node. Services in other languages can follow them by
+hand.
+
+Assumed pipeline: container stdout → Vector (adds metadata, redacts secrets) → OpenObserve (one
+stream, nested fields flattened with `_`) → MCP for AI agents.
+
+## 1. Output format
+
+1. **One JSON object per line on stdout or stderr.** Do not write log files, and do not send logs
+   over HTTP from the app. Logs must pass through the redaction step on the host.
+2. **No multi-line output.** The stack trace goes in `err_stack` on the same line.
+3. **Flat snake_case fields.** Values are only strings, numbers or booleans. Group related fields
+   with a prefix (`http_`, `err_`, `db_`, `job_`). Turn arrays into counts or ids.
+4. **Do not rely on an app timestamp.** The collector sets the time.
+5. **Reserved names.** The collector sets or overwrites these, so apps never use them:
+   `project`, `service`, `vps`, `version`, `container_name`, `container_id`, `image`, `stream`,
+   `_timestamp`, `label`, `host`, `source_type`, `msg`, `lvl`, `severity`. To rename a
+   project or service, use the Docker labels `log.project` / `log.service`.
+6. **Size limits:**
+   - the whole line ≤ 16 KB, because Docker splits longer lines and the JSON breaks;
+   - `message` ≤ 500 characters;
+   - `err_stack` ≤ 4000 characters;
+   - other strings ≤ 1000 characters.
+
+## 2. Standard fields
+
+| Group | Fields |
+|---|---|
+| Core | `level` (`trace\|debug\|info\|warn\|error\|fatal`), `message`, `event` (required for warn/error/fatal) |
+| Correlation | `request_id`, `trace_id`, `span_id`, `job_name`, `job_id`, `job_attempt`, `user_id` (internal id, never an email), `tenant_id` |
+| Inbound HTTP | `http_method`, `http_route` (template, e.g. `/orders/:id`), `http_path` (no query string), `http_status`, `duration_ms` |
+| Outbound HTTP | `peer_service`, `http_method`, `http_url` (no query string or credentials), `http_status`, `duration_ms` |
+| Error | `err_type`, `err_message`, `err_code` (string), `err_stack`, `err_cause` (cause chain joined with ` <- `, max 5) |
+| Database | `db_system`, `db_operation`, `db_table`, `db_rows`, `duration_ms`, `db_statement` (parameterized only) |
+
+Naming rules for domain fields:
+- ids: `<entity>_id`;
+- durations: `*_ms`;
+- sizes: `*_bytes`;
+- counts: `*_count`;
+- booleans: `is_*` / `has_*`;
+- money: `amount_minor` (integer, smallest unit) + `currency`.
+
+A concept has one name in every service.
+
+## 3. Levels
+
+| Level | Use for |
+|---|---|
+| `fatal` | The process cannot continue and is about to exit. |
+| `error` | An operation failed and someone must investigate: a 5xx response, or a job that has used up its retries. |
+| `warn` | Something unusual that was handled, or a client error: 4xx, retry, fallback, a slow query or call. |
+| `info` | Lifecycle and business events: request summaries, start/stop, a job done, an order created. |
+| `debug` / `trace` | Diagnostics. Off in production. |
+
+- Invalid user input is never `error`.
+- `LOG_LEVEL` controls the level and defaults to `info`.
+
+## 4. `event` and `message`
+
+- `event` names are `<domain>.<action>`: lowercase, past tense for things that happened, for
+  example `order.created` or `payment.failed`.
+- Once an `event` name is used, never rename it.
+- `message` is a **constant** English phrase. Variables go in fields, not in the text.
+- Two exceptions:
+  - `http.request` uses `"<METHOD> <route template> <status>"`, or `"<METHOD> <status>"` when the
+    route is unknown. It never contains the raw path.
+  - `console` lines (legacy `console.*` calls routed through the logger) keep the original text.
+
+System events shared by all services:
+
+| Event | Level | When |
+|---|---|---|
+| `app.started` | info | ready to serve (with `runtime_version`, `log_level`, `port`) |
+| `app.stopping` | info | the app starts its own graceful shutdown |
+| `app.crashed` | fatal | uncaught error, process exits |
+| `app.unhandled_error` | error | uncaught error, process keeps running |
+| `config.invalid` | fatal | missing or invalid config at startup (never log the value) |
+| `http.request` | by status | one summary line per inbound request |
+| `http.outbound` | warn | an outbound call failed (network error or 5xx) or was slow (≥ 1 s) |
+| `db.slow_query` | warn | a query took longer than the threshold (default 500 ms) |
+| `db.error` | error | a database error that no upper layer handles |
+| `job.started` / `job.completed` | info | job lifecycle |
+| `job.failed` | warn if retries remain, error on the final attempt or a non-retryable error | job error |
+| `action.completed` | info | a server action finished, including a redirect or not-found (with `action_name`, `duration_ms`) |
+| `action.failed` | error | a server action threw |
+| `console` | by console method | a legacy `console.*` call (with `console_method`) |
+
+## 5. What to log
+
+**Required:**
+- `app.started` and `app.stopping`.
+- One `http.request` line per request: 5xx at `error`, 4xx at `warn`, otherwise `info`. Skip
+  health checks, static assets and `OPTIONS`.
+- **Log each error once, at the boundary.** Code that rethrows does not log. A failed request
+  produces one `error` line: its `http.request` line, carrying `err_*`.
+- `job.completed` / `job.failed` with `job_name`, `job_id` and `duration_ms`.
+- Outbound calls that fail or are slow.
+- Important business events, with entity ids.
+
+**Never log:**
+- secrets: passwords, tokens, API keys, cookies, `Authorization` headers, connection strings;
+- request or response bodies;
+- query strings;
+- personal data: email, phone, name, address, ID numbers, IP address, full user agent;
+- card or bank numbers;
+- SQL with its parameter values;
+- dumps of environment variables.
+
+## 6. Correlation
+
+- Reuse an incoming `x-request-id` if it is valid (≤ 64 characters, `[A-Za-z0-9._-]`).
+  Otherwise generate a UUID v4. Return it as a response header.
+- Parse W3C `traceparent` into `trace_id` and `span_id`. Do not invent trace ids.
+- Forward `x-request-id` and `traceparent` to services you own, never to third parties.
+- A job enqueued from a request carries that request's `request_id` in its payload.
+- Every log line inside a request or job gets these fields from async context, without being
+  passed by hand.
+
+## 7. Compliance levels
+
+| Level | Requires |
+|---|---|
+| L1 | JSON lines, a textual `level`, `message`, no reserved names, no secrets or personal data |
+| L2 | L1 + `request_id` on every line of a request, the `http.request` line, `err_*` on failures, `event` on warn/error/fatal |
+| L3 | L2 + `http.outbound`, `job.*`, header propagation, constant messages |
+
+## 8. Versioning
+
+- Adding fields or events keeps version v1.
+- Renaming a field or changing its meaning needs a v2, with migration notes, and a major release
+  of the library.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tan Ngo
+
+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

@@ -0,0 +1,291 @@
+# @tanngo11/log
+
+Structured JSON logging for Node services. It writes one JSON line per log to stdout, following
+[log contract v1](CONTRACT.md),
+so every service is searchable the same way in OpenObserve and readable by AI agents through MCP.
+
+- Zero runtime dependencies, Node ≥ 20, ESM and CommonJS.
+- Request context (`request_id`, `trace_id`, `user_id`...) on every line via `AsyncLocalStorage`.
+- One `http.request` summary line per request, carrying the error when the request fails.
+- Adapters for Express, Fastify, NestJS, Next.js (App Router) and BullMQ.
+
+## Install
+
+```bash
+npm i @tanngo11/log
+# before the npm package is published:
+npm i github:TanNgo11/node-log#v0.1.0
+```
+
+## Core
+
+```ts
+// src/lib/log.ts
+import { createLogger } from "@tanngo11/log";
+
+export const log = createLogger();
+```
+
+```ts
+log.info("order created", { event: "order.created", order_id: order.id, items_count: 3 });
+log.warn("shipping quote failed, using flat rate", { event: "shipping_quote.fallback_used", err });
+log.error("create order failed", { event: "order.create_failed", err });
+```
+
+Every level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`) takes `(message, fields?)`.
+
+- Keep `message` constant. Put variable values in fields.
+- `event` is required for `warn`, `error` and `fatal`.
+- Pass errors as `err`. They become `err_type`, `err_message`, `err_code`, `err_stack` and
+  `err_cause`.
+
+| Env | Default | Meaning |
+|---|---|---|
+| `LOG_LEVEL` | `info` | minimum level written |
+| `LOG_FORMAT` | `json` | `pretty` prints readable lines for local development only |
+
+`createLogger(options)` accepts:
+- `level`, `format`;
+- `base`: fields added to every line;
+- `redactKeys`, `redactValues`, `redact`: custom redaction (see below);
+- `snakeCase`: default `true`;
+- `write`: replaces stdout, for tests.
+
+### Custom redaction
+
+```ts
+import { createLogger, REDACT_PATTERNS } from "@tanngo11/log";
+
+export const log = createLogger({
+  // extra key names, or RegExp tested on the snake_case key
+  redactKeys: ["tax_code", /^national_id/],
+  // value patterns masked in every string, including messages
+  redactValues: [REDACT_PATTERNS.phoneVN, REDACT_PATTERNS.paymentCard],
+  // last step for each field; return undefined to drop the field
+  redact: (key, value) => (key === "customer_name" && typeof value === "string" ? `${value[0]}***` : value),
+});
+```
+
+- `REDACT_PATTERNS` currently contains `phoneVN`, `paymentCard` and `ipv4`.
+- These patterns are opt-in because they can match ordinary numbers. `paymentCard` does not
+  match 13-digit millisecond timestamps.
+- The `redact` hook never receives `level`, `message` or `event`.
+- If the hook throws, that line becomes a `log.serialize_failed` line instead.
+
+### Context
+
+```ts
+import { addContext, recordError, withContext } from "@tanngo11/log";
+
+await withContext({ tenant_id }, () => handle());  // every log inside carries tenant_id
+addContext({ user_id: user.id });                   // after authentication, inside a request
+recordError(err);                                    // attach err to the request's http.request line
+```
+
+`log.child({ job_name: "sync_stock" })` returns a logger that always adds those fields.
+
+### What the logger normalizes
+
+Applied in this order:
+1. Merges fields: `base`, then context, then `child`, then the call. Later sources win.
+2. Flattens nested objects with `_`, up to three key segments (`order.customer.id` becomes
+   `order_customer_id`). Arrays and deeper objects become JSON strings.
+3. Converts camelCase keys to snake_case (`orderId` becomes `order_id`). Pass `snakeCase: false`
+   to turn this off.
+4. Prefixes keys that Vector overwrites with `app_`: `project`, `service`, `version`, `host`,
+   `msg`, `level`, `message`...
+5. Replaces the values of sensitive keys with `[REDACTED]`, at any depth, including inside
+   arrays.
+   - A key counts as sensitive when any snake_case part of it names a secret: `password`,
+     `secret`, `token`, `api_key`, `authorization`, `cookie`, `session_id`, `credentials`, `dsn`,
+     `connection_string`, `jwt`...
+   - So `stripeSecretKey` and `x-api-key` are redacted.
+   - Keys that only describe a secret stay readable: `token_count`, `token_type`,
+     `password_reset_at`.
+   - `redactKeys` adds more key names.
+6. Masks secrets inside any string value or message:
+   - credentials in URLs (`postgres://[REDACTED]@db`);
+   - `Bearer` tokens;
+   - JWTs;
+   - email addresses (`***@example.com`).
+7. Strips the query string, hash and credentials from `http_path`, `http_url` and every
+   `*_url` field.
+8. Truncates `message` to 500 chars, `err_stack` to 4000 and other strings to 1000. Lines over
+   16000 bytes keep only core fields and get `log_truncated: true`.
+
+The logger never throws into your code.
+
+### Outbound calls, jobs, lifecycle
+
+```ts
+import { createFetch, installProcessHandlers, jobData, logShutdown, logStartup, runJob } from "@tanngo11/log";
+
+const ghn = createFetch(log, { peer_service: "ghn" });                 // logs http.outbound on 5xx, network error, or > 1s
+const api = createFetch(log, { peer_service: "backend-api", internal: true }); // also forwards x-request-id / traceparent
+
+await runJob(log, { job_name: "sync_stock", job_id: id }, () => syncStock()); // job.completed / job.failed
+await queue.add("send_invoice", jobData({ invoice_id }));             // carries the current request_id into the job
+
+installProcessHandlers(log); // app.crashed on uncaught errors, then exit(1) after 1s so Sentry & co. can flush
+logStartup(log, { port: 3000 }); // app.started
+
+process.once("SIGTERM", async () => {
+  logShutdown(log, { signal: "SIGTERM" }); // app.stopping; the library never handles signals itself
+  await server.close();
+  process.exit(0);
+});
+```
+
+### Legacy `console.*` calls
+
+```ts
+import { patchConsole } from "@tanngo11/log";
+
+patchConsole(log); // console.log/info → info, warn → warn, error → error, debug/trace → debug
+```
+
+Every `console.*` call becomes a JSON line with `event: "console"` and the request context. This
+gets an old codebase to contract level L1 in one line. Framework output that goes through
+`console`, such as Next.js error printing, is covered too. The function returns `restore()`.
+
+## Express
+
+```ts
+import { errorRecorder, requestLogger } from "@tanngo11/log/express";
+
+app.use(requestLogger(log));   // before routes
+// ... routes ...
+app.use(errorRecorder());      // after routes, before your error handler
+app.use(yourErrorHandler);
+```
+
+## Fastify
+
+```ts
+import { fastifyLogger } from "@tanngo11/log/fastify";
+
+const app = Fastify({ logger: false });
+await app.register(fastifyLogger, { log });
+```
+
+## NestJS (Express or Fastify adapter)
+
+```ts
+import { NestLogger, setupNestLogging } from "@tanngo11/log/nest";
+
+const app = await NestFactory.create(AppModule, { logger: new NestLogger(log) });
+// or: NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter(), { logger: new NestLogger(log) })
+await setupNestLogging(app, log); // before app.listen()
+```
+
+`setupNestLogging` detects the adapter:
+- Express gets the `requestLogger` middleware.
+- Fastify gets the `fastifyLogger` plugin.
+
+Both get `ErrorRecorderInterceptor`. For manual setup, `requestLogger`, `fastifyLogger` and
+`ErrorRecorderInterceptor` are exported too.
+
+Nest's own logs become JSON with `nest_context`. Extra arguments are kept: objects become fields,
+other values go to `nest_args`. Unhandled exceptions are written once, on the
+`http.request` line, not again by Nest's `ExceptionsHandler`. Requires `rxjs` (already a Nest
+dependency).
+
+## Next.js (App Router)
+
+Route handlers:
+
+```ts
+// app/api/orders/[id]/route.ts
+import { withLogging } from "@tanngo11/log/next";
+import { log } from "@/lib/log";
+
+export const GET = withLogging(log, async (request: NextRequest, { params }) => { /* ... */ }, { route: "/api/orders/[id]" });
+```
+
+Server actions:
+
+```ts
+"use server";
+import { withAction } from "@tanngo11/log/next";
+
+export const saveOrder = withAction(log, "save_order", async (input: OrderInput) => { /* ... */ });
+// action.completed (info) or action.failed (error, once); redirect()/notFound() count as completed
+```
+
+Server components and anything not wrapped:
+
+```ts
+// instrumentation.ts
+import { patchConsole } from "@tanngo11/log";
+import { nextOnRequestError, registerNext } from "@tanngo11/log/next";
+import { log } from "@/lib/log";
+
+export function register() {
+  registerNext(log); // app.started + crash logging (Next keeps serving, so no exit)
+  patchConsole(log); // Next's own error output and leftover console.* become JSON
+}
+export const onRequestError = nextOnRequestError(log);
+```
+
+Optional: give every request an `x-request-id` in `middleware.ts` (edge runtime):
+
+```ts
+import { withRequestId } from "@tanngo11/log/next/edge";
+
+export function middleware(request: NextRequest) {
+  return NextResponse.next({ request: { headers: withRequestId(request) } });
+}
+```
+
+Notes:
+- `redirect()` and `notFound()` are logged with their real status (307, 404), not as errors.
+- Errors already logged by `withLogging` are not logged again by `onRequestError`.
+- If the edge build complains about the import in `instrumentation.ts`, import inside
+  `register()`: `if (process.env.NEXT_RUNTIME === "nodejs") { const { registerNext } = await import("@tanngo11/log/next"); ... }`.
+
+## BullMQ
+
+```ts
+import { loggedProcessor } from "@tanngo11/log/bullmq";
+
+new Worker("invoices", loggedProcessor(log, "send_invoice_email", async (job) => { /* ... */ }));
+```
+
+- A failure on the final attempt, or an `UnrecoverableError`, is logged at `error`. Earlier
+  attempts fail at `warn`.
+- When enqueueing from a request, use `queue.add(name, jobData(data))`. The job's logs then carry
+  that request's `request_id`.
+
+## Prisma (5 and 6)
+
+```ts
+import { prismaLogging } from "@tanngo11/log/prisma";
+
+export const prisma = new PrismaClient().$extends(prismaLogging(log, { db_system: "postgres" }));
+```
+
+- Logs `db.slow_query` (`warn`) for queries that take 500 ms or more (`slowMs`). Fields:
+  `db_table` (the model), `db_operation` (`findMany`, `$queryRaw`...), `db_rows`, `duration_ms`.
+- Never logs SQL text or query arguments.
+- Failed queries are not logged by default. The error already reaches the request's
+  `http.request` line with `err_code` (`P2002`...), and the contract logs each error once. Pass
+  `logErrors: true` to also get a `db.error` line.
+
+## Migrating from the shared winston logger
+
+For repos using the old shared winston logger (S3 transport, nested metadata):
+
+1. Replace `src/lib/logger/index.ts` with `export const log = createLogger(); export const logger = log;`.
+2. Rewrite each `log.error(msg, err, meta)` call as `log.error(msg, { ...meta, err })`.
+3. In `withErrorHandler`, replace the `logger.error("API Error", ...)` call with
+   `recordError(error)`. Then wrap routes with `withLogging`.
+4. Remove the S3 transport. OpenObserve already stores the logs.
+5. Call `patchConsole(log)` once at startup. Remaining `console.*` calls are then JSON too.
+
+## Rules the library cannot enforce
+
+- Use a constant `message` and stable `event` names.
+- Never log request or response bodies, query strings, email addresses, phone numbers, tokens or
+  card data.
+
+See sections 4 and 5 of the contract.

package/dist/bullmq.cjs

@@ -0,0 +1,108 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/bullmq.ts
+var bullmq_exports = {};
+__export(bullmq_exports, {
+  loggedProcessor: () => loggedProcessor
+});
+module.exports = __toCommonJS(bullmq_exports);
+
+// src/context.ts
+var import_node_async_hooks = require("async_hooks");
+
+// src/global.ts
+function globalSingleton(name, make) {
+  const key = /* @__PURE__ */ Symbol.for(`@tanngo11/log.${name}`);
+  const g = globalThis;
+  let value = g[key];
+  if (value === void 0) {
+    value = make();
+    g[key] = value;
+  }
+  return value;
+}
+
+// src/context.ts
+var als = globalSingleton("als", () => new import_node_async_hooks.AsyncLocalStorage());
+function runWithStore(fields, fn) {
+  const parent = als.getStore();
+  const store = { fields: { ...parent?.fields, ...fields }, parent };
+  return als.run(store, () => fn(store));
+}
+function withContext(fields, fn) {
+  return runWithStore(fields, () => fn());
+}
+
+// src/error.ts
+var logged = globalSingleton("logged", () => /* @__PURE__ */ new WeakSet());
+function markLogged(err) {
+  if (typeof err === "object" && err !== null) logged.add(err);
+}
+
+// src/job.ts
+async function runJob(log, info, fn) {
+  const ctx = { ...info.fields, job_name: info.job_name };
+  if (info.job_id !== void 0) ctx.job_id = String(info.job_id);
+  if (info.job_attempt !== void 0) ctx.job_attempt = info.job_attempt;
+  if (info.request_id !== void 0) ctx.request_id = info.request_id;
+  return withContext(ctx, async () => {
+    const start = performance.now();
+    try {
+      const result = await fn();
+      log.info("job completed", { event: "job.completed", duration_ms: Math.round(performance.now() - start) });
+      return result;
+    } catch (err) {
+      const final = typeof info.final_attempt === "function" ? info.final_attempt(err) : info.final_attempt ?? true;
+      log[final ? "error" : "warn"]("job failed", {
+        event: "job.failed",
+        duration_ms: Math.round(performance.now() - start),
+        err
+      });
+      markLogged(err);
+      throw err;
+    }
+  });
+}
+
+// src/bullmq.ts
+function loggedProcessor(log, name, processor) {
+  return (job, ...rest) => {
+    const attempts = job.opts?.attempts ?? 1;
+    const attempt = job.attemptsMade + 1;
+    const requestId = job.data?.request_id;
+    return runJob(
+      log,
+      {
+        job_name: name,
+        job_id: job.id,
+        job_attempt: attempt,
+        // UnrecoverableError skips the remaining retries.
+        final_attempt: (err) => attempt >= attempts || err?.name === "UnrecoverableError",
+        request_id: typeof requestId === "string" ? requestId : void 0
+      },
+      () => processor(job, ...rest)
+    );
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loggedProcessor
+});
+//# sourceMappingURL=bullmq.cjs.map

package/dist/bullmq.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bullmq.ts","../src/context.ts","../src/global.ts","../src/error.ts","../src/job.ts"],"sourcesContent":["import { runJob } from \"./job\";\nimport type { Logger } from \"./logger\";\n\n/** Minimal shape of a BullMQ Job; avoids depending on bullmq. */\nexport interface BullJobLike {\n  id?: string;\n  attemptsMade: number;\n  opts?: { attempts?: number };\n  data?: unknown;\n}\n\nexport function loggedProcessor<J extends BullJobLike, R, A extends unknown[] = [token?: string, signal?: AbortSignal]>(\n  log: Logger,\n  name: string,\n  processor: (job: J, ...rest: A) => Promise<R>,\n): (job: J, ...rest: A) => Promise<R> {\n  return (job, ...rest) => {\n    const attempts = job.opts?.attempts ?? 1;\n    const attempt = job.attemptsMade + 1;\n    const requestId = (job.data as { request_id?: unknown } | undefined)?.request_id;\n    return runJob(\n      log,\n      {\n        job_name: name,\n        job_id: job.id,\n        job_attempt: attempt,\n        // UnrecoverableError skips the remaining retries.\n        final_attempt: (err) => attempt >= attempts || (err as { name?: unknown } | null)?.name === \"UnrecoverableError\",\n        request_id: typeof requestId === \"string\" ? requestId : undefined,\n      },\n      () => processor(job, ...rest),\n    );\n  };\n}\n","import { AsyncLocalStorage } from \"node:async_hooks\";\nimport { globalSingleton } from \"./global\";\nimport type { Fields } from \"./normalize\";\n\nexport interface ContextStore {\n  fields: Fields;\n  error?: unknown;\n  /** Route template captured while the router still knew it (Express error path). */\n  route?: string;\n  parent?: ContextStore;\n}\n\nconst als = globalSingleton(\"als\", () => new AsyncLocalStorage<ContextStore>());\n\nexport const STORE_KEY: symbol = Symbol.for(\"@tanngo11/log.store\");\n\nexport function runWithStore<T>(fields: Fields, fn: (store: ContextStore) => T): T {\n  const parent = als.getStore();\n  const store: ContextStore = { fields: { ...parent?.fields, ...fields }, parent };\n  return als.run(store, () => fn(store));\n}\n\nexport function withContext<T>(fields: Fields, fn: () => T): T {\n  return runWithStore(fields, () => fn());\n}\n\nexport function currentStore(): ContextStore | undefined {\n  return als.getStore();\n}\n\nexport function getContext(): Fields {\n  return als.getStore()?.fields ?? {};\n}\n\n// Applies to the current context and every enclosing one, so a field added inside a nested\n// withContext/runJob still reaches the request's http.request line.\nexport function addContext(fields: Fields): void {\n  for (let s = als.getStore(); s; s = s.parent) Object.assign(s.fields, fields);\n}\n\n// Sets the error on the store and on enclosing stores that have none yet.\nexport function recordErrorIn(store: ContextStore, err: unknown): void {\n  store.error = err;\n  for (let s = store.parent; s; s = s.parent) if (s.error === undefined) s.error = err;\n}\n\n// Marks the error that the current request/job summary line should carry. Does not write a line.\nexport function recordError(err: unknown): void {\n  const store = als.getStore();\n  if (store) recordErrorIn(store, err);\n}\n\nexport function attachStore(target: object, store: ContextStore): void {\n  (target as Record<symbol, ContextStore>)[STORE_KEY] = store;\n}\n\nexport function storeOf(target: unknown): ContextStore | undefined {\n  if (typeof target !== \"object\" || target === null) return undefined;\n  return (target as Record<symbol, ContextStore | undefined>)[STORE_KEY];\n}\n","// Singletons shared by every copy of this package loaded in the process (ESM and CJS builds,\n// or duplicated installs), so context and dedupe state never split.\nexport function globalSingleton<T>(name: string, make: () => T): T {\n  const key = Symbol.for(`@tanngo11/log.${name}`);\n  const g = globalThis as unknown as Record<symbol, T | undefined>;\n  let value = g[key];\n  if (value === undefined) {\n    value = make();\n    g[key] = value;\n  }\n  return value;\n}\n","import { globalSingleton } from \"./global\";\nimport { defaultRedactor } from \"./redact\";\n\nexport interface ErrFields {\n  err_type?: string;\n  err_message?: string;\n  err_code?: string;\n  err_stack?: string;\n  err_cause?: string;\n}\n\nconst MAX_CAUSE_DEPTH = 5;\n\nexport function isErrorLike(v: unknown): v is Error {\n  if (v instanceof Error) return true;\n  return (\n    typeof v === \"object\" &&\n    v !== null &&\n    typeof (v as { message?: unknown }).message === \"string\" &&\n    (\"stack\" in v || \"name\" in v)\n  );\n}\n\nfunction errorType(e: Error): string {\n  if (e.name && e.name !== \"Error\") return e.name;\n  const ctor = (e as { constructor?: { name?: string } }).constructor?.name;\n  return ctor && ctor !== \"Object\" ? ctor : \"Error\";\n}\n\nexport function serializeError(err: unknown): ErrFields {\n  if (!isErrorLike(err)) {\n    if (typeof err === \"string\") return { err_type: \"string\", err_message: err };\n    return { err_type: typeof err, err_message: defaultRedactor.json(err) };\n  }\n  const e = err as Error & { code?: unknown; cause?: unknown };\n  const out: ErrFields = { err_type: errorType(e), err_message: String(e.message ?? \"\") };\n  if (e.code !== undefined && e.code !== null) out.err_code = String(e.code);\n  if (typeof e.stack === \"string\") out.err_stack = e.stack;\n\n  const causes: string[] = [];\n  let cause = e.cause;\n  while (cause !== undefined && cause !== null && causes.length < MAX_CAUSE_DEPTH) {\n    if (isErrorLike(cause)) {\n      causes.push(`${errorType(cause)}: ${cause.message}`);\n      cause = (cause as { cause?: unknown }).cause;\n    } else {\n      causes.push(defaultRedactor.json(cause));\n      cause = undefined;\n    }\n  }\n  if (causes.length > 0) out.err_cause = causes.join(\" <- \");\n  return out;\n}\n\nconst logged = globalSingleton(\"logged\", () => new WeakSet<object>());\n\n// Marks an error as already written, so a later boundary (e.g. Next's onRequestError)\n// does not log it a second time.\nexport function markLogged(err: unknown): void {\n  if (typeof err === \"object\" && err !== null) logged.add(err);\n}\n\nexport function isLogged(err: unknown): boolean {\n  return typeof err === \"object\" && err !== null && logged.has(err);\n}\n","import { getContext, withContext } from \"./context\";\nimport { markLogged } from \"./error\";\nimport type { Logger } from \"./logger\";\nimport type { Fields } from \"./normalize\";\n\nexport interface JobInfo {\n  job_name: string;\n  job_id?: string | number;\n  job_attempt?: number;\n  /** No retries left after this attempt (or decided per error). Defaults to true when unknown. */\n  final_attempt?: boolean | ((err: unknown) => boolean);\n  request_id?: string;\n  fields?: Fields;\n}\n\nexport async function runJob<T>(log: Logger, info: JobInfo, fn: () => T | Promise<T>): Promise<T> {\n  const ctx: Fields = { ...info.fields, job_name: info.job_name };\n  if (info.job_id !== undefined) ctx.job_id = String(info.job_id);\n  if (info.job_attempt !== undefined) ctx.job_attempt = info.job_attempt;\n  if (info.request_id !== undefined) ctx.request_id = info.request_id;\n\n  return withContext(ctx, async () => {\n    const start = performance.now();\n    try {\n      const result = await fn();\n      log.info(\"job completed\", { event: \"job.completed\", duration_ms: Math.round(performance.now() - start) });\n      return result;\n    } catch (err) {\n      const final = typeof info.final_attempt === \"function\" ? info.final_attempt(err) : (info.final_attempt ?? true);\n      log[final ? \"error\" : \"warn\"](\"job failed\", {\n        event: \"job.failed\",\n        duration_ms: Math.round(performance.now() - start),\n        err,\n      });\n      markLogged(err);\n      throw err;\n    }\n  });\n}\n\n/** Adds the current request_id to a job payload, so the job's logs link back to the request. */\nexport function jobData<T extends Record<string, unknown>>(data: T): T & { request_id?: string } {\n  const requestId = getContext().request_id;\n  if (typeof requestId !== \"string\" || data.request_id !== undefined) return data;\n  return { ...data, request_id: requestId };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,8BAAkC;;;ACE3B,SAAS,gBAAmB,MAAc,MAAkB;AACjE,QAAM,MAAM,uBAAO,IAAI,iBAAiB,IAAI,EAAE;AAC9C,QAAM,IAAI;AACV,MAAI,QAAQ,EAAE,GAAG;AACjB,MAAI,UAAU,QAAW;AACvB,YAAQ,KAAK;AACb,MAAE,GAAG,IAAI;AAAA,EACX;AACA,SAAO;AACT;;;ADCA,IAAM,MAAM,gBAAgB,OAAO,MAAM,IAAI,0CAAgC,CAAC;AAIvE,SAAS,aAAgB,QAAgB,IAAmC;AACjF,QAAM,SAAS,IAAI,SAAS;AAC5B,QAAM,QAAsB,EAAE,QAAQ,EAAE,GAAG,QAAQ,QAAQ,GAAG,OAAO,GAAG,OAAO;AAC/E,SAAO,IAAI,IAAI,OAAO,MAAM,GAAG,KAAK,CAAC;AACvC;AAEO,SAAS,YAAe,QAAgB,IAAgB;AAC7D,SAAO,aAAa,QAAQ,MAAM,GAAG,CAAC;AACxC;;;AE8BA,IAAM,SAAS,gBAAgB,UAAU,MAAM,oBAAI,QAAgB,CAAC;AAI7D,SAAS,WAAW,KAAoB;AAC7C,MAAI,OAAO,QAAQ,YAAY,QAAQ,KAAM,QAAO,IAAI,GAAG;AAC7D;;;AC7CA,eAAsB,OAAU,KAAa,MAAe,IAAsC;AAChG,QAAM,MAAc,EAAE,GAAG,KAAK,QAAQ,UAAU,KAAK,SAAS;AAC9D,MAAI,KAAK,WAAW,OAAW,KAAI,SAAS,OAAO,KAAK,MAAM;AAC9D,MAAI,KAAK,gBAAgB,OAAW,KAAI,cAAc,KAAK;AAC3D,MAAI,KAAK,eAAe,OAAW,KAAI,aAAa,KAAK;AAEzD,SAAO,YAAY,KAAK,YAAY;AAClC,UAAM,QAAQ,YAAY,IAAI;AAC9B,QAAI;AACF,YAAM,SAAS,MAAM,GAAG;AACxB,UAAI,KAAK,iBAAiB,EAAE,OAAO,iBAAiB,aAAa,KAAK,MAAM,YAAY,IAAI,IAAI,KAAK,EAAE,CAAC;AACxG,aAAO;AAAA,IACT,SAAS,KAAK;AACZ,YAAM,QAAQ,OAAO,KAAK,kBAAkB,aAAa,KAAK,cAAc,GAAG,IAAK,KAAK,iBAAiB;AAC1G,UAAI,QAAQ,UAAU,MAAM,EAAE,cAAc;AAAA,QAC1C,OAAO;AAAA,QACP,aAAa,KAAK,MAAM,YAAY,IAAI,IAAI,KAAK;AAAA,QACjD;AAAA,MACF,CAAC;AACD,iBAAW,GAAG;AACd,YAAM;AAAA,IACR;AAAA,EACF,CAAC;AACH;;;AJ3BO,SAAS,gBACd,KACA,MACA,WACoC;AACpC,SAAO,CAAC,QAAQ,SAAS;AACvB,UAAM,WAAW,IAAI,MAAM,YAAY;AACvC,UAAM,UAAU,IAAI,eAAe;AACnC,UAAM,YAAa,IAAI,MAA+C;AACtE,WAAO;AAAA,MACL;AAAA,MACA;AAAA,QACE,UAAU;AAAA,QACV,QAAQ,IAAI;AAAA,QACZ,aAAa;AAAA;AAAA,QAEb,eAAe,CAAC,QAAQ,WAAW,YAAa,KAAmC,SAAS;AAAA,QAC5F,YAAY,OAAO,cAAc,WAAW,YAAY;AAAA,MAC1D;AAAA,MACA,MAAM,UAAU,KAAK,GAAG,IAAI;AAAA,IAC9B;AAAA,EACF;AACF;","names":[]}

package/dist/bullmq.d.cts

@@ -0,0 +1,14 @@
+import { L as Logger } from './logger-CFMTzjsm.cjs';
+
+/** Minimal shape of a BullMQ Job; avoids depending on bullmq. */
+interface BullJobLike {
+    id?: string;
+    attemptsMade: number;
+    opts?: {
+        attempts?: number;
+    };
+    data?: unknown;
+}
+declare function loggedProcessor<J extends BullJobLike, R, A extends unknown[] = [token?: string, signal?: AbortSignal]>(log: Logger, name: string, processor: (job: J, ...rest: A) => Promise<R>): (job: J, ...rest: A) => Promise<R>;
+
+export { type BullJobLike, loggedProcessor };

package/dist/bullmq.d.ts

@@ -0,0 +1,14 @@
+import { L as Logger } from './logger-CFMTzjsm.js';
+
+/** Minimal shape of a BullMQ Job; avoids depending on bullmq. */
+interface BullJobLike {
+    id?: string;
+    attemptsMade: number;
+    opts?: {
+        attempts?: number;
+    };
+    data?: unknown;
+}
+declare function loggedProcessor<J extends BullJobLike, R, A extends unknown[] = [token?: string, signal?: AbortSignal]>(log: Logger, name: string, processor: (job: J, ...rest: A) => Promise<R>): (job: J, ...rest: A) => Promise<R>;
+
+export { type BullJobLike, loggedProcessor };