🦍 api-ape

Remote Procedure Events (RPE) — A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods. Get real-time broadcasts with zero setup.

Install

npm install api-ape

Requirements: Node.js 14+ (for server), modern browsers (for client)

Quick Start

Server (ape)

const { createServer } = require('http')
const { ape } = require('api-ape')

const server = createServer()
ape(server, { where: 'api' })  // Load controllers from ./api folder
server.listen(3000)

Controllers

Drop a file in your api/ folder — it automatically becomes an endpoint:

// api/hello.js
module.exports = function(name) {
  return `Hello, ${name}!`
}

// api/message.js  
module.exports = function(text) {
  this.broadcastOthers('message', { text, from: this.clientId })
  return { sent: true }
}

Client (api)

Browser:

<script src="/api/ape.js"></script>
<script>
  const result = await api.hello('World')  // "Hello, World!"

  // Subscribe to messages (pass a callback)
  const unsub = api.message(data => console.log(data))
</script>

Bundlers (React, Vue, etc.):

import api from 'api-ape'

const result = await api.hello('World')

// Subscribe (pass callback) vs RPC call (pass data)
const unsub = api.message(data => console.log(data))  // Subscribe
await api.message({ text: 'Hello' })                   // RPC call

Key Concepts

• Auto-wiring — Drop JS files in a folder, they become API endpoints
• Real-time broadcasts — Built-in broadcast() and broadcastOthers() methods
• Pub/Sub channels — Clients subscribe to channels, server publishes updates
• Promise-based calls — api.users.list() maps to api/users/list.js
• Automatic reconnection — Client reconnects with exponential backoff
• HTTP fallback — Falls back to long polling when WebSockets are blocked
• JSS Encoding — Supports Date, RegExp, Error, Set, Map over the wire
• 🌲 Forest — Distributed mesh for horizontal scaling
• 🔐 Authentication — OPAQUE/PAKE auth with tiered access control

Examples

• example/ExpressJs/ — Simple real-time chat
• example/NextJs/ — Production chat with React & Docker
• example/Vite/ — Vite + Vue
• example/Bun/ — Bun runtime

cd example/ExpressJs && npm install && npm start

Documentation

| Docs | Description | |------|-------------| | Server README | API reference, lifecycle hooks, auto-routing, file transfers, 🌲 Forest | | Client README | Client usage, connection states, file transfers, security | | Auth README | OPAQUE authentication, tiered access, authorization | | Adapters README | Database adapters for Forest |

Contributing

1. Fork the repository
2. Create a branch: git checkout -b feature/your-feature
3. Make changes and add tests
4. Run tests: npm test
5. Push and open a PR

Tests

npm test            # Run tests
npm run test:watch  # Watch mode
npm run test:cover  # Coverage

License

MIT — Brian Shannon

Made with 🦍 by the api-ape community