@mantaq/sugar 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anders Can
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,418 @@
+# @mantaq/sugar
+
+Convenience helpers for [@mantaq/core](../core) actors. State/event batching, pattern matching, effect utilities, and dynamic child management.
+
+## Install
+
+```bash
+npm install @mantaq/sugar
+# or
+pnpm add @mantaq/sugar
+# or
+yarn add @mantaq/sugar
+```
+
+## Quick Start
+
+```ts
+import { states, events, matches, withTimeout } from "@mantaq/sugar";
+import { Actor, VirtualClock } from "@mantaq/core";
+
+const s = states("idle", "loading", "success", "error");
+const e = events("fetch", "resolve", "fail");
+
+const clock = new VirtualClock();
+
+const machine = new Actor({
+  inputs: [e.fetch],
+  internal: [e.resolve, e.fail],
+  context: {},
+  states: [s.idle, s.loading, s.success, s.error],
+  initial: s.idle,
+  clock,
+  setup: (m) => {
+    m.on(s.idle, e.fetch, () => ({ state: s.loading }));
+    m.effect(s.loading, (input) => withTimeout(2000, input, () => e.resolve.create()));
+    m.on(s.loading, e.resolve, () => ({ state: s.success }));
+    m.on(s.loading, e.fail, () => ({ state: s.error }));
+  },
+});
+
+matches(machine, "idle"); // true
+machine.send(e.fetch.create());
+matches(machine, "loading"); // true
+clock.advance(2000);
+matches(machine, "success"); // true
+```
+
+## Patterns
+
+### Type-safe state groups with `states()`
+
+Use `states()` to create a record of `StateRef`s with full type safety. The returned keys match the input strings exactly.
+
+```ts
+import { states } from "@mantaq/sugar";
+
+const s = states("idle", "loading", "success", "error");
+
+s.idle.name; // "idle"
+s.success.final(); // StateRef with isFinal = true
+
+const actor = new Actor({
+  states: [s.idle, s.loading, s.success, s.error],
+  initial: s.idle,
+  // ...
+});
+```
+
+**Anti-pattern:** Creating states manually without `states()` and losing type safety:
+
+```ts
+import { state } from "@mantaq/core";
+
+const idle = state("idle")();
+const loading = state("loading")();
+const success = state("success")();
+const error = state("error")();
+// No single record — easy to miss one, no autocomplete, no compile check
+```
+
+`states()` guarantees all names exist as typed keys. Manual creation requires you to keep references in sync yourself.
+
+### Type-safe event groups with `events()`
+
+Same as `states()` but for events. Creates a typed record with `.create()`, `.is()`, and other `EventRef` methods.
+
+```ts
+import { events } from "@mantaq/sugar";
+
+const e = events("fetch", "resolve", "fail");
+
+e.fetch.create(); // { id: "fetch" }
+e.resolve.is(emittedEvent); // boolean
+
+const actor = new Actor({
+  inputs: [e.fetch],
+  internal: [e.resolve],
+  // ...
+});
+```
+
+**Anti-pattern:** Scattering event refs across files without a shared group:
+
+```ts
+import { event } from "@mantaq/core";
+
+const fetchEvent = event("fetch")();
+const resolveEvent = event("resolve")();
+const failEvent = event("fail")();
+// No single source of truth — naming drift, typos not caught
+```
+
+`events()` creates a single typed object. Any typo in a key is a compile error.
+
+### Pattern matching with `matches()`
+
+`matches()` uses dot-separated paths. The format alternates between state names and region keys: `"state.regionKey.state"`.
+
+```ts
+import { matches } from "@mantaq/sugar";
+
+// flat
+matches(actor, "idle"); // true if in idle
+
+// hierarchical — state, region key, nested state
+matches(actor, "connected.default.active");
+
+// parallel — match any region
+matches(actor, "player.playing");
+```
+
+**Anti-pattern:** Using wrong path format:
+
+```ts
+// WRONG — region key must come after parent state
+matches(actor, "active.connected.default");
+
+// WRONG — trailing dot always returns false
+matches(actor, "idle.");
+
+// WRONG — empty string returns false
+matches(actor, "");
+```
+
+Path format: `"parentState.regionKey.childState"`. The region key is the key you passed to the actor's `regions` option, not the nested state's name.
+
+### Using `tag()` for state grouping
+
+`tag()` groups multiple `StateRef`s and tests if a snapshot matches any of them. Useful for UI that needs to branch on state categories.
+
+```ts
+import { tag } from "@mantaq/sugar";
+
+const s = states("idle", "loading", "success", "error");
+const busy = tag(s.idle, s.loading);
+const terminal = tag(s.success, s.error);
+
+// In UI
+if (busy.has(snapshot)) {
+  showSpinner();
+} else if (terminal.has(snapshot)) {
+  showResult();
+}
+```
+
+**Anti-pattern:** Testing individual states manually with `matches()`:
+
+```ts
+if (matches(actor, "idle") || matches(actor, "loading")) {
+  showSpinner();
+}
+// Breaks when hierarchy changes, verbose, error-prone
+```
+
+`tag()` searches recursively through parallel regions and nested hierarchies — works regardless of depth.
+
+### ActorMap patterns
+
+`ActorMap` manages dynamic children by string key. Always use `ensure()` to avoid duplicate spawns.
+
+```ts
+import { ActorMap, isIn } from "@mantaq/sugar";
+
+const map = new ActorMap(parentActor);
+
+// Safe spawn — no-op if key exists
+map.ensure("child1", () => createChild());
+
+// Send events
+map.send("child1", someEvent);
+
+// Snapshot a child
+const snap = map.snapshot("child1");
+if (snap && isIn(snap, "active")) {
+  // child is active
+}
+
+// Kill when done
+map.kill("child1");
+```
+
+**Anti-pattern:** Using `spawn()` without checking for duplicates:
+
+```ts
+map.spawn("child1", () => createChild());
+map.spawn("child1", () => createChild()); // overwrites silently — previous child lost
+```
+
+`ensure()` is idempotent — safe to call repeatedly. `spawn()` always replaces.
+
+### Effect utilities: `withPromise` vs manual handling
+
+Always use `withPromise()` for promise-to-event bridging. It handles abort signals automatically.
+
+```ts
+import { withPromise } from "@mantaq/sugar";
+
+// Correct — abort-aware
+withPromise(fetchData(), input.signal, input.emit, {
+  success: (data) => ({ id: "loaded", data }),
+  error: (err) => ({ id: "loadFailed", error: String(err) }),
+});
+```
+
+**Anti-pattern:** Manual `.then()/.catch()` without abort handling:
+
+```ts
+fetchData()
+  .then((data) => {
+    input.emit({ id: "loaded", data }); // fires even if actor destroyed
+  })
+  .catch((err) => {
+    input.emit({ id: "loadFailed", error: String(err) }); // same problem
+  });
+```
+
+`withPromise` checks `isAborted(signal)` before each emit. Manual chains fire events into destroyed actors.
+
+## Helpers
+
+### `matches(actor, pattern)`
+
+Dot-notation state pattern matching against an actor's snapshot. Works with flat, hierarchical, and parallel states.
+
+```ts
+import { matches } from "@mantaq/sugar";
+
+// flat
+matches(actor, "idle"); // true/false
+
+// hierarchical — region path
+matches(actor, "connected.default.active");
+
+// parallel — any region matches
+matches(actor, "player.playback.playing");
+```
+
+Pattern format: `"state.regionKey.state"` or just `"state"` for flat. Empty string or trailing dots return `false`.
+
+### `ActorMap`
+
+Dynamic child actor registry. Spawns, sends to, kills, and snapshots children by string key. Optionally wires child output to a parent actor.
+
+```ts
+import { ActorMap, isIn } from "@mantaq/sugar";
+
+const map = new ActorMap(); // or new ActorMap(parentActor)
+
+map.spawn("child1", () => childActor);
+map.spawn("child2", () => otherActor);
+
+map.send("child1", someEvent);
+map.kill("child2");
+map.keys(); // ["child1"]
+
+const snap = map.snapshot("child1"); // Snapshot | undefined
+if (snap && isIn(snap, "active")) {
+  // child is active
+}
+```
+
+**`ensure(key, factory)`** — spawn only if key missing:
+
+```ts
+map.ensure("child1", () => childActor); // no-op if exists
+```
+
+**Typing children:** `ActorMap` is untyped by design. Access children through your own typed references or use `matches()` / `snapshot()` for type-safe checks.
+
+**Parent wiring:** When constructed with a parent actor, child outputs are automatically forwarded to the parent:
+
+```ts
+const map = new ActorMap(parentActor);
+map.spawn("child", () => childActor);
+// child emits → parent receives
+```
+
+### `broadcast(map, event)`
+
+Send an event to every key in an `ActorMap` (or any `SendableMap`):
+
+```ts
+import { broadcast } from "@mantaq/sugar";
+
+broadcast(map, { id: "ping" });
+```
+
+Works with `ActorMap` or any object implementing `{ keys(): string[]; send(key, event): void }`.
+
+### `tag(...stateRefs)`
+
+Group multiple `StateRef`s and test if a snapshot matches any of them. Useful for UI state grouping.
+
+```ts
+import { tag } from "@mantaq/sugar";
+import { state } from "@mantaq/core";
+
+const idle = state("idle")();
+const loading = state("loading")();
+const busy = tag(idle, loading);
+
+busy.has(snapshot); // true if snapshot is idle or loading (any depth)
+```
+
+Searches recursively through parallel regions and nested hierarchies.
+
+### `states(...names)`
+
+Batch-create `StateRef`s as a typed record:
+
+```ts
+import { states } from "@mantaq/sugar";
+
+const s = states("idle", "loading", "success");
+s.idle.name; // "idle"
+s.success.final(); // StateRef with isFinal = true
+```
+
+### `events(...names)`
+
+Batch-create `EventRef`s as a typed record:
+
+```ts
+import { events } from "@mantaq/sugar";
+
+const e = events("click", "submit");
+e.click.create(); // { id: "click" }
+e.click.is(emittedEvent); // boolean
+```
+
+### `withPromise(promise, signal, emit, events)`
+
+Bridge a promise into actor events. Emits `success` on resolve, `error` on reject. Respects `AbortSignal` — skips emit if aborted before settlement.
+
+```ts
+import { withPromise } from "@mantaq/sugar";
+
+withPromise(fetchData(), input.signal, input.emit, {
+  success: (data) => ({ id: "loaded", data }),
+  error: (err) => ({ id: "loadFailed", error: String(err) }),
+});
+```
+
+### `withTimeout(ms, input, eventFn)`
+
+Schedule a timeout event through the actor's clock. Aborts cleanly if the actor is destroyed before timeout fires.
+
+```ts
+import { withTimeout } from "@mantaq/sugar";
+
+withTimeout(5000, input, () => ({ id: "timeout", reason: "exceeded" }));
+```
+
+## Migration from Core
+
+Starting with `@mantaq/core`? Here's what sugar adds.
+
+| Core                                    | Sugar                                        | Benefit                                                                   |
+| --------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
+| `state("idle")()` × N                   | `states("idle", "loading")`                  | Single call. Typed record. No missed names.                               |
+| `event("FETCH")()` × N                  | `events("FETCH", "RESOLVE")`                 | Single call. Typed record. Shared source of truth.                        |
+| `snapshot().path.includes("active")`    | `matches(actor, "active")`                   | Works on actor directly. Dot-notation for hierarchies: `"idle.region.a"`. |
+| Manual `.then()/.catch()` + abort check | `withPromise(promise, signal, emit, events)` | Auto abort-aware. No forgotten `signal.aborted` guard.                    |
+| Group states by variable naming         | `tag(stateA, stateB).has(snapshot)`          | Recursive matching. Works through parallel regions.                       |
+
+**Core alone:**
+
+```ts
+import { state, event } from "@mantaq/core";
+
+const idle = state("idle")();
+const loading = state("loading")();
+const success = state("success")();
+const failEvent = event("FAIL")();
+
+actor.snapshot().path.includes("idle"); // flat name only
+```
+
+**With sugar:**
+
+```ts
+import { states, events, matches, tag } from "@mantaq/sugar";
+
+const s = states("idle", "loading", "success");
+const e = events("FAIL");
+
+matches(actor, "idle"); // actor, not snapshot
+matches(actor, "connected.default.active"); // hierarchical
+
+const busy = tag(s.idle, s.loading);
+busy.has(actor.snapshot()); // recursive
+```
+
+No migration needed. Sugar wraps core — use both side by side.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+import { AnyActor, AnyEventRef, EffectInput, EventRef, InternalEvent, Snapshot, StateRef } from "@mantaq/core";
+//#region src/actors/matches.d.ts
+declare function matches(actor: {
+  snapshot(): Snapshot;
+}, pattern: string): boolean;
+//#endregion
+//#region src/transitions/broadcast.d.ts
+type EventLike = {
+  id: string;
+  [key: string]: unknown;
+};
+type SendableEvent = AnyEventRef | EventLike;
+interface SendableMap<T extends SendableEvent = SendableEvent> {
+  keys(): string[];
+  send(key: string, event: T): void;
+}
+declare function broadcast<const T extends SendableEvent>(map: SendableMap<T>, event: T): void;
+//#endregion
+//#region src/actors/actor-map.d.ts
+declare class ActorMap implements SendableMap<SendableEvent> {
+  #private;
+  constructor(parent?: AnyActor);
+  spawn(key: string, factory: () => AnyActor): void;
+  send(key: string, event: SendableEvent): void;
+  kill(key: string): void;
+  get size(): number;
+  has(key: string): boolean;
+  keys(): string[];
+  ensure(key: string, factory: () => AnyActor): void;
+  snapshot(key: string): Snapshot | undefined;
+}
+//#endregion
+//#region src/state.d.ts
+declare function states<T extends string>(...names: T[]): { [K in T]: StateRef<K>; };
+//#endregion
+//#region src/event.d.ts
+declare function events<T extends string>(...names: T[]): { [K in T]: EventRef<K>; };
+//#endregion
+//#region src/effects/promise.d.ts
+type EmitFn = (event: {
+  id: string;
+  [key: string]: unknown;
+}) => void;
+declare function withPromise<T>(promise: Promise<T>, signal: AbortSignal, emit: EmitFn, events: {
+  success: (data: T) => {
+    id: string;
+    [key: string]: unknown;
+  };
+  error: (err: unknown) => {
+    id: string;
+    [key: string]: unknown;
+  };
+}): void;
+//#endregion
+//#region src/effects/timeout.d.ts
+declare function withTimeout<ActorContext>(ms: number, input: EffectInput<ActorContext>, event: () => InternalEvent): void;
+//#endregion
+//#region src/tags.d.ts
+interface Tag {
+  has(snapshot: Snapshot): boolean;
+}
+declare function tag(...stateNames: StateRef<string, unknown>[]): Tag;
+//#endregion
+//#region src/snapshot.d.ts
+declare function isIn(snapshot: Snapshot, stateRefName: string): boolean;
+declare function activeLeaves(snapshot: Snapshot): string[];
+//#endregion
+export { ActorMap, type EventLike, type SendableEvent, type SendableMap, activeLeaves, broadcast, events, isIn, matches, states, tag, withPromise, withTimeout };

package/dist/index.mjs

@@ -0,0 +1,122 @@
+import { abortEffects, setOutputHandler } from "@mantaq/core/internal";
+import { Either } from "@mantaq/utils";
+import { event, state } from "@mantaq/core";
+//#region src/actors/matches.ts
+function matchSnapshot(snapshot, parts, index) {
+	const stateName = snapshot.path[0];
+	for (let end = index; end < parts.length; end++) {
+		if (parts.slice(index, end + 1).join(".") !== stateName) continue;
+		if (end === parts.length - 1) return true;
+		const regionSnap = snapshot.regions[parts[end + 1]];
+		if (!regionSnap) return false;
+		if (end + 1 === parts.length - 1) return true;
+		return matchSnapshot(regionSnap, parts, end + 2);
+	}
+	return false;
+}
+function matches(actor, pattern) {
+	if (!pattern || pattern.endsWith(".") || pattern.startsWith(".") || pattern.includes("..")) return false;
+	const parts = pattern.split(".");
+	return matchSnapshot(actor.snapshot(), parts, 0);
+}
+//#endregion
+//#region src/actors/actor-map.ts
+var ActorMap = class {
+	#actors = /* @__PURE__ */ new Map();
+	#parent;
+	constructor(parent) {
+		this.#parent = parent ?? null;
+	}
+	spawn(key, factory) {
+		if (this.#actors.has(key)) {
+			console.warn(`[ActorMap] spawning over existing key "${key}". Old actor will be aborted.`);
+			this.kill(key);
+		}
+		const child = factory();
+		if (this.#parent) Either.match(setOutputHandler(child, (event) => {
+			this.#parent.send(event);
+		}), (err) => console.error(err.message), () => {});
+		this.#actors.set(key, child);
+	}
+	send(key, event) {
+		this.#actors.get(key)?.send(event);
+	}
+	kill(key) {
+		const actor = this.#actors.get(key);
+		if (actor) Either.match(abortEffects(actor), (err) => console.error(err.message), () => {});
+		this.#actors.delete(key);
+	}
+	get size() {
+		return this.#actors.size;
+	}
+	has(key) {
+		return this.#actors.has(key);
+	}
+	keys() {
+		return [...this.#actors.keys()];
+	}
+	ensure(key, factory) {
+		if (!this.#actors.has(key)) this.spawn(key, factory);
+	}
+	snapshot(key) {
+		return this.#actors.get(key)?.snapshot();
+	}
+};
+//#endregion
+//#region src/state.ts
+function states(...names) {
+	const result = {};
+	for (const name of names) result[name] = state(name)();
+	return result;
+}
+//#endregion
+//#region src/event.ts
+function events(...names) {
+	const result = {};
+	for (const name of names) result[name] = event(name)();
+	return result;
+}
+//#endregion
+//#region src/effects/promise.ts
+function withPromise(promise, signal, emit, events) {
+	promise.then((data) => {
+		if (!signal.aborted) emit(events.success(data));
+	}).catch((err) => {
+		if (!signal.aborted) emit(events.error(err));
+	});
+}
+//#endregion
+//#region src/effects/timeout.ts
+function withTimeout(ms, input, event) {
+	if (typeof ms !== "number" || ms < 0 || !Number.isFinite(ms)) console.warn(`[withTimeout] invalid ms value: ${ms}. Timeout may not fire.`);
+	input.clock.setTimeout(ms, () => {
+		if (input.signal.aborted) return;
+		input.emit(event());
+	});
+}
+//#endregion
+//#region src/transitions/broadcast.ts
+function broadcast(map, event) {
+	for (const key of map.keys()) map.send(key, event);
+}
+//#endregion
+//#region src/snapshot.ts
+function isIn(snapshot, stateRefName) {
+	if (snapshot.path[0] === stateRefName) return true;
+	for (const region of Object.values(snapshot.regions)) if (isIn(region, stateRefName)) return true;
+	return false;
+}
+function activeLeaves(snapshot) {
+	if (Object.keys(snapshot.regions).length === 0) return [snapshot.path.join(".")];
+	const leaves = [];
+	for (const [regionName, region] of Object.entries(snapshot.regions)) for (const leaf of activeLeaves(region)) leaves.push(`${snapshot.path[0]}.${regionName}.${leaf}`);
+	return leaves;
+}
+//#endregion
+//#region src/tags.ts
+function tag(...stateNames) {
+	const names = stateNames.map((s) => s.name);
+	return { has: (snapshot) => names.some((name) => isIn(snapshot, name)) };
+}
+//#endregion
+export { ActorMap, activeLeaves, broadcast, events, isIn, matches, states, tag, withPromise, withTimeout };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mantaq/sugar",
+  "version": "0.0.1",
+  "description": "Userland sugar for mantaq actors — matches, effect helpers, transition utilities.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AndersCan/mantaq",
+    "directory": "packages/sugar"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mantaq/core": "0.0.1",
+    "@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": "^7.0.2",
+    "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",
+    "mutation": "stryker run",
+    "coverage": "vp test run --coverage"
+  }
+}