vite-plugin-better-console 1.0.2

package/README.md

@@ -0,0 +1,238 @@
+# vite-plugin-better-console
+
+Zero-dependency Vite plugin that replaces the plain `console.log` workflow with a structured, colour-coded, dev-only logger. Every call is automatically **silent in production** — no dead code, no bundle bloat.
+
+---
+
+## Features
+
+| | |
+|---|---|
+| 🎨 **Colour-coded badges** | per log level (debug / info / warn / error) |
+| 📍 **Auto caller info** | file, line, and function name from the stack |
+| 🔢 **Log level filtering** | suppress noisy debug logs in staging |
+| 🧩 **Smart value formatting** | Map, Set, Date, Promise, Error, Array, Object all pretty-printed |
+| ⏱ **Timestamps** | locale, ISO, time-only, date-only, or relative (`+42ms`) |
+| 🔇 **Production safe** | entire logger tree is a no-op when `mode === 'production'` |
+| 🏗 **Zero imports in app code** | plugin auto-injects into your entry files |
+| 🦾 **Full TypeScript** | types for every option, augments `console.better` globally |
+
+---
+
+## Install
+
+```bash
+npm install vite-plugin-better-console
+# or
+pnpm add vite-plugin-better-console
+# or
+yarn add vite-plugin-better-console
+```
+
+Requires **Vite 5+**.
+
+---
+
+## Quick start
+
+### 1. Register the plugin
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { betterConsole } from 'vite-plugin-better-console'
+
+export default defineConfig({
+  plugins: [betterConsole()],
+})
+```
+
+### 2. Use `console.better` anywhere in your app
+
+```ts
+// No import needed — the plugin injects it automatically
+console.better('user loaded', { id: 1, name: 'Ada' })
+console.better.debug('cache key', cacheKey)
+console.better.warn('slow response', response, { comment: 'over 2 s' })
+console.better.error('fetch failed', error)
+console.better.table('users', users)
+```
+
+---
+
+## Configuration
+
+All options are optional.
+
+```ts
+betterConsole({
+  // ── Plugin ────────────────────────────────────────────────
+  inject: true,                    // auto-inject into detected entries (default: true)
+  injectEntries: ['src/main.ts'],  // additional explicit entries
+  injectPattern: '**/bootstrap.{ts,js}', // glob or RegExp for extra targets
+
+  // ── Logger ────────────────────────────────────────────────
+  warnInProduction: true,    // one-time banner if called in production
+  logLevel: 'debug',         // 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  collapsed: true,           // collapse groups by default
+  showPath: true,            // show caller file path
+  showLine: true,            // show caller line number
+  showFn: true,              // show caller function name
+  showType: true,            // show value type
+  timestamp: true,           // show timestamp
+  timestampFormat: 'locale', // 'locale'|'iso'|'time-only'|'date-only'|'relative'
+
+  // ── Custom badge labels ───────────────────────────────────
+  badge: {
+    debug: '🐛',
+    info:  'ℹ️',
+    warn:  '⚠️',
+    error: '🔴',
+  },
+  // badge: false  — disable the prefix, show only the label
+
+  // ── CSS theme ─────────────────────────────────────────────
+  theme: {
+    badge_debug: 'color:#7c3aed;font-weight:700',
+    badge_info:  'color:#1d4ed8;font-weight:700',
+    badge_warn:  'color:#b45309;font-weight:700',
+    badge_error: 'color:#dc2626;font-weight:700',
+    label: 'color:#94a3b8;font-size:11px',
+    value: 'color:#0ea5e9;font-weight:600',
+    meta:  'color:#64748b;font-size:11px',
+  },
+})
+```
+
+### Option reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `inject` | `boolean` | `true` | Auto-inject runtime into entry files |
+| `injectEntries` | `string[]` | `[]` | Additional entry globs |
+| `injectPattern` | `string \| RegExp` | — | Extra glob/regex targets |
+| `warnInProduction` | `boolean` | `true` | Show one-time prod warning |
+| `logLevel` | `LogLevel` | `'debug'` | Minimum level to print |
+| `collapsed` | `boolean` | `true` | Collapse groups by default |
+| `showPath` | `boolean` | `true` | Show file path |
+| `showLine` | `boolean` | `true` | Show line number |
+| `showFn` | `boolean` | `true` | Show function name |
+| `showType` | `boolean` | `true` | Show value type |
+| `timestamp` | `boolean` | `true` | Show timestamp |
+| `timestampFormat` | `TimestampFormat` | `'locale'` | Timestamp format |
+| `badge` | `Record<LogLevel,string> \| false` | built-in | Badge prefix per level |
+| `theme` | `ThemeStyles` | built-in | CSS `%c` strings |
+
+---
+
+## Per-call options
+
+Override any global option for a single call:
+
+```ts
+console.better('api response', data, {
+  level: 'warn',          // treat as warn
+  comment: 'slow path',   // note appended at the end
+  collapsed: false,       // expand this group
+  enabled: isDebugMode,   // conditional logging
+  timestamp: false,       // skip timestamp
+  // Manual caller override:
+  path: 'src/App.vue',
+  line: 42,
+  fn: 'handleSubmit',
+})
+```
+
+---
+
+## Timestamp formats
+
+| Format | Example |
+|--------|---------|
+| `'locale'` | `06 Jun 2026 14:32:11` |
+| `'iso'` | `2026-06-06T14:32:11.000Z` |
+| `'time-only'` | `14:32:11` |
+| `'date-only'` | `06 Jun 2026` |
+| `'relative'` | `+142ms` (since page load) |
+
+---
+
+## Value smart-formatting
+
+| Type | Output |
+|------|--------|
+| `Array` / `Object` | `console.table` |
+| `Map` | `console.table` with `{ key, value }` rows |
+| `Set` | `console.table` with `{ index, value }` rows |
+| `Date` | ISO + local string |
+| `Promise` | `Promise { <pending> }` + resolved/rejected |
+| `Error` | Full stack trace |
+| `Function` | `ƒ functionName` |
+| `null` / `undefined` | Styled italic |
+| Primitives | `console.info` |
+
+---
+
+## Standalone usage (without Vite)
+
+You can use the runtime directly — useful in Node scripts, tests, or frameworks
+that don't use Vite:
+
+```ts
+import { createLogger, attachRuntime } from 'vite-plugin-better-console/runtime'
+
+// Standalone logger
+const log = createLogger({ dev: true, logLevel: 'info' })
+log('server ready', { port: 3000 })
+log.warn('rate limit', { ip: '1.2.3.4' })
+
+// Or attach to console globally
+attachRuntime(createLogger({ dev: process.env.NODE_ENV !== 'production' }))
+console.better.info('attached')
+```
+
+---
+
+## How it works
+
+```
+vite.config.ts
+  └─ betterConsole()
+       │
+       ├─ config()          — injects __BETTER_CONSOLE_DEV__ / _WARN_ / _OPTIONS__ defines
+       ├─ configResolved()  — collects Rollup entry paths
+       ├─ transformIndexHtml() — collects <script type="module" src="…"> entries
+       ├─ resolveId()       — handles `virtual:better-console`
+       ├─ load()            — virtual module: `import 'vite-plugin-better-console/runtime'`
+       └─ transform()       — prepends the virtual import to each entry
+                              (dev only — production builds skip this entirely)
+
+Browser
+  └─ runtime/index.js (auto-executed)
+       ├─ resolveOptions()  — reads injected JSON + defaults
+       ├─ createLogger()    — builds the LogFn
+       └─ attachRuntime()   — sets console.better = log
+```
+
+---
+
+## TypeScript support
+
+`console.better` is globally typed — no import needed in your app:
+
+```ts
+// tsconfig.json — add to types or reference
+/// <reference types="vite-plugin-better-console/runtime" />
+```
+
+Or add to `vite-env.d.ts`:
+
+```ts
+/// <reference types="vite-plugin-better-console/runtime" />
+```
+
+---
+
+## License
+
+MIT

package/dist/caller.d.ts

@@ -0,0 +1,93 @@
+// ─── Caller Detection ────────────────────────────────────────────────────────
+//
+// Parses the V8 / SpiderMonkey / JavaScriptCore stack trace format to find
+// the first frame that is NOT part of this library's own internals.
+//
+// Supported formats:
+//   Chrome/Node:  "    at FnName (file:///path/to/file.js:12:5)"
+//   Chrome anon:  "    at file:///path/to/file.js:12:5"
+//   Firefox:      "FnName@file:///path/to/file.js:12:5"
+//   Safari:       "FnName@file:///path/to/file.js:12:5"
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CallerInfo {
+  path?: string
+  line?: string
+  col?: string
+  fn?: string
+}
+
+/**
+ * Tokens that identify internal frames we want to skip.
+ * These are matched case-insensitively against "path fn".
+ */
+const SKIP_TOKENS = [
+  'vite-plugin-better-console',
+  'betterConsole',
+  'getCaller',
+  'createLogger',
+  'attachRuntime',
+  'logAtLevel',
+  'printMeta',
+  'printValue',
+]
+
+// Chrome / Node: `at [async] [FnName] (path:line:col)` or `at path:line:col`
+const RE_V8 =
+  /^\s*at\s+(?:async\s+)?(?:([\w$.<>\[\] ]+?)\s+\()?(?:file:\/\/)?(.+?):(\d+)(?::(\d+))?\)?$/
+
+// Firefox / Safari: `[FnName@]path:line:col`
+const RE_FF =
+  /^\s*(?:([\w$.<>\[\]]+)@)?(?:file:\/\/)?(.+?):(\d+)(?::(\d+))?$/
+
+function parseFrame(raw: string): CallerInfo | null {
+  let m = raw.match(RE_V8)
+  if (m) {
+    const [, fn, path, line, col] = m
+    if (!path) return null
+    return { fn: fn?.trim() || undefined, path: cleanPath(path), line, col }
+  }
+
+  m = raw.match(RE_FF)
+  if (m) {
+    const [, fn, path, line, col] = m
+    if (!path) return null
+    return { fn: fn?.trim() || undefined, path: cleanPath(path), line, col }
+  }
+
+  return null
+}
+
+function cleanPath(raw: string): string {
+  return raw
+    .replace(/^file:\/\//, '')
+    .replace(/\\/g, '/')
+    .replace(/\?.*$/, '')   // strip HMR query strings e.g. ?t=123456
+    .replace(/^\/\//, '/')
+}
+
+function isInternal(info: CallerInfo): boolean {
+  const haystack = `${info.path ?? ''} ${info.fn ?? ''}`.toLowerCase()
+  return SKIP_TOKENS.some((tok) => haystack.includes(tok.toLowerCase()))
+}
+
+/**
+ * Returns the first non-internal caller from the current stack.
+ * `extraSkip` bumps the start position when wrapped inside additional helpers.
+ */
+export function getCaller(extraSkip = 0): CallerInfo {
+  const stack = new Error().stack
+  if (!stack) return {}
+
+  // Slice off "Error\n" + the frames that belong to getCaller itself
+  const lines = stack.split('\n').slice(1 + extraSkip)
+
+  for (const line of lines) {
+    const frame = parseFrame(line)
+    if (!frame) continue
+    if (isInternal(frame)) continue
+    return frame
+  }
+
+  return {}
+}

package/dist/config.d.ts

@@ -0,0 +1,116 @@
+import type { LogLevel, LoggerOptions, ThemeStyles, TimestampFormat } from './types.js'
+import { LOG_LEVEL_RANK } from './types.js'
+
+// ─── Global define injected by the Vite plugin ───────────────────────────────
+declare const __BETTER_CONSOLE_DEV__: boolean | undefined
+declare const __BETTER_CONSOLE_WARN__: boolean | undefined
+declare const __BETTER_CONSOLE_OPTIONS__: string | undefined
+
+// ─── Default theme ───────────────────────────────────────────────────────────
+
+export const DEFAULT_THEME: Required<ThemeStyles> = {
+  badge_debug:
+    'display:inline-block;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:700;letter-spacing:.5px;background:#f3f0ff;color:#6d28d9;border:1px solid #c4b5fd',
+  badge_info:
+    'display:inline-block;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:700;letter-spacing:.5px;background:#eff6ff;color:#1d4ed8;border:1px solid #93c5fd',
+  badge_warn:
+    'display:inline-block;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:700;letter-spacing:.5px;background:#fffbeb;color:#b45309;border:1px solid #fcd34d',
+  badge_error:
+    'display:inline-block;padding:2px 8px;border-radius:4px;font-size:11px;font-weight:700;letter-spacing:.5px;background:#fef2f2;color:#dc2626;border:1px solid #fca5a5',
+  label: 'color:#94a3b8;font-size:11px;min-width:68px;display:inline-block',
+  value: 'color:#0ea5e9;font-weight:600',
+  meta:  'color:#64748b;font-size:11px',
+  divider: 'color:#cbd5e1',
+}
+
+// ─── Default logger options ───────────────────────────────────────────────────
+
+export const DEFAULT_OPTIONS: Required<Omit<LoggerOptions, 'dev' | 'warnInProduction' | 'theme' | 'badge'>> = {
+  logLevel: 'debug',
+  collapsed: true,
+  showPath: true,
+  showLine: true,
+  showFn: true,
+  showType: true,
+  timestamp: true,
+  timestampFormat: 'locale',
+}
+
+// ─── Dev / warn detection ─────────────────────────────────────────────────────
+
+export function detectDev(): boolean {
+  // 1. Plugin compile-time define (most reliable)
+  if (typeof __BETTER_CONSOLE_DEV__ !== 'undefined') {
+    return __BETTER_CONSOLE_DEV__
+  }
+  // 2. Vite HMR env
+  try {
+    if (import.meta.env?.PROD) return false
+    if (import.meta.env?.DEV)  return true
+  } catch { /* not in Vite context */ }
+  // 3. Node env
+  if (typeof process !== 'undefined') {
+    return process.env?.NODE_ENV !== 'production'
+  }
+  return true
+}
+
+export function detectWarnInProduction(): boolean {
+  if (typeof __BETTER_CONSOLE_WARN__ !== 'undefined') {
+    return __BETTER_CONSOLE_WARN__
+  }
+  return true
+}
+
+// ─── Injected options (from vite.config) ─────────────────────────────────────
+
+function parseInjectedOptions(): Partial<LoggerOptions> {
+  if (typeof __BETTER_CONSOLE_OPTIONS__ === 'undefined') return {}
+  try {
+    const raw = __BETTER_CONSOLE_OPTIONS__
+    return (typeof raw === 'string' ? JSON.parse(raw) : raw) ?? {}
+  } catch {
+    return {}
+  }
+}
+
+// ─── Resolve ─────────────────────────────────────────────────────────────────
+
+export type ResolvedLoggerOptions = {
+  dev: boolean
+  warnInProduction: boolean
+  logLevel: LogLevel
+  collapsed: boolean
+  showPath: boolean
+  showLine: boolean
+  showFn: boolean
+  showType: boolean
+  timestamp: boolean
+  timestampFormat: TimestampFormat
+  theme: Required<ThemeStyles>
+  badge: Partial<Record<LogLevel, string>> | false
+}
+
+export function resolveOptions(overrides: LoggerOptions = {}): ResolvedLoggerOptions {
+  const injected = parseInjectedOptions()
+
+  return {
+    ...DEFAULT_OPTIONS,
+    ...injected,
+    ...overrides,
+    dev:              overrides.dev              ?? detectDev(),
+    warnInProduction: overrides.warnInProduction ?? detectWarnInProduction(),
+    theme: {
+      ...DEFAULT_THEME,
+      ...injected.theme,
+      ...overrides.theme,
+    },
+    badge: overrides.badge ?? injected.badge ?? {},
+  }
+}
+
+// ─── Level check ─────────────────────────────────────────────────────────────
+
+export function shouldLog(level: LogLevel, minLevel: LogLevel = 'debug'): boolean {
+  return (LOG_LEVEL_RANK[level] ?? 0) >= (LOG_LEVEL_RANK[minLevel] ?? 0)
+}

package/dist/format.d.ts

@@ -0,0 +1,137 @@
+import type { TimestampFormat } from './types.js'
+import type { ResolvedLoggerOptions } from './config.js'
+
+// ─── Type detection ───────────────────────────────────────────────────────────
+
+export function typeOf(value: unknown): string {
+  return Object.prototype.toString.call(value).slice(8, -1)
+}
+
+// ─── Timestamp ────────────────────────────────────────────────────────────────
+
+let _start = Date.now()
+
+export function formatTimestamp(date: Date, format: TimestampFormat): string {
+  if (typeof format === 'function') return format(date)
+
+  switch (format) {
+    case 'iso':
+      return date.toISOString()
+
+    case 'time-only':
+      return date.toLocaleTimeString('en-GB', {
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+      })
+
+    case 'date-only':
+      return date.toLocaleDateString('en-GB', {
+        year: 'numeric',
+        month: 'short',
+        day: '2-digit',
+      })
+
+    case 'relative': {
+      const ms = date.getTime() - _start
+      if (ms < 1000) return `+${ms}ms`
+      if (ms < 60_000) return `+${(ms / 1000).toFixed(2)}s`
+      return `+${(ms / 60_000).toFixed(1)}min`
+    }
+
+    case 'locale':
+    default: {
+      const d = date.toLocaleDateString('en-GB', {
+        year: 'numeric',
+        month: 'short',
+        day: '2-digit',
+      })
+      const t = date.toLocaleTimeString('en-GB', {
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+      })
+      return `${d} ${t}`
+    }
+  }
+}
+
+// ─── Meta row printer ────────────────────────────────────────────────────────
+
+export function printMeta(
+  label: string,
+  value: unknown,
+  opts: ResolvedLoggerOptions,
+): void {
+  if (value == null || value === '') return
+
+  console.info(
+    `%c${label.padEnd(10)}%c${value}`,
+    opts.theme.label,
+    opts.theme.value,
+  )
+}
+
+// ─── Value pretty-printer ────────────────────────────────────────────────────
+
+export function printValue(value: unknown): void {
+  const kind = typeOf(value)
+
+  switch (kind) {
+    case 'Map': {
+      const rows = Array.from(value as Map<unknown, unknown>, ([k, v]) => ({ key: k, value: v }))
+      console.table(rows)
+      return
+    }
+
+    case 'Set': {
+      const rows = Array.from(value as Set<unknown>, (v, i) => ({ index: i, value: v }))
+      console.table(rows)
+      return
+    }
+
+    case 'Array':
+    case 'Object':
+      console.table(value)
+      return
+
+    case 'Date': {
+      const d = value as Date
+      console.info(`${d.toISOString()}  (local: ${d.toLocaleString()})`)
+      return
+    }
+
+    case 'Promise':
+      console.info('%cPromise { <pending> }', 'color:#94a3b8;font-style:italic')
+      ;(value as Promise<unknown>).then(
+        (r)  => console.info('  ↳ resolved →', r),
+        (e)  => console.info('  ↳ rejected →', e),
+      )
+      return
+
+    case 'Error': {
+      const err = value as Error
+      console.info(err.stack ?? err.message ?? String(err))
+      return
+    }
+
+    case 'Function':
+      console.info(`ƒ ${(value as Function).name || '(anonymous)'}`)
+      return
+
+    case 'RegExp':
+      console.info(String(value))
+      return
+
+    case 'Null':
+      console.info('%cnull', 'color:#94a3b8;font-style:italic')
+      return
+
+    case 'Undefined':
+      console.info('%cundefined', 'color:#94a3b8;font-style:italic')
+      return
+
+    default:
+      if (value !== undefined) console.info(value)
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+// Runtime entry point — imported by the virtual module injected into app entries.
+// This file intentionally runs side-effects so that console.log is patched
+// before any app code executes.
+
+export type { LogLevel, LoggerOptions, LogCallOptions, LogFn, ThemeStyles, BetterConsoleOptions } from './types.js'
+export { LOG_LEVEL_RANK } from './types.js'
+export { DEFAULT_THEME, DEFAULT_OPTIONS, resolveOptions, shouldLog, detectDev, detectWarnInProduction } from './config.js'
+export { getCaller }   from './caller.js'
+export { typeOf, formatTimestamp, printMeta, printValue } from './format.js'
+export { createLogger } from './logger.js'
+
+import { createLogger } from './logger.js'
+import { resolveOptions } from './config.js'
+
+/**
+ * Attach a logger instance to `console.log` (aliased as `console.better`).
+ * Calling this more than once is safe — subsequent calls overwrite the reference.
+ */
+export function attachRuntime(logger?: ReturnType<typeof createLogger>) {
+  const instance = logger ?? createLogger(resolveOptions())
+
+  if (typeof console !== 'undefined') {
+    // Primary alias — idiomatic usage
+    ;(console as any).log = (console as any).log    // keep original intact
+    ;(console as any).better = instance
+
+    // Legacy alias kept for users who prefer the old name
+    ;(console as any).logger = instance
+  }
+
+  return instance
+}
+
+// ── Auto-attach on import ─────────────────────────────────────────────────────
+// When the Vite plugin injects `import 'vite-plugin-better-console/runtime'`
+// into an entry file this runs exactly once before app code.
+
+const _logger = attachRuntime()
+export default _logger