Centralized, runtime-agnostic library for real-time collaboration and synchronization
npm install @principal-ai/control-tower-coreCentralized, runtime-agnostic library for real-time collaboration and synchronization.
``bash`
npm install @principal-ai/control-tower-core
`typescript
import {
ServerBuilder,
DefaultRoomManager,
DefaultLockManager,
MockTransportAdapter
} from '@principal-ai/control-tower-core';
// Create a server with default implementations
const server = new ServerBuilder()
.withTransport(new MockTransportAdapter())
.withRoomManager(new DefaultRoomManager())
.withLockManager(new DefaultLockManager())
.build();
await server.start(8080);
console.log('Server started on port 8080');
`
- Room Management: Create, join, and manage collaborative rooms
- Lock Management: File/directory locking with queue support
- Real-time Events: Event broadcasting and history
- Extensible: Abstract interfaces for custom implementations
- TypeScript: Full type safety with generated declarations
- Experimental APIs: Opt-in broadcast features for rapid prototyping (see Experimental Features)
The main entry point for creating servers:
`typescript`
const server = new ServerBuilder()
.withTransport(transportAdapter)
.withRoomManager(roomManager)
.withLockManager(lockManager)
.withAuth(authAdapter) // optional
.withStorage(storageAdapter) // optional
.withDefaultRoomConfig({
maxUsers: 50,
maxHistory: 100,
permissions: ['read', 'write']
})
.build();
- DefaultRoomManager: In-memory room managementDefaultLockManager
- : In-memory locking with queue supportMockTransportAdapter
- : Mock transport for testing
Implement the abstract interfaces to create custom adapters:
`typescript
import { RoomManager } from '@principal-ai/control-tower-core';
class CustomRoomManager extends RoomManager {
async createRoom(id: string, config: RoomConfig): Promise
// Your implementation
}
// ... implement other methods
}
`
⚠️ For Development Use Only
Control Tower Core provides experimental broadcast APIs for rapid prototyping and internal tooling. These APIs allow broadcasting messages beyond room boundaries.
`typescript
import { ServerBuilder } from '@principal-ai/control-tower-core';
const server = new ServerBuilder()
.withTransport(transportAdapter)
.withRoomManager(roomManager)
.withLockManager(lockManager)
.withExperimentalFeatures({
enableBroadcast: true // Enable experimental broadcast APIs
})
.build();
`
`typescript
// Broadcast to all connected clients
await server.experimental.broadcast({
type: 'system:announcement',
data: { message: 'Server maintenance in 5 minutes' }
});
// Broadcast to authenticated users only
await server.experimental.broadcastAuthenticated({
type: 'presence:user_online',
data: { userId: 'alice' }
});
// Broadcast with custom filtering
await server.experimental.broadcastWhere(
(client) => client.userId.startsWith('admin_'),
{ type: 'admin:alert', data: { ... } }
);
// Send to specific users
await server.experimental.sendToUsers(
['user1', 'user2'],
{ type: 'notification:mention', data: { ... } }
);
`
- Experimental APIs may change or be removed without major version bumps
- Not recommended for production applications
- Use for prototyping, then submit a feature request to graduate to stable API
- See full documentation for details
Control Tower Core provides comprehensive test utilities for building reliable applications.
The MockTransportAdapter provides test helpers for simulating client-server interactions:
`typescript
import { MockTransportAdapter } from '@principal-ai/control-tower-core';
const transport = new MockTransportAdapter();
// Simulate a client connection
await transport.simulateConnection('client-id', {
authenticated: true,
userId: 'user-123',
metadata: { deviceType: 'desktop' }
});
// Simulate client messages
await transport.simulateClientMessage('client-id', 'join_room', {
roomId: 'room-1'
});
// Simulate incoming server messages (for client tests)
transport.simulateIncomingMessage({
type: 'room_joined',
payload: { roomId: 'room-1', state: { ... } }
});
// Track connection attempts (useful for reconnection tests)
const attempts = transport.getConnectionAttempts();
transport.resetConnectionAttempts();
// Get messages sent to specific clients
const messages = transport.getSentMessages('client-id');
`
`bashRun all tests
bun test
- Experimental Broadcast APIs
- Feature Request Template
- Architecture Design
- Changelog
MIT