A lightweight TypeScript wrapper around the Ably Realtime and REST APIs, supporting both server-side (Node.js) and client-side (browser) usage.
npm install @midtownhi/ablyA lightweight TypeScript wrapper around the Ably Realtime and REST APIs, supporting both server-side (Node.js) and client-side (browser) usage.
``bash`
npm install @midtownhi/ablyor
yarn add @midtownhi/ably
- Simplified API for working with Ably's realtime pub/sub messaging
- TypeScript support with full type definitions
- Channel management for real-time communication
- Support for both Realtime and REST APIs
- Works in both Node.js and browser environments
- Single import with named exports for different implementations
#### Server-Side (Node.js)
`typescript
// Import directly from the package
import ably from '@midtownhi/ably';
// Or use the named export
import { ably_node } from '@midtownhi/ably';
// Subscribe to a channel
const channel = ably.subscribe('my-channel');
// Or with named export
const channel = ably_node.subscribe('my-channel');
// Listen for events on that channel
channel.on('my-event', (message) => {
console.log('Received message:', message.data);
});
`
You can also create custom instances:
`typescript
import { AblyService, NodeConfig } from '@midtownhi/ably';
// Create custom instance
const service = new AblyService({
key: 'your-api-key',
// OR use custom environment object
environment: { ABLY_API_KEY: 'your-api-key' }
} as NodeConfig);
// Use the custom instance
const channel = service.subscribe('my-channel');
`
#### Client-Side (Browser)
`typescript
// Import browser implementation
import { ably_browser, BrowserConfig } from '@midtownhi/ably';
// Create Ably service for realtime using token auth (recommended for production)
const realtimeService = ably_browser.createService({
authUrl: '/api/createAblyToken',
authMethod: 'POST',
authHeaders: { 'Content-Type': 'application/json' },
clientId: 'user123'
});
// OR using API key (for development only)
const devService = ably_browser.createService({
key: 'your-api-key'
});
// Subscribe to a channel
const channel = realtimeService.subscribe('my-channel');
// Listen for events
channel.on('my-event', (message) => {
console.log('Received message:', message.data);
});
`
`typescript
// Import REST client
import { ably_rest, RestConfig } from '@midtownhi/ably';
// For production with token auth (browser)
const browserClient = ably_rest({
authUrl: '/api/createAblyToken',
authMethod: 'POST'
});
// For server-side or development with API key
const serverClient = ably_rest({
key: 'your-api-key'
});
// Use the client to publish events
await browserClient.emit('my-channel', 'my-event', { hello: 'world' });
`
You can also use the class directly:
`typescript
import { AblyRestService, RestConfig } from '@midtownhi/ably';
const client = new AblyRestService({
key: 'your-api-key'
} as RestConfig);
await client.emit('my-channel', 'my-event', { data: 'value' });
`
Set your Ably API key using the ABLY_API_KEY environment variable or pass it directly in configuration.
For browser environments, you have two authentication options:
1. Token Authentication (Recommended for production):
- authUrl: URL to your token serverauthMethod
- : HTTP method as string (e.g., 'GET', 'POST')authHeaders
- : Optional headersauthParams
- : Optional query parametersclientId
- : Optional client identifier
2. API Key (Development only):
- key: Your Ably API key (not recommended for production browser environments)
Note: Both the browser and Node implementations accept either key or token auth parameters. The Node implementation additionally supports using environment variables.
`bashInstall dependencies
yarn install
Type Reference
This library provides specific types to help with TypeScript integration:
`typescript
// Import types
import {
BrowserConfig, // For browser configuration
NodeConfig, // For Node.js configuration
RestConfig, // For REST client configuration
Channel // Channel type
} from '@midtownhi/ably';
`Project Structure
The library has a simple structure with a focus on type safety and ease of use:
-
ably_browser.ts - Browser implementation with token auth
- ably_node.ts - Node.js implementation with environment variables
- ably_rest.ts - REST client implementation for both environments
- ably_channel.ts - Channel management for real-time subscriptions
- index.ts - Main entry point that exports all implementationsAll are compiled to the
dist` directory with full TypeScript definitions.MIT