@mengine/utils 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+//#region src/disposeable.d.ts
+declare abstract class Disposable {
+  abstract dispose(): void;
+  [Symbol.dispose](): void;
+}
+declare class FnDisposable extends Disposable {
+  private teardown;
+  constructor(teardown: () => void);
+  dispose(): void;
+}
+declare class DisposableSet extends Disposable {
+  private disposables;
+  dispose(): void;
+  add<T extends () => void>(teardown: T): void;
+  add<T extends Disposable>(teardown: T): void;
+  delete<T extends () => void>(teardown: T): void;
+  delete<T extends Disposable>(teardown: T): void;
+  clear(): void;
+}
+//#endregion
+//#region src/event.d.ts
+interface EventSchema {
+  [key: string]: [any, any?];
+}
+type KeyToKey<T extends EventSchema> = { [K in keyof T]: string extends K ? never : K };
+declare type ValuesOf<T> = T extends { [K in keyof T]: infer _U } ? _U : never;
+type EventNames<T extends EventSchema> = ValuesOf<KeyToKey<T>>;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type RequiredInput<In> = IsAny<In> extends true ? [In] : [In] extends [never] ? [] : [In] extends [void] ? [] : [In];
+type EventInput<Events extends EventSchema, Type extends EventNames<Events>> = Type extends keyof Events ? Events[Type] extends [infer In] ? RequiredInput<In> : Events[Type] extends [infer In, infer _Out] ? RequiredInput<In> : never : never;
+declare class EventBus<Events extends EventSchema> {
+  private listeners;
+  on<EventName extends EventNames<Events>>(eventName: EventName, callback: (...input: EventInput<Events, EventName>) => void): () => void;
+  off<EventName extends EventNames<Events>>(eventName: EventName, callback: (...input: EventInput<Events, EventName>) => void): void;
+  emit<EventName extends EventNames<Events>>(eventName: EventName, ...input: EventInput<Events, EventName>): void;
+  clear<EventName extends EventNames<Events>>(eventName: EventName): void;
+  clearAll(): void;
+}
+//#endregion
+//#region src/loop.d.ts
+/**
+ * 运行一段异步任务，并在其完成后检查取消点：即使任务本身没有响应取消，
+ * 只要 `signal` 在任务返回时已 abort，就抛出 `signal.reason` 而不是返回结果——
+ * 避免把 abort 之后的结果泄漏给调用方。
+ *
+ * 取代原先的 `@checkpoint()` 方法装饰器：显式传入 signal，不再靠“参数位”约定，
+ * 也就不需要在方法上保留只为定位 signal 的未用参数。
+ */
+declare function runWithCheckpoint<T>(signal: AbortSignal, task: () => Promise<T>): Promise<T>;
+//#endregion
+//#region src/promise.d.ts
+declare function timeout<T>(inner: Promise<T>, timeout: number): Promise<T>;
+//#endregion
+//#region src/task.d.ts
+declare const MANUALLY_STOP = "Manually stopped";
+/**
+ * Runtime scope owned by a single Task instance.
+ *
+ * The signal is task-owned: callers should proxy outside signals with
+ * `task.abortOn(signal)` instead of wiring them into executors by hand.
+ * Disposers run once when the task settles by resolve, reject, cancel,
+ * timeout, or sidecar abort.
+ */
+interface TaskScope {
+  readonly signal: AbortSignal;
+  readonly disposer: {
+    add(dispose: () => void): void;
+  };
+}
+type TaskExecutor<T> = (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void, scope: TaskScope) => void;
+/**
+ * Promise with task-owned cancellation and cleanup.
+ *
+ * `Task` keeps cancellation control inside its own AbortController. Outside
+ * abort signals are sidecars that can only proxy into this controller. Task
+ * combinators build a cancellation tree, so aborting a parent cancels child
+ * tasks without leaking parent signal wiring into child executors.
+ */
+declare class Task<T> extends Promise<T> {
+  private abortController;
+  /**
+   * Keep native Promise chaining from constructing Task without an executor.
+   * */
+  static get [Symbol.species](): PromiseConstructor;
+  /**
+   * Create a cancellable promise.
+   *
+   * Use `scope.signal` when an underlying API accepts AbortSignal. Use
+   * `scope.disposer.add()` for listeners, timers, subscriptions, and other
+   * cleanup that must run when the task settles.
+   */
+  constructor(executor: TaskExecutor<T>);
+  /**
+   * Cancel this task with a caller-provided reason, or MANUALLY_STOP.
+   * */
+  cancel(reason?: any): void;
+  /**
+   * Cancel this task when the timeout elapses.
+   *
+   * The timer is cleared on any settlement, and timeout cancellation follows
+   * the same internal abort path as `cancel()` and `abortOn()`.
+   */
+  timeout(timeoutMs: number): Task<T>;
+  /**
+   * Proxy an outside AbortSignal into this task's internal controller.
+   *
+   * This does not abort the outside signal. The listener is removed when this
+   * task settles, and an already-aborted signal cancels the task immediately.
+   */
+  abortOn(signal: AbortSignal): Task<T>;
+  /**
+   * Run an executor that returns or throws instead of calling resolve/reject.
+   *
+   * The provided scope is the same task-owned scope used by the constructor,
+   * so simple tasks can still register disposers without manual promise wiring.
+   */
+  static spawn<T>(executor: (scope: TaskScope) => T | PromiseLike<T>): Task<T>;
+  /**
+   * Resolve after `timeoutMs` unless cancelled first.
+   *
+   * The timer is registered as a disposer, so cancellation clears it through
+   * normal task cleanup.
+   */
+  static delay(timeoutMs: number): Task<void>;
+  /**
+   * Promise.all with Task cancellation semantics.
+   *
+   * Parent cancellation cancels child Task instances. If one child rejects,
+   * pending child Task instances are cancelled with the same reason. Plain
+   * promises are awaited but cannot be cancelled.
+   */
+  static all<T extends readonly unknown[] | []>(values: T): Task<{ -readonly [P in keyof T]: Awaited<T[P]> }>;
+  static all<T>(values: Iterable<T | PromiseLike<T>>): Task<Awaited<T>[]>;
+  /**
+   * Raise an error on the task's internal controller.
+   */
+  private raise;
+}
+//#endregion
+export { Disposable, DisposableSet, EventBus, EventInput, EventNames, EventSchema, FnDisposable, MANUALLY_STOP, Task, TaskScope, runWithCheckpoint, timeout };

package/dist/index.js

@@ -0,0 +1,251 @@
+//#region src/disposeable.ts
+var Disposable = class {
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+};
+var FnDisposable = class extends Disposable {
+	teardown;
+	constructor(teardown) {
+		super();
+		this.teardown = teardown;
+	}
+	dispose() {
+		this.teardown();
+	}
+};
+var DisposableSet = class extends Disposable {
+	disposables = /* @__PURE__ */ new Set();
+	dispose() {
+		for (const disposable of this.disposables) disposable.dispose();
+		this.disposables.clear();
+	}
+	add(teardown) {
+		if (teardown instanceof Disposable) this.disposables.add(teardown);
+		else this.disposables.add(new FnDisposable(teardown));
+	}
+	delete(teardown) {
+		if (teardown instanceof Disposable) this.disposables.delete(teardown);
+	}
+	clear() {
+		this.disposables.clear();
+	}
+};
+//#endregion
+//#region src/event.ts
+var EventBus = class {
+	listeners = /* @__PURE__ */ new Map();
+	on(eventName, callback) {
+		let listeners = this.listeners.get(eventName);
+		if (!listeners) {
+			listeners = /* @__PURE__ */ new Set();
+			this.listeners.set(eventName, listeners);
+		}
+		listeners.add(callback);
+		return () => {
+			listeners?.delete(callback);
+		};
+	}
+	off(eventName, callback) {
+		this.listeners.get(eventName)?.delete(callback);
+	}
+	emit(eventName, ...input) {
+		this.listeners.get(eventName)?.forEach((callback) => callback(...input));
+	}
+	clear(eventName) {
+		this.listeners.delete(eventName);
+	}
+	clearAll() {
+		this.listeners.clear();
+	}
+};
+//#endregion
+//#region src/loop.ts
+/**
+* 运行一段异步任务，并在其完成后检查取消点：即使任务本身没有响应取消，
+* 只要 `signal` 在任务返回时已 abort，就抛出 `signal.reason` 而不是返回结果——
+* 避免把 abort 之后的结果泄漏给调用方。
+*
+* 取代原先的 `@checkpoint()` 方法装饰器：显式传入 signal，不再靠“参数位”约定，
+* 也就不需要在方法上保留只为定位 signal 的未用参数。
+*/
+async function runWithCheckpoint(signal, task) {
+	const result = await task();
+	if (signal.aborted) throw signal.reason;
+	return result;
+}
+//#endregion
+//#region src/promise.ts
+async function timeout(inner, timeout) {
+	const timer = Promise.withResolvers();
+	const timerHandler = setTimeout(() => {
+		timer.reject(/* @__PURE__ */ new Error(`Timeout after ${timeout}ms`));
+	}, timeout);
+	return Promise.race([inner, timer.promise]).finally(() => {
+		clearTimeout(timerHandler);
+	});
+}
+//#endregion
+//#region src/task.ts
+const MANUALLY_STOP = "Manually stopped";
+/**
+* Promise with task-owned cancellation and cleanup.
+*
+* `Task` keeps cancellation control inside its own AbortController. Outside
+* abort signals are sidecars that can only proxy into this controller. Task
+* combinators build a cancellation tree, so aborting a parent cancels child
+* tasks without leaking parent signal wiring into child executors.
+*/
+var Task = class Task extends Promise {
+	abortController;
+	/**
+	* Keep native Promise chaining from constructing Task without an executor.
+	* */
+	static get [Symbol.species]() {
+		return Promise;
+	}
+	/**
+	* Create a cancellable promise.
+	*
+	* Use `scope.signal` when an underlying API accepts AbortSignal. Use
+	* `scope.disposer.add()` for listeners, timers, subscriptions, and other
+	* cleanup that must run when the task settles.
+	*/
+	constructor(executor) {
+		const abortController = new AbortController();
+		const disposes = /* @__PURE__ */ new Set();
+		let cleanedUp = false;
+		const runDispose = (dispose) => {
+			try {
+				dispose();
+			} catch (error) {
+				console.error("Task disposer failed", error);
+			}
+		};
+		const cleanup = () => {
+			if (cleanedUp) return;
+			cleanedUp = true;
+			for (const dispose of disposes) runDispose(dispose);
+			disposes.clear();
+		};
+		const scope = {
+			signal: abortController.signal,
+			disposer: { add(dispose) {
+				if (cleanedUp) {
+					runDispose(dispose);
+					return;
+				}
+				disposes.add(dispose);
+			} }
+		};
+		super((resolve, reject) => {
+			abortController.signal.addEventListener("abort", () => {
+				reject(abortController.signal.reason);
+			});
+			executor(resolve, reject, scope);
+		});
+		this.abortController = abortController;
+		this.then(cleanup, cleanup);
+	}
+	/**
+	* Cancel this task with a caller-provided reason, or MANUALLY_STOP.
+	* */
+	cancel(reason) {
+		this.raise(reason ?? "Manually stopped");
+	}
+	/**
+	* Cancel this task when the timeout elapses.
+	*
+	* The timer is cleared on any settlement, and timeout cancellation follows
+	* the same internal abort path as `cancel()` and `abortOn()`.
+	*/
+	timeout(timeoutMs) {
+		const timer = setTimeout(() => {
+			this.raise(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs} ms`));
+		}, timeoutMs);
+		const clear = () => {
+			clearTimeout(timer);
+		};
+		this.then(clear, clear);
+		return this;
+	}
+	/**
+	* Proxy an outside AbortSignal into this task's internal controller.
+	*
+	* This does not abort the outside signal. The listener is removed when this
+	* task settles, and an already-aborted signal cancels the task immediately.
+	*/
+	abortOn(signal) {
+		if (signal.aborted) {
+			this.raise(signal.reason);
+			return this;
+		}
+		const abort = () => {
+			this.raise(signal.reason);
+		};
+		const cleanup = () => {
+			signal.removeEventListener("abort", abort);
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		this.then(cleanup, cleanup);
+		return this;
+	}
+	/**
+	* Run an executor that returns or throws instead of calling resolve/reject.
+	*
+	* The provided scope is the same task-owned scope used by the constructor,
+	* so simple tasks can still register disposers without manual promise wiring.
+	*/
+	static spawn(executor) {
+		return new Task((resolve, reject, scope) => {
+			try {
+				const result = executor(scope);
+				Promise.resolve(result).then(resolve, reject);
+			} catch (error) {
+				reject(error);
+			}
+		});
+	}
+	/**
+	* Resolve after `timeoutMs` unless cancelled first.
+	*
+	* The timer is registered as a disposer, so cancellation clears it through
+	* normal task cleanup.
+	*/
+	static delay(timeoutMs) {
+		return new Task((resolve, _reject, scope) => {
+			const timer = setTimeout(resolve, timeoutMs);
+			scope.disposer.add(() => {
+				clearTimeout(timer);
+			});
+		});
+	}
+	static all(values) {
+		const items = Array.from(values);
+		return new Task((resolve, reject, scope) => {
+			const cancelItems = (reason) => {
+				for (const item of items) if (item instanceof Task) item.cancel(reason);
+			};
+			const abortChildren = () => {
+				cancelItems(scope.signal.reason);
+			};
+			scope.signal.addEventListener("abort", abortChildren, { once: true });
+			scope.disposer.add(() => {
+				scope.signal.removeEventListener("abort", abortChildren);
+			});
+			Promise.all(items).then(resolve, (reason) => {
+				cancelItems(reason);
+				reject(reason);
+			});
+		});
+	}
+	/**
+	* Raise an error on the task's internal controller.
+	*/
+	raise(reason) {
+		if (this.abortController.signal.aborted) return;
+		this.abortController.abort(reason);
+	}
+};
+//#endregion
+export { Disposable, DisposableSet, EventBus, FnDisposable, MANUALLY_STOP, Task, runWithCheckpoint, timeout };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@mengine/utils",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/one2x-ai/medeo-engine.git",
+    "directory": "packages/utils"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    },
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "prepublishOnly": "vp pack"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}