@mantaq/sugar 0.0.2 → 0.2.0

package/README.md

@@ -89,7 +89,7 @@ import { events } from "@mantaq/sugar";
 
 const e = events("fetch", "resolve", "fail");
 
-e.fetch.create(); // { id: "fetch" }
+e.fetch.create(); // { type: "fetch" }
 e.resolve.is(emittedEvent); // boolean
 
 const actor = new Actor({
@@ -203,7 +203,7 @@ map.kill("child1");
 
 ```ts
 map.spawn("child1", () => createChild());
-map.spawn("child1", () => createChild()); // overwrites silently — previous child lost
+map.spawn("child1", () => createChild()); // warns, aborts the previous child, replaces
 ```
 
 `ensure()` is idempotent — safe to call repeatedly. `spawn()` always replaces.
@@ -217,8 +217,8 @@ 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) }),
+  success: (data) => ({ type: "loaded", payload: data }),
+  error: (err) => ({ type: "loadFailed", payload: String(err) }),
 });
 ```
 
@@ -227,14 +227,14 @@ withPromise(fetchData(), input.signal, input.emit, {
 ```ts
 fetchData()
   .then((data) => {
-    input.emit({ id: "loaded", data }); // fires even if actor destroyed
+    input.emit({ type: "loaded", payload: data }); // fires even if actor destroyed
   })
   .catch((err) => {
-    input.emit({ id: "loadFailed", error: String(err) }); // same problem
+    input.emit({ type: "loadFailed", payload: String(err) }); // same problem
   });
 ```
 
-`withPromise` checks `isAborted(signal)` before each emit. Manual chains fire events into destroyed actors.
+`withPromise` checks `signal.aborted` before each emit. Manual chains fire events into destroyed actors.
 
 ## Helpers
 
@@ -302,7 +302,7 @@ Send an event to every key in an `ActorMap` (or any `SendableMap`):
 ```ts
 import { broadcast } from "@mantaq/sugar";
 
-broadcast(map, { id: "ping" });
+broadcast(map, { type: "ping" });
 ```
 
 Works with `ActorMap` or any object implementing `{ keys(): string[]; send(key, event): void }`.
@@ -344,7 +344,7 @@ Batch-create `EventRef`s as a typed record:
 import { events } from "@mantaq/sugar";
 
 const e = events("click", "submit");
-e.click.create(); // { id: "click" }
+e.click.create(); // { type: "click" }
 e.click.is(emittedEvent); // boolean
 ```
 
@@ -356,8 +356,8 @@ Bridge a promise into actor events. Emits `success` on resolve, `error` on rejec
 import { withPromise } from "@mantaq/sugar";
 
 withPromise(fetchData(), input.signal, input.emit, {
-  success: (data) => ({ id: "loaded", data }),
-  error: (err) => ({ id: "loadFailed", error: String(err) }),
+  success: (data) => ({ type: "loaded", payload: data }),
+  error: (err) => ({ type: "loadFailed", payload: String(err) }),
 });
 ```
 
@@ -368,7 +368,7 @@ Schedule a timeout event through the actor's clock. Aborts cleanly if the actor
 ```ts
 import { withTimeout } from "@mantaq/sugar";
 
-withTimeout(5000, input, () => ({ id: "timeout", reason: "exceeded" }));
+withTimeout(5000, input, () => ({ type: "timeout", payload: { reason: "exceeded" } }));
 ```
 
 ## Migration from Core

package/dist/index.d.mts

@@ -6,8 +6,8 @@ declare function matches(actor: {
 //#endregion
 //#region src/transitions/broadcast.d.ts
 type EventLike = {
-  id: string;
-  [key: string]: unknown;
+  type: string;
+  payload?: unknown;
 };
 type SendableEvent = AnyEventRef | EventLike;
 interface SendableMap<T extends SendableEvent = SendableEvent> {
@@ -17,38 +17,62 @@ 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/effects/promise.d.ts
 type EmitFn = (event: {
-  id: string;
-  [key: string]: unknown;
+  type: string;
+  payload?: unknown;
 }) => void;
 declare function withPromise<T>(promise: Promise<T>, signal: AbortSignal, emit: EmitFn, events: {
   success: (data: T) => {
-    id: string;
-    [key: string]: unknown;
+    type: string;
+    payload?: unknown;
   };
   error: (err: unknown) => {
-    id: string;
-    [key: string]: unknown;
+    type: string;
+    payload?: unknown;
   };
 }): void;
 //#endregion

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { abortEffects, setOutputHandler } from "@mantaq/core/internal";
+import { abortEffects } from "@mantaq/core/internal";
 import { Either } from "@mantaq/utils";
 import { event, state } from "@mantaq/core";
 //#region src/actors/matches.ts
@@ -21,29 +21,44 @@ 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.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 +70,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 +79,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
@@ -88,11 +107,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/sugar",
-  "version": "0.0.2",
+  "version": "0.2.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.0.2",
-    "@mantaq/utils": "0.0.1"
+    "@mantaq/core": "0.2.0",
+    "@mantaq/utils": "0.0.2"
   },
   "devDependencies": {
     "@stryker-mutator/core": "^9",