@mantaq/sugar 0.1.0 → 0.3.0

package/README.md

@@ -307,6 +307,29 @@ broadcast(map, { type: "ping" });
 
 Works with `ActorMap` or any object implementing `{ keys(): string[]; send(key, event): void }`.
 
+### `onOutput(actor, handler)`
+
+Route an actor's emitted outputs to a handler. `regions` auto-wire child
+outputs into the parent; ActorMap children do not — this is the public
+wrapper for that wiring seam, no internal import needed:
+
+```ts
+import { ActorMap, onOutput } from "@mantaq/sugar";
+
+const requests = new ActorMap(
+  (id) => {
+    const child = createHandler(id);
+    onOutput(child, (e) => {
+      if (result.is(e)) parent.send(e);
+    });
+    return child;
+  },
+  { autoReap: true },
+);
+```
+
+The `is()` guard narrows the output to the receiver's declared input.
+
 ### `tag(...stateRefs)`
 
 Group multiple `StateRef`s and test if a snapshot matches any of them. Useful for UI state grouping.

package/dist/index.d.mts

@@ -17,25 +17,59 @@ interface SendableMap<T extends SendableEvent = SendableEvent> {
 declare function broadcast<const T extends SendableEvent>(map: SendableMap<T>, event: T): void;
 //#endregion
 //#region src/actors/actor-map.d.ts
+interface ActorMapOptions {
+  /**
+   * When true, a child that reaches a final state (or dies into `__error`)
+   * is removed from the map automatically. Without it, completed children
+   * linger until explicitly `kill`ed.
+   */
+  autoReap?: boolean;
+}
+/**
+ * Keyed registry of one actor type. `spawn(key)` builds a fresh instance via
+ * the factory — same actor shape, keyed by id. The factory receives the key.
+ */
 declare class ActorMap implements SendableMap<SendableEvent> {
   #private;
-  constructor(parent?: AnyActor);
-  spawn(key: string, factory: () => AnyActor): void;
+  constructor(factory: (id: string) => AnyActor, options?: ActorMapOptions);
+  spawn(key: string): 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;
+  ensure(key: string): 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>; };
+interface StatesEntry {
+  name: string;
+  final?: boolean;
+}
+type StatesArg = string | StatesEntry;
+type NameOf<T> = T extends string ? T : T extends {
+  name: infer N extends string;
+} ? N : never;
+type FinalOf<T> = T extends {
+  final: true;
+} ? true : false;
+type StatesRecord<T extends StatesArg[]> = { [K in T[number] as NameOf<K>]: StateRef<NameOf<K>, unknown, FinalOf<K>>; };
+declare function states<const T extends StatesArg[]>(...entries: T): StatesRecord<T>;
 //#endregion
 //#region src/event.d.ts
 declare function events<T extends string>(...names: T[]): { [K in T]: EventRef<K>; };
 //#endregion
+//#region src/output.d.ts
+/**
+ * Route an actor's emitted outputs to a handler.
+ *
+ * `regions` auto-wire child outputs into the parent. ActorMap children do
+ * not — this is the public wrapper for that wiring seam. One call in the
+ * factory connects a child's declared outputs to a receiver.
+ */
+declare function onOutput(actor: AnyActor, handler: (event: InternalEvent) => void): void;
+//#endregion
 //#region src/effects/promise.d.ts
 type EmitFn = (event: {
   type: string;
@@ -65,4 +99,4 @@ declare function tag(...stateNames: StateRef<string, unknown>[]): Tag;
 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 };
+export { ActorMap, type EventLike, type SendableEvent, type SendableMap, activeLeaves, broadcast, events, isIn, matches, onOutput, states, tag, withPromise, withTimeout };

package/dist/index.mjs

@@ -21,29 +21,45 @@ function matches(actor, pattern) {
 }
 //#endregion
 //#region src/actors/actor-map.ts
+/**
+* Keyed registry of one actor type. `spawn(key)` builds a fresh instance via
+* the factory — same actor shape, keyed by id. The factory receives the key.
+*/
 var ActorMap = class {
 	#actors = /* @__PURE__ */ new Map();
-	#parent;
-	constructor(parent) {
-		this.#parent = parent ?? null;
+	#reapers = /* @__PURE__ */ new Map();
+	#factory;
+	#autoReap;
+	constructor(factory, options = {}) {
+		this.#factory = factory;
+		this.#autoReap = options.autoReap === true;
 	}
-	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), () => {});
+	spawn(key) {
+		if (this.#actors.has(key)) this.kill(key);
+		const child = this.#factory(key);
 		this.#actors.set(key, child);
+		if (this.#autoReap) {
+			if (child.snapshot().done) {
+				this.#actors.delete(key);
+				return;
+			}
+			const off = child.on("done", () => {
+				if (this.#actors.get(key) === child) this.#actors.delete(key);
+				this.#reapers.delete(key);
+			});
+			this.#reapers.set(key, off);
+		}
 	}
 	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), () => {});
+		if (actor) Either.match(abortEffects(actor), (err) => {
+			throw new Error(err.message);
+		}, () => {});
+		this.#reapers.get(key)?.();
+		this.#reapers.delete(key);
 		this.#actors.delete(key);
 	}
 	get size() {
@@ -55,8 +71,8 @@ var ActorMap = class {
 	keys() {
 		return [...this.#actors.keys()];
 	}
-	ensure(key, factory) {
-		if (!this.#actors.has(key)) this.spawn(key, factory);
+	ensure(key) {
+		if (!this.#actors.has(key)) this.spawn(key);
 	}
 	snapshot(key) {
 		return this.#actors.get(key)?.snapshot();
@@ -64,9 +80,13 @@ var ActorMap = class {
 };
 //#endregion
 //#region src/state.ts
-function states(...names) {
+function states(...entries) {
 	const result = {};
-	for (const name of names) result[name] = state(name)();
+	for (const entry of entries) {
+		const name = typeof entry === "string" ? entry : entry.name;
+		const ref = state(name)();
+		result[name] = typeof entry === "object" && entry.final ? ref.final() : ref;
+	}
 	return result;
 }
 //#endregion
@@ -77,6 +97,18 @@ function events(...names) {
 	return result;
 }
 //#endregion
+//#region src/output.ts
+/**
+* Route an actor's emitted outputs to a handler.
+*
+* `regions` auto-wire child outputs into the parent. ActorMap children do
+* not — this is the public wrapper for that wiring seam. One call in the
+* factory connects a child's declared outputs to a receiver.
+*/
+function onOutput(actor, handler) {
+	setOutputHandler(actor, handler);
+}
+//#endregion
 //#region src/effects/promise.ts
 function withPromise(promise, signal, emit, events) {
 	promise.then((data) => {
@@ -88,11 +120,10 @@ function withPromise(promise, signal, emit, events) {
 //#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());
-	});
+	}, { signal: input.signal });
 }
 //#endregion
 //#region src/transitions/broadcast.ts
@@ -119,4 +150,4 @@ function tag(...stateNames) {
 	return { has: (snapshot) => names.some((name) => isIn(snapshot, name)) };
 }
 //#endregion
-export { ActorMap, activeLeaves, broadcast, events, isIn, matches, states, tag, withPromise, withTimeout };
+export { ActorMap, activeLeaves, broadcast, events, isIn, matches, onOutput, states, tag, withPromise, withTimeout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/sugar",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Userland sugar for mantaq actors — matches, effect helpers, transition utilities.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/core": "0.1.0",
-    "@mantaq/utils": "0.0.2"
+    "@mantaq/utils": "0.0.2",
+    "@mantaq/core": "0.2.0"
   },
   "devDependencies": {
     "@stryker-mutator/core": "^9",