loggily 0.0.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn Stabell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,153 @@
-# loggily
+# Loggily
 
-Structured logging with context, levels, and formatting — the logger that gets out of your way.
+**Clarity without the clutter.**
 
-**Coming soon.**
+One library. One namespace tree. One output pipeline. For logs (structured JSON or console), debug(), and tracing spans. Near-zero overhead from disabled log levels. Pure TypeScript. ~3KB. Zero dependencies.
+
+[![Tests](https://github.com/beorn/loggily/actions/workflows/test.yml/badge.svg)](https://github.com/beorn/loggily/actions/workflows/test.yml)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.2+-blue.svg)](https://www.typescriptlang.org/)
+[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> Early release (0.x) -- API may evolve before 1.0.
+
+## Install
+
+```bash
+npm install loggily
+```
+
+| Requirement   | Version                                           |
+| ------------- | ------------------------------------------------- |
+| Node.js       | 18+                                               |
+| Bun           | 1.0+                                              |
+| TypeScript    | 5.2+ (for `using`; `.end()` works on any version) |
+| Module format | ESM-only                                          |
+| Browser       | Supported via conditional export                  |
+
+## Quick Start
+
+```typescript
+import { createLogger } from "loggily"
+
+const log = createLogger("myapp")
+
+// ?. skips the entire call — including argument evaluation — when the level is disabled
+log.info?.("server started", { port: 3000 })
+log.debug?.("cache hit", { key: "user:42" })
+log.error?.(new Error("connection lost"))
+```
+
+Output in development (colorized with timestamps and clickable source lines):
+
+```
+14:32:15 INFO myapp server started {port: 3000}
+14:32:15 DEBUG myapp cache hit {key: "user:42"}
+14:32:15 ERROR myapp connection lost
+```
+
+Set `NODE_ENV=production` or `LOG_FORMAT=json` and the same code emits structured JSON:
+
+```json
+{ "time": "2024-01-15T14:32:15.123Z", "level": "info", "name": "myapp", "msg": "server started", "port": 3000 }
+```
+
+### Spans
+
+Time operations with lightweight spans. Uses TC39 [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) (`using` requires TypeScript 5.2+ and runtime support). For other environments, call `.end()` manually:
+
+```typescript
+// With `using` (TS 5.2+, Bun 1.0+, Node 22+)
+{
+  using span = log.span("db:query", { table: "users" })
+  const users = await db.query("SELECT * FROM users")
+  span.spanData.count = users.length
+}
+// Output: SPAN myapp:db:query (45ms) {count: 100, table: "users"}
+
+// Without `using` — works on any runtime
+const span = log.span("db:query", { table: "users" })
+try {
+  const users = await db.query("SELECT * FROM users")
+  span.spanData.count = users.length
+} finally {
+  span.end()
+}
+```
+
+## Why Loggily?
+
+One API for debug-style namespace logging, structured JSON output, and lightweight spans. Many projects end up with separate tools for these -- **debug** for conditional output, **pino/winston** for production logs, a tracing SDK for timings -- with separate configs, formats, and APIs. Loggily integrates all three into one namespace tree, one output pipeline, one `?.` pattern.
+
+### Near-zero cost for disabled logs
+
+Most loggers waste work when logging is disabled. Even with a noop function, arguments are still evaluated:
+
+```typescript
+// Traditional — args are ALWAYS evaluated, even when debug is off
+log.debug(`state: ${JSON.stringify(computeExpensiveState())}`)
+```
+
+Loggily uses optional chaining to skip the entire call — including argument evaluation:
+
+```typescript
+// Loggily — args are NOT evaluated when disabled
+log.debug?.(`state: ${JSON.stringify(computeExpensiveState())}`)
+```
+
+For trivial arguments the difference is negligible. But for real-world logging — string interpolation, JSON serialization, state snapshots — optional chaining is typically **10x+ faster** because it skips the work entirely. The more expensive your arguments, the bigger the win.
+
+> **Note**: The big performance advantage is specifically for disabled logging with expensive arguments, not universal logger throughput. Pino is optimized for high-throughput enabled JSON logging; Loggily's biggest advantage is skipping work when logs are disabled. See [benchmarks](https://beorn.codes/loggily/guide/benchmarks) for detailed numbers per scenario.
+
+## Features
+
+- **Namespace hierarchy** — organize logs with `:` separators. `log.logger("db")` creates `myapp:db`. Children inherit parent context.
+- **Lightweight spans and trace IDs** — time any operation with `using span = log.span("name")`. Automatic duration, parent-child tracking, and trace IDs. For full OpenTelemetry interoperability with exporters and propagation, use OpenTelemetry.
+- **Lazy messages** — `log.debug?.(() => expensiveString())` skips the function entirely when disabled.
+- **Child context** — `log.child({ requestId })` adds structured fields to every message in the chain.
+- **Dev & production** — colorized console with timestamps, level colors, and clickable source lines in development. Structured JSON in production. Switches automatically via `NODE_ENV` — same code, zero config.
+- **File writer** — `addWriter()` + `createFileWriter()` for buffered file output with auto-flush.
+- **Worker threads** — forward logs from workers to the main thread with full type safety (`loggily/worker`).
+- **debug-compatible namespace filtering** — reads `DEBUG=myapp:*` just like the debug package. Easy migration from debug — see the [migration guide](https://beorn.codes/loggily/guide/migration-from-debug).
+
+## When Not to Use Loggily
+
+- **Max-throughput transport pipelines** — use [Pino](https://getpino.io/) for worker-thread transports, custom serializers, and log rotation.
+- **Vendor/exporter interop** — use [OpenTelemetry](https://opentelemetry.io/) for distributed tracing with propagation, semantic conventions, and backend integrations.
+- **Tiny dev-only namespace logs** — use [debug](https://github.com/debug-js/debug) if all you need is conditional dev output with zero ceremony.
+
+## Documentation
+
+- **[Get Started](https://beorn.codes/loggily/guide/journey)** — progressive guide from first log to full observability
+- **[Full docs site](https://beorn.codes/loggily/)** — guides, API reference, migration guides
+- [Comparison](https://beorn.codes/loggily/guide/comparison) — vs Pino, Winston, Bunyan, debug
+- [Migration from debug](https://beorn.codes/loggily/guide/migration-from-debug) — step-by-step migration guide
+
+## Environment Variables
+
+| Variable       | Values                                  | Effect                                  |
+| -------------- | --------------------------------------- | --------------------------------------- |
+| `LOG_LEVEL`    | trace, debug, info, warn, error, silent | Minimum output level                    |
+| `LOG_FORMAT`   | console, json                           | Output format                           |
+| `DEBUG`        | `*`, namespace prefixes, `-prefix`      | Namespace filter (like `debug` package) |
+| `TRACE`        | `1`, `true`, or namespace prefixes      | Enable span output                      |
+| `TRACE_FORMAT` | json                                    | Force JSON for spans                    |
+| `NODE_ENV`     | production                              | Auto-enable JSON format                 |
+
+## API
+
+| Function                                                               | Description                                                   |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `createLogger(name, props?)`                                           | Create a logger (disabled levels return `undefined` for `?.`) |
+| `.trace?.()` / `.debug?.()` / `.info?.()` / `.warn?.()` / `.error?.()` | Log at level (message + optional data)                        |
+| `.logger(namespace)`                                                   | Create child logger with extended namespace                   |
+| `.span(namespace, props?)`                                             | Create timed span (implements `Disposable`)                   |
+| `.child(context)`                                                      | Create child with structured context fields                   |
+| `addWriter(fn)` / `createFileWriter(path)`                             | Custom output writers                                         |
+| `setLogLevel()` / `setLogFormat()` / `enableSpans()`                   | Runtime configuration                                         |
+| `createWorkerLogger()` / `createWorkerLogHandler()`                    | Worker thread support (`loggily/worker`)                      |
+
+See the [full API reference](https://beorn.codes/loggily/api/) for all functions and options.
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,16 +1,77 @@
 {
   "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.4.0",
+  "description": "TypeScript logger with debug-style namespaces, structured JSON output, and lightweight spans. Disabled logs skip argument evaluation via optional chaining.",
+  "keywords": [
+    "browser",
+    "bun",
+    "debug",
+    "json-logger",
+    "logger",
+    "logging",
+    "namespace",
+    "node",
+    "observability",
+    "optional-chaining",
+    "spans",
+    "structured-logging",
+    "tracing",
+    "typescript"
+  ],
+  "homepage": "https://beorn.codes/loggily/",
+  "bugs": {
+    "url": "https://github.com/beorn/loggily/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"
   },
+  "files": [
+    "src",
+    "dist"
+  ],
   "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"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bunx --bun vitest run",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "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,170 @@
+/**
+ * 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
+
+/**
+ * Map from spanId → the SpanContext that was active when the span was entered.
+ * Used to restore the exact previous context on exit, avoiding corruption
+ * from non-LIFO end() ordering.
+ */
+const previousContexts = new Map<string, SpanContext | null>()
+
+// ============ 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.
+ *
+ * Captures the full previous SpanContext snapshot so it can be restored
+ * exactly on exit, even with non-LIFO end() ordering.
+ *
+ * @internal
+ */
+export function enterSpanContext(spanId: string, traceId: string, parentId: string | null): void {
+  if (!contextEnabled || !storage) return
+
+  // Capture the full previous context before overwriting
+  const previous = storage.getStore() ?? null
+  previousContexts.set(spanId, previous)
+
+  storage.enterWith({ spanId, traceId, parentId })
+}
+
+/**
+ * Restore the previous span context (called when a span ends).
+ * Restores the exact SpanContext snapshot captured at enter time,
+ * preventing corruption from non-LIFO end() ordering.
+ *
+ * @internal
+ */
+export function exitSpanContext(spanId: string): void {
+  if (!contextEnabled || !storage) return
+
+  const previous = previousContexts.get(spanId)
+  previousContexts.delete(spanId)
+
+  if (previous) {
+    storage.enterWith(previous)
+  } else {
+    // No previous context — exit entirely
+    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,
+  }
+}