@joinremba/catalog 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joinremba/catalog",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Production-ready logging and error event layer for TypeScript backends, built on Pino.",
   "type": "module",
   "main": "./src/index.ts",
@@ -25,6 +25,31 @@
       "types": "./src/adapters/hono.ts",
       "import": "./src/adapters/hono.ts",
       "default": "./src/adapters/hono.ts"
+    },
+    "./adapters/express": {
+      "types": "./src/adapters/express.ts",
+      "import": "./src/adapters/express.ts",
+      "default": "./src/adapters/express.ts"
+    },
+    "./adapters/fastify": {
+      "types": "./src/adapters/fastify.ts",
+      "import": "./src/adapters/fastify.ts",
+      "default": "./src/adapters/fastify.ts"
+    },
+    "./webhook": {
+      "types": "./src/webhook.ts",
+      "import": "./src/webhook.ts",
+      "default": "./src/webhook.ts"
+    },
+    "./otel": {
+      "types": "./src/otel.ts",
+      "import": "./src/otel.ts",
+      "default": "./src/otel.ts"
+    },
+    "./sampling": {
+      "types": "./src/sampling.ts",
+      "import": "./src/sampling.ts",
+      "default": "./src/sampling.ts"
     }
   },
   "files": [

package/src/adapters/express.test.ts

@@ -0,0 +1,67 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "../index";
+import { requestIdMiddleware, httpLoggerMiddleware } from "./express";
+
+function mockReq() {
+  const headers: Record<string, string | undefined> = {};
+  return {
+    method: "GET",
+    path: "/api/users",
+    ip: "127.0.0.1",
+    headers,
+    query: { page: "1" },
+    get(name: string) {
+      return headers[name.toLowerCase()];
+    },
+  };
+}
+
+function mockRes() {
+  const listeners: Record<string, Array<(...args: unknown[]) => void>> = {};
+  return {
+    statusCode: 200,
+    status(code: number) {
+      this.statusCode = code;
+      return this;
+    },
+    on(event: string, fn: (...args: unknown[]) => void) {
+      (listeners[event] ??= []).push(fn);
+      return this;
+    },
+    emit(event: string, ...args: unknown[]) {
+      for (const fn of listeners[event] ?? []) fn(...args);
+    },
+  };
+}
+
+test("requestIdMiddleware sets requestId", () => {
+  const catalog = createCatalog({ service: "test" });
+  const req = mockReq();
+  const res = mockRes();
+  requestIdMiddleware(catalog)(req as any, res as any, () => {});
+  expect((req as any).requestId).toBeDefined();
+});
+
+test("httpLoggerMiddleware skips excluded paths", () => {
+  const catalog = createCatalog({ service: "test" });
+  const req = mockReq();
+  req.path = "/health";
+  const res = mockRes();
+  let called = false;
+  httpLoggerMiddleware(catalog)(req as any, res as any, () => {
+    called = true;
+  });
+  expect(called).toBe(true);
+});
+
+test("httpLoggerMiddleware logs on finish", () => {
+  const catalog = createCatalog({ service: "test" });
+  const req = mockReq();
+  const res = mockRes();
+  let called = false;
+  httpLoggerMiddleware(catalog)(req as any, res as any, () => {
+    called = true;
+  });
+  expect(called).toBe(true);
+  expect(() => res.emit("finish")).not.toThrow();
+});

package/src/adapters/express.ts

@@ -0,0 +1,79 @@
+import type { Catalog } from "../index";
+
+interface ExpressRequest {
+  method: string;
+  path: string;
+  ip?: string;
+  headers: Record<string, string | string[] | undefined>;
+  query: Record<string, string | undefined>;
+  get(name: string): string | undefined;
+}
+
+interface ExpressResponse {
+  statusCode: number;
+  status(code: number): ExpressResponse;
+  on(event: string, listener: (...args: unknown[]) => void): ExpressResponse;
+}
+
+type ExpressNext = (err?: unknown) => void;
+
+export interface ExpressRequestIdOptions {
+  header?: string;
+  generate?: () => string;
+}
+
+export function requestIdMiddleware(_catalog: Catalog, options?: ExpressRequestIdOptions) {
+  const headerName = options?.header?.toLowerCase() ?? "x-request-id";
+  const generate = options?.generate ?? (() => crypto.randomUUID());
+
+  return (req: ExpressRequest, _res: ExpressResponse, next: ExpressNext) => {
+    const existing = req.get(headerName) ?? req.get("x-request-id");
+    (req as unknown as Record<string, unknown>).requestId = existing ?? generate();
+    next();
+  };
+}
+
+export interface HttpLogOptions {
+  excludePaths?: string[];
+}
+
+export function httpLoggerMiddleware(catalog: Catalog, options?: HttpLogOptions) {
+  const exclude = new Set(options?.excludePaths ?? ["/health", "/favicon.ico"]);
+
+  return (req: ExpressRequest, res: ExpressResponse, next: ExpressNext) => {
+    if (exclude.has(req.path)) return next();
+
+    const requestId = (req as unknown as Record<string, unknown>).requestId as string | undefined;
+    const log = requestId ? catalog.child({ requestId }) : catalog;
+    const start = performance.now();
+    const method = req.method;
+    const path = req.path;
+
+    log.info({
+      message: `--> ${method} ${path}`,
+      method,
+      path,
+      query: req.query,
+      userAgent: req.get("user-agent"),
+      ip: req.ip,
+    });
+
+    res.on("finish", () => {
+      const duration = ((performance.now() - start) * 1000).toFixed(2);
+      const status = res.statusCode;
+      const level = status >= 500 ? "error" : status >= 400 ? "warn" : "info";
+
+      const logData = {
+        message: `<-- ${method} ${path} ${status} ${duration}ms`,
+        status,
+        durationMs: duration,
+      };
+
+      if (level === "info") log.info(logData);
+      else if (level === "warn") log.warn(logData);
+      else log.error(logData);
+    });
+
+    next();
+  };
+}

package/src/adapters/fastify.test.ts

@@ -0,0 +1,37 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "../index";
+import { requestIdHook, httpLoggerHook } from "./fastify";
+
+function mockRequest() {
+  return {
+    method: "GET",
+    url: "/api/users",
+    ip: "127.0.0.1",
+    headers: { "user-agent": "test-agent" },
+    query: { page: "1" },
+  };
+}
+
+function mockReply(statusCode = 200) {
+  return { statusCode };
+}
+
+test("requestIdHook sets requestId", () => {
+  const catalog = createCatalog({ service: "test" });
+  const req = mockRequest();
+  const reply = mockReply();
+  requestIdHook(catalog)(req as any, reply as any, () => {});
+  expect((req as any).requestId).toBeDefined();
+});
+
+test("httpLoggerHook skips excluded paths", () => {
+  const catalog = createCatalog({ service: "test" });
+  const req = mockRequest();
+  req.url = "/health";
+  const reply = mockReply();
+  let called = false;
+  httpLoggerHook(catalog)(req as any, reply as any, () => {
+    called = true;
+  });
+  expect(called).toBe(true);
+});

package/src/adapters/fastify.ts

@@ -0,0 +1,77 @@
+import type { Catalog } from "../index";
+
+interface FastifyRequest {
+  method: string;
+  url: string;
+  ip: string;
+  headers: Record<string, string | string[] | undefined>;
+  query: Record<string, string | undefined>;
+}
+
+interface FastifyReply {
+  statusCode: number;
+}
+
+export interface FastifyRequestIdOptions {
+  header?: string;
+  generate?: () => string;
+}
+
+export function requestIdHook(catalog: Catalog, options?: FastifyRequestIdOptions) {
+  const headerName = options?.header?.toLowerCase() ?? "x-request-id";
+  const generate = options?.generate ?? (() => crypto.randomUUID());
+
+  return (request: FastifyRequest, _reply: FastifyReply, done: () => void) => {
+    const existing = request.headers[headerName] ?? request.headers["x-request-id"];
+    (request as unknown as Record<string, unknown>).requestId = existing ?? generate();
+    done();
+  };
+}
+
+export interface HttpLogOptions {
+  excludePaths?: string[];
+}
+
+export function httpLoggerHook(catalog: Catalog, options?: HttpLogOptions) {
+  const exclude = new Set(options?.excludePaths ?? ["/health", "/favicon.ico"]);
+
+  return (request: FastifyRequest, reply: FastifyReply, done: () => void) => {
+    if (exclude.has(request.url)) return done();
+
+    const requestId = (request as unknown as Record<string, unknown>).requestId as
+      | string
+      | undefined;
+    const log = requestId ? catalog.child({ requestId }) : catalog;
+    const start = performance.now();
+    const method = request.method;
+    const url = request.url;
+
+    log.info({
+      message: `--> ${method} ${url}`,
+      method,
+      url,
+      query: request.query,
+      userAgent: request.headers["user-agent"],
+      ip: request.ip,
+    });
+
+    done();
+
+    // Capture duration when reply is sent (Fastify calls onResponse after send)
+    queueMicrotask(() => {
+      const duration = ((performance.now() - start) * 1000).toFixed(2);
+      const status = reply.statusCode;
+      const level = status >= 500 ? "error" : status >= 400 ? "warn" : "info";
+
+      const logData = {
+        message: `<-- ${method} ${url} ${status} ${duration}ms`,
+        status,
+        durationMs: duration,
+      };
+
+      if (level === "info") log.info(logData);
+      else if (level === "warn") log.warn(logData);
+      else log.error(logData);
+    });
+  };
+}

package/src/otel.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "./index";
+import { otelBridge } from "./otel";
+import type { OtelApi } from "./otel";
+
+function mockOtelApi(): OtelApi {
+  return {
+    trace: {
+      getActiveSpan() {
+        return {
+          spanContext() {
+            return { traceId: "abc123", spanId: "def456", traceFlags: 1 };
+          },
+          addEvent(_name: string, _attrs?: Record<string, unknown>) {},
+          setAttribute(_key: string, _value: unknown) {},
+        };
+      },
+    },
+    SpanStatusCode: { OK: 0, ERROR: 1, UNSET: 2 },
+  };
+}
+
+test("otelBridge injects trace context", () => {
+  const catalog = createCatalog({ service: "test" });
+  const otel = mockOtelApi();
+  const bridged = otelBridge(catalog, { api: otel });
+
+  expect(() => {
+    bridged.info("app.started", { version: "1.0.0" });
+  }).not.toThrow();
+});
+
+test("otelBridge child preserves bridging", () => {
+  const catalog = createCatalog({ service: "test" });
+  const otel = mockOtelApi();
+  const bridged = otelBridge(catalog, { api: otel });
+  const child = bridged.child({ requestId: "req-1" });
+
+  expect(() => {
+    child.info("child.event");
+  }).not.toThrow();
+});

package/src/otel.ts

@@ -0,0 +1,77 @@
+import type { Catalog, LogLevel } from "./index";
+
+export interface OtelSpanContext {
+  traceId: string;
+  spanId: string;
+  traceFlags?: number;
+}
+
+export interface OtelSpan {
+  spanContext(): OtelSpanContext;
+  addEvent(name: string, attributes?: Record<string, unknown>): void;
+  setAttribute(key: string, value: unknown): void;
+}
+
+export interface OtelApi {
+  trace: {
+    getActiveSpan(): OtelSpan | undefined;
+  };
+  SpanStatusCode: { OK: number; ERROR: number; UNSET: number };
+}
+
+export interface OtelBridgeOptions {
+  api: OtelApi;
+  captureSpanEvents?: boolean;
+  spanAttributePrefix?: string;
+}
+
+export function otelBridge(catalog: Catalog, options: OtelBridgeOptions) {
+  const { api, captureSpanEvents = false, spanAttributePrefix = "log" } = options;
+
+  function withTraceContext(
+    first: string | Record<string, unknown>,
+    data?: Record<string, unknown>
+  ) {
+    const span = api.trace.getActiveSpan();
+    if (!span) return { first, data };
+
+    const ctx = span.spanContext();
+    const traceData: Record<string, unknown> = {
+      trace_id: ctx.traceId,
+      span_id: ctx.spanId,
+      ...(data as Record<string, unknown>),
+    };
+
+    if (captureSpanEvents) {
+      const msg = typeof first === "string" ? first : "";
+      span.addEvent(msg, traceData);
+    }
+
+    span.setAttribute(`${spanAttributePrefix}.trace_id`, ctx.traceId);
+
+    return { first, data: traceData };
+  }
+
+  function adapt(method: LogLevel) {
+    return (first: string | Record<string, unknown>, second?: Record<string, unknown>) => {
+      const { first: f, data: d } = withTraceContext(first, second);
+      const logFn = (catalog as unknown as Record<string, (...args: unknown[]) => void>)[method]!;
+      logFn(f, d);
+    };
+  }
+
+  return {
+    trace: adapt("trace"),
+    debug: adapt("debug"),
+    info: adapt("info"),
+    warn: adapt("warn"),
+    error: adapt("error"),
+    fatal: adapt("fatal"),
+    child(bindings: Record<string, unknown>) {
+      return otelBridge(catalog.child(bindings), options);
+    },
+    get level(): LogLevel {
+      return catalog.level;
+    },
+  };
+}

package/src/sampling.test.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "./index";
+import { samplingCatalog } from "./sampling";
+
+test("samplingCatalog at rate 1.0 passes all events", () => {
+  const catalog = createCatalog({ service: "test" });
+  let called = false;
+
+  const spy = new Proxy(catalog, {
+    get(target, prop) {
+      if (prop === "info")
+        return () => {
+          called = true;
+        };
+      if (typeof prop === "string") {
+        return (target as unknown as Record<string, unknown>)[prop];
+      }
+      return undefined;
+    },
+  });
+
+  const s2 = samplingCatalog(spy, { rate: 1.0 });
+  s2.info("test.event");
+  expect(called).toBe(true);
+});
+
+test("samplingCatalog at rate 0.0 drops all events", () => {
+  const catalog = createCatalog({ service: "test" });
+  const sampled = samplingCatalog(catalog, { rate: 0.0 });
+  expect(() => sampled.info("dropped.event")).not.toThrow();
+});
+
+test("samplingCatalog filters by level", () => {
+  const catalog = createCatalog({ service: "test" });
+  const sampled = samplingCatalog(catalog, { rate: 1.0, level: "warn" });
+  expect(() => {
+    sampled.info("info.event");
+    sampled.warn("warn.event");
+    sampled.error("error.event");
+  }).not.toThrow();
+});

package/src/sampling.ts

@@ -0,0 +1,75 @@
+import type { Catalog, LogLevel } from "./index";
+
+type SamplerFn = (level: LogLevel, message: string, data?: Record<string, unknown>) => boolean;
+
+export interface SamplingOptions {
+  rate: number;
+  level?: LogLevel;
+  sampler?: SamplerFn;
+  keyFn?: (level: LogLevel, message: string, data?: Record<string, unknown>) => string;
+}
+
+function defaultKeyFn(_level: LogLevel, message: string, _data?: Record<string, unknown>): string {
+  return message;
+}
+
+function deterministicSampler(
+  rate: number,
+  keyFn: (level: LogLevel, message: string, data?: Record<string, unknown>) => string
+): SamplerFn {
+  return (level, message, data) => {
+    const key = keyFn(level, message, data);
+    let hash = 0;
+    for (let i = 0; i < key.length; i++) {
+      const char = key.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    const normalized = Math.abs(hash) / 0x7fffffff;
+    return normalized < rate;
+  };
+}
+
+export function samplingCatalog(catalog: Catalog, options: SamplingOptions) {
+  const { rate, level: levelFilter, sampler, keyFn } = options;
+  const levels: LogLevel[] = ["trace", "debug", "info", "warn", "error", "fatal"];
+  const minLevelIdx = levelFilter ? levels.indexOf(levelFilter) : 0;
+
+  const shouldSample: SamplerFn =
+    sampler ??
+    (keyFn ? deterministicSampler(rate, keyFn) : deterministicSampler(rate, defaultKeyFn));
+
+  function adapt(method: LogLevel) {
+    return (first: string | Record<string, unknown>, second?: Record<string, unknown>) => {
+      const levelIdx = levels.indexOf(method);
+      if (levelIdx < minLevelIdx) return;
+
+      const message = typeof first === "string" ? first : "";
+      const data = typeof first === "object" ? (first as Record<string, unknown>) : second;
+
+      if (!shouldSample(method, message, data)) return;
+
+      const logFn = (catalog as unknown as Record<string, (...args: unknown[]) => void>)[method]!;
+      if (typeof first === "string") {
+        logFn(first, second);
+      } else {
+        logFn(first);
+      }
+    };
+  }
+
+  return {
+    trace: adapt("trace"),
+    debug: adapt("debug"),
+    info: adapt("info"),
+    warn: adapt("warn"),
+    error: adapt("error"),
+    fatal: adapt("fatal"),
+    child(bindings: Record<string, unknown>) {
+      return samplingCatalog(catalog.child(bindings), options);
+    },
+    get level(): LogLevel {
+      return catalog.level;
+    },
+  };
+}

package/src/webhook.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import { createCatalog } from "./index";
+import { webhookLogger } from "./webhook";
+
+test("webhookLogger enqueues events without throwing", () => {
+  const catalog = createCatalog({ service: "test" });
+  const wh = webhookLogger(catalog, {
+    targets: [{ url: "https://hooks.example.com/logs" }],
+  });
+
+  expect(() => {
+    wh.info("app.started", { version: "1.0.0" });
+    wh.error("db.connection_failed", { database: "prod" });
+  }).not.toThrow();
+
+  wh.stop();
+});
+
+test("webhookLogger filters by target level", () => {
+  const catalog = createCatalog({ service: "test" });
+  const wh = webhookLogger(catalog, {
+    targets: [{ url: "https://hooks.example.com/errors", level: "error" }],
+  });
+
+  expect(() => {
+    wh.info("app.started");
+    wh.error("critical.failure");
+  }).not.toThrow();
+
+  wh.stop();
+});

package/src/webhook.ts

@@ -0,0 +1,135 @@
+import type { Catalog, LogLevel } from "./index";
+
+export interface WebhookTarget {
+  url: string;
+  level?: LogLevel;
+  headers?: Record<string, string>;
+  secret?: string;
+}
+
+export interface WebhookOptions {
+  targets: WebhookTarget[];
+  batchIntervalMs?: number;
+  maxBatchSize?: number;
+  retryCount?: number;
+}
+
+interface QueuedEvent {
+  level: LogLevel;
+  message: string;
+  data?: Record<string, unknown>;
+  timestamp: number;
+}
+
+async function signPayload(payload: string, secret: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return Array.from(new Uint8Array(sig))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export function webhookLogger(catalog: Catalog, options: WebhookOptions) {
+  const { targets, batchIntervalMs = 5000, maxBatchSize = 50, retryCount = 2 } = options;
+  const queues: Map<string, QueuedEvent[]> = new Map();
+  const timers: Map<string, ReturnType<typeof setInterval>> = new Map();
+
+  for (const target of targets) {
+    queues.set(target.url, []);
+    const timer = setInterval(() => flush(target), batchIntervalMs);
+    timers.set(target.url, timer);
+  }
+
+  async function flush(target: WebhookTarget) {
+    const queue = queues.get(target.url);
+    if (!queue || queue.length === 0) return;
+
+    const batch = queue.splice(0, maxBatchSize);
+    const body = JSON.stringify({ events: batch });
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...target.headers,
+    };
+
+    if (target.secret) {
+      headers["X-Signature-256"] = await signPayload(body, target.secret);
+    }
+
+    for (let attempt = 0; attempt <= retryCount; attempt++) {
+      try {
+        const res = await fetch(target.url, { method: "POST", headers, body });
+        if (res.ok) break;
+        if (attempt < retryCount) await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+      } catch {
+        if (attempt < retryCount) await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+      }
+    }
+  }
+
+  function shouldLog(level: LogLevel, targetLevel?: LogLevel): boolean {
+    const levels: LogLevel[] = ["trace", "debug", "info", "warn", "error", "fatal"];
+    const targetIdx = targetLevel ? levels.indexOf(targetLevel) : 0;
+    const eventIdx = levels.indexOf(level);
+    return eventIdx >= targetIdx;
+  }
+
+  function enqueue(
+    level: LogLevel,
+    first: string | Record<string, unknown>,
+    second?: Record<string, unknown>
+  ) {
+    const message = typeof first === "string" ? first : "";
+    const data = typeof first === "object" ? first : second;
+
+    for (const target of targets) {
+      if (!shouldLog(level, target.level)) continue;
+      const queue = queues.get(target.url);
+      if (queue) {
+        queue.push({ level, message, data, timestamp: Date.now() });
+      }
+    }
+  }
+
+  function stop() {
+    for (const [url, timer] of timers) {
+      clearInterval(timer);
+      const target = targets.find((t) => t.url === url);
+      if (target) {
+        clearInterval(timer);
+        flush(target);
+      }
+    }
+    timers.clear();
+    queues.clear();
+  }
+
+  return {
+    trace(first: string | Record<string, unknown>, second?: Record<string, unknown>) {
+      enqueue("trace", first, second);
+    },
+    debug(first: string | Record<string, unknown>, second?: Record<string, unknown>) {
+      enqueue("debug", first, second);
+    },
+    info(first: string | Record<string, unknown>, second?: Record<string, unknown>) {
+      enqueue("info", first, second);
+    },
+    warn(first: string | Record<string, unknown>, second?: Record<string, unknown>) {
+      enqueue("warn", first, second);
+    },
+    error(first: string | Record<string, unknown>, second?: Record<string, unknown>) {
+      enqueue("error", first, second);
+    },
+    fatal(first: string | Record<string, unknown>, second?: Record<string, unknown>) {
+      enqueue("fatal", first, second);
+    },
+    stop,
+    flush: () => Promise.all(targets.map(flush)),
+  };
+}