fix: update some internal types & docstrings

some types were renamed but these are unlikely to have been used directly.

src/types.ts

@@ -10,7 +10,7 @@ import type * as xs from 'xstate';
  */
 export type ActorEventTuple<
   Actor extends AnyActor,
-  EventTypes extends ActorEventTypeTuple<Actor>,
+  EventTypes extends Readonly<ActorEventTypeTuple<Actor>>,
 > = {
   -readonly [K in keyof EventTypes]: EventFromEventType<Actor, EventTypes[K]>;
 };
@@ -26,38 +26,28 @@ export type ActorEventType<Actor extends AnyActor> =
 /**
  * A tuple of event types (event names) Event by an actor
  */
-export type ActorEventTypeTuple<Actor extends AnyActor> = [
-  ActorEventType<Actor>,
-  ...ActorEventType<Actor>[],
-];
+export type ActorEventTypeTuple<Actor extends AnyActor> = ReadableArray<
+  [ActorEventType<Actor>, ...ActorEventType<Actor>[]]
+>;
 
 export type AnyActor = xs.AnyActor;
 
-export type AnyListenableActor = xs.Actor<ListenableLogic>;
+export type AnyListenableActor = xs.Actor<AnyEventReceiverLogic>;
 
-export type AnyOutputtableActor = xs.Actor<OutputtableLogic>;
+export type AnyOutputtableActor = xs.Actor<AnyTerminalLogic>;
 
-export type AnySnapshottableActor = xs.Actor<SnapshottableLogic>;
+export type AnySnapshottableActor = xs.Actor<AnySnapshotEmitterLogic>;
 
 export type AnyStateMachineActor = xs.Actor<xs.AnyStateMachine>;
 
 export type AuditionEventOptions = {
   otherActorId?: RegExp | string;
 } & AuditionOptions;
 
-/**
- * @internal
- */
-export type InternalAuditionEventOptions = {
-  otherActorId?: RegExp | string;
-} & InternalAuditionOptions;
-
 /**
  * Options for all `*With()` functions
- *
- * @internal
  */
-export type InternalAuditionOptions = {
+export type AuditionOptions = {
   /**
    * Default inspector to use
    *
@@ -73,77 +63,114 @@ export type InternalAuditionOptions = {
   logger?: LoggerFn;
 
   /**
-   * If `true`, the actor will be stopped after a successful operation
-   */
-  stop: boolean;
-
-  /**
-   * Default timeout for those methods which accept a timeout.
+   * Default timeout (in milliseconds) for those methods which accept a timeout.
+   *
+   * @defaultValue 1000
    */
   timeout?: number;
 };
 
 /**
- * Options for all `*With()` functions
+ * Given a XState Actor and an {@link EventObject.type event type} (the `type`
+ * field of an `EventObject`), returns the type of the corresponding event.
+ *
+ * Does not apply to "emitted" events.
+ *
+ * @template Actor The State Machine Actor
+ * @template EventType The event type (the `type` field of the `EventObject`)
  */
-export type AuditionOptions = {
-  /**
-   * Default inspector to use
-   *
-   * @param An {@link xs.InspectionEvent InspectionEvent}
-   */
-  inspector?: InspectorFn | xs.Observer<xs.InspectionEvent>;
+export type EventFromEventType<
+  Actor extends AnyActor,
+  EventType extends ActorEventType<Actor>,
+> = xs.ExtractEvent<xs.EventFromLogic<Actor['logic']>, EventType>;
 
-  /**
-   * Default logger to use
-   *
-   * @param Anything To be logged
-   */
-  logger?: LoggerFn;
+/**
+ * An inspector function or XState `Observer` for an Actor
+ */
+export type InspectorFn = NonNullable<xs.ActorOptions<any>['inspect']>;
 
+/**
+ * Internal options for functions accepting {@link AuditionEventOptions}.
+ *
+ * @internal
+ */
+export type InternalAuditionEventOptions = AuditionEventOptions &
+  InternalAuditionOptions;
+
+/**
+ * Internal options for all `*With()` functions
+ *
+ * @internal
+ */
+export type InternalAuditionOptions = {
   /**
-   * Default timeout for those methods which accept a timeout.
+   * If `true`, the actor will be stopped after a successful operation
    */
-  timeout?: number;
-};
+  stop: boolean;
+} & AuditionOptions;
 
 /**
- * Lookup for event/Event-event based on type
+ * A logger function for an XState Actor
  */
-export type EventFromEventType<
-  Actor extends AnyActor,
-  K extends ActorEventType<Actor>,
-> = xs.ExtractEvent<xs.EventFromLogic<Actor['logic']>, K>;
+export type LoggerFn = NonNullable<xs.ActorOptions<any>['logger']>;
 
 /**
- * An inspector function for an actor
+ * An array or tuple which is either readonly or mutable
  */
-export type InspectorFn = (evt: xs.InspectionEvent) => void;
+export type ReadableArray<T extends readonly any[]> = Readonly<T> | T;
 
 /**
  * Any actor logic that can receive events
+ *
+ * @see {@link https://stately.ai/docs/actors#actor-logic-capabilities}
+ */
+export type AnyEventReceiverLogic =
+  | AnyStateMachineLogic
+  | SomeTransitionLogic
+  | xs.ActorLogic<xs.CallbackSnapshot<any>, any, any, any, any>;
+
+/**
+ * Any actor logic that can send events
+ *
+ * @see {@link https://stately.ai/docs/actors#actor-logic-capabilities}
+ */
+export type AnyEventSenderLogic = xs.AnyActorLogic;
+
+/**
+ * Any actor logic which can theoretically emit snapshots
+ *
+ * @see {@link https://stately.ai/docs/actors#actor-logic-capabilities}
  */
-export type ListenableLogic =
-  | xs.ActorLogic<xs.AnyMachineSnapshot, any, any, any, any>
-  | xs.ActorLogic<xs.CallbackSnapshot<any>, any, any, any, any>
-  | xs.ActorLogic<xs.TransitionSnapshot<any>, any, any, any, any>;
+export type AnySnapshotEmitterLogic =
+  | AnyTerminalLogic
+  | SomeTransitionLogic
+  | xs.ActorLogic<xs.ObservableSnapshot<any, any>, any, any, any, any>;
 
 /**
- * A logger function for an actor
+ * Any state machine logic
+ *
+ * @see {@link https://stately.ai/docs/actors#actor-logic-capabilities}
  */
-export type LoggerFn = (...args: any[]) => void;
+export type AnyStateMachineLogic = xs.AnyStateMachine;
 
 /**
- * Any actor logic which can theoretically produce output upon completion
+ * Any actor logic which can theoretically terminate and/or produce output.
+ *
+ * @see {@link https://stately.ai/docs/actors#actor-logic-capabilities}
  */
-export type OutputtableLogic =
-  | xs.ActorLogic<xs.AnyMachineSnapshot, any, any, any, any>
+export type AnyTerminalLogic =
+  | AnyStateMachineLogic
   | xs.ActorLogic<xs.PromiseSnapshot<any, any>, any, any, any, any>;
 
 /**
- * Any actor logic which can theoretically emit snapshots
+ * Any Transition Actor logic
+ *
+ * @see {@link https://stately.ai/docs/actors#fromtransition}
  */
-export type SnapshottableLogic =
-  | OutputtableLogic
-  | xs.ActorLogic<xs.ObservableSnapshot<any, any>, any, any, any, any>
-  | xs.ActorLogic<xs.TransitionSnapshot<any>, any, any, any, any>;
+export type SomeTransitionLogic = xs.ActorLogic<
+  xs.TransitionSnapshot<any>,
+  any,
+  any,
+  any,
+  any
+>;

src/until-emitted.ts

@@ -8,8 +8,12 @@ import {
   type AnyStateMachineActor,
   type AuditionOptions,
   type InternalAuditionOptions,
+  type ReadableArray,
 } from './types.js';
 
+/**
+ * A tuple of events emitted by an actor matching `EmittedTypes`.
+ */
 export type ActorEmittedTuple<
   Actor extends AnyStateMachineActor,
   EmittedTypes extends Readonly<ActorEmittedTypeTuple<Actor>>,
@@ -20,13 +24,11 @@ export type ActorEmittedTuple<
   >;
 };
 
-type ActorEmittedType<Actor extends AnyStateMachineActor> = xs.EmittedFrom<
-  Actor['logic']
->['type'];
+export type ActorEmittedType<Actor extends AnyStateMachineActor> =
+  xs.EmittedFrom<Actor['logic']>['type'];
 
 export type ActorEmittedTypeTuple<Actor extends AnyStateMachineActor> =
-  | [ActorEmittedType<Actor>, ...ActorEmittedType<Actor>[]]
-  | readonly [ActorEmittedType<Actor>, ...ActorEmittedType<Actor>[]];
+  ReadableArray<[ActorEmittedType<Actor>, ...ActorEmittedType<Actor>[]]>;
 
 export type CurryEmitted = (() => CurryEmitted) &
   (<
@@ -76,10 +78,19 @@ export type CurryEmittedWithP2<Actor extends AnyStateMachineActor> =
       emittedTypes: EmittedTypes,
     ) => Promise<ActorEmittedTuple<Actor, EmittedTypes>>);
 
-type EmittedFromEmittedType<
+/**
+ * Given a State Machine Actor and a _emitted_
+ * {@link EventObject.type event type} (the `type` field of an `EventObject`),
+ * returns the type of the corresponding event.
+ *
+ * @template Actor The State Machine Actor
+ * @template EventType The _emitted_ event type (the `type` field of the
+ *   `EventObject`)
+ */
+export type EmittedFromEmittedType<
   Actor extends AnyStateMachineActor,
-  K extends ActorEmittedType<Actor>,
-> = xs.ExtractEvent<xs.EmittedFrom<Actor['logic']>, K>;
+  EventType extends ActorEmittedType<Actor>,
+> = xs.ExtractEvent<xs.EmittedFrom<Actor['logic']>, EventType>;
 
 export function runUntilEmitted<
   Actor extends AnyStateMachineActor,
@@ -132,7 +143,7 @@ export function runUntilEmittedWith<
 /**
  * This function just returns itself.
  *
- * @returns {@link CurryEmitted This function}
+ * @returns This function
  */
 export function waitForEmitted(): CurryEmitted;
 

src/until-event-received.ts

@@ -75,19 +75,16 @@ export type CurryEventReceivedWithP3<
 > = Promise<ActorEventTuple<Actor, EventReceivedTypes>>;
 
 /**
- * Runs an actor until it sends one or more events (in order).
+ * Runs an XState `Actor` until it receives one or more events (in order).
  *
- * @param actor An existing {@link Actor}
- * @param events One or more _event names_ (the `type` field) to wait for (in
- *   order)
- * @returns The matching events (assuming they all occurred in order)
+ * @template Actor The type of `actor`
+ * @template EventReceivedTypes The type of `eventTypes`
+ * @param actor An XState `Actor` that can receive events
+ * @param eventTypes One or more _event names_ (the `type` field) to wait for
+ *   (in order)
+ * @returns A `Promise` fulfilling with the matching events (assuming they all
+ *   occurred in order)
  */
-export function runUntilEventReceived(): CurryEventReceived;
-
-export function runUntilEventReceived<Actor extends AnyListenableActor>(
-  actor: Actor,
-): CurryEventReceivedP1<Actor>;
-
 export function runUntilEventReceived<
   Actor extends AnyListenableActor,
   const EventReceivedTypes extends ActorEventTypeTuple<Actor>,
@@ -96,6 +93,26 @@ export function runUntilEventReceived<
   eventTypes: EventReceivedTypes,
 ): CurryEventReceivedP2<Actor, EventReceivedTypes>;
 
+/**
+ * Returns a function which runs an actor until it sends one or more events (in
+ * order).
+ *
+ * @template Actor The type of `actor`
+ * @param actor An XState `Actor` that can receive events
+ * @returns A function which runs an actor until it sends one or more events (in
+ *   order)
+ */
+export function runUntilEventReceived<Actor extends AnyListenableActor>(
+  actor: Actor,
+): CurryEventReceivedP1<Actor>;
+
+/**
+ * Returns itself.
+ *
+ * @returns A function which returns itself
+ */
+export function runUntilEventReceived(): CurryEventReceived;
+
 export function runUntilEventReceived<
   Actor extends AnyListenableActor,
   const EventReceivedTypes extends ActorEventTypeTuple<Actor>,
@@ -152,26 +169,57 @@ export function waitForEventReceived<
 }
 
 /**
- * Runs an actor until it sends one or more events (in order), with options
- * including a target actor ID.
+ * Returns itself.
  *
- * @param actor An existing {@link Actor}
- * @param events One or more _event names_ (the `type` field) to wait for (in
- *   order)
- * @param options Options
- * @returns The matching events (assuming they all occurred in order)
+ * @returns A function which returns itself
  */
 export function waitForEventReceivedWith(): CurryEventReceivedWith;
 
+/**
+ * Returns a function which, if provided {@link AuditionEventOptions options} and
+ * {@link ActorEventTypeTuple event types}, will waits until an XState `Actor`
+ * receives one or more events (in order).
+ *
+ * @template Actor The type of `actor`
+ * @param actor An XState `Actor` that can receive events
+ * @returns Returns a function which, if provided
+ *   {@link AuditionEventOptions options} and
+ *   {@link ActorEventTypeTuple event types}, will waits until an XState `Actor`
+ *   receives one or more events (in order).
+ */
 export function waitForEventReceivedWith<Actor extends AnyListenableActor>(
   actor: Actor,
 ): CurryEventReceivedWithP1<Actor>;
 
+/**
+ * Returns a function which waits until an XState `Actor` receives one or more
+ * events (in order).
+ *
+ * @template Actor The type of `actor`
+ * @param actor An XState `Actor` that can receive events
+ * @param options Options, including `otherActorId` which will filter on the
+ *   sender
+ * @returns A `Promise` fulfilling with the matching events (assuming they all
+ *   occurred in order)
+ */
 export function waitForEventReceivedWith<Actor extends AnyListenableActor>(
   actor: Actor,
   options: AuditionEventOptions,
 ): CurryEventReceivedWithP2<Actor>;
 
+/**
+ * Wait until an XState `Actor` receives one or more events (in order).
+ *
+ * @template Actor The type of `actor`
+ * @template EventReceivedTypes The type of `eventTypes`
+ * @param actor An XState `Actor` that can receive events
+ * @param options Options, including `otherActorId` which will filter on the
+ *   sender
+ * @param eventTypes One or more _event names_ (the `type` field) to wait for
+ *   (in order)
+ * @returns A `Promise` fulfilling with the matching events (assuming they all
+ *   occurred in order)
+ */
 export function waitForEventReceivedWith<
   Actor extends AnyListenableActor,
   const EventReceivedTypes extends ActorEventTypeTuple<Actor>,