# @signe/room

> PartyKit room primitives with synchronized state, sessions, guards, and HTTP handlers.

Latest version **3.2.1** (published 2026-09-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @signe/room
pnpm add @signe/room
yarn add @signe/room
bun add @signe/room
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.2.1 |
| Published | 2026-09-26 |
| First published | 2024-06-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 853.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Samuel Ronce |
| Maintainers | webcreative5 |
| Keywords | partykit, realtime, websocket, cloudflare, typescript |

## Links

- npm: https://www.npmjs.com/package/@signe/room
- npm.io page: https://npm.io/package/@signe/room

## Dependencies (4)

- [zod](https://npm.io/package/zod.md) ^3.23.8
- [dset](https://npm.io/package/dset.md) ^3.1.3
- [@signe/sync](https://npm.io/package/@signe/sync.md) 3.1.1
- [partysocket](https://npm.io/package/partysocket.md) ^1.0.1

## Recent versions

- 3.2.1 (latest) — 2026-09-26
- 3.2.0 — 2026-08-06
- 3.1.1 — 2026-07-28
- 3.1.0 — 2026-06-15
- 3.0.1 — 2026-05-13
- 3.0.0 — 2026-05-13
- 2.10.0 — 2026-05-08
- 2.9.4 — 2026-05-07
- 2.9.3 — 2026-05-07
- 2.9.2 — 2026-05-07
- 2.9.0 — 2026-04-03
- 2.8.3 — 2026-01-14
- 2.8.2 — 2026-01-09
- 2.8.1 — 2026-01-08
- 2.8.0 — 2026-01-08
- … 38 more at https://npm.io/package/@signe/room/versions

## README

# @signe/room

A real-time multiplayer room system for Signe applications, providing seamless state synchronization and user management.

## Installation

```bash
npm install @signe/room @signe/reactive @signe/sync
```

## Features

- 🔄 Automatic state synchronization across clients
- 👥 Built-in user management with customizable player classes
- 🎮 Action-based message handling with type safety
- 🌐 HTTP request routing with path parameters
- 🔐 Flexible authentication and authorization system
- 🛡️ Guard system for room and action-level security
- 🎯 Full TypeScript support
- 🔌 WebSocket-based real-time communication
- 💾 Automatic state persistence
- 🚀 Optimized for performance with throttling support

## Basic Usage

Here's a simple example of a multiplayer game room:

```ts
import { signal } from "@signe/reactive";
import { Room, Server, Action } from "@signe/room";
import { id, sync, users } from "@signe/sync";

// Define a Player class
class Player {
  @id() id: string;
  @sync() x = signal(0);
  @sync() y = signal(0);
  @sync() score = signal(0);
}

// Create your room
@Room({
  path: "game",
})
class GameRoom {
  @users(Player) players = signal({});
  @sync() gameState = signal("waiting");

  @Action("move")
  move(player: Player, position: { x: number, y: number }) {
    player.x.set(position.x);
    player.y.set(position.y);
  }
}

// Create your server
export default class GameServer extends Server {
  rooms = [GameRoom];
}
```

## Action 

An action is a function that is called when a client sends a message to the server.

Function have to be decorated with the `@Action` decorator and  have 3 parameters:

- The first parameter is the player instance
- The second parameter is the value of the action
- The third parameter is the Party.Connection instance

### Unhandled actions

If you want to catch any valid WebSocket message whose `action` is not registered
with `@Action(...)`, you can use `@UnhandledAction()`.

The fallback handler receives:

- The first parameter is the player instance
- The second parameter is the full message object: `{ action, value }`
- The third parameter is the `Party.Connection` instance

```ts
import { Action, Guard, Room, UnhandledAction } from "@signe/room";

function isAuthenticated(conn: Party.Connection, value: any, room: Party.Room) {
  return !!conn.state?.publicId;
}

@Room({
  path: "game",
})
class GameRoom {
  @Action("move")
  move(player: any, value: { x: number; y: number }) {
    player.x.set(value.x);
    player.y.set(value.y);
  }

  @UnhandledAction()
  @Guard([isAuthenticated])
  onUnhandledAction(
    player: any,
    message: { action: string; value: unknown },
    conn: Party.Connection
  ) {
    console.warn("Unhandled action", message.action, message.value, {
      connectionId: conn.id,
      sessionId: conn.sessionId,
    });
  }
}
```

Notes:

- `@UnhandledAction()` is only called if the incoming message matches the expected
  WebSocket shape `{ action, value }`
- If a matching `@Action("...")` exists, it always has priority over
  `@UnhandledAction()`
- You can combine `@UnhandledAction()` with `@Guard(...)`

## HTTP Request Handling

The `@Request` decorator allows you to handle HTTP requests with specific routes and methods:

```ts
import { z } from "zod";
import { Room, Request, RequestGuard, ServerResponse } from "@signe/room";

@Room({
  path: "api"
})
class ApiRoom {
  @sync() gameState = signal("waiting");
  @users(Player) players = signal({});
  @sync() scores = signal([]);

  // Handle GET requests
  @Request({ path: "/status" })
  getStatus(req: Party.Request) {
    return {
      status: "online",
      players: Object.keys(this.players()).length,
      gameState: this.gameState(),
    };
  }

  // Handle requests with path parameters
  @Request({ path: "/players/:id" })
  getPlayer(req: Party.Request, res: ServerResponse) {
    const player = this.players()[req.params.id];
    if (!player) {
      return res.notFound("Player not found");
    }
    return player;
  }

  // Handle POST requests with body validation
  @Request(
    { path: "/scores", method: "POST" },
    z.object({ 
      playerId: z.string(),
      score: z.number().min(0)
    })
  )
  @Guard([isAuthenticated])
  submitScore(req: Party.Request, res: ServerResponse) {
    this.scores.update(scores => [...scores, req.data]);
    return res.success({ success: true });
  }
}
```

Request handler methods receive these parameters:
1. `req`: The original Party.Request object
2. `body`: The validated request body (if validation schema was provided)
3. `params`: An object containing any path parameters
4. `room`: The Party.Room instance

You can return:
- A Response object for complete control
- An object that will be serialized as JSON
- A string that will be returned as text/plain

## Advanced Features

### User Sessions and Reconnects

Rooms use the WebSocket `id` query parameter as the private session id
(`privateId`). Each active WebSocket still receives its own unique
`conn.id`; the stable session id is available as `conn.sessionId`. The
corresponding `publicId` is the key used in `@users()` collections. Query
parameters such as a display name are user data only; they do not identify the
session.

Identifier summary:

| Identifier | Meaning | Stability |
| --- | --- | --- |
| `conn.id` | Unique WebSocket connection id | New for every active socket |
| `conn.sessionId` | Private session id from the WebSocket `id` query parameter | Stable across reconnects and shared by tabs using the same `id` |
| `publicId` | User id stored in `@users()` collections | Stable for the restored session |

Use `conn.id` when you need to address or exclude one physical WebSocket, for
example `room.broadcast(message, [conn.id])`. Use `conn.sessionId` when you
need to read, restore, transfer, or log the private user session.

Pass a stable `id` when connecting if a browser refresh or reconnect should
restore the same user. If `id` is omitted, each connection creates a new
session and therefore a new user entry. To implement logout, remove or rotate
the stored id before reconnecting.

Multiple active WebSockets can use the same session id. They share the same
`publicId`, receive broadcasts independently, and the user is marked offline
only after the last connection for that session closes.

```ts
import { connectionRoom } from "@signe/sync/client";

const sessionId =
  localStorage.getItem("room-session-id") ?? crypto.randomUUID();

localStorage.setItem("room-session-id", sessionId);

await connectionRoom({
  host: window.location.origin,
  room: "your-room-name",
  party: "main",
  id: sessionId,
}, roomInstance);
```

### Session Transfer

You can transfer a user's session from one room to another using `$sessionTransfer`.
This is an advanced use of the same session mechanism and preserves the same
private session id (`privateId`) across rooms.

Server-side (inside a room or action):

```ts
@Action("transfer")
async transfer(player: Player, data: { targetRoomId: string }, conn: Party.Connection) {
  const transferToken = await this.$sessionTransfer(conn, data.targetRoomId);
  return { transferToken };
}
```

Client-side:
- Connect to the target room with the same session id (`privateId`).
- You can pass it as `id` in `connectionRoom` options from `@signe/sync/client`.
- The target room restores the session and user data.

Example (client):
```ts
import { connectionRoom } from "@signe/sync/client";

await connectionRoom(
  {
    host: "https://your-host",
    room: "targetRoomId",
    id: "private-session-id",
  },
  roomInstance
);
```

Optional: hydrate transferred snapshots before loading

If your user snapshot contains ids for complex instances (e.g. inventory items),
implement `onSessionRestore` on the room to resolve ids into instances before `load`.

```ts
class GameRoom {
  async onSessionRestore({ userSnapshot }) {
    if (Array.isArray(userSnapshot.items)) {
      const items = await this.itemRegistry.resolveMany(userSnapshot.items);
      return { ...userSnapshot, items };
    }
    return userSnapshot;
  }
}
```

### Snapshot Hydration (Ids -> Instances)

When a snapshot only contains ids for complex objects, you need to resolve them
before calling `load`. This is useful even outside session transfer.

```ts
const snapshot = createStatesSnapshotDeep(user);

// Resolve ids to instances
const items = await itemRegistry.resolveMany(snapshot.items);

// Hydrate and load
const hydrated = { ...snapshot, items };
load(user, hydrated, true);
```

### Storage Restore Hydration

Room storage is loaded automatically when a room starts. If persisted snapshots
contain complex values that must become runtime instances again, implement
`onStorageRestore` or `onUserStorageRestore` on the room.

Use `onStorageRestore` to transform the full room snapshot before it is loaded:

```ts
class GameRoom {
  async onStorageRestore({ snapshot, room, legacy }) {
    return {
      ...snapshot,
      status: snapshot.status ?? "waiting",
    };
  }
}
```

Use `onUserStorageRestore` to transform each persisted entry in the room's
`@users()` collection. The hook receives a fresh user helper instance so you can
reuse instance methods to hydrate nested data before the snapshot is loaded.

```ts
class GameRoom {
  @users(Player) players = signal({});

  async onUserStorageRestore({ userSnapshot, user, publicId }) {
    return {
      ...userSnapshot,
      items: await user.resolveItems(userSnapshot.items),
      skills: await user.resolveSkills(userSnapshot.skills),
    };
  }
}
```

Returning `undefined` keeps the original snapshot unchanged. The `legacy` flag is
`true` only when loading data from the pre-`state:` storage layout during
automatic migration.

### Room Configuration

The `@Room` decorator accepts various configuration options:

```ts
@Room({
  path: "game-{id}",     // Dynamic path with parameters
  maxUsers: 4,           // Limit number of users
  throttleStorage: 1000, // Throttle storage updates (ms)
  throttleSync: 100,     // Throttle sync updates (ms)
  hibernate: false,      // Enable/disable hibernation
  guards: [isAuthenticated], // Room-level guards
})
```

### Authentication & Authorization

You can implement authentication and authorization using guards:

```ts
// Authentication guard
function isAuthenticated(conn: Connection, ctx: ConnectionContext) {
  const token = ctx.request.headers.get("authorization");
  return validateToken(token); // Returns boolean or Promise<boolean>
}

// Role-based guard
function isAdmin(conn: Connection, value: any) {
  return conn.state.role === "admin";
}

@Room({
  path: "admin-panel",
  guards: [isAuthenticated], // Applied to all connections and messages
})
class AdminRoom {
  @Action("deleteUser")
  @Guard([isAdmin]) // Applied only to this action
  async deleteUser(admin: Player, userId: string) {
    // Only authenticated admins can execute this
  }
  
  @Request({ path: "/admin/users", method: "DELETE" })
  @Guard([isAdmin]) // Applied only to this request handler
  async deleteUserViaHttp(req: Party.Request) {
    // Only authenticated admins can access this endpoint
  }
}
```

### Action Validation with Zod

You can validate action input data using Zod schemas:

```ts
import { z } from "zod";

class GameRoom {
  @Action("move", z.object({
    x: z.number().min(0).max(1000),
    y: z.number().min(0).max(1000)
  }))
  move(player: Player, position: { x: number, y: number }) {
    player.x.set(position.x);
    player.y.set(position.y);
  }

  @Action("setName", z.object({
    name: z.string().min(3).max(20)
  }))
  setName(player: Player, data: { name: string }) {
    player.name.set(data.name);
  }
}
```

Actions with invalid data will be automatically rejected if they don't match the validation schema.

### State Management

The room system provides several ways to manage state:

```ts
class GameRoom {
  // Synchronized signals
  @sync() score = signal(0);
  @sync() gameState = signal<"waiting" | "playing" | "ended">("waiting");
  
  // User management
  @users(Player) players = signal({});
  
  // Complex state
  @sync() 
  gameConfig = signal({
    maxPlayers: 4,
    timeLimit: 300,
    mapSize: { width: 1000, height: 1000 }
  });

  // Methods to update state
  @Action("updateConfig")
  updateConfig(player: Player, config: Partial<GameConfig>) {
    if (player.isHost) {
      this.gameConfig.update(current => ({
        ...current,
        ...config
      }));
    }
  }
}
```

### Manual Synchronization

By default, state changes are automatically synchronized to all clients. However, you can disable automatic synchronization and manually control when to broadcast changes using the `autoSync` option and the `$applySync` method.

This is useful when you want to:
- Batch multiple state changes before broadcasting
- Control synchronization timing for performance optimization
- Implement custom synchronization logic

```ts
@Room({
  path: "game"
})
class GameRoom {
  autoSync = false; // Disable automatic synchronization
  
  @sync() count = signal(0);
  @sync() score = signal(0);
  @sync() level = signal(1);

  @Action("updateGameState")
  updateGameState(player: Player, data: { count: number, score: number, level: number }) {
    // Make multiple changes without triggering sync
    this.count.set(data.count);
    this.score.set(data.score);
    this.level.set(data.level);
    
    // Manually trigger synchronization when ready
    this.$applySync();
  }

  @Action("batchUpdate")
  batchUpdate(player: Player, updates: any[]) {
    // Apply multiple updates
    updates.forEach(update => {
      // ... apply updates
    });
    
    // Sync all changes at once
    this.$applySync();
  }
}
```

You can also toggle `autoSync` at runtime:

```ts
class GameRoom {
  @sync() count = signal(0);

  @Action("startBatchMode")
  startBatchMode() {
    this.$autoSync = false; // Disable auto sync
  }

  @Action("endBatchMode")
  endBatchMode() {
    this.$applySync(); // Sync pending changes
    this.$autoSync = true; // Re-enable auto sync
  }
}
```

**Instance Properties:**
- `$autoSync` (boolean): Controls whether synchronization happens automatically (default: `true`)
- `$pendingSync` (Map): Stores pending synchronization changes when `autoSync` is disabled
- `$applySync()` (method): Manually broadcasts all pending changes to all clients

**Note:** When `autoSync` is disabled, changes are stored in `$pendingSync` until you call `$applySync()`. If you call `$applySync()` with no pending changes, it will broadcast the current state from `$memoryAll`, which is useful for forcing a full state synchronization.

### Connecting to World Service

The World Service provides optimal room and shard assignment for distributed applications. It handles load balancing and allows clients to connect to the most appropriate server.

Use this setup when one logical room may need to accept clients through one or more shard parties. A `WorldRoom` keeps the room and shard registry, while each `Shard` proxies client WebSocket and HTTP traffic to the main room server.

#### Environment Variables

To use the Signe room system, you need to configure two essential environment variables:

```env
# Required for JWT authentication
AUTH_JWT_SECRET=a-string-secret-at-least-256-bits-long

# Required for secure communication between shards
SHARD_SECRET=your_shard_secret
```

These secrets should be strong, unique values and kept secure. `SHARD_SECRET` is used for shard-to-world stats updates and shard-to-main-server traffic. A request or WebSocket connection that claims to come from a shard must include this secret.

#### Server Configuration

To use the World service, you need to:

1. Add `WorldRoom` to your server:

```ts
import { Server, WorldRoom } from '@signe/room';

export default class MainServer extends Server {
  rooms = [
    GameRoom,
    WorldRoom // Add WorldRoom to enable World service
  ]
}
```

2. Add `Shard` to your server in `party/shard.ts`:

```ts
import { Shard } from '@signe/room';

export default class ShardServer extends Shard {}
```

By default, a shard belongs to `world-default`. For a multi-world deployment, the shard can resolve its world from the shard id generated by `WorldRoom`, from constructor options, or from environment variables:

```ts
import { Shard, type Party } from '@signe/room';

export default class EuShardServer extends Shard {
  constructor(room: Party.Room) {
    super(room, {
      worldId: 'world-eu'
    });
  }
}
```

If you let `WorldRoom` create shard metadata, shard ids use this format:

```txt
{roomId}:{worldId}:{uniqueShardId}
```

For example:

```txt
match-123:world-eu:1710000000000-4821
```

The `Shard` class can read `world-eu` from that id and report stats back to the matching world.

3. Configure your `partykit.json` file:

```json
{
  "$schema": "https://www.partykit.io/schema.json",
  "name": "yourapp",
  "main": "party/server.ts",
  "compatibilityDate": "2025-02-04",
  "parties": {
    "shard": "party/shard.ts", // Shard implementation
    "world": "party/server.ts" // World service implementation
  }
}
```

#### Multi-World Setup

`WorldRoom` uses the dynamic path `world-{worldId}`. This means these are separate world instances:

```txt
/parties/world/world-default
/parties/world/world-eu
/parties/world/world-us
```

Each world owns its own room registry, shard registry, load-balancing counters, shard heartbeats, and inactive shard cleanup. A shard should report to exactly one world.

When a client connects through a specific world, pass the same `worldId` to `connectionWorld()`:

```js
const euConnection = await connectionWorld({
  host: 'https://your-app-url.com',
  room: 'match-123',
  worldId: 'world-eu',
  autoCreate: true
}, room);
```

For an admin connection to a world room, use the world id as the room id:

```js
const worldConnection = await connectionRoom({
  host: window.location.origin,
  room: 'world-eu',
  party: 'world',
  query: {
    'world-auth-token': 'your-jwt-token'
  }
}, worldRoom);
```

#### World Admin Authorization

World management endpoints and world-room WebSocket connections require a JWT signed with `AUTH_JWT_SECRET`. The token must include a `worlds` claim listing the world ids that the operator can access:

```json
{
  "sub": "operator-1",
  "worlds": ["world-default", "world-eu"]
}
```

Use `["*"]` for a global operator:

```json
{
  "sub": "admin",
  "worlds": ["*"]
}
```

Tokens without a `worlds` claim, or without the current world id in that claim, are rejected even when the JWT signature is valid. Admin clients can pass the token either with an `Authorization: Bearer <token>` header or with the `world-auth-token` query parameter:

```js
await fetch('/parties/world/world-eu/register-room', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'match-123',
    balancingStrategy: 'round-robin',
    public: true,
    maxPlayersPerShard: 50
  })
});
```

The same `worldId` must be used consistently by:
- the client request to `connectionWorld()`;
- the `WorldRoom` party id;
- the shard metadata/id or shard constructor option.

#### Client Connection

On the client side, use the `connectionWorld` function to connect to your room through the World service:

```js
import { connectionWorld } from '@signe/sync/client';

// Initialize your room instance
const room = new YourRoomSchema();

// Connect through the World service
const connection = await connectionWorld({
  host: 'https://your-app-url.com', // Your application URL
  room: 'unique-room-id',             // Room identifier
  worldId: 'world-eu',                 // Optional, defaults to 'world-default'
  autoCreate: true,                     // Auto-create room if it doesn't exist
  retryCount: 3,                        // Number of connection attempts
  retryDelay: 1000                    // Delay between retries in ms
}, room);

// Listen for events
connection.on('customEvent', (data) => {
  console.log('Received custom event:', data);
});

// Send events to the room
connection.emit('increment', { value: 1 });

// Close the connection when done
connection.close();
```

For connecting to a standard room (not through World service), use the `connectionRoom` function:

```js
import { connectionRoom } from '@signe/sync/client';

// Initialize your room instance
const room = new YourRoomSchema();
const sessionId = localStorage.getItem('room-session-id') ?? crypto.randomUUID();
localStorage.setItem('room-session-id', sessionId);

// Connect directly to a room
const connection = await connectionRoom({
  host: window.location.origin,
  room: 'your-room-name',
  id: sessionId,
  party: 'your-party-name', // Optional, defaults to main party
  query: {} // Optional query parameters
}, room);

// For connecting to a World room with authentication
const worldConnection = await connectionRoom({
  host: window.location.origin,
  room: 'world-default',
  party: 'world',
  query: {
    // Use pre-generated JWT token for authentication
    'world-auth-token': 'your-jwt-token'
  }
}, worldRoom);
```

The `connectionWorld` function:
1. Queries the World service to find the optimal shard for the requested room
2. Establishes a WebSocket connection to the assigned shard
3. Returns a connection object with methods for sending and receiving messages

This approach offers several benefits:
- Automatic load balancing across multiple servers
- Simplified connection management
- Built-in retry logic for reliability
- Room creation on demand

#### Shard Lifecycle Notes

World tracks each shard with:
- `roomId`: the logical room served by the shard;
- `worldId`: the world that owns the shard;
- `url`: the shard connection target returned to clients;
- `currentConnections`: the latest reported connection count;
- `maxConnections`: the configured shard capacity;
- `status`: `active`, `maintenance`, or `draining`;
- `lastHeartbeat`: the latest stats update timestamp.

The built-in balancing strategies only consider active shards with available capacity (`currentConnections < maxConnections`):
- `round-robin`: rotates through available shards;
- `least-connections`: picks the available shard with the lowest reported connection count;
- `random`: picks a random available shard.

If every active shard is full and `autoCreate` is enabled, the world creates another shard when the room has not reached `maxShards`. If no capacity is available and the room cannot create another shard, `/connect` returns a capacity error.

Shard stats are updated when connections change and through periodic forced heartbeats. Inactive shards are removed after the world cleanup timeout.

When a shard is marked `draining`, the world stops assigning new clients to it. Existing WebSocket clients remain connected to that shard. Once the shard reports `currentConnections: 0`, the world removes it from the shard registry automatically. Scaling down uses the same flow: empty candidate shards are removed immediately, while occupied candidate shards are marked `draining` and removed later when they become empty.

Current limitations:
- Draining does not migrate connected clients; it waits for them to disconnect naturally.
- The world registry is held in room state; use deployment-specific persistence if your topology requires an external global registry.

### Packet Interception

You can implement the `interceptorPacket` method in your room to inspect and modify packets before they're sent to users:

```ts
class GameRoom {
  // Intercept packets before they're sent to users
  async interceptorPacket(user: Player, packet: any, conn: Party.Connection) {
    // Modify the packet based on user-specific logic
    if (user.role === 'spectator') {
      delete modifiedPacket.secretData;
      return modifiedPacket;
    }
    
    // Return null to prevent the packet from being sent to this user
    if (user.isBlocked) {
      return null;
    }
    
    // Return the packet as is or with modifications
    return packet;
  }
}
```

The `interceptorPacket` method allows you to:
- Modify packets on a per-user basis before they're sent
- Return a modified packet to change what the user receives
- Return `null` to prevent the packet from being sent to that user
- Implement user-specific filtering or censoring of data

### Lifecycle Hooks

Rooms provide several lifecycle hooks:

```ts
class GameRoom {
  async onJoin(player: Player, conn: Connection, ctx: ConnectionContext) {}
  async onLeave(player: Player, conn: Connection) {}
}
```

## Server Methods

The server provides several methods to help you manage your room:

```ts
import { RoomMethods } from "@signe/room";

export class GameRoom {
  action(name: string, data: any) {
    this.$send(conn, {
      type: 'action',
      name,
      data
    })
  }
  
  broadcast(name: string, data: any) {
    this.$broadcast({
      type: 'action',
      name,
      data
    })
  }
}

export interface GameRoom extends RoomMethods {}


## Party.Connection

Wraps a standard WebSocket, with a few additional PartyKit-specific properties.

```ts
connection.send("Good-bye!");
connection.close();
```

> https://docs.partykit.io/reference/partyserver-api/#partyconnection

## Node.js adapter

`@signe/room/node` runs a room server in a standard single-process Node.js
application. It is useful for local development, self-hosting, Express/Fastify
style integrations, Vite dev servers, and tests that do not need PartyKit.

```ts
import { createServer } from "node:http";
import { WebSocketServer } from "ws";
import { Action, Request, Room, Server } from "@signe/room";
import { createMemoryNodeRoomStorage, createNodeRoomTransport } from "@signe/room/node";
import { signal } from "@signe/reactive";
import { sync } from "@signe/sync";

@Room({ path: "demo" })
class CounterRoom {
  @sync() count = signal(0);

  @Action("increment")
  increment(_user: unknown, value: { amount?: number }) {
    this.count.update((count) => count + (value.amount ?? 1));
  }

  @Request({ path: "/count" })
  getCount() {
    return { count: this.count() };
  }
}

class CounterServer extends Server {
  rooms = [CounterRoom];
}

const storage = createMemoryNodeRoomStorage();

const transport = createNodeRoomTransport(CounterServer, {
  partiesPath: "/parties/main",
  storage,
});

const server = createServer((req, res) => {
  void transport.handleNodeRequest(req, res);
});

const wsServer = new WebSocketServer({ noServer: true });

server.on("upgrade", (request, socket, head) => {
  transport.handleUpgrade(wsServer, request, socket, head);
});

server.listen(3000);
```

HTTP requests use the same PartyKit-style room path:

```bash
curl http://localhost:3000/parties/main/demo/count
```

WebSocket clients connect to the room URL and send normal action packets:

```js
const socket = new WebSocket("ws://localhost:3000/parties/main/demo");

socket.send(JSON.stringify({
  action: "increment",
  value: { amount: 1 }
}));
```

For middleware frameworks, pass a `next` callback. Requests that do not match
the configured parties path are delegated to `next`.

```ts
app.use((req, res, next) => {
  void transport.handleNodeRequest(req, res, next);
});
```

Room-to-room requests are available through `room.context.parties`:

```ts
const response = await this.room.context.parties.main
  .get("other-room")
  .fetch("/count");
```

The Node adapter stores room state in memory by default. The package also
provides explicit memory and SQLite storage providers.

Use `createMemoryNodeRoomStorage()` when you want to keep a reference to the
memory backend, inspect it, clear it, or save a snapshot for a later process
restart.

```ts
const storage = createMemoryNodeRoomStorage();

const transport = createNodeRoomTransport(CounterServer, {
  storage,
});

const snapshot = storage.snapshot();
const restoredStorage = createMemoryNodeRoomStorage({ snapshot });
```

Use `createSqliteNodeRoomStorage()` when you want room storage persisted in a
SQLite database. This helper uses Node's built-in `node:sqlite` module.

```ts
import {
  createNodeRoomTransport,
  createSqliteNodeRoomStorage,
} from "@signe/room/node";

const transport = createNodeRoomTransport(CounterServer, {
  storage: createSqliteNodeRoomStorage({
    databasePath: "./rooms.sqlite",
  }),
});
```

The SQLite helper enables `PRAGMA busy_timeout = 5000` and `PRAGMA journal_mode
= WAL` by default to make development servers more tolerant of short-lived
write contention. You can override those defaults with `busyTimeoutMs`,
`journalMode`, and `busyRetries`.

Room state is stored as incremental `state:` entries. When a persisted delete is
encountered, the server compacts the room state by materializing the current
snapshot and removing durable delete markers. This keeps long-running SQLite
storage from accumulating `"$delete"` tombstones after objects or users are
removed.

To create your own storage backend, implement the key-value methods used by
`@signe/room`: `get`, `put`, `delete`, and `list`, then return it from a storage
provider.

```ts
import type { NodeRoomStorage, NodeRoomStorageProvider } from "@signe/room/node";

class MyStorage implements NodeRoomStorage {
  async get<T = unknown>(key: string): Promise<T | undefined> {
    // Read from your database
  }

  async put<T = unknown>(key: string, value: T): Promise<void> {
    // Write to your database
  }

  async delete(key: string): Promise<void | boolean> {
    // Delete from your database
  }

  async list<T = unknown>(): Promise<Map<string, T>> {
    // Return all key/value entries for the room
  }
}

const storage: NodeRoomStorageProvider = {
  getStorage(namespace, roomId) {
    return new MyStorage(namespace, roomId);
  },
};

const transport = createNodeRoomTransport(CounterServer, {
  storage,
});
```

To create your own Node transport integration, use the low-level methods exposed
by `createNodeRoomTransport()`:

- `transport.fetch(requestOrPath, init?)` for runtimes using Web
  `Request`/`Response`;
- `transport.handleNodeRequest(req, res, next?)` for Node HTTP middleware;
- `transport.handleUpgrade(wsServer, request, socket, head)` for `ws`
  WebSocket upgrades;
- `transport.acceptWebSocket(webSocket, request)` when your framework already
  accepted the WebSocket and you only need to attach it to a room.

The first Node adapter version targets single-process Node.js only; clustering,
multi-process coordination, Cloudflare Durable Objects, Bun WebSocket, and
uWebSockets.js support are outside this adapter.

See `packages/room/examples/node` for a runnable HTTP + WebSocket example.

## Testing

```ts
import { test, vi } from "vitest"
import { testRoom, Room, Action, sync } from "@signe/room"
import { signal } from "@signe/reactive"

test('test', async () => {

    @Room({
        path: "game"
    })
    class GameRoom {
      @sync() count = signal(0);

      @Action('increment')
      increment() {
        this.count.update(c => c + 1)
      }
    }

    const { createClient, room, server } = await testRoom(GameRoom)
    const client1 = await createClient()
    const client2 = await createClient()

    const countFn = vi.fn()

    client1.addEventListener('message', countFn)
    client2.addEventListener('message',countFn)

    await client1.send({
        action: 'increment'
    })

    expect(countFn).toHaveBeenCalledTimes(2)
    expect(countFn).toHaveBeenCalledWith('{"type":"sync","value":{"count":1}}')
    expect(room.count()).toBe(1)
    expect(server.roomStorage.get('.')).toEqual({
      count: 1
    })
})
```

## License

MIT

---
_Source: https://npm.io/package/@signe/room · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._