[core] Event emitter

packages/core/src/actions/emit.ts

@@ -0,0 +1,152 @@
+import isDevelopment from '#is-development';
+import {
+  ActionArgs,
+  AnyActorScope,
+  AnyActor,
+  AnyMachineSnapshot,
+  DelayExpr,
+  EventObject,
+  MachineContext,
+  NoInfer,
+  RaiseActionOptions,
+  SendExpr,
+  ParameterizedObject,
+  AnyEventObject
+} from '../types.ts';
+
+function resolveEmit(
+  _: AnyActorScope,
+  snapshot: AnyMachineSnapshot,
+  args: ActionArgs<any, any, any>,
+  actionParams: ParameterizedObject['params'] | undefined,
+  {
+    event: eventOrExpr,
+    id,
+    delay
+  }: {
+    event:
+      | EventObject
+      | SendExpr<
+          MachineContext,
+          EventObject,
+          ParameterizedObject['params'] | undefined,
+          EventObject,
+          EventObject
+        >;
+    id: string | undefined;
+    delay:
+      | string
+      | number
+      | DelayExpr<
+          MachineContext,
+          EventObject,
+          ParameterizedObject['params'] | undefined,
+          EventObject
+        >
+      | undefined;
+  },
+  { internalQueue }: { internalQueue: AnyEventObject[] }
+) {
+  const delaysMap = snapshot.machine.implementations.delays;
+
+  if (typeof eventOrExpr === 'string') {
+    throw new Error(
+      `Only event objects may be used with emit; use emit({ type: "${eventOrExpr}" }) instead`
+    );
+  }
+  const resolvedEvent =
+    typeof eventOrExpr === 'function'
+      ? eventOrExpr(args, actionParams)
+      : eventOrExpr;
+
+  let resolvedDelay: number | undefined;
+  if (typeof delay === 'string') {
+    const configDelay = delaysMap && delaysMap[delay];
+    resolvedDelay =
+      typeof configDelay === 'function'
+        ? configDelay(args, actionParams)
+        : configDelay;
+  } else {
+    resolvedDelay =
+      typeof delay === 'function' ? delay(args, actionParams) : delay;
+  }
+  if (typeof resolvedDelay !== 'number') {
+    internalQueue.push(resolvedEvent);
+  }
+  return [snapshot, { event: resolvedEvent, id, delay: resolvedDelay }];
+}
+
+function executeEmit(
+  actorScope: AnyActorScope,
+  params: {
+    event: EventObject;
+    id: string | undefined;
+    delay: number | undefined;
+  }
+) {
+  const { event, delay, id } = params;
+  // if (typeof delay === 'number') {
+  actorScope.defer(() => {
+    actorScope.emit(event);
+  });
+  return;
+  // }
+}
+
+export interface RaiseAction<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TParams extends ParameterizedObject['params'] | undefined,
+  TEvent extends EventObject,
+  TDelay extends string
+> {
+  (args: ActionArgs<TContext, TExpressionEvent, TEvent>, params: TParams): void;
+  _out_TEvent?: TEvent;
+  _out_TDelay?: TDelay;
+}
+
+/**
+ * Raises an event. This places the event in the internal event queue, so that
+ * the event is immediately consumed by the machine in the current step.
+ *
+ * @param eventType The event to raise.
+ */
+export function emit<
+  TContext extends MachineContext,
+  TExpressionEvent extends EventObject,
+  TEvent extends EventObject = TExpressionEvent,
+  TParams extends ParameterizedObject['params'] | undefined =
+    | ParameterizedObject['params']
+    | undefined,
+  TDelay extends string = string
+>(
+  eventOrExpr:
+    | AnyEventObject
+    | SendExpr<TContext, TExpressionEvent, TParams, AnyEventObject, TEvent>,
+  options?: RaiseActionOptions<
+    TContext,
+    TExpressionEvent,
+    TParams,
+    NoInfer<TEvent>,
+    NoInfer<TDelay>
+  >
+): RaiseAction<TContext, TExpressionEvent, TParams, TEvent, TDelay> {
+  function emit(
+    args: ActionArgs<TContext, TExpressionEvent, TEvent>,
+    params: TParams
+  ) {
+    if (isDevelopment) {
+      throw new Error(`This isn't supposed to be called`);
+    }
+  }
+
+  emit.type = 'xstate.emit';
+  emit.event = eventOrExpr;
+  emit.id = options?.id;
+  emit.delay = options?.delay;
+
+  emit.resolve = resolveEmit;
+  emit.execute = executeEmit;
+
+  return emit;
+}

packages/core/src/createActor.ts

@@ -14,6 +14,7 @@ import { AnyActorSystem, Clock, createSystem } from './system.ts';
 import type {
   ActorScope,
   AnyActorLogic,
+  AnyEventObject,
   ConditionalRequired,
   DoneActorEvent,
   EventFromLogic,
@@ -44,6 +45,7 @@ export type EventListener<TEvent extends EventObject = EventObject> = (
 
 export type Listener = () => void;
 export type ErrorListener = (error: any) => void;
+export type EmittedEventHandler = (event: AnyEventObject) => void;
 
 // those values are currently used by @xstate/react directly so it's important to keep the assigned values in sync
 export enum ProcessingStatus {
@@ -91,6 +93,7 @@ export class Actor<TLogic extends AnyActorLogic>
   );
 
   private observers: Set<Observer<SnapshotFrom<TLogic>>> = new Set();
+  private eventListeners: Map<string, Set<EmittedEventHandler>> = new Map();
   private logger: (...args: any[]) => void;
 
   /** @internal */
@@ -178,6 +181,12 @@ export class Actor<TLogic extends AnyActorLogic>
           );
         }
         (child as any)._stop();
+      },
+      emit: (emittedEvent) => {
+        for (const handler of this.eventListeners.get(emittedEvent.type) ??
+          []) {
+          handler(emittedEvent);
+        }
       }
     };
 
@@ -397,6 +406,22 @@ export class Actor<TLogic extends AnyActorLogic>
     };
   }
 
+  public on(
+    emittedEventType: string,
+    handler: EmittedEventHandler
+  ): Subscription {
+    const set = this.eventListeners.get(emittedEventType) ?? new Set();
+    set.add(handler);
+    this.eventListeners.set(emittedEventType, set);
+
+    return {
+      unsubscribe: () => {
+        const set = this.eventListeners.get(emittedEventType)!;
+        set?.delete(handler);
+      }
+    };
+  }
+
   /**
    * Starts the Actor from the initial state
    */

packages/core/src/types.ts

@@ -1952,6 +1952,10 @@ export interface ActorRef<
   /** @internal */
   _processingStatus: ProcessingStatus;
   src: string | AnyActorLogic;
+  on: (
+    emittedEventType: string,
+    handler: (emittedEvent: AnyEventObject) => void
+  ) => Subscription;
 }
 
 export type AnyActorRef = ActorRef<any, any>;
@@ -2105,6 +2109,7 @@ export interface ActorScope<
   sessionId: string;
   logger: (...args: any[]) => void;
   defer: (fn: () => void) => void;
+  emit: (event: AnyEventObject) => void;
   system: TSystem;
   stopChild: (child: AnyActorRef) => void;
 }

packages/core/test/eventEmitter.test.ts

@@ -0,0 +1,26 @@
+import { AnyEventObject, createActor, createMachine } from '../src';
+import { emit } from '../src/actions/emit';
+
+describe('event emitter', () => {
+  it('emits events that can be listened to on actorRef.on(…)', async () => {
+    const machine = createMachine({
+      on: {
+        someEvent: {
+          actions: emit({ type: 'emitted', foo: 'bar' })
+        }
+      }
+    });
+
+    const actor = createActor(machine).start();
+    setTimeout(() => {
+      actor.send({
+        type: 'someEvent'
+      });
+    });
+    const event = await new Promise<AnyEventObject>((res) => {
+      actor.on('emitted', res);
+    });
+
+    expect(event.foo).toBe('bar');
+  });
+});