OpenSocket JavaScript SDK

🔌 Vendor-agnostic real-time communication for JavaScript/TypeScript

Overview

OpenSocket provides a unified API for real-time communication across multiple providers (Pusher, Ably, Socket.io, etc.), allowing you to switch providers without changing your application code.

🚀 Quick Start

npm install @open-socket/core

import { createOpenSocket } from '@open-socket/core';
import { PusherProvider } from '@open-socket/provider-pusher';

// Initialize with your chosen provider
const socket = await createOpenSocket({
  provider: new PusherProvider({
    key: 'your-pusher-key',
    cluster: 'us2',
  }),
});

// Connect to the provider
await socket.connect();

// Subscribe to a channel
const channel = socket.channel('my-channel');

// Listen for messages
await channel.subscribe('my-event', message => {
  console.log('Received:', message.data);
});

// Publish messages
await channel.publish('my-event', {
  text: 'Hello, real-time world!',
});

📦 Packages

This monorepo contains the following packages:

Package	Description	Version
@open-socket/core	Core abstractions and interfaces
@open-socket/testing-utils	Testing utilities and mock provider

Provider Packages (Coming Soon)

• @open-socket/provider-pusher - Pusher adapter
• @open-socket/provider-ably - Ably adapter
• @open-socket/provider-socketio - Socket.io adapter

Framework Packages (Coming Soon)

• @open-socket/react - React hooks and components
• @open-socket/vue - Vue composables
• @open-socket/angular - Angular services

✨ Features

• Vendor Agnostic: Switch between providers with a single config change
• Type Safe: Full TypeScript support with strict typing
• Lightweight: Core package <10KB gzipped
• Extensible: Middleware system for customization
• Well Tested: Comprehensive test suite for all providers
• Modern: ES modules, tree-shaking, async/await

🔄 Switching Providers

One of the key benefits of OpenSocket is the ability to switch providers easily:

// Using Pusher
const socket = await createOpenSocket({
  provider: new PusherProvider({ key: 'pusher-key' }),
});

// Switch to Ably (same API!)
const socket = await createOpenSocket({
  provider: new AblyProvider({ key: 'ably-key' }),
});

// Switch to Socket.io (same API!)
const socket = await createOpenSocket({
  provider: new SocketIOProvider({ url: 'http://localhost:3000' }),
});

🧪 Testing

OpenSocket includes comprehensive testing utilities:

import { MockProvider, createProviderTestSuite } from '@open-socket/testing-utils';

// Use the mock provider for testing
const mockProvider = new MockProvider();
const socket = await createOpenSocket({ provider: mockProvider });

// Simulate events
mockProvider.simulateMessage('channel', 'event', { test: true });

// Run the standard test suite against your provider
createProviderTestSuite(() => new YourProvider(), 'YourProvider');

🏗️ Architecture

OpenSocket uses a layered architecture:

Application Code
     ↓
OpenSocket API (unified interface)
     ↓
Provider Interface (abstraction)
     ↓
Provider Adapter (implementation)
     ↓
Native Provider SDK

🛠️ Development

This project uses pnpm workspaces and Turborepo:

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run in development mode
pnpm dev

# Lint and format
pnpm lint
pnpm format

📊 Provider Feature Matrix

Feature	Pusher	Ably	Socket.io
Public Channels	✅	✅	✅
Private Channels	✅	✅	✅
Presence	✅	✅	✅
Message History	❌	✅	⚠️
Binary Data	❌	✅	✅
Acknowledgments	❌	✅	✅

🔌 Middleware

Extend OpenSocket with custom middleware:

const loggingMiddleware = {
  name: 'logging',
  pre: async context => {
    console.log('Before:', context.operation);
  },
  post: async context => {
    console.log('After:', context.operation);
  },
  error: async (error, context) => {
    console.error('Error:', error);
  },
};

socket.use(loggingMiddleware);

📚 Documentation

• Getting Started Guide
• API Reference
• Provider Guides
• Migration Guide

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

OpenSocket is inspired by:

• OpenFeature for the vendor-agnostic approach
• The real-time communication community

🔗 Links

• Website
• GitHub
• NPM
• Discord

---

Built with ❤️ by the OpenSocket community