loggily 0.6.0 → 0.6.2

package/src/file-writer.ts

@@ -1,110 +0,0 @@
-/**
- * File writer for loggily — Node.js/Bun only.
- *
- * Separated from core logger to allow tree-shaking in browser bundles.
- * Uses dynamic import("node:fs") to avoid static dependency on Node APIs.
- */
-
-import { openSync, writeSync, closeSync } from "node:fs"
-
-/** Options for creating an async buffered file writer */
-export interface FileWriterOptions {
-  /** Buffer size threshold in bytes before flushing (default: 4096) */
-  bufferSize?: number
-  /** Flush interval in milliseconds (default: 100) */
-  flushInterval?: number
-}
-
-/** An async buffered file writer with automatic flushing */
-export interface FileWriter {
-  /** Write a line to the buffer (appends newline) */
-  write(line: string): void
-  /** Flush the buffer immediately */
-  flush(): void
-  /** Close the writer and flush remaining buffer */
-  close(): void
-}
-
-/**
- * Create an async buffered file writer for log output.
- * Buffers writes and flushes on size threshold or interval.
- * Registers a process.on('exit') handler to flush remaining buffer.
- *
- * **Node.js/Bun only** — not available in browser environments.
- *
- * @param filePath - Path to the log file (opened in append mode)
- * @param options - Buffer size and flush interval configuration
- * @returns FileWriter with write, flush, and close methods
- *
- * @example
- * const writer = createFileWriter('/tmp/app.log')
- * const unsubscribe = addWriter((formatted) => writer.write(formatted))
- *
- * // On shutdown:
- * unsubscribe()
- * writer.close()
- */
-export function createFileWriter(filePath: string, options: FileWriterOptions = {}): FileWriter {
-  const bufferSize = options.bufferSize ?? 4096
-  const flushInterval = options.flushInterval ?? 100
-
-  let buffer = ""
-  let fd: number | null = null
-  let timer: ReturnType<typeof setInterval> | null = null
-  let closed = false
-
-  // Open file in append mode
-  fd = openSync(filePath, "a")
-
-  /** Flush buffer contents to disk synchronously */
-  function flush(): void {
-    if (buffer.length === 0 || fd === null) return
-    const data = buffer
-    writeSync(fd, data)
-    buffer = ""
-  }
-
-  // Set up periodic flush
-  timer = setInterval(flush, flushInterval)
-  // Don't let the timer keep the process alive
-  if (timer && typeof timer === "object" && "unref" in timer) {
-    ;(timer as { unref(): void }).unref()
-  }
-
-  // Flush on process exit to avoid data loss
-  const exitHandler = (): void => flush()
-  process.on("exit", exitHandler)
-
-  return {
-    write(line: string): void {
-      if (closed) return
-      buffer += line + "\n"
-      if (buffer.length >= bufferSize) {
-        flush()
-      }
-    },
-
-    flush,
-
-    close(): void {
-      if (closed) return
-      closed = true
-      if (timer !== null) {
-        clearInterval(timer)
-        timer = null
-      }
-      try {
-        flush()
-      } catch {
-        // Swallow flush errors during close — data loss is unavoidable
-        // at this point, but we must still release the fd and exit handler.
-      } finally {
-        if (fd !== null) {
-          closeSync(fd)
-          fd = null
-        }
-        process.removeListener("exit", exitHandler)
-      }
-    },
-  }
-}

package/src/index.browser.ts

@@ -1,72 +0,0 @@
-/**
- * loggily browser entry point.
- *
- * Re-exports the full logger API except createFileWriter (which requires node:fs).
- * Bundlers resolve this via the "browser" condition in package.json exports.
- */
-
-// Re-export everything from core logger
-export {
-  // Types
-  type OutputLogLevel,
-  type LogLevel,
-  type LazyMessage,
-  type SpanData,
-  type Logger,
-  type SpanLogger,
-  type OutputMode,
-  type LogFormat,
-  type ConditionalLogger,
-
-  // Writers
-  addWriter,
-  setSuppressConsole,
-  setOutputMode,
-  getOutputMode,
-
-  // Configuration
-  setLogLevel,
-  getLogLevel,
-  enableSpans,
-  disableSpans,
-  spansAreEnabled,
-  setTraceFilter,
-  getTraceFilter,
-  setDebugFilter,
-  getDebugFilter,
-  setLogFormat,
-  getLogFormat,
-
-  // ID management
-  resetIds,
-
-  // Span collection
-  startCollecting,
-  stopCollecting,
-  getCollectedSpans,
-  clearCollectedSpans,
-
-  // Logger creation
-  createLogger,
-} from "./core.js"
-
-// Tracing utilities (runtime-agnostic, work in browser)
-export {
-  setIdFormat,
-  getIdFormat,
-  type IdFormat,
-  traceparent,
-  type TraceparentOptions,
-  setSampleRate,
-  getSampleRate,
-} from "./tracing.js"
-
-// File writer types (exported for type compatibility, but the function throws)
-export type { FileWriterOptions, FileWriter } from "./file-writer.js"
-
-/** @throws Always — createFileWriter is not available in browser environments */
-export function createFileWriter(): never {
-  throw new Error(
-    "createFileWriter is not available in browser environments. Use addWriter() with a custom transport instead.",
-  )
-}

package/src/index.ts

@@ -1,18 +0,0 @@
-/**
- * loggily - Structured logging with spans
- *
- * Full entry point for Node.js, Bun, and Deno.
- * Browser environments use index.browser.ts via the "browser" export condition.
- */
-
-export * from "./core.js"
-export { createFileWriter, type FileWriter, type FileWriterOptions } from "./file-writer.js"
-export {
-  setIdFormat,
-  getIdFormat,
-  type IdFormat,
-  traceparent,
-  type TraceparentOptions,
-  setSampleRate,
-  getSampleRate,
-} from "./tracing.js"

package/src/metrics.ts

@@ -1,201 +0,0 @@
-/**
- * Metrics collection for loggily spans.
- *
- * Two modes:
- * - **Ambient**: import this module → spans auto-record when TRACE is active
- * - **Explicit**: `withMetrics(collector?)(logger)` for custom collection
- *
- * @example
- * ```typescript
- * import { spanStats } from "loggily/metrics"
- * // TRACE=myapp bun run app
- * // → on exit: spanStats() returns aggregated p50/p95/p99
- *
- * // Custom collector:
- * import { withMetrics, createMetricsCollector } from "loggily/metrics"
- * const log = withMetrics()(createLogger("myapp"))
- * ```
- */
-
-import {
-  type SpanRecorder,
-  type SpanRecord,
-  type ConditionalLogger,
-  type Logger,
-  type LazyProps,
-  type SpanLogger,
-  _setAmbientRecorder,
-  spansAreEnabled,
-} from "./core.js"
-
-export type { SpanRecorder, SpanRecord }
-
-// ============ Stats ============
-
-export interface SpanStats {
-  count: number
-  min: number
-  max: number
-  mean: number
-  p50: number
-  p95: number
-  p99: number
-  total: number
-}
-
-function percentile(sorted: number[], p: number): number {
-  if (sorted.length === 0) return 0
-  const idx = Math.min(Math.floor(sorted.length * p), sorted.length - 1)
-  return sorted[idx]!
-}
-
-function computeStats(durations: number[]): SpanStats {
-  const sorted = [...durations].sort((a, b) => a - b)
-  const total = sorted.reduce((sum, d) => sum + d, 0)
-  return {
-    count: sorted.length,
-    min: sorted[0] ?? 0,
-    max: sorted[sorted.length - 1] ?? 0,
-    mean: sorted.length > 0 ? total / sorted.length : 0,
-    p50: percentile(sorted, 0.5),
-    p95: percentile(sorted, 0.95),
-    p99: percentile(sorted, 0.99),
-    total,
-  }
-}
-
-// ============ Collector ============
-
-export interface MetricsCollector extends SpanRecorder {
-  /** Get stats for a specific span namespace */
-  stats(name: string): SpanStats | undefined
-  /** Get stats for all recorded namespaces */
-  all(): Map<string, SpanStats>
-  /** Format a human-readable summary */
-  summary(): string
-  /** Reset all collected data */
-  reset(): void
-}
-
-export function createMetricsCollector(maxEntries = 1000): MetricsCollector {
-  const store = new Map<string, number[]>()
-
-  return {
-    recordSpan(data: SpanRecord): void {
-      let arr = store.get(data.name)
-      if (!arr) {
-        arr = []
-        store.set(data.name, arr)
-      }
-      arr.push(data.durationMs)
-      // Bound memory: keep last N entries per namespace
-      if (arr.length > maxEntries) arr.shift()
-    },
-
-    stats(name: string): SpanStats | undefined {
-      const arr = store.get(name)
-      if (!arr || arr.length === 0) return undefined
-      return computeStats(arr)
-    },
-
-    all(): Map<string, SpanStats> {
-      const result = new Map<string, SpanStats>()
-      for (const [name, durations] of store) {
-        if (durations.length > 0) result.set(name, computeStats(durations))
-      }
-      return result
-    },
-
-    summary(): string {
-      const entries = [...this.all().entries()]
-      if (entries.length === 0) return "(no span data)"
-      const lines = entries.map(
-        ([name, s]) =>
-          `${name}: ${s.count} spans, mean=${s.mean.toFixed(1)}ms, p50=${s.p50.toFixed(1)}ms, p95=${s.p95.toFixed(1)}ms, p99=${s.p99.toFixed(1)}ms`,
-      )
-      return lines.join("\n")
-    },
-
-    reset(): void {
-      store.clear()
-    },
-  }
-}
-
-// ============ Ambient Collector ============
-
-const _ambient = createMetricsCollector()
-
-// Auto-activate ambient recording.
-// Always set — the cost is one ?.recordSpan() call per span (negligible).
-// The TRACE gate already controls whether spans are *created* at all.
-_setAmbientRecorder(_ambient)
-
-/** Get aggregated span stats (from ambient collector). */
-export function spanStats(): Map<string, SpanStats> {
-  return _ambient.all()
-}
-
-/** Get the ambient collector's formatted summary. */
-export function spanSummary(): string {
-  return _ambient.summary()
-}
-
-/** Reset the ambient collector. */
-export function resetSpanStats(): void {
-  _ambient.reset()
-}
-
-// ============ withMetrics ============
-
-/**
- * Compose a logger with a metrics collector.
- * Returns a curried wrapper: `withMetrics(collector?)(logger)`
- *
- * - No arg: uses the built-in ambient collector
- * - Custom collector: records to your collector
- * - Stackable: `withMetrics(a)(withMetrics(b)(logger))` fans out to both
- *
- * @example
- * ```typescript
- * const log = withMetrics()(createLogger("myapp"))
- * const log = withMetrics(myCollector)(createLogger("myapp"))
- * ```
- */
-export function withMetrics(collector?: SpanRecorder): (logger: ConditionalLogger) => ConditionalLogger {
-  const recorder = collector ?? _ambient
-
-  return (logger: ConditionalLogger): ConditionalLogger => {
-    // Wrap the logger's span method to intercept disposal
-    return new Proxy(logger, {
-      get(target, prop: string | symbol) {
-        if (prop === "span") {
-          const originalSpan = target.span
-          if (!originalSpan) return undefined // TRACE off — preserve ?.  behavior
-          return (namespace?: string, props?: LazyProps): SpanLogger => {
-            const span = originalSpan.call(target, namespace, props)
-            // Wrap disposal to record to our collector
-            const originalDispose = (span as unknown as { [Symbol.dispose]: () => void })[Symbol.dispose]
-            ;(span as unknown as { [Symbol.dispose]: () => void })[Symbol.dispose] = () => {
-              originalDispose.call(span)
-              // After original disposal computed duration, record it
-              if (span.spanData?.duration != null) {
-                recorder.recordSpan({ name: span.name, durationMs: span.spanData.duration })
-              }
-            }
-            return span
-          }
-        }
-        if (prop === "logger") {
-          // Child loggers inherit the metrics wrapper
-          return (namespace?: string, childProps?: Record<string, unknown>): Logger => {
-            const child = target.logger(namespace, childProps)
-            // Re-wrap the child — withMetrics(recorder) applied recursively
-            return withMetrics(recorder)(child as unknown as ConditionalLogger) as unknown as Logger
-          }
-        }
-        return (target as unknown as Record<string | symbol, unknown>)[prop]
-      },
-    })
-  }
-}

package/src/tracing.ts

@@ -1,150 +0,0 @@
-/**
- * Distributed tracing utilities for loggily.
- *
- * Provides W3C-compatible trace/span ID generation, traceparent header formatting,
- * and head-based sampling. All features are opt-in and don't break the existing API.
- */
-
-import type { SpanData } from "./core.js"
-
-// ============ ID Format ============
-
-/** Supported ID formats */
-export type IdFormat = "simple" | "w3c"
-
-let currentIdFormat: IdFormat = "simple"
-
-/**
- * Set the ID format for new spans and traces.
- * - "simple": sp_1, sp_2, tr_1, tr_2 (default, lightweight)
- * - "w3c": 32-char hex trace ID, 16-char hex span ID (W3C Trace Context compatible)
- */
-export function setIdFormat(format: IdFormat): void {
-  currentIdFormat = format
-}
-
-/** Get the current ID format */
-export function getIdFormat(): IdFormat {
-  return currentIdFormat
-}
-
-// Simple format counters (used by core.ts via the generator functions)
-let simpleSpanCounter = 0
-let simpleTraceCounter = 0
-
-/** Generate a hex string of the given byte length using crypto.randomUUID */
-function randomHex(bytes: number): string {
-  // crypto.randomUUID() gives us 32 hex chars (128 bits) after removing dashes
-  // For 16 bytes (32 hex chars) we use one UUID, for 8 bytes (16 hex chars) we take a slice
-  const uuid = crypto.randomUUID().replace(/-/g, "")
-  return uuid.slice(0, bytes * 2)
-}
-
-/** Generate a span ID according to the current format */
-export function generateSpanId(): string {
-  if (currentIdFormat === "w3c") {
-    return randomHex(8) // 16-char hex
-  }
-  return `sp_${(++simpleSpanCounter).toString(36)}`
-}
-
-/** Generate a trace ID according to the current format */
-export function generateTraceId(): string {
-  if (currentIdFormat === "w3c") {
-    return randomHex(16) // 32-char hex
-  }
-  return `tr_${(++simpleTraceCounter).toString(36)}`
-}
-
-/** Reset ID counters (for testing) */
-export function resetIdCounters(): void {
-  simpleSpanCounter = 0
-  simpleTraceCounter = 0
-}
-
-// ============ W3C Traceparent ============
-
-/** Options for traceparent header formatting */
-export interface TraceparentOptions {
-  /** Whether this span is sampled. Defaults to true for backwards compatibility. */
-  sampled?: boolean
-}
-
-/**
- * Format a W3C traceparent header from span data.
- *
- * Format: `{version}-{trace-id}-{span-id}-{trace-flags}`
- * - version: "00" (current W3C spec version)
- * - trace-id: 32 hex chars (128 bits)
- * - span-id: 16 hex chars (64 bits)
- * - trace-flags: "01" (sampled) or "00" (not sampled)
- *
- * Works with both simple and W3C ID formats. Simple IDs are zero-padded to spec length.
- *
- * @param spanData - Span data with id and traceId
- * @param options - Optional settings (sampled flag). Defaults to sampled=true.
- * @returns W3C traceparent header string
- *
- * @example
- * ```typescript
- * const span = log.span("http-request")
- * const header = traceparent(span.spanData)
- * // → "00-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6-1a2b3c4d5e6f7a8b-01"
- * fetch(url, { headers: { traceparent: header } })
- * ```
- */
-export function traceparent(spanData: SpanData, options?: TraceparentOptions): string {
-  const traceId = padHex(spanData.traceId, 32)
-  const spanId = padHex(spanData.id, 16)
-  const flags = (options?.sampled ?? true) ? "01" : "00"
-  return `00-${traceId}-${spanId}-${flags}`
-}
-
-/** Pad or hash an ID to the specified hex length */
-function padHex(id: string, length: number): string {
-  // If it's already the right length and looks like hex, use as-is
-  if (id.length === length && /^[0-9a-f]+$/.test(id)) {
-    return id
-  }
-
-  // For simple IDs (sp_1, tr_1), create a deterministic hex representation
-  // by encoding the string as hex bytes, zero-padded to the target length
-  let hex = ""
-  for (let i = 0; i < id.length; i++) {
-    hex += id.charCodeAt(i).toString(16).padStart(2, "0")
-  }
-  // Pad or truncate to target length
-  return hex.padStart(length, "0").slice(-length)
-}
-
-// ============ Sampling ============
-
-let sampleRate = 1.0
-
-/**
- * Set the head-based sampling rate for new traces.
- * Applied at trace creation — all spans within a sampled trace are kept.
- *
- * @param rate - Sampling rate from 0.0 (sample nothing) to 1.0 (sample everything, default)
- */
-export function setSampleRate(rate: number): void {
-  if (rate < 0 || rate > 1) {
-    throw new Error(`Sample rate must be between 0.0 and 1.0, got ${rate}`)
-  }
-  sampleRate = rate
-}
-
-/** Get the current sampling rate */
-export function getSampleRate(): number {
-  return sampleRate
-}
-
-/**
- * Determine whether a new trace should be sampled.
- * Called at trace creation time (head-based sampling).
- */
-export function shouldSample(): boolean {
-  if (sampleRate >= 1.0) return true
-  if (sampleRate <= 0.0) return false
-  return Math.random() < sampleRate
-}