@mantaq/sugar 1.0.0 → 2.0.1

package/README.md

@@ -387,6 +387,36 @@ withPromise(fetchData(), input.signal, input.emit, {
 });
 ```
 
+#### Errors as values
+
+When a port returns `Promise<Either<PortError, Loaded>>`, map the result with `Either.match` inside `success`. No new helper is needed, and both branches stay typed without a cast:
+
+```ts
+import { Either } from "@mantaq/utils";
+import { withPromise } from "@mantaq/sugar";
+
+m.effect(loading, {
+  name: "load",
+  sends: [loaded, failed, loadRejected],
+  fn: (input) =>
+    withPromise({
+      promise: port.load(),
+      signal: input.signal,
+      emit: input.emit,
+      events: {
+        success: (result) =>
+          Either.match(result, {
+            onLeft: (e): LoadEvent => failed.create(e), // e: PortError
+            onRight: (v): LoadEvent => loaded.create(v), // v: Loaded
+          }),
+        error: (err) => loadRejected.create({ message: String(err) }),
+      },
+    }),
+});
+```
+
+`LoadEvent` is the union of the two event shapes; annotating both handlers with it lets `Either.match` infer one result type. A rejected promise still goes through `error`, and an effect aborted before the promise settles emits nothing. See `src/effects/promise.either.test.ts`.
+
 ### `withTimeout(ms, input, eventFn)`
 
 Schedule a timeout event through the actor's clock. Aborts cleanly if the actor is destroyed before timeout fires.

package/dist/index.d.mts

@@ -1,5 +1,4 @@
 import { Actor, ActorBuilder, ActorOptions, AnyActor, AnyEventRef, AnyStateRef, Clock, EffectInput, EventRef, InitialState, InternalEvent, Snapshot, StateRef } from "@mantaq/core";
-//#region src/actors/matches.d.ts
 interface MatchTarget {
   snapshot(): Snapshot;
 }
@@ -8,9 +7,7 @@ interface MatchTarget {
  * pattern as one dotted string or as separate segments. A segment containing
  * dots matches states whose own name contains dots.
  */
-declare function matches(actor: MatchTarget, ...pattern: [pattern: string]): boolean;
-//#endregion
-//#region src/transitions/broadcast.d.ts
+export declare function matches(actor: MatchTarget, ...pattern: [pattern: string]): boolean;
 /**
  * Plain event shape sugar helpers accept next to core event refs.
  */
@@ -30,9 +27,7 @@ interface SendableMap<T extends SendableEvent = SendableEvent> {
  * Fan every given event out to all children of the map, once per key, in
  * key order.
  */
-declare function broadcast<const T extends SendableEvent>(map: SendableMap<T>, ...events: [event: T]): void;
-//#endregion
-//#region src/actors/actor-map.d.ts
+export declare function broadcast<const T extends SendableEvent>(map: SendableMap<T>, ...events: [event: T]): void;
 /**
  * Minimal actor surface the map needs. Real actors satisfy this
  * structurally — tests can substitute tiny fakes.
@@ -63,11 +58,9 @@ interface ActorMap extends SendableMap<SendableEvent> {
   snapshot(key: string): Snapshot | undefined;
   readonly size: number;
 }
-declare function createActorMap(factory: (id: string) => ActorMapChild, { autoReap }?: {
+export declare function createActorMap(factory: (id: string) => ActorMapChild, { autoReap }?: {
   autoReap?: boolean;
 }): ActorMap;
-//#endregion
-//#region src/state.d.ts
 interface StatesEntry {
   name: string;
   final?: boolean;
@@ -80,12 +73,8 @@ 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
+export declare function states<const T extends StatesArg[]>(...entries: T): StatesRecord<T>;
+export declare function events<T extends string>(...names: T[]): { [K in T]: EventRef<K>; };
 /**
  * Route an actor's emitted outputs to one or more handlers.
  *
@@ -94,43 +83,30 @@ declare function events<T extends string>(...names: T[]): { [K in T]: EventRef<K
  * factory connects a child's declared outputs to a receiver — pass several
  * handlers to feed multiple receivers.
  */
-declare function onOutput(actor: AnyActor, ...handlers: [handler: (event: InternalEvent) => void]): void;
-//#endregion
-//#region src/effects/promise.d.ts
-type EmitFn = (event: {
+export declare function onOutput(actor: AnyActor, ...handlers: [handler: (event: InternalEvent) => void]): void;
+type AnyEvent = {
   type: string;
   payload?: unknown;
-}) => void;
-interface WithPromiseOptions<T> {
+};
+/** `Emit`: events the effect may send; follows the effect's `sends` list when declared. */
+interface WithPromiseOptions<T, Emit = AnyEvent> {
   promise: Promise<T>;
   signal: AbortSignal;
-  emit: EmitFn;
+  emit: (event: Emit) => void;
   events: {
-    success: (data: T) => {
-      type: string;
-      payload?: unknown;
-    };
-    error: (err: unknown) => {
-      type: string;
-      payload?: unknown;
-    };
+    success: (data: T) => NoInfer<Emit>;
+    error: (err: unknown) => NoInfer<Emit>;
   };
 }
-declare function withPromise<T>(options: WithPromiseOptions<T>): Promise<void>;
-//#endregion
-//#region src/effects/timeout.d.ts
-declare function withTimeout<ActorContext>(durationMs: number, options: {
-  input: EffectInput<ActorContext>;
-  event: () => InternalEvent;
+export declare function withPromise<T, Emit = AnyEvent>(options: WithPromiseOptions<T, Emit>): Promise<void>;
+export declare function withTimeout<ActorContext, Payload = unknown, Emit extends InternalEvent = InternalEvent>(durationMs: number, options: {
+  input: EffectInput<ActorContext, Payload, Emit>;
+  event: () => NoInfer<Emit>;
 }): void;
-//#endregion
-//#region src/tags.d.ts
 interface Tag {
   has(snapshot: Snapshot): boolean;
 }
-declare function tag(...stateRefs: StateRef<string, unknown>[]): Tag;
-//#endregion
-//#region src/parts.d.ts
+export declare function tag(...stateRefs: StateRef<string, unknown>[]): Tag;
 interface ActorSpec {
   states: readonly AnyStateRef[];
   inputs: readonly AnyEventRef[];
@@ -151,9 +127,9 @@ type OutputsOf<S extends ActorSpec> = "outputs" extends keyof S ? [NotUndef<S["o
 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> = (builder: BuilderOf<S>) => void;
-declare function definePart<S extends ActorSpec = never>(part: (builder: BuilderOf<S>) => void): Fragment<S>;
+export declare function definePart<S extends ActorSpec = never>(part: (builder: BuilderOf<S>) => void): Fragment<S>;
 /** Apply one or more parts to a builder, in order. */
-declare function use<S extends ActorSpec>(builder: BuilderOf<S>, ...parts: [Fragment<S>, ...Fragment<S>[]]): void;
+export declare function use<S extends ActorSpec>(builder: BuilderOf<S>, ...parts: [Fragment<S>, ...Fragment<S>[]]): void;
 type Part<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (builder: 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;
@@ -172,18 +148,15 @@ type SpecValue<States extends readonly AnyStateRef[], Inputs extends readonly An
  * the initial ref narrow to literals while 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>;
+export 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>;
 /**
  * Build an actor whose setup applies every given part in order. Pass parts
  * as separate arguments — single part or many.
  */
-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>[]): Actor<States, Inputs, Internal, Outputs, ActorContext>;
-//#endregion
-//#region src/snapshot.d.ts
+export 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>[]): Actor<States, Inputs, Internal, Outputs, ActorContext>;
 /**
  * True when any of the named states is active anywhere in the snapshot tree.
  */
-declare function isIn(snapshot: Snapshot, ...stateNames: [stateName: string]): boolean;
-declare function activeLeaves(snapshot: Snapshot): string[];
-//#endregion
-export { type ActorMap, type ActorMapChild, type ActorSpec, type BuilderOf, type EventLike, type Fragment, type Part, type SendableEvent, type SendableMap, type WithPromiseOptions, activeLeaves, actorSpec, broadcast, createActorMap, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };
+export declare function isIn(snapshot: Snapshot, ...stateNames: [stateName: string]): boolean;
+export declare function activeLeaves(snapshot: Snapshot): string[];
+export type { ActorMap, ActorMapChild, ActorSpec, BuilderOf, EventLike, Fragment, Part, SendableEvent, SendableMap, WithPromiseOptions };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { Actor, event, state } from "@mantaq/core";
-//#region src/actors/matches.ts
+// src/actors/matches.ts
 function matchFrom(patternParts) {
 	function matchRegion(options) {
 		const stateName = options.snapshot.path[0];
@@ -31,8 +31,7 @@ function matches(actor, ...pattern) {
 		index: 0
 	});
 }
-//#endregion
-//#region src/actors/actor-map.ts
+// src/actors/actor-map.ts
 function createActorMap(factory, { autoReap } = {}) {
 	const actors = /* @__PURE__ */ new Map();
 	const reapers = /* @__PURE__ */ new Map();
@@ -100,8 +99,7 @@ function createActorMap(factory, { autoReap } = {}) {
 		}
 	};
 }
-//#endregion
-//#region src/parse-refs.ts
+// src/parse-refs.ts
 /**
 * Boundary utility for the `states()` and `events()` helpers. Ref records are
 * built dynamically, keyed by a literal name tuple. TypeScript cannot express
@@ -114,8 +112,7 @@ function parseStateRefs(record) {
 function parseEventRefs(record) {
 	return record;
 }
-//#endregion
-//#region src/state.ts
+// src/state.ts
 function states(...entries) {
 	const result = {};
 	for (const entry of entries) {
@@ -125,15 +122,13 @@ function states(...entries) {
 	}
 	return parseStateRefs(result);
 }
-//#endregion
-//#region src/event.ts
+// src/event.ts
 function events(...names) {
 	const result = {};
 	for (const name of names) result[name] = event(name)();
 	return parseEventRefs(result);
 }
-//#endregion
-//#region src/output.ts
+// src/output.ts
 /**
 * Route an actor's emitted outputs to one or more handlers.
 *
@@ -145,8 +140,7 @@ function events(...names) {
 function onOutput(actor, ...handlers) {
 	for (const handler of handlers) actor.on("output", { fn: handler });
 }
-//#endregion
-//#region src/effects/promise.ts
+// src/effects/promise.ts
 function withPromise(options) {
 	const { promise, signal, emit, events } = options;
 	return promise.then((data) => {
@@ -155,20 +149,19 @@ function withPromise(options) {
 		if (!signal.aborted) emit(events.error(err));
 	});
 }
-//#endregion
-//#region src/effects/timeout.ts
+// src/effects/timeout.ts
 function withTimeout(durationMs, options) {
 	const { input, event } = options;
 	input.clock.setTimeout(durationMs, {
 		signal: input.signal,
+		eventName: event().type,
 		cb: () => {
 			if (input.signal.aborted) return;
 			input.emit(event());
 		}
 	});
 }
-//#endregion
-//#region src/transitions/broadcast.ts
+// src/transitions/broadcast.ts
 /**
 * Fan every given event out to all children of the map, once per key, in
 * key order.
@@ -176,8 +169,7 @@ function withTimeout(durationMs, options) {
 function broadcast(map, ...events) {
 	for (const event of events) for (const key of map.keys()) map.send(key, event);
 }
-//#endregion
-//#region src/snapshot.ts
+// src/snapshot.ts
 function isInState(options) {
 	if (options.snapshot.path[0] === options.stateName) return true;
 	for (const region of Object.values(options.snapshot.regions)) if (isInState({
@@ -201,14 +193,12 @@ function activeLeaves(snapshot) {
 	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
+// src/tags.ts
 function tag(...stateRefs) {
 	const names = stateRefs.map((ref) => ref.name);
 	return { has: (snapshot) => names.some((name) => isIn(snapshot, name)) };
 }
-//#endregion
-//#region src/parts.ts
+// src/parts.ts
 function definePart(part) {
 	return part;
 }
@@ -237,5 +227,4 @@ function withParts(base, ...parts) {
 		}
 	});
 }
-//#endregion
 export { activeLeaves, actorSpec, broadcast, createActorMap, definePart, events, isIn, matches, onOutput, states, tag, use, withParts, withPromise, withTimeout };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/sugar",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "description": "Userland sugar for mantaq actors — matches, effect helpers, transition utilities.",
   "license": "MIT",
   "repository": {
@@ -20,19 +20,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/core": "0.4.0"
+    "@mantaq/core": "0.5.1"
   },
   "devDependencies": {
-    "@stryker-mutator/core": "^9",
-    "@stryker-mutator/vitest-runner": "^9",
+    "@stryker-mutator/core": "^10",
+    "@stryker-mutator/vitest-runner": "^10",
     "@types/node": "^26.2.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/coverage-v8": "5.0.5",
     "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.3"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0",
+    "vitest": "5.0.5",
+    "@mantaq/pbt": "0.0.3",
+    "@mantaq/utils": "0.0.4"
   },
   "scripts": {
     "build": "vp pack",