Type Alias: PlayEvent<TPayload>

Documentation / @xmachines/play / PlayEvent

type PlayEvent<TPayload> = object & TPayload;

Defined in: types.ts:69

Generic event type for Play Architecture

PlayEvent represents the minimal event contract for Actor communication: any object with a type string property. Infrastructure forwards events to the Actor, and the Actor’s state machine guards determine validity.

Type Parameter: The generic TPayload allows specifying the shape of additional event fields beyond type. It defaults to Record<string, unknown> for maximum flexibility.

Architectural Context: Implements Passive Infrastructure (INV-04) where infrastructure reflects user actions as events without making decisions. The Actor’s state machine guards determine whether each event is valid from the current state.

Framework Agnostic: This type is intentionally generic and not tied to any specific state machine framework. It matches the common event shape used by XState, Robot, and other state machine libraries.

Common Event Types:

• Domain events: { type: 'auth.login', userId: '123' }
• Custom events: { type: 'form.submit', data: {...} }

Type Declaration

Name	Type	Defined in
type	string	types.ts:70

Type Parameters

Type Parameter	Default type	Description
TPayload extends Record<string, unknown>	Record<string, unknown>	Additional fields beyond type (defaults to Record<string, unknown>)

Examples

Using without type parameter (flexible)

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

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

Using with type parameter (type-safe)

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

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

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

// TypeScript error: missing required field
const invalid: LoginEvent = { type: "auth.login" }; // Error!

See

RFC Play v1