loggily 0.0.1 → 0.4.0

package/src/file-writer.ts

@@ -0,0 +1,110 @@
+/**
+ * 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

@@ -0,0 +1,72 @@
+/**
+ * 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 +1,18 @@
-export const VERSION = "0.0.1"
+/**
+ * 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/tracing.ts

@@ -0,0 +1,150 @@
+/**
+ * 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
+}