@idlebox/common 1.3.15 → 1.3.16

package/src/debugging/serializable.ts

@@ -0,0 +1,146 @@
+declare const window: any;
+declare const EventTarget: any;
+declare const Element: any;
+
+type ScalarTypes =
+	| bigint
+	| number
+	| Number
+	| boolean
+	| Boolean
+	| string
+	| String
+	| symbol
+	| undefined
+	| null
+	| Date
+	| RegExp
+	| Function;
+
+export function isScalar(value: any): value is ScalarTypes {
+	switch (typeof value) {
+		case 'bigint':
+		case 'number':
+		case 'boolean':
+		case 'string':
+		case 'symbol':
+		case 'undefined':
+		case 'function':
+			return true;
+		case 'object':
+			return (
+				value === null ||
+				value instanceof Date ||
+				value instanceof Boolean ||
+				value instanceof String ||
+				value instanceof Number ||
+				value instanceof RegExp
+			);
+		default:
+			return false;
+	}
+}
+
+export enum SerializableKind {
+	Invalid = 0,
+	Primitive,
+	Manual,
+	Other,
+}
+
+export function isSerializable(value: any): SerializableKind {
+	const t = typeof value;
+	switch (t) {
+		case 'bigint':
+		// @ts-expect-error
+		case 'number':
+			if (isNaN(value) || Infinity === value || -Infinity === value) {
+				return SerializableKind.Invalid;
+			}
+		case 'boolean':
+		case 'string':
+		case 'undefined':
+			return SerializableKind.Primitive;
+		case 'object':
+			if (!value) {
+				return SerializableKind.Invalid;
+			}
+			if ('toJSON' in value || Symbol.toPrimitive in value) {
+				return SerializableKind.Manual;
+			}
+			if (
+				value instanceof Map ||
+				value instanceof WeakMap ||
+				value instanceof Set ||
+				value instanceof WeakSet ||
+				value instanceof RegExp ||
+				value instanceof Promise ||
+				value === Math
+			) {
+				return SerializableKind.Invalid;
+			}
+			if (typeof window === 'object') {
+				if (value instanceof EventTarget) {
+					return SerializableKind.Invalid;
+				}
+			}
+			if ('then' in value && typeof value['then'] === 'function') {
+				return SerializableKind.Invalid;
+			}
+
+			return SerializableKind.Other;
+	}
+	return SerializableKind.Invalid;
+}
+
+export function getTypeOf(value: any) {
+	const t = typeof value;
+	switch (t) {
+		case 'bigint':
+		case 'number':
+		case 'boolean':
+		case 'string':
+		case 'symbol':
+		case 'undefined':
+		case 'function':
+			return t;
+	}
+	if (value === null) return 'null';
+	if (value instanceof Promise) return 'Promise';
+	if (value instanceof Error) return 'Error';
+
+	if (typeof window === 'object') {
+		if (value instanceof Element) return 'DOM';
+		if (value instanceof EventTarget) return 'EventTarget';
+	}
+
+	if (value instanceof String) return 'string';
+	if (value instanceof Number) return 'number';
+	if (value instanceof Boolean) return 'boolean';
+	if (value instanceof Date) return 'datetime';
+	if (value instanceof RegExp) return 'regexp';
+
+	return 'unknown';
+}
+
+export function assertSerializable(value: any) {
+	if (!value) return;
+
+	assertSerializableWalker(value, '$');
+}
+
+function assertSerializableWalker(data: any, path: string) {
+	const type = isSerializable(data);
+	if (type === SerializableKind.Invalid) {
+		console.error('在对象中发现不可序列化的数据: 路径为 %s, 可能的类型为: %s\n%j', path, getTypeOf(data), data);
+		throw new TypeError(`对象路径 ${path} 无法序列化`);
+	}
+
+	if (type === SerializableKind.Manual || type === SerializableKind.Primitive) {
+		return;
+	}
+
+	for (const [key, value] of Object.entries(data)) {
+		assertSerializableWalker(value, `${path}/${key}`);
+	}
+}

package/src/debugging/tryInspect.ts

@@ -0,0 +1,37 @@
+const inspect = Symbol.for('nodejs.util.inspect.custom'); // high version node
+const inspectOld = tryGetSymbol();
+
+declare const global: any;
+
+function tryGetSymbol() {
+	try {
+		const r = global.require;
+		return r('util').inspect.custom;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * try to call `inspect` method of an object, if not exists, call `toString`.
+ * @returns {string}
+ */
+export function tryInspect(object: any) {
+	if (!object || typeof object !== 'object') {
+		return JSON.stringify(object);
+	}
+
+	if (object[inspect]) {
+		return object[inspect]();
+	} else if (inspectOld && object[inspectOld]) {
+		return object[inspectOld]();
+	} else if (object['inspect']) {
+		return object['inspect']();
+	} else if (object[Symbol.toStringTag]) {
+		return object[Symbol.toStringTag]();
+	} else if (object.toJSON) {
+		return object.toJSON();
+	} else {
+		return '' + object;
+	}
+}

package/src/error/convertUnknown.ts

@@ -0,0 +1,10 @@
+import { getErrorFrame } from './getFrame';
+
+export function convertCatchedError(e: unknown): Error {
+	if (e instanceof Error) {
+		return e;
+	} else {
+		console.error('Catched 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

@@ -0,0 +1,13 @@
+/**
+ * Get nth line of Error.stack
+ * @returns {string} if frame greater than max, return ''
+ */
+export function getErrorFrame(e: Error, frame: number): string {
+	if (e && e.stack) {
+		const stackArr = e.stack.split('\n');
+		if (stackArr.length > frame + 1) {
+			return stackArr[frame + 1].trim();
+		}
+	}
+	return '';
+}

package/src/function/asyncCallbackList.ts

@@ -0,0 +1,75 @@
+import { nameFunction } from './functionName';
+
+export interface MyAsyncCallback<Argument extends unknown[]> {
+	displayName?: string;
+
+	(...param: Argument): Promise<void | undefined | boolean> | void | undefined | boolean;
+}
+
+/**
+ * like CallbackList, but async
+ */
+export class AsyncCallbackList<Argument extends unknown[]> {
+	protected list: MyAsyncCallback<Argument>[] = [];
+	protected running: boolean = false;
+
+	constructor() {
+		this.run = (this.run as any).bind(this);
+	}
+
+	count() {
+		return this.list.length;
+	}
+
+	reset() {
+		if (this.running) {
+			throw new Error("Can not reset when it's running.");
+		}
+		this.list.length = 0;
+	}
+
+	/**
+	 * @param name optional name of `item` (will assign displayName to `item`)
+	 * @returns function list length
+	 */
+	add(item: MyAsyncCallback<Argument>, name?: string): 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);
+	}
+
+	/**
+	 * @returns if removed: return `item`; if did not exists: return null
+	 */
+	remove(item: MyAsyncCallback<Argument>): null | MyAsyncCallback<Argument> {
+		if (this.running) {
+			throw new Error("Can not remove callback when it's running.");
+		}
+		const found = this.list.indexOf(item);
+		if (found !== -1) {
+			return this.list.splice(found, 1)[0];
+		}
+		return null;
+	}
+
+	/**
+	 * Stop run if one callback return `true`
+	 * @returns {boolean} true if one callback return true
+	 */
+	async run(...argument: Argument): Promise<boolean> {
+		this.running = true;
+		let ret: boolean | undefined | void;
+		for (const cb of this.list) {
+			ret = await cb(...argument);
+			if (ret === true) {
+				break;
+			}
+		}
+		this.running = false;
+		return ret || false;
+	}
+}

package/src/function/callbackList.ts

@@ -0,0 +1,88 @@
+import { nameFunction } from './functionName';
+
+export interface MyCallback<Argument extends unknown[]> {
+	displayName?: string;
+
+	(...param: Argument): any;
+}
+
+/**
+ * Manage a list of callback
+ */
+export class CallbackList<Argument extends unknown[]> {
+	protected list: MyCallback<Argument>[] = [];
+	protected running: boolean = false;
+	protected stop: boolean = false;
+
+	constructor() {
+		this.run = (this.run as any).bind(this);
+	}
+
+	count() {
+		return this.list.length;
+	}
+
+	/**
+	 * remove all callback
+	 */
+	reset() {
+		if (this.running) {
+			throw new Error("Can not reset when it's running.");
+		}
+		this.list.length = 0;
+	}
+
+	/**
+	 * @param name optional name of `item` (will assign displayName to `item`)
+	 * @returns function list length
+	 */
+	add(item: MyCallback<Argument>, name?: string): 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);
+	}
+
+	/**
+	 * @returns if removed: return `item`; if did not exists: return null
+	 */
+	remove(item: MyCallback<Argument>): null | MyCallback<Argument> {
+		if (this.running) {
+			throw new Error("Can not remove callback when it's running.");
+		}
+		const found = this.list.indexOf(item);
+		if (found !== -1) {
+			return this.list.splice(found, 1)[0];
+		}
+		return null;
+	}
+
+	/**
+	 * in a callback, call this.stopRun() to stop remain callbacks (not by return false)
+	 * @returns {boolean} true if every callback called, false if stop in middle
+	 */
+	run(...argument: Argument): boolean {
+		if (this.running) {
+			throw new Error("can not run CallbackList in it's callback.");
+		}
+		this.stop = false;
+
+		this.running = true;
+		for (const cb of this.list) {
+			if (this.stop) break;
+			cb(...argument);
+		}
+		this.running = false;
+
+		const ret = !this.stop;
+		this.stop = false;
+		return ret;
+	}
+
+	stopRun() {
+		this.stop = true;
+	}
+}

package/src/function/delayCallbackList.ts

@@ -0,0 +1,45 @@
+import { nameFunction } from './functionName';
+
+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 DelayCallbackList<Argument extends unknown[]> {
+	private delayArgument?: Argument;
+	private delayComplete: boolean = false;
+
+	protected list?: MyDelayCallback<Argument>[] = [];
+
+	count() {
+		return this.list?.length ?? 0;
+	}
+
+	add(item: MyDelayCallback<Argument>, name?: string) {
+		if (name) {
+			nameFunction(name, item);
+		}
+		if (this.delayComplete) {
+			item(...this.delayArgument!);
+		} else {
+			this.list!.push(item);
+		}
+	}
+
+	run(argument: Argument) {
+		if (this.delayComplete) {
+			throw new Error('call to delay callback twice!');
+		}
+		this.delayComplete = true;
+		this.delayArgument = argument;
+		this.list!.forEach((cb) => {
+			cb(...argument);
+		});
+		delete this.list;
+	}
+}

package/src/function/functionName.ts

@@ -0,0 +1,39 @@
+/**
+ * Function with displayName
+ */
+export interface NamedFunction extends Function {
+	displayName: string;
+}
+
+/**
+ * Get displayName/name of a function
+ */
+export function functionName(func: Function) {
+	return (func as NamedFunction).displayName || func.name;
+}
+
+/**
+ * Set displayName of a function
+ */
+export function nameFunction<T extends Function>(name: string, func: T): T & NamedFunction {
+	return Object.assign(func, {
+		displayName: name,
+		inspect() {
+			return `[Function: ${name}]`;
+		},
+	});
+}
+
+export interface MaybeNamedFunction extends Function {
+	displayName?: string;
+}
+
+/**
+ * Assert function must have oneof displayName/name property
+ */
+export function assertFunctionHasName(func: MaybeNamedFunction) {
+	if (!func.displayName && !func.name) {
+		console.error(func);
+		throw new TypeError('function must have name!');
+	}
+}