@idlebox/common 1.4.19 → 1.4.21

package/src/lifecycle/dispose/disposable.ts

@@ -0,0 +1,162 @@
+import type { MaybeNamed } from '../../debugging/object-with-name.js';
+import { createStackTraceHolder, type StackTraceHolder } from '../../error/stack-trace.js';
+import { Emitter } from '../event/event.js';
+import type { EventRegister } from '../event/type.js';
+import { fromNativeDisposable } from './bridges/native.js';
+import { _debug_dispose, dispose_name } from './debug.js';
+import { DuplicateDisposed } from './disposedError.js';
+
+export enum DuplicateDisposeAction {
+	Disable = 0,
+	Warning = 1,
+	Allow = 2,
+}
+
+/** @public */
+export interface IDisposableEvents {
+	onDisposeError: EventRegister<Error>;
+	onBeforeDispose: EventRegister<void>;
+	readonly hasDisposed: boolean;
+}
+
+/** @public */
+export interface IDisposable extends MaybeNamed {
+	dispose(): void;
+}
+
+/** @public */
+export interface IAsyncDisposable extends MaybeNamed {
+	dispose(): void | Promise<void>;
+}
+
+type _Type<Async extends boolean> = Async extends true ? IAsyncDisposable : IDisposable;
+type _RType<Async extends boolean> = Async extends true ? Promise<void> : void;
+
+/**
+ * 增强型Disposable
+ * @internal
+ */
+export abstract class AbstractEnhancedDisposable<Async extends boolean> implements IDisposableEvents {
+	protected readonly _onDisposeError = new Emitter<Error>();
+	public readonly onDisposeError: EventRegister<Error> = this._onDisposeError.register;
+
+	protected readonly _onBeforeDispose = new Emitter<void>();
+	public readonly onBeforeDispose: EventRegister<void> = this._onBeforeDispose.register;
+
+	protected readonly _onPostDispose = new Emitter<void>();
+	public readonly onPostDispose: EventRegister<void> = this._onPostDispose.register;
+
+	/** for debug */
+	public readonly displayName?: string;
+	protected readonly _logger;
+
+	constructor(displayName?: string) {
+		if (displayName !== undefined) {
+			this.displayName = displayName;
+		} else if (!this.displayName) {
+			displayName = dispose_name(this, 'AsyncDisposable');
+			this.displayName = displayName;
+		}
+
+		this._logger = _debug_dispose.extend(this.displayName || 'disposable');
+
+		this._onPostDispose.handle(() => {
+			this._onPostDispose.dispose();
+		});
+		this._disposables.push(this._onBeforeDispose);
+		this._disposables.push(this._onDisposeError);
+	}
+
+	/**
+	 * @throws if already disposed
+	 */
+	public assertNotDisposed() {
+		if (this._disposed) {
+			throw new DuplicateDisposed(this, this._disposed.trace);
+		}
+	}
+
+	/**
+	 * the "DisposableStack"
+	 */
+	protected readonly _disposables: _Type<Async>[] = [];
+
+	/**
+	 * register a disposable object
+	 */
+	public _register<T extends _Type<Async>>(d: T): T;
+	public _register<T extends _Type<Async> & IDisposableEvents>(d: T, autoDereference?: boolean): T;
+	public _register(d: any, autoDereference?: boolean): any {
+		if (this._logger.enabled) this._logger(`register ${dispose_name(d)}`);
+		this.assertNotDisposed();
+		this._disposables.unshift(fromNativeDisposable(d));
+		if (autoDereference) {
+			(d as IDisposableEvents).onBeforeDispose(() => {
+				this._unregister(d);
+			});
+		}
+		return d;
+	}
+
+	public _unregister(d: _Type<Async>) {
+		if (this._logger.enabled) this._logger(`unregister ${dispose_name(d)}`);
+		this.assertNotDisposed();
+		return this._disposables.splice(this._disposables.indexOf(d), 1).length > 0;
+	}
+
+	protected readonly duplicateDispose: DuplicateDisposeAction = DuplicateDisposeAction.Warning;
+	private _disposed?: {
+		trace: StackTraceHolder;
+		result: _RType<Async>;
+	};
+	public get disposed() {
+		return !!this._disposed;
+	}
+	/**
+	 * @deprecated use disposed
+	 */
+	public get hasDisposed() {
+		return !!this._disposed;
+	}
+	/**
+	 * 释放相关资源
+	 */
+	public dispose(): _RType<Async> {
+		if (this._disposed) {
+			if (this.duplicateDispose === DuplicateDisposeAction.Allow) return this._disposed.result;
+
+			const dupErr = new DuplicateDisposed(this, this._disposed.trace);
+			if (this.duplicateDispose === DuplicateDisposeAction.Disable) {
+				throw dupErr;
+			} else {
+				console.warn(dupErr);
+				return this._disposed.result;
+			}
+		}
+		this._onBeforeDispose.fireNoError();
+
+		let r: any;
+		try {
+			r = this._dispose(this._disposables);
+		} finally {
+			this._disposables.length = 0;
+			Object.freeze(this._disposables);
+
+			this._disposed = {
+				trace: createStackTraceHolder('disposed', this.dispose),
+				result: r,
+			};
+		}
+
+		if (r && 'then' in r) {
+			r.then(() => {});
+		}
+		return r;
+	}
+
+	get [Symbol.toStringTag](): string {
+		return this.displayName || 'unknown disposable';
+	}
+
+	protected abstract _dispose(disposables: readonly _Type<Async>[]): _RType<Async>;
+}

package/src/lifecycle/dispose/disposableEvent.ts

@@ -1,102 +1,36 @@
-import type { IDisposable } from './lifecycle.js';
+import type { IDisposable } from './disposable.js';
 
-declare const AbortController: new () => any;
-
-export interface IEventListenerOptions {
-	capture?: boolean;
-	once?: boolean;
-	passive?: boolean;
+export function addAnyKindOfListener(host: IEventEmitterObject | IShorthandEmitterObject, name: string, handler: Function) {
+	if ('on' in host) {
+		host.on(name, handler);
+	} else if ('addListener' in host) {
+		host.addListener(name, handler);
+	}
 }
 
-export interface IEventHostObject<T extends Function> {
-	addEventListener(type: string, handler: T, options?: IEventListenerOptions): any;
-	removeEventListener(type: string, handler: T, options?: IEventListenerOptions): any;
+export interface IShorthandEmitterObject {
+	on(type: string, handler: Function): void;
+	off(type: string, handler: Function): void;
 }
 
-export interface IEventEmitterObject<T extends Function> {
-	addListener(type: string, handler: T): any;
-	removeListener(type: string, handler: T): any;
+export interface IEventEmitterObject {
+	addListener(type: string, handler: Function): void;
+	removeListener(type: string, handler: Function): void;
 }
 
-export function addDisposableEventListener<T extends Function>(target: IEventHostObject<T> | IEventEmitterObject<T>, type: string, options: IEventListenerOptions, handler: T): IDisposable;
-
-export function addDisposableEventListener<T extends Function>(target: IEventHostObject<T> | IEventEmitterObject<T>, type: string, handler: T): IDisposable;
-
-export function addDisposableEventListener<T extends Function>(target: IEventHostObject<T> | IEventEmitterObject<T>, type: string, _options: IEventListenerOptions | T | undefined, _handler?: T): IDisposable {
-	if (!_handler) {
-		if (typeof _options === 'function') {
-			_handler = _options;
-			_options = undefined;
-		} else {
-			throw new Error('missing handler');
-		}
-	}
-
-	const handler = _handler as T;
-	const options = _options as IEventListenerOptions;
-
+export function addDisposableEventListener(target: IEventEmitterObject | IShorthandEmitterObject, type: string, handler: Function): IDisposable {
 	let remove: IDisposable['dispose'];
 
-	if ('addEventListener' in target) {
-		if (passiveSupported === undefined || abortSupported === undefined) {
-			checkAllSupport(target);
-		}
-		const [abort, xOptions] = check(options);
-		target.addEventListener(type, handler, xOptions);
-		if (abort) {
-			remove = () => {
-				abort;
-			};
-		} else {
-			remove = () => {
-				target.removeEventListener(type, handler, xOptions);
-			};
-		}
-	} else {
+	if ('addListener' in target) {
 		target.addListener(type, handler);
 		remove = () => {
 			target.removeListener(type, handler);
 		};
-	}
-	return { dispose: remove };
-}
-
-let passiveSupported: boolean;
-let abortSupported: boolean;
-function check(options: IEventListenerOptions = {}): [{ abort(): void } | undefined, IEventListenerOptions] {
-	if (!passiveSupported) {
-		return [undefined, (options.capture || false) as any];
-	}
-
-	if (abortSupported) {
-		const controller = new AbortController();
-		(options as any).signal = controller.signal;
-		return [controller, options];
-	}
-	return [undefined, options];
-}
-
-function checkAllSupport(ele: IEventHostObject<any>) {
-	passiveSupported = checkSupport('passive', ele);
-	abortSupported = typeof AbortController !== 'undefined' && checkSupport('signal', ele);
-}
-
-function checkSupport(field: string, ele: IEventHostObject<any>) {
-	let supported = false;
-	try {
-		const options = {
-			get [field]() {
-				// This function will be called when the browser
-				//   attempts to access the passive property.
-				supported = true;
-				return undefined;
-			},
+	} else {
+		target.on(type, handler);
+		remove = () => {
+			target.off(type, handler);
 		};
-
-		ele.addEventListener('_test_', null, options);
-		ele.removeEventListener('_test_', null, options);
-	} catch (_err) {
-		supported = false;
 	}
-	return supported;
+	return { dispose: remove };
 }

package/src/lifecycle/dispose/disposedError.ts

@@ -1,40 +1,57 @@
-import { tryInspect } from '../../debugging/tryInspect.js';
-import { getErrorFrame } from '../../error/getFrame.js';
-import { prettyFormatError } from '../../error/pretty.js';
-import type { StackTraceHolder } from '../../error/stackTrace.js';
+import { isNodeJs } from '../../autoindex.js';
+import { tryInspect } from '../../debugging/inspect.js';
+import { getErrorFrame } from '../../error/get-frame.js';
+import { prettyFormatError } from '../../error/pretty.nodejs.js';
+import type { StackTraceHolder } from '../../error/stack-trace.js';
+import { dispose_name } from './debug.js';
+
+export class Disposed extends Error {
+	constructor(
+		message = 'Object has been disposed',
+		private readonly previous: StackTraceHolder,
+	) {
+		super(message);
+		this.name = 'DisposedError';
+	}
+
+	override get stack() {
+		return `${super.stack}\nDisposed at:\n${this.previous.stack}`;
+	}
+}
 
 /**
  * Error when call dispose() twice
  */
-export class DisposedError extends Error {
+export class DuplicateDisposed extends Error {
 	public readonly inspectString: string;
 	constructor(
 		object: any,
-		public readonly previous: StackTraceHolder,
+		private readonly previous: StackTraceHolder,
 	) {
-		const insp = tryInspect(object);
-
-		const old = (Error as any).stackTraceLimit;
-		(Error as any).stackTraceLimit = Number.MAX_SAFE_INTEGER;
+		const old = Error.stackTraceLimit;
+		Error.stackTraceLimit = Number.MAX_SAFE_INTEGER;
+		const stacks = getErrorFrame(previous, 2);
 
-		super(`Object [${insp}] has already disposed ${getErrorFrame(previous, 2)}.`);
+		const inspectString = tryInspect(object);
+		const name = dispose_name(object, inspectString);
 
-		(Error as any).stackTraceLimit = old;
+		super(`Object [${name}] has already disposed ${stacks}.`);
+		this.name = 'DuplicateDisposedError';
+		this.inspectString = inspectString;
 
-		this.inspectString = insp;
-		this.name = 'Warning';
+		Error.stackTraceLimit = old;
 
 		this.tryCreateConsoleWarning().catch(() => {});
 	}
 
 	public async tryCreateConsoleWarning() {
 		console.error('DisposedWarning: duplicate dispose.');
-		console.error(' * first   dispose:\n%s', prettyFormatError(this.previous, false));
-		console.error(' * current dispose:\n%s', prettyFormatError(this, false));
+		console.error(' * first   dispose:\n ', isNodeJs ? prettyFormatError(this.previous, false) : this.previous);
+		console.error(' * current dispose:\n ', isNodeJs ? prettyFormatError(this, false) : this);
 		console.error(' * Object: %s', this.inspectString);
 	}
-}
 
-export function isDisposedError(error: any): boolean {
-	return error instanceof DisposedError;
+	is(other: unknown): other is DuplicateDisposed {
+		return other instanceof DuplicateDisposed;
+	}
 }

package/src/lifecycle/dispose/sync-disposable.ts

@@ -0,0 +1,53 @@
+import { createStackTraceHolder, type StackTraceHolder } from '../../error/stack-trace.js';
+import { dispose_name } from './debug.js';
+import { AbstractEnhancedDisposable, type IDisposable } from './disposable.js';
+import { DuplicateDisposed } from './disposedError.js';
+
+/**
+ * 简单版手动disposable
+ */
+export abstract class DisposableOnce implements IDisposable {
+	private _disposed?: StackTraceHolder;
+
+	public get hasDisposed() {
+		return !!this._disposed;
+	}
+	public dispose(): void {
+		if (this._disposed) {
+			console.warn(new DuplicateDisposed(this, this._disposed).message);
+			return;
+		}
+		this._disposed = createStackTraceHolder('disposed', this.dispose);
+		this._dispose();
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	protected abstract _dispose(): void;
+}
+
+/**
+ * 完整版disposable类
+ * 可以继承
+ * 也可以直接用（相当于一个DisposableStack）
+ */
+export class EnhancedDisposable extends AbstractEnhancedDisposable<false> implements IDisposable {
+	protected override _dispose(disposables: readonly IDisposable[]): void {
+		for (const item of disposables.values()) {
+			try {
+				if (this._logger.enabled) this._logger(`dispose ${dispose_name(item)}`);
+				item.dispose();
+			} catch (e) {
+				if (e instanceof Error) {
+					this._onDisposeError.fire(e);
+				} else {
+					console.error('error during dispose, throw:', e);
+					this._onDisposeError.fire(new Error(`${e}`));
+				}
+			}
+		}
+	}
+
+	/// compitable with stack
+	public [Symbol.dispose] = this.dispose;
+}

package/src/lifecycle/event/event.ts

@@ -1,116 +1,100 @@
-import { createStackTraceHolder } from '../../autoindex.js';
-import { AppExit } from '../../error-wellknown/exit.error.js';
-import type { IDisposable } from '../dispose/lifecycle.js';
-
-export type EventHandler<T> = (data: T) => void;
-
-export interface EventRegister<T> {
-	(callback: EventHandler<T>): IDisposable;
-	once(callback: EventHandler<T>): IDisposable;
-}
-
-type DeferFn = () => void;
+import { Exit } from '@idlebox/errors';
+import { nameObject, objectName } from '../../debugging/object-with-name.js';
+import { createStackTraceHolder } from '../../error/stack-trace.js';
+import { functionToDisposable } from '../dispose/bridges/function.js';
+import { DuplicateDisposed } from '../dispose/disposedError.js';
+import type { IDisposable } from '../dispose/disposable.js';
+import type { EventHandler, EventRegister, IEventEmitter } from './type.js';
 
 /**
- * 事件注册对象
  * @public
  */
-export class Emitter<T> implements IDisposable {
-	protected readonly _callbacks: EventHandler<T>[] = [];
+export class Emitter<T = unknown> implements IEventEmitter<T> {
+	protected _callbacks?: (EventHandler<T> | undefined)[];
 	private executing = false;
+	private _something_change_during_call = false;
 
 	constructor(public readonly displayName?: string) {}
 
-	/**
-	 * @returns 当前注册回调数量
-	 */
 	public listenerCount() {
-		return this._callbacks.length;
+		return this._callbacks?.length ?? 0;
 	}
 
-	/**
-	 * 触发本事件
-	 * @param data 回调数据
-	 */
 	public fire(data: T) {
 		this.requireNotExecuting();
+		if (!this._callbacks) return;
+
 		this.executing = true;
 		try {
 			for (const callback of this._callbacks) {
-				callback(data);
+				callback?.(data);
 			}
 		} finally {
-			this.doDefer();
 			this.executing = false;
+			if (this._something_change_during_call) {
+				this.checkDeleted();
+			}
 		}
 	}
 
-	/**
-	 * 与 `fire()`相同，但是忽略任何错误，并且即便出错也继续执行全部callback
-	 */
 	public fireNoError(data: T) {
 		this.requireNotExecuting();
+		if (!this._callbacks) return;
+
 		this.executing = true;
 		for (const callback of this._callbacks) {
 			try {
-				callback(data);
+				callback?.(data);
 			} catch (e) {
-				if (e instanceof AppExit) {
-					continue;
+				if (e instanceof Exit) {
+					break;
 				}
 				console.error('Emitter.fireNoError: error ignored: %s', e instanceof Error ? e.stack : e);
 			}
 		}
-		this.doDefer();
 		this.executing = false;
+		if (this._something_change_during_call) {
+			this.checkDeleted();
+		}
 	}
 
 	get register(): EventRegister<T> {
 		return Object.assign(this.handle.bind(this), {
 			once: this.once.bind(this),
+			wait: this.wait.bind(this),
 		});
 	}
 
-	/**
-	 * AI喜欢用event()
-	 * @alias register
-	 */
 	get event(): EventRegister<T> {
 		return this.register;
 	}
 
 	/**
-	 * 注册本事件的新回调
-	 * @param callback 回调函数
+	 * 添加监听器
 	 */
 	handle(callback: EventHandler<T>): IDisposable {
 		this.requireNotExecuting();
-		let disposed = false;
-		this._callbacks.unshift((e) => {
-			if (!disposed) callback(e);
-		});
-		const realDispose = () => {
-			const index = this._callbacks.indexOf(callback);
-			if (index !== -1) {
-				this._callbacks.splice(index, 1);
-			}
-		};
-
-		const dispose = () => {
-			disposed = true;
-			if (this.executing) {
-				this.defer(realDispose);
-			} else {
-				realDispose();
-			}
-		};
 
-		return { dispose };
+		if (!this._callbacks) this._callbacks = [];
+
+		const callbacks = this._callbacks;
+		callbacks.unshift(callback);
+
+		return functionToDisposable(
+			nameObject(`removeListener(${objectName(callback)})`, () => {
+				const index = callbacks.indexOf(callback);
+				if (index === -1) return;
+				if (this.executing) {
+					callbacks[index] = undefined;
+				} else {
+					callbacks.splice(index, 1);
+				}
+			}),
+		);
 	}
 
 	/**
-	 * 注册一次性回调
-	 * @param callback 回调函数
+	 * 添加一次性监听器
 	 */
 	once(callback: EventHandler<T>): IDisposable {
 		this.requireNotExecuting();
@@ -121,19 +105,28 @@ export class Emitter<T> implements IDisposable {
 		return disposable;
 	}
 
-	private defers: DeferFn[] = [];
-	public defer(fn: DeferFn) {
-		this.defers.push(fn);
-	}
-	private doDefer() {
-		for (const fn of this.defers) {
-			fn();
-		}
-		this.defers.length = 0;
+	/**
+	 * 创建一个等待下次触发的promise
+	 */
+	private _waittings?: Set<Function>;
+	wait(): Promise<T> {
+		return new Promise((resolve, reject) => {
+			if (!this._waittings) this._waittings = new Set<Function>();
+			this._waittings.add(reject);
+			this.once((data) => {
+				resolve(data);
+			});
+		});
 	}
 
-	[Symbol.dispose]() {
-		this.dispose();
+	private checkDeleted() {
+		if (!this._callbacks) return;
+
+		for (let i = this._callbacks.length - 1; i >= 0; i--) {
+			if (this._callbacks[i] === undefined) {
+				this._callbacks.splice(i, 1);
+			}
+		}
 	}
 
 	private _disposed = false;
@@ -141,22 +134,36 @@ export class Emitter<T> implements IDisposable {
 		return this._disposed;
 	}
 
+	/**
+	 * 运行过程中可以dispose，本次运行仍然会继续到最后
+	 * 但立即不能再次调用类似handle的方法
+	 */
 	dispose() {
 		if (this._disposed) return;
 		this._disposed = true;
-		this.requireNotExecuting();
-		this._callbacks.length = 0;
 
-		const trace = createStackTraceHolder('disposed');
+		this._callbacks = undefined;
+
+		if (this._waittings) {
+			for (const rej of this._waittings) {
+				rej(new Error('disposed'));
+			}
+		}
+
+		this._waittings = undefined;
 
-		this.fireNoError =
+		const trace = createStackTraceHolder('disposed');
+		this.requireNotExecuting =
+			this.fireNoError =
 			this.fire =
 			this.handle =
 				() => {
-					throw new Error('Event is disposed', { cause: trace });
+					throw new DuplicateDisposed(this, trace);
 				};
 	}
 
+	readonly [Symbol.dispose] = this.dispose;
+
 	private requireNotExecuting() {
 		if (this.executing) {
 			throw new Error('conflict state, emitter is firing');