@statelyai/examine

A utility function for examining state in browser environments.

Installation

npm install @statelyai/examine

Usage

Basic Usage

import { examine } from "@statelyai/examine"

const state = { count: 0, user: "John" }
const examinedState = examine("myActor", state)

Complex Data Types

The examine function now safely serializes complex JavaScript data types including:

import { examine } from "@statelyai/examine"

// Works with Dates
const stateWithDate = {
  timestamp: new Date(),
  user: "John"
}
examine("timeActor", stateWithDate)

// Works with Maps
const stateWithMap = {
  userMap: new Map([
    ["user1", { name: "Alice", age: 30 }],
    ["user2", { name: "Bob", age: 25 }]
  ])
}
examine("mapActor", stateWithMap)

// Works with Sets
const stateWithSet = {
  tags: new Set(["admin", "user", "moderator"]),
  permissions: new Set([1, 2, 3])
}
examine("setActor", stateWithSet)

// Works with BigInt
const stateWithBigInt = {
  largeNumber: BigInt("123456789012345678901234567890"),
  count: 42
}
examine("bigintActor", stateWithBigInt)

// Works with circular references
const circularState: any = { name: "parent" }
circularState.self = circularState
examine("circularActor", circularState)

Event Tracking

// Track events between actors
examine.event("USER_LOGIN", 
  { userId: "123", timestamp: new Date() },
  { source: "authService", target: "userManager" }
)

// Complex event data is also serialized safely
examine.event("DATA_SYNC", 
  {
    syncMap: new Map([["key1", "value1"]]),
    metadata: { date: new Date(), size: BigInt(1000) }
  },
  { source: "dataService", target: "syncManager" }
)

Configuration

// Configure serialization behavior
examine.configure({
  serialize: true, // Enable/disable serialization (default: true)
  examinerKey: "customExaminer" // Custom examiner function name
})

// Disable serialization for performance-critical scenarios
examine.configure({ serialize: false })

// Use custom examiner function
examine.configure({ examinerKey: "myCustomDebugger" })

API

examine<T>(actorName: string, state: T): T

Examines the given state and returns it unchanged. The function serializes complex data types for safe transport and calls a global examine receiver function if available.

Parameters:

• actorName (string): The name of the actor/component being examined
• state (T): The state object to examine (supports any JavaScript data type)

Returns: The same state object that was passed in

examine.event(type: string, data?: any, details?: object): void

Tracks events sent between actors.

Parameters:

• type (string): The event type identifier
• data (any): Optional event data (supports any JavaScript data type)
• details (object): Optional event details
  • source (string): Source actor name
  • target (string): Target actor name
  • tags (string[]): Event tags

examine.configure(options: object): void

Configures the examine function behavior.

Parameters:

• options (object): Configuration options
  • serialize (boolean): Enable/disable SuperJSON serialization (default: true)
  • examinerKey (string): Custom global examiner function name (default: "statelyai__examine")

License

MIT