loggily 0.0.1 → 0.3.0

package/package.json

@@ -1,16 +1,64 @@
 {
   "name": "loggily",
-  "version": "0.0.1",
-  "description": "Structured logging with context, levels, and formatting — the logger that gets out of your way",
-  "keywords": ["logging", "logger", "structured", "debug", "log"],
+  "version": "0.3.0",
+  "description": "Structured logging with spans. ~3KB, zero-overhead disabled logging via optional chaining.",
+  "keywords": [
+    "logger",
+    "logging",
+    "optional-chaining",
+    "spans",
+    "structured",
+    "tracing",
+    "typescript",
+    "zero-overhead"
+  ],
+  "homepage": "https://beorn.codes/decant/",
+  "bugs": {
+    "url": "https://github.com/beorn/decant/issues"
+  },
   "license": "MIT",
-  "author": "Bjørn Stabell <bjorn@stabell.org>",
-  "homepage": "https://github.com/beorn/loggily",
+  "author": "Beorn",
   "repository": {
     "type": "git",
-    "url": "https://github.com/beorn/loggily.git"
+    "url": "https://github.com/beorn/decant.git"
   },
   "type": "module",
-  "main": "src/index.ts",
-  "files": ["src", "README.md"]
+  "module": "src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./src/index.browser.ts",
+      "default": "./src/index.ts"
+    },
+    "./file-writer": {
+      "types": "./dist/file-writer.d.ts",
+      "default": "./src/file-writer.ts"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "default": "./src/worker.ts"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "default": "./src/context.ts"
+    },
+    "./tracing": {
+      "types": "./dist/tracing.d.ts",
+      "default": "./src/tracing.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bunx --bun vitest run",
+    "docs:dev": "vitepress dev docs/site",
+    "docs:build": "vitepress build docs/site",
+    "docs:preview": "vitepress preview docs/site"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "vitepress": "^1.6.3",
+    "vitest": "^4.0.18"
+  }
 }

package/src/colors.ts

@@ -0,0 +1,27 @@
+/**
+ * Vendored ANSI color functions — replaces picocolors dependency.
+ * Supports NO_COLOR, FORCE_COLOR, and TTY detection.
+ */
+
+const _process = typeof process !== "undefined" ? process : undefined
+
+const enabled =
+  _process?.env?.["FORCE_COLOR"] !== undefined && _process?.env?.["FORCE_COLOR"] !== "0"
+    ? true
+    : _process?.env?.["NO_COLOR"] !== undefined
+      ? false
+      : (_process?.stdout?.isTTY ?? false)
+
+function wrap(open: string, close: string): (str: string) => string {
+  if (!enabled) return (str) => str
+  return (str) => open + str + close
+}
+
+export const colors = {
+  dim: wrap("\x1b[2m", "\x1b[22m"),
+  blue: wrap("\x1b[34m", "\x1b[39m"),
+  yellow: wrap("\x1b[33m", "\x1b[39m"),
+  red: wrap("\x1b[31m", "\x1b[39m"),
+  magenta: wrap("\x1b[35m", "\x1b[39m"),
+  cyan: wrap("\x1b[36m", "\x1b[39m"),
+}

package/src/context.ts

@@ -0,0 +1,155 @@
+/**
+ * AsyncLocalStorage-based context propagation for loggily — Node.js/Bun only.
+ *
+ * Separated from core logger to allow tree-shaking in browser bundles.
+ * When enabled, new spans automatically parent to the current context span,
+ * and writeLog() auto-tags with trace_id/span_id from context.
+ *
+ * @example
+ * ```typescript
+ * import { enableContextPropagation, getCurrentSpan } from "loggily/context"
+ *
+ * enableContextPropagation()
+ *
+ * const log = createLogger("myapp")
+ * {
+ *   using span = log.span("request")
+ *   // All logs and child spans within this async context
+ *   // automatically inherit trace_id and span_id
+ *   log.info("inside span") // auto-tagged with trace_id, span_id
+ *
+ *   const current = getCurrentSpan()
+ *   // current === { spanId: "sp_1", traceId: "tr_1", parentId: null }
+ * }
+ * ```
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks"
+import { _setContextHooks, _clearContextHooks } from "./core.js"
+
+// ============ Types ============
+
+/** Minimal span context stored in AsyncLocalStorage */
+export interface SpanContext {
+  readonly spanId: string
+  readonly traceId: string
+  readonly parentId: string | null
+}
+
+// ============ State ============
+
+let storage: AsyncLocalStorage<SpanContext> | null = null
+let contextEnabled = false
+
+// ============ API ============
+
+/**
+ * Enable AsyncLocalStorage-based context propagation.
+ * Once enabled, new spans automatically parent to the current context span,
+ * and log messages are auto-tagged with trace_id/span_id.
+ *
+ * **Node.js/Bun only** — not available in browser environments.
+ */
+export function enableContextPropagation(): void {
+  if (!storage) {
+    storage = new AsyncLocalStorage<SpanContext>()
+  }
+  contextEnabled = true
+
+  // Register hooks with core.ts
+  _setContextHooks({
+    getContextTags,
+    getContextParent() {
+      const span = getCurrentSpan()
+      if (!span) return null
+      return { spanId: span.spanId, traceId: span.traceId }
+    },
+    enterContext: enterSpanContext,
+    exitContext: exitSpanContext,
+  })
+}
+
+/**
+ * Disable context propagation.
+ * Existing spans continue to work, but new spans won't auto-parent.
+ */
+export function disableContextPropagation(): void {
+  contextEnabled = false
+  _clearContextHooks()
+}
+
+/** Check if context propagation is enabled */
+export function isContextPropagationEnabled(): boolean {
+  return contextEnabled
+}
+
+/**
+ * Get the current span context from AsyncLocalStorage.
+ * Returns null if no span is active in the current async context,
+ * or if context propagation is not enabled.
+ */
+export function getCurrentSpan(): SpanContext | null {
+  if (!contextEnabled || !storage) return null
+  return storage.getStore() ?? null
+}
+
+/**
+ * Enter a span context for the remainder of the current synchronous execution
+ * and any async operations started from it. Used by the logger when creating
+ * spans with `using` — since `using` doesn't wrap user code in a callback,
+ * `enterWith()` is the right primitive.
+ *
+ * @internal
+ */
+export function enterSpanContext(spanId: string, traceId: string, parentId: string | null): void {
+  if (!contextEnabled || !storage) return
+  storage.enterWith({ spanId, traceId, parentId })
+}
+
+/**
+ * Restore the parent span context (called when a span ends).
+ * Re-enters the parent's context, or clears the context if there is no parent.
+ *
+ * @internal
+ */
+export function exitSpanContext(parentId: string | null, parentTraceId: string | null): void {
+  if (!contextEnabled || !storage) return
+  if (parentId && parentTraceId) {
+    // Restore parent context — note: we don't have the parent's parentId
+    // but that's fine since this context is only used for auto-tagging and
+    // auto-parenting new child spans (which will read spanId and traceId).
+    storage.enterWith({ spanId: parentId, traceId: parentTraceId, parentId: null })
+  } else {
+    // No parent — exit the context entirely
+    // enterWith(undefined as any) is not ideal, but there's no "exitWith"
+    // We use a sentinel to indicate "no active span"
+    storage.enterWith(undefined as unknown as SpanContext)
+  }
+}
+
+/**
+ * Run a function within a span context.
+ * Used for explicit context scoping (e.g., in request handlers).
+ *
+ * @param context - The span context to set
+ * @param fn - The function to run within the context
+ * @returns The return value of fn
+ */
+export function runInSpanContext<T>(context: SpanContext, fn: () => T): T {
+  if (!contextEnabled || !storage) return fn()
+  return storage.run(context, fn)
+}
+
+/**
+ * Get the context tags (trace_id, span_id) for the current async context.
+ * Used by writeLog() to auto-tag log messages.
+ * Returns empty object if context propagation is disabled or no span is active.
+ */
+export function getContextTags(): Record<string, string> {
+  const span = getCurrentSpan()
+  if (!span) return {}
+  return {
+    trace_id: span.traceId,
+    span_id: span.spanId,
+  }
+}