@steve02081504/virtual-console 0.1.6 → 0.1.8

package/browser.d.mts

@@ -0,0 +1,114 @@
+import type { Console } from 'node:console'
+import type { Writable } from 'node:stream'
+
+/**
+ * 虚拟控制台配置选项
+ */
+export interface VirtualConsoleOptions {
+	/** 如果为 true，则在捕获输出的同时，也调用底层控制台进行实际输出 */
+	realConsoleOutput?: boolean
+	/** 如果为 true，则捕获输出并保存在 outputs 属性中 */
+	recordOutput?: boolean
+	/** 专门处理单个 Error 对象的错误处理器 */
+	error_handler?: ((error: Error) => void) | null
+	/** 用于 realConsoleOutput 的底层控制台实例 */
+	base_console?: VirtualConsole | Console
+}
+
+/**
+ * 控制台反射逻辑
+ */
+export interface ConsoleReflect {
+	/** 从默认控制台获取当前控制台对象 */
+	Reflect: () => VirtualConsole
+	/** 设置当前控制台对象的函数 */
+	ReflectSet: (value: VirtualConsole) => void
+	/** 在新的异步上下文中执行函数的函数 */
+	ReflectRun: <T>(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>
+}
+
+/**
+ * 虚拟流，包装 Node.js 可写流
+ */
+interface VirtualStream extends Writable {
+	/** 是否为 TTY */
+	readonly isTTY: boolean
+	/** 列数 */
+	readonly columns: number
+	/** 行数 */
+	readonly rows: number
+	/** 获取底层目标流 */
+	readonly targetStream: NodeJS.WritableStream
+	/** 获取颜色深度 */
+	getColorDepth(): number
+	/** 判断是否支持颜色 */
+	hasColors(): boolean
+}
+
+/**
+ * 虚拟控制台，用于捕获输出，同时可以选择性地将输出传递给真实的控制台
+ */
+export class VirtualConsole extends Console {
+	/** 捕获的所有输出 */
+	outputs: string
+	/** 捕获的所有输出 (HTML) */
+	outputsHtml: string
+	/** 最终合并后的配置项 */
+	options: Required<Omit<VirtualConsoleOptions, 'base_console'>> & {
+		base_console?: VirtualConsole | Console
+	}
+	/** 用于 realConsoleOutput 的底层控制台实例 */
+	base_console: VirtualConsole | Console
+
+	constructor(options?: VirtualConsoleOptions)
+
+	/**
+	 * 若提供 fn，则在新的异步上下文中执行 fn，并将 fn 上下文的控制台替换为此对象。
+	 * 否则，将当前异步上下文中的控制台替换为此对象。
+	 * @param fn 在新的异步上下文中执行的函数
+	 * @returns 若提供 fn，则返回 fn 的 Promise 结果；否则返回 void
+	 */
+	hookAsyncContext<T>(fn?: () => T | Promise<T>): Promise<T> | void
+
+	/**
+	 * 在终端中打印一行，等同于 log。
+	 * @param id 用于标识可覆盖行的唯一 ID
+	 * @param args 要打印的内容
+	 */
+	freshLine(id: string, ...args: unknown[]): void
+
+	/** 清空捕获的输出，并选择性地清空真实控制台 */
+	clear(): void
+}
+
+/** 全局异步存储，浏览器环境下不存在 */
+export const consoleAsyncStorage: undefined
+
+/** 默认的虚拟控制台实例 */
+export const defaultConsole: VirtualConsole
+
+/** 全局控制台的附加属性 */
+export const globalConsoleAdditionalProperties: Record<string, unknown>
+
+/**
+ * 设置全局控制台反射逻辑
+ * @param Reflect 从默认控制台映射到新的控制台对象的函数
+ * @param ReflectSet 设置当前控制台对象的函数
+ * @param ReflectRun 在新的异步上下文中执行函数的函数
+ */
+export function setGlobalConsoleReflect(
+	Reflect: (defaultConsole: VirtualConsole) => VirtualConsole,
+	ReflectSet: (value: VirtualConsole) => void,
+	ReflectRun: <T>(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>
+): void
+
+/** 获取全局控制台反射逻辑 */
+export function getGlobalConsoleReflect(): ConsoleReflect
+
+/** 全局控制台实例（代理对象，委托给当前活动的虚拟控制台） */
+export const console: VirtualConsole
+
+declare global {
+	/** 全局控制台实例 */
+	var console: VirtualConsole
+}

package/main.d.mts

@@ -0,0 +1,118 @@
+import type { AsyncLocalStorage } from 'node:async_hooks'
+import type { Console } from 'node:console'
+import type { Writable } from 'node:stream'
+
+/**
+ * 虚拟控制台配置选项
+ */
+export interface VirtualConsoleOptions {
+	/** 如果为 true，则在捕获输出的同时，也调用底层控制台进行实际输出 */
+	realConsoleOutput?: boolean
+	/** 如果为 true，则捕获输出并保存在 outputs 属性中 */
+	recordOutput?: boolean
+	/** 如果为 true，则启用 ANSI 转义序列支持（Node.js 环境） */
+	supportsAnsi?: boolean
+	/** 专门处理单个 Error 对象的错误处理器 */
+	error_handler?: ((error: Error) => void) | null
+	/** 用于 realConsoleOutput 的底层控制台实例 */
+	base_console?: VirtualConsole | Console
+}
+
+/**
+ * 控制台反射逻辑
+ */
+export interface ConsoleReflect {
+	/** 从默认控制台获取当前控制台对象 */
+	Reflect: () => VirtualConsole
+	/** 设置当前控制台对象的函数 */
+	ReflectSet: (value: VirtualConsole) => void
+	/** 在新的异步上下文中执行函数的函数 */
+	ReflectRun: <T>(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>
+}
+
+/**
+ * 虚拟流，包装 Node.js 可写流
+ */
+interface VirtualStream extends Writable {
+	/** 是否为 TTY */
+	readonly isTTY: boolean
+	/** 列数 */
+	readonly columns: number
+	/** 行数 */
+	readonly rows: number
+	/** 获取底层目标流 */
+	readonly targetStream: NodeJS.WritableStream
+	/** 获取颜色深度 */
+	getColorDepth(): number
+	/** 判断是否支持颜色 */
+	hasColors(): boolean
+}
+
+/**
+ * 虚拟控制台，用于捕获输出，同时可以选择性地将输出传递给真实的控制台
+ */
+export class VirtualConsole extends Console {
+	/** 捕获的所有输出 */
+	outputs: string
+	/** 捕获的所有输出 (HTML) */
+	outputsHtml: string
+	/** 最终合并后的配置项 */
+	options: Required<Omit<VirtualConsoleOptions, 'base_console'>> & {
+		base_console?: VirtualConsole | Console
+	}
+	/** 用于 realConsoleOutput 的底层控制台实例 */
+	base_console: VirtualConsole | Console
+
+	constructor(options?: VirtualConsoleOptions)
+
+	/**
+	 * 若提供 fn，则在新的异步上下文中执行 fn，并将 fn 上下文的控制台替换为此对象。
+	 * 否则，将当前异步上下文中的控制台替换为此对象。
+	 * @param fn 在新的异步上下文中执行的函数
+	 * @returns 若提供 fn，则返回 fn 的 Promise 结果；否则返回 void
+	 */
+	hookAsyncContext<T>(fn?: () => T | Promise<T>): Promise<T> | void
+
+	/**
+	 * 在终端中打印一行，如果前一次调用也是具有相同 ID 的 freshLine，
+	 * 则会覆盖上一行而不是打印新行（Node.js 环境）。浏览器环境等同于 log。
+	 * @param id 用于标识可覆盖行的唯一 ID
+	 * @param args 要打印的内容
+	 */
+	freshLine(id: string, ...args: unknown[]): void
+
+	/** 清空捕获的输出，并选择性地清空真实控制台 */
+	clear(): void
+}
+
+/** 全局异步存储，用于管理控制台上下文（Node.js 环境） */
+export const consoleAsyncStorage: AsyncLocalStorage<VirtualConsole>
+
+/** 默认的虚拟控制台实例 */
+export const defaultConsole: VirtualConsole
+
+/** 全局控制台的附加属性 */
+export const globalConsoleAdditionalProperties: Record<string, unknown>
+
+/**
+ * 设置全局控制台反射逻辑
+ * @param Reflect 从默认控制台映射到新的控制台对象的函数
+ * @param ReflectSet 设置当前控制台对象的函数
+ * @param ReflectRun 在新的异步上下文中执行函数的函数
+ */
+export function setGlobalConsoleReflect(
+	Reflect: (defaultConsole: VirtualConsole) => VirtualConsole,
+	ReflectSet: (value: VirtualConsole) => void,
+	ReflectRun: <T>(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>
+): void
+
+/** 获取全局控制台反射逻辑 */
+export function getGlobalConsoleReflect(): ConsoleReflect
+
+/** 全局控制台实例 */
+export const console: VirtualConsole
+
+declare global {
+	/** 全局控制台实例 */
+	var console: VirtualConsole
+}

package/node.d.mts

@@ -0,0 +1,118 @@
+import type { AsyncLocalStorage } from 'node:async_hooks'
+import type { Console } from 'node:console'
+import type { Writable } from 'node:stream'
+
+/**
+ * 虚拟控制台配置选项
+ */
+export interface VirtualConsoleOptions {
+	/** 如果为 true，则在捕获输出的同时，也调用底层控制台进行实际输出 */
+	realConsoleOutput?: boolean
+	/** 如果为 true，则捕获输出并保存在 outputs 属性中 */
+	recordOutput?: boolean
+	/** 如果为 true，则启用 ANSI 转义序列支持 */
+	supportsAnsi?: boolean
+	/** 专门处理单个 Error 对象的错误处理器 */
+	error_handler?: ((error: Error) => void) | null
+	/** 用于 realConsoleOutput 的底层控制台实例 */
+	base_console?: VirtualConsole | Console
+}
+
+/**
+ * 控制台反射逻辑
+ */
+export interface ConsoleReflect {
+	/** 从默认控制台获取当前控制台对象 */
+	Reflect: () => VirtualConsole
+	/** 设置当前控制台对象的函数 */
+	ReflectSet: (value: VirtualConsole) => void
+	/** 在新的异步上下文中执行函数的函数 */
+	ReflectRun: <T>(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>
+}
+
+/**
+ * 虚拟流，包装 Node.js 可写流
+ */
+interface VirtualStream extends Writable {
+	/** 是否为 TTY */
+	readonly isTTY: boolean
+	/** 列数 */
+	readonly columns: number
+	/** 行数 */
+	readonly rows: number
+	/** 获取底层目标流 */
+	readonly targetStream: NodeJS.WritableStream
+	/** 获取颜色深度 */
+	getColorDepth(): number
+	/** 判断是否支持颜色 */
+	hasColors(): boolean
+}
+
+/**
+ * 虚拟控制台，用于捕获输出，同时可以选择性地将输出传递给真实的控制台
+ */
+export class VirtualConsole extends Console {
+	/** 捕获的所有输出 */
+	outputs: string
+	/** 捕获的所有输出 (HTML) */
+	outputsHtml: string
+	/** 最终合并后的配置项 */
+	options: Required<Omit<VirtualConsoleOptions, 'base_console'>> & {
+		base_console?: VirtualConsole | Console
+	}
+	/** 用于 realConsoleOutput 的底层控制台实例 */
+	base_console: VirtualConsole | Console
+
+	constructor(options?: VirtualConsoleOptions)
+
+	/**
+	 * 若提供 fn，则在新的异步上下文中执行 fn，并将 fn 上下文的控制台替换为此对象。
+	 * 否则，将当前异步上下文中的控制台替换为此对象。
+	 * @param fn 在新的异步上下文中执行的函数
+	 * @returns 若提供 fn，则返回 fn 的 Promise 结果；否则返回 void
+	 */
+	hookAsyncContext<T>(fn?: () => T | Promise<T>): Promise<T> | void
+
+	/**
+	 * 在终端中打印一行，如果前一次调用也是具有相同 ID 的 freshLine，
+	 * 则会覆盖上一行而不是打印新行。
+	 * @param id 用于标识可覆盖行的唯一 ID
+	 * @param args 要打印的内容
+	 */
+	freshLine(id: string, ...args: unknown[]): void
+
+	/** 清空捕获的输出，并选择性地清空真实控制台 */
+	clear(): void
+}
+
+/** 全局异步存储，用于管理控制台上下文 */
+export const consoleAsyncStorage: AsyncLocalStorage<VirtualConsole>
+
+/** 默认的虚拟控制台实例 */
+export const defaultConsole: VirtualConsole
+
+/** 全局控制台的附加属性 */
+export const globalConsoleAdditionalProperties: Record<string, unknown>
+
+/**
+ * 设置全局控制台反射逻辑
+ * @param Reflect 从默认控制台映射到新的控制台对象的函数
+ * @param ReflectSet 设置当前控制台对象的函数
+ * @param ReflectRun 在新的异步上下文中执行函数的函数
+ */
+export function setGlobalConsoleReflect(
+	Reflect: (defaultConsole: VirtualConsole) => VirtualConsole,
+	ReflectSet: (value: VirtualConsole) => void,
+	ReflectRun: <T>(value: VirtualConsole, fn: () => T | Promise<T>) => Promise<T>
+): void
+
+/** 获取全局控制台反射逻辑 */
+export function getGlobalConsoleReflect(): ConsoleReflect
+
+/** 全局控制台实例（代理对象，委托给当前活动的虚拟控制台） */
+export const console: VirtualConsole
+
+declare global {
+	/** 全局控制台实例 */
+	var console: VirtualConsole
+}

package/node.mjs

@@ -152,6 +152,14 @@ class VirtualStream extends Writable {
 	hasColors() {
 		return this.#targetStream.hasColors()
 	}
+
+	/**
+	 * 获取底层目标流。
+	 * @returns {NodeJS.WritableStream} 底层目标流。
+	 */
+	get targetStream() {
+		return this.#targetStream
+	}
 }
 
 /**
@@ -194,6 +202,12 @@ export class VirtualConsole extends Console {
 	/** @type {Console} - 用于 realConsoleOutput 的底层控制台实例 */
 	#base_console
 
+	/** @private @type {VirtualStream} - 标准输出流 */
+	#_stdout
+
+	/** @private @type {VirtualStream} - 标准错误流 */
+	#_stderr
+
 	/** @private @type {string | null} - 用于 freshLine 功能，记录上一次 freshLine 的 ID */
 	#loggedFreshLineId = null
 
@@ -207,6 +221,8 @@ export class VirtualConsole extends Console {
 	 */
 	constructor(options = {}) {
 		super(new Writable({ /** 啥也不干  */ write: () => { } }), new Writable({ /** 啥也不干  */ write: () => { } }))
+		for (const property of ['_stdout', '_stderr'])
+			delete this[property] // 因为父类的实例属性会遮蔽子类的getter/setter，所以需要删除这些字段
 
 		const base_console = options.base_console || consoleReflect()
 		delete options.base_console
@@ -239,22 +255,11 @@ export class VirtualConsole extends Console {
 	}
 
 	/**
-	 * 获取用于 realConsoleOutput 的底层控制台实例。
-	 * @returns {Console} 底层控制台实例。
-	 */
-	get base_console() {
-		return this.#base_console
-	}
-
-	/**
-	 * 设置用于 realConsoleOutput 的底层控制台实例。
-	 * @param {Console} value - 底层控制台实例。
-	 * @returns {void}
+	 * 获取虚拟控制台的上下文对象，用于创建 VirtualStream。
+	 * @returns {object} 上下文对象。
 	 */
-	set base_console(value) {
-		this.#base_console = value
-
-		const context = {
+	#getStreamContext() {
+		return {
 			/**
 			 * 写入完成时的回调函数，用于重置 loggedFreshLineId。
 			 * @returns {void}
@@ -265,9 +270,63 @@ export class VirtualConsole extends Console {
 			options: this.options,
 			state: this
 		}
+	}
+
+	/**
+	 * 获取标准输出流。
+	 * @returns {VirtualStream} 标准输出流。
+	 */
+	get _stdout() {
+		return this.#_stdout
+	}
+
+	/**
+	 * 设置标准输出流，自动将其包装为 VirtualStream。
+	 * @param {NodeJS.WritableStream | VirtualStream} value - 要设置的流。
+	 * @returns {void}
+	 */
+	set _stdout(value) {
+		const context = this.#getStreamContext()
+		const targetStream = value?.targetStream || value || process.stdout
+		this.#_stdout = new VirtualStream(targetStream, context)
+	}
+
+	/**
+	 * 获取标准错误流。
+	 * @returns {VirtualStream} 标准错误流。
+	 */
+	get _stderr() {
+		return this.#_stderr
+	}
+
+	/**
+	 * 设置标准错误流，自动将其包装为 VirtualStream。
+	 * @param {NodeJS.WritableStream | VirtualStream} value - 要设置的流。
+	 * @returns {void}
+	 */
+	set _stderr(value) {
+		const context = this.#getStreamContext()
+		const targetStream = value?.targetStream || value || process.stderr
+		this.#_stderr = new VirtualStream(targetStream, context)
+	}
+
+	/**
+	 * 设置用于 realConsoleOutput 的底层控制台实例。
+	 * @param {Console} value - 底层控制台实例。
+	 * @returns {void}
+	 */
+	set base_console(value) {
+		this.#base_console = value || globalThis.console
+		this._stdout = this.#base_console?._stdout
+		this._stderr = this.#base_console?._stderr
+	}
 
-		this._stdout = new VirtualStream(this.#base_console?._stdout || process.stdout, context)
-		this._stderr = new VirtualStream(this.#base_console?._stderr || process.stderr, context)
+	/**
+	 * 获取用于 realConsoleOutput 的底层控制台实例。
+	 * @returns {Console} 底层控制台实例。
+	 */
+	get base_console() {
+		return this.#base_console
 	}
 
 	/**

package/package.json

@@ -1,9 +1,35 @@
 {
 	"name": "@steve02081504/virtual-console",
-	"version": "0.1.6",
+	"version": "0.1.8",
 	"description": "A virtual console for capturing and manipulating terminal output.",
 	"main": "main.mjs",
 	"type": "module",
+	"exports": {
+		".": {
+			"browser": {
+				"types": "./browser.d.mts",
+				"default": "./browser.mjs"
+			},
+			"node": {
+				"types": "./node.d.mts",
+				"default": "./node.mjs"
+			},
+			"types": "./main.d.mts",
+			"default": "./main.mjs"
+		},
+		"./node": {
+			"types": "./node.d.mts",
+			"default": "./node.mjs"
+		},
+		"./browser": {
+			"types": "./browser.d.mts",
+			"default": "./browser.mjs"
+		}
+	},
+	"types": "./main.d.mts",
+	"scripts": {
+		"test": "node test.mjs"
+	},
 	"keywords": [
 		"console",
 		"virtual",
@@ -17,9 +43,9 @@
 	},
 	"homepage": "https://github.com/steve02081504/virtual-console#readme",
 	"dependencies": {
+		"ansi_up": "latest",
 		"ansi-escapes": "latest",
 		"full-proxy": "latest",
-		"supports-ansi": "latest",
-		"ansi_up": "latest"
+		"supports-ansi": "latest"
 	}
 }