prompt.txt

# ActorCore Development Guide

This guide contains essential information for working with the ActorCore project.

## Project Naming and Terminology

- Use `ActorCore` when referring to the project in documentation and plain English
- Use `actor-core` (kebab-case) when referring to the project in code, package names, and imports

### Core Concepts

- **Actor**: A stateful, long-lived entity that processes messages and maintains state
- **Manager**: Component responsible for creating, routing, and managing actor instances
- **Action**: Method for an actor to expose callable functions to clients
- **Event**: Asynchronous message sent from an actor to connected clients
- **Alarm**: Scheduled callback that triggers at a specific time

## Build Commands

- **Type Check:** `yarn check-types` - Verify TypeScript types
- **Check specific package:** `yarn check-types -F actor-core` - Check only specified package
- **Build:** `yarn build` - Production build using Turbopack
- **Build specific package:** `yarn build -F actor-core` - Build only specified package
- **Format:** `yarn fmt` - Format code with Biome

## Driver Implementations

Available driver implementations:

- **Memory**: In-memory implementation for development and testing
- **Redis**: Production-ready implementation using Redis for persistence and pub/sub
- **Cloudflare Workers**: Uses Durable Objects for actor state persistence
- **Rivet**: Fully-managed cloud platform with built-in scaling and monitoring

## Platform Support

ActorCore supports multiple runtime environments:

- **NodeJS**: Standard Node.js server environment
- **Cloudflare Workers**: Edge computing environment
- **Bun**: Fast JavaScript runtime alternative to Node.js
- **Rivet**: Cloud platform with built-in scaling and management

## Package Import Resolution

When importing from workspace packages, always check the package's `package.json` file under the `exports` field to determine the correct import paths:

1. Locate the package's `package.json` file
2. Find the `exports` object which maps subpath patterns to their file locations
3. Use these defined subpaths in your imports rather than direct file paths

## Code Style Guidelines

- **Formatting:** Uses Biome for consistent formatting
- **Imports:** Organized imports enforced, unused imports warned
- **TypeScript:** Strict mode enabled, target ESNext
- **Naming:** 
  - camelCase for variables, functions
  - PascalCase for classes, interfaces, types
  - UPPER_CASE for constants
- **Error Handling:** 
  - Use `UserError` for client-safe errors
  - Use `InternalError` for internal errors

## Project Structure

- Monorepo with Yarn workspaces and Turborepo
- Core code in `packages/actor-core/`
- Platform implementations in `packages/platforms/`
- Driver implementations in `packages/drivers/`

## State Management

- Each actor owns and manages its own isolated state via `c.state`
- State is automatically persisted between action calls
- State is initialized via `createState` function or `state` constant
- Only JSON-serializable types can be stored in state
- Use `onStateChange` to react to state changes

## Authentication and Security

- Authentication is handled through the `onBeforeConnect` lifecycle hook
- Connection state is accessed with `c.conn.state`
- Access control should be implemented for each action
- Throwing an error in `onBeforeConnect` will abort the connection
- Use `UserError` for safe error messages to clients
- Use data validation libraries like zod for input validation

## Actions and Events

- **Actions**: Used for clients to call actor functions
- **Events**: For actors to publish updates to clients
- Actions are defined in the `actions` object of the actor configuration
- Helper functions outside the `actions` object are not callable by clients
- Broadcasting is done via `c.broadcast(name, data)`
- Specific client messaging uses `conn.send(name, data)`
- Clients subscribe to events with `actor.on(eventName, callback)`

## Lifecycle Hooks

- `createState()`: Function that returns initial actor state
- `onStart(c)`: Called any time actor is started (after restart/upgrade)
- `onStateChange(c, newState)`: Called when actor state changes
- `onBeforeConnect(c)`: Called when new client connects
- `onConnect(c)`: Executed after client connection succeeds
- `onDisconnect(c)`: Called when client disconnects

## Actor Management

- App is configured with actors using `setup({ actors: { actorName }})` followed by `serve(app)`
- Actors are accessed by client using `client.actorName.get()`
- Actors can pass an ID parameter or object with `client.actorName.get(id)` or `client.actorName.get({key: value})`
- Actors can be shut down with `c.shutdown()` from within the actor

## Scaling and Architecture Guidelines

- Each actor should have a single responsibility
- Keep state minimal and relevant to the actor's core function
- Use separate actors for different entity types (users, rooms, documents)
- Avoid too many cross-actor communications
- Use appropriate topology based on your scaling needs

## Scheduling

- Schedule future events with `c.after(duration, fn, ...args)`
- Schedule events for specific time with `c.at(timestamp, fn, ...args)`
- Scheduled events persist across actor restarts

## CORS Configuration

- Configure CORS to allow cross-origin requests in production
- Set allowed origins, methods, headers, and credentials
- For development, use `cors: { origin: "http://localhost:3000" }`

## Development Best Practices

- Prefer functional actor pattern with `actor({ ... })` syntax
- Use zod for runtime type validation
- Use `assertUnreachable(x: never)` for exhaustive type checking
- Add proper JSDoc comments for public APIs
- Run `yarn check-types` regularly during development
- Use `tsx` CLI to execute TypeScript scripts directly