npm package: @statelyai/examine
Description: Examine state
Author: david@stately.ai
Latest version: 0.1.0

# @statelyai/examine

A utility function for examining state in browser environments.

## Installation

```bash
npm install @statelyai/examine
```

## Usage

### Basic Usage

```typescript
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:

```typescript
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

```typescript
// 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

```typescript
// 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