@idlebox/common 1.4.19 → 1.4.21

package/src/date/{timeString.ts → to-string.ts}

@@ -74,27 +74,25 @@ export namespace humanDate {
 
 	/**
 	 * format time delta (in ms) to string, like: '1d'
-	 * when ms<=0, returns '0s'
+	 * when delta<=0, returns '0s'
 	 *
 	 * format can set by `setLocaleFormatter`
 	 * day is the largest unit
 	 */
 	export function deltaTiny(from: number, to: number): string;
 	export function deltaTiny(ms: number): string;
-	export function deltaTiny(ms: number, to?: number) {
-		if (arguments.length === 2) {
-			ms = to! - ms;
-		}
-		if (ms > oneDay) {
-			return formatters.d(Math.floor(ms / oneDay));
-		} else if (ms > oneHour) {
-			return formatters.h(Math.floor(ms / oneHour));
-		} else if (ms > oneMinute) {
-			return formatters.m(Math.floor(ms / oneMinute));
-		} else if (ms > oneSecond) {
-			return formatters.s(Math.floor(ms / oneSecond));
-		} else if (ms > 0) {
-			return formatters.ms(ms);
+	export function deltaTiny(from: number, to?: number) {
+		const delta = to !== undefined ? from - to : from;
+		if (delta > oneDay) {
+			return formatters.d(Math.floor(delta / oneDay));
+		} else if (delta > oneHour) {
+			return formatters.h(Math.floor(delta / oneHour));
+		} else if (delta > oneMinute) {
+			return formatters.m(Math.floor(delta / oneMinute));
+		} else if (delta > oneSecond) {
+			return formatters.s(Math.floor(delta / oneSecond));
+		} else if (delta > 0) {
+			return formatters.ms(Math.floor(delta));
 		} else {
 			return '0s';
 		}
@@ -102,27 +100,21 @@ export namespace humanDate {
 
 	/**
 	 * format time delta (in ms) to string, like: '1d10m42s'
-	 * only return XXXms when ms<1000
-	 * when ms<=0, returns '0s'
+	 * only return XXXms when delta<1min
+	 * when delta<=0, returns '0s'
 	 *
 	 * format can set by `setLocaleFormatter`
 	 * day is the largest unit
 	 */
 	export function delta(from: number, to: number): string;
-	export function delta(ms: number): string;
-	export function delta(ms: number, to?: number) {
-		if (arguments.length === 2) {
-			ms = to! - ms;
-		}
-		if (ms <= 0) {
+	export function delta(deltaMs: number): string;
+	export function delta(from: number, to?: number) {
+		const delta = to !== undefined ? from - to : from;
+		if (delta <= 0) {
 			return '0s';
 		}
 
-		// ms
-		if (ms < oneSecond) {
-			return formatters.ms(ms);
-		}
-
+		let ms = delta;
 		let ret = '';
 		if (ms > oneDay) {
 			ret += formatters.d(Math.floor(ms / oneDay));
@@ -136,7 +128,14 @@ export namespace humanDate {
 			ret += formatters.m(Math.floor(ms / oneMinute));
 			ms = ms % oneMinute;
 		}
-		ret += formatters.s(Math.floor(ms / oneSecond));
+		if (ms > oneSecond) {
+			ret += formatters.s(Math.floor(ms / oneSecond));
+			ms = ms % oneSecond;
+		}
+		if (ms > 0 && delta < oneMinute) {
+			ret += formatters.ms(Math.floor(ms));
+		}
+
 		return ret;
 	}
 }

package/src/debugging/{tryInspect.ts → inspect.ts}

@@ -16,7 +16,7 @@ function tryGetSymbol() {
  * try to call `inspect` method of an object, if not exists, call `toString`.
  * @returns {string}
  */
-export function tryInspect(object: any) {
+export function tryInspect(object: any): string {
 	if (!object || typeof object !== 'object') {
 		return JSON.stringify(object);
 	}

package/src/debugging/object-with-name.ts

@@ -0,0 +1,64 @@
+import { definePrivateConstant } from '../autoindex.js';
+
+export interface NamedObject {
+	displayName: string;
+}
+
+/**
+ * Get displayName/name of a object
+ */
+export function objectName<T = unknown>(func: NonNullable<T>) {
+	return (func as MaybeNamed).displayName || (func as MaybeNamed).name;
+}
+
+/**
+ * Set displayName of a object
+ */
+export function nameObject<T extends {} = any>(name: string, object: T): T & NamedObject {
+	if (typeof object === 'function') {
+		definePrivateConstant(object, 'name', name);
+	} else if ('name' in object) {
+		definePrivateConstant(object, 'displayName', name);
+	} else {
+		definePrivateConstant(object, 'name', name);
+	}
+	definePrivateConstant(object, Symbol.toStringTag, `${object.constructor.name}: ${name}`);
+	return object as any;
+}
+
+export interface MaybeNamed {
+	readonly name?: string;
+	readonly displayName?: string;
+}
+
+/**
+ * Assert function must have oneof displayName/name property
+ */
+export function assertObjectHasName<T = unknown>(func: NonNullable<T>): asserts func is T & NamedObject {
+	if (!(func as MaybeNamed).displayName && !(func as MaybeNamed).name) {
+		console.error(func);
+		throw new TypeError('object must have name!');
+	}
+}
+
+/**
+ * Function with displayName
+ */
+export interface NamedFunction extends Function {
+	displayName: string;
+}
+/**
+ * Function with displayName
+ */
+export interface MaybeNamedFunction extends Function {
+	displayName?: string;
+}
+
+/** like objectName but return <anonymous> */
+export function functionName(func: Function) {
+	return objectName(func) || '<anonymous>';
+}
+/** @deprecated use nameObject */
+export const nameFunction = nameObject;
+/** @deprecated use assertObjectHasName */
+export const assertFunctionHasName = assertObjectHasName;

package/src/debugging/serializable.ts

@@ -32,11 +32,11 @@ export function isSerializable(value: any): SerializableKind {
 	const t = typeof value;
 	switch (t) {
 		case 'bigint':
-		// @ts-expect-error
 		case 'number':
 			if (Number.isNaN(value) || Number.POSITIVE_INFINITY === value || Number.NEGATIVE_INFINITY === value) {
 				return SerializableKind.Invalid;
 			}
+			return SerializableKind.Primitive;
 		case 'boolean':
 		case 'string':
 		case 'undefined':

package/src/error/convert-unknown.ts

@@ -0,0 +1,9 @@
+import { getErrorFrame } from './get-frame.js';
+
+export function convertCaughtError(e: unknown): Error {
+	if (e instanceof Error) {
+		return e;
+	}
+	console.error('Caught invalid error at %s, type %s, value %s.', getErrorFrame(new Error(), 1), typeof e, e);
+	return new Error(`Invalid: ${e}`);
+}

package/src/error/{getFrame.ts → get-frame.ts}

@@ -1,4 +1,4 @@
-import type { IWithStack } from './stackTrace.js';
+import type { IWithStack } from './stack-trace.js';
 
 /**
  * Get nth line of Error.stack

package/src/error/{pretty.ts → pretty.nodejs.ts}

@@ -3,7 +3,7 @@ import { relativePath } from '../path/normalizePath.js';
 import { globalObject } from '../platform/globalObject.js';
 import { isNative } from '../platform/os.js';
 import { vscEscapeValue } from './pretty.vscode.js';
-import { createStackTraceHolder } from './stackTrace.js';
+import { createStackTraceHolder } from './stack-trace.js';
 
 const process = globalObject.process;
 const window = globalObject.window;
@@ -338,13 +338,14 @@ const regErrorClassName = /^(\S+):/;
 
 /**
  * Pretty formats an error object.
+ * only meanfull in nodejs
  * @param e The error object to format.
  * @param withMessage Whether to include the error message.
  */
 export function prettyFormatError<ErrorType extends IError = IError>(e: ErrorType, withMessage?: boolean): string;
 /** @internal */
 export function prettyFormatError<ErrorType extends IError = IError>(e: ErrorType, withMessage?: boolean, boundary?: CallableFunction): string;
-export function prettyFormatError<ErrorType extends IError = IError>(e: ErrorType, withMessage = true, boundary: CallableFunction = prettyPrintError) {
+export function prettyFormatError<ErrorType extends IError = IError>(e: ErrorType, withMessage = true, boundary: CallableFunction = prettyFormatError) {
 	if (!e || !e.stack) {
 		if (withMessage) {
 			const msg = e?.message || 'Unknown Error';

package/src/function/{asyncCallbackList.ts → callback-list.async.ts}

@@ -1,5 +1,3 @@
-import { nameFunction } from './functionName.js';
-
 export interface MyAsyncCallback<Argument extends unknown[]> {
 	displayName?: string;
 
@@ -7,7 +5,7 @@ export interface MyAsyncCallback<Argument extends unknown[]> {
 }
 
 /**
- * like CallbackList, but async
+ * like CallbackList, but async run one by one
  */
 export class AsyncCallbackList<Argument extends unknown[]> {
 	protected list: MyAsyncCallback<Argument>[] = [];
@@ -32,13 +30,10 @@ export class AsyncCallbackList<Argument extends unknown[]> {
 	 * @param name optional name of `item` (will assign displayName to `item`)
 	 * @returns function list length
 	 */
-	add(item: MyAsyncCallback<Argument>, name?: string): number {
+	add(item: MyAsyncCallback<Argument>): number {
 		if (this.running) {
 			throw new Error("Can not add callback when it's running.");
 		}
-		if (name) {
-			nameFunction(name, item);
-		}
 		return this.list.push(item);
 	}
 

package/src/function/callback-list.delay.ts

@@ -0,0 +1,29 @@
+export interface MyDelayCallback<Argument extends unknown[]> {
+	displayName?: string;
+	(...param: Argument): void;
+}
+
+/**
+ * remember arguments after run
+ * run all later added function with memorized argument
+ */
+export class MemorizedOnceCallbackList<Argument extends unknown[]> {
+	protected list: MyDelayCallback<Argument>[] = [];
+
+	count() {
+		return this.list.length;
+	}
+
+	add(item: MyDelayCallback<Argument>) {
+		this.list.push(item);
+	}
+
+	run(...args: Argument) {
+		this.add = (item) => {
+			item(...args);
+		};
+		for (const item of this.list) {
+			item(...args);
+		}
+	}
+}

package/src/function/{callbackList.ts → callback-list.ts}

@@ -1,4 +1,4 @@
-import { nameFunction } from './functionName.js';
+import { nameFunction } from '../debugging/object-with-name.js';
 
 export type MyCallback<Argument extends unknown[]> = (...param: Argument) => boolean | undefined | void;
 

package/src/function/noop.ts

@@ -0,0 +1 @@
+export function noop() {}

package/src/global.d.ts

@@ -1,2 +1,12 @@
 /// <reference types="@idlebox/itypes" />
 /// <reference types="debug" />
+
+declare interface ErrorConstructor {
+	captureStackTrace: any;
+	stackTraceLimit: number;
+}
+
+declare namespace NodeJS {
+	type Signals = string;
+	interface ErrnoException extends Error {}
+}

package/src/legacy/rename.ts

@@ -0,0 +1,15 @@
+import { convertCaughtError } from '../error/convert-unknown.js';
+import { functionToDisposable } from '../lifecycle/dispose/bridges/function.js';
+import { EnhancedAsyncDisposable } from '../lifecycle/dispose/async-disposable.js';
+import { EnhancedDisposable } from '../lifecycle/dispose/sync-disposable.js';
+
+/** @deprecated use functionToDisposable */
+export const toDisposable = functionToDisposable;
+
+/** @deprecated use EnhancedAsyncDisposable */
+export const AsyncDisposable = EnhancedAsyncDisposable;
+/** @deprecated use EnhancedDisposable */
+export const Disposable = EnhancedDisposable;
+
+/** @deprecated use convertCaughtError */
+export const convertCatchedError = convertCaughtError;

package/src/lifecycle/{promise/cancellationToken → cancellation}/driver.browser.ts

@@ -1,9 +1,8 @@
-import type { EventHandler } from '../../event/event.js';
-
+import type { EventHandler } from '../event/type.js';
 import type { CancellationDriver, __CancellationToken } from './source.js';
 
-declare const AbortController: any; // TODO
-declare type AbortController = any; // TODO
+declare const AbortController: any;
+declare type AbortController = any;
 
 /** @internal */
 export class CancellationDriverBrowser implements CancellationDriver {

package/src/lifecycle/{promise/cancellationToken → cancellation}/driver.common.ts

@@ -1,5 +1,6 @@
-import type { IDisposable } from '../../dispose/lifecycle.js';
-import { Emitter, type EventHandler } from '../../event/event.js';
+import type { IDisposable } from '../dispose/disposable.js';
+import { Emitter } from '../event/event.js';
+import type { EventHandler } from '../event/type.js';
 
 import type { CancellationDriver, __CancellationToken } from './source.js';
 

package/src/lifecycle/{promise/cancellationToken → cancellation}/source.ts

@@ -1,7 +1,7 @@
-import { globalObject } from '../../../platform/globalObject.js';
-import type { IDisposable } from '../../dispose/lifecycle.js';
-import { DisposableOnce } from '../../dispose/lifecycle.sync.js';
-import type { EventHandler } from '../../event/event.js';
+import { globalObject } from '../../platform/globalObject.js';
+import type { IDisposable } from '../dispose/disposable.js';
+import { DisposableOnce } from '../dispose/sync-disposable.js';
+import type { EventHandler } from '../event/type.js';
 import { CancellationDriverBrowser } from './driver.browser.js';
 import { CancellationDriverCommon } from './driver.common.js';
 

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

@@ -0,0 +1,41 @@
+import { convertCaughtError } from '../../autoindex.js';
+import { dispose_name } from './debug.js';
+import { AbstractEnhancedDisposable, type IAsyncDisposable } from './disposable.js';
+
+/**
+ * Async version of Disposable
+ * @public
+ */
+export class EnhancedAsyncDisposable extends AbstractEnhancedDisposable<true> implements IAsyncDisposable {
+	protected override async _dispose(disposables: readonly IAsyncDisposable[]): Promise<void> {
+		for (const d of disposables) {
+			try {
+				if (this._logger.enabled) this._logger(`dispose ${dispose_name(d)}`);
+				await d.dispose();
+			} catch (e) {
+				this._onDisposeError.fireNoError(convertCaughtError(e));
+			}
+		}
+	}
+
+	[Symbol.asyncDispose] = this.dispose;
+}
+
+/**
+ * Disposable everything in same time
+ * @public
+ */
+export class UnorderedAsyncDisposable extends EnhancedAsyncDisposable {
+	protected override async _dispose(disposables: readonly IAsyncDisposable[]) {
+		const ps = disposables.map(async (d) => {
+			try {
+				if (this._logger.enabled) this._logger(`dispose ${dispose_name(d)}`);
+				await d.dispose();
+			} catch (e) {
+				this._onDisposeError.fireNoError(convertCaughtError(e));
+			}
+		});
+
+		await Promise.allSettled(ps);
+	}
+}

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

@@ -0,0 +1,31 @@
+import { functionName, nameObject } from '../../../debugging/object-with-name.js';
+import { dispose_name } from '../debug.js';
+import type { IAsyncDisposable, IDisposable } from '../disposable.js';
+
+/**
+ * Convert "dispose function" to disposable object
+ * @public
+ */
+export function functionToDisposable<RT>(fn: () => RT): RT extends Promise<any> ? IAsyncDisposable : IDisposable {
+	return {
+		get displayName() {
+			return `disposeFn(${functionName(fn)})`;
+		},
+		dispose: fn,
+	} as any;
+}
+
+/**
+ * convert disposable object to function
+ * eg.
+ *
+ * useEffect(() => {
+ * 	const disposable = new Xyz();
+ * 	return toFunction(disposable);
+ * }, [])
+ */
+export function disposerFunction<T extends IDisposable | IAsyncDisposable>(obj: T): T extends IAsyncDisposable ? () => Promise<void> : () => void {
+	return nameObject(dispose_name(obj), () => {
+		obj.dispose();
+	}) as any;
+}

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

@@ -0,0 +1,23 @@
+import type { IAsyncDisposable, IDisposable } from '../disposable.js';
+
+/**
+ * 把原生的Disposable/AsyncDisposable对象转换为本包可以使用的版本
+ */
+export function fromNativeDisposable<T extends AsyncDisposable>(disposable: T): T & IAsyncDisposable;
+export function fromNativeDisposable<T extends Disposable>(disposable: T): T & IDisposable;
+export function fromNativeDisposable<T extends AsyncDisposable | Disposable>(disposable: T): T & IAsyncDisposable & IDisposable;
+export function fromNativeDisposable(disposable: any): any {
+	if (!('dispose' in disposable)) {
+		Object.assign(disposable, { dispose: disposable[Symbol.asyncDispose] ?? disposable[Symbol.dispose] });
+	}
+	return disposable as any;
+}
+
+export function toNativeDisposable(disposable: IAsyncDisposable): AsyncDisposable;
+export function toNativeDisposable(disposable: IDisposable): Disposable;
+export function toNativeDisposable(disposable: any): any {
+	if (!('dispose' in disposable)) {
+		Object.assign(disposable, { dispose: disposable[Symbol.asyncDispose] ?? disposable[Symbol.dispose] });
+	}
+	return disposable as any;
+}

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

@@ -0,0 +1,70 @@
+import { objectName } from '../../../debugging/object-with-name.js';
+import type { IAsyncDisposable } from '../disposable.js';
+
+type ClosableAsync = {
+	close(): Promise<any>;
+	close(cb: (e?: Error) => void): void;
+};
+
+/**
+ * Convert "dispose function" to disposable object
+ * @public
+ */
+export function closableToDisposable<T extends ClosableAsync>(closable: T): IAsyncDisposable {
+	const promised = closable.close.length === 0;
+
+	return {
+		get displayName() {
+			return `closable(${objectName(closable) || 'unknown'})`;
+		},
+		dispose() {
+			if (promised) {
+				return closable.close();
+			} else {
+				return new Promise<void>((resolve, reject) => {
+					return closable.close((error) => {
+						if (error) {
+							reject(error);
+						} else {
+							resolve();
+						}
+					});
+				});
+			}
+		},
+	};
+}
+
+type EndableAsync = {
+	end(): Promise<any>;
+	end(cb: (e?: Error) => void): void;
+};
+
+/**
+ * Convert "dispose function" to disposable object
+ * @public
+ */
+export function endableToDisposable<T extends EndableAsync>(endable: T): IAsyncDisposable {
+	const promised = endable.end.length === 0;
+
+	return {
+		get displayName() {
+			return `endable(${objectName(endable) || 'unknown'})`;
+		},
+		dispose() {
+			if (promised) {
+				return endable.end();
+			} else {
+				return new Promise<void>((resolve, reject) => {
+					return endable.end((error) => {
+						if (error) {
+							reject(error);
+						} else {
+							resolve();
+						}
+					});
+				});
+			}
+		},
+	};
+}

package/src/lifecycle/dispose/debug.ts

@@ -1,17 +1,35 @@
 import debug from 'debug';
-import type { IAsyncDisposable, IDisposable } from './lifecycle.js';
+import type { IAsyncDisposable, IDisposable } from './disposable.js';
 
 /** @internal */
 export const _debug_dispose = debug('dispose');
 
 /** @internal */
-export function dispose_name(dis: IDisposable | IAsyncDisposable, defaultName = '<unknown>'): string {
-	return dis.displayName || dis.name || name_of_func(dis.constructor) || name_of_func(dis.dispose) || defaultName;
+export function dispose_name(disposable: IDisposable | IAsyncDisposable | AsyncDisposable | Disposable, defaultName = '<unknown>'): string {
+	const dis = disposable as any;
+	return (
+		dis.displayName ||
+		dis.name ||
+		name_of_func(dis.constructor) ||
+		name_of_func(dis.dispose) ||
+		name_of_func(dis[Symbol.dispose]) ||
+		name_of_func(dis[Symbol.asyncDispose]) ||
+		defaultName
+	);
 }
 function name_of_func(obj: any) {
 	const name: string = obj.name;
 
-	if (name === 'Object' || name === 'Function' || name === 'AsyncFunction' || name === 'GeneratorFunction' || name === 'AsyncGeneratorFunction' || name === 'Disposable' || name === 'AsyncDisposable' || name.toLowerCase() === 'dispose') {
+	if (
+		name === 'Object' ||
+		name === 'Function' ||
+		name === 'AsyncFunction' ||
+		name === 'GeneratorFunction' ||
+		name === 'AsyncGeneratorFunction' ||
+		name === 'Disposable' ||
+		name === 'AsyncDisposable' ||
+		name.toLowerCase() === 'dispose'
+	) {
 		return '';
 	}