{"_id":"@aionbuilders/helios-protocol","_rev":"6-004a57a60ee31297f5fc544f198075da","name":"@aionbuilders/helios-protocol","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@aionbuilders/helios-protocol","version":"1.0.0","keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"author":"Killian Di Vincenzo","license":"MIT","_id":"@aionbuilders/helios-protocol@1.0.0","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios-protocol#readme","bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"dist":{"shasum":"55f86739d1fd28f5d17bd6ab8a3c0b33346ca81b","tarball":"https://registry.npmjs.org/@aionbuilders/helios-protocol/-/helios-protocol-1.0.0.tgz","fileCount":34,"integrity":"sha512-z/IToXC0Iz++HunxI2fm2WYY5UPzIwU8xBNi0YYSMNnjVIKIgF/gj17wATw2//KDNggTl3ip+otjPGlbReUTBQ==","signatures":[{"sig":"MEUCIQDvJXBY1nXvk0gSUzzisxhYmEzdbsLnC2QhiTFxf+fbUAIgFYeZIlFNZaXX4Q9J/6blrMGczXj3bsfe6wrpxNKyBdw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70506},"type":"module","types":"dist/index.d.ts","module":"src/index.js","shasum":"55f86739d1fd28f5d17bd6ab8a3c0b33346ca81b","exports":{".":{"types":"./dist/index.d.ts","import":"./src/index.js"}},"scripts":{"test":"bun test","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-z/IToXC0Iz++HunxI2fm2WYY5UPzIwU8xBNi0YYSMNnjVIKIgF/gj17wATw2//KDNggTl3ip+otjPGlbReUTBQ==","repository":{"url":"https://github.com/aionbuilders/helios-protocol.git","type":"git"},"_npmVersion":"10.8.3","description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","directories":{},"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.3.3"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/helios-protocol_1.0.0_1766937210142_0.7431187396443728","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aionbuilders/helios-protocol","version":"1.0.1","keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"author":{"name":"Killian Di Vincenzo"},"license":"MIT","_id":"@aionbuilders/helios-protocol@1.0.1","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios-protocol#readme","bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"dist":{"shasum":"1dc1584cceb29dff74e973357a3595c43cc5d251","tarball":"https://registry.npmjs.org/@aionbuilders/helios-protocol/-/helios-protocol-1.0.1.tgz","fileCount":33,"integrity":"sha512-PDbBB1wt3j7g15IulU0oVKqhctxdYPXRGcg8i21kEjcDH30dsuWdrNO7ou3EqJe9432xi/LnH5MFbbj6Q/+SKQ==","signatures":[{"sig":"MEUCIGQXkMC7ynhuQb+iKvFVpBzXO52kUQYyWxSv4wew5ChmAiEAv+t+XeY5CRPNZHpg7Z78YWSJEm6ahbpGNF3Pd7CB3hA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49812},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"test":"bun test","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-protocol.git","type":"git"},"_npmVersion":"10.9.2","description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.3.3"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/helios-protocol_1.0.1_1766937436398_0.17264328105882787","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aionbuilders/helios-protocol","version":"1.0.2","keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"author":{"name":"Killian Di Vincenzo"},"license":"MIT","_id":"@aionbuilders/helios-protocol@1.0.2","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios-protocol#readme","bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"dist":{"shasum":"bac9a8ee7fdcf6321f8839b87632a7ab53496efc","tarball":"https://registry.npmjs.org/@aionbuilders/helios-protocol/-/helios-protocol-1.0.2.tgz","fileCount":33,"integrity":"sha512-6Z9LwJdH02PDij0SFdrpIe7+s7cVoZyxI1L+qw7aeoowlgawaFYsz4XdWyXyq5PEVfZHo+P8/M/bz10SmR0HBQ==","signatures":[{"sig":"MEYCIQDkM4w96CwJ606zF3+62bnNa0DOMIDHKmeeN3/rmYf3pQIhAKTJIkl3b7dpJFmMY6tg9lDUVJtF7lCvPDOCLwc/r9Pb","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49764},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"test":"bun test","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-protocol.git","type":"git"},"_npmVersion":"10.9.2","description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.3.3"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/helios-protocol_1.0.2_1766940106058_0.20277780342006957","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aionbuilders/helios-protocol","version":"1.0.3","keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"author":{"name":"Killian Di Vincenzo"},"license":"MIT","_id":"@aionbuilders/helios-protocol@1.0.3","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios-protocol#readme","bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"dist":{"shasum":"9be3664af8c084f2bcd8ad55fec8ca4da4bf7e9d","tarball":"https://registry.npmjs.org/@aionbuilders/helios-protocol/-/helios-protocol-1.0.3.tgz","fileCount":34,"integrity":"sha512-zUnHOMFqWvn89YjVGk5wHOgP4HNr3gwxZHV5SdNb7votwztH7aTAXUET0JDaKN2unpzi+PoPTsGJ5Ajf0ReZPw==","signatures":[{"sig":"MEQCIAiSvzSAhiDVut687Mek1z9pQL2G/EcQQVigsOeyfWqDAiBOzxJDWYGbmFFDl0vLLAmUERqJsRNmE/SB82XzudzcSw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51720},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"test":"bun test","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 && cp src/index.d.ts dist/index.d.ts","release:stable":"npm version major && npm publish"},"_npmUser":{"name":"killiandvcz","email":"hello@killiandvcz.fr"},"repository":{"url":"git+https://github.com/aionbuilders/helios-protocol.git","type":"git"},"_npmVersion":"10.9.2","description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.3.3"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/helios-protocol_1.0.3_1766940350355_0.6807386508892141","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aionbuilders/helios-protocol","version":"1.1.0","keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"author":{"name":"Killian Di Vincenzo"},"license":"MIT","_id":"@aionbuilders/helios-protocol@1.1.0","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"homepage":"https://github.com/aionbuilders/helios-protocol#readme","bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"dist":{"shasum":"b9816b1bc049babd147c031fb512346fdd70e5e4","tarball":"https://registry.npmjs.org/@aionbuilders/helios-protocol/-/helios-protocol-1.1.0.tgz","fileCount":62,"integrity":"sha512-CaI1sImSMZT/BJLFQ6EqPcpjyb1AIA1++PYnKxC96rnKnSE9c5CQ8sydpK8JGlNWuiJN+/HxEWCsnppF8svKVQ==","signatures":[{"sig":"MEQCIDqx0ChY8Eltu0ylAF1uIi1+rk7MTteh05RyW6DRpPsYAiB8sk6k5speq4xiJvLNkWmP8C9e5qbQGdbnhF8rhHQFeA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113810},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"scripts":{"test":"bun test","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 && mkdir -p dist/types && cp -r src/types/* dist/types/","release:stable":"npm version major && npm publish"},"_npmUser":{"name":"killiandvcz","email":"hello@killiandvcz.fr"},"repository":{"url":"git+https://github.com/aionbuilders/helios-protocol.git","type":"git"},"_npmVersion":"10.9.2","description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","directories":{},"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.3.3"},"peerDependencies":{"typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/helios-protocol_1.1.0_1767186921972_0.528004751071733","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@aionbuilders/helios-protocol","version":"1.1.1","description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","type":"module","types":"dist/index.d.ts","main":"dist/index.js","module":"dist/index.js","exports":{".":{"import":"./dist/index.js","require":"./dist/index.js","types":"./dist/index.d.ts"}},"publishConfig":{"access":"public"},"scripts":{"test":"bun test","build":"bun build src/index.js --outdir dist --target node --minify","generate-types":"tsc --project ./tsc/tsconfig.json && mkdir -p dist/types && cp -r src/types/* dist/types/","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"},"keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"author":{"name":"Killian Di Vincenzo"},"repository":{"type":"git","url":"git+https://github.com/aionbuilders/helios-protocol.git"},"bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"homepage":"https://github.com/aionbuilders/helios-protocol#readme","license":"MIT","devDependencies":{"@types/bun":"latest","typescript":"^5.3.3"},"peerDependencies":{"typescript":"^5.0.0"},"_id":"@aionbuilders/helios-protocol@1.1.1","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-T3F/fRPo3OpNr7Dcz/tBLHZzGL4dADWvd95uXfWtJJcUKhyVqGGbBZR8o23Recnz87dgqRckQwlejaLP9ah/wQ==","shasum":"0c454d979e85f65388dd4b4712f95a581bbef013","tarball":"https://registry.npmjs.org/@aionbuilders/helios-protocol/-/helios-protocol-1.1.1.tgz","fileCount":62,"unpackedSize":110299,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDcblOlkYjjBp0DC3+jbwtajI1o0ctxpwqagcTwPxn0OwIhAPQBiqBTTf0oPZ+xTbSlYag6tC5sAcfz60MS3Bn2MjvN"}]},"_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-protocol_1.1.1_1768485952477_0.2325425679494375"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-28T15:53:30.068Z","modified":"2026-01-15T14:05:52.873Z","1.0.0":"2025-12-28T15:53:30.318Z","1.0.1":"2025-12-28T15:57:16.541Z","1.0.2":"2025-12-28T16:41:46.213Z","1.0.3":"2025-12-28T16:45:50.498Z","1.1.0":"2025-12-31T13:15:22.118Z","1.1.1":"2026-01-15T14:05:52.730Z"},"bugs":{"url":"https://github.com/aionbuilders/helios-protocol/issues"},"author":{"name":"Killian Di Vincenzo"},"license":"MIT","homepage":"https://github.com/aionbuilders/helios-protocol#readme","keywords":["websocket","protocol","messaging","rpc","request-response","pubsub","events","real-time","bun","runtime-agnostic"],"repository":{"type":"git","url":"git+https://github.com/aionbuilders/helios-protocol.git"},"description":"Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol with request/response and pub/sub patterns","maintainers":[{"name":"killiandvcz","email":"hello@killiandvcz.fr"}],"readme":"# @aionbuilders/helios-protocol\n\n> Core protocol implementation for Helios - a lightweight, runtime-agnostic WebSocket messaging protocol\n\n[![npm version](https://img.shields.io/npm/v/@aionbuilders/helios-protocol.svg)](https://www.npmjs.com/package/@aionbuilders/helios-protocol)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- 🚀 **Lightweight** - Zero runtime dependencies, pure JavaScript\n- 🔄 **Request/Response Pattern** - RPC-style async request/response with timeout support\n- 📡 **Pub/Sub Events** - Topic-based event system with wildcard matching\n- 🎯 **Type-Safe** - Full TypeScript definitions with JSDoc annotations\n- ⚡ **Runtime Agnostic** - Works with Bun, Node.js, Deno, and browsers\n- 🔒 **Validation** - Built-in message validation with detailed error reporting\n- 🧪 **Well Tested** - 245+ test cases covering all core functionality\n\n## Installation\n\n```bash\n# Using npm\nnpm install @aionbuilders/helios-protocol\n\n# Using bun\nbun add @aionbuilders/helios-protocol\n\n# Using yarn\nyarn add @aionbuilders/helios-protocol\n```\n\n## Quick Start\n\n```javascript\nimport { Request, Event, Parser, Serializer } from '@aionbuilders/helios-protocol';\n\n// Create a request\nconst request = Request.outgoing(\n  { userId: 123 },\n  { method: 'user.get', timeout: 5000 }\n);\n\n// Serialize for transport\nconst serialized = Serializer.serialize(request);\n\n// Parse incoming messages\nconst message = Parser.parse(serialized);\n\n// Create an event\nconst event = Event.outgoing(\n  { message: 'Hello, World!' },\n  { topic: 'chat.room.general', reliable: true }\n);\n```\n\n## API Reference\n\n### Core Components\n\n- **Messages** - Request, Response, Event message types\n- **MethodManager** - RPC method routing with middleware\n- **EventManager** - Pub/sub event system with topic subscriptions\n- **Parser/Serializer** - Message parsing and serialization\n- **Errors** - Structured error hierarchy\n- **Utils** - PatternMatcher and CapturePatternMatcher\n\n### Messages\n\nThe protocol supports three message types: **Request**, **Response**, and **Event**.\n\n#### Request\n\nRPC-style request messages with timeout support.\n\n```javascript\nimport { Request } from '@aionbuilders/helios-protocol';\n\n// Create outgoing request\nconst request = Request.outgoing(\n  { userId: 123, action: 'update' },  // payload\n  {\n    method: 'user.update',            // required\n    timeout: 5000,                    // optional (ms)\n    metadata: { trace: 'abc' },       // optional\n    peer: { service: 'user-service' } // optional routing\n  }\n);\n\n// Access properties\nconsole.log(request.method);    // 'user.update'\nconsole.log(request.timeout);   // 5000\nconsole.log(request.payload);   // { userId: 123, action: 'update' }\nconsole.log(request.id);        // auto-generated UUID\n```\n\n**Method format**: Alphanumeric characters, dots, dashes, and underscores (e.g., `user.get`, `chat-room.join`)\n\n#### Response\n\nResponse to a request message.\n\n```javascript\nimport { Response } from '@aionbuilders/helios-protocol';\n\n// Success response\nconst success = Response.outgoing(\n  { user: { id: 123, name: 'Alice' } },  // payload\n  {\n    requestId: request.id,                // required\n    status: 200                           // required\n  }\n);\n\n// Error response\nconst error = Response.outgoing(\n  null,\n  {\n    requestId: request.id,\n    status: 404,\n    error: 'User not found'\n  }\n);\n\n// Access properties\nconsole.log(success.status);     // 200\nconsole.log(success.requestId);  // matches request.id\nconsole.log(success.payload);    // { user: {...} }\nconsole.log(error.error);        // 'User not found'\n```\n\n**Status codes**: Follow HTTP conventions (200, 404, 500, etc.)\n\n#### Event\n\nPub/sub style event messages with topic routing.\n\n```javascript\nimport { Event } from '@aionbuilders/helios-protocol';\n\n// Create event\nconst event = Event.outgoing(\n  { message: 'Hello!', user: 'Alice' },  // data\n  {\n    topic: 'chat.room.general',          // required\n    reliable: true,                      // optional (default: false)\n    metadata: { priority: 'high' }       // optional\n  }\n);\n\n// Topic matching with wildcards\nEvent.matchTopic('chat.room.general', 'chat.*');        // true (single level)\nEvent.matchTopic('chat.room.general', 'chat.**');       // true (multi level)\nEvent.matchTopic('chat.room.general', 'user.*');        // false\nEvent.matchTopic('chat.room.general.dm', 'chat.*');     // false\nEvent.matchTopic('chat.room.general.dm', 'chat.**');    // true\n\n// Access properties\nconsole.log(event.topic);     // 'chat.room.general'\nconsole.log(event.reliable);  // true\nconsole.log(event.data);      // { message: 'Hello!', user: 'Alice' }\n```\n\n**Topic format**: Alphanumeric characters, dots, dashes, underscores, and wildcards (`*`, `**`)\n- `*` matches exactly one level (e.g., `chat.*` matches `chat.room` but not `chat.room.general`)\n- `**` matches one or more levels (e.g., `chat.**` matches `chat.room.general`)\n\n### MethodManager\n\nRPC method routing with middleware support and pattern matching.\n\n```javascript\nimport { MethodManager, Request } from '@aionbuilders/helios-protocol';\n\nconst methods = new MethodManager();\n\n// Register methods\nmethods.register('user.get', async (context) => {\n  // Access request data\n  const userId = context.payload.userId;\n\n  // Return response data directly\n  return { id: userId, name: 'Alice', email: 'alice@example.com' };\n});\n\nmethods.register('user.create', async (context) => {\n  // Return custom status code using context.createResponse\n  return context.createResponse({ id: 456 }, 201);\n});\n\n// Register with options\nmethods.register('user.update', async (context) => {\n  return { updated: true };\n}, { timeout: 10000 });\n\n// Handle incoming requests\nconst request = Request.outgoing({ userId: 123 }, { method: 'user.get' });\nconst response = await methods.handle(request);\n\nconsole.log(response.status);  // 200\nconsole.log(response.data);    // { id: 123, name: 'Alice', ... }\n```\n\n#### Middleware\n\nAdd cross-cutting concerns like logging, auth, validation:\n\n```javascript\n// Global middleware (runs for all methods)\nmethods.use('**', async (context, next) => {\n  console.log(`[${context.method}] Start`);\n  const result = await next();\n  console.log(`[${context.method}] Done`);\n  return result;\n});\n\n// Pattern-based middleware (runs for matching methods)\nmethods.use('user.*', async (context, next) => {\n  // Auth check for all user.* methods\n  if (!context.clientId) {\n    throw new Error('Unauthorized');\n  }\n  return await next();\n});\n\n// Specific method middleware\nmethods.use('user.delete', async (context, next) => {\n  // Audit log for user deletions\n  console.log('Deleting user:', context.payload.userId);\n  return await next();\n});\n```\n\n**Pattern matching**:\n- `user.get` - Exact match\n- `user.*` - Single level wildcard (matches `user.get`, `user.create`)\n- `user.**` - Multi-level wildcard (matches `user.get`, `user.settings.update`)\n- `**.admin` - Prefix wildcard (matches `user.admin`, `system.admin`)\n\n#### Context Data\n\nPass additional data to handlers (like client ID, auth info):\n\n```javascript\nconst response = await methods.handle(request, {\n  clientId: 'client-123',\n  userId: 456,\n  permissions: ['read', 'write']\n});\n\nmethods.register('post.create', async (context) => {\n  // Access custom context data\n  const { clientId, userId, permissions } = context;\n\n  if (!permissions.includes('write')) {\n    return context.createResponse(null, 403);\n  }\n\n  return { postId: 789, author: userId };\n});\n```\n\n#### Namespaces\n\nOrganize methods into logical groups:\n\n```javascript\n// Create namespace\nconst userMethods = methods.namespace('user');\n\n// Register methods with automatic prefix\nuserMethods.register('get', async (context) => {\n  return { id: 123 };\n});\n\nuserMethods.register('create', async (context) => {\n  return { id: 456 };\n});\n\n// Accessible as 'user.get' and 'user.create'\nconst response = await methods.handle(\n  Request.outgoing({}, { method: 'user.get' })\n);\n```\n\n### EventManager\n\nPub/sub event system with topic routing and middleware.\n\n```javascript\nimport { EventManager, Event } from '@aionbuilders/helios-protocol';\n\nconst events = new EventManager();\n\n// Subscribe to events\nevents.on('user:created', async (context) => {\n  console.log('New user:', context.data.userId);\n});\n\nevents.on('user:deleted', async (context) => {\n  console.log('User deleted:', context.data.userId);\n});\n\n// Subscribe with wildcards\nevents.on('user:*', async (context) => {\n  // Matches user:created, user:deleted, user:updated, etc.\n  console.log('User event:', context.topic);\n});\n\nevents.on('chat:**', async (context) => {\n  // Matches chat:message, chat:room:join, chat:room:leave, etc.\n  console.log('Chat event:', context.data);\n});\n\n// Dispatch events\nconst event = Event.outgoing(\n  { userId: 123, name: 'Alice' },\n  { topic: 'user:created' }\n);\n\nawait events.handle(event);\n```\n\n#### One-time Listeners\n\nSubscribe to events that auto-remove after first execution:\n\n```javascript\nevents.once('system:ready', async (context) => {\n  console.log('System initialized');\n  // This listener will be removed after first execution\n});\n```\n\n#### Event Middleware\n\nAdd cross-cutting logic to event handling:\n\n```javascript\n// Global middleware\nevents.use('**', async (context, next) => {\n  console.log(`Event: ${context.topic}`);\n  await next();\n});\n\n// Pattern-based middleware\nevents.use('user:*', async (context, next) => {\n  // Log all user events\n  console.log('User event data:', context.data);\n  await next();\n});\n\n// Specific topic middleware\nevents.use('chat:message', async (context, next) => {\n  // Filter profanity for chat messages\n  context.data.message = filterProfanity(context.data.message);\n  await next();\n});\n```\n\n#### Context Data\n\nPass additional context when handling events:\n\n```javascript\nawait events.handle(event, {\n  clientId: 'client-123',\n  server: 'ws-server-1'\n});\n\nevents.on('user:action', async (context) => {\n  // Access custom context\n  console.log('Client:', context.clientId);\n  console.log('Server:', context.server);\n});\n```\n\n#### Event Namespaces\n\nOrganize event listeners into logical groups:\n\n```javascript\n// Create namespace\nconst userEvents = events.namespace('user');\n\n// Register listeners with automatic prefix\nuserEvents.on('created', async (context) => {\n  console.log('User created');\n});\n\nuserEvents.on('deleted', async (context) => {\n  console.log('User deleted');\n});\n\n// Accessible as 'user:created' and 'user:deleted'\nawait events.handle(\n  Event.outgoing({}, { topic: 'user:created' })\n);\n```\n\n#### Management API\n\n```javascript\n// List all registered topics\nconst topics = events.topics();  // ['user:created', 'chat:message', ...]\n\n// Get listeners for a topic\nconst listeners = events.listeners('user:created');\n\n// Check if topic has listeners\nif (events.has('user:created')) {\n  console.log('Has listeners');\n}\n\n// Remove specific listener\nevents.off('user:created', myHandler);\n\n// Remove all listeners for topic\nevents.offAll('user:created');\n\n// Clear all listeners\nevents.clear();\n```\n\n### Parser & Serializer\n\n#### Serializer\n\nConvert messages to wire format (JSON or binary).\n\n```javascript\nimport { Serializer } from '@aionbuilders/helios-protocol';\n\n// Serialize to JSON (default)\nconst jsonString = Serializer.serialize(message);\n\n// Serialize to binary (Uint8Array)\nconst binary = Serializer.serialize(message, 'binary');\n\n// Check if message can be serialized\nif (Serializer.canSerialize(message)) {\n  const data = Serializer.serialize(message);\n}\n```\n\n#### Parser\n\nParse incoming data into typed message instances.\n\n```javascript\nimport { Parser } from '@aionbuilders/helios-protocol';\n\n// Parse from different formats\nconst message = Parser.parse(jsonString);           // from JSON string\nconst message = Parser.parse(uint8Array);           // from Uint8Array\nconst message = Parser.parse(arrayBuffer);          // from ArrayBuffer\n\n// Returns the correct message type\nif (message instanceof Request) {\n  console.log('Received request:', message.method);\n} else if (message instanceof Response) {\n  console.log('Received response:', message.status);\n} else if (message instanceof Event) {\n  console.log('Received event:', message.topic);\n}\n```\n\n### Errors\n\nThe protocol provides a structured error hierarchy.\n\n```javascript\nimport {\n  HeliosError,       // Base error class\n  ValidationError,   // Invalid data provided (4xx equivalent)\n  ProtocolError,     // Invalid message format (4xx equivalent)\n  TimeoutError       // Request timeout (5xx equivalent)\n} from '@aionbuilders/helios-protocol';\n\ntry {\n  const request = Request.outgoing({}, { /* missing method */ });\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.log(error.message);  // \"Request requires a method\"\n    console.log(error.details);  // [{ field: \"method\", message: \"Method is required\" }]\n  }\n}\n\ntry {\n  const message = Parser.parse(invalidData);\n} catch (error) {\n  if (error instanceof ProtocolError) {\n    console.log(error.code);     // \"INVALID_MESSAGE_TYPE\"\n    console.log(error.message);  // \"Invalid message type\"\n  }\n}\n```\n\n### Message Properties\n\nAll messages share common properties:\n\n```javascript\n// Common to all messages\nmessage.id          // Unique identifier (UUID v4)\nmessage.type        // 'request' | 'response' | 'event'\nmessage.protocol    // Protocol version (e.g., 'helios/1.0.0')\nmessage.timestamp   // Unix timestamp in milliseconds\nmessage.direction   // 'outgoing' | 'incoming'\nmessage.metadata    // Optional metadata object\nmessage.peer        // Optional peer routing { id?, service?, metadata? }\n\n// Methods\nmessage.clone()     // Create a deep copy\nmessage.validate()  // Validate message integrity\nmessage.toJSON()    // Convert to plain object\n```\n\n## Complete Export List\n\n```javascript\n// Messages\nimport {\n  Message,\n  Request,\n  Response,\n  Event\n} from '@aionbuilders/helios-protocol';\n\n// Method Management (RPC)\nimport {\n  MethodManager,\n  MethodHandler,\n  RequestContext,\n  MethodNamespaceManager\n} from '@aionbuilders/helios-protocol';\n\n// Event Management (Pub/Sub)\nimport {\n  EventManager,\n  EventListener,\n  EventContext,\n  EventNamespaceManager\n} from '@aionbuilders/helios-protocol';\n\n// Parser & Serializer\nimport {\n  Parser,\n  Serializer\n} from '@aionbuilders/helios-protocol';\n\n// Errors\nimport {\n  HeliosError,\n  ValidationError,\n  ProtocolError,\n  TimeoutError\n} from '@aionbuilders/helios-protocol';\n\n// Utils\nimport {\n  PatternMatcher,\n  CapturePatternMatcher\n} from '@aionbuilders/helios-protocol';\n```\n\n## TypeScript Support\n\nFull TypeScript definitions are included:\n\n```typescript\nimport type {\n  MessageType,\n  MessageHeaders,\n  RequestHeaders,\n  ResponseHeaders,\n  EventHeaders,\n  MessageOptions,\n  PeerRouting,\n  SerializedMessage\n} from '@aionbuilders/helios-protocol';\n\n// All classes are fully typed\nconst request = Request.outgoing<{ userId: number }>(\n  { userId: 123 },\n  { method: 'user.get' }\n);\n\n// Type-safe access\nconst userId: number = request.payload.userId;\n```\n\n## Peer Routing\n\nMessages can include peer routing information for multi-peer scenarios:\n\n```javascript\n// Route by peer ID\nconst request = Request.outgoing(\n  { action: 'ping' },\n  {\n    method: 'health.check',\n    peer: { id: 'client-abc-123' }\n  }\n);\n\n// Route by service type\nconst request = Request.outgoing(\n  { userId: 123 },\n  {\n    method: 'user.get',\n    peer: { service: 'user-service' }\n  }\n);\n\n// Route with metadata\nconst request = Request.outgoing(\n  { query: 'data' },\n  {\n    method: 'search',\n    peer: {\n      service: 'search-service',\n      metadata: { region: 'eu-west-1', version: '2.0' }\n    }\n  }\n);\n```\n\n**Note**: At least one of `id` or `service` is required when using peer routing.\n\n## Validation\n\nThe protocol uses a **two-phase validation** approach:\n\n### Outgoing (Creation) - Strict\nWhen creating messages, validation is strict and throws immediately:\n\n```javascript\n// ❌ Throws ValidationError: method is required\nRequest.outgoing({}, {});\n\n// ❌ Throws ValidationError: invalid method format\nRequest.outgoing({}, { method: 'invalid method!' });\n\n// ❌ Throws ValidationError: timeout must be positive\nRequest.outgoing({}, { method: 'test', timeout: -1 });\n```\n\n### Incoming (Parsing) - Permissive\nWhen parsing received messages, validation is permissive and only throws for critical errors:\n\n```javascript\n// Parses successfully, logs warning for unusual values\nconst message = Parser.parse(slightlyInvalidData);\n```\n\n### Manual Validation\nYou can manually validate a message at any time:\n\n```javascript\ntry {\n  message.validate();\n  console.log('Message is valid');\n} catch (error) {\n  console.error('Validation failed:', error.details);\n}\n```\n\n## Protocol Version\n\nCurrent protocol version: **helios/1.0.0**\n\nThe protocol follows semantic versioning:\n- **Major version** changes indicate breaking protocol changes\n- **Minor version** changes add backward-compatible features\n- **Patch version** changes are bug fixes\n\nMessages with incompatible major versions are rejected automatically.\n\n## Examples\n\n### Full Request/Response Cycle\n\n```javascript\nimport { Request, Response, Parser, Serializer } from '@aionbuilders/helios-protocol';\n\n// Client side: create and send request\nconst request = Request.outgoing(\n  { userId: 123 },\n  { method: 'user.get', timeout: 5000 }\n);\n\nconst requestData = Serializer.serialize(request);\n// Send requestData over WebSocket...\n\n// Server side: receive and parse request\nconst receivedRequest = Parser.parse(requestData);\n\n// Process request and create response\nconst response = Response.outgoing(\n  { id: 123, name: 'Alice', email: 'alice@example.com' },\n  { requestId: receivedRequest.id, status: 200 }\n);\n\nconst responseData = Serializer.serialize(response);\n// Send responseData back over WebSocket...\n\n// Client side: receive response\nconst receivedResponse = Parser.parse(responseData);\nconsole.log(receivedResponse.payload); // { id: 123, name: 'Alice', ... }\n```\n\n### Pub/Sub with Events\n\n```javascript\nimport { Event, Parser, Serializer } from '@aionbuilders/helios-protocol';\n\n// Publisher: create and broadcast event\nconst event = Event.outgoing(\n  { message: 'New user joined!', user: 'Bob' },\n  { topic: 'chat.room.lobby', reliable: true }\n);\n\nconst eventData = Serializer.serialize(event);\n// Broadcast eventData to all subscribers...\n\n// Subscriber: receive and handle event\nconst receivedEvent = Parser.parse(eventData);\n\nif (receivedEvent instanceof Event) {\n  // Check topic match\n  if (Event.matchTopic(receivedEvent.topic, 'chat.**')) {\n    console.log('Chat event:', receivedEvent.data);\n  }\n}\n```\n\n## Runtime Compatibility\n\nThis protocol package is **runtime agnostic** and works with:\n\n- ✅ **Bun** (recommended, optimized for Bun runtime)\n- ✅ **Node.js** (v16+)\n- ✅ **Deno**\n- ✅ **Browsers** (modern browsers with ES2020+ support)\n\n## Related Packages\n\n- **[@aionbuilders/helios](https://github.com/aionbuilders/helios)** - Server implementation (Bun)\n- **[@aionbuilders/starling](https://github.com/aionbuilders/starling)** - Client implementation (browser + Bun)\n\n## Contributing\n\nContributions are welcome! Please read [DEVELOPMENT.md](./DEVELOPMENT.md) for development guidelines and architectural decisions.\n\n## License\n\nMIT © Killian Di Vincenzo (AION Builders)\n\n---\n\n**Made with ❤️ by [Killian Di Vincenzo](https://github.com/killiandvcz) with [AION Builders](https://github.com/aionbuilders)**\n","readmeFilename":"README.md"}