colorino 0.1.0

package/LICENSE.MD

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 simwai
+
+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

@@ -0,0 +1,239 @@
+# 🎨 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.
+
+***
+
+## Table of Contents
+
+- [Why use Colorino?](#why-use-colorino)
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Quick Start](#quick-start)
+  - [Creating a Custom Logger](#creating-a-custom-logger)
+  - [Options & Theme Overrides](#options--theme-overrides)
+  - [Customization](#customization)
+  - [Supported Environment Variables](#supported-environment-variables)
+- [Colorino vs. Chalk](#colorino-vs-chalk)
+- [API Reference](#api-reference)
+- [Extending Colorino](#extending-colorino)
+- [Contributing](#contributing)
+- [License](#license)
+
+***
+
+## 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.
+
+***
+
+## 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.
+
+***
+
+## Installation
+
+```sh
+npm install colorino
+# or
+yarn add colorino
+```
+
+***
+
+## Usage
+
+### 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...')
+```
+
+***
+
+### 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!')
+```
+
+***
+
+### Options & Theme Overrides
+
+Both `createColorino(palette?, options?)` and `new Colorino(palette?, options?)` accept:
+
+| Option             | Type                  | Default     | Description                                                                    |
+|--------------------|----------------------|-------------|--------------------------------------------------------------------------------|
+| `disableWarnings`  | `boolean`            | `false`     | Suppress warnings when color support can't be detected or is disabled           |
+| `theme`            | `'dark' \| 'light' \| 'unknown'` | *(auto)*      | Override auto-theme detection: force `'dark'` or `'light'` for palette selection |
+
+#### Example: Forcing a theme
+
+If the auto-contrast and theme detection doesn't work (e.g., in some CI/CD, headless, or basic terminals), **force the color scheme**:
+
+```typescript
+import { createColorino } from 'colorino'
+
+// Force dark palette regardless of environment
+const forcedDarkLogger = createColorino({}, { theme: 'dark' })
+
+forcedDarkLogger.info('This will always use dark-friendly colors.')
+```
+
+> **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).
+
+***
+
+### Customization
+
+Use your brand colors or tweak log levels as desired. Unspecified colors use the smart palette.
+
+```typescript
+import { Colorino } from 'colorino'
+
+// Custom error color; others use theme defaults
+const myLogger = new Colorino({ error: '#ff007b' })
+
+myLogger.error('Oh no!')
+myLogger.info('Still styled by theme.')
+```
+
+***
+
+### 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`       |
+
+***
+
+## 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  | ✔                                | ✘                |
+| Extendable class  | ✔                                | ✘                |
+
+***
+
+## API Reference
+
+### colorino (default export)
+
+Preconfigured logger.
+
+- `.log(...args)`
+- `.info(...args)`
+- `.warn(...args)`
+- `.error(...args)`
+- `.debug(...args)`
+- `.trace(...args)`
+
+### new Colorino(palette?, options?)
+
+- `palette` (`Partial<Palette>`): Override colors for log types.
+- `options` (`{ disableWarnings?: boolean; theme?: 'dark' | 'light' | 'unknown' }`): Control warnings and explicit theme.
+
+***
+
+## Extending Colorino
+
+Example: Add a `fatal()` logger for critical errors.
+
+```typescript
+import { Colorino, type Palette } from 'colorino'
+
+export class MyLogger extends Colorino {
+  constructor(palette?: Partial<Palette>, options?: { disableWarnings?: boolean }) {
+    super(palette, options)
+  }
+  public fatal(...args: unknown[]): void {
+    super.error(...args)
+    if (typeof process !== 'undefined' && process.exit) {
+      process.exit(1)
+    }
+  }
+}
+```
+
+Usage:
+
+```typescript
+const logger = new MyLogger({ error: '#d92626' })
+
+logger.info('Starting!')
+logger.fatal('Missing config: Exiting')
+```
+
+***
+
+## Contributing
+
+PRs and issues welcome!
+
+1. Fork the repo.
+2. Make a branch (`git checkout -b feat/my-feature`)
+3. Add your change, with tests.
+4. Run `npm test` to ensure all tests pass in both Node and browser.
+5. Open a Pull Request.
+
+***
+
+## License
+
+MIT
+
+***
+
+> *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.

package/dist/browser.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+const theme = require('./shared/colorino.BCUN0J9y.cjs');
+require('neverthrow');
+
+class BrowserColorSupportDetector {
+  constructor(_window, _navigator, _overrideTheme) {
+    this._window = _window;
+    this._navigator = _navigator;
+    this._overrideTheme = _overrideTheme;
+  }
+  isBrowserEnv() {
+    return !!this._window && !!this._navigator?.userAgent;
+  }
+  getColorLevel() {
+    if (!this.isBrowserEnv()) {
+      return theme.ColorLevel.NO_COLOR;
+    }
+    const userAgent = this._navigator.userAgent.toLowerCase();
+    if (userAgent.includes("chrome")) return theme.ColorLevel.ANSI256;
+    if (userAgent.includes("firefox")) return theme.ColorLevel.ANSI256;
+    return theme.ColorLevel.ANSI256;
+  }
+  getTheme() {
+    if (this._overrideTheme) {
+      return this._overrideTheme;
+    }
+    if (!this.isBrowserEnv()) {
+      return "unknown";
+    }
+    if (this._window.matchMedia("(prefers-color-scheme: dark)").matches) {
+      return "dark";
+    }
+    if (this._window.matchMedia("(prefers-color-scheme: light)").matches) {
+      return "light";
+    }
+    return "unknown";
+  }
+}
+
+function createColorino(palette, options = {}) {
+  const validator = new theme.InputValidator();
+  const browserDetector = new BrowserColorSupportDetector(
+    window,
+    navigator,
+    options.theme
+  );
+  return new theme.Colorino(
+    palette,
+    validator,
+    browserDetector,
+    // Always use browser detector
+    void 0,
+    // Node detector is never available
+    options
+  );
+}
+const colorino = createColorino(theme.darkDraculaPalette);
+
+exports.colorino = colorino;
+exports.createColorino = createColorino;

package/dist/browser.d.cts

@@ -0,0 +1,7 @@
+import { P as Palette, C as ColorinoOptions, a as Colorino } from './shared/colorino.V5I9NhYv.cjs';
+import 'neverthrow';
+
+declare function createColorino(palette: Palette, options?: ColorinoOptions): Colorino;
+declare const colorino: Colorino;
+
+export { colorino, createColorino };

package/dist/browser.d.mts

@@ -0,0 +1,7 @@
+import { P as Palette, C as ColorinoOptions, a as Colorino } from './shared/colorino.V5I9NhYv.mjs';
+import 'neverthrow';
+
+declare function createColorino(palette: Palette, options?: ColorinoOptions): Colorino;
+declare const colorino: Colorino;
+
+export { colorino, createColorino };

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+import { P as Palette, C as ColorinoOptions, a as Colorino } from './shared/colorino.V5I9NhYv.js';
+import 'neverthrow';
+
+declare function createColorino(palette: Palette, options?: ColorinoOptions): Colorino;
+declare const colorino: Colorino;
+
+export { colorino, createColorino };

package/dist/browser.mjs

@@ -0,0 +1,58 @@
+import { C as ColorLevel, a as Colorino, I as InputValidator, d as darkDraculaPalette } from './shared/colorino.xxLMfJFV.mjs';
+import 'neverthrow';
+
+class BrowserColorSupportDetector {
+  constructor(_window, _navigator, _overrideTheme) {
+    this._window = _window;
+    this._navigator = _navigator;
+    this._overrideTheme = _overrideTheme;
+  }
+  isBrowserEnv() {
+    return !!this._window && !!this._navigator?.userAgent;
+  }
+  getColorLevel() {
+    if (!this.isBrowserEnv()) {
+      return ColorLevel.NO_COLOR;
+    }
+    const userAgent = this._navigator.userAgent.toLowerCase();
+    if (userAgent.includes("chrome")) return ColorLevel.ANSI256;
+    if (userAgent.includes("firefox")) return ColorLevel.ANSI256;
+    return ColorLevel.ANSI256;
+  }
+  getTheme() {
+    if (this._overrideTheme) {
+      return this._overrideTheme;
+    }
+    if (!this.isBrowserEnv()) {
+      return "unknown";
+    }
+    if (this._window.matchMedia("(prefers-color-scheme: dark)").matches) {
+      return "dark";
+    }
+    if (this._window.matchMedia("(prefers-color-scheme: light)").matches) {
+      return "light";
+    }
+    return "unknown";
+  }
+}
+
+function createColorino(palette, options = {}) {
+  const validator = new InputValidator();
+  const browserDetector = new BrowserColorSupportDetector(
+    window,
+    navigator,
+    options.theme
+  );
+  return new Colorino(
+    palette,
+    validator,
+    browserDetector,
+    // Always use browser detector
+    void 0,
+    // Node detector is never available
+    options
+  );
+}
+const colorino = createColorino(darkDraculaPalette);
+
+export { colorino, createColorino };

package/dist/node.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+const theme = require('./shared/colorino.BCUN0J9y.cjs');
+const neverthrow = require('neverthrow');
+
+class OscThemeQuerier {
+  constructor(_stdin, _stdout, _timeout = 300, _cacheTtl = 36e5) {
+    this._stdin = _stdin;
+    this._stdout = _stdout;
+    this._timeout = _timeout;
+    this._cacheTtl = _cacheTtl;
+  }
+  cachedResult;
+  cacheTimestamp;
+  async query() {
+    if (!this._stdout.isTTY || typeof this._stdin.setRawMode !== "function") {
+      return neverthrow.err(new theme.OscQueryError("Not a TTY environment"));
+    }
+    const now = Date.now();
+    if (this.cachedResult !== void 0 && this.cacheTimestamp !== void 0 && now - this.cacheTimestamp < this._cacheTtl) {
+      return this.cachedResult;
+    }
+    const result = await this._performQuery();
+    this.cachedResult = result;
+    this.cacheTimestamp = now;
+    return result;
+  }
+  async _performQuery() {
+    return new Promise((resolve) => {
+      const originalRawMode = this._stdin.isRaw;
+      let buffer = "";
+      let isResolved = false;
+      const cleanup = () => {
+        if (isResolved) return;
+        isResolved = true;
+        clearTimeout(timer);
+        this._stdin.removeListener("data", onData);
+        this._stdin.setRawMode(originalRawMode);
+      };
+      const onData = (chunk) => {
+        buffer += chunk.toString();
+        const parseResult = this._parseResponse(buffer);
+        if (parseResult.isOk()) {
+          cleanup();
+          resolve(parseResult);
+        }
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve(
+          neverthrow.err(new theme.OscQueryError("OSC query timeout - terminal did not respond"))
+        );
+      }, this._timeout);
+      this._stdin.setRawMode(true);
+      this._stdin.on("data", onData);
+      this._stdout.write("\x1B]11;?\x1B\\");
+    });
+  }
+  _parseResponse(response) {
+    const rgbMatch = response.match(
+      /rgb:([0-9a-f]{2,4})\/([0-9a-f]{2,4})\/([0-9a-f]{2,4})/i
+    );
+    if (!rgbMatch) {
+      return neverthrow.err(new theme.OscQueryError("No valid OSC response found in buffer"));
+    }
+    const red = this._normalizeHex(rgbMatch[1]);
+    const green = this._normalizeHex(rgbMatch[2]);
+    const blue = this._normalizeHex(rgbMatch[3]);
+    const luminance = this._calculateLuminance(red, green, blue);
+    return neverthrow.ok(luminance < 0.5 ? "dark" : "light");
+  }
+  _normalizeHex(hexValue) {
+    const normalized = hexValue.padEnd(4, "0").slice(0, 2);
+    return parseInt(normalized, 16);
+  }
+  _calculateLuminance(red, green, blue) {
+    return (0.299 * red + 0.587 * green + 0.114 * blue) / 255;
+  }
+}
+
+class NodeColorSupportDetector {
+  constructor(_process, overrideTheme) {
+    this._process = _process;
+    if (!this.isNodeEnv()) return;
+    const processEnv = _process.env;
+    this._envForceColor = processEnv["FORCE_COLOR"];
+    this._envNoColor = processEnv["NO_COLOR"];
+    this._envTerm = processEnv["TERM"];
+    this._envColorTerm = processEnv["COLORTERM"];
+    this._envCliColor = processEnv["CLICOLOR"];
+    this._envCliColorForce = processEnv["CLICOLOR_FORCE"];
+    this._envWtSession = processEnv["WT_SESSION"];
+    this._isTTY = !!_process.stdout.isTTY;
+    this._overrideTheme = overrideTheme;
+    if (!this._overrideTheme && this._isTTY && typeof this._process.stdin.setRawMode === "function") {
+      this._querier = new OscThemeQuerier(
+        this._process.stdin,
+        this._process.stdout
+      );
+    }
+  }
+  _envForceColor;
+  _envTerm;
+  _envColorTerm;
+  _envNoColor;
+  _envCliColor;
+  _envCliColorForce;
+  _envWtSession;
+  _isTTY;
+  _querier;
+  _overrideTheme;
+  isNodeEnv() {
+    return typeof this._process !== "undefined";
+  }
+  getColorLevel() {
+    if (this._envNoColor !== void 0) {
+      return theme.ColorLevel.NO_COLOR;
+    }
+    if (this._envForceColor !== void 0) {
+      if (this._envForceColor === "0" || this._envForceColor === "false") {
+        return theme.ColorLevel.NO_COLOR;
+      }
+      if (this._envForceColor === "1" || this._envForceColor === "true") {
+        return theme.ColorLevel.ANSI;
+      }
+      const level = parseInt(this._envForceColor, 10);
+      if (level >= 0 && level <= 3) {
+        return level;
+      }
+      return theme.ColorLevel.ANSI;
+    }
+    const isForced = this._envCliColorForce !== void 0 && this._envCliColorForce !== "0";
+    if (!this._isTTY && !isForced) {
+      return theme.ColorLevel.NO_COLOR;
+    }
+    if (this._envTerm === "dumb") {
+      return theme.ColorLevel.NO_COLOR;
+    }
+    if (this._envColorTerm === "truecolor" || this._envColorTerm === "24bit") {
+      return theme.ColorLevel.TRUECOLOR;
+    }
+    if (this._envWtSession !== void 0) {
+      return theme.ColorLevel.TRUECOLOR;
+    }
+    if (this._envTerm) {
+      if (/^xterm-kitty$/.test(this._envTerm) || /^xterm-ghostty$/.test(this._envTerm) || /^wezterm$/.test(this._envTerm) || /-truecolor$/.test(this._envTerm)) {
+        return theme.ColorLevel.TRUECOLOR;
+      }
+      if (/-256(color)?$/i.test(this._envTerm)) {
+        return theme.ColorLevel.ANSI256;
+      }
+      if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(
+        this._envTerm
+      )) {
+        return theme.ColorLevel.ANSI;
+      }
+    }
+    if (this._envColorTerm) {
+      return theme.ColorLevel.ANSI;
+    }
+    if (this._envCliColor !== void 0 && this._envCliColor !== "0") {
+      return theme.ColorLevel.ANSI;
+    }
+    return this._isTTY ? theme.ColorLevel.ANSI : theme.ColorLevel.NO_COLOR;
+  }
+  async getTheme() {
+    if (this._overrideTheme) {
+      return this._overrideTheme;
+    }
+    if (!this.isNodeEnv() || !this._isTTY || !this._querier) {
+      return "unknown";
+    }
+    const result = await this._querier.query();
+    return result.unwrapOr("unknown");
+  }
+}
+
+function createColorino(palette, options = {}) {
+  const validator = new theme.InputValidator();
+  const nodeDetector = new NodeColorSupportDetector(process, options.theme);
+  return new theme.Colorino(
+    palette,
+    validator,
+    void 0,
+    // Browser detector is never available
+    nodeDetector,
+    // Always use node detector
+    options
+  );
+}
+const colorino = createColorino(theme.darkDraculaPalette);
+
+exports.colorino = colorino;
+exports.createColorino = createColorino;

package/dist/node.d.cts

@@ -0,0 +1,7 @@
+import { P as Palette, C as ColorinoOptions, a as Colorino } from './shared/colorino.V5I9NhYv.cjs';
+import 'neverthrow';
+
+declare function createColorino(palette: Palette, options?: ColorinoOptions): Colorino;
+declare const colorino: Colorino;
+
+export { colorino, createColorino };

package/dist/node.d.mts

@@ -0,0 +1,7 @@
+import { P as Palette, C as ColorinoOptions, a as Colorino } from './shared/colorino.V5I9NhYv.mjs';
+import 'neverthrow';
+
+declare function createColorino(palette: Palette, options?: ColorinoOptions): Colorino;
+declare const colorino: Colorino;
+
+export { colorino, createColorino };

package/dist/node.d.ts

@@ -0,0 +1,7 @@
+import { P as Palette, C as ColorinoOptions, a as Colorino } from './shared/colorino.V5I9NhYv.js';
+import 'neverthrow';
+
+declare function createColorino(palette: Palette, options?: ColorinoOptions): Colorino;
+declare const colorino: Colorino;
+
+export { colorino, createColorino };