ihsm 0.1.23 → 0.1.25

package/README.md

@@ -83,7 +83,7 @@ class Open extends DoorTop {
   }
 }
 
-const door = makeActor(DoorTop, { openCount: 0 }, new Port());
+const door = makeActor(DoorTop, { openCount: 0 });
 await door.hsm.sync();
 
 door.notify.open();
@@ -140,7 +140,7 @@ class WalletTop extends TopState<WalletConfig> {
 @InitialState
 class Open extends WalletTop {}
 
-const wallet = makeActor(WalletTop, { balance: 100 }, new Port());
+const wallet = makeActor(WalletTop, { balance: 100 });
 await wallet.hsm.sync();
 
 wallet.notify.deposit(50);
@@ -212,7 +212,7 @@ class Stopped extends PlayerTop {
   }
 }
 
-const player = makeActor(PlayerTop, { track: '' }, new Port());
+const player = makeActor(PlayerTop, { track: '' });
 await player.hsm.sync();
 
 player.notify.play();

package/lib/cjs/internal/console-instrumentation.d.ts

@@ -28,7 +28,7 @@ export interface ConsoleInstrumentationOptions {
  * ```ts
  * import { createConsoleInstrumentation, registerCollector, makeActor, Port } from 'ihsm';
  * registerCollector(createConsoleInstrumentation());
- * const actor = makeActor(Top, ctx, new Port(), { initialize: true });
+ * const actor = makeActor(Top, ctx, { initialize: true });
  * ```
  */
 export declare function createConsoleInstrumentation(options?: ConsoleInstrumentationOptions): Instrumentation;

package/lib/cjs/internal/console-instrumentation.js

@@ -23,7 +23,7 @@ function shortUuid(uuid) {
  * ```ts
  * import { createConsoleInstrumentation, registerCollector, makeActor, Port } from 'ihsm';
  * registerCollector(createConsoleInstrumentation());
- * const actor = makeActor(Top, ctx, new Port(), { initialize: true });
+ * const actor = makeActor(Top, ctx, { initialize: true });
  * ```
  */
 function createConsoleInstrumentation(options = {}) {

package/lib/cjs/internal/runtime.d.ts

@@ -1,4 +1,3 @@
-/** @internal Consolidated ihsm runtime (no pure types — see ./types.ts). */
 import type { ActorConfig, ActorContextOf, ActorConfigOf, ActorOptions, ChildActor, ChildHsm, DispatchableMachine, EmbodimentKind, ErrorHost, ExternalActor, ExternalHsm, HandlerHsm, HsmWithTracing, InboundActor, InboundHsm, Instance, NotificationQueue, ParentActor, PlannedTransition, IPort, MachinePortInput, Properties, ProtocolIndex, RandomService, ReservedName, SelfNotifications, ServiceCallOptions, StateClass, StateEvents, Task, TimerService, TopStateArg, TraceWriter, DispatchErrorCallback, Transition, TransitionResolver, TransitionHost, TransitionRoutineExecuteOptions, TransitionRoutinePlan, TransitionTracer, Disposable, EventObserver, TransitionTraceHost, ActorIdentity, ActorLogger, Instrumentation, OutboundCallBegin, TraceFrame } from './types';
 export declare enum TraceLevel {
     PRODUCTION = 0,
@@ -252,6 +251,10 @@ export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<
     private _traceDomainStack;
     protected _instrumentationHost?: InstrumentationHost;
     private _drainWaiters;
+    private _tasksSinceYield;
+    private _sliceStart;
+    /** @internal Pending actor initialization — always runs before hi-priority work. */
+    _initTask?: Task;
     constructor(TopState: StateClass<C>, instance: Instance<C>, traceWriter: TraceWriter, traceLevel: TraceLevel, dispatchErrorCallback: DispatchErrorCallback<C>, identity: ActorIdentity);
     get ctx(): ActorContextOf<C>;
     set ctx(ctx: ActorContextOf<C>);
@@ -282,10 +285,12 @@ export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<
     /** Invoke the user dispatch-error callback, first notifying instrumentation (pure observer). */
     reportDispatchError(err: Error): void;
     private flushDrainWaiters;
+    protected enqueueInitTask(task: Task): void;
     pushTask(t: Task): void;
     pushHiPriorityTask(t: Task): void;
     unshiftHiPriorityTask(t: Task): void;
     private enqueueTask;
+    private scheduleKickoff;
     restore(state: StateClass<C>, ctx: ActorContextOf<C>): void;
     private dequeue;
     private exec;
@@ -363,13 +368,24 @@ type ActorHandleFor<C extends ActorConfig, K extends EmbodimentKind> = K extends
 type SpawnContext<C extends ActorConfig = ActorConfig> = {
     readonly parentMachine?: Machine<C>;
 };
+/** @internal Distinguish {@link ActorOptions} from a port when the port argument is omitted. */
+export declare function isActorOptions(value: unknown): value is ActorOptions<ActorConfig>;
+/** @internal */
+export declare function resolveFactoryPortAndOptions<C extends ActorConfig>(portOrOptions?: MachinePortInput<C> | ActorOptions<C>, maybeOptions?: ActorOptions<C>): {
+    port: MachinePortInput<C> | undefined;
+    options: ActorOptions<C>;
+};
 /** @internal Spawn with embodiment kind — used by factories and `ihsm/testing`. */
 export declare function spawnActor<C extends ActorConfig, K extends EmbodimentKind>(kind: K, topState: TopStateArg<C>, ctx: ActorContextOf<C>, port: MachinePortInput<C> | undefined, options: ActorOptions<C>, spawnContext?: SpawnContext<C>): ActorHandleFor<C, K>;
 /** Production black-box — public protocol only (generated handle). */
-export declare function makeActor<T extends TopStateArg<ActorConfig>>(topState: T, ctx: ActorContextOf<ActorConfigOf<T>>, port?: MachinePortInput<ActorConfigOf<T>>, options?: ActorOptions<ActorConfigOf<T>>): ExternalActor<ActorConfigOf<T>>;
+export declare function makeActor<T extends TopStateArg<ActorConfig>>(topState: T, ctx: ActorContextOf<ActorConfigOf<T>>, options?: ActorOptions<ActorConfigOf<T>>): ExternalActor<ActorConfigOf<T>>;
+export declare function makeActor<T extends TopStateArg<ActorConfig>>(topState: T, ctx: ActorContextOf<ActorConfigOf<T>>, port: MachinePortInput<ActorConfigOf<T>>, options?: ActorOptions<ActorConfigOf<T>>): ExternalActor<ActorConfigOf<T>>;
 export declare function asParentActor<T extends TopStateArg<ActorConfig>>(handler: TopState<ActorConfigOf<T>>): ParentActor<T>;
 /** Parent composes a child machine — returns full child protocol shell with `parent` set. */
-export declare function makeChildActor<ParentT extends TopStateArg<ActorConfig>, ChildT extends TopStateArg<ActorConfig>>(parent: ParentActor<ParentT>, childTop: ChildT, childCtx: ActorContextOf<ActorConfigOf<ChildT>>, port?: MachinePortInput<ActorConfigOf<ChildT>>, options?: ActorOptions<ActorConfigOf<ChildT>>): ChildActor<ActorConfigOf<ChildT>> & {
+export declare function makeChildActor<ParentT extends TopStateArg<ActorConfig>, ChildT extends TopStateArg<ActorConfig>>(parent: ParentActor<ParentT>, childTop: ChildT, childCtx: ActorContextOf<ActorConfigOf<ChildT>>, options?: ActorOptions<ActorConfigOf<ChildT>>): ChildActor<ActorConfigOf<ChildT>> & {
+    readonly parent: ParentActor<ParentT>;
+};
+export declare function makeChildActor<ParentT extends TopStateArg<ActorConfig>, ChildT extends TopStateArg<ActorConfig>>(parent: ParentActor<ParentT>, childTop: ChildT, childCtx: ActorContextOf<ActorConfigOf<ChildT>>, port: MachinePortInput<ActorConfigOf<ChildT>>, options?: ActorOptions<ActorConfigOf<ChildT>>): ChildActor<ActorConfigOf<ChildT>> & {
     readonly parent: ParentActor<ParentT>;
 };
 export { kHandlerMachine, kParentLink } from './types';

package/lib/cjs/internal/runtime.js

@@ -33,10 +33,15 @@ exports.createNotificationTask = createNotificationTask;
 exports.createServiceTask = createServiceTask;
 exports.isRequestingPort = isRequestingPort;
 exports.defaultDispatchErrorCallback = defaultDispatchErrorCallback;
+exports.isActorOptions = isActorOptions;
+exports.resolveFactoryPortAndOptions = resolveFactoryPortAndOptions;
 exports.spawnActor = spawnActor;
 exports.makeActor = makeActor;
 exports.asParentActor = asParentActor;
 exports.makeChildActor = makeChildActor;
+/** @internal Consolidated ihsm runtime (no pure types — see ./types.ts). */
+/// <reference types="node" />
+const scheduler_1 = require("./scheduler");
 const types_1 = require("./types");
 const identity_1 = require("./identity");
 const instrumentation_1 = require("./instrumentation");
@@ -1614,6 +1619,10 @@ class HsmObject {
     _traceDomainStack;
     _instrumentationHost;
     _drainWaiters = [];
+    _tasksSinceYield = 0;
+    _sliceStart = 0;
+    /** @internal Pending actor initialization — always runs before hi-priority work. */
+    _initTask;
     constructor(TopState, instance, traceWriter, traceLevel, dispatchErrorCallback, identity) {
         this._instance = instance;
         this._transitionState = undefined;
@@ -1729,6 +1738,13 @@ class HsmObject {
         for (const resolve of waiters)
             resolve();
     }
+    enqueueInitTask(task) {
+        this._initTask = task;
+        if (this._isRunning)
+            return;
+        this._isRunning = true;
+        this.scheduleKickoff();
+    }
     pushTask(t) {
         this.enqueueTask(t, this._jobs);
     }
@@ -1740,31 +1756,53 @@ class HsmObject {
         if (this._isRunning)
             return;
         this._isRunning = true;
-        this.dequeue();
+        this.scheduleKickoff();
     }
     enqueueTask(t, queue) {
         queue.push(t);
         if (this._isRunning)
             return;
         this._isRunning = true;
-        this.dequeue();
+        this.scheduleKickoff();
+    }
+    scheduleKickoff() {
+        queueMicrotask(() => this.dequeue());
     }
     restore(state, ctx) {
         this.currentState = state;
         this.ctx = ctx;
     }
     dequeue() {
-        if (this._hiPriorityJobs.length == 0 && this._jobs.length == 0) {
+        if (this._initTask === undefined && this._hiPriorityJobs.length == 0 && this._jobs.length == 0) {
             this._isRunning = false;
             this._instrumentationHost?.onQueuesDrained();
             this.flushDrainWaiters();
             return;
         }
+        if (this._initTask !== undefined) {
+            const task = this._initTask;
+            this._initTask = undefined;
+            this.exec(task);
+            return;
+        }
         const task = this._hiPriorityJobs.length > 0 ? this._hiPriorityJobs.shift() : this._jobs.shift();
         this.exec(task);
     }
     exec(task) {
-        setTimeout(() => this.runTask(task).then(() => this.dequeue()), 0);
+        if (this._tasksSinceYield === 0) {
+            this._sliceStart = (0, scheduler_1.nowMs)();
+        }
+        void this.runTask(task).then(() => {
+            this._tasksSinceYield++;
+            const overBudget = this._tasksSinceYield >= scheduler_1.YIELD_TASK_BUDGET || (0, scheduler_1.nowMs)() - this._sliceStart >= scheduler_1.YIELD_TIME_BUDGET_MS;
+            if (overBudget) {
+                this._tasksSinceYield = 0;
+                (0, scheduler_1.yieldToMacrotask)(() => this.dequeue());
+            }
+            else {
+                this.dequeue();
+            }
+        });
     }
     runTask(task) {
         this._instrumentationHost?.onTaskBegin(task);
@@ -1881,7 +1919,7 @@ class Machine extends HsmObject {
         if (initialize) {
             const initTask = createInitTask(this, this.transitionResolver);
             (0, instrumentation_1.setTaskMeta)(initTask, { event: 'initialize', queue: 'default', triggerKind: 'init', internal: false });
-            this.pushTask(initTask);
+            this.enqueueInitTask(initTask);
         }
     }
     allocateChildSpawnIndex(childTopName) {
@@ -2453,6 +2491,31 @@ function defaultDispatchErrorCallback(hsm, err) {
     hsm.traceWriter.write(hsm, err);
     throw err;
 }
+const ACTOR_OPTION_KEYS = new Set(['initialize', 'traceLevel', 'traceWriter', 'dispatchErrorCallback', 'transitions']);
+/** @internal Distinguish {@link ActorOptions} from a port when the port argument is omitted. */
+function isActorOptions(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    if (value instanceof Port || isRequestingPort(value)) {
+        return false;
+    }
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+        return true;
+    }
+    return keys.every(key => ACTOR_OPTION_KEYS.has(key));
+}
+/** @internal */
+function resolveFactoryPortAndOptions(portOrOptions, maybeOptions) {
+    if (maybeOptions !== undefined) {
+        return { port: portOrOptions, options: maybeOptions };
+    }
+    if (portOrOptions !== undefined && isActorOptions(portOrOptions)) {
+        return { port: undefined, options: portOrOptions };
+    }
+    return { port: portOrOptions, options: {} };
+}
 /** @internal Spawn with embodiment kind — used by factories and `ihsm/testing`. */
 function spawnActor(kind, topState, ctx, port, options, spawnContext = {}) {
     const { initialize = exports.defaultInitialize, traceLevel = TraceLevel.DEBUG, traceWriter = exports.defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback, transitions } = options;
@@ -2495,9 +2558,9 @@ function spawnActor(kind, topState, ctx, port, options, spawnContext = {}) {
     boundPort.actor = createActorHandle(machine, topState, protocolIndex, portKind);
     return createActorHandle(machine, topState, protocolIndex, kind);
 }
-/** Production black-box — public protocol only (generated handle). */
-function makeActor(topState, ctx, port, options = {}) {
-    return spawnActor('root', topState, ctx, port, options);
+function makeActor(topState, ctx, portOrOptions, options) {
+    const { port, options: resolvedOptions } = resolveFactoryPortAndOptions(portOrOptions, options);
+    return spawnActor('root', topState, ctx, port, resolvedOptions);
 }
 function asParentActor(handler) {
     const machine = handler[types_1.kHandlerMachine];
@@ -2509,10 +2572,10 @@ function asParentActor(handler) {
         [types_1.kParentLink]: machine,
     };
 }
-/** Parent composes a child machine — returns full child protocol shell with `parent` set. */
-function makeChildActor(parent, childTop, childCtx, port, options = {}) {
+function makeChildActor(parent, childTop, childCtx, portOrOptions, options) {
+    const { port, options: resolvedOptions } = resolveFactoryPortAndOptions(portOrOptions, options);
     const parentMachine = parent[types_1.kParentLink];
-    const child = spawnActor('child', childTop, childCtx, port, options, { parentMachine: parentMachine });
+    const child = spawnActor('child', childTop, childCtx, port, resolvedOptions, { parentMachine: parentMachine });
     Object.defineProperty(child, 'parent', { value: parent, enumerable: true, writable: false, configurable: true });
     return child;
 }