jsonl-logger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Annexare
+
+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,127 @@
+# jsonl-logger
+
+Lightweight JSON Lines logger with pluggable formatters. Modern ESM-only, zero dependencies, Bun-first, works on Node.js and Deno.
+
+## Install
+
+```bash
+bun add jsonl-logger
+# or
+npm install jsonl-logger
+```
+
+## Quick Start
+
+```typescript
+import { logger } from 'jsonl-logger'
+
+logger.info('Server started', { port: 3000 })
+logger.error('Request failed', { path: '/api' }, new Error('timeout'))
+```
+
+## Formatters
+
+Two built-in formatters for popular log backends:
+
+### Google Cloud Logging
+
+```typescript
+import { googleCloud } from 'jsonl-logger/google-cloud'
+import { Logger } from 'jsonl-logger'
+
+const logger = new Logger(undefined, { json: true, formatter: googleCloud })
+// Output: {"message":"...","timestamp":"...","severity":"INFO",...}
+```
+
+### VictoriaLogs (default)
+
+```typescript
+import { victoriaLogs } from 'jsonl-logger/victoria-logs'
+// Output: {"_msg":"...","_time":"...","level":"info",...}
+```
+
+### Custom Formatter
+
+```typescript
+import type { Formatter } from 'jsonl-logger'
+
+const myFormatter: Formatter = {
+  messageKey: 'msg',
+  format: (record) => ({
+    msg: record.message,
+    ts: record.timestamp,
+    lvl: record.level,
+    ...record.context,
+  }),
+}
+```
+
+## Console Interception
+
+Monkey-patch `console.*` methods to output structured JSON — captures logs from third-party libraries:
+
+```typescript
+import { intercept, originalConsole } from 'jsonl-logger/intercept'
+
+intercept({
+  // Optional: custom formatter (default: victoriaLogs)
+  formatter: googleCloud,
+  // Optional: filter out noisy messages
+  filter: (level, message) => !message.includes('deprecation'),
+  // Optional: minimum log level
+  level: 'warn',
+})
+
+// Already-formatted JSON from the Logger class passes through unchanged
+console.log('plain text') // → structured JSON
+originalConsole.log('bypass interception')
+```
+
+## Preload (Next.js Standalone)
+
+Auto-intercept from first line using `--preload`:
+
+```bash
+bun --preload jsonl-logger/preload server.js
+```
+
+Environment variables:
+- `LOG_FORMAT` — `google-cloud` or `victoria-logs` (default)
+- `LOG_LEVEL` — `debug`, `info` (default), `warn`, `error`, `fatal`
+
+## Child Loggers
+
+```typescript
+const requestLogger = logger.child({ requestId: 'abc-123', service: 'api' })
+requestLogger.info('Processing request')
+// All entries include requestId and service
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JSON_LOGS` | `false` | Enable JSON output (`true` for production) |
+| `LOG_LEVEL` | `info`/`debug` | Minimum log level (defaults to `info` when JSON, `debug` otherwise) |
+| `LOG_FORMAT` | `victoria-logs` | Formatter for preload module (`google-cloud` or `victoria-logs`) |
+
+## Runtime Detection
+
+The logger auto-detects the runtime and uses the fastest available I/O:
+- **Bun** / **Node.js** — `process.stdout.write` / `process.stderr.write` (bypasses console overhead)
+- **Deno** — `Deno.stdout.writeSync` / `Deno.stderr.writeSync`
+- **Browser / unknown** — falls back to `console.log` / `console.error`
+
+## Exports
+
+| Subpath | Export |
+|---------|--------|
+| `jsonl-logger` | `Logger`, `logger`, types |
+| `jsonl-logger/google-cloud` | `googleCloud` formatter |
+| `jsonl-logger/victoria-logs` | `victoriaLogs` formatter |
+| `jsonl-logger/intercept` | `intercept()`, `originalConsole` |
+| `jsonl-logger/preload` | Side-effect auto-intercept |
+
+## License
+
+MIT

package/dist/google-cloud.d.ts

@@ -0,0 +1,2 @@
+import type { Formatter } from './types';
+export declare const googleCloud: Formatter;

package/dist/google-cloud.js

@@ -0,0 +1 @@
+import{a}from"./index-rhgqp0zd.js";export{a as googleCloud};

package/dist/index-abhqk8y0.js

@@ -0,0 +1,4 @@
+var B={debug:0,info:1,warn:2,error:3,fatal:4},A=/\x1b\[[0-9;]*m/g;function C(h){return h.replace(A,"")}var w=typeof process<"u"&&process.stdout&&typeof process.stdout.write==="function"?"node":typeof Deno<"u"&&Deno.stdout?"deno":"browser",z=w==="deno"?new TextEncoder:null;function F(h,j){if(w==="node")(j?process.stderr??process.stdout:process.stdout).write(`${h}
+`);else if(w==="deno"&&z){let q=z.encode(`${h}
+`);if(j)Deno.stderr.writeSync(q);else Deno.stdout.writeSync(q)}else if(j)console.error(h);else console.log(h)}
+export{B as d,C as e,F as f};

package/dist/index-rhgqp0zd.js

@@ -0,0 +1,2 @@
+var t={debug:"DEBUG",info:"INFO",warn:"WARNING",error:"ERROR",fatal:"CRITICAL"},o={messageKey:"message",format(e){let r={message:e.message,timestamp:e.timestamp,severity:t[e.level],...e.context};if(e.error){if(r["error.name"]=e.error.name,r["error.message"]=e.error.message,e.error.stack)r["error.stack"]=e.error.stack}return r}};
+export{o as a};

package/dist/index-rxqh9v58.js

@@ -0,0 +1,2 @@
+var t={messageKey:"_msg",format(e){let r={_msg:e.message,_time:e.timestamp,level:e.level,...e.context};if(e.error){if(r["error.name"]=e.error.name,r["error.message"]=e.error.message,e.error.stack)r["error.stack"]=e.error.stack}return r}};
+export{t as g};

package/dist/index-x1ss6ry6.js

@@ -0,0 +1,2 @@
+import{d as G,e as Q,f as F}from"./index-abhqk8y0.js";import{g as R}from"./index-rxqh9v58.js";var A={log:console.log.bind(console),info:console.info.bind(console),warn:console.warn.bind(console),error:console.error.bind(console),debug:console.debug.bind(console)};function W(...j){let b="";for(let k=0;k<j.length;k++){if(k>0)b+=" ";let q=j[k];if(typeof q==="string")b+=Q(q);else if(q instanceof Error)b+=q.message;else try{b+=JSON.stringify(q)}catch{b+=String(q)}}return b.trim()}function X(...j){let b;for(let k of j)if(typeof k==="object"&&k!==null&&!(k instanceof Error)&&!Array.isArray(k)){if(!b)b={};Object.assign(b,k)}return b}function Y(...j){for(let b of j)if(b instanceof Error)return b}var H={debug:!1,info:!1,warn:!1,error:!0,fatal:!0};function Z(j,b,k,q){let D=`"${b.messageKey}"`;return(...z)=>{if(z.length===1&&typeof z[0]==="string"&&z[0].charCodeAt(0)===123&&z[0].includes(D)){F(z[0],H[j]);return}if(G[j]<k)return;let B=W(...z);if(q&&!q(j,B))return;let T=X(...z),C=Y(...z),U={level:j,message:B,timestamp:new Date().toISOString(),context:T||{},error:C?{name:C.name,message:C.message,stack:C.stack}:void 0};F(JSON.stringify(b.format(U)),H[j])}}var I="__jsonlLoggerIntercepted";function J(j){if(globalThis[I])return;globalThis[I]=!0;let b=j?.formatter??R,k=G[j?.level??"debug"],q=j?.filter,D=[["log","info"],["info","info"],["warn","warn"],["error","error"],["debug","debug"]];for(let[z,B]of D)console[z]=Z(B,b,k,q)}
+export{A as b,J as c};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { LogContext, LoggerOptions } from './types';
+export type { Formatter, InterceptOptions, LogContext, LoggerOptions, LogLevel, LogRecord, } from './types';
+export { logLevelValues, stripAnsi } from './types';
+export declare class Logger {
+    private ctx;
+    private min;
+    private json;
+    private fmt;
+    constructor(context?: LogContext, options?: LoggerOptions);
+    child(context: LogContext): Logger;
+    private log;
+    private logPlain;
+    debug(message: string, meta?: LogContext): void;
+    info(message: string, meta?: LogContext): void;
+    warn(message: string, meta?: LogContext): void;
+    error(message: string, meta?: LogContext, error?: Error): void;
+    fatal(message: string, meta?: LogContext, error?: Error): void;
+}
+export declare const logger: Logger;

package/dist/index.js

@@ -0,0 +1 @@
+import{d as n,e as a,f as c}from"./index-abhqk8y0.js";import{g as L}from"./index-rxqh9v58.js";var m=process.env.JSON_LOGS==="true",d=process.env.LOG_LEVEL||(m?"info":"debug"),h={debug:!1,info:!1,warn:!1,error:!0,fatal:!0};class g{ctx;min;json;fmt;constructor(o,t){this.ctx=o||{},this.json=t?.json??m,this.fmt=t?.formatter??L;let e=t?.level??d;this.min=n[e]??n.info}child(o){let t=new g({...this.ctx,...o},{json:this.json,formatter:this.fmt});return t.min=this.min,t}log(o,t,e,r){if(n[o]<this.min)return;let s={level:o,message:this.json?a(t).trim():t,timestamp:new Date().toISOString(),context:e?{...this.ctx,...e}:this.ctx};if(r)s.error={name:r.name,message:r.message,stack:r.stack};if(this.json)c(JSON.stringify(this.fmt.format(s)),h[o]);else this.logPlain(o,s)}logPlain(o,t){let e={debug:"\x1B[36m",info:"\x1B[32m",warn:"\x1B[33m",error:"\x1B[31m",fatal:"\x1B[35m"},r="\x1B[0m",s=e[o],f=new Date(t.timestamp).toLocaleTimeString("en-US",{hour12:!1}),p=o.toUpperCase().padEnd(5),l=t.context,x=Object.keys(l).length>0?` ${JSON.stringify(l)}`:"",v=t.error?` [${t.error.name}: ${t.error.message}]`:"",i=`${s}${f} ${p}\x1B[0m ${t.message}${x}${v}`;switch(o){case"debug":console.debug(i);break;case"warn":console.warn(i);break;case"error":case"fatal":console.error(i);break;default:console.log(i)}}debug(o,t){this.log("debug",o,t)}info(o,t){this.log("info",o,t)}warn(o,t){this.log("warn",o,t)}error(o,t,e){this.log("error",o,t,e)}fatal(o,t,e){this.log("fatal",o,t,e)}}var w=new g;export{a as stripAnsi,w as logger,n as logLevelValues,g as Logger};

package/dist/intercept.d.ts

@@ -0,0 +1,11 @@
+import type { InterceptOptions } from './types';
+type ConsoleMethods = {
+    log: typeof console.log;
+    info: typeof console.info;
+    warn: typeof console.warn;
+    error: typeof console.error;
+    debug: typeof console.debug;
+};
+export declare const originalConsole: ConsoleMethods;
+export declare function intercept(options?: InterceptOptions): void;
+export {};

package/dist/intercept.js

@@ -0,0 +1 @@
+import{b as a,c as b}from"./index-x1ss6ry6.js";import"./index-abhqk8y0.js";import"./index-rxqh9v58.js";export{a as originalConsole,b as intercept};

package/dist/preload.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/preload.js

@@ -0,0 +1 @@
+import{a as r}from"./index-rhgqp0zd.js";import{c as t}from"./index-x1ss6ry6.js";import"./index-abhqk8y0.js";import{g as o}from"./index-rxqh9v58.js";var e={"victoria-logs":o,"google-cloud":r},s=process.env.LOG_FORMAT||"victoria-logs",i=e[s]??o,m=process.env.LOG_LEVEL||"info";t({formatter:i,level:m});

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export type LogContext = Record<string, unknown>;
+export type LogRecord = {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    context: LogContext;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+};
+export type Formatter = {
+    format: (record: LogRecord) => Record<string, unknown>;
+    messageKey: string;
+};
+export type LoggerOptions = {
+    formatter?: Formatter;
+    json?: boolean;
+    level?: LogLevel;
+};
+export type InterceptOptions = {
+    formatter?: Formatter;
+    filter?: (level: LogLevel, message: string) => boolean;
+    level?: LogLevel;
+};
+export declare const logLevelValues: Record<LogLevel, number>;
+export declare function stripAnsi(str: string): string;
+export declare function write(data: string, isError: boolean): void;

package/dist/victoria-logs.d.ts

@@ -0,0 +1,2 @@
+import type { Formatter } from './types';
+export declare const victoriaLogs: Formatter;

package/dist/victoria-logs.js

@@ -0,0 +1 @@
+import{g as a}from"./index-rxqh9v58.js";export{a as victoriaLogs};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "jsonl-logger",
+  "version": "0.1.0",
+  "description": "Lightweight ESM-only JSON Lines logger with pluggable formatters for Google Cloud Logging, VictoriaLogs, and more",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./src/preload.ts",
+    "./dist/preload.js"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./google-cloud": {
+      "bun": "./src/google-cloud.ts",
+      "import": "./dist/google-cloud.js",
+      "types": "./dist/google-cloud.d.ts"
+    },
+    "./victoria-logs": {
+      "bun": "./src/victoria-logs.ts",
+      "import": "./dist/victoria-logs.js",
+      "types": "./dist/victoria-logs.d.ts"
+    },
+    "./intercept": {
+      "bun": "./src/intercept.ts",
+      "import": "./dist/intercept.js",
+      "types": "./dist/intercept.d.ts"
+    },
+    "./preload": {
+      "bun": "./src/preload.ts",
+      "import": "./dist/preload.js",
+      "types": "./dist/preload.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build src/index.ts src/google-cloud.ts src/victoria-logs.ts src/intercept.ts src/preload.ts --outdir dist --target node --format esm --splitting --minify",
+    "build:types": "tsc --emitDeclarationOnly",
+    "lint": "biome check --write .",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.2",
+    "@types/bun": "1.3.9",
+    "typescript": "5.9.3"
+  },
+  "keywords": [
+    "logger",
+    "jsonl",
+    "json-lines",
+    "esm",
+    "structured-logging",
+    "google-cloud-logging",
+    "victoria-logs",
+    "bun",
+    "nextjs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/annexare/jsonl-logger.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/google-cloud.ts

@@ -0,0 +1,27 @@
+import type { Formatter, LogLevel, LogRecord } from './types'
+
+const severityMap: Record<LogLevel, string> = {
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
+  fatal: 'CRITICAL',
+}
+
+export const googleCloud: Formatter = {
+  messageKey: 'message',
+  format(record: LogRecord): Record<string, unknown> {
+    const entry: Record<string, unknown> = {
+      message: record.message,
+      timestamp: record.timestamp,
+      severity: severityMap[record.level],
+      ...record.context,
+    }
+    if (record.error) {
+      entry['error.name'] = record.error.name
+      entry['error.message'] = record.error.message
+      if (record.error.stack) entry['error.stack'] = record.error.stack
+    }
+    return entry
+  },
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+import type {
+  Formatter,
+  LogContext,
+  LoggerOptions,
+  LogLevel,
+  LogRecord,
+} from './types'
+import { logLevelValues, stripAnsi, write } from './types'
+import { victoriaLogs } from './victoria-logs'
+
+export type {
+  Formatter,
+  InterceptOptions,
+  LogContext,
+  LoggerOptions,
+  LogLevel,
+  LogRecord,
+} from './types'
+export { logLevelValues, stripAnsi } from './types'
+
+const defaultJson = process.env.JSON_LOGS === 'true'
+const defaultLevel: LogLevel =
+  (process.env.LOG_LEVEL as LogLevel | undefined) ||
+  (defaultJson ? 'info' : 'debug')
+
+const isErrorLevel: Record<LogLevel, boolean> = {
+  debug: false,
+  info: false,
+  warn: false,
+  error: true,
+  fatal: true,
+}
+
+export class Logger {
+  private ctx: LogContext
+  private min: number
+  private json: boolean
+  private fmt: Formatter
+
+  constructor(context?: LogContext, options?: LoggerOptions) {
+    this.ctx = context || {}
+    this.json = options?.json ?? defaultJson
+    this.fmt = options?.formatter ?? victoriaLogs
+    const level: LogLevel = options?.level ?? defaultLevel
+    this.min = logLevelValues[level] ?? logLevelValues.info
+  }
+
+  child(context: LogContext): Logger {
+    const child = new Logger(
+      { ...this.ctx, ...context },
+      {
+        json: this.json,
+        formatter: this.fmt,
+      },
+    )
+    child.min = this.min
+    return child
+  }
+
+  private log(
+    level: LogLevel,
+    message: string,
+    meta?: LogContext,
+    err?: Error,
+  ): void {
+    if (logLevelValues[level] < this.min) return
+
+    const record: LogRecord = {
+      level,
+      message: this.json ? stripAnsi(message).trim() : message,
+      timestamp: new Date().toISOString(),
+      context: meta ? { ...this.ctx, ...meta } : this.ctx,
+    }
+
+    if (err) {
+      record.error = { name: err.name, message: err.message, stack: err.stack }
+    }
+
+    if (this.json) {
+      write(JSON.stringify(this.fmt.format(record)), isErrorLevel[level])
+    } else {
+      this.logPlain(level, record)
+    }
+  }
+
+  private logPlain(level: LogLevel, record: LogRecord): void {
+    const colors: Record<LogLevel, string> = {
+      debug: '\x1b[36m',
+      info: '\x1b[32m',
+      warn: '\x1b[33m',
+      error: '\x1b[31m',
+      fatal: '\x1b[35m',
+    }
+    const reset = '\x1b[0m'
+    const color = colors[level]
+
+    const time = new Date(record.timestamp).toLocaleTimeString('en-US', {
+      hour12: false,
+    })
+    const levelStr = level.toUpperCase().padEnd(5)
+
+    const ctx = record.context
+    const metaStr = Object.keys(ctx).length > 0 ? ` ${JSON.stringify(ctx)}` : ''
+
+    const errStr = record.error
+      ? ` [${record.error.name}: ${record.error.message}]`
+      : ''
+
+    const output = `${color}${time} ${levelStr}${reset} ${record.message}${metaStr}${errStr}`
+
+    switch (level) {
+      case 'debug':
+        console.debug(output)
+        break
+      case 'warn':
+        console.warn(output)
+        break
+      case 'error':
+      case 'fatal':
+        console.error(output)
+        break
+      default:
+        console.log(output)
+    }
+  }
+
+  debug(message: string, meta?: LogContext): void {
+    this.log('debug', message, meta)
+  }
+
+  info(message: string, meta?: LogContext): void {
+    this.log('info', message, meta)
+  }
+
+  warn(message: string, meta?: LogContext): void {
+    this.log('warn', message, meta)
+  }
+
+  error(message: string, meta?: LogContext, error?: Error): void {
+    this.log('error', message, meta, error)
+  }
+
+  fatal(message: string, meta?: LogContext, error?: Error): void {
+    this.log('fatal', message, meta, error)
+  }
+}
+
+export const logger = new Logger()

package/src/intercept.ts

@@ -0,0 +1,136 @@
+import type { Formatter, InterceptOptions, LogLevel } from './types'
+import { logLevelValues, stripAnsi, write } from './types'
+import { victoriaLogs } from './victoria-logs'
+
+type ConsoleMethods = {
+  log: typeof console.log
+  info: typeof console.info
+  warn: typeof console.warn
+  error: typeof console.error
+  debug: typeof console.debug
+}
+
+// Capture original methods once, before anything else runs
+export const originalConsole: ConsoleMethods = {
+  log: console.log.bind(console),
+  info: console.info.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+}
+
+function formatMessage(...args: unknown[]): string {
+  let result = ''
+  for (let i = 0; i < args.length; i++) {
+    if (i > 0) result += ' '
+    const arg = args[i]
+    if (typeof arg === 'string') {
+      result += stripAnsi(arg)
+    } else if (arg instanceof Error) {
+      result += arg.message
+    } else {
+      try {
+        result += JSON.stringify(arg)
+      } catch {
+        result += String(arg)
+      }
+    }
+  }
+  return result.trim()
+}
+
+function extractMeta(...args: unknown[]): Record<string, unknown> | undefined {
+  let merged: Record<string, unknown> | undefined
+  for (const arg of args) {
+    if (
+      typeof arg === 'object' &&
+      arg !== null &&
+      !(arg instanceof Error) &&
+      !Array.isArray(arg)
+    ) {
+      if (!merged) merged = {}
+      Object.assign(merged, arg)
+    }
+  }
+  return merged
+}
+
+function extractError(...args: unknown[]): Error | undefined {
+  for (const arg of args) {
+    if (arg instanceof Error) return arg
+  }
+}
+
+const isErrorLevel = {
+  debug: false,
+  info: false,
+  warn: false,
+  error: true,
+  fatal: true,
+}
+
+function createOverride(
+  level: LogLevel,
+  formatter: Formatter,
+  minLevel: number,
+  filter?: (level: LogLevel, message: string) => boolean,
+): (...args: unknown[]) => void {
+  const msgKey = `"${formatter.messageKey}"`
+
+  return (...args: unknown[]) => {
+    // Passthrough: already-formatted JSON from our Logger
+    if (
+      args.length === 1 &&
+      typeof args[0] === 'string' &&
+      args[0].charCodeAt(0) === 123 && // starts with '{'
+      args[0].includes(msgKey)
+    ) {
+      write(args[0], isErrorLevel[level])
+      return
+    }
+
+    if (logLevelValues[level] < minLevel) return
+
+    const message = formatMessage(...args)
+
+    if (filter && !filter(level, message)) return
+
+    const meta = extractMeta(...args)
+    const error = extractError(...args)
+
+    const record = {
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      context: meta || {},
+      error: error
+        ? { name: error.name, message: error.message, stack: error.stack }
+        : undefined,
+    }
+
+    write(JSON.stringify(formatter.format(record)), isErrorLevel[level])
+  }
+}
+
+const guardKey = '__jsonlLoggerIntercepted'
+
+export function intercept(options?: InterceptOptions): void {
+  if ((globalThis as Record<string, unknown>)[guardKey]) return
+  ;(globalThis as Record<string, unknown>)[guardKey] = true
+
+  const formatter = options?.formatter ?? victoriaLogs
+  const minLevel = logLevelValues[options?.level ?? 'debug']
+  const filter = options?.filter
+
+  const methodMap: [keyof ConsoleMethods, LogLevel][] = [
+    ['log', 'info'],
+    ['info', 'info'],
+    ['warn', 'warn'],
+    ['error', 'error'],
+    ['debug', 'debug'],
+  ]
+
+  for (const [method, level] of methodMap) {
+    console[method] = createOverride(level, formatter, minLevel, filter)
+  }
+}

package/src/preload.ts

@@ -0,0 +1,17 @@
+import { googleCloud } from './google-cloud'
+import { intercept } from './intercept'
+import type { Formatter } from './types'
+import { victoriaLogs } from './victoria-logs'
+
+const formatters: Record<string, Formatter> = {
+  'victoria-logs': victoriaLogs,
+  'google-cloud': googleCloud,
+}
+
+const format = process.env.LOG_FORMAT || 'victoria-logs'
+const formatter = formatters[format] ?? victoriaLogs
+const level =
+  (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error' | 'fatal') ||
+  'info'
+
+intercept({ formatter, level })

package/src/types.ts

@@ -0,0 +1,75 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+
+export type LogContext = Record<string, unknown>
+
+export type LogRecord = {
+  level: LogLevel
+  message: string
+  timestamp: string
+  context: LogContext
+  error?: { name: string; message: string; stack?: string }
+}
+
+export type Formatter = {
+  format: (record: LogRecord) => Record<string, unknown>
+  messageKey: string
+}
+
+export type LoggerOptions = {
+  formatter?: Formatter
+  json?: boolean
+  level?: LogLevel
+}
+
+export type InterceptOptions = {
+  formatter?: Formatter
+  filter?: (level: LogLevel, message: string) => boolean
+  level?: LogLevel
+}
+
+export const logLevelValues: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  fatal: 4,
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: needed to strip ANSI color codes
+const ansiPattern = /\x1b\[[0-9;]*m/g
+
+export function stripAnsi(str: string): string {
+  return str.replace(ansiPattern, '')
+}
+
+/**
+ * Detect runtime once, resolve streams at call time.
+ * Stream lookup is deferred so tests/runtime can replace process.stdout.
+ */
+const runtime: 'node' | 'deno' | 'browser' =
+  typeof process !== 'undefined' &&
+  process.stdout &&
+  typeof process.stdout.write === 'function'
+    ? 'node'
+    : // @ts-expect-error Deno global
+      typeof Deno !== 'undefined' && Deno.stdout
+      ? 'deno'
+      : 'browser'
+
+const denoEncoder = runtime === 'deno' ? new TextEncoder() : null
+
+export function write(data: string, isError: boolean): void {
+  if (runtime === 'node') {
+    const stream = isError ? (process.stderr ?? process.stdout) : process.stdout
+    stream.write(`${data}\n`)
+  } else if (runtime === 'deno' && denoEncoder) {
+    const bytes = denoEncoder.encode(`${data}\n`)
+    // @ts-expect-error Deno global
+    if (isError) Deno.stderr.writeSync(bytes)
+    // @ts-expect-error Deno global
+    else Deno.stdout.writeSync(bytes)
+  } else {
+    if (isError) console.error(data)
+    else console.log(data)
+  }
+}

package/src/victoria-logs.ts

@@ -0,0 +1,19 @@
+import type { Formatter, LogRecord } from './types'
+
+export const victoriaLogs: Formatter = {
+  messageKey: '_msg',
+  format(record: LogRecord): Record<string, unknown> {
+    const entry: Record<string, unknown> = {
+      _msg: record.message,
+      _time: record.timestamp,
+      level: record.level,
+      ...record.context,
+    }
+    if (record.error) {
+      entry['error.name'] = record.error.name
+      entry['error.message'] = record.error.message
+      if (record.error.stack) entry['error.stack'] = record.error.stack
+    }
+    return entry
+  },
+}