@idlebox/common 1.4.11 → 1.4.13

package/src/lifecycle/dispose/lifecycle.async.ts

@@ -1,9 +1,14 @@
+import type debug from 'debug';
 import { convertCatchedError } from '../../error/convertUnknown.js';
 import { Emitter, type EventRegister } from '../event/event.js';
 import { _debug_dispose, dispose_name } from './debug.js';
 import { DisposedError } from './disposedError.js';
 import type { IAsyncDisposable, IDisposableEvents } from './lifecycle.js';
 
+interface _DOMAsyncDisposable {
+	[Symbol.asyncDispose](): Promise<void>;
+}
+
 /**
  * Async version of Disposable
  * @public
@@ -18,11 +23,20 @@ export class AsyncDisposable implements IAsyncDisposable, IDisposableEvents {
 	public readonly onBeforeDispose: EventRegister<void> = this._onBeforeDispose.register;
 
 	private _disposed?: Error;
+	public readonly displayName?: string;
 
 	/** @internal */
-	readonly #logger;
-	constructor(public readonly displayName?: string) {
-		this.#logger = _debug_dispose.extend(this.displayName || 'async-disposable');
+	protected readonly _logger: debug.Debugger;
+
+	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);
 	}
 
 	public get hasDisposed() {
@@ -44,7 +58,7 @@ export class AsyncDisposable implements IAsyncDisposable, IDisposableEvents {
 	public _register<T extends IAsyncDisposable>(d: T): T;
 	public _register<T extends IAsyncDisposable & IDisposableEvents>(d: T, autoDereference?: boolean): T;
 	public _register<T extends IAsyncDisposable | (IAsyncDisposable & IDisposableEvents)>(d: T, deref?: boolean): T {
-		if (this.#logger.enabled) this.#logger(`register ${dispose_name(d)}`);
+		if (this._logger.enabled) this._logger(`register ${dispose_name(d)}`);
 		this.assertNotDisposed();
 		this._disposables.unshift(d);
 		if (deref) {
@@ -56,27 +70,64 @@ export class AsyncDisposable implements IAsyncDisposable, IDisposableEvents {
 	}
 
 	public _unregister(d: IAsyncDisposable) {
-		if (this.#logger.enabled) this.#logger(`unregister ${dispose_name(d)}`);
+		if (this._logger.enabled) this._logger(`unregister ${dispose_name(d)}`);
 		return this._disposables.splice(this._disposables.indexOf(d), 1).length > 0;
 	}
 
-	public async dispose(): Promise<void> {
+	protected __finalize_dispose() {
 		if (this._disposed) {
 			console.warn(new DisposedError(this, this._disposed).message);
-			return;
+			return [];
 		}
+
 		this._onBeforeDispose.fireNoError();
 		this._disposed = new Error('disposed');
 
 		this._disposables.push(this._onBeforeDispose);
 		this._disposables.push(this._onDisposeError);
-		for (const cb of this._disposables) {
+
+		return this._disposables;
+	}
+
+	[Symbol.asyncDispose]() {
+		return this.dispose();
+	}
+	static fromWeb(disposable: _DOMAsyncDisposable): IAsyncDisposable {
+		if (!('dispose' in disposable)) {
+			Object.assign(disposable, { dispose: disposable[Symbol.asyncDispose] });
+		}
+		return disposable as unknown as IAsyncDisposable;
+	}
+	toWeb(): _DOMAsyncDisposable {
+		return this;
+	}
+
+	public async dispose(): Promise<void> {
+		for (const cb of this.__finalize_dispose()) {
 			try {
-				if (this.#logger.enabled) this.#logger(`dispose ${dispose_name(cb)}`);
+				if (this._logger.enabled) this._logger(`dispose ${dispose_name(cb)}`);
 				await cb.dispose();
 			} catch (e) {
-				this._onDisposeError.fire(convertCatchedError(e));
+				this._onDisposeError.fireNoError(convertCatchedError(e));
 			}
 		}
 	}
 }
+
+/**
+ * @internal
+ */
+export class AsyncDisposableUnordered extends AsyncDisposable {
+	override async dispose() {
+		const ps = this.__finalize_dispose().map((d) => {
+			if (this._logger.enabled) this._logger(`dispose ${dispose_name(d)}`);
+			return Promise.resolve()
+				.then(() => d.dispose())
+				.catch((e) => {
+					this._onDisposeError.fireNoError(convertCatchedError(e));
+				});
+		});
+
+		await Promise.allSettled(ps);
+	}
+}

package/src/lifecycle/dispose/lifecycle.global.ts

@@ -1,13 +1,13 @@
 import { globalSingletonStrong } from '../../platform/globalSingleton.js';
 import { createSymbol } from '../../platform/globalSymbol.js';
 import { _debug_dispose } from './debug.js';
-import { AsyncDisposable } from './lifecycle.async.js';
+import { AsyncDisposable, AsyncDisposableUnordered } from './lifecycle.async.js';
 import type { IDisposable } from './lifecycle.js';
 
 const symbol = createSymbol('lifecycle', 'application');
 
-function create() {
-	return new AsyncDisposable('global');
+function create(): AsyncDisposable {
+	return new AsyncDisposableUnordered('global');
 }
 
 const logger = _debug_dispose.extend('global');
@@ -21,6 +21,8 @@ export function registerGlobalLifecycle(object: IDisposable) {
 
 /**
  * Same as disposeGlobal, but do not throw by duplicate call
+ * 
+ * Never throws when child object dispose failed
  */
 export function ensureDisposeGlobal() {
 	const obj = globalSingletonStrong<AsyncDisposable>(symbol);

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

@@ -3,6 +3,10 @@ import { _debug_dispose, dispose_name } from './debug.js';
 import { DisposedError } from './disposedError.js';
 import type { IDisposable, IDisposableEvents } from './lifecycle.js';
 
+interface _DOMDisposable {
+	[Symbol.dispose](): void;
+}
+
 export abstract class DisposableOnce implements IDisposable {
 	private _disposed?: Error;
 
@@ -18,6 +22,18 @@ export abstract class DisposableOnce implements IDisposable {
 		this._dispose();
 	}
 
+	toWeb(): _DOMDisposable {
+		return this;
+	}
+	static fromWeb(disposable: _DOMDisposable): IDisposable {
+		if (!('dispose' in disposable)) {
+			Object.assign(disposable, { dispose: disposable[Symbol.dispose] });
+		}
+		return disposable as unknown as IDisposable;
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
 	protected abstract _dispose(): void;
 }
 
@@ -38,7 +54,7 @@ export class Disposable implements IDisposable, IDisposableEvents {
 	/** @internal */
 	readonly #logger;
 	constructor(public readonly displayName?: string) {
-		this.#logger = _debug_dispose.extend(this.displayName || 'async-disposable');
+		this.#logger = _debug_dispose.extend(this.displayName || 'disposable');
 	}
 
 	public get hasDisposed() {
@@ -76,6 +92,19 @@ export class Disposable implements IDisposable, IDisposableEvents {
 		return this._disposables.splice(this._disposables.indexOf(d), 1).length > 0;
 	}
 
+	toWeb(): _DOMDisposable {
+		return this;
+	}
+	static fromWeb(disposable: _DOMDisposable): IDisposable {
+		if (!('dispose' in disposable)) {
+			Object.assign(disposable, { dispose: disposable[Symbol.dispose] });
+		}
+		return disposable as unknown as IDisposable;
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+
 	public dispose(): void {
 		if (this._disposed) {
 			console.warn(new DisposedError(this, this._disposed).message);
@@ -88,7 +117,7 @@ export class Disposable implements IDisposable, IDisposableEvents {
 		this._disposables.push(this._onDisposeError);
 		for (const item of this._disposables.values()) {
 			try {
-				if (this.#logger.enabled) this.#logger(`register ${dispose_name(item)}`);
+				if (this.#logger.enabled) this.#logger(`dispose ${dispose_name(item)}`);
 				item.dispose();
 			} catch (e) {
 				if (e instanceof Error) {

package/src/lifecycle/dispose/lifecycle.ts

@@ -13,8 +13,12 @@ export interface IDisposableEvents {
 export interface IDisposable {
 	dispose(): void;
 
-	name?: string;
-	displayName?: string;
+	readonly name?: string;
+	readonly displayName?: string;
+
+	// [Symbol.dispose]?(): void;
+	/** @internal do not use/rely */
+	// [Symbol.asyncDispose]?(): Promise<void>;
 }
 
 /** @public */
@@ -23,12 +27,46 @@ export interface IAsyncDisposable {
 
 	name?: string;
 	displayName?: string;
+
+	// [Symbol.dispose]?(): void | Promise<void>;
+	// [Symbol.asyncDispose]?(): void | Promise<void>;
 }
 
 /**
  * Convert "dispose function" to disposable object
  * @public
  */
-export function toDisposable(fn: () => void): IDisposable {
-	return { dispose: fn };
+export function toDisposable(fn_or_obj: Disposable | AsyncDisposable | (() => void)): IDisposable {
+	if (typeof fn_or_obj === 'function') {
+		return {
+			get displayName() {
+				return `toDisposable(${fn_or_obj.name || 'anonymous'})`;
+			},
+			dispose: fn_or_obj,
+		};
+	} else if (Symbol.dispose in fn_or_obj) {
+		const obj = fn_or_obj as any;
+		return {
+			get displayName() {
+				return `toDisposable[Disposable](${obj.displayName || obj.name || obj.constructor.name || 'unknown'})`;
+			},
+			dispose() {
+				fn_or_obj[Symbol.dispose]();
+			},
+		};
+	} else if (Symbol.asyncDispose in fn_or_obj) {
+		const obj = fn_or_obj as any;
+		return {
+			get displayName() {
+				return `toDisposable[AsyncDisposable](${obj.displayName || obj.name || obj.constructor.name || 'unknown'})`;
+			},
+			dispose() {
+				return fn_or_obj[Symbol.asyncDispose]();
+			},
+		};
+	} else {
+		throw new TypeError('toDisposable: expected function or object with Symbol.dispose or Symbol.asyncDispose', {
+			cause: fn_or_obj,
+		});
+	}
 }

package/src/lifecycle/event/event.ts

@@ -1,8 +1,11 @@
+import { AppExit } from '../../autoindex.js';
 import type { IDisposable } from '../dispose/lifecycle.js';
 
 export type EventHandler<T> = (data: T) => void;
 
-export type EventRegister<T> = (callback: EventHandler<T>) => IDisposable;
+export type EventRegister<T> = ((callback: EventHandler<T>) => IDisposable) & {
+	once(callback: EventHandler<T>): IDisposable;
+};
 
 type DeferFn = () => void;
 
@@ -14,9 +17,7 @@ export class Emitter<T> implements IDisposable {
 	protected readonly _callbacks: EventHandler<T>[] = [];
 	private executing = false;
 
-	constructor(public readonly displayName?: string) {
-		this.handle = this.handle.bind(this);
-	}
+	constructor(public readonly displayName?: string) {}
 
 	/**
 	 * @returns 当前注册回调数量
@@ -52,18 +53,28 @@ export class Emitter<T> implements IDisposable {
 			try {
 				callback(data);
 			} catch (e) {
-				console.error('Error ignored: ', e);
+				if (e instanceof AppExit) {
+					continue;
+				}
+				console.error('Error ignored: %s', e instanceof Error ? e.message : e);
 			}
 		}
 		this.doDefer();
 		this.executing = false;
 	}
 
+	get register(): EventRegister<T> {
+		return Object.assign(this.handle.bind(this), {
+			once: this.once.bind(this),
+		});
+	}
+
 	/**
-	 * 获取handle()方法的引用
+	 * AI喜欢用event()
+	 * @alias register
 	 */
-	get register(): EventRegister<T> {
-		return this.handle;
+	get event(): EventRegister<T> {
+		return this.register;
 	}
 
 	/**
@@ -82,16 +93,17 @@ export class Emitter<T> implements IDisposable {
 				this._callbacks.splice(index, 1);
 			}
 		};
-		return {
-			dispose: () => {
-				disposed = true;
-				if (this.executing) {
-					this.defer(realDispose);
-				} else {
-					realDispose();
-				}
-			},
+
+		const dispose = () => {
+			disposed = true;
+			if (this.executing) {
+				this.defer(realDispose);
+			} else {
+				realDispose();
+			}
 		};
+
+		return { dispose };
 	}
 
 	/**
@@ -118,6 +130,9 @@ export class Emitter<T> implements IDisposable {
 		this.defers.length = 0;
 	}
 
+	[Symbol.dispose]() {
+		this.dispose();
+	}
 	dispose() {
 		this.requireNotExecuting();
 		this._callbacks.length = 0;

package/src/lifecycle/promise/deferredPromise.ts

@@ -30,10 +30,15 @@ export class DeferredPromise<T, PT = any> {
 					this.progress(fn);
 					return this.p;
 				},
-			}
+			},
 		);
 	}
 
+	/**
+	 * notify progress to callbacks
+	 * @param progress argument
+	 * @returns 
+	 */
 	notify(progress: PT): this {
 		if (this.#success !== undefined) throw new Error('no more event after settled');
 		for (const cb of this.#progressList) {
@@ -42,24 +47,36 @@ export class DeferredPromise<T, PT = any> {
 		return this;
 	}
 
+	/**
+	 * register a progress callback
+	 * @param fn progress callback function, will be called when notify is called
+	 * @returns 
+	 */
 	progress(fn: ProgressCallback<PT>): IDisposable {
 		if (this.#success !== undefined) throw new Error('no more listener after settled');
 		this.#progressList.push(fn);
 
+		const dispose = () => {
+			const index = this.#progressList.indexOf(fn);
+			if (index >= 0) {
+				this.#progressList.splice(index, 1);
+			}
+		};
 		return {
-			dispose: () => {
-				const index = this.#progressList.indexOf(fn);
-				if (index >= 0) {
-					this.#progressList.splice(index, 1);
-				}
-			},
+			dispose,
 		};
 	}
 
+	/**
+	 * whether the promise is still working (not completed)
+	 */
 	get working(): boolean {
 		return this.#success === undefined;
 	}
 
+	/**
+	 * whether the promise is completed (resolved or rejected)
+	 */
 	get completed(): boolean {
 		return this.#success !== undefined;
 	}
@@ -91,7 +108,7 @@ export class DeferredPromise<T, PT = any> {
 	}
 
 	/**
-	 * reject the promise with CancelError
+	 * reject the deferred with {CancelError}
 	 */
 	cancel() {
 		this.#success = false;
@@ -115,7 +132,7 @@ export class DeferredPromise<T, PT = any> {
 			},
 			(e) => {
 				p.error(e);
-			}
+			},
 		);
 		return p;
 	}

package/src/lifecycle/timeout/interval.ts

@@ -0,0 +1,60 @@
+import type { IDisposable } from '../dispose/lifecycle.js';
+import { Disposable } from '../dispose/lifecycle.sync.js';
+import { Emitter } from '../event/event.js';
+
+/**
+ * @param unref defaults to `false`, when true, call `unref()` on the timer.
+ *            can not set to `true` on other platform.
+ * @returns dispose will stop the interval
+ */
+export function interval(ms: number, action: () => void, unref = false) {
+	let timer: number | undefined = setInterval(action, ms);
+	// unref is not supported in browser
+	if (unref) (timer as any).unref();
+
+	return {
+		dispose: () => {
+			if (!timer) return;
+			clearInterval(timer);
+			timer = undefined;
+		},
+	};
+}
+
+/**
+ * A simple interval class.
+ * 
+ * mainly use for pause/resume several times.
+ */
+export class Interval extends Disposable {
+	private readonly _emitter = this._register(new Emitter<void>());
+	public readonly onTick = this._emitter.event;
+	private timer?: IDisposable;
+
+	constructor(
+		private readonly ms: number,
+		private readonly unref = false,
+	) {
+		super();
+		this.fire = this.fire.bind(this);
+	}
+
+	fire() {
+		this._emitter.fire();
+	}
+
+	resume() {
+		if (this.timer) return;
+		this.timer = interval(this.ms, this.fire, this.unref);
+	}
+
+	pause() {
+		if (!this.timer) return;
+		this.timer.dispose();
+	}
+
+	override dispose() {
+		if (this.timer) this.timer.dispose();
+		return super.dispose();
+	}
+}

package/src/lifecycle/timeout/timeout.ts

@@ -1,38 +1,50 @@
-import { TimeoutError } from './timeoutError.js';
 import { DeferredPromise } from '../promise/deferredPromise.js';
+import { TimeoutError } from './timeoutError.js';
 
 /**
+ * @param unref defaults to `false`, when true, call `unref()` on the timer.
+ *            can not set to `true` on other platform.
  * @returns promise reject with TimeoutError after specific time
  */
-export function timeout(ms: number, error = 'no response'): Promise<never> {
+export function timeout(ms: number, error = 'no response', unref = false): Promise<never> {
 	return new Promise((_, reject) => {
-		setTimeout(() => {
+		const timer = setTimeout(() => {
 			reject(new TimeoutError(ms, error));
 		}, ms);
+		if (unref) (timer as any).unref();
 	});
 }
 
 /**
+ * @param unref defaults to `false`, when true, call `unref()` on the timer.
+ *            can not set to `true` on other platform.
  * @returns promise resolve after specific time
  */
-export function sleep(ms: number): Promise<void> {
+export function sleep(ms: number, unref = false): Promise<void> {
 	return new Promise((resolve) => {
-		setTimeout(() => {
+		const timer = setTimeout(() => {
 			resolve();
 		}, ms);
+		if (unref) (timer as any).unref();
 	});
 }
 
-export function timeoutPromise<T>(ms: number, p: Promise<T>): Promise<T>;
-export function timeoutPromise<T>(ms: number, message: string, p: Promise<T>): Promise<T>;
-export function timeoutPromise<T, PT = any>(ms: number, p: DeferredPromise<T, PT>): DeferredPromise<T, PT>;
-export function timeoutPromise<T, PT = any>(
-	ms: number,
-	message: string,
-	p: DeferredPromise<T, PT>
-): DeferredPromise<T, PT>;
+export function timeoutPromise<T>(ms: number, p: PromiseLike<T> | DeferredPromise<T>): PromiseLike<T>;
+export function timeoutPromise<T>(ms: number, message: string, p: PromiseLike<T> | DeferredPromise<T>): PromiseLike<T>;
 
-export function timeoutPromise<T>(ms: number, message: string | T, p?: T): T {
+/**
+ * race the promise with timeout
+ *
+ * @param ms timeout in milliseconds
+ * @param message error.message when timeout
+ * @param p the promise
+ * @returns
+ */
+export function timeoutPromise<T>(
+	ms: number,
+	message: string | PromiseLike<T> | DeferredPromise<T>,
+	p?: PromiseLike<T> | DeferredPromise<T>,
+): PromiseLike<T> {
 	let msg: string | undefined;
 	if (typeof message !== 'string') {
 		p = message;
@@ -41,7 +53,7 @@ export function timeoutPromise<T>(ms: number, message: string | T, p?: T): T {
 		msg = message;
 	}
 	if (p instanceof DeferredPromise) {
-		return Promise.race([p.p, timeout(ms, msg)]).then(() => p) as any;
+		return Promise.race([p.p, timeout(ms, msg)]);
 	}
-	return Promise.race([p, timeout(ms, msg)]).then(() => p) as any;
+	return Promise.race([p as PromiseLike<T>, timeout(ms, msg)]);
 }

package/src/lifecycle/timeout/timeoutError.ts

@@ -8,9 +8,11 @@ export class TimeoutError extends Error {
 	constructor(time: number, what = 'no response') {
 		super(`Timeout: ${what} in ${humanDate.deltaTiny(time)}`);
 	}
+
+	static is = isTimeoutError;
 }
 
 /** @public */
-export function isTimeoutError(error: Error): error is TimeoutError {
+export function isTimeoutError(error: unknown): error is TimeoutError {
 	return error instanceof TimeoutError;
 }

package/src/misc/package.json.ts

@@ -36,6 +36,8 @@ function isPathMap(exportsField: IExportCondition | IExportMap): exportsField is
 	return Object.keys(exportsField).some((e) => e.startsWith('.'));
 }
 export function parseExportsField(exports: IExportsField): IFullExportsField {
+	if (!exports) return {};
+
 	if (typeof exports === 'string') {
 		return { '.': { default: exports } };
 	}