colorino 0.6.0 → 0.6.1

package/README.md

@@ -1,334 +1,262 @@
-# <a id="0"></a>🎨 Colorino
-
-**The zero-configuration, context-aware `console` logger for Node.js and the browser.**
-
-Colorino automatically adapts its palette to your terminal or browser DevTools theme.
-
-# <a id="0"></a>
-
-- [Why use Colorino?](#1)
-- [Features](#2)
-- [Installation](#3)
-- [Usage](#4)
-  - [Quick Start](#4-1)
-  - [Creating a Custom Logger](#4-2)
-  - [Options & Theme Overrides](#4-3)
-    - [Available Theme Presets](#4-3-1)
-    - [Examples](#4-3-2)
-  - [Customization](#4-4)
-  - [Supported Environment Variables](#4-5)
-- [Colorino vs. Chalk](#5)
-- [API Reference](#6)
-  - [1. `colorino` (default instance)](#6-1)
-  - [2. `createColorino(palette?, options?)` (factory)](#6-2)
-- [Extending Colorino](#7)
-  - [Why This Pattern?](#7-1)
-- [Contributing](#8)
-- [License](#9)
-
-<!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli -->
-
-## <a id="1"></a>Why use Colorino?
-
-Plain `console.log` is colorless and inconsistent. Libraries like `chalk` let you style strings, but you have to decorate every message and manually manage color choices.
-
-Colorino is different: it’s a "batteries-included" logging facade with beautiful, theme-aware colors and a familiar API—no learning curve, no configuration. Instantly upgrade your logs everywhere.
-
-## <a id="2"></a>Features
-
-- 🎨 **Smart Theming:** Automatically detects *dark/light* mode and uses a coordinated color palette.
-- 🤝 **Familiar API:** If you know `console.log`, you already know Colorino: all standard log levels are supported.
-- 🔀 **Environment-Aware:** Works in **Node.js** (ANSI color and truecolor) and all major **Browsers** (CSS styles).
-- ⚡️ **Fast, Lightweight:** Minimal dependencies, works great in modern frameworks and CLIs.
-- 🔒 **Robust:** Handles bad inputs and weird environments safely.
-- 🛠️ **Customizable:** Override individual log colors for your own branding.
-
-## <a id="3"></a>Installation
-
-```bash
-npm install colorino
-```
-
-## <a id="4"></a>Usage
-
-### <a id="4-1"></a>Quick Start
-
-Just import the default instance and log away!
-
-```typescript
-import { colorino } from 'colorino'
-
-// All log levels automatically themed
-colorino.error('A critical error!')
-colorino.warn('A warning message.')
-colorino.info('Useful info logging.')
-colorino.log('A plain log.')
-colorino.debug('Debug with objects:', { x: 5, y: 9 })
-colorino.trace('Tracing app start...')
-```
-
-### <a id="4-2"></a>Creating a Custom Logger
-
-Need your own colors or different settings?
-Use the factory to create as many loggers as you want (each with its own palette and options):
-
-```typescript
-import { createColorino } from 'colorino'
-
-const myLogger = createColorino(
-  { // Palette (partial)
-    error: '#ff007b',
-    info: '#3498db'
-  },
-  { disableWarnings: true } // Options (see below)
-)
-myLogger.error('Critical!')
-myLogger.info('Rebranded info!')
-```
-
-### <a id="4-3"></a>Options & Theme Overrides
-
-`createColorino(palette?, options?)` accepts:
-
-| Option            | Type                           | Default | Description                                                                    |
-|-------------------|--------------------------------|---------|--------------------------------------------------------------------------------|
-| `disableWarnings` | `boolean`                      | `false` | Suppress warnings when color support can't be detected or is disabled.         |
-| `theme`           | `ThemeOption` (see below)      | `'auto'`| Control the active color theme or force a specific mode.                       |
-
-**`theme` accepts three types of values:**
-
-1. **`'auto'`** (Default): Automatically detects your terminal or browser theme (dark/light) and applies the matching default preset.
-2. **`'dark' | 'light'`**: Forces the logger into a specific mode using the default preset for that mode.
-3. **`ThemeName`**: Forces a specific built-in palette (e.g., `'dracula'`).
-
-#### <a id="4-3-1"></a>Available Theme Presets
-
-Pass any of these names to the `theme` option to use a specific palette:
-
-| Theme Name           | Type            | Description                                      |
-|----------------------|-----------------|--------------------------------------------------|
-| `'dracula'`          | **Dark** (High) | Vibrant pinks, purples, and cyans.               |
-| `'catppuccin-mocha'` | **Dark** (Low)  | *Default Dark.* Soothing pastel colors.          |
-| `'github-light'`     | **Light** (High)| *Default Light.* Clean, sharp, high-contrast.    |
-| `'catppuccin-latte'` | **Light** (Low) | Warm, cozy light mode with soft colors.          |
-
-#### <a id="4-3-2"></a>Examples
-
-**1. Force a specific mode (uses defaults):**
-Useful for CI/CD or environments where detection fails.
-
-```typescript
-// Forces the default dark theme (Catppuccin Mocha)
-const darkLogger = createColorino({}, { theme: 'dark' })
-```
-
-**2. Use a specific preset:**
-Instant branding with zero configuration.
-
-```typescript
-// Forces the Dracula palette
-const draculaLogger = createColorino({}, { theme: 'dracula' })
-```
-
-**3. Customize a preset:**
-Overlay your own colors on top of a built-in theme.
-
-```typescript
-// Use GitHub Light but with a custom error color
-const myLogger = createColorino(
-  { error: '#ff007b' }, 
-  { theme: 'github-light' }
-)
-```
-
-> **Tip:**
-> Forcing `'dark'` or `'light'` bypasses automatic theming, ensuring predictable colors in environments with unknown or unsupported theme detection (like some CI pipelines, dumb terminals, or minimal browsers).
-
-### <a id="4-4"></a>Customization
-
-Use your brand colors by passing a partial palette to the `createColorino` factory. Any log levels you don't specify will use the smart theme defaults.
-
-```typescript
-import { createColorino } from 'colorino'
-
-// Custom error color; others use theme defaults
-const myLogger = createColorino({ error: '#ff007b' })
-
-myLogger.error('Oh no!') // Uses your custom color
-myLogger.info('Still styled by theme.') // Uses the default theme color
-```
-
-### <a id="4-5"></a>Supported Environment Variables
-
-Colorino auto-detects your environment and color support, but you can override behavior using these standard environment variables (compatible with Chalk):
-
-| Variable         | Effect                                            | Example                  |
-|------------------|---------------------------------------------------|--------------------------|
-| `NO_COLOR`       | Forces *no color* output                          | `NO_COLOR=1 node app.js` |
-| `FORCE_COLOR`    | Forces color (`1`=ANSI, `2`=256, `3`=truecolor)   | `FORCE_COLOR=3 node app.js` |
-| `CLICOLOR`       | `"0"` disables color                              | `CLICOLOR=0 node app.js` |
-| `CLICOLOR_FORCE` | Non-`"0"` value enables color even if not a TTY   | `CLICOLOR_FORCE=1 node app.js` |
-| `TERM`           | Terminal type, can increase/decrease support      | `TERM=xterm-256color`    |
-| `COLORTERM`      | `'truecolor'` or `'24bit'` enables truecolor      | `COLORTERM=truecolor`    |
-| `WT_SESSION`     | Detected for Windows Terminal (enables color)     |                          |
-| `CI`             | Many CI platforms default to *no color*           | `CI=1 node app.js`       |
-
-## <a id="5"></a>Colorino vs. Chalk
-
-| Feature                  | 🎨 **Colorino**            | 🖍️ **Chalk**    |
-|--------------------------|----------------------------|-----------------|
-| Out-of-box logs          | ✔ themed, all log levels   | ✘ string styling|
-| Zero-config              | ✔                          | ✘ manual, per-use|
-| Node + browser           | ✔                          | ✘ (Node only)   |
-| CSS console logs         | ✔                          | ✘               |
-| Extensible / Composable  | ✔ (via factory)            | ✘               |
-
-## <a id="6"></a>API Reference
-
-The `colorino` package exports two main items:
-
-### <a id="6-1"></a>1. `colorino` (default instance)
-
-A pre-configured, zero-setup logger instance. Just import and use.
-
-- `.log(...args)`
-- `.info(...args)`
-- `.warn(...args)`
-- `.error(...args)`
-- `.debug(...args)`
-- `.trace(...args)`
-
-### <a id="6-2"></a>2. `createColorino(palette?, options?)` (factory)
-
-A factory function to create your own customized logger instances.
-
-- `palette` (`Partial<Palette>`): An object to override default colors for specific log levels (e.g., `{ error: '#ff007b' }`).
-- `options` (`ColorinoOptions`): An object to control behavior:
-  - `disableWarnings: boolean` (default `false`): Suppress warnings on environments with no color support.
-  - `theme: 'dark' | 'light'` (default `auto`): Force a specific theme instead of auto-detecting.
-
-## <a id="7"></a>Extending Colorino
-
-Example: Add a `fatal()` logger for critical errors.
-
-Since colorino uses a factory pattern, extend it by creating your own factory that composes the base logger with additional methods:
-
-```typescript
-import { createColorino, type ColorinoOptions, type Palette } from 'colorino'
-
-// Create a factory for your custom logger
-export function createMyLogger(palette?: Partial<Palette>, options?: ColorinoOptions) {
-  // Get the base logger instance
-  const baseLogger = createColorino(palette, options)
-
-  // Define your custom method
-  function fatal(...args: unknown[]): void {
-    // Reuse the base logger's error method
-    baseLogger.error(...args)
-
-    // Add your custom behavior
-    if (typeof process !== 'undefined' && process.exit) {
-      process.exit(1)
-    }
-  }
-
-  // Return a new object with all base methods + your custom ones
-  // This preserves type safety and the original API
-  return {
-    ...baseLogger,
-    fatal,
-  }
-}
-```
-
-Usage:
-
-```typescript
-const logger = createMyLogger({ error: '#d92626' })
-
-logger.info('Starting!')
-logger.fatal('Missing config: Exiting')
-```
-
-### <a id="7-1"></a>Why This Pattern?
-
-- **Composition > Inheritance**: No fragile base class problems
-- **Type Safe**: TypeScript infers the return type correctly
-- **Future Proof**: Works even if colorino's internal implementation changes
-- **Clean**: No messing with `super()` or constructor parameters
-- **Composable**: You can layer multiple extensions
-
-## <a id="8"></a>Contributing
-
-We welcome contributions! Here's exactly how to get started:
-
-1. **Setup**
-    Fork the repo and install dependencies. This will also set up Git hooks via `husky`.
-
-    ```bash
-    git clone https://github.com/simwai/colorino.git
-    cd colorino
-    npm install
-    ```
-
-2. **Development Workflow**
-    Create a branch for your feature or fix.
-
-    ```bash
-    git checkout -b feat/my-cool-feature
-    ```
-
-3. **Running Tests**
-    We use **Vitest** for testing. Please run the full suite to ensure compatibility with both Node.js and Browsers.
-
-    ```bash
-    # Run all tests (Node + Browser)
-    npm run test:all
-    
-    # Run only Node.js tests
-    npm run test:node
-    
-    # Run only Browser tests
-    npm run test:browser
-    
-    # Watch mode with UI (great for dev!)
-    npm run test:ui
-    ```
-
-4. **Linting & Formatting**
-    We use **Oxlint** and **Oxfmt** for fast, robust linting.
-
-    ```bash
-    # Fix lint issues and format code
-    npm run format
-    ```
-
-5. **Commit Changes**
-    Commit your work. This triggers our `lint-staged` hooks to automatically lint, format, and run related tests on your staged files.
-
-    ```bash
-    git add .
-    git commit -m "feat: ✨ Add amazing new feature"
-    ```
-
-6. **Building**
-    To verify the build output (using `unbuild`):
-
-    ```bash
-    npm run build
-    ```
-
-7. **Submission**
-    Push your branch and open a Pull Request.
-
-    ```bash
-    git push origin feat/my-cool-feature
-    ```
-
-## <a id="9"></a>License
-
-[MIT](LICENSE.md)
-
----
-
-> *Note:* When running tests, browser output is simulated. Visual styling only appears in real browsers/devtools, but Colorino always routes logs correctly for every environment.
+# <a id="0"></a>🎨 Colorino
+
+**The zero-configuration, context-aware `console` logger for Node.js and the browser.**
+
+Colorino automatically adapts its palette to your terminal or browser DevTools theme.
+
+# <a id="0"></a><a id="0"></a>
+
+- [Why use Colorino?](#1)
+- [Features](#2)
+- [Installation](#3)
+- [Usage](#4)
+  - [Quick Start](#4-1)
+  - [Creating a Custom Logger](#4-2)
+  - [Options & Theme Overrides](#4-3)
+    - [Available Theme Presets](#4-3-1)
+    - [Examples](#4-3-2)
+  - [Customization](#4-4)
+  - [Supported Environment Variables](#4-5)
+- [Colorino vs. Chalk](#5)
+- [API Reference](#6)
+  - [1. `colorino` (default instance)](#6-1)
+  - [2. `createColorino(palette?, options?)` (factory)](#6-2)
+- [Extending Colorino](#7)
+  - [Why This Pattern?](#7-1)
+- [License](#8)
+
+<!-- Table of contents is made with https://github.com/eugene-khyst/md-toc-cli -->
+
+## <a id="1"></a>Why use Colorino?
+
+Plain `console.log` is colorless and inconsistent. Libraries like `chalk` let you style strings, but you have to decorate every message and manually manage color choices.
+
+Colorino is different: it’s a "batteries-included" logging facade with beautiful, theme-aware colors and a familiar API—no learning curve, no configuration. Instantly upgrade your logs everywhere.
+
+## <a id="2"></a>Features
+
+- 🎨 **Smart Theming:** Automatically detects *dark/light* mode and uses a coordinated color palette.
+- 🤝 **Familiar API:** If you know `console.log`, you already know Colorino: all standard log levels are supported.
+- 🔀 **Environment-Aware:** Works in **Node.js** (ANSI color and truecolor) and all major **Browsers** (CSS styles).
+- ⚡️ **Fast, Lightweight:** Minimal dependencies, works great in modern frameworks and CLIs.
+- 🔒 **Robust:** Handles bad inputs and weird environments safely.
+- 🛠️ **Customizable:** Override individual log colors for your own branding.
+
+## <a id="3"></a>Installation
+
+```bash
+npm install colorino
+```
+
+## <a id="4"></a>Usage
+
+### <a id="4-1"></a>Quick Start
+
+Just import the default instance and log away!
+
+```typescript
+import { colorino } from 'colorino'
+
+// All log levels automatically themed
+colorino.error('A critical error!')
+colorino.warn('A warning message.')
+colorino.info('Useful info logging.')
+colorino.log('A plain log.')
+colorino.debug('Debug with objects:', { x: 5, y: 9 })
+colorino.trace('Tracing app start...')
+```
+
+### <a id="4-2"></a>Creating a Custom Logger
+
+Need your own colors or different settings?
+Use the factory to create as many loggers as you want (each with its own palette and options):
+
+```typescript
+import { createColorino } from 'colorino'
+
+const myLogger = createColorino(
+  { // Palette (partial)
+    error: '#ff007b',
+    info: '#3498db'
+  },
+  { disableWarnings: true } // Options (see below)
+)
+myLogger.error('Critical!')
+myLogger.info('Rebranded info!')
+```
+
+### <a id="4-3"></a>Options & Theme Overrides
+
+`createColorino(palette?, options?)` accepts:
+
+| Option            | Type                           | Default | Description                                                                    |
+|-------------------|--------------------------------|---------|--------------------------------------------------------------------------------|
+| `disableWarnings` | `boolean`                      | `false` | Suppress warnings when color support can't be detected or is disabled.         |
+| `theme`           | `ThemeOption` (see below)      | `'auto'`| Control the active color theme or force a specific mode.                       |
+
+**`theme` accepts three types of values:**
+
+1. **`'auto'`** (Default): Automatically detects your terminal or browser theme (dark/light) and applies the matching default preset.
+2. **`'dark' | 'light'`**: Forces the logger into a specific mode using the default preset for that mode.
+3. **`ThemeName`**: Forces a specific built-in palette (e.g., `'dracula'`).
+
+#### <a id="4-3-1"></a>Available Theme Presets
+
+Pass any of these names to the `theme` option to use a specific palette:
+
+| Theme Name           | Type            | Description                                      |
+|----------------------|-----------------|--------------------------------------------------|
+| `'dracula'`          | **Dark** (High) | Vibrant pinks, purples, and cyans.               |
+| `'catppuccin-mocha'` | **Dark** (Low)  | *Default Dark.* Soothing pastel colors.          |
+| `'github-light'`     | **Light** (High)| *Default Light.* Clean, sharp, high-contrast.    |
+| `'catppuccin-latte'` | **Light** (Low) | Warm, cozy light mode with soft colors.          |
+
+#### <a id="4-3-2"></a>Examples
+
+**1. Force a specific mode (uses defaults):**
+Useful for CI/CD or environments where detection fails.
+
+```typescript
+// Forces the default dark theme (Catppuccin Mocha)
+const darkLogger = createColorino({}, { theme: 'dark' })
+```
+
+**2. Use a specific preset:**
+Instant branding with zero configuration.
+
+```typescript
+// Forces the Dracula palette
+const draculaLogger = createColorino({}, { theme: 'dracula' })
+```
+
+**3. Customize a preset:**
+Overlay your own colors on top of a built-in theme.
+
+```typescript
+// Use GitHub Light but with a custom error color
+const myLogger = createColorino(
+  { error: '#ff007b' }, 
+  { theme: 'github-light' }
+)
+```
+
+> **Tip:**
+> Forcing `'dark'` or `'light'` bypasses automatic theming, ensuring predictable colors in environments with unknown or unsupported theme detection (like some CI pipelines, dumb terminals, or minimal browsers).
+
+### <a id="4-4"></a>Customization
+
+Use your brand colors by passing a partial palette to the `createColorino` factory. Any log levels you don't specify will use the smart theme defaults.
+
+```typescript
+import { createColorino } from 'colorino'
+
+// Custom error color; others use theme defaults
+const myLogger = createColorino({ error: '#ff007b' })
+
+myLogger.error('Oh no!') // Uses your custom color
+myLogger.info('Still styled by theme.') // Uses the default theme color
+```
+
+### <a id="4-5"></a>Supported Environment Variables
+
+Colorino auto-detects your environment and color support, but you can override behavior using these standard environment variables (compatible with Chalk):
+
+| Variable         | Effect                                            | Example                  |
+|------------------|---------------------------------------------------|--------------------------|
+| `NO_COLOR`       | Forces *no color* output                          | `NO_COLOR=1 node app.js` |
+| `FORCE_COLOR`    | Forces color (`1`=ANSI, `2`=256, `3`=truecolor)   | `FORCE_COLOR=3 node app.js` |
+| `CLICOLOR`       | `"0"` disables color                              | `CLICOLOR=0 node app.js` |
+| `CLICOLOR_FORCE` | Non-`"0"` value enables color even if not a TTY   | `CLICOLOR_FORCE=1 node app.js` |
+| `TERM`           | Terminal type, can increase/decrease support      | `TERM=xterm-256color`    |
+| `COLORTERM`      | `'truecolor'` or `'24bit'` enables truecolor      | `COLORTERM=truecolor`    |
+| `WT_SESSION`     | Detected for Windows Terminal (enables color)     |                          |
+| `CI`             | Many CI platforms default to *no color*           | `CI=1 node app.js`       |
+
+## <a id="5"></a>Colorino vs. Chalk
+
+| Feature                  | 🎨 **Colorino**            | 🖍️ **Chalk**    |
+|--------------------------|----------------------------|-----------------|
+| Out-of-box logs          | ✔ themed, all log levels   | ✘ string styling|
+| Zero-config              | ✔                          | ✘ manual, per-use|
+| Node + browser           | ✔                          | ✘ (Node only)   |
+| CSS console logs         | ✔                          | ✘               |
+| Extensible / Composable  | ✔ (via factory)            | ✘               |
+
+## <a id="6"></a>API Reference
+
+The `colorino` package exports two main items:
+
+### <a id="6-1"></a>1. `colorino` (default instance)
+
+A pre-configured, zero-setup logger instance. Just import and use.
+
+- `.log(...args)`
+- `.info(...args)`
+- `.warn(...args)`
+- `.error(...args)`
+- `.debug(...args)`
+- `.trace(...args)`
+
+### <a id="6-2"></a>2. `createColorino(palette?, options?)` (factory)
+
+A factory function to create your own customized logger instances.
+
+- `palette` (`Partial<Palette>`): An object to override default colors for specific log levels (e.g., `{ error: '#ff007b' }`).
+- `options` (`ColorinoOptions`): An object to control behavior:
+  - `disableWarnings: boolean` (default `false`): Suppress warnings on environments with no color support.
+  - `theme: 'dark' | 'light'` (default `auto`): Force a specific theme instead of auto-detecting.
+
+## <a id="7"></a>Extending Colorino
+
+Example: Add a `fatal()` logger for critical errors.
+
+Since colorino uses a factory pattern, extend it by creating your own factory that composes the base logger with additional methods:
+
+```typescript
+import { createColorino, type ColorinoOptions, type Palette } from 'colorino'
+
+// Create a factory for your custom logger
+export function createMyLogger(palette?: Partial<Palette>, options?: ColorinoOptions) {
+  // Get the base logger instance
+  const baseLogger = createColorino(palette, options)
+
+  // Define your custom method
+  function fatal(...args: unknown[]): void {
+    // Reuse the base logger's error method
+    baseLogger.error(...args)
+
+    // Add your custom behavior
+    if (typeof process !== 'undefined' && process.exit) {
+      process.exit(1)
+    }
+  }
+
+  // Return a new object with all base methods + your custom ones
+  // This preserves type safety and the original API
+  return {
+    ...baseLogger,
+    fatal,
+  }
+}
+```
+
+Usage:
+
+```typescript
+const logger = createMyLogger({ error: '#d92626' })
+
+logger.info('Starting!')
+logger.fatal('Missing config: Exiting')
+```
+
+### <a id="7-1"></a>Why This Pattern?
+
+- **Composition > Inheritance**: No fragile base class problems
+- **Type Safe**: TypeScript infers the return type correctly
+- **Future Proof**: Works even if colorino's internal implementation changes
+- **Clean**: No messing with `super()` or constructor parameters
+- **Composable**: You can layer multiple extensions
+
+## <a id="8"></a>License
+
+[MIT](LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colorino",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A super simple colorized logger that gets the most out of your terminal",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
+    "generate-readme-toc": "md-toc-cli -i README.md",
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",
     "version:major": "npm version major",
@@ -69,6 +70,7 @@
     "@vitest/ui": "^4.0.15",
     "husky": "^9.0.0",
     "lint-staged": "^15.2.0",
+    "md-toc-cli": "^3.1.1",
     "oxfmt": "^0.9.0",
     "oxlint": "^0.2.0",
     "playwright": "^1.57.0",