{"_id":"@aionbuilders/helios","_rev":"3-881344ad42de527198f31ab90306e907","name":"@aionbuilders/helios","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@aionbuilders/helios","version":"1.0.0","keywords":["websocket","bun","server","real-time","rpc","pubsub","session-recovery","rooms","broadcast","helios","ws","websockets"],"author":"Killian Di Vincenzo","license":"MIT","_id":"@aionbuilders/helios@1.0.0","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios#readme","bugs":{"url":"https://github.com/aionbuilders/helios/issues"},"dist":{"shasum":"82585aa7020f3c569eb27f65f14b7027222d9667","tarball":"https://registry.npmjs.org/@aionbuilders/helios/-/helios-1.0.0.tgz","fileCount":27,"integrity":"sha512-F6TzMa0bG1vRZn+eOuIxFIa6hNepo9egJYOXPrdJxyJNGYO6WyScistQvSTrvWoBOMAjL7BTVUT1Xf90cBlY2w==","signatures":[{"sig":"MEYCIQCZaJMbU4qdPImTgc2PbU3YuMv6gQTqxq5lV1iEcG58pgIhANJLV5jHNsNiQxsTsEQHISuUeuSUEXkag03P/pG31JQO","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":111135},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","shasum":"82585aa7020f3c569eb27f65f14b7027222d9667","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"dev":"bun run --watch tests/server.js","build":"bun build src/index.js --outdir dist --target node --minify","release:alpha":"npm version prerelease && npm publish --tag alpha","release:minor":"npm version minor && npm publish --tag latest","release:patch":"npm version patch && npm publish","generate-types":"tsc --project ./tsc/tsconfig.json","prepublishOnly":"bun test && npm run build && npm run generate-types","release:stable":"npm version major && npm publish"},"_npmUser":{"name":"killiandvcz","email":"hello@killiandvcz.fr"},"_integrity":"sha512-F6TzMa0bG1vRZn+eOuIxFIa6hNepo9egJYOXPrdJxyJNGYO6WyScistQvSTrvWoBOMAjL7BTVUT1Xf90cBlY2w==","repository":{"url":"https://github.com/aionbuilders/helios.git","type":"git"},"_npmVersion":"10.8.3","description":"WebSocket server implementation for Bun - Production-ready real-time messaging with session recovery, health checks, and room management","directories":{},"_nodeVersion":"24.3.0","dependencies":{"jose":"^6.1.3","@killiandvcz/pulse":"^2.1.3","@aionbuilders/helios-protocol":"^1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/helios_1.0.0_1767188709989_0.20680397988290888","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aionbuilders/helios","version":"1.0.1","keywords":["websocket","bun","server","real-time","rpc","pubsub","session-recovery","rooms","broadcast","helios","ws","websockets"],"author":{"name":"Killian Di Vincenzo"},"license":"MIT","_id":"@aionbuilders/helios@1.0.1","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios#readme","bugs":{"url":"https://github.com/aionbuilders/helios/issues"},"dist":{"shasum":"9464759bc16a15b9980508cd126635cb2833ccc2","tarball":"https://registry.npmjs.org/@aionbuilders/helios/-/helios-1.0.1.tgz","fileCount":27,"integrity":"sha512-nIiClXOT86W/xtUhtJrNhEskz+3fPjx06X6F1vCatY6W3WIU4DgpJsd4JkPejMSV8b+C1lblLi3eLw+8KqIWmw==","signatures":[{"sig":"MEUCIQDP0WmNQ+th3P15lVNaIIQHfC4z23b+2hfJ+kAxBtZ08gIgCxUarKui1Q1e9BSsl2NZx0fqm0GiQZMgCq9X/e/ucZ8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":110907},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"dev":"bun run --watch tests/server.js","build":"bun build src/index.js --outdir dist --target node --minify","release:alpha":"npm version prerelease && npm publish --tag alpha","release:minor":"npm version minor && npm publish --tag latest","release:patch":"npm version patch && npm publish","generate-types":"tsc --project ./tsc/tsconfig.json","prepublishOnly":"bun test && npm run build && npm run generate-types","release:stable":"npm version major && npm publish"},"_npmUser":{"name":"killiandvcz","email":"hello@killiandvcz.fr"},"repository":{"url":"git+https://github.com/aionbuilders/helios.git","type":"git"},"_npmVersion":"10.9.2","description":"WebSocket server implementation for Bun - Production-ready real-time messaging with session recovery, health checks, and room management","directories":{},"_nodeVersion":"22.14.0","dependencies":{"jose":"^6.1.3","@killiandvcz/pulse":"^2.1.3","@aionbuilders/helios-protocol":"^1.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"1.3.6"},"peerDependencies":{"typescript":"^5.9.3"},"_npmOperationalInternal":{"tmp":"tmp/helios_1.0.1_1768486119368_0.43900455793831084","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aionbuilders/helios","version":"1.0.2","description":"WebSocket server implementation for Bun - Production-ready real-time messaging with session recovery, health checks, and room management","types":"dist/index.d.ts","main":"dist/index.js","module":"dist/index.js","type":"module","scripts":{"dev":"bun run --watch tests/server.js","build":"bun build src/index.js --outdir dist --target node --minify","generate-types":"tsc --project ./tsc/tsconfig.json","prepublishOnly":"bun test && npm run build && npm run generate-types","release:alpha":"npm version prerelease && npm publish --tag alpha","release:stable":"npm version major && npm publish","release:minor":"npm version minor && npm publish --tag latest","release:patch":"npm version patch && npm publish"},"exports":{".":{"import":"./dist/index.js","require":"./dist/index.js","types":"./dist/index.d.ts"}},"keywords":["websocket","bun","server","real-time","rpc","pubsub","session-recovery","rooms","broadcast","helios","ws","websockets"],"engines":{"bun":">=1.0.0"},"author":{"name":"Killian Di Vincenzo"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aionbuilders/helios.git"},"bugs":{"url":"https://github.com/aionbuilders/helios/issues"},"homepage":"https://github.com/aionbuilders/helios#readme","publishConfig":{"access":"public"},"devDependencies":{"@types/bun":"1.3.6"},"peerDependencies":{"typescript":"^5.9.3"},"dependencies":{"@aionbuilders/helios-protocol":"^1.1.1","@killiandvcz/pulse":"^2.1.3","jose":"^6.1.3"},"_id":"@aionbuilders/helios@1.0.2","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-x9TpNRgxtNVo2sPKNVFL9uE47f1SPp8BXqhbXmiQA+aFfT3Kb6+9EZ+XnSYVX//Vh9+z4/CC+FZ7wlaW3BJP1g==","shasum":"390ac50ff9f2eda565a37f2a9a46bc215ee4bdab","tarball":"https://registry.npmjs.org/@aionbuilders/helios/-/helios-1.0.2.tgz","fileCount":27,"unpackedSize":111140,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCcVZ/sSqfga9ijZZ1EEJ8DvyBPF8ZUiYVXB6yN2bhG2gIgUynd8A5JQkm3GQEvzAMxPQGxP2vrbs0g/iySbX4yA7Y="}]},"_npmUser":{"name":"killiandvcz","email":"hello@killiandvcz.fr"},"directories":{},"maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/helios_1.0.2_1768487723819_0.18129869282299005"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-31T13:45:09.921Z","modified":"2026-01-15T14:35:24.133Z","1.0.0":"2025-12-31T13:45:10.134Z","1.0.1":"2026-01-15T14:08:39.524Z","1.0.2":"2026-01-15T14:35:23.989Z"},"bugs":{"url":"https://github.com/aionbuilders/helios/issues"},"author":{"name":"Killian Di Vincenzo"},"license":"MIT","homepage":"https://github.com/aionbuilders/helios#readme","keywords":["websocket","bun","server","real-time","rpc","pubsub","session-recovery","rooms","broadcast","helios","ws","websockets"],"repository":{"type":"git","url":"git+https://github.com/aionbuilders/helios.git"},"description":"WebSocket server implementation for Bun - Production-ready real-time messaging with session recovery, health checks, and room management","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"readme":"# @aionbuilders/helios\n\n> WebSocket server implementation for Bun - Production-ready real-time messaging\n\n[![npm version](https://badge.fury.io/js/@aionbuilders%2Fhelios.svg)](https://www.npmjs.com/package/@aionbuilders/helios)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Bun](https://img.shields.io/badge/Bun-%23000000.svg?style=flat&logo=bun&logoColor=white)](https://bun.sh)\n\n## Why Helios?\n\n**Not Socket.IO, not bare WebSocket** - Helios sits in between:\n- More structured than raw WebSocket\n- Less opinionated than Socket.IO\n- Leverages Bun's native performance\n- Built on solid primitives\n\n## Features\n\n### ✨ Production Ready\n- 🔐 **Session Recovery** - Reconnect without data loss (JWT-based)\n- 💓 **Health Checks** - Automatic ping/pong keep-alive\n- 📡 **Room Manager** - Broadcast with permission validators\n- 🎯 **RPC Methods** - Request/response with middleware\n- 📢 **Pub/Sub Events** - Topic-based subscriptions\n- 🧹 **Clean Lifecycle** - Proper connection cleanup\n\n### 🚀 Performance\n- Native Bun.serve WebSocket\n- Zero-copy message passing\n- Efficient pattern matching\n- Minimal overhead\n\n### 🛠️ Developer Experience\n- TypeScript definitions\n- Comprehensive JSDoc\n- Middleware support\n- Event-driven architecture\n\n## Installation\n\n```bash\n# Using bun (recommended)\nbun add @aionbuilders/helios\n\n# Using npm\nnpm install @aionbuilders/helios\n```\n\n**Requirements**: Bun v1.0+\n\n## Quick Start\n\n### Basic Server\n\n```javascript\nimport { Helios } from '@aionbuilders/helios';\n\nconst helios = new Helios();\n\n// Register a method\nhelios.method('user.get', async (context) => {\n  return {\n    id: context.payload.userId,\n    name: \"Alice\"\n  };\n});\n\n// Listen to events\nhelios.on('chat:message', async (data, context) => {\n  console.log('Message:', data);\n});\n\n// Start server\nhelios.serve({ port: 3000 });\nconsole.log('✨ Helios running on port 3000');\n```\n\n### With Session Recovery\n\n```javascript\nconst helios = new Helios({\n  sessionRecovery: {\n    enabled: true,\n    secret: process.env.SESSION_SECRET, // min 32 bytes\n    ttl: 5 * 60 * 1000 // 5 minutes\n  }\n});\n\nhelios.events.on('session:recovered', ({ connection, session }) => {\n  console.log('Session recovered:', session.sessionId);\n});\n```\n\n### With Rooms (Broadcast)\n\n```javascript\n// Declare rooms with validators\nhelios.room('lobby', { type: 'public' });\n\nhelios.room('user:*', {\n  validator: async (connection, captures) => {\n    const [userId] = captures;\n    return connection.data.get('userId') === userId;\n  }\n});\n\n// Broadcast to room\nhelios.broadcast('lobby', {\n  type: 'announcement',\n  message: 'Welcome!'\n});\n```\n\n### With Middleware\n\n```javascript\n// Global middleware\nhelios.use('**', async (context, next) => {\n  console.log('Request:', context.method);\n  const start = Date.now();\n\n  const result = await next();\n\n  console.log('Duration:', Date.now() - start, 'ms');\n  return result;\n});\n\n// Namespace middleware\nconst api = helios.namespace('api');\napi.use('**', async (context, next) => {\n  // Auth check\n  const token = context.connection.data.get('token');\n  if (!token) {\n    return context.createErrorResponse('Unauthorized', 401);\n  }\n  return await next();\n});\n\napi.register('users.list', async (context) => {\n  return { users: [...] };\n});\n```\n\n## Core Concepts\n\n### Connection\n\nEach WebSocket connection is wrapped in a `Connection` instance:\n\n```javascript\nhelios.events.on('connection', ({ connection }) => {\n  // Store user data\n  connection.data.set('user', { id: 123, role: 'admin' });\n\n  // Send messages\n  connection.emit('welcome', { message: 'Hello!' });\n\n  // Make requests\n  const response = await connection.request('service.call', { ... });\n});\n```\n\n### Methods (RPC)\n\nRegister methods that clients can call:\n\n```javascript\nhelios.method('user.create', async (context) => {\n  const { username, email } = context.payload;\n\n  // Access connection\n  const userId = context.connection.data.get('userId');\n\n  // Return response\n  return { id: newUserId, username };\n});\n```\n\n### Events (Pub/Sub)\n\nSubscribe to events from clients:\n\n```javascript\nhelios.on('chat:message', async (data, context) => {\n  // data = event payload\n  // context = EventContext with connection info\n\n  // Broadcast to others\n  helios.broadcast('chat:room', {\n    from: context.clientId,\n    message: data.text\n  });\n});\n```\n\n### Rooms\n\nManage broadcast groups with permissions:\n\n```javascript\n// Public room\nhelios.room('lobby', { type: 'public' });\n\n// Protected room with pattern\nhelios.room('document:*', {\n  validator: async (connection, captures, data) => {\n    const [docId] = captures;\n    return await checkDocumentAccess(\n      connection.data.get('userId'),\n      docId\n    );\n  }\n});\n\n// Clients subscribe via RPC\n// Built-in method: helios.subscribe\n```\n\n## Session Recovery\n\nConnections can reconnect after network issues without losing state:\n\n```javascript\nconst helios = new Helios({\n  sessionRecovery: {\n    enabled: true,\n    secret: process.env.SESSION_SECRET,\n    ttl: 5 * 60 * 1000 // 5 minutes\n  }\n});\n```\n\n**What's preserved:**\n- ✅ `connection.data` Map\n- ✅ Room subscriptions\n- ✅ Pending requests\n- ✅ All connection properties\n\nSee [SESSION_RECOVERY.md](./SESSION_RECOVERY.md) for details.\n\n## Health Checks\n\nAutomatic ping/pong to detect dead connections:\n\n```javascript\nconst helios = new Helios({\n  healthCheck: {\n    enabled: true,        // default: true\n    interval: 30000,      // 30s\n    timeout: 10000,       // 10s\n    maxMissed: 2          // close after 2 missed pongs\n  }\n});\n\nhelios.events.on('ping-timeout', ({ connection }) => {\n  console.log('Connection dead:', connection.id);\n});\n```\n\n## API Reference\n\n### Helios Options\n\n```typescript\ninterface HeliosOptions {\n  requestTimeout?: number;          // Default: 5000ms\n  parseMode?: 'strict' | 'permissive'; // Default: 'strict'\n  sessionRecovery?: SessionRecoveryOptions;\n  healthCheck?: HealthCheckOptions;\n}\n\ninterface SessionRecoveryOptions {\n  enabled: boolean;\n  secret: string;           // Required: 32+ bytes\n  ttl?: number;             // Default: 300000ms (5 min)\n}\n\ninterface HealthCheckOptions {\n  enabled?: boolean;        // Default: true\n  interval?: number;        // Default: 30000ms\n  timeout?: number;         // Default: 10000ms\n  maxMissed?: number;       // Default: 2\n}\n```\n\n### Connection\n\n```typescript\nclass Connection {\n  id: string;\n  sessionId: string | null;\n  data: Map<string, any>;\n\n  // Send messages\n  send(message: Message): Promise<boolean>;\n  emit(topic: string, data: any): Promise<boolean>;\n  request(method: string, payload: any): Promise<Response>;\n\n  // State\n  state: 'OPEN' | 'CLOSING' | 'CLOSED';\n}\n```\n\n### Events\n\n```javascript\n// Lifecycle\nhelios.events.on('connection', ({ connection, helios }) => { ... });\nhelios.events.on('disconnection', ({ connection, code, reason }) => { ... });\n\n// Session Recovery\nhelios.events.on('session:recovered', ({ connection, session }) => { ... });\nhelios.events.on('session:refreshed', ({ connection, token }) => { ... });\n\n// Rooms\nhelios.events.on('room:subscribed', ({ connection, topic }) => { ... });\nhelios.events.on('room:unsubscribed', ({ connection, topic }) => { ... });\n\n// Health Checks\nhelios.events.on('ping-timeout', ({ connection }) => { ... });\nhelios.events.on('ping-missed', ({ connection, missedPongs }) => { ... });\nhelios.events.on('pong-received', ({ connection, latency }) => { ... });\n```\n\n## Examples\n\n### Authentication\n\n```javascript\nhelios.events.on('connection', async ({ connection }) => {\n  // Wait for auth\n  const timeout = setTimeout(() => {\n    connection.ws.close(4001, 'Auth timeout');\n  }, 5000);\n\n  helios.events.once(`auth:${connection.id}`, ({ token }) => {\n    clearTimeout(timeout);\n    const user = validateToken(token);\n    connection.data.set('user', user);\n  });\n});\n\nhelios.method('auth.login', async (context) => {\n  const { username, password } = context.payload;\n  const token = await authenticateUser(username, password);\n\n  helios.events.emit(`auth:${context.connection.id}`, { token });\n\n  return { success: true, token };\n});\n```\n\n### Chat Room\n\n```javascript\n// Declare room\nhelios.room('chat:*', {\n  validator: async (connection, captures) => {\n    const [roomId] = captures;\n    // Check if user has access to room\n    return await hasRoomAccess(\n      connection.data.get('userId'),\n      roomId\n    );\n  }\n});\n\n// Handle messages\nhelios.on('chat:message', async (data, context) => {\n  const user = context.connection.data.get('user');\n\n  // Broadcast to room\n  helios.broadcast(context.topic, {\n    from: user.username,\n    text: data.text,\n    timestamp: Date.now()\n  });\n});\n```\n\n### Microservices Gateway\n\n```javascript\nconst helios = new Helios();\n\n// Service connections\nconst services = new Map();\n\nhelios.events.on('connection', ({ connection }) => {\n  const serviceType = connection.data.get('serviceType');\n  if (serviceType) {\n    services.set(serviceType, connection);\n  }\n});\n\n// Route to services\nhelios.method('gateway.**', async (context) => {\n  const [, serviceName] = context.method.split('.');\n  const service = services.get(serviceName);\n\n  if (!service) {\n    return context.createErrorResponse('Service unavailable', 503);\n  }\n\n  return await service.request(context.method, context.payload);\n});\n```\n\n## Related Packages\n\n- [@aionbuilders/helios-protocol](https://npm.im/@aionbuilders/helios-protocol) - Core protocol\n- [@aionbuilders/starling](https://npm.im/@aionbuilders/starling) - Client implementation\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Run tests\nbun test\n\n# Run example server\nbun run dev\n\n# Watch mode\nbun --watch tests/server.js\n```\n\n## Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new features\n4. Submit a pull request\n\n## License\n\nMIT © Killian Di Vincenzo\n\n## Acknowledgments\n\nBuilt with ❤️ using [Bun](https://bun.sh)\n","readmeFilename":"README.md"}