@heojeongbo/log-palette 0.2.0

package/dist/types/config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Global format configuration for log-palette.
+ * Change these settings once to affect all loggers.
+ */
+export interface GlobalConfig {
+    /**
+     * Number of inner characters inside the prefix brackets.
+     * Total prefix width = innerWidth + 2 (for the `[` and `]`).
+     *
+     * - Short domains are left-padded with dots to fill this width.
+     * - Domains longer than this are truncated with `…`.
+     *
+     * @default 8  → prefix is always `[XXXXXXXX]` (10 chars total)
+     */
+    innerWidth: number;
+    /**
+     * Whether to include a timestamp in each log line.
+     * @default true
+     */
+    timestamp: boolean;
+}
+/**
+ * Read the current global configuration.
+ * Returns a snapshot — mutating the returned object has no effect.
+ */
+export declare function getConfig(): Readonly<GlobalConfig>;
+/**
+ * Update one or more global format settings.
+ * Changes apply immediately to all subsequent log calls across all loggers.
+ *
+ * @example
+ * ```ts
+ * // Wider prefix column (good when you have long domain names)
+ * configure({ innerWidth: 12 })
+ *
+ * // Strip timestamps (cleaner in environments that add their own)
+ * configure({ timestamp: false })
+ * ```
+ */
+export declare function configure(options: Partial<GlobalConfig>): void;

package/dist/types/formatter.d.ts

@@ -0,0 +1,3 @@
+export declare function formatTimestamp(date: Date): string;
+export declare function formatPrefix(domain: string): string;
+export declare function prefixStyle(color: string): string;

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export type { GlobalConfig } from './config.js';
+export { configure, getConfig } from './config.js';
+export { createLogger, LogPalette } from './logger.js';
+export { disableAll, enableAll, getAllLoggers, getLogger, setGlobalLevel } from './registry.js';
+export type { Logger, LoggerOptions, LogLevel } from './types.js';

package/dist/types/logger.d.ts

@@ -0,0 +1,97 @@
+import type { Logger, LoggerOptions, LogLevel } from './types.js';
+/**
+ * A logger instance tied to a specific domain.
+ * Outputs colored prefix badges to the browser console.
+ *
+ * @example
+ * ```ts
+ * const log = new LogPalette('auth', { color: '#7c3aed', level: 'info' })
+ * log.info('User signed in', { userId: 42 })
+ * // → [....auth] 05:35:41.039 User signed in { userId: 42 }
+ * ```
+ */
+export declare class LogPalette implements Logger {
+    readonly domain: string;
+    readonly color: string;
+    private _minLevel;
+    private _enabled;
+    /**
+     * @param domain  Service/feature name shown in the prefix badge (e.g. 'auth', 'api').
+     * @param options Optional configuration for color, level filtering, and enabled state.
+     */
+    constructor(domain: string, options?: LoggerOptions);
+    /**
+     * Dynamically change the minimum log level for this logger.
+     * Useful for adjusting verbosity at runtime without recreating the logger.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Enable or disable this logger at runtime.
+     * When disabled, all log calls are silently dropped.
+     */
+    setEnabled(enabled: boolean): void;
+    private _log;
+    /** @inheritdoc */
+    log(...args: unknown[]): void;
+    /** @inheritdoc */
+    info(...args: unknown[]): void;
+    /** @inheritdoc */
+    warn(...args: unknown[]): void;
+    /** @inheritdoc */
+    error(...args: unknown[]): void;
+    /** @inheritdoc */
+    debug(...args: unknown[]): void;
+    /**
+     * Open a DevTools console group with the domain prefix applied to the label.
+     * Always call `groupEnd()` to close it.
+     *
+     * @example
+     * ```ts
+     * apiLog.group('Fetch /users')
+     * apiLog.info('response', data)
+     * apiLog.groupEnd()
+     * ```
+     */
+    group(label: string): void;
+    /**
+     * Open a collapsed DevTools console group with the domain prefix applied to the label.
+     * Always call `groupEnd()` to close it.
+     */
+    groupCollapsed(label: string): void;
+    /** Close the most recently opened group. */
+    groupEnd(): void;
+    /**
+     * Start a named performance timer, namespaced to this domain.
+     * Use `timeEnd(label)` to stop it and log the elapsed time.
+     *
+     * @example
+     * ```ts
+     * authLog.time('login')
+     * await performLogin()
+     * authLog.timeEnd('login')
+     * // DevTools: [....auth] login: 42.1ms
+     * ```
+     */
+    time(label: string): void;
+    /**
+     * Stop the named timer started with `time(label)` and log the elapsed duration.
+     * @param label Must match the label passed to `time()`.
+     */
+    timeEnd(label: string): void;
+}
+/**
+ * Create a new logger for the given domain.
+ * Each call creates a fresh instance; use `getLogger()` for singleton behavior.
+ *
+ * @param domain  Service/feature name (e.g. 'auth', 'api', 'payments').
+ * @param options Optional color, level, and enabled settings.
+ *
+ * @example
+ * ```ts
+ * const log = createLogger('auth')
+ * log.info('App started')
+ *
+ * const payLog = createLogger('payments', { color: '#16a34a', level: 'warn' })
+ * ```
+ */
+export declare function createLogger(domain: string, options?: LoggerOptions): Logger;

package/dist/types/registry.d.ts

@@ -0,0 +1,64 @@
+import type { Logger, LoggerOptions, LogLevel } from './types.js';
+/**
+ * Get or create a logger for the given domain.
+ * Unlike `createLogger()`, this returns the same instance every time it is
+ * called with the same domain — making it safe to call from multiple modules.
+ *
+ * Options are only applied on first call for a domain; subsequent calls with
+ * the same domain return the existing instance regardless of options.
+ *
+ * @example
+ * ```ts
+ * // In module A
+ * const log = getLogger('api')
+ *
+ * // In module B — same instance
+ * const log = getLogger('api')
+ * ```
+ */
+export declare function getLogger(domain: string, options?: LoggerOptions): Logger;
+/**
+ * Return a read-only snapshot of all registered loggers, keyed by domain.
+ * Useful for debugging or building DevTools integrations.
+ *
+ * @example
+ * ```ts
+ * const loggers = getAllLoggers()
+ * console.log([...loggers.keys()])  // ['api', 'auth', 'payments']
+ * ```
+ */
+export declare function getAllLoggers(): ReadonlyMap<string, Logger>;
+/**
+ * Set the minimum log level for every registered logger at once.
+ * Loggers created after this call are not affected — they use their own
+ * options or the default ('debug').
+ *
+ * Call this early in your app entry point to control verbosity globally:
+ *
+ * @example
+ * ```ts
+ * // Only show warnings and errors in production
+ * if (import.meta.env.PROD) setGlobalLevel('warn')
+ * ```
+ */
+export declare function setGlobalLevel(level: LogLevel): void;
+/**
+ * Enable all registered loggers.
+ *
+ * @example
+ * ```ts
+ * enableAll()
+ * ```
+ */
+export declare function enableAll(): void;
+/**
+ * Disable all registered loggers. All log calls will be silently dropped
+ * until `enableAll()` or individual `setEnabled(true)` is called.
+ *
+ * @example
+ * ```ts
+ * // Silence everything in production builds
+ * if (import.meta.env.PROD) disableAll()
+ * ```
+ */
+export declare function disableAll(): void;

package/dist/types/types.d.ts

@@ -0,0 +1,68 @@
+export type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+export interface LoggerOptions {
+    /**
+     * CSS color string for this domain's prefix badge.
+     * If omitted, a color is auto-derived from the domain name via djb2 hash.
+     * Accepts any valid CSS color value: '#f06', 'hsl(200,80%,55%)', 'coral', etc.
+     */
+    color?: string;
+    /**
+     * Minimum log level to output. Levels below this are silently dropped.
+     * Order (lowest→highest): debug < log < info < warn < error
+     * Defaults to 'debug' (all levels pass through).
+     */
+    level?: LogLevel;
+    /**
+     * When false, suppress all output regardless of level.
+     * Defaults to true.
+     */
+    enabled?: boolean;
+}
+export interface Logger {
+    /** Log at 'log' level. */
+    log(...args: unknown[]): void;
+    /** Log at 'info' level. */
+    info(...args: unknown[]): void;
+    /** Log at 'warn' level. */
+    warn(...args: unknown[]): void;
+    /** Log at 'error' level. */
+    error(...args: unknown[]): void;
+    /** Log at 'debug' level. */
+    debug(...args: unknown[]): void;
+    /**
+     * Open a collapsible DevTools group with the domain prefix.
+     * Must be closed with `groupEnd()`.
+     */
+    group(label: string): void;
+    /**
+     * Open a collapsed DevTools group with the domain prefix.
+     * Must be closed with `groupEnd()`.
+     */
+    groupCollapsed(label: string): void;
+    /** Close the most recently opened group. */
+    groupEnd(): void;
+    /**
+     * Start a named timer prefixed with the domain.
+     * Use `timeEnd(label)` to stop and print elapsed time.
+     */
+    time(label: string): void;
+    /**
+     * Stop a named timer and log the elapsed time to the console.
+     * @param label Must match the label passed to `time()`.
+     */
+    timeEnd(label: string): void;
+    /**
+     * Dynamically change the minimum log level for this logger.
+     * Useful for adjusting verbosity at runtime.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Enable or disable this logger at runtime.
+     * When disabled, all log calls are silently dropped.
+     */
+    setEnabled(enabled: boolean): void;
+    /** The domain name this logger was created with. */
+    readonly domain: string;
+    /** The resolved CSS color string for this logger's prefix. */
+    readonly color: string;
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@heojeongbo/log-palette",
+  "version": "0.2.0",
+  "description": "Browser logging library with domain-based colored prefixes",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts && tsc --emitDeclarationOnly",
+    "dev": "rolldown -c rolldown.config.ts --watch",
+    "check": "tsc --noEmit",
+    "lint": "biome check src/ example/src/",
+    "lint:fix": "biome check --write src/ example/src/",
+    "format": "biome format --write src/ example/src/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "release-it",
+    "release:minor": "release-it minor",
+    "release:major": "release-it major",
+    "release:patch": "release-it patch",
+    "release:dry": "release-it --dry-run"
+  },
+  "keywords": [
+    "logger",
+    "browser",
+    "console",
+    "color",
+    "debug"
+  ],
+  "author": "heojeongbo <heojungbo@gmail.com> (https://github.com/HeoJeongBo)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HeoJeongBo/log-palette.git"
+  },
+  "homepage": "https://github.com/HeoJeongBo/log-palette#readme",
+  "bugs": {
+    "url": "https://github.com/HeoJeongBo/log-palette/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.3.11",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@release-it/conventional-changelog": "^10.0.6",
+    "release-it": "^19.2.4",
+    "rolldown": "^1.0.0-rc.11",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "workspaces": [
+    "example"
+  ]
+}

package/src/__tests__/color.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { domainToColor } from '../color.js'
+
+describe('domainToColor', () => {
+  it('returns a valid hsl color string', () => {
+    const color = domainToColor('auth')
+    expect(color).toMatch(/^hsl\(\d+,\s*75%,\s*60%\)$/)
+  })
+
+  it('returns the same color for the same domain', () => {
+    expect(domainToColor('auth')).toBe(domainToColor('auth'))
+    expect(domainToColor('api')).toBe(domainToColor('api'))
+    expect(domainToColor('payments')).toBe(domainToColor('payments'))
+  })
+
+  it('returns different colors for different domains', () => {
+    const colors = new Set(['auth', 'api', 'ui', 'payments', 'websocket'].map(domainToColor))
+    expect(colors.size).toBeGreaterThan(1)
+  })
+
+  it('hue is within 0-359 range', () => {
+    for (const domain of ['a', 'test', 'some-long-domain-name', '']) {
+      const color = domainToColor(domain)
+      const match = color.match(/^hsl\((\d+),/)
+      expect(match).not.toBeNull()
+      const hue = parseInt(match?.[1] ?? '', 10)
+      expect(hue).toBeGreaterThanOrEqual(0)
+      expect(hue).toBeLessThan(360)
+    }
+  })
+})

package/src/__tests__/config.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { configure, getConfig } from '../config.js'
+
+describe('configure / getConfig', () => {
+  // Restore default config after each test
+  afterEach(() => {
+    configure({ innerWidth: 8, timestamp: true })
+  })
+
+  it('returns default config', () => {
+    const config = getConfig()
+    expect(config.innerWidth).toBe(8)
+    expect(config.timestamp).toBe(true)
+  })
+
+  it('updates innerWidth', () => {
+    configure({ innerWidth: 12 })
+    expect(getConfig().innerWidth).toBe(12)
+  })
+
+  it('updates timestamp', () => {
+    configure({ timestamp: false })
+    expect(getConfig().timestamp).toBe(false)
+  })
+
+  it('partial update leaves other fields unchanged', () => {
+    configure({ innerWidth: 10 })
+    expect(getConfig().timestamp).toBe(true)
+  })
+
+  it('throws RangeError for innerWidth < 1', () => {
+    expect(() => configure({ innerWidth: 0 })).toThrow(RangeError)
+    expect(() => configure({ innerWidth: -1 })).toThrow(RangeError)
+  })
+
+  it('getConfig returns a snapshot (mutating it has no effect)', () => {
+    const snap = getConfig() as { innerWidth: number }
+    snap.innerWidth = 999
+    expect(getConfig().innerWidth).toBe(8)
+  })
+})

package/src/__tests__/formatter.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { configure } from '../config.js'
+import { formatPrefix, formatTimestamp, prefixStyle } from '../formatter.js'
+
+describe('formatTimestamp', () => {
+  it('returns HH:mm:ss.SSS format', () => {
+    const date = new Date('2024-01-01T05:35:41.039Z')
+    // Use local time representation
+    const ts = formatTimestamp(date)
+    expect(ts).toMatch(/^\d{2}:\d{2}:\d{2}\.\d{3}$/)
+  })
+
+  it('pads single-digit values with zeros', () => {
+    const date = new Date(2024, 0, 1, 1, 2, 3, 4)
+    const ts = formatTimestamp(date)
+    expect(ts).toBe('01:02:03.004')
+  })
+})
+
+describe('formatPrefix', () => {
+  it('pads short domains with dots on the left', () => {
+    expect(formatPrefix('auth')).toBe('[....auth]')
+    expect(formatPrefix('api')).toBe('[.....api]')
+    expect(formatPrefix('ui')).toBe('[......ui]')
+  })
+
+  it('uses no dots for exactly 8-char domains', () => {
+    expect(formatPrefix('payments')).toBe('[payments]')
+  })
+
+  it('all prefixes have consistent bracket width (10 chars)', () => {
+    const domains = ['a', 'ui', 'auth', 'api', 'payments']
+    for (const domain of domains) {
+      expect(formatPrefix(domain)).toHaveLength(10)
+    }
+  })
+
+  it('truncates long domains to 7 chars + ellipsis', () => {
+    const result = formatPrefix('websocket')
+    expect(result).toBe('[websock\u2026]')
+    expect(result).toHaveLength(10)
+  })
+
+  it('truncates very long domains consistently', () => {
+    const result = formatPrefix('verylongdomainname')
+    expect(result).toHaveLength(10)
+    expect(result).toMatch(/^\[.{8}\]$/)
+    expect(result).toContain('\u2026')
+  })
+})
+
+describe('formatPrefix with custom innerWidth', () => {
+  afterEach(() => configure({ innerWidth: 8 }))
+
+  it('respects innerWidth: 4', () => {
+    configure({ innerWidth: 4 })
+    expect(formatPrefix('ui')).toBe('[..ui]')
+    expect(formatPrefix('auth')).toBe('[auth]')
+    expect(formatPrefix('login')).toBe('[log\u2026]')
+  })
+
+  it('all prefixes match innerWidth + 2', () => {
+    configure({ innerWidth: 12 })
+    const domains = ['a', 'auth', 'payments', 'verylongdomainname']
+    for (const domain of domains) {
+      expect(formatPrefix(domain)).toHaveLength(14)
+    }
+  })
+})
+
+describe('prefixStyle', () => {
+  it('returns a CSS string with the given color', () => {
+    const style = prefixStyle('#ff0000')
+    expect(style).toContain('#ff0000')
+    expect(style).toContain('font-weight: bold')
+  })
+
+  it('works with hsl colors', () => {
+    const style = prefixStyle('hsl(200, 75%, 60%)')
+    expect(style).toContain('hsl(200, 75%, 60%)')
+  })
+})