Type Alias: PlayEvent<TPayload>

API / @xmachines/play / PlayEvent

type PlayEvent<TPayload> = object & TPayload;

Defined in: packages/play/src/types.ts:71

The generic event type of the Play Architecture

PlayEvent is the minimal event contract of the Actor communication: it is every object with a type string property. The infrastructure sends each event to the Actor, and the guards of the Actor state machine decide the validity.

The type parameter: the generic TPayload gives the shape of the event fields after type. Its default is Record<string, unknown>, which accepts each shape.

Architectural context: the type implements Passive Infrastructure (INV-04). The infrastructure converts each user action into an event, and it makes no decision. The guards of the Actor state machine decide if each event is valid in the current state.

Framework-agnostic: this type is generic on purpose, and it is bound to no state machine framework. It matches the common event shape of XState, of Robot, and of the other state machine libraries.

The common event types:

• A domain event: { type: 'auth.login', userId: '123' }
• Your own event: { type: 'form.submit', data: {...} }

Type Declaration

Name	Type	Defined in
type	string	packages/play/src/types.ts:72

Type Parameters

Type Parameter	Default type	Description
TPayload extends Record<string, unknown>	Record<string, unknown>	The fields after type. The default is Record<string, unknown>

Examples

The use without the type parameter, which is flexible

import type { PlayEvent } from "@xmachines/play";

// It accepts every event with type: string
const loginEvent: PlayEvent = {
  type: "auth.login",
  userId: "user123",
  timestamp: Date.now(),
};
actor.send(loginEvent);

The use with the type parameter, which is type-safe

import type { PlayEvent } from "@xmachines/play";

// A type-safe event with a known shape
type LoginEvent = PlayEvent<{ userId: string; timestamp: number }>;

const loginEvent: LoginEvent = {
  type: "auth.login",
  userId: "user123",
  timestamp: Date.now(),
};

// A TypeScript error: a necessary field is absent
const invalid: LoginEvent = { type: "auth.login" }; // Error!

See

Play RFC