@vanilla-bean/log 7.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 justfatlard
+
+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,311 @@
+# Log
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Zero-dependency console logging with tags, verbosity control, and unlimited custom log levels.
+
+## Why Log
+
+Log follows Unix philosophy: do logging well, let the system handle output routing. Writes to stdout as plain text; containers, process supervisors, and log tails handle the rest.
+
+- Zero runtime dependencies
+- Custom methods (`log.success()`, `log.database()`) alongside native console methods, no configuration needed
+- Tagged loggers, verbosity filtering, color, and global registry in ~1KB, easy to read, easy to fork
+
+## Installation
+
+```bash
+npm install @vanilla-bean/log
+# or
+bun add @vanilla-bean/log
+```
+
+## Quick Start
+
+Create tagged loggers that share instances and support unlimited custom methods:
+
+```javascript
+import Log from '@vanilla-bean/log';
+
+// Create tagged logger instances
+const api = new Log({ tag: 'api', verbosity: 2, color: true });
+const db = new Log({ tag: 'database', verbosity: 1 });
+
+// Use all console methods
+api.info('Server started');
+api.warn('High memory usage');
+api.error('Connection failed');
+
+// Custom methods work automatically
+api.success('Request completed');
+db.query('SELECT * FROM users');
+
+// Verbosity-gated calls: log(n)('msg') shows when logger verbosity > n
+api(1)('Debug info'); // shows when verbosity > 1 (visible here, verbosity is 2)
+api(3)('Trace data'); // shows when verbosity > 3 (hidden here, verbosity is 2)
+
+// log('msg') is shorthand for log(0)('msg') — shows when verbosity > 0
+api('Request received');
+```
+
+## Core Features
+
+### Tagged Logger Registry
+
+Identical tags return the same logger instance, preventing duplicates and enabling cross-module coordination:
+
+```javascript
+// Module A
+const log = new Log({ tag: 'app', verbosity: 1 });
+
+// Module B - gets same logger instance
+const log = new Log({ tag: 'app' }); // Inherits verbosity: 1
+
+// Access any logger globally
+import { loggers } from '@vanilla-bean/log';
+loggers.app.options.verbosity = 3; // Updates everywhere
+```
+
+> **Note:** Calling `new Log()` without a tag uses the shared `__default` singleton. Two unrelated modules both doing `new Log()` will share the same logger instance and options. Always pass a tag when you want an independent logger.
+
+### Verbosity Control
+
+The primary form is `log(n)('msg')`: logs when the logger's verbosity is greater than `n`, silent otherwise. Calling `log('msg')` directly is shorthand for `log(0)('msg')`: shows when verbosity is greater than 0.
+
+```javascript
+const log = new Log({ verbosity: 3 });
+
+log(1)('High priority');     // shows when verbosity > 1
+log(2)('Debug info');        // shows when verbosity > 2
+log(5)('Trace data');        // shows when verbosity > 5 (hidden here)
+
+log('Shorthand');            // shorthand for log(0)('Shorthand') — shows when verbosity > 0
+
+// Works the same on any method
+log.warn(1)('Important warning');
+log.error(0)('Critical error');
+```
+
+> **Gotcha:** A lone number is always treated as a verbosity level, never as a message. `log(42)` returns a curried function; it does not log the number 42. To log a bare number, pass a second argument: `log(42, '')`.
+
+### Unlimited Log Methods
+
+Create unlimited custom log methods alongside native console methods:
+
+```javascript
+const log = new Log({ tag: 'app' });
+
+// Native console methods
+log.info('Information');
+log.warn('Warning');
+log.error('Error');
+log.debug('Debug data');
+
+// Custom methods work automatically
+log.success('Operation completed');
+log.database('Query executed');
+log.network('Request sent');
+log.cache('Cache hit');
+log.security('Auth failed');
+```
+
+### Color Output
+
+Add color support for enhanced terminal readability:
+
+```javascript
+const log = new Log({ color: true });
+
+log.info('Blue text'); // Built-in blue
+log.warn('Yellow text'); // Built-in yellow
+log.error('Red text'); // Built-in red
+
+// Custom colors per tag or method
+const colorLog = new Log({
+	color: true,
+	colorMap: {
+		success: '\x1b[32m', // Green
+		critical: '\x1b[91m', // Bright red
+	},
+});
+```
+
+## Configuration Options
+
+```javascript
+const log = new Log({
+	tag: 'myapp',       // Logger identifier (omit to share the global __default singleton)
+	verbosity: 0,       // Default: 0 (silent). log(n)() shows when n < verbosity; log('msg') shows when verbosity > 0
+	color: false,       // Disable color output
+	silentTag: false,   // Hide [tag] prefix
+	methodTag: false,   // Show [method] label for native methods (info/warn/error); custom methods always show their label
+	colorMap: {},       // Custom ANSI color codes
+});
+```
+
+## Advanced Usage
+
+### Dynamic Configuration
+
+```javascript
+const log = new Log({ tag: 'api', verbosity: 1 });
+
+log(2)('This is hidden');
+
+// Increase verbosity at runtime
+log.options.verbosity = 3;
+
+log(2)('Now visible');
+```
+
+### Tag Management
+
+```javascript
+const log = new Log({ tag: 'init' });
+log('Starting up');
+
+// Switch to different tag
+log.setTag('runtime');
+log('Now running');
+```
+
+### Global Configuration
+
+Set process-wide defaults before creating loggers, or map custom methods to console methods:
+
+```javascript
+import Log, { setDefaults, setMethodMap } from '@vanilla-bean/log';
+
+setDefaults({ verbosity: 2, color: true });
+setMethodMap({ critical: 'error', trace: 'debug' });
+
+const log = new Log({ tag: 'app' }); // inherits verbosity: 2, color: true
+log.critical('Fatal error');          // routes to console.error
+```
+
+### Cross-Module Coordination
+
+```javascript
+// logger.js
+import Log from '@vanilla-bean/log';
+export const appLog = new Log({ tag: 'app', verbosity: 1 });
+
+// module1.js
+import { appLog } from './logger.js';
+appLog.info('Module 1 loaded');
+
+// module2.js
+import { loggers } from '@vanilla-bean/log';
+loggers.app.warn('Module 2 warning'); // Same logger instance
+```
+
+## Production Deployment
+
+### Log Aggregation
+
+Log writes human-readable text to stdout. For log aggregation pipelines that expect JSON (ELK, Fluentd, Datadog), you'll need a JSON logger. Log is the right tool when a human is reading the output — development, debugging, process supervision, or simple production tails.
+
+For plain-text pipelines, disable colors and keep tags for pattern matching:
+
+```javascript
+const log = new Log({
+	tag: 'api',
+	silentTag: false, // keep [api] prefix for grep/awk
+	color: false,     // no ANSI codes in log files
+});
+
+log.info('user_login', { userId: 123, ip: '1.2.3.4' });
+// Output: [api] user_login { userId: 123, ip: '1.2.3.4' }
+```
+
+### Environment Configuration
+
+```javascript
+const log = new Log({
+	tag: process.env.SERVICE_NAME || 'app',
+	verbosity: process.env.LOG_LEVEL || 1,
+	color: process.env.NODE_ENV === 'development',
+});
+```
+
+## Comparison
+
+| Feature           | Log                   | Winston                | Pino             | Debug       |
+| ----------------- | --------------------- | ---------------------- | ---------------- | ----------- |
+| Bundle Size       | ~1KB                  | ~2MB                   | ~1MB             | ~8KB        |
+| Dependencies      | 0                     | Many                   | Some             | 1           |
+| Log Levels        | Unlimited             | 6 + custom             | 6 standard       | 1           |
+| Verbosity Control | ✓ Core                | ✓                      | ✓                | Environment |
+| Tags/Namespaces   | ✓ Singleton           | ✓                      | ✓                | ✓           |
+| Transports        | stdout only           | 20+ built-in           | Plugin ecosystem | stdout only |
+| Container-Native  | ✓                     | Configuration required | ✓                | ✓           |
+
+## API Reference
+
+### Constructor
+
+```typescript
+new Log(options?: {
+  tag?: string;           // Default: '__default'
+  verbosity?: number;     // Default: 0
+  color?: boolean;        // Default: false
+  silentTag?: boolean;    // Default: false
+  methodTag?: boolean;    // Default: false — shows [method] for native methods; custom methods always show it
+  colorMap?: object;      // Custom colors
+})
+```
+
+### Logger Methods
+
+```typescript
+// Primary form: verbosity-gated, curried
+log(verbosity: number): (message: any, ...args: any[]) => void;
+log.methodName(verbosity: number): (message: any, ...args: any[]) => void;
+
+// Shorthand: equivalent to log(0)('msg') — shows when verbosity > 0
+log(message: any, ...args: any[]): void;
+log.methodName(message: any, ...args: any[]): void;
+```
+
+### Instance Methods
+
+```typescript
+log.setTag(newTag: string): void;
+log.options: object;  // Mutable configuration
+```
+
+### Global Configuration
+
+```typescript
+setDefaults(options: Partial<LogOptions>): void;
+setMethodMap(map: Record<string, string>): void;
+```
+
+### Exports
+
+```typescript
+import Log, { loggers, defaults, methodMap, setDefaults, setMethodMap } from '@vanilla-bean/log';
+```
+
+## Contributing
+
+Contributions welcome! Submit Pull Requests for improvements. Open issues first for major changes.
+
+### Development Setup
+
+```bash
+# Clone and setup
+git clone https://github.com/fatlard1993/log.git
+cd log
+bun install
+
+# Development workflow
+bun test           # Run tests
+bun run demo       # Run examples
+bun run lint       # Check code style
+bun test --watch   # Watch mode
+```
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.

package/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './src/log';
+export * from './src/log';

package/index.js

@@ -0,0 +1,2 @@
+export { default } from './src/log';
+export * from './src/log';

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@vanilla-bean/log",
+	"version": "7.0.0",
+	"exports": {
+		".": "./index.js"
+	},
+	"types": "./index.d.ts",
+	"files": [
+		"/src/**/*",
+		"!/src/**/*.test.js",
+		"index.js",
+		"index.d.ts"
+	],
+	"description": "A console log wrapper with tags, colors, and verbosity",
+	"author": "justfatlard",
+	"license": "MIT",
+	"scripts": {
+		"demo": "bun ./demo/index.js",
+		"lint": "bun --bun eslint",
+		"lint:fix": "bun --bun eslint --fix",
+		"format": "bun run lint:fix && bun --bun prettier --write . | grep -q unchanged",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"version": "npm version"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fatlard1993/log.git"
+	},
+	"bugs": {
+		"url": "https://github.com/fatlard1993/log/issues"
+	},
+	"homepage": "https://github.com/fatlard1993/log#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {},
+	"devDependencies": {
+		"@eslint/compat": "^1.4.1",
+		"@eslint/js": "^9.39.4",
+		"bun-types": "^1.3.14",
+		"eslint": "^9.39.4",
+		"eslint-plugin-compat": "^7.0.2",
+		"eslint-plugin-import": "^2.32.0",
+		"eslint-plugin-jsdoc": "^63.0.2",
+		"eslint-plugin-spellcheck": "0.0.20",
+		"eslint-plugin-unicorn": "^64.0.0",
+		"eslint-plugin-write-good-comments": "^0.2.0",
+		"globals": "^16.5.0",
+		"prettier": "^3.8.3"
+	}
+}

package/src/log.d.ts

@@ -0,0 +1,57 @@
+export interface LogOptions {
+	/** Unique identifier for this logger */
+	tag?: string;
+	/** log(n) calls show when n < verbosity; direct calls show when verbosity > 0 */
+	verbosity?: number;
+	/** Enable ANSI color output */
+	color?: boolean;
+	/** Suppress [tag] prefix in output */
+	silentTag?: boolean;
+	/** Show [method] label for native console methods; custom methods always show their label */
+	methodTag?: boolean;
+	/** Custom ANSI color code mappings keyed by tag or method name */
+	colorMap?: Record<string, string>;
+}
+
+export type ResolvedLogOptions = Required<LogOptions>;
+
+/**
+ * Callable directly or with a verbosity number for curried calls:
+ *   log.info('message')     → immediate log
+ *   log.info(2)('message')  → logs only when logger verbosity > 2
+ */
+export interface LogMethod {
+	(verbosity: number): (...args: any[]) => void;
+	(...args: any[]): void;
+}
+
+/** Logger instance returned by `new Log()` */
+export interface Logger extends LogMethod {
+	options: ResolvedLogOptions;
+	setTag(newTag: string): void;
+	info: LogMethod;
+	warn: LogMethod;
+	error: LogMethod;
+	debug: LogMethod;
+	/** Any custom method name works via Proxy */
+	[method: string]: any;
+}
+
+interface LogConstructor {
+	new(options?: LogOptions): Logger;
+}
+
+declare const Log: LogConstructor;
+export default Log;
+
+/** Global default options applied to all new logger instances */
+export declare const defaults: ResolvedLogOptions;
+/** Global map of custom method names to console method names */
+export declare const methodMap: Record<string, string>;
+/** Registry of all tagged logger instances */
+export declare const loggers: Record<string, Logger>;
+
+/** Merges options into the global defaults applied to all new logger instances */
+export declare function setDefaults(options: Partial<ResolvedLogOptions>): void;
+/** Merges entries into the global method map used by all loggers */
+export declare function setMethodMap(map: Record<string, string>): void;

package/src/log.js

@@ -0,0 +1,193 @@
+/**
+ * Stores all logger instances indexed by tag name.
+ * @type {Record<string, Function>}
+ */
+export const loggers = {};
+
+/**
+ * Default configuration options for all logger instances.
+ * @type {object}
+ * @property {number} verbosity - Verbosity threshold; log(n) shows when n < verbosity, direct calls show when verbosity > 0
+ * @property {boolean} color - Enable ANSI color output
+ * @property {boolean} silentTag - Suppress tag labels in output
+ * @property {boolean} methodTag - Show [method] label for native console methods; custom methods always show their label
+ * @property {string} tag - Default tag identifier
+ * @property {Record<string, string>} colorMap - Custom ANSI color code mappings
+ */
+export const defaults = {
+	verbosity: 0,
+	color: false,
+	silentTag: false,
+	methodTag: false,
+	tag: '__default',
+	colorMap: {},
+};
+
+/**
+ * Maps custom method names to console methods.
+ * @type {Record<string, string>}
+ */
+export const methodMap = {};
+
+/**
+ * Default ANSI color codes for console output.
+ * @type {Record<string, string>}
+ */
+const DEFAULT_COLOR_MAP = {
+	__reset: '\u001B[0m',
+	info: '\u001B[34m',
+	warn: '\u001B[33m',
+	error: '\u001B[31m',
+};
+
+/**
+ * Creates flexible logging utility with tagging, verbosity levels, and color output.
+ * Implements singleton pattern where instances with identical tags share the same logger.
+ */
+class Log {
+	/**
+	 * Creates new Log instance or returns existing instance for duplicate tags.
+	 * @param {object} [options] - Configuration options
+	 * @param {string} [options.tag] - Unique identifier for this logger
+	 * @param {number} [options.verbosity] - Verbosity threshold to display messages
+	 * @param {boolean} [options.color] - Enable ANSI color output
+	 * @param {boolean} [options.silentTag] - Suppress tag labels from output
+	 * @param {boolean} [options.methodTag] - Show [method] label for native console methods; custom methods always show their label
+	 * @param {Record<string, string>} [options.colorMap] - Custom ANSI color code mappings
+	 * @returns {Function} Proxy-wrapped logger function with dynamic method access
+	 */
+	constructor(options = {}) {
+		this.options = { ...defaults, ...options };
+
+		const { tag } = this.options;
+
+		if (loggers[tag]) {
+			loggers[tag].options = { ...loggers[tag].options, ...options };
+
+			return loggers[tag];
+		}
+
+		this._explicit = options;
+
+		/**
+		 * Proxy that intercepts property access to dynamically create logger methods.
+		 * Enables calling log.info(), log.warn(), etc. without pre-defining methods.
+		 */
+		const defaultLogger = new Proxy(this.makeLogger('log'), {
+			get: (target, key) => {
+				if (typeof key !== 'string') return Reflect.get(target, key);
+				return Reflect.get(target, key) ?? this[key] ?? this.makeLogger(key);
+			},
+		});
+
+		defaultLogger.options = this.options;
+
+		loggers[tag] = defaultLogger;
+
+		return defaultLogger;
+	}
+
+	/**
+	 * Creates logger function for specified console method.
+	 * @param {string} method - Console method name (log, info, warn, error, etc.)
+	 * @returns {Function} Logger function supporting direct calls and verbosity-specific curried calls
+	 */
+	makeLogger(method) {
+		const { tag } = this.options;
+
+		return (...args) => {
+			const {
+				colorMap,
+				silentTag,
+				methodTag,
+				verbosity,
+				color: useColor,
+			} = loggers[tag]?.options || this.options;
+
+			const isVerbosityCall = args.length === 1 && typeof args[0] === 'number';
+			const thisVerbosity = isVerbosityCall ? args.shift() : 0;
+			if (!isVerbosityCall && args.length === 0) return;
+			const willShow = !!console && thisVerbosity < verbosity;
+			const isNativeConsoleMethod = !!console && typeof console[method] === 'function';
+			const resolvedMethod = isNativeConsoleMethod ? method : (methodMap[method] || 'log');
+
+			let colorReset;
+
+			if (willShow) {
+				const colors = { ...DEFAULT_COLOR_MAP, ...colorMap };
+				const color = colors[tag] || colors[method] || colors[methodMap[method]];
+
+				if (!silentTag) {
+					let tagText = '';
+
+					if (tag !== '__default') tagText += `[${tag}]`;
+					if (methodTag || !isNativeConsoleMethod) tagText += `[${method}]`;
+
+					if (tagText) args.unshift(tagText);
+				}
+
+				if (useColor && color) {
+					args.unshift(color);
+					colorReset = colors.__reset;
+					if (!isVerbosityCall) args.push(colorReset);
+				} else if (method === 'error') {
+					args.unshift('[ERROR]');
+				}
+			}
+
+			if (isVerbosityCall) {
+				if (!willShow || !console) return () => {};
+				return colorReset
+					? (...messageArgs) => console[resolvedMethod](...args, ...messageArgs, colorReset)
+					: (...messageArgs) => console[resolvedMethod](...args, ...messageArgs);
+			}
+
+			if (willShow) console[resolvedMethod](...args);
+		};
+	}
+
+	/**
+	 * Updates logger tag and relocates instance in global registry.
+	 * When newTag already exists, options are merged: constructor-time options take priority over the
+	 * existing logger's options. Runtime mutations to this.options after construction are not tracked
+	 * and may be overwritten by the existing logger's values during the merge.
+	 * @param {string} newTag - New tag identifier
+	 */
+	setTag(newTag) {
+		const { tag } = this.options;
+
+		if (newTag === tag) return;
+
+		if (loggers[newTag]) {
+			Object.assign(this.options, loggers[newTag].options, this._explicit);
+		}
+
+		loggers[newTag] = loggers[tag];
+		this.options.tag = newTag;
+
+		const { colorMap } = this.options;
+		if (colorMap[tag]) {
+			colorMap[newTag] = colorMap[tag];
+		}
+
+		delete loggers[tag];
+	}
+}
+
+/**
+ * Merges options into the global defaults applied to all new logger instances.
+ * @param {Partial<typeof defaults>} options - Default settings to apply
+ */
+export function setDefaults(options) {
+	Object.assign(defaults, options);
+}
+
+/**
+ * Merges entries into the global method map used by all loggers.
+ * @param {Record<string, string>} map - Custom method names mapped to console methods
+ */
+export function setMethodMap(map) {
+	Object.assign(methodMap, map);
+}
+
+export default Log;