{"_rev":"3-8c3305fdc78f02af07b10a3bb2760636","time":{"created":"2026-01-26T11:09:45.629Z","modified":"2026-01-26T11:09:46.379Z","1.0.0":"2026-01-26T00:47:56.234Z","1.0.1":"2026-01-26T11:09:45.855Z"},"_id":"@caeligo/nexus-orchestrator","name":"@caeligo/nexus-orchestrator","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@caeligo/nexus-orchestrator","version":"1.0.1","description":"The unified event orchestrator","license":"MIT","author":{"name":"Moaaz KHASSAWNEH","email":"moath.o.h.k@gmail.com","url":"https://github.com/MoaazKHASSAWNEH/"},"repository":{"type":"git","url":"git+https://github.com/MoaazKHASSAWNEH/nexus-orchestrator.git"},"bugs":{"url":"https://github.com/MoaazKHASSAWNEH/nexus-orchestrator/issues"},"homepage":"https://MoaazKHASSAWNEH.github.io/nexus-orchestrator/","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"dev":"tsup --watch","build":"tsup","test":"vitest","lint":"biome check src","format":"biome check --write src","release":"changeset publish","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs"},"devDependencies":{"@biomejs/biome":"^2.3.12","@changesets/cli":"^2.29.8","mermaid":"^11.12.2","tsup":"^8.5.1","typescript":"^5.9.3","vitepress":"^1.6.4","vitepress-plugin-mermaid":"^2.0.17","vitest":"^4.0.18","vue":"^3.5.27"},"_id":"@caeligo/nexus-orchestrator@1.0.1","gitHead":"6f5557e955c911e1713261335770a0373531f813","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-vrDSto0X/wJTUX3Cl6epXGpYb+GPu837jrI/9USjE7XZNoZPJKjO9hR3ZhK+lJPp0SlWN07wsaNUy3X40mYrmA==","shasum":"d64cc153a6d645734e44a66a06a20dcc03e8b9b8","tarball":"https://registry.npmjs.org/@caeligo/nexus-orchestrator/-/nexus-orchestrator-1.0.1.tgz","fileCount":10,"unpackedSize":124384,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC3uDJq3JIj5DelUCH4FTyBuKCLl1vBv/MRyZr4AVPfkwIhAOei6VDMDaD+HfESX6tCeRMvKxR/yvY3NnHa5G3Ztsnn"}]},"_npmUser":{"name":"momokh1995","email":"moath.o.h.k@gmail.com"},"directories":{},"maintainers":[{"name":"momokh1995","email":"moath.o.h.k@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/nexus-orchestrator_1.0.1_1769425785710_0.8107930626412942"},"_hasShrinkwrap":false}},"maintainers":[{"name":"momokh1995","email":"moath.o.h.k@gmail.com"}],"description":"The unified event orchestrator","homepage":"https://MoaazKHASSAWNEH.github.io/nexus-orchestrator/","repository":{"type":"git","url":"git+https://github.com/MoaazKHASSAWNEH/nexus-orchestrator.git"},"author":{"name":"Moaaz KHASSAWNEH","email":"moath.o.h.k@gmail.com","url":"https://github.com/MoaazKHASSAWNEH/"},"bugs":{"url":"https://github.com/MoaazKHASSAWNEH/nexus-orchestrator/issues"},"license":"MIT","readme":"
\r\n\r\n# โšก Nexus Orchestrator\r\n\r\n**The Ultimate Event Bus with AI & Resilience**\r\n\r\n[![NPM Version](https://img.shields.io/npm/v/@caeligo/nexus-orchestrator?style=flat-square&color=blue)](https://www.npmjs.com/package/@caeligo/nexus-orchestrator)\r\n[![License](https://img.shields.io/npm/l/@caeligo/nexus-orchestrator?style=flat-square&color=green)](./LICENSE)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\r\n[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@caeligo/nexus-orchestrator?style=flat-square)](https://bundlephobia.com/package/@caeligo/nexus-orchestrator)\r\n[![Documentation](https://img.shields.io/badge/docs-view-blue?style=flat-square)](./docs)\r\n\r\n[Documentation](./docs) โ€ข [Getting Started](#-quick-start) โ€ข [Examples](#-examples) โ€ข [API Reference](./docs/api)\r\n\r\n
\r\n\r\n---\r\n\r\n## ๐ŸŽฏ Overview\r\n\r\n**Nexus Orchestrator** is a next-generation event bus engineered for production-grade applications. It transcends traditional pub/sub patterns by introducing **AI-powered prediction**, **priority-based execution**, **built-in resilience**, and **cross-platform communication**.\r\n\r\n### Why Nexus?\r\n\r\nTraditional event buses (`EventEmitter`, `Mitt`) work for simple cases but fall short in complex, real-world applications:\r\n\r\n```typescript\r\n// โŒ Traditional Event Bus Problems\r\neventBus.on('api:fetch', handler); // What if it fails? No retries.\r\neventBus.emit('analytics', data); // Blocks critical UI updates\r\neventBus.emit('chat:message', msg); // Lost if network fails\r\n// No request/reply, no state, no intelligence\r\n```\r\n\r\n```typescript\r\n// โœ… Nexus Orchestrator Solution\r\nconst bus = new Nexus({\r\n replayMemory: 50, // History for late subscribers\r\n predictionThreshold: 0.7, // AI learns user patterns\r\n debug: true // Redux DevTools integration\r\n});\r\n\r\n// Request/Reply built-in\r\nconst user = await bus.request('user:fetch', { id: 123 });\r\n\r\n// Priority scheduling prevents UI freezes\r\nbus.emit('analytics:track', data, { priority: 'background' });\r\n\r\n// Automatic retries with fallback\r\nbus.on('api:call', handler, { attempts: 3, backoff: 1000 });\r\n```\r\n\r\n---\r\n\r\n## โœจ Key Features\r\n\r\n\r\n\r\n\r\n\r\n\r\n
\r\n\r\n### ๐Ÿง  **AI Event Prediction**\r\nMarkov Chain learning predicts user behavior and prefetches resources intelligently.\r\n\r\n### ๐ŸŽฏ **Priority Lanes**\r\nExecute events at `critical`, `high`, `normal`, or `background` priority to prevent UI freezes.\r\n\r\n### ๐Ÿ”„ **RPC Pattern**\r\nBuilt-in request/reply with Promise-based async communication.\r\n\r\n\r\n\r\n### ๐Ÿ›ก๏ธ **Circuit Breakers**\r\nAutomatic retries with exponential backoff and fallback handlers.\r\n\r\n### ๐Ÿต **Chaos Monkey**\r\nTest resilience by simulating packet loss and latency in development.\r\n\r\n### ๐ŸŒ **Teleportation**\r\nBridge client/server seamlessly with WebSocket integration.\r\n\r\n
\r\n\r\n**Plus:** Data Cursors, Cross-Tab Sync, Middleware Pipelines, Redux DevTools, Mermaid Diagrams, and more.\r\n\r\n---\r\n\r\n## ๐Ÿ“ฆ Installation\r\n\r\n```bash\r\nnpm install @caeligo/nexus-orchestrator\r\n```\r\n\r\n**Requirements:** Node.js 16+ or modern browsers (ES2020+)\r\n\r\n---\r\n\r\n## ๐Ÿš€ Quick Start\r\n\r\n### 1. Create a Type-Safe Instance\r\n\r\n```typescript\r\nimport { Nexus } from '@caeligo/nexus-orchestrator';\r\n\r\n// Define your event contract\r\ninterface AppEvents {\r\n 'user:login': { username: string; timestamp: number };\r\n 'user:logout': { userId: string };\r\n 'cart:add': { productId: number; quantity: number };\r\n 'api:error': { message: string; code: number };\r\n}\r\n\r\nconst bus = new Nexus({\r\n replayMemory: 50, // Keep last 50 events\r\n debug: true, // Enable DevTools\r\n predictionThreshold: 0.7 // Enable AI predictions at 70% confidence\r\n});\r\n```\r\n\r\n### 2. Subscribe & Emit\r\n\r\n```typescript\r\n// Subscribe to events\r\nbus.on('user:login', (payload) => {\r\n console.log(`Welcome, ${payload.username}!`);\r\n});\r\n\r\n// Emit events\r\nbus.emit('user:login', { \r\n username: 'alice', \r\n timestamp: Date.now() \r\n});\r\n```\r\n\r\n### 3. Request/Reply Pattern\r\n\r\n```typescript\r\n// Server-side handler\r\nbus.on('user:fetch', async (payload) => {\r\n const user = await database.getUser(payload.id);\r\n bus.reply(payload, user);\r\n});\r\n\r\n// Client-side request\r\nconst user = await bus.request('user:fetch', { id: 123 });\r\nconsole.log(user.name); // Type-safe!\r\n```\r\n\r\n---\r\n\r\n## ๐Ÿ’ก Examples\r\n\r\n### Priority-Based Execution\r\n\r\n```typescript\r\n// Critical: Runs immediately (blocks thread)\r\nbus.emit('ui:button-disable', { id: 'submit' }, { priority: 'critical' });\r\n\r\n// High: Runs in microtask (important but non-blocking)\r\nbus.emit('api:fetch', data, { priority: 'high' });\r\n\r\n// Normal: Runs next tick (default)\r\nbus.emit('page:update', data);\r\n\r\n// Background: Runs when idle (analytics, logging)\r\nbus.emit('analytics:track', data, { priority: 'background' });\r\n```\r\n\r\n### State Management with Cursors\r\n\r\n```typescript\r\n// Create a cursor (like a reactive variable)\r\nconst authCursor = bus.cursor('auth:state', { loggedIn: false });\r\n\r\n// Read synchronously anywhere\r\nif (authCursor.value.loggedIn) {\r\n renderDashboard();\r\n}\r\n\r\n// Updates automatically on emit\r\nbus.emit('auth:state', { loggedIn: true, user: 'alice' });\r\nconsole.log(authCursor.value); // { loggedIn: true, user: 'alice' }\r\n```\r\n\r\n### Resilience with Circuit Breakers\r\n\r\n```typescript\r\nbus.on('payment:process', processPayment, {\r\n attempts: 3, // Retry 3 times\r\n backoff: 2000, // Wait 2s between retries\r\n fallback: (error) => {\r\n // Called after all retries fail\r\n showOfflineMode();\r\n logCriticalError(error);\r\n }\r\n});\r\n```\r\n\r\n### AI-Powered Prefetching\r\n\r\n```typescript\r\nconst bus = new Nexus({ predictionThreshold: 0.75 });\r\n\r\n// Listen for AI predictions\r\nbus.on('prediction:product:add-to-cart', (data) => {\r\n console.log(`User likely to add to cart (${data.probability * 100}%)`);\r\n \r\n // Prefetch inventory and pricing\r\n prefetchProductData(data.originalPayload.productId);\r\n});\r\n\r\n// Nexus learns patterns automatically\r\nbus.emit('product:view', { productId: 123 });\r\n// After learning, emits: 'prediction:product:add-to-cart'\r\n```\r\n\r\n### Cross-Platform Communication\r\n\r\n```typescript\r\n// Client\r\nconst ws = new WebSocket('ws://localhost:3000');\r\n\r\nconst bus = new Nexus({\r\n teleport: (event, payload) => {\r\n ws.send(JSON.stringify({ event, payload }));\r\n }\r\n});\r\n\r\nws.onmessage = (msg) => {\r\n const { event, payload } = JSON.parse(msg.data);\r\n bus.feed(event, payload); // Inject into bus\r\n};\r\n\r\n// Events automatically sync across network!\r\nbus.emit('chat:message', { text: 'Hello!' });\r\n```\r\n\r\n### Data Transformation Pipelines\r\n\r\n```typescript\r\nimport { filter, map, debounce, logger } from '@caeligo/nexus-orchestrator';\r\n\r\nbus.pipe(\r\n 'search:input',\r\n debounce(300), // Wait for typing to stop\r\n filter(data => data.query.length >= 3), // Minimum 3 chars\r\n map(data => ({ ...data, normalized: data.query.toLowerCase() })),\r\n logger('search'), // Debug logging\r\n async (data) => {\r\n const results = await searchAPI(data.normalized);\r\n bus.emit('search:results', results);\r\n }\r\n);\r\n```\r\n\r\n---\r\n\r\n## ๐Ÿ“š Documentation\r\n\r\nComprehensive documentation is available in the [`docs/`](./docs) directory:\r\n\r\n- **[Getting Started](./docs/guide/getting-started.md)** - Installation and basic concepts\r\n- **[Architecture Overview](./docs/guide/architecture.md)** - Internal design and data flow\r\n- **[RPC Pattern](./docs/guide/rpc-pattern.md)** - Request/Reply communication\r\n- **[Priority Lanes](./docs/guide/priority-lanes.md)** - Performance optimization\r\n- **[Cursors & State](./docs/guide/cursors-state.md)** - State management\r\n- **[Resilience](./docs/guide/resilience.md)** - Circuit breakers and retries\r\n- **[Chaos Monkey](./docs/guide/chaos-monkey.md)** - Failure testing\r\n- **[AI Prediction](./docs/guide/ai-prediction.md)** - Event prediction\r\n- **[Teleportation](./docs/guide/teleportation.md)** - Network bridging\r\n- **[Pipes & Operators](./docs/guide/pipes-utils.md)** - Data transformation\r\n- **[API Reference](./docs/api/index.md)** - Complete API documentation\r\n\r\n### View Documentation Locally\r\n\r\n```bash\r\nnpm run docs:dev\r\n```\r\n\r\nVisit `https://MoaazKHASSAWNEH.github.io/nexus-orchestrator/` for the full interactive documentation.\r\n\r\n---\r\n\r\n## ๐ŸŽฏ Use Cases\r\n\r\nNexus Orchestrator is ideal for:\r\n\r\n- โœ… **Complex SPAs** (React, Vue, Angular) with intricate state management\r\n- โœ… **Real-time applications** (Chat, collaborative tools, dashboards)\r\n- โœ… **E-commerce platforms** requiring predictive prefetching\r\n- โœ… **Microservices** needing event-driven communication\r\n- โœ… **Offline-first apps** with resilience requirements\r\n- โœ… **Large codebases** benefiting from architectural documentation\r\n\r\n---\r\n\r\n## โš–๏ธ Comparison\r\n\r\n| Feature | Nexus | EventEmitter | Mitt | RxJS |\r\n|---------|-------|--------------|------|------|\r\n| **TypeScript Support** | โœ… Full | โš ๏ธ Partial | โœ… Full | โœ… Full |\r\n| **Request/Reply** | โœ… Built-in | โŒ | โŒ | โŒ |\r\n| **Priority Lanes** | โœ… 4 Levels | โŒ | โŒ | โš ๏ธ Schedulers |\r\n| **AI Prediction** | โœ… Markov Chain | โŒ | โŒ | โŒ |\r\n| **State Cursors** | โœ… Sync Access | โŒ | โŒ | โœ… BehaviorSubject |\r\n| **Circuit Breakers** | โœ… Automatic | โŒ | โŒ | โš ๏ธ Manual |\r\n| **Chaos Testing** | โœ… Built-in | โŒ | โŒ | โŒ |\r\n| **Cross-Tab Sync** | โœ… BroadcastChannel | โŒ | โŒ | โŒ |\r\n| **Bundle Size** | **~3KB** | Built-in | ~200B | ~20KB |\r\n| **Learning Curve** | **Low** | Low | Low | **High** |\r\n| **Production Ready** | โœ… | โœ… | โœ… | โœ… |\r\n\r\n---\r\n\r\n## ๐Ÿ—๏ธ Architecture\r\n\r\n```mermaid\r\ngraph TB\r\n subgraph \"Nexus Core\"\r\n A[Emit Event] --> B{Priority Scheduler}\r\n B -->|Critical| C[Immediate Sync]\r\n B -->|High| D[Microtask]\r\n B -->|Normal| E[Event Loop]\r\n B -->|Background| F[Idle Callback]\r\n end\r\n \r\n subgraph \"Intelligence\"\r\n G[Markov Chain] --> H[Prediction Engine]\r\n H --> I[Prefetch Events]\r\n end\r\n \r\n subgraph \"Networking\"\r\n J[Teleport Bridge] --> K[WebSocket]\r\n L[BroadcastChannel] --> M[Cross-Tab Sync]\r\n end\r\n \r\n subgraph \"Resilience\"\r\n N[Circuit Breaker] --> O[Retry Logic]\r\n P[Chaos Monkey] --> Q[Failure Simulation]\r\n end\r\n \r\n A --> G\r\n A --> J\r\n C --> R[Listeners]\r\n D --> R\r\n E --> R\r\n F --> R\r\n R --> N\r\n```\r\n\r\n---\r\n\r\n## ๐Ÿงช Testing\r\n\r\n```bash\r\n# Run tests\r\nnpm test\r\n\r\n# Run tests with coverage\r\nnpm run test:coverage\r\n\r\n# Lint code\r\nnpm run lint\r\n\r\n# Format code\r\nnpm run format\r\n```\r\n\r\n---\r\n\r\n## [Learn more in the documentation](https://MoaazKHASSAWNEH.github.io/nexus-orchestrator/)\r\n\r\n## ๐Ÿค Contributing\r\n\r\nContributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) before submitting PRs.\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n---\r\n\r\n## ๐Ÿ“ License\r\n\r\nMIT ยฉ 2026 [Moaaz KHASSAWNEH](https://github.com/MoaazKHASSAWNEH)\r\n\r\n---\r\n\r\n## ๐Ÿ”— Links\r\n\r\n- **[NPM Package](https://www.npmjs.com/package/@caeligo/nexus-orchestrator)**\r\n- **[GitHub Repository](https://github.com/MoaazKHASSAWNEH/nexus-orchestrator)**\r\n- **[Documentation](./docs)**\r\n- **[Issue Tracker](https://github.com/MoaazKHASSAWNEH/nexus-orchestrator/issues)**\r\n- **[Changelog](./CHANGELOG.md)**\r\n\r\n---\r\n\r\n
\r\n\r\n**Built with โค๏ธ by [Moaaz KHASSAWNEH](https://github.com/MoaazKHASSAWNEH)**\r\n\r\nIf you find Nexus Orchestrator useful, please consider giving it a โญ on [GitHub](https://github.com/MoaazKHASSAWNEH/nexus-orchestrator)!\r\n\r\n
","readmeFilename":"README.md"}