@mantaq/sugar 0.2.0 → 0.4.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

@@ -1,4 +1,4 @@
-import { AnyActor, AnyEventRef, EffectInput, EventRef, InternalEvent, Snapshot, StateRef } from "@mantaq/core";
+import { Actor, ActorBuilder, ActorOptions, AnyActor, AnyEventRef, AnyStateRef, Clock, EffectInput, EventRef, InitialState, InternalEvent, Snapshot, StateRef } from "@mantaq/core";
 //#region src/actors/matches.d.ts
 declare function matches(actor: {
   snapshot(): Snapshot;
@@ -60,6 +60,16 @@ declare function states<const T extends StatesArg[]>(...entries: T): StatesRecor
 //#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;
@@ -85,8 +95,52 @@ interface Tag {
 }
 declare function tag(...stateNames: StateRef<string, unknown>[]): Tag;
 //#endregion
+//#region src/parts.d.ts
+interface ActorSpec {
+  states: readonly AnyStateRef[];
+  inputs: readonly AnyEventRef[];
+  internal?: readonly AnyEventRef[];
+  outputs?: readonly AnyEventRef[];
+  context?: unknown;
+  initial: AnyStateRef | {
+    state: AnyStateRef;
+    payload?: unknown;
+  };
+  clock?: Clock;
+  regions?: Record<string, AnyActor>;
+  internalBudget?: number;
+}
+type NotUndef<T> = [Exclude<T, undefined>] extends [never] ? never : Exclude<T, undefined>;
+type InternalOf<S extends ActorSpec> = "internal" extends keyof S ? [NotUndef<S["internal"]>] extends [never] ? readonly [] : NotUndef<S["internal"]> : readonly [];
+type OutputsOf<S extends ActorSpec> = "outputs" extends keyof S ? [NotUndef<S["outputs"]>] extends [never] ? readonly [] : NotUndef<S["outputs"]> : readonly [];
+type ContextOf<S extends ActorSpec> = "context" extends keyof S ? [NotUndef<S["context"]>] extends [never] ? Record<string, unknown> : NotUndef<S["context"]> : Record<string, unknown>;
+type BuilderOf<S extends ActorSpec> = ActorBuilder<S["states"], S["inputs"], InternalOf<S>, OutputsOf<S>, ContextOf<S>>;
+type Fragment<S extends ActorSpec> = (m: BuilderOf<S>) => void;
+declare function definePart<S extends ActorSpec = never>(fn: (m: BuilderOf<S>) => void): Fragment<S>;
+declare function use<S extends ActorSpec>(m: BuilderOf<S>, part: Fragment<S>): void;
+type Part<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
+type SpecValue<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext, Initial> = {
+  states: States;
+  inputs: Inputs;
+  internal?: Internal;
+  outputs?: Outputs;
+  context?: ActorContext;
+  clock?: Clock;
+  regions?: Record<string, AnyActor>;
+  internalBudget?: number;
+  initial: Initial;
+};
+/**
+ * Construct the actor's static spec — states, inputs, internal/output events,
+ * context, initial state, clock, regions and budget. State/event tuples and
+ * the initial ref narrow to literals; the context stays mutable, so
+ * `definePart` handlers read and write it with no `as` casts.
+ */
+declare function actorSpec<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>, const Initial extends InitialState<States[number]> = InitialState<States[number]>>(spec: SpecValue<States, Inputs, Internal, Outputs, ActorContext, Initial>): SpecValue<States, Inputs, Internal, Outputs, ActorContext, Initial>;
+declare function withParts<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>>(base: Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup">, parts: Part<States, Inputs, Internal, Outputs, ActorContext> | readonly Part<States, Inputs, Internal, Outputs, ActorContext>[]): Actor<States, Inputs, Internal, Outputs, ActorContext>;
+//#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 };
+export { ActorMap, type ActorSpec, type BuilderOf, type EventLike, type Fragment, type Part, type SendableEvent, type SendableMap, activeLeaves, actorSpec, broadcast, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };

package/dist/index.mjs

@@ -1,6 +1,4 @@
-import { abortEffects } from "@mantaq/core/internal";
-import { Either } from "@mantaq/utils";
-import { event, state } from "@mantaq/core";
+import { Actor, event, state } from "@mantaq/core";
 //#region src/actors/matches.ts
 function matchSnapshot(snapshot, parts, index) {
 	const stateName = snapshot.path[0];
@@ -45,6 +43,7 @@ var ActorMap = class {
 			}
 			const off = child.on("done", () => {
 				if (this.#actors.get(key) === child) this.#actors.delete(key);
+				this.#reapers.delete(key);
 			});
 			this.#reapers.set(key, off);
 		}
@@ -53,10 +52,7 @@ var ActorMap = class {
 		this.#actors.get(key)?.send(event);
 	}
 	kill(key) {
-		const actor = this.#actors.get(key);
-		if (actor) Either.match(abortEffects(actor), (err) => {
-			throw new Error(err.message);
-		}, () => {});
+		this.#actors.get(key)?.dispose();
 		this.#reapers.get(key)?.();
 		this.#reapers.delete(key);
 		this.#actors.delete(key);
@@ -96,6 +92,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) {
+	actor.on("output", handler);
+}
+//#endregion
 //#region src/effects/promise.ts
 function withPromise(promise, signal, emit, events) {
 	promise.then((data) => {
@@ -137,4 +145,30 @@ function tag(...stateNames) {
 	return { has: (snapshot) => names.some((name) => isIn(snapshot, name)) };
 }
 //#endregion
-export { ActorMap, activeLeaves, broadcast, events, isIn, matches, states, tag, withPromise, withTimeout };
+//#region src/parts.ts
+function definePart(fn) {
+	return fn;
+}
+function use(m, part) {
+	part(m);
+}
+/**
+* Construct the actor's static spec — states, inputs, internal/output events,
+* context, initial state, clock, regions and budget. State/event tuples and
+* the initial ref narrow to literals; the context stays mutable, so
+* `definePart` handlers read and write it with no `as` casts.
+*/
+function actorSpec(spec) {
+	return spec;
+}
+function withParts(base, parts) {
+	const list = Array.isArray(parts) ? parts : [parts];
+	return new Actor({
+		...base,
+		setup: (m) => {
+			for (const part of list) part(m);
+		}
+	});
+}
+//#endregion
+export { ActorMap, activeLeaves, actorSpec, broadcast, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };

package/package.json

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