@ifesol/ipc-framework-js

v1.0.1

Published

7 months ago

Efficient Inter-Process Communication Framework for JavaScript/TypeScript - Frontend & Backend

Downloads

0High
0Medium
0Low

ifesol

ipc inter-process-communication websocket real-time messaging pubsub frontend backend typescript javascript framework

IPC Framework JS

A powerful, TypeScript-first Inter-Process Communication framework for JavaScript/TypeScript applications. Works seamlessly in both Node.js (backend) and browser (frontend) environments using WebSockets.

🚀 Features

🌐 Universal: Works in both Node.js and browser environments
📝 TypeScript First: Full TypeScript support with comprehensive type definitions
🔄 Real-time: WebSocket-based communication for instant message delivery
🏗️ Hierarchical: Organized by applications → channels → messages
📡 Multiple Message Types: Request/Response, Pub/Sub, Notifications
🔗 Auto-reconnection: Built-in reconnection logic with exponential backoff
💗 Heartbeat: Keep-alive mechanism to maintain connections
🎯 Type-safe: Fully typed APIs for better developer experience
📦 Dual Package: Separate builds for Node.js and browsers

📦 Installation

npm install ipc-framework-js

For Node.js usage, you'll also need the WebSocket library:

npm install ws
npm install --save-dev @types/ws  # If using TypeScript

🎯 Quick Start

Server (Node.js)

import { IPCServer, MessageType } from 'ipc-framework-js';

// Create server
const server = new IPCServer({
  host: 'localhost',
  port: 8888,
  maxConnections: 100
});

// Create application and channels
const chatApp = server.createApplication('chat_app', 'Chat Application');
const generalChannel = chatApp.createChannel('general');

// Set up message handler
generalChannel.setHandler(MessageType.REQUEST, (message) => {
  console.log('Received message:', message.payload);
  
  // Broadcast to all subscribers
  server.handlePublish(message, generalChannel);
});

// Start server
await server.start();
console.log('🚀 IPC Server started on ws://localhost:8888');

Client (Node.js)

import { IPCClient, MessageType } from 'ipc-framework-js';

// Create client
const client = new IPCClient('chat_app', {
  host: 'localhost',
  port: 8888,
  reconnectAttempts: 5
});

// Connect
await client.connect();

// Subscribe to messages
client.subscribe('general', (message) => {
  console.log('Received:', message.payload);
});

// Send message
client.request('general', {
  username: 'john',
  text: 'Hello World!'
});

Client (Browser)

<!DOCTYPE html>
<html>
<head>
  <title>IPC Client</title>
  <script src="./node_modules/ipc-framework-js/dist/browser/index.js"></script>
</head>
<body>
  <script>
    // Create client
    const client = new IPCFramework.IPCClient('chat_app', {
      host: 'localhost',
      port: 8888
    });

    // Connect and use
    client.connect().then(() => {
      console.log('Connected!');
      
      // Subscribe to messages
      client.subscribe('general', (message) => {
        console.log('Received:', message.payload);
      });
      
      // Send message
      client.request('general', {
        username: 'browser_user',
        text: 'Hello from browser!'
      });
    });
  </script>
</body>
</html>

📚 API Reference

Server API

`IPCServer`

class IPCServer {
  constructor(options?: IServerOptions)
  
  // Server lifecycle
  async start(): Promise<void>
  async stop(): Promise<void>
  
  // Application management
  createApplication(appId: string, name?: string): Application
  getApplication(appId: string): Application | undefined
  removeApplication(appId: string): boolean
  
  // Statistics
  getStats(): IServerStats
  listApplications(): Map<string, any>
}

Server Options

interface IServerOptions {
  host?: string;          // Default: 'localhost'
  port?: number;          // Default: 8888
  maxConnections?: number; // Default: 100
  heartbeatInterval?: number; // Default: 30000ms
}

Client API

`IPCClient`

class IPCClient {
  constructor(appId: string, options?: IClientOptions)
  
  // Connection management
  async connect(): Promise<boolean>
  disconnect(): void
  isConnected(): boolean
  
  // Messaging
  subscribe(channelId: string, handler?: MessageHandler): boolean
  unsubscribe(channelId: string): boolean
  request(channelId: string, data: any): string
  notify(channelId: string, data: any): string
  publish(channelId: string, data: any): string
  
  // Advanced messaging
  async sendRequest(channelId: string, data: any, timeout?: number): Promise<Message | null>
  sendRequestAsync(channelId: string, data: any, callback: Function): string
  
  // Utilities
  async ping(timeout?: number): Promise<boolean>
  getConnectionInfo(): IConnectionInfo
  
  // Event handlers
  onConnected(handler: () => void): void
  onDisconnected(handler: () => void): void
  onError(handler: (error: Error) => void): void
}

Client Options

interface IClientOptions {
  host?: string;              // Default: 'localhost'
  port?: number;              // Default: 8888
  connectionTimeout?: number;  // Default: 10000ms
  reconnectAttempts?: number;  // Default: 5
  reconnectDelay?: number;     // Default: 1000ms
  heartbeatInterval?: number;  // Default: 30000ms
}

Message Types

enum MessageType {
  REQUEST = 'request',         // Request-response pattern
  RESPONSE = 'response',       // Response to a request
  NOTIFICATION = 'notification', // One-way message
  SUBSCRIBE = 'subscribe',     // Subscribe to channel
  UNSUBSCRIBE = 'unsubscribe', // Unsubscribe from channel
  PUBLISH = 'publish'          // Publish to subscribers
}

Core Classes

`Message`

class Message {
  readonly messageId: string;
  readonly appId: string;
  readonly channelId: string;
  readonly messageType: MessageType;
  readonly payload: any;
  readonly timestamp: number;
  readonly replyTo?: string;
  
  // Serialization
  toJSON(): string
  toObject(): IMessage
  
  // Static methods
  static fromJSON(json: string): Message
  static fromObject(data: IMessage): Message
  
  // Utility methods
  createResponse(payload: any): Message
  isResponse(): boolean
  isRequest(): boolean
  // ... more utility methods
}

`Application`

class Application {
  readonly appId: string;
  readonly name: string;
  readonly createdAt: number;
  
  // Channel management
  createChannel(channelId: string): Channel
  getChannel(channelId: string): Channel | undefined
  removeChannel(channelId: string): boolean
  listChannels(): string[]
  
  // Statistics
  getStats(): IApplicationStats
  getTotalConnectionCount(): number
}

`Channel`

class Channel {
  readonly channelId: string;
  readonly appId: string;
  readonly createdAt: number;
  
  // Subscriber management
  addSubscriber(connectionId: string): void
  removeSubscriber(connectionId: string): boolean
  getSubscribers(): string[]
  
  // Message handling
  setHandler(messageType: MessageType, handler: MessageHandler): void
  removeHandler(messageType: MessageType): boolean
  executeHandler(message: Message): Promise<boolean>
}

🏗️ Architecture

The IPC Framework follows a hierarchical structure:

Server
├── Application (chat_app)
│   ├── Channel (general)
│   ├── Channel (tech_talk)
│   └── Channel (random)
├── Application (file_share)
│   ├── Channel (upload)
│   └── Channel (download)
└── Application (monitoring)
    ├── Channel (metrics)
    └── Channel (alerts)

Message Flow

Client connects to server with an appId
Client subscribes to channels within that application
Messages are routed based on appId → channelId
Handlers process messages based on message type
Responses/broadcasts are sent back to relevant subscribers

🛠️ Development

Building

# Install dependencies
npm install

# Build for all environments
npm run build

# Build for specific environments
npm run build:node      # Node.js build
npm run build:browser   # Browser build
npm run build:types     # TypeScript declarations

Development Mode

# Watch mode for development
npm run dev

# Run examples
npm run example:server    # Start example server
npm run example:chat     # Start chat client
npm run example:browser  # Start browser demo

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

📋 Examples

Chat Application

Complete chat application with multiple channels:

Server: examples/node/server.js
Client: examples/node/chat-client.js
Browser: examples/browser/index.html

File Sharing

File upload/download with progress tracking:

# Terminal 1: Start server
npm run example:server

# Terminal 2: Start file client
node examples/node/file-client.js

System Monitoring

Real-time metrics and alerting:

# Start monitoring client
node examples/node/monitoring-client.js

🌐 Browser Usage

ES Modules (Modern)

<script type="module">
  import { IPCClient } from './node_modules/ipc-framework-js/dist/browser/index.esm.js';
  
  const client = new IPCClient('my_app');
  // Use client...
</script>

UMD (Universal)

<script src="./node_modules/ipc-framework-js/dist/browser/index.js"></script>
<script>
  const client = new IPCFramework.IPCClient('my_app');
  // Use client...
</script>

With Bundlers

Works with Webpack, Rollup, Vite, etc.:

import { IPCClient } from 'ipc-framework-js';

// Bundler will automatically use browser build
const client = new IPCClient('my_app');

🔧 Configuration

TypeScript Configuration

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Environment Detection

The library automatically detects the environment and uses appropriate WebSocket implementation:

Node.js: Uses ws package
Browser: Uses native WebSocket

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature-name
Commit changes: git commit -am 'Add feature'
Push to branch: git push origin feature-name
Submit pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

🙏 Acknowledgments

Inspired by modern real-time communication needs and built with developer experience in mind.