@syncar/server 1.0.0-alpha.1 → 1.0.0-alpha.2

package/README.md

@@ -1,139 +1,206 @@
-# @synca/server
+# @syncar/server
 
-> Node.js WebSocket server for real-time synchronization with pub/sub broadcasting and composable middleware.
+> Real-time WebSocket server with pub/sub channels and composable middleware.
 
-[![npm version](https://badge.fury.io/js/%40synca%2Fserver.svg)](https://www.npmjs.com/package/@synca/server)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/%40syncar%2Fserver.svg)](https://www.npmjs.com/package/@syncar/server)
+![MIT License](https://img.shields.io/badge/license-MIT-blue)
 
-## Features
+## Why Syncar?
 
-- **Real-time WebSocket Communication** - Fast, bidirectional messaging powered by `ws`.
-- **Composable Middleware** - Hono-style middleware for auth, logging, rate limiting, and more.
-- **Broadcast & Multicast Channels** - Topic-based messaging patterns with automatic chunking.
-- **Handshake Authentication** - Dedicated hook for authenticating clients during connection.
-- **Type-Safe API** - Full TypeScript support for messages, context, and state.
-- **Automatic Chunking** - Handles high-volume broadcasts without blocking the event loop.
+- **Simple API** — Create servers in 3 lines of code
+- **Type-safe** — Full TypeScript support
+- **Flexible Channels** — Broadcast (all clients) or Multicast (subscribers only)
+- **Middleware** — Hono-style composable middleware for auth, logging, rate limiting
+- **Production Ready** — 97%+ test coverage, automatic reconnection, chunked broadcasts
 
 ## Installation
 
 ```bash
-npm install @synca/server
+npm install @syncar/server
 ```
 
 ## Quick Start
 
 ```typescript
-import { createSyncaServer } from '@synca/server'
+import { createSyncarServer } from '@syncar/server'
 
-const server = createSyncaServer({ port: 3000 })
-
-// 1. Add Middleware
-server.use(async (c, next) => {
-  console.log(`[${c.req.action}] client:${c.req.client?.id}`)
-  await next()
-})
+// Create and start server
+const server = createSyncarServer({ port: 3000 })
+await server.start()
 
-// 2. Create Channels
-const chat = server.createMulticast<string>('chat')
+// Create a chat channel (multicast - subscribers only)
+const chat = server.createMulticast<{ text: string; user: string }>('chat')
 
-// Optional: Custom message handling (disables auto-relay)
+// Handle incoming messages
 chat.onMessage((data, client) => {
-  console.log(`Received: ${data}`)
-  chat.publish(`User said: ${data}`, { exclude: [client.id] })
+    console.log(`${client.id}: ${data.text}`)
+    chat.publish(data, { exclude: [client.id] }) // Broadcast to others
 })
+```
 
-// 3. Start Server
-await server.start()
+## Core Concepts
+
+### Channels
+
+| Type        | Description                          | Use Case                            |
+| ----------- | ------------------------------------ | ----------------------------------- |
+| `Broadcast` | Sends to **all** connected clients   | System announcements, notifications |
+| `Multicast` | Sends to **subscribed** clients only | Chat rooms, topic-based feeds       |
+
+```typescript
+// Broadcast - everyone receives
+const broadcast = server.createBroadcast<string>()
+broadcast.publish('Server maintenance in 5 minutes')
+
+// Multicast - only subscribers receive
+const chat = server.createMulticast<Message>('chat')
+chat.publish({ text: 'Hello', user: 'Alice' })
 ```
 
-## Middleware
+### Client Connection
+
+```typescript
+// WebSocket connect
+const ws = new WebSocket('ws://localhost:3000')
+
+// Subscribe to multicast channel
+ws.send(JSON.stringify({ action: 'subscribe', channel: 'chat' }))
+
+// Send message to channel
+ws.send(
+    JSON.stringify({
+        action: 'message',
+        channel: 'chat',
+        data: { text: 'Hello' },
+    }),
+)
+```
 
-Synca uses a powerful middleware system inspired by Hono. Middleware can intercept `connect`, `disconnect`, `message`, `subscribe`, and `unsubscribe` actions.
+## Middleware
 
-### Built-in Middleware
+Add middleware globally or per-channel:
 
 ```typescript
-import { 
-  createAuthMiddleware, 
-  createLoggingMiddleware, 
-  createRateLimitMiddleware 
-} from '@synca/server'
-
-// Global Auth
-server.use(createAuthMiddleware({
-  verifyToken: async (token) => ({ id: '123', name: 'User' })
-}))
-
-// Channel-specific Middleware
-const adminChannel = server.createMulticast('admin')
-adminChannel.use(async (c, next) => {
-  if (c.get('user')?.role !== 'admin') {
-    return c.reject('Unauthorized')
-  }
-  await next()
+import { createAuthMiddleware, createRateLimitMiddleware } from '@syncar/server'
+
+const server = createSyncarServer({
+    port: 3000,
+    middleware: [
+        createAuthMiddleware({
+            verifyToken: async (token) => verifyJwt(token),
+            getToken: (ctx) => ctx.message?.data?.token,
+        }),
+        createRateLimitMiddleware({ maxRequests: 100, windowMs: 60000 }),
+    ],
+})
+
+// Channel-specific middleware
+const admin = server.createMulticast('admin')
+admin.use(async (c, next) => {
+    if (c.get('user')?.role !== 'admin') return c.reject('Unauthorized')
+    await next()
 })
 ```
 
-## Handshake Authentication
+Built-in middleware: `createAuthMiddleware`, `createLoggingMiddleware`, `createRateLimitMiddleware`, `createChannelWhitelistMiddleware`
 
-Validate clients before the WebSocket connection is even established.
+## Server Options
 
 ```typescript
-server.authenticate(async (request) => {
-  const token = request.headers['authorization']
-  if (!token) throw new Error('Missing token')
-  
-  const userId = await verify(token)
-  return userId // This becomes the client.id
+createSyncarServer({
+    port: 3000, // Server port
+    host: '0.0.0.0', // Bind address
+    path: '/syncar', // WebSocket endpoint
+    enablePing: true, // Auto ping/pong
+    pingInterval: 30000, // Ping interval (ms)
+    broadcastChunkSize: 500, // Chunk size for large broadcasts
+    logger: console, // Custom logger
+    middleware: [], // Global middleware
 })
 ```
 
-## Channels
-
-### Broadcast Channel
-Sends messages to **all** connected clients. No subscription needed.
+## Server Lifecycle
 
 ```typescript
-const broadcast = server.createBroadcast<string>()
-broadcast.publish('Global alert!')
+// Start server
+await server.start()
+
+// Get statistics
+const stats = server.getStats()
+// { clientCount, channelCount, subscriptionCount, startedAt }
+
+// Stop server (closes all connections)
+await server.stop()
 ```
 
-### Multicast Channel
-Topic-based messaging for **subscribed** clients.
+## With Existing HTTP Server
 
 ```typescript
-const room = server.createMulticast<string>('room-1')
+import { createServer } from 'http'
+import { Syncar } from '@syncar/server'
 
-// Manual subscription
-room.subscribe('client-id')
+const httpServer = createServer()
+const server = new Syncar({ server: httpServer })
 
-// Message handling (with auto-relay if no handler is set)
-room.onMessage((data, client) => {
-  // data is typed
-})
+await server.start()
+httpServer.listen(3000)
 ```
 
 ## API Reference
 
-### Server API
-| Method | Description |
-| :--- | :--- |
-| `start()` | Starts the server. |
-| `stop()` | Stops the server. |
-| `use(middleware)` | Registers global middleware. |
-| `authenticate(hook)` | Sets the handshake authentication hook. |
-| `createBroadcast<T>()` | Gets/creates the global broadcast channel. |
-| `createMulticast<T>(name)` | Gets/creates a named multicast channel. |
-| `getStats()` | Returns active clients, channels, and subscriptions. |
-
-### Channel API
-| Method | Description |
-| :--- | :--- |
-| `publish(data, options?)` | Sends message to subscribers. |
-| `onMessage(handler)` | Registers a custom message handler. |
-| `use(middleware)` | Registers channel-specific middleware. |
-| `subscribe(clientId)` | Manually subscribes a client. |
-| `unsubscribe(clientId)` | Manually unsubscribes a client. |
+### Syncar Class
+
+```typescript
+// Lifecycle
+start(): Promise<void>
+stop(): Promise<void>
+
+// Channels
+createBroadcast<T>(): BroadcastChannel<T>
+createMulticast<T>(name: string): MulticastChannel<T>
+hasChannel(name: string): boolean
+getChannels(): string[]
+
+// Middleware & Auth
+use(middleware: Middleware): void
+authenticate(hook: (request: IncomingMessage) => Promise<string>): void
+
+// Utilities
+getStats(): ServerStats
+getConfig(): Readonly<ServerConfig>
+getRegistry(): ClientRegistry
+```
+
+### Channel Methods (Broadcast/Multicast)
+
+```typescript
+// Publishing
+publish(data: T, options?: { exclude?: string[], to?: string[] }): Promise<void>
+
+// Handlers
+onMessage(handler: (data: T, client: Client) => void): void
+
+// Middleware
+use(middleware: Middleware): void
+
+// Subscription (Multicast only)
+subscribe(clientId: string): void
+unsubscribe(clientId: string): void
+```
+
+## Error Types
+
+```typescript
+import {
+    ConfigError, // Invalid configuration
+    TransportError, // WebSocket connection issues
+    ChannelError, // Channel operation errors
+    ClientError, // Client-specific errors
+    ValidationError, // Invalid input data
+    StateError, // Invalid server state
+    MiddlewareRejectionError, // Middleware blocked action
+} from '@syncar/server'
+```
 
 ## License