@bjro/slog 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjro/slog",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A dead-simple structured logger for ECMAScript runtimes",
   "type": "module",
   "exports": {

package/src/hono.ts

@@ -1,3 +1,4 @@
+/** @module slog/hono — Hono middleware for per-request structured logging. */
 import { createMiddleware } from 'hono/factory';
 import { getRuntimeKey } from 'hono/adapter';
 import type { MiddlewareHandler } from 'hono';
@@ -5,6 +6,16 @@ import type { Logger } from './types.ts';
 
 export type { Logger } from './types.ts';
 
+/**
+ * Creates Hono middleware that attaches a per-request logger to the context and logs request completion.
+ *
+ * The middleware enriches a child logger with request metadata (request ID, method, path, user-agent),
+ * stores it at `c.get('logger')`, and emits an `info` entry on every response. If the handler throws,
+ * an `error` entry is also emitted. On Cloudflare Workers the flush is handed to `waitUntil`.
+ *
+ * @param logger - A preconfigured Logger instance to derive per-request child loggers from.
+ * @returns A Hono MiddlewareHandler.
+ */
 export function slogMiddleware(logger: Logger): MiddlewareHandler {
   return createMiddleware<{ Variables: { logger: Logger } }>(async (c, next) => {
     const requestLogger = logger.withContext({

package/src/index.ts

@@ -1,3 +1,4 @@
+/** @module slog — Structured logging for every JavaScript runtime. */
 export type { LogLevel, LogEntry, Plugin, Transport, Logger, LoggerOptions } from './types.ts';
 export { LOG_LEVELS } from './levels.ts';
 export { createLogger } from './logger.ts';

package/src/levels.ts

@@ -1,5 +1,6 @@
 import type { LogLevel } from './types.ts';
 
+/** Numeric severity values for each log level, used for level comparisons. */
 export const LOG_LEVELS: Record<LogLevel, number> = {
   trace: 0,
   debug: 1,

package/src/logger.ts

@@ -90,6 +90,11 @@ class LoggerImpl implements Logger {
   }
 }
 
+/**
+ * Creates a new structured logger instance.
+ * @param options - Logger configuration (level, plugins, transports, context).
+ * @returns A Logger instance.
+ */
 export function createLogger(options?: LoggerOptions): Logger {
   return new LoggerImpl(options);
 }

package/src/plugins/errorSerializer.ts

@@ -10,6 +10,7 @@ function serializeError(val: unknown): { name: string; message: string; stack?:
   return { name: 'Error', message: String(val) };
 }
 
+/** Plugin that serializes Error instances in the `error` and `err` data fields into plain objects with name, message, and stack properties. */
 export const errorSerializer: Plugin = {
   name: 'errorSerializer',
   transform(entry: LogEntry): LogEntry {

package/src/plugins/fieldEnrich.ts

@@ -1,5 +1,10 @@
 import type { LogEntry, Plugin } from '../types.ts';
 
+/**
+ * Creates a plugin that merges static fields into every log entry's data.
+ * @param fields - Key-value pairs to add to each entry. Snapshot is taken at creation time.
+ * @returns A Plugin that enriches entries with the provided fields.
+ */
 export function createFieldEnrichPlugin(fields: Record<string, unknown>): Plugin {
   const frozenFields = Object.freeze({ ...fields });
   return {

package/src/plugins/levelFilter.ts

@@ -2,6 +2,11 @@ import type { LogEntry, Plugin } from '../types.ts';
 import type { LogLevel } from '../types.ts';
 import { LOG_LEVELS } from '../levels.ts';
 
+/**
+ * Creates a plugin that drops log entries below the specified minimum severity level.
+ * @param minLevel - Minimum log level to allow through.
+ * @returns A Plugin that filters entries below minLevel.
+ */
 export function createLevelFilterPlugin(minLevel: LogLevel): Plugin {
   const threshold = LOG_LEVELS[minLevel];
   return {

package/src/plugins/redact.ts

@@ -1,5 +1,10 @@
 import type { LogEntry, Plugin } from '../types.ts';
 
+/**
+ * Creates a plugin that replaces values of matching data keys with `[REDACTED]`.
+ * @param patterns - Array of exact key strings or RegExp patterns to match against data field keys.
+ * @returns A Plugin that redacts matched fields.
+ */
 export function createRedactPlugin(patterns: Array<string | RegExp>): Plugin {
   return {
     name: 'redact',

package/src/transports/console.ts

@@ -9,6 +9,10 @@ const CONSOLE_METHOD: Record<LogLevel, 'log' | 'info' | 'warn' | 'error'> = {
   fatal: 'error',
 };
 
+/**
+ * Creates a transport that writes JSON-serialized log entries to the console using level-appropriate methods.
+ * @returns A Transport that writes NDJSON to console.
+ */
 export function createConsoleTransport(): Transport {
   return {
     write(entry: LogEntry): void {

package/src/transports/http.ts

@@ -1,8 +1,12 @@
 import type { LogEntry, Transport } from '../types.ts';
 
+/** Configuration for the HTTP batch transport. */
 export interface HttpBatchTransportConfig {
+  /** The URL to POST NDJSON batches to. */
   url: string;
+  /** Optional HTTP headers to include in every POST request. */
   headers?: Record<string, string>;
+  /** Interval in milliseconds between automatic flushes. When omitted, the transport only flushes on explicit flush() calls. */
   flushInterval?: number; // ms, optional auto-flush timer
 }
 
@@ -24,6 +28,11 @@ async function postWithRetry(url: string, body: string, headers: Record<string,
   }
 }
 
+/**
+ * Creates a transport that buffers entries in memory and sends them as NDJSON batches via HTTP POST on flush.
+ * @param config - HTTP batch transport configuration.
+ * @returns A Transport that batches and sends entries over HTTP.
+ */
 export function createHttpBatchTransport(config: HttpBatchTransportConfig): Transport {
   const buffer: LogEntry[] = [];
   let timer: ReturnType<typeof setInterval> | undefined;

package/src/transports/pretty.ts

@@ -20,7 +20,9 @@ const LEVEL_COLOR: Record<LogLevel, string> = {
 
 const RESET = '\x1b[0m';
 
+/** Configuration for the pretty-print transport. */
 export interface PrettyTransportConfig {
+  /** Maximum number of characters to render for any single field value before truncating with `...`. Defaults to 120. */
   maxValueLength?: number;
 }
 
@@ -46,6 +48,11 @@ function formatFields(obj: Record<string, unknown>, maxLen: number): string {
     .join(' ');
 }
 
+/**
+ * Creates a transport that writes colorized, human-readable log output to the console.
+ * @param config - Optional pretty-print configuration.
+ * @returns A Transport that writes human-readable output.
+ */
 export function createPrettyTransport(config?: PrettyTransportConfig): Transport {
   const maxValueLength = config?.maxValueLength ?? 120;
 

package/src/transports/routed.ts

@@ -1,11 +1,19 @@
 import type { LogEntry, LogLevel, Transport } from '../types.ts';
 import { LOG_LEVELS } from '../levels.ts';
 
+/** A predicate-transport pair for routing log entries. */
 export interface TransportRoute {
+  /** Function that returns true if the entry should be sent to this route's transport. */
   predicate: (entry: LogEntry) => boolean;
+  /** The transport to write matching entries to. */
   transport: Transport;
 }
 
+/**
+ * Creates a transport that routes each entry to transports whose predicates match.
+ * @param routes - Array of predicate-transport pairs.
+ * @returns A Transport that routes entries by predicate.
+ */
 export function createRoutedTransport(routes: TransportRoute[]): Transport {
   return {
     write(entry: LogEntry): void {
@@ -21,15 +29,30 @@ export function createRoutedTransport(routes: TransportRoute[]): Transport {
   };
 }
 
+/**
+ * Creates a predicate that matches entries at or above the given severity level.
+ * @param level - The minimum severity level to match.
+ * @returns A predicate function that returns true for entries at or above the given level.
+ */
 export function atOrAboveLevel(level: LogLevel): (entry: LogEntry) => boolean {
   const min = LOG_LEVELS[level];
   return (entry) => LOG_LEVELS[entry.level] >= min;
 }
 
+/**
+ * Creates a predicate that matches entries at exactly the given severity level.
+ * @param level - The exact severity level to match.
+ * @returns A predicate function that returns true for entries at exactly the given level.
+ */
 export function exactLevel(level: LogLevel): (entry: LogEntry) => boolean {
   return (entry) => entry.level === level;
 }
 
+/**
+ * Creates a predicate that matches entries below the given severity level.
+ * @param level - The exclusive upper bound severity level.
+ * @returns A predicate function that returns true for entries below the given level.
+ */
 export function belowLevel(level: LogLevel): (entry: LogEntry) => boolean {
   const threshold = LOG_LEVELS[level];
   return (entry) => LOG_LEVELS[entry.level] < threshold;

package/src/types.ts

@@ -1,37 +1,93 @@
+/** Severity levels from least to most severe. */
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
 
+/** A structured log record produced by the logger. */
 export interface LogEntry {
+  /** Severity level of the entry. */
   level: LogLevel;
+  /** Unix millisecond timestamp via Date.now(). */
   timestamp: number;        // Unix ms via Date.now()
+  /** Optional human-readable message. */
   message?: string;
+  /** Contextual fields inherited from the logger or withContext(). */
   context: Record<string, unknown>;
+  /** Per-call structured data fields. */
   data: Record<string, unknown>;
 }
 
+/** Transforms or filters log entries before they reach transports. */
 export interface Plugin {
+  /** Unique identifier for the plugin. */
   name: string;
+  /**
+   * Transforms the given log entry, or returns null to drop it.
+   * @param entry - The log entry to transform.
+   * @returns The transformed entry, or null to drop it from the pipeline.
+   */
   transform(entry: LogEntry): LogEntry | null;
 }
 
+/** Delivers log entries to an output destination. */
 export interface Transport {
+  /**
+   * Writes a log entry to the transport's internal buffer or directly to output.
+   * @param entry - The log entry to write.
+   */
   write(entry: LogEntry): void;
+  /** Flushes buffered entries to the output destination. */
   flush(): Promise<void>;
 }
 
+/** Structured logger supporting leveled methods, child contexts, and flush. */
 export interface Logger {
+  /**
+   * Logs an entry at trace level.
+   * @param data - Structured data fields; use a `message` key for a human-readable message.
+   */
   trace(data: object): void;
+  /**
+   * Logs an entry at debug level.
+   * @param data - Structured data fields; use a `message` key for a human-readable message.
+   */
   debug(data: object): void;
+  /**
+   * Logs an entry at info level.
+   * @param data - Structured data fields; use a `message` key for a human-readable message.
+   */
   info(data: object): void;
+  /**
+   * Logs an entry at warn level.
+   * @param data - Structured data fields; use a `message` key for a human-readable message.
+   */
   warn(data: object): void;
+  /**
+   * Logs an entry at error level.
+   * @param data - Structured data fields; use a `message` key for a human-readable message.
+   */
   error(data: object): void;
+  /**
+   * Logs an entry at fatal level.
+   * @param data - Structured data fields; use a `message` key for a human-readable message.
+   */
   fatal(data: object): void;
+  /**
+   * Returns a new Logger with additional context fields merged in.
+   * @param context - Key-value pairs to add to every subsequent log entry.
+   * @returns A new Logger instance with the merged context.
+   */
   withContext(context: Record<string, unknown>): Logger;
+  /** Flushes all buffered entries through transports and awaits completion. */
   flush(): Promise<void>;
 }
 
+/** Configuration for createLogger(). */
 export interface LoggerOptions {
+  /** Minimum log level to emit. Entries below this level are silently dropped. Defaults to `'info'`. */
   level?: LogLevel;
+  /** Array of plugins applied to each entry in order before transport delivery. */
   plugins?: Plugin[];
+  /** Array of transports that receive entries on flush. */
   transports?: Transport[];
+  /** Initial context fields merged into every log entry produced by this logger. */
   context?: Record<string, unknown>;
 }