@idlebox/logger 0.0.1

package/src/common/debug.commands.ts

@@ -0,0 +1,132 @@
+import { relative } from 'node:path';
+import { formatWithOptions, inspect } from 'node:util';
+
+const STRING_MAX_LENGTH = 128;
+
+function color_error(message: string, color: boolean) {
+	if (color) {
+		return `\x1B[38;5;9m<inspect**${message}**>\x1B[39m`;
+	} else {
+		return `<inspect**${message}**>`;
+	}
+}
+
+function options(color: boolean) {
+	return {
+		depth: 5,
+		compact: true,
+		colors: color,
+		maxArrayLength: 3,
+		maxStringLength: STRING_MAX_LENGTH,
+	};
+}
+
+export function nodeFormat(message: string, object: readonly unknown[], color: boolean): string {
+	return formatWithOptions(options(color), message, ...object);
+}
+
+export function nodeInspect(object: unknown, color: boolean): string {
+	return inspect(object, options(color));
+}
+
+function isSyncIterable(obj: unknown): obj is Iterable<unknown> {
+	return typeof obj === 'object' && obj !== null && Symbol.iterator in obj;
+}
+
+const debug_commands = {
+	inspect(object: unknown, color: boolean) {
+		return inspect(object, options(color));
+	},
+	stripe(s: unknown, color: boolean) {
+		if (typeof s !== 'string') {
+			return color_error(`can not stripe ${typeof s}`, color);
+		}
+		if (s.length > 100) {
+			if (color) {
+				return `\x1B[38;5;10m"${s.slice(0, STRING_MAX_LENGTH - 3)}..."\x1B[39m`;
+			} else {
+				return `"${s.slice(0, STRING_MAX_LENGTH - 3)}..."`;
+			}
+		} else {
+			return s;
+		}
+	},
+	list(items: unknown, color: boolean) {
+		if (!isSyncIterable(items)) {
+			return color_error(`list<> need iterable value, not ${typeof items}(${items?.constructor?.name})`, color);
+		}
+		const postfix = color ? '\x1B[0m' : '';
+		let index = 0;
+		const lines: string[] = [];
+		const prefix = color ? '\x1B[2m' : '';
+		for (const item of items) {
+			if (Array.isArray(item)) {
+				if (item.length === 2) {
+					const [key, value] = item;
+					if (typeof key === 'number') {
+						lines.push(`  - ${prefix}${item}${postfix}`);
+					} else {
+						lines.push(`  * ${prefix}${key}: ${value.toString()}${postfix}`);
+					}
+				} else {
+					return color_error(`list<> item ${index} is array with length ${item.length}, expected 2`, color);
+				}
+			} else {
+				lines.push(`  - ${prefix}${item}${postfix}`);
+			}
+			index++;
+		}
+
+		if (lines.length === 0) {
+			const prefix = color ? '\x1B[3;2m' : '';
+			return ':\n' + prefix + '  - <list is empty>' + postfix;
+		}
+		return ':\n' + lines.join('\n');
+	},
+	commandline(cmds: unknown, color: boolean) {
+		if (Array.isArray(cmds)) {
+			const prefix = color ? '\x1B[2m' : '';
+			const postfix = color ? '\x1B[0m' : '';
+			return prefix + cmds.map((s) => JSON.stringify(s)).join(' ') + postfix;
+		} else if (typeof cmds === 'string') {
+			const prefix = color ? '\x1B[2;3m' : '';
+			const postfix = color ? '\x1B[0m' : '';
+			return prefix + cmds + postfix;
+		} else {
+			return color_error(`commandline<> need string or array, not ${typeof cmds}`, color);
+		}
+	},
+	long(s: unknown, color: boolean) {
+		if (typeof s !== 'string') {
+			if (Array.isArray(s)) {
+				s = `[${s.join(', ')}]`;
+			} else {
+				return color_error(`long<> need string, not ${typeof s}(${s?.constructor?.name})`, color);
+			}
+		}
+		if (color) {
+			return `\x1B[3m${s}\x1B[23m`;
+		} else {
+			return s;
+		}
+	},
+	relative(s: unknown, color: boolean) {
+		if (typeof s !== 'string') {
+			return color_error(`relative<> need string, not ${typeof s}(${s?.constructor?.name})`, color);
+		}
+		return relative(process.cwd(), s);
+	},
+};
+type DebugCommands = Record<string, (arg: unknown, color: boolean) => string>;
+
+export function call_debug_command(
+	command: keyof typeof debug_commands | string,
+	arg: unknown,
+	color: boolean,
+): string {
+	const fn = (debug_commands as DebugCommands)[command];
+	if (!fn) {
+		return color_error(`unknown command ${command}`, color);
+	}
+	return fn(arg, color);
+}

package/src/common/helpers.ts

@@ -0,0 +1,184 @@
+import debug from 'debug';
+import process from 'node:process';
+import { terminal } from './logger.global.js';
+import { EnableLogLevel } from './types.js';
+
+/**
+ * 判断 字符串是否为“真值”
+ *  * 1 / 0
+ *  * true / false
+ *  * on / off
+ *  * yes / no
+ *  * enabled / disabled
+ *
+ * 其他内容会导致一个警告，并返回 false
+ */
+export function is_string_truthy(value: string | undefined) {
+	if (!value) return false;
+
+	value = value.toLowerCase();
+	if (value === '1' || value === 'true' || value === 'on' || value === 'yes' || value === 'enabled') {
+		return true;
+	} else if (value === '0' || value === 'false' || value === 'off' || value === 'no' || value === 'disabled') {
+		return false;
+	} else {
+		terminal.warn`invalid boolean string: ${value}, assuming false.`;
+		return false;
+	}
+}
+
+interface IWritableStream extends NodeJS.WritableStream {
+	colorEnabled?: boolean;
+	isTTY?: boolean;
+}
+
+function _colorEnabled(stream: IWritableStream): boolean {
+	const colorArg = process.argv.find((e) => e.startsWith('--color=') || e === '--color' || e === '-c');
+	const noColorArg = process.argv.includes('--no-color');
+
+	// 命令行顶级优先
+	if (colorArg) return true;
+	if (noColorArg) return false;
+
+	// 环境变量
+	if (process.env.NO_COLOR || process.env.NODE_DISABLE_COLORS === '1') {
+		/**
+		 * https://force-color.org/
+		 * https://nodejs.org/docs/latest/api/cli.html#node_disable_colors1
+		 */
+		return false;
+	} else if (process.env.FORCE_COLOR) {
+		return true;
+	}
+
+	// 检测其他可能
+	if (stream.isTTY) {
+		return true;
+	}
+
+	// TODO
+
+	return false;
+}
+
+export function detectColorEnable(stream: IWritableStream = process.stderr): boolean {
+	if (stream.colorEnabled === undefined) {
+		stream.colorEnabled = _colorEnabled(stream);
+	}
+	return stream.colorEnabled;
+}
+
+export function escapeRegExp(str: string) {
+	return str.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, '\\$&');
+}
+
+/**
+ *
+ * @param tag tag to match, e.g. "app:db:insert"
+ * @returns a RegExp, eg. /(^|\s)(\\*|app:\\*|app:db:\\*|app:db:insert)($|\s)/
+ */
+export function compile_match_regex(tag: string, invert = false): RegExp {
+	const parts = tag.split(':');
+	parts.pop();
+
+	let regs = ['\\*'];
+
+	let comb = [];
+	for (const part of parts) {
+		comb.push(part);
+		regs.push(`${escapeRegExp(comb.join(':'))}:\\*`);
+	}
+	regs.push(escapeRegExp(tag));
+	return new RegExp(`(?:^|,)(${invert ? '-' : ''})(${regs.join('|')})(?:$|,)`, 'i');
+}
+
+/**
+ * 从字符串中匹配指定的tag是否启用，不完全模拟 debug 模块的功能，不处理反义匹配（需用match_disabled）
+ * @param tag 类似 "app:db:insert" 的tag
+ * @param env 环境变量内容，默认 process.env.DEBUG
+ * @returns 冒号数量
+ */
+export function match_enabled(tag: string, env = process.env.DEBUG || ''): number {
+	const tagReg = compile_match_regex(tag);
+	const m = tagReg.exec(env);
+	if (!m) return 0;
+	return m[0].split(':').length;
+}
+
+/**
+ * 从字符串中匹配指定的tag是否禁用，不完全模拟 debug 模块的功能，tag前面不要加-
+ * @param tag 类似 "app:db:insert" 的tag
+ * @param env 环境变量内容，默认 process.env.DEBUG
+ * @returns 冒号数量 - 1
+ */
+export function match_disabled(tag: string, env = process.env.DEBUG || ''): number {
+	const tagReg = compile_match_regex(tag, true);
+	const m = tagReg.exec(env);
+	if (!m) return -1;
+	return m[0].split(':').length - 1;
+}
+
+/**
+ * 调用debug模块的debug.enabled方法
+ */
+export function debug_enabled(tag: string) {
+	return debug(tag).enabled;
+}
+
+/**
+ * 当指定tag开启时，应该输出它的什么级别
+ * tag关闭时始终默认error
+ *
+ * 只有新创建的受此影响，且不影响root-logger，也不影响.extend
+ */
+export let defaultLogLevel = (() => {
+	if (process.argv.includes('--verbose')) {
+		// 参数中含有 --verbose 时，设置默认日志级别
+		return EnableLogLevel.verbose;
+	} else {
+		// 参数中含有 --debug 或 -d 时，设置默认日志级别
+		const dbgCnt = process.argv.filter((e) => e === '--debug' || e === '-d').length;
+		if (dbgCnt > 1) {
+			return EnableLogLevel.verbose;
+		} else if (dbgCnt === 1) {
+			return EnableLogLevel.debug;
+		}
+	}
+
+	// DEBUG=xxx,verbose,xxx
+	// biome-ignore lint/performance/useTopLevelRegex:
+	const has_debug_verbose = /(?<=^|,)(verbose|debug)(?=$|,)/;
+	const setted = has_debug_verbose.exec(process.env.DEBUG || '');
+	if (setted) {
+		if (setted[0] === 'verbose') {
+			return EnableLogLevel.verbose;
+		} else {
+			return EnableLogLevel.debug;
+		}
+	} else {
+		// 直接通过 DEBUG_LEVEL 设置
+		switch (process.env.DEBUG_LEVEL || '') {
+			case '':
+				return EnableLogLevel.log;
+			case 'verbose':
+				return EnableLogLevel.verbose;
+			case 'debug':
+				return EnableLogLevel.debug;
+			case 'info':
+				return EnableLogLevel.info;
+			case 'warn':
+				return EnableLogLevel.warn;
+			default:
+				console.error('Invalid DEBUG_LEVEL: %s, using verbose.', process.env.DEBUG_LEVEL);
+				return EnableLogLevel.verbose;
+		}
+	}
+})();
+
+/**
+ * 手动设置默认日志级别
+ * root-logger 和 已经创建的 不受此影响
+ */
+export function set_default_log_level(level: EnableLogLevel) {
+	defaultLogLevel = level;
+}

package/src/common/logger.create.ts

@@ -0,0 +1,35 @@
+import process from 'node:process';
+import { PassThrough } from 'node:stream';
+import { create } from './create.js';
+import { debug_enabled, defaultLogLevel } from './helpers.js';
+import { terminal } from './logger.global.js';
+import { EnableLogLevel, type IMyLogger } from './types.js';
+
+/**
+ * 创建一个新的logger实例
+ * @param color_enabled 默认自动
+ * @param pipeTo 默认是 process.stderr
+ * @returns
+ */
+export function createLogger(
+	tag: string,
+	color_enabled: boolean | undefined = undefined,
+	pipeTo: undefined | NodeJS.WritableStream = process.stderr,
+): IMyLogger {
+	const stream = new PassThrough();
+	if (pipeTo) {
+		Object.assign(stream, { isTTY: (pipeTo as any).isTTY });
+		stream.pipe(pipeTo);
+	}
+
+	let level = EnableLogLevel.error;
+	if (debug_enabled(tag)) {
+		level = defaultLogLevel;
+	}
+
+	const logger = create(tag, color_enabled, stream, level);
+
+	(terminal || logger).verbose`logger "${tag}" created, level = ${EnableLogLevel[level]}`;
+
+	return logger;
+}

package/src/common/logger.global.ts

@@ -0,0 +1,31 @@
+import process from 'node:process';
+import { PassThrough } from 'node:stream';
+import { create } from './create.js';
+import { EnableLogLevel, type IMyLogger } from './types.js';
+
+const stream = new PassThrough();
+stream.pipe(process.stderr);
+Object.assign(stream, { isTTY: process.stderr.isTTY });
+
+/**
+ * 作为logger导出，必须在程序入口调用过 createGlobalLogger() 才能使用
+ */
+export let terminal: IMyLogger;
+
+/**
+ * 创建root-logger，随后logger变量可用
+ */
+export function createGlobalLogger(tag: string, defaultLevel: EnableLogLevel = EnableLogLevel.auto): void {
+	if (terminal) throw new Error('global logger already created');
+
+	terminal = create(tag, undefined, stream);
+
+	terminal.enable(defaultLevel || EnableLogLevel.log);
+
+	if (terminal.verbose.isEnabled) {
+		terminal.verbose`verbose is enabled`;
+	} else {
+		terminal.debug`debug is enabled`;
+	}
+	return;
+}

package/src/common/types.ts

@@ -0,0 +1,39 @@
+export type IMyDebug<T = void> = (message: TemplateStringsArray | string, ...args: readonly any[]) => T;
+
+export interface IMyDebugWithControl extends IMyDebug {
+	enable(): void;
+	disable(): void;
+	readonly isEnabled: boolean;
+}
+
+export enum EnableLogLevel {
+	auto,
+	fatal,
+	error,
+	warn,
+	info,
+	log,
+	debug,
+	verbose,
+}
+
+export type IMyLogger = {
+	fatal: IMyDebug<never>;
+
+	error: IMyDebug;
+	success: IMyDebugWithControl;
+
+	warn: IMyDebugWithControl;
+	info: IMyDebugWithControl;
+	log: IMyDebugWithControl;
+	debug: IMyDebugWithControl;
+	verbose: IMyDebugWithControl;
+
+	extend: (tag: string) => IMyLogger;
+	stream: NodeJS.ReadableStream;
+
+	enable(newMaxLevel: EnableLogLevel): void;
+
+	readonly tag: string;
+	readonly colorEnabled: boolean;
+};

package/src/index.ts

@@ -0,0 +1,23 @@
+export { LogLevel, logTagColor } from './common/colors.js';
+export { all_logger_names } from './common/create.js';
+export { createDebug } from './common/debug-fn.js';
+export {
+	detectColorEnable as color_enabled,
+	debug_enabled,
+	is_string_truthy,
+	match_disabled,
+	match_enabled,
+	set_default_log_level,
+} from './common/helpers.js';
+export { createLogger } from './common/logger.create.js';
+export {
+	createGlobalLogger as createRootLogger,
+	terminal as logger,
+} from './common/logger.global.js';
+export {
+	EnableLogLevel,
+	type IMyDebug,
+	type IMyDebugWithControl,
+	type IMyLogger,
+} from './common/types.js';
+export { createLogFile } from './printers/file.js';

package/src/printers/file.ts

@@ -0,0 +1,29 @@
+import { createWriteStream } from 'node:fs';
+import { resolve } from 'node:path';
+import { Transform, type TransformCallback } from 'node:stream';
+
+export function createLogFile(filePath: string): NodeJS.WritableStream {
+	const file = resolve(process.cwd(), filePath);
+	console.log(`Creating log file: ${file}`);
+	const target = createWriteStream(file, { autoClose: true, encoding: 'utf-8', flush: true });
+	target.on('error', (err) => {
+		console.error(`Error writing to log file ${file}:`, err);
+	});
+	target.on('open', (fd) => {
+		console.error(`log file ${file}:`, fd);
+	});
+	target.on('close', () => {
+		console.error(`log file ${file}: close`);
+	});
+	const filter = new ColorRemoveStream();
+	filter.pipe(target, { end: true });
+
+	return filter;
+}
+
+class ColorRemoveStream extends Transform {
+	override _transform(chunk: Buffer, _encoding: string, callback: TransformCallback): void {
+		const cleaned = chunk.toString().replace(/\x1B\[[0-9;]*m/g, '');
+		callback(null, cleaned);
+	}
+}

package/src/test/01-simple.test.ts

@@ -0,0 +1,44 @@
+import { createGlobalLogger } from '../common/logger.global.js';
+import { logger } from '../index.js';
+
+createGlobalLogger('wow');
+
+const l = 'such';
+const o = { hello: 'world' };
+
+logger.error`wow, ${l} doge! ${o}!`;
+logger.error('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.warn`wow, ${l} doge! ${o}!`;
+logger.warn('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.info`wow, ${l} doge! ${o}!`;
+logger.info('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.log`wow, ${l} doge! ${o}!`;
+logger.log('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.success`wow, ${l} doge! ${o}!`;
+logger.success('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.debug`wow, ${l} doge! ${o}!`;
+logger.debug('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.verbose`wow, ${l} doge! ${o}!`;
+logger.verbose('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.fatal`wow, ${l} doge! ${o}!`;
+logger.fatal('wow, such %s! %o?', l, o);
+
+// @ts-ignore
+console.log('----------------');
+
+// @ts-ignore
+logger.error`this not happen`;

package/src/test/02-debug.test.ts

@@ -0,0 +1,11 @@
+import { createGlobalLogger } from '../common/logger.global.js';
+import { logger } from '../index.js';
+
+createGlobalLogger('wow');
+
+const l = 'such';
+const o = { hello: 'world' };
+
+logger.debug`wow, ${l} doge! ${o}!`;
+console.log('----------------');
+logger.debug('wow, such %s! %o?', l, o);

package/src/test/03-file.test.ts

@@ -0,0 +1,46 @@
+import { createGlobalLogger } from '../common/logger.global.js';
+import { createLogFile, logger } from '../index.js';
+
+createGlobalLogger('wow');
+
+logger.stream.pipe(createLogFile('test.log'));
+
+const l = 'such';
+const o = { hello: 'world' };
+
+logger.error`wow, ${l} doge! ${o}!`;
+logger.error('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.warn`wow, ${l} doge! ${o}!`;
+logger.warn('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.info`wow, ${l} doge! ${o}!`;
+logger.info('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.log`wow, ${l} doge! ${o}!`;
+logger.log('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.success`wow, ${l} doge! ${o}!`;
+logger.success('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.debug`wow, ${l} doge! ${o}!`;
+logger.debug('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.verbose`wow, ${l} doge! ${o}!`;
+logger.verbose('wow, such %s! %o?', l, o);
+console.log('----------------');
+
+logger.fatal`wow, ${l} doge! ${o}!`;
+logger.fatal('wow, such %s! %o?', l, o);
+
+// @ts-ignore
+console.log('----------------');
+
+// @ts-ignore
+logger.error`this not happen`;

package/src/tsconfig.json

@@ -0,0 +1,10 @@
+{
+	"extends": "@internal/local-rig/profiles/default/tsconfig.json",
+	"compilerOptions": {
+		"typeRoots": ["../node_modules/@types", "../node_modules"],
+		"outDir": "../lib",
+		"rootDir": "./",
+		"types": ["node"],
+		"noEmitOnError": false
+	}
+}