@mantaq/core 0.0.1

package/dist/index.mjs

@@ -0,0 +1,557 @@
+import { registerActor, setOutputHandler } from "./internal.mjs";
+//#region src/state.ts
+function state(id) {
+	return () => new StateRef(id, false);
+}
+var StateRef = class StateRef {
+	name;
+	isFinal;
+	/** @internal */ _regions;
+	constructor(name, isFinal) {
+		this.name = name;
+		this.isFinal = isFinal;
+	}
+	regions(options) {
+		this._regions = options;
+		return this;
+	}
+	final() {
+		const next = new StateRef(this.name, true);
+		next._regions = this._regions;
+		return next;
+	}
+	create(payload) {
+		return {
+			state: this,
+			payload
+		};
+	}
+};
+//#endregion
+//#region src/real-clock.ts
+var RealClock = class {
+	#start = Date.now();
+	now() {
+		return Date.now() - this.#start;
+	}
+	setTimeout(ms, cb, options) {
+		if (options?.signal?.aborted) return -1;
+		let onAbort;
+		const id = Number(globalThis.setTimeout(() => {
+			if (onAbort && options?.signal) options.signal.removeEventListener("abort", onAbort);
+			cb();
+		}, ms));
+		if (options?.signal) {
+			onAbort = () => globalThis.clearTimeout(id);
+			options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+		return id;
+	}
+	clearTimeout(id) {
+		globalThis.clearTimeout(id);
+	}
+	setInterval(ms, cb, options) {
+		const id = Number(globalThis.setInterval(cb, ms));
+		if (options?.signal) {
+			const onAbort = () => globalThis.clearInterval(id);
+			options.signal.addEventListener("abort", onAbort, { once: true });
+		}
+		return id;
+	}
+	clearInterval(id) {
+		globalThis.clearInterval(id);
+	}
+};
+//#endregion
+//#region src/abort-tracker.ts
+function trackAbort(signal, id, map) {
+	const onAbort = signal ? () => {
+		map.delete(id);
+	} : void 0;
+	if (signal && onAbort) signal.addEventListener("abort", onAbort, { once: true });
+	return onAbort;
+}
+function clearAbort(timer) {
+	if (timer.signal && timer.onAbort) timer.signal.removeEventListener("abort", timer.onAbort);
+}
+//#endregion
+//#region src/virtual-clock.ts
+var VirtualClock = class {
+	#now = 0;
+	#timers = /* @__PURE__ */ new Map();
+	#intervals = /* @__PURE__ */ new Map();
+	#nextId = 1;
+	#drain = null;
+	now() {
+		return this.#now;
+	}
+	setTimeout(ms, cb, options) {
+		const signal = options?.signal;
+		if (signal?.aborted) return -1;
+		const id = this.#nextId++;
+		const onAbort = trackAbort(signal, id, this.#timers);
+		this.#timers.set(id, {
+			deadline: this.#now + ms,
+			cb,
+			signal,
+			onAbort,
+			eventName: options?.eventName
+		});
+		return id;
+	}
+	clearTimeout(id) {
+		const timer = this.#timers.get(id);
+		if (timer) {
+			clearAbort(timer);
+			this.#timers.delete(id);
+		}
+	}
+	setInterval(ms, cb, options) {
+		const signal = options?.signal;
+		if (signal?.aborted) return -1;
+		const id = this.#nextId++;
+		const onAbort = trackAbort(signal, id, this.#intervals);
+		this.#intervals.set(id, {
+			ms,
+			next: this.#now + ms,
+			cb,
+			signal,
+			onAbort
+		});
+		return id;
+	}
+	clearInterval(id) {
+		const interval = this.#intervals.get(id);
+		if (interval) {
+			clearAbort(interval);
+			this.#intervals.delete(id);
+		}
+	}
+	#findEarliestDeadline(target) {
+		let earliest = target;
+		let found = false;
+		for (const t of this.#timers.values()) if (t.deadline <= target && t.deadline <= earliest) {
+			earliest = t.deadline;
+			found = true;
+		}
+		for (const t of this.#intervals.values()) if (t.next <= target && t.next <= earliest) {
+			earliest = t.next;
+			found = true;
+		}
+		return found ? earliest : null;
+	}
+	#fireTimersAt(deadline) {
+		const ids = [];
+		for (const [id, t] of this.#timers) if (t.deadline === deadline) ids.push(id);
+		for (const id of ids) {
+			const timer = this.#timers.get(id);
+			if (timer) {
+				clearAbort(timer);
+				this.#timers.delete(id);
+				timer.cb();
+			}
+		}
+	}
+	#fireIntervalsAt(deadline) {
+		const ids = [];
+		for (const [id, t] of this.#intervals) if (t.next === deadline) ids.push(id);
+		for (const id of ids) {
+			const interval = this.#intervals.get(id);
+			if (interval) {
+				interval.cb();
+				if (this.#intervals.has(id)) interval.next = this.#now + interval.ms;
+			}
+		}
+	}
+	advance(ms) {
+		const target = this.#now + ms;
+		while (true) {
+			const deadline = this.#findEarliestDeadline(target);
+			if (deadline === null) break;
+			this.#now = deadline;
+			this.#fireTimersAt(deadline);
+			this.#fireIntervalsAt(deadline);
+		}
+		this.#now = target;
+		this.#drain?.();
+	}
+	hasPending() {
+		return this.#timers.size > 0 || this.#intervals.size > 0;
+	}
+	pendingTimers() {
+		const result = [];
+		for (const [id, t] of this.#timers) result.push({
+			id,
+			deadline: t.deadline,
+			ms: t.deadline - this.#now,
+			eventName: t.eventName
+		});
+		return result;
+	}
+	setDrain(fn) {
+		this.#drain = fn;
+	}
+};
+//#endregion
+//#region src/queue.ts
+var InternalQueue = class {
+	#queue = [];
+	#index = 0;
+	#processing = false;
+	#stopped = false;
+	#settledResolvers = [];
+	get length() {
+		return this.#queue.length - this.#index;
+	}
+	get isProcessing() {
+		return this.#processing;
+	}
+	push(...events) {
+		if (this.#stopped) return;
+		this.#queue.push(...events);
+	}
+	settled() {
+		if (this.length === 0 && !this.#processing) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.#settledResolvers.push(resolve);
+		});
+	}
+	process(processEvent) {
+		this.#process((event) => {
+			processEvent(event);
+			return true;
+		});
+	}
+	processCancellable(processEvent) {
+		this.#process(processEvent);
+	}
+	#process(processEvent) {
+		if (this.#processing) return;
+		this.#processing = true;
+		try {
+			while (this.#index < this.#queue.length) {
+				if (this.#stopped) break;
+				const event = this.#queue[this.#index++];
+				if (!processEvent(event)) {
+					this.#stopped = true;
+					break;
+				}
+			}
+		} finally {
+			this.#queue.length = 0;
+			this.#index = 0;
+			this.#processing = false;
+			this.#stopped = false;
+			if (this.#settledResolvers.length > 0) {
+				const resolvers = this.#settledResolvers.splice(0);
+				for (const resolve of resolvers) resolve();
+			}
+		}
+	}
+};
+//#endregion
+//#region src/subscribers.ts
+var Subscribers = class {
+	change = /* @__PURE__ */ new Set();
+	done = /* @__PURE__ */ new Set();
+	addChange(fn) {
+		this.change.add(fn);
+		return () => this.change.delete(fn);
+	}
+	addDone(fn) {
+		this.done.add(fn);
+		return () => this.done.delete(fn);
+	}
+	emitChange(snapshot) {
+		for (const fn of this.change) fn(snapshot);
+	}
+	emitDone() {
+		for (const fn of this.done) fn();
+	}
+	clear() {
+		this.change.clear();
+		this.done.clear();
+	}
+};
+//#endregion
+//#region src/snapshot.ts
+function buildSnapshot(s, regions) {
+	const path = [s.name];
+	const regionSnapshots = {};
+	for (const [regionName, child] of Object.entries(regions)) regionSnapshots[regionName] = child.snapshot();
+	const snap = {
+		path,
+		regions: regionSnapshots
+	};
+	if (s.isFinal) snap.done = true;
+	return snap;
+}
+//#endregion
+//#region src/effects.ts
+function runEffects(options) {
+	if (options.state.isFinal) return null;
+	const list = options.effects[options.state.name];
+	if (!list || list.length === 0) return null;
+	const abort = new AbortController();
+	for (const effectFn of list) effectFn({
+		signal: abort.signal,
+		state: {
+			name: options.state.name,
+			payload: options.statePayload
+		},
+		event: options.event,
+		context: options.context,
+		emit: options.emit,
+		clock: options.clock
+	});
+	return abort;
+}
+//#endregion
+//#region src/dispatch.ts
+function parseTarget(step) {
+	if (!step.state) return void 0;
+	if (step.state instanceof StateRef) return {
+		state: step.state,
+		payload: step.payload
+	};
+	return {
+		state: step.state.state,
+		payload: step.state.payload
+	};
+}
+//#endregion
+//#region src/builder.ts
+var ActorBuilder = class {
+	#transitions = {};
+	#effects = {};
+	on(stateRef, eventRef, fn) {
+		const sName = stateRef.name;
+		const eId = eventRef.id;
+		(this.#transitions[sName] ??= {})[eId] = fn;
+		return this;
+	}
+	onAny(eventRef, fn) {
+		const eId = eventRef.id;
+		(this.#transitions["Any"] ??= {})[eId] = fn;
+		return this;
+	}
+	effect(stateRef, fn) {
+		(this.#effects[stateRef.name] ??= []).push(fn);
+		return this;
+	}
+	/** @internal */ build() {
+		return {
+			transitions: this.#transitions,
+			effects: this.#effects
+		};
+	}
+};
+//#endregion
+//#region src/actor.ts
+function pickState(initial) {
+	return initial instanceof StateRef ? initial : initial.state;
+}
+function resolveInitial(initial) {
+	return pickState(initial);
+}
+var Actor = class {
+	state;
+	clock;
+	#context;
+	#options;
+	#regions = {};
+	#children = /* @__PURE__ */ new Map();
+	#queue = new InternalQueue();
+	#subs = new Subscribers();
+	#effectAbort = null;
+	#outputHandler = null;
+	#internalIds;
+	#inputIds;
+	#internalBudget;
+	#draining = false;
+	get context() {
+		return this.#context;
+	}
+	get regions() {
+		return this.#regions;
+	}
+	get options() {
+		return this.#options;
+	}
+	constructor(options) {
+		registerActor(this, {
+			children: this.#children,
+			getOutputHandler: () => this.#outputHandler,
+			setOutputHandler: (fn) => {
+				this.#outputHandler = fn;
+			},
+			pushInternal: (event) => this.#pushEvent(event),
+			drainInternal: () => this.#drainInternal(),
+			abortEffects: () => this.#abortEffects()
+		});
+		const builder = new ActorBuilder();
+		options.setup(builder);
+		const built = builder.build();
+		this.#options = {
+			...options,
+			transitions: built.transitions,
+			effects: built.effects
+		};
+		this.#internalIds = new Set((options.internal ?? []).map((e) => e.id));
+		this.#inputIds = new Set(options.inputs.map((e) => e.id));
+		this.#internalBudget = options.internalBudget ?? 1e4;
+		this.clock = options.clock ?? new RealClock();
+		this.clock.setDrain?.(() => this.#drainInternal());
+		const initState = resolveInitial(options.initial);
+		const stateNames = new Set(options.states.map((s) => s.name));
+		if (!stateNames.has(initState.name)) console.warn(`[Actor] initial state "${initState.name}" not found in declared states [${[...stateNames].join(", ")}]`);
+		this.state = initState;
+		this.#context = options.context ?? {};
+		if (options.regions) for (const [key, child] of Object.entries(options.regions)) {
+			this.#regions[key] = child;
+			const result = setOutputHandler(child, (event) => {
+				this.#queue.push(event);
+				this.#drainInternal();
+			});
+			if (result[0] !== void 0) console.error(result[0].message);
+			this.#children.set(key, child);
+		}
+	}
+	on(event, fn) {
+		if (event === "change") {
+			const cb = fn;
+			this.#subs.change.add(cb);
+			cb(this.snapshot());
+			return () => this.#subs.change.delete(cb);
+		}
+		const cb = fn;
+		this.#subs.done.add(cb);
+		return () => this.#subs.done.delete(cb);
+	}
+	settled() {
+		return this.#queue.settled();
+	}
+	send(event) {
+		this.#dispatch(event);
+	}
+	#dispatch(event) {
+		if (this.state.isFinal) return;
+		const transitions = this.#options.transitions;
+		const stateTransition = transitions[this.state.name]?.[event.id];
+		const anyTransition = transitions["Any"]?.[event.id];
+		const transitionApplied = stateTransition ? this.#applyStateStep(event, stateTransition) : false;
+		if ((anyTransition ? this.#applyAnyStep(event, anyTransition, !transitionApplied) : false) || this.#queue.length > 0) this.#drainInternal();
+		else if (!stateTransition && !anyTransition) console.warn(`[Actor] no transition for event "${event.id}" in state "${this.state.name}". Event dropped.`);
+	}
+	#applyStateStep(event, transition) {
+		const step = transition(event, {
+			context: this.#context,
+			actor: this
+		});
+		if (step.emit) this.#queue.push(...step.emit);
+		if (step.state) {
+			this.#applyTransition(event, step);
+			return true;
+		}
+		return false;
+	}
+	#applyAnyStep(event, transition, allowTransition) {
+		const step = transition(event, {
+			context: this.#context,
+			actor: this
+		});
+		if (step.state && allowTransition) this.#applyTransition(event, step);
+		if (step.emit) {
+			this.#queue.push(...step.emit);
+			return true;
+		}
+		return false;
+	}
+	snapshot() {
+		return buildSnapshot(this.state, this.#regions);
+	}
+	#pushEvent(event) {
+		this.#queue.push(event);
+	}
+	#abortEffects() {
+		this.#effectAbort?.abort();
+		this.#subs.clear();
+	}
+	#applyTransition(event, step) {
+		if (!step.state) return;
+		this.#effectAbort?.abort();
+		const resolved = parseTarget(step);
+		if (!resolved) return;
+		this.state = resolved.state;
+		this.#runEffects(event, resolved.payload);
+		this.#subs.emitChange(this.snapshot());
+		if (this.state.isFinal) this.#subs.emitDone();
+	}
+	#runEffects(event, statePayload) {
+		const list = this.#options.effects[this.state.name];
+		if (!list || list.length === 0) {
+			this.#effectAbort = null;
+			return;
+		}
+		const abort = runEffects({
+			effects: { [this.state.name]: list },
+			state: this.state,
+			statePayload,
+			event,
+			context: this.#context,
+			emit: (e) => {
+				this.#queue.push(e);
+				this.#drainInternal();
+			},
+			clock: this.clock
+		});
+		this.#effectAbort = abort;
+	}
+	#drainInternal() {
+		if (this.#draining) return;
+		this.#draining = true;
+		let budgetExceeded = false;
+		try {
+			const budget = this.#internalBudget;
+			let count = 0;
+			this.#queue.processCancellable((event) => {
+				if (count >= budget) {
+					budgetExceeded = true;
+					this.#abortEffects();
+					return false;
+				}
+				count++;
+				if (this.#internalIds.has(event.id)) this.#dispatch(event);
+				else if (this.#inputIds.has(event.id)) this.#dispatch(event);
+				else if (this.#outputHandler) this.#outputHandler(event);
+				return true;
+			});
+		} finally {
+			this.#draining = false;
+		}
+		if (budgetExceeded) console.warn(`[Actor] internal event budget (${this.#internalBudget}) exceeded — possible emit loop. Actor halting.`);
+	}
+};
+//#endregion
+//#region src/event.ts
+function event(id) {
+	return () => new EventRef(id);
+}
+var EventRef = class {
+	id;
+	constructor(id) {
+		this.id = id;
+	}
+	is(anyEvent) {
+		return !!anyEvent && typeof anyEvent === "object" && "id" in anyEvent && anyEvent.id === this.id;
+	}
+	create(payload) {
+		if (payload === void 0) return { id: this.id };
+		return {
+			...payload,
+			id: this.id
+		};
+	}
+};
+//#endregion
+export { Actor, EventRef, RealClock, StateRef, VirtualClock, event, state };

package/dist/internal.d.mts

@@ -0,0 +1,26 @@
+import { s as InternalEvent, t as AnyActor } from "./actor-internal-CfZDmHJ3.mjs";
+import { Either } from "@mantaq/utils";
+//#region src/internal-registry.d.ts
+interface ActorInternal {
+  children: Map<string, AnyActor>;
+  getOutputHandler(): ((event: InternalEvent) => void) | null;
+  setOutputHandler(fn: ((event: InternalEvent) => void) | null): void;
+  pushInternal(event: InternalEvent): void;
+  drainInternal(): void;
+  abortEffects(): void;
+}
+interface RegistryError {
+  message: string;
+}
+declare global {
+  var __mantaqCoreInternalRegistry: WeakMap<object, ActorInternal> | undefined;
+}
+declare function registerActor(actor: object, internal: ActorInternal): void;
+declare function getChildren(actor: object): Either<RegistryError, Map<string, AnyActor>>;
+declare function getOutputHandler(actor: object): Either<RegistryError, ((event: InternalEvent) => void) | null>;
+declare function setOutputHandler(actor: object, fn: ((event: InternalEvent) => void) | null): Either<RegistryError, void>;
+declare function pushInternal(actor: object, event: InternalEvent): Either<RegistryError, void>;
+declare function drainInternal(actor: object): Either<RegistryError, void>;
+declare function abortEffects(actor: object): Either<RegistryError, void>;
+//#endregion
+export { ActorInternal, RegistryError, abortEffects, drainInternal, getChildren, getOutputHandler, pushInternal, registerActor, setOutputHandler };

package/dist/internal.mjs

@@ -0,0 +1,31 @@
+import { Either } from "@mantaq/utils";
+//#region src/internal-registry.ts
+const registry = globalThis.__mantaqCoreInternalRegistry ??= /* @__PURE__ */ new WeakMap();
+const UNREGISTERED = { message: "[mantaq] actor is not registered with the internal registry" };
+function withInternal(actor, fn) {
+	const internal = registry.get(actor);
+	return internal === void 0 ? Either.left(UNREGISTERED) : [void 0, fn(internal)];
+}
+function registerActor(actor, internal) {
+	registry.set(actor, internal);
+}
+function getChildren(actor) {
+	return withInternal(actor, (internal) => internal.children);
+}
+function getOutputHandler(actor) {
+	return withInternal(actor, (internal) => internal.getOutputHandler());
+}
+function setOutputHandler(actor, fn) {
+	return withInternal(actor, (internal) => internal.setOutputHandler(fn));
+}
+function pushInternal(actor, event) {
+	return withInternal(actor, (internal) => internal.pushInternal(event));
+}
+function drainInternal(actor) {
+	return withInternal(actor, (internal) => internal.drainInternal());
+}
+function abortEffects(actor) {
+	return withInternal(actor, (internal) => internal.abortEffects());
+}
+//#endregion
+export { abortEffects, drainInternal, getChildren, getOutputHandler, pushInternal, registerActor, setOutputHandler };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mantaq/core",
+  "version": "0.0.1",
+  "description": "State machine runtime with actor model, event system, state hierarchy, effects, and virtual clock.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./internal": "./dist/internal.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mantaq/utils": "0.0.1"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "^9",
+    "@stryker-mutator/vitest-runner": "^9",
+    "@types/node": "^26.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+    "vite-plus": "0.2.8",
+    "vitest": "4.1.10",
+    "@mantaq/pbt": "0.0.1"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "coverage": "vp test run --coverage"
+  }
+}