effect-machine 0.21.0 → 0.22.0

package/README.md

@@ -204,6 +204,7 @@ Read [Atom and UI integration](./docs/atom-and-ui.md) and browse [all examples](
 - Durability saves committed transitions.
 - Supervision restarts defects within an Effect `Schedule` budget.
 - Inspection reports events, named transition operations, transitions, named guards, tasks, Effects, errors, stops, and actor generations.
+- Dynamic Inspector hubs let lazy tools observe existing actors without actor restart or state duplication.
 
 Read [Persistence and supervision](./docs/persistence-and-supervision.md) and [Inspection](./docs/inspection.md).
 

package/dist/index.d.ts

@@ -6,5 +6,5 @@ import { Durability, DurabilityCommit, FinalContext, GuardPredicate, HandlerCont
 import { ProcessEventResult } from "./internal/transition.js";
 import { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemKey, ActorSystemService, Default, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, actorSystemKey } from "./actor.js";
 import { InputTestHarnessOptions, SimulationOptions, SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { type ActorClient, ActorExit, type ActorExit as ActorExitType, type ActorLifecycle, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystemKey, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type FinalContext, type GuardEvent, type GuardPredicate, type HandlerContext, type InputMakeConfig, type InputTestHarnessOptions, type InspectionEvent, type InspectorService as Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, NoReplyError, type OperationEvent, PersistenceError, type ProcessEventResult, type Recovery, type RecoveryContext, type ReplayOptions, type ReplyFields, type ReplyResult, type SimulationOptions, type SimulationResult, type SpawnEvent, type SpawnOptions, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type SystemSpawnOptions, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type TransitionEvent, type TransitionInfo, VersionConflictError, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorHub, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, tracingInspector } from "./inspection.js";
+export { type ActorClient, ActorExit, type ActorExit as ActorExitType, type ActorLifecycle, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystemKey, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type FinalContext, type GuardEvent, type GuardPredicate, type HandlerContext, type InputMakeConfig, type InputTestHarnessOptions, type InspectionEvent, type InspectorService as Inspector, type InspectorHandler, type InspectorHub, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, NoReplyError, type OperationEvent, PersistenceError, type ProcessEventResult, type Recovery, type RecoveryContext, type ReplayOptions, type ReplyFields, type ReplyResult, type SimulationOptions, type SimulationResult, type SpawnEvent, type SpawnOptions, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type SystemSpawnOptions, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type TransitionEvent, type TransitionInfo, VersionConflictError, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, makeInspectorHub, simulate, tracingInspector };

package/dist/index.js

@@ -1,8 +1,8 @@
 import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, NoReplyError, PersistenceError, VersionConflictError } from "./errors.js";
 import { Event, State } from "./schema.js";
-import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
+import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, tracingInspector } from "./inspection.js";
 import { ActorExit, Supervision } from "./supervision.js";
 import { ActorScope, ActorSystem, ActorSystemKey, Default, actorSystemKey } from "./actor.js";
 import { machine_exports } from "./machine.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-export { ActorExit, ActorScope, ActorStoppedError, Default as ActorSystemDefault, ActorSystemKey, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, NoReplyError, PersistenceError, State, Supervision, VersionConflictError, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, ActorScope, ActorStoppedError, Default as ActorSystemDefault, ActorSystemKey, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, NoReplyError, PersistenceError, State, Supervision, VersionConflictError, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, makeInspectorHub, simulate, tracingInspector };

package/dist/inspection.d.ts

@@ -124,6 +124,13 @@ type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Ef
 interface InspectorService<S, E> {
   readonly onInspect: InspectorHandler<S, E>;
 }
+/**
+ * Dynamic Inspector fan-out for applications that load inspection consumers after actors start.
+ */
+interface InspectorHub<S, E> {
+  readonly inspector: InspectorService<S, E>;
+  readonly register: (inspector: InspectorService<S, E>) => () => void;
+}
 declare const Inspector_base: Context.ServiceClass<Inspector, "effect-machine/inspection/Inspector", InspectorService<any, any>>;
 /**
  * Inspector service tag - optional service for machine introspection
@@ -149,6 +156,17 @@ declare const makeInspectorEffect: <S = {
   readonly _tag: string;
 }>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void>) => InspectorService<ResolveType<S>, ResolveType<E>>;
 declare const combineInspectors: <S, E>(...inspectors: ReadonlyArray<InspectorService<S, E>>) => InspectorService<S, E>;
+/**
+ * Create an Inspector that accepts sinks throughout its lifetime.
+ *
+ * Provide `hub.inspector` before actor startup. Consumers can then register and unregister sinks
+ * without restarting the actor. A sink failure does not affect the actor or other sinks.
+ */
+declare const makeInspectorHub: <S = {
+  readonly _tag: string;
+}, E = {
+  readonly _tag: string;
+}>() => InspectorHub<ResolveType<S>, ResolveType<E>>;
 interface TracingInspectorOptions<S, E> {
   readonly spanName?: string | ((event: InspectionEvent<S, E>) => string);
   readonly attributes?: (event: InspectionEvent<S, E>) => Readonly<Record<string, string | number | boolean>>;
@@ -176,4 +194,4 @@ declare const collectingInspector: <S extends {
   readonly _tag: string;
 }>(events: InspectionEvent<S, E>[]) => InspectorService<S, E>;
 //#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };
+export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorHub, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, tracingInspector };

package/dist/inspection.js

@@ -15,15 +15,39 @@ var Inspector = class extends Context.Service()("effect-machine/inspection/Inspe
 */
 const makeInspector = (onInspect) => ({ onInspect });
 const makeInspectorEffect = (onInspect) => ({ onInspect });
-const inspectionEffect = (inspector, event) => {
+const inspectionEffect = (inspector, event) => Effect.suspend(() => {
 	const result = inspector.onInspect(event);
 	if (Effect.isEffect(result)) return result;
 	return Effect.void;
-};
+});
 const combineInspectors = (...inspectors) => ({ onInspect: (event) => Effect.forEach(inspectors, (inspector) => inspectionEffect(inspector, event).pipe(Effect.ignoreCause), {
 	concurrency: 16,
 	discard: true
 }) });
+/**
+* Create an Inspector that accepts sinks throughout its lifetime.
+*
+* Provide `hub.inspector` before actor startup. Consumers can then register and unregister sinks
+* without restarting the actor. A sink failure does not affect the actor or other sinks.
+*/
+const makeInspectorHub = () => {
+	const inspectorByRegistration = /* @__PURE__ */ new Map();
+	const inspector = { onInspect: (event) => Effect.forEach(Array.from(inspectorByRegistration.values()), (registeredInspector) => inspectionEffect(registeredInspector, event).pipe(Effect.ignoreCause), {
+		concurrency: 16,
+		discard: true
+	}) };
+	const register = (registeredInspector) => {
+		const registration = Symbol();
+		inspectorByRegistration.set(registration, registeredInspector);
+		return () => {
+			inspectorByRegistration.delete(registration);
+		};
+	};
+	return {
+		inspector,
+		register
+	};
+};
 const inspectionSpanName = (event) => {
 	switch (event.type) {
 		case "@machine.spawn": return `Machine.inspect ${event.initialState._tag}`;
@@ -157,4 +181,4 @@ const collectingInspector = (events) => ({ onInspect: (event) => {
 	events.push(event);
 } });
 //#endregion
-export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };
+export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, makeInspectorHub, tracingInspector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"