@idlebox/common 1.5.20 → 1.5.22

package/src/lifecycle/dispose/bridges/streams.ts

@@ -2,37 +2,42 @@ import { defineInspectMethod } from '../../../debugging/inspect.js';
 import { objectName } from '../../../debugging/object-with-name.js';
 import type { IAsyncDisposable } from '../disposable.js';
 
-type ClosableAsync = {
-	close(): Promise<any>;
-	close(cb: (e?: Error) => void): any;
-};
+type ClosableAsync =
+	| {
+			closed?: boolean;
+			close(): Promise<any>;
+	  }
+	| {
+			closed?: boolean;
+			close(cb: (e?: Error) => void): any;
+	  };
 
 /**
  * Convert "close()"-able object to disposable
+ *
+ * FIXME: 关闭事件不同步
+ *
  * @public
  */
 export function closableToDisposable<T extends ClosableAsync>(closable: T): IAsyncDisposable {
-	const promised = closable.close.length === 0;
-
 	return defineInspectMethod(
 		{
 			get displayName() {
 				return `closable(${objectName(closable) || 'unknown'})`;
 			},
 			dispose(): Promise<void> {
-				if (promised) {
-					return Promise.resolve(closable.close()).then(() => undefined);
-				} else {
-					return new Promise<void>((resolve, reject) => {
-						closable.close((error) => {
-							if (error) {
-								reject(error);
-							} else {
-								resolve();
-							}
-						});
+				return new Promise<void>((resolve, reject) => {
+					const mayPromise = closable.close((error) => {
+						if (error) {
+							reject(error);
+						} else {
+							resolve();
+						}
 					});
-				}
+					if (typeof mayPromise?.then === 'function') {
+						mayPromise.then(resolve, reject);
+					}
+				});
 			},
 		},
 		(_depth, options) => {
@@ -41,37 +46,42 @@ export function closableToDisposable<T extends ClosableAsync>(closable: T): IAsy
 	);
 }
 
-type EndableAsync = {
-	end(): Promise<any>;
-	end(cb: (e?: Error) => void): any;
-};
+type EndableAsync =
+	| {
+			ended?: boolean;
+			end(): Promise<any>;
+	  }
+	| {
+			ended?: boolean;
+			end(cb: (e?: Error) => void): any;
+	  };
 
 /**
  * Convert "end()"-able object to disposable
+ *
+ * FIXME: 关闭事件不同步
+ *
  * @public
  */
 export function endableToDisposable<T extends EndableAsync>(endable: T): IAsyncDisposable {
-	const promised = endable.end.length === 0;
-
 	return defineInspectMethod(
 		{
 			get displayName() {
 				return `endable(${objectName(endable) || 'unknown'})`;
 			},
 			dispose(): Promise<void> {
-				if (promised) {
-					return Promise.resolve(endable.end()).then(() => undefined);
-				} else {
-					return new Promise<void>((resolve, reject) => {
-						return endable.end((error) => {
-							if (error) {
-								reject(error);
-							} else {
-								resolve();
-							}
-						});
+				return new Promise<void>((resolve, reject) => {
+					const mayPromise = endable.end((error) => {
+						if (error) {
+							reject(error);
+						} else {
+							resolve();
+						}
 					});
-				}
+					if (typeof mayPromise?.then === 'function') {
+						mayPromise.then(resolve, reject);
+					}
+				});
 			},
 		},
 		(_depth, options) => {

package/src/lifecycle/dispose/disposable.ts

@@ -1,7 +1,9 @@
 import { defineInspectMethod } from '../../debugging/inspect.js';
 import type { MaybeNamed } from '../../debugging/object-with-name.js';
+import { convertCaughtError } from '../../error/convert-unknown.js';
+import { prettyPrintError } from '../../error/pretty.nodejs.js';
 import { createStackTraceHolder, type StackTraceHolder } from '../../error/stack-trace.js';
-import { definePublicConstant } from '../../object/definePublicConstant.js';
+import { isPromiseLike } from '../../promise/is-promise.js';
 import { Emitter } from '../event/event.js';
 import type { EventRegister } from '../event/type.js';
 import { fromNativeDisposable } from './bridges/native.js';
@@ -15,10 +17,14 @@ export enum DuplicateDisposeAction {
 }
 
 /** @public */
-export interface IDisposableEvents {
-	onDisposeError: EventRegister<Error>;
-	onBeforeDispose: EventRegister<void>;
-	readonly hasDisposed: boolean;
+export interface IDisposableEvents extends IBackReferenceDisposableEvent {
+	readonly onDisposeError: EventRegister<Error>;
+	readonly onPostDispose: EventRegister<void>;
+	readonly disposed: boolean;
+}
+
+export interface IBackReferenceDisposableEvent {
+	readonly onBeforeDispose: EventRegister<void>;
 }
 
 /** @public */
@@ -34,6 +40,22 @@ export interface IAsyncDisposable extends MaybeNamed {
 type _Type<Async extends boolean> = Async extends true ? IAsyncDisposable : IDisposable;
 type _RType<Async extends boolean> = Async extends true ? Promise<void> : void;
 
+interface IDisposeState<Async extends boolean> {
+	/**
+	 * 存在stack说明dispose已经开始（可能已经完成）
+	 */
+	trace?: StackTraceHolder;
+	finished: boolean;
+	/**
+	 * 同步的是undefined，异步的是Promise
+	 */
+	result?: _RType<Async>;
+	/**
+	 * 只有同步的用到，每次调用始终抛出相同错误，异步通过promise保存状态
+	 */
+	error?: Error;
+}
+
 /**
  * 增强型Disposable
  */
@@ -69,11 +91,11 @@ export abstract class AbstractEnhancedDisposable<Async extends boolean> implemen
 			return `[Function debug]`;
 		});
 
-		this._onDisposeError = this._register(new Emitter<Error>(`${this.displayName}:errorEvent`));
+		this._onDisposeError = new Emitter<Error>(`${this.displayName}:errorEvent`, Emitter.EAction.PrintIgnore);
 		this.onDisposeError = this._onDisposeError.register;
-		this._onBeforeDispose = this._register(new Emitter<void>(`${this.displayName}:beforeEvent`));
+		this._onBeforeDispose = new Emitter<void>(`${this.displayName}:beforeEvent`, Emitter.EAction.PrintIgnore);
 		this.onBeforeDispose = this._onBeforeDispose.register;
-		this._onPostDispose = new Emitter<void>(`${this.displayName}:postEvent`);
+		this._onPostDispose = new Emitter<void>(`${this.displayName}:postEvent`, Emitter.EAction.PrintIgnore);
 		this.onPostDispose = this._onPostDispose.register;
 	}
 
@@ -81,8 +103,8 @@ export abstract class AbstractEnhancedDisposable<Async extends boolean> implemen
 	 * @throws if already disposed
 	 */
 	public assertNotDisposed() {
-		if (this._disposed) {
-			throw new DuplicateDisposedError(this, this._disposed.trace);
+		if (this.__dispose_state.trace) {
+			throw new DuplicateDisposedError(this, this.__dispose_state.trace);
 		}
 	}
 
@@ -90,14 +112,15 @@ export abstract class AbstractEnhancedDisposable<Async extends boolean> implemen
 	 * 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<T extends _Type<Async> & IBackReferenceDisposableEvent>(d: T, autoDereference?: boolean): T;
 	public _register(d: any, autoDereference?: boolean): any {
 		if (this._logger.enabled) this._logger(`register ${dispose_name(d)}`);
 		this.assertNotDisposed();
 		if (this._disposables.indexOf(d) !== -1) throw new Error(`disposable object ${dispose_name(d)} has already registed into "${dispose_name(this)}"`);
 		this._disposables.unshift(fromNativeDisposable(d));
 		if (autoDereference) {
-			(d as IDisposableEvents).onBeforeDispose(() => {
+			(d as IBackReferenceDisposableEvent).onBeforeDispose(() => {
+				if (this.disposing || this.disposed) return;
 				this._unregister(d);
 			});
 		}
@@ -117,52 +140,88 @@ export abstract class AbstractEnhancedDisposable<Async extends boolean> implemen
 		return rmOk;
 	}
 
-	private _disposed?: {
-		trace: StackTraceHolder;
-		result: _RType<Async>;
-	};
+	private __dispose_state: IDisposeState<Async> = { finished: false };
 	public get disposed() {
-		return !!this._disposed;
+		return this.__dispose_state.finished;
 	}
+
 	/**
-	 * @deprecated use disposed
+	 * 正在dispose中（已开始但未完成）
 	 */
-	public get hasDisposed() {
-		return !!this._disposed;
+	public get disposing() {
+		return !this.__dispose_state.finished && !!this.__dispose_state.trace;
 	}
 
 	/**
 	 * 释放相关资源
 	 */
 	public dispose(): _RType<Async> {
-		if (this._disposed) {
-			if (this.duplicateDispose === DuplicateDisposeAction.Allow) return this._disposed.result;
+		if (this.__dispose_state.trace) {
+			// 释放已开始或已结束
+			if (this.duplicateDispose === DuplicateDisposeAction.Allow) {
+				if (this.__dispose_state.error) {
+					throw this.__dispose_state.error;
+				} else {
+					/**
+					 * biome-ignore lint/style/noNonNullAssertion: 完全无需考虑
+					 *
+					 * 异步dispose的同步部分，重复调用dispose，会返回undefined而非Promise
+					 * 但这正好是希望的，否则死锁了
+					 */
+					return this.__dispose_state.result!;
+				}
+			}
 
-			const dupErr = new DuplicateDisposedError(this, this._disposed.trace);
+			const dupErr = new DuplicateDisposedError(this, this.__dispose_state.trace);
 			dupErr.consoleWarning();
 			if (this.duplicateDispose === DuplicateDisposeAction.Disable) {
 				throw dupErr;
 			} else {
-				return this._disposed.result;
+				return this.__dispose_state.result as any;
 			}
+			// never
 		}
-		this._onBeforeDispose.fireNoError();
 
-		const r = this._dispose(this._disposables);
-		const trace = createStackTraceHolder('disposed', this.dispose);
 		const cleanup = () => {
-			definePublicConstant(this, '_disposed', {
-				// 记录 disposed 状态，顺便也记录调用栈
-				trace: trace,
-				result: r,
-			});
+			this.__dispose_state.finished = true;
 
 			Object.assign(this, { _disposables: null });
-			this._onPostDispose.fireNoError();
+			this._onPostDispose.fire();
 			this._onPostDispose.dispose();
+
+			this._onDisposeError.dispose();
 		};
-		if (r && 'then' in r) {
-			r.finally(cleanup);
+
+		// 第一时间设置trace
+		this.__dispose_state.trace = createStackTraceHolder('disposed', this.dispose);
+
+		this._onBeforeDispose.fire();
+		this._onBeforeDispose.dispose();
+
+		try {
+			this.__dispose_state.result = this._dispose(this._disposables);
+		} catch (e) {
+			// 同步错误处理
+			const err = convertCaughtError(e);
+			this.__dispose_state.error = err;
+			this._onDisposeError.fire(err);
+			if (this._onDisposeError.listenerCount() === 0) {
+				prettyPrintError('unhandled sync dispose error', err);
+			}
+			cleanup();
+			throw this.__dispose_state.error;
+		}
+
+		const r = this.__dispose_state.result;
+		if (isPromiseLike(r)) {
+			// 异步错误处理
+			r.catch((e) => {
+				e = convertCaughtError(e);
+				this._onDisposeError.fire(e);
+				if (this._onDisposeError.listenerCount() === 0) {
+					prettyPrintError('unhandled async dispose error', e);
+				}
+			}).finally(cleanup);
 		} else {
 			cleanup();
 		}

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

@@ -10,7 +10,7 @@ import { DuplicateDisposedError } from './disposedError.js';
 export abstract class DisposableOnce implements IDisposable {
 	private _disposed?: StackTraceHolder;
 
-	public get hasDisposed() {
+	public get disposed() {
 		return !!this._disposed;
 	}
 	public dispose(): void {
@@ -32,21 +32,37 @@ export abstract class DisposableOnce implements IDisposable {
  * 完整版disposable类
  * 可以继承
  * 也可以直接用（相当于一个DisposableStack）
+ *
+ * 抛出异常的行为会延迟到所有资源都尝试释放完毕之后，因此显然只会抛出其中一个异常给dispose()的调用者
+ * 每一个资源释放失败，都会分别触发onDisposeError事件，如果此事件存在监听器，则最后不会抛出异常（处非监听器本身重新抛出）
+ * 不支持在dispose过程中添加onError事件监听器
+ *
  */
 export class EnhancedDisposable extends AbstractEnhancedDisposable<false> implements IDisposable {
 	protected override _dispose(disposables: readonly IDisposable[]): void {
+		const hasListener = this._onDisposeError.listenerCount() > 0;
+
+		let lastError = null;
 		for (const item of disposables.values()) {
 			try {
 				if (this._logger.enabled) this._logger(`dispose ${dispose_name(item)}`);
 				item.dispose();
 			} catch (e) {
-				const ee = convertCaughtError(e);
-				this._onDisposeError.fire(ee);
-				if (!this._onDisposeError.listenerCount()) {
-					console.error('Unhandled error during dispose: %s', ee.stack);
+				if (hasListener) {
+					try {
+						this._onDisposeError.fire(convertCaughtError(e));
+					} catch (e) {
+						lastError = e;
+					}
+				} else {
+					lastError = e;
 				}
 			}
 		}
+
+		if (lastError) {
+			throw lastError;
+		}
 	}
 
 	/// compitable with stack

package/src/lifecycle/event/event.ts

@@ -1,6 +1,7 @@
-import { Exit } from '@idlebox/errors';
 import { defineInspectMethod, inspectSymbol } from '../../debugging/inspect.js';
 import { nameObject, objectName } from '../../debugging/object-with-name.js';
+import { convertCaughtError } from '../../error/convert-unknown.js';
+import { prettyPrintError } from '../../error/pretty.nodejs.js';
 import { createStackTraceHolder } from '../../error/stack-trace.js';
 import { functionToDisposable } from '../dispose/bridges/function.js';
 import type { IDisposable } from '../dispose/disposable.js';
@@ -9,15 +10,27 @@ import type { EventHandler, EventRegister, IEventEmitter } from './type.js';
 
 const anonymousName = 'AnonymousEmitter';
 
+enum FireErrorAction {
+	Throw = 0,
+	Delay = 1,
+	Ignore = 2,
+	PrintIgnore = 3,
+}
+
 /**
  * @public
  */
 export class Emitter<T = unknown> implements IEventEmitter<T> {
-	protected _callbacks?: (EventHandler<T> | undefined)[];
+	protected readonly _callbacks: (EventHandler<T> | undefined)[] = [];
 	private executing = false;
 	private _something_change_during_call = false;
 
-	constructor(public readonly displayName: string = anonymousName) {
+	static readonly EAction = FireErrorAction;
+
+	constructor(
+		public readonly displayName: string = anonymousName,
+		private readonly onErrorDefault: FireErrorAction = FireErrorAction.Throw,
+	) {
 		this.handle = Object.defineProperties(this.handle.bind(this), {
 			once: {
 				get: () => this.once.bind(this),
@@ -25,7 +38,7 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 			wait: {
 				get: () => this.wait.bind(this),
 			},
-			hasDisposed: {
+			disposed: {
 				get: () => this._disposed,
 			},
 		});
@@ -35,17 +48,69 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 	}
 
 	public listenerCount() {
-		return this._callbacks?.length ?? 0;
+		return this._callbacks.length;
+	}
+
+	private __fireThrow(data: T) {
+		for (const callback of this._callbacks) {
+			callback?.(data);
+		}
+	}
+	private __fireDelay(data: T) {
+		const errors: Error[] = [];
+		for (const callback of this._callbacks) {
+			try {
+				callback?.(data);
+			} catch (e) {
+				errors.push(convertCaughtError(e));
+			}
+		}
+		return errors;
+	}
+	private __fireIgnore(data: T) {
+		for (const callback of this._callbacks) {
+			try {
+				callback?.(data);
+			} catch {}
+		}
+	}
+	private __firePrintIgnore(data: T) {
+		for (const callback of this._callbacks) {
+			try {
+				callback?.(data);
+			} catch (e) {
+				const ee = convertCaughtError(e);
+				prettyPrintError('error while handling event', ee);
+			}
+		}
 	}
 
-	public fire(data: T) {
+	/**
+	 * @param data
+	 * @param error {Emitter.EAction} 如何处理错误
+	 *  - Throw: 默认行为，遇到错误立即抛出，后续监听器不再被调用
+	 *  - Delay: 等所有监听器都调用完后，如果有错误则抛出AggregateError，包含所有错误
+	 *  - Ignore: 忽略所有错误，继续调用全部监听器
+	 *  - PrintIgnore: 忽略所有错误，但打印错误信息
+	 * @returns
+	 */
+	public fire(data: T, error = this.onErrorDefault) {
 		this.requireNotExecuting();
-		if (!this._callbacks) return;
+		if (!this._callbacks.length) return;
 
 		this.executing = true;
 		try {
-			for (const callback of this._callbacks) {
-				callback?.(data);
+			if (error === FireErrorAction.Throw) {
+				this.__fireThrow(data);
+			} else if (error === FireErrorAction.Delay) {
+				const errors = this.__fireDelay(data);
+				if (errors.length) {
+					throw new AggregateError(errors, 'multiple errors while handling event');
+				}
+			} else if (error === FireErrorAction.Ignore) {
+				this.__fireIgnore(data);
+			} else if (error === FireErrorAction.PrintIgnore) {
+				this.__firePrintIgnore(data);
 			}
 		} finally {
 			this.executing = false;
@@ -55,25 +120,9 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 		}
 	}
 
+	/** @deprecated use fire(data, Emitter.Error.Ignore) */
 	public fireNoError(data: T) {
-		this.requireNotExecuting();
-		if (!this._callbacks) return;
-
-		this.executing = true;
-		for (const callback of this._callbacks) {
-			try {
-				callback?.(data);
-			} catch (e) {
-				if (e instanceof Exit) {
-					break;
-				}
-				console.error('Emitter.fireNoError: error ignored: %s', e instanceof Error ? e.stack : e);
-			}
-		}
-		this.executing = false;
-		if (this._something_change_during_call) {
-			this.checkDeleted();
-		}
+		this.fire(data, FireErrorAction.Ignore);
 	}
 
 	get register(): EventRegister<T> {
@@ -91,20 +140,17 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 	handle(callback: EventHandler<T>): IDisposable {
 		this.requireNotExecuting();
 
-		if (!this._callbacks) this._callbacks = [];
-
-		const callbacks = this._callbacks;
-		callbacks.unshift(callback);
+		this._callbacks.unshift(callback);
 
 		return functionToDisposable(
 			nameObject(`removeListener(${objectName(callback)})`, () => {
-				const index = callbacks.indexOf(callback);
+				const index = this._callbacks.indexOf(callback);
 				if (index === -1) return;
 				if (this.executing) {
 					this._something_change_during_call = true;
-					callbacks[index] = undefined;
+					this._callbacks[index] = undefined;
 				} else {
-					callbacks.splice(index, 1);
+					this._callbacks.splice(index, 1);
 				}
 			}),
 		);
@@ -147,7 +193,7 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 	}
 
 	private _disposed = false;
-	public get hasDisposed() {
+	public get disposed() {
 		return this._disposed;
 	}
 
@@ -159,7 +205,8 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 		if (this._disposed) return;
 		this._disposed = true;
 
-		this._callbacks = undefined;
+		this._callbacks.length = 0;
+		Object.assign(this, { _callbacks: null });
 
 		if (this._waittings) {
 			for (const rej of this._waittings) {
@@ -169,7 +216,7 @@ export class Emitter<T = unknown> implements IEventEmitter<T> {
 
 		this._waittings = undefined;
 
-		const trace = createStackTraceHolder('disposed');
+		const trace = createStackTraceHolder('disposed', this.dispose);
 
 		const makeUnCallable = (name: string) => {
 			Object.assign(this, {

package/src/lifecycle/event/type.ts

@@ -53,7 +53,7 @@ export interface IEventEmitter<T = unknown> extends IDisposable {
 	 */
 	wait(): Promise<T>;
 
-	readonly hasDisposed: boolean;
+	readonly disposed: boolean;
 }
 
 export type EventHandler<T> = (data: T) => void;
@@ -65,7 +65,7 @@ export interface EventRegister<T> {
 	(callback: EventHandler<T>): IDisposable;
 	once(callback: EventHandler<T>): IDisposable;
 	wait(): IDisposable;
-	readonly hasDisposed: boolean;
+	readonly disposed: boolean;
 }
 
 export type EventEmitterMap<T extends Record<string, unknown>> = {

package/src/map-and-set/required-map.ts

@@ -37,6 +37,10 @@ export class RequiredMap<K, V> extends Map<K, V> {
 	}
 }
 
+if (Map.prototype.getOrInsert) {
+	RequiredMap.prototype.get = Map.prototype.getOrInsert as any;
+}
+
 /**
  * A map that holds instances, automatically create new instance
  */
@@ -56,3 +60,9 @@ export abstract class InstanceMap<K, V> extends Map<K, V> {
 		return nv;
 	}
 }
+
+if (typeof Map.prototype.getOrInsertComputed === 'function') {
+	RequiredMap.prototype.get = function (this: InstanceMap<any, any>, id: any): any {
+		return this.getOrInsertComputed(id, (k) => this.instance(k));
+	};
+}

package/src/promise/deferred-promise.ts

@@ -1,6 +1,5 @@
 import { CanceledError, TimeoutError } from '@idlebox/errors';
 import type { IDisposable } from '../lifecycle/dispose/disposable.js';
-import type { TimeoutType } from '../schedule/local-type.js';
 import { scheduler } from '../schedule/scheduler.js';
 
 export type ValueCallback<T = any> = (value: T | Promise<T>) => void;
@@ -143,16 +142,16 @@ export class DeferredPromise<T, PT = any> {
 		};
 	}
 
-	#timer?: TimeoutType;
+	private timer?: ITimeoutType;
 	#cancel_timeout() {
-		if (this.#timer) {
-			clearTimeout(this.#timer);
-			this.#timer = undefined;
+		if (this.timer) {
+			clearTimeout(this.timer);
+			this.timer = undefined;
 		}
 	}
 	timeout(ms: number) {
 		if (this.settled) throw new Error('no more timeout after settled');
-		this.#timer = setTimeout(() => {
+		this.timer = setTimeout(() => {
 			this.error(new TimeoutError(ms, 'promise not settled'));
 		}, ms);
 

package/src/promise/is-promise.ts

@@ -0,0 +1,3 @@
+export function isPromiseLike(object: unknown): object is PromiseLike<unknown> {
+	return typeof object === 'object' && object !== null && typeof (object as any).then === 'function';
+}

package/src/re-export.ts

@@ -1,4 +1,3 @@
-/// <reference types="@idlebox/itypes" />
 /// <reference types="debug" />
 
 export * from '@idlebox/errors';

package/src/schedule/extendable-timer.ts

@@ -1,12 +1,11 @@
 import { DeferredPromise } from '../promise/deferred-promise.js';
-import type { TimeoutType } from './local-type.js';
 
 /**
  * 反复推迟的 setTimeout
  */
 export class ExtendableTimer {
 	private readonly dfd = new DeferredPromise<void>();
-	private tmr?: TimeoutType;
+	public tmr?: ITimeoutType;
 
 	constructor(private readonly durationMs: number) {}