api-ape 2.3.0 → 3.0.0

package/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/api-ape.svg)](https://www.npmjs.com/package/api-ape)
 [![GitHub issues](https://img.shields.io/github/issues/codemeasandwich/api-ape)](https://github.com/codemeasandwich/api-ape/issues)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#zero-dependencies)
+[![Dependabot](https://img.shields.io/dependabot/codemeasandwich/api-ape)](https://github.com/codemeasandwich/api-ape/security/dependabot)
 [![CSRF protected](https://img.shields.io/badge/CSRF%20🚷-protected-green.svg)](#csrf-protection)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/api-ape)](https://bundlephobia.com/package/api-ape)
 [![JJS Encoding](https://img.shields.io/badge/encoding-JJS-blue.svg)](#jjs-encoding)
@@ -32,7 +33,7 @@ yarn add api-ape
 
 ```js
 const { createServer } = require('http')
-const ape = require('api-ape')
+const { ape } = require('api-ape')
 
 const server = createServer()
 
@@ -45,7 +46,7 @@ server.listen(3000)
 **With Express:**
 ```js
 const express = require('express')
-const ape = require('api-ape')
+const { ape } = require('api-ape')
 
 const app = express()
 const server = app.listen(3000)  // Get the HTTP server
@@ -344,7 +345,7 @@ module.exports = function(announcement) {
 ### Using ape.clients
 
 ```js
-const ape = require('api-ape')
+const { ape } = require('api-ape')
 
 // Get online count
 console.log('Online:', ape.clients.size)

package/index.d.ts

@@ -219,6 +219,10 @@ export interface ForestOptions {
 
 /**
  * Initialize api-ape on a Node.js HTTP/HTTPS server
+ * 
+ * V3 Breaking Change:
+ * Old: const ape = require('api-ape')
+ * New: const { ape } = require('api-ape')
  */
 declare function ape(server: HttpServer, options: ApeServerOptions): void
 
@@ -280,8 +284,48 @@ declare namespace ape {
     export function message<T = any, R = any>(data?: T): Promise<R>
 }
 
-// Server-side default export (also works as browser client proxy)
-export default ape
+// =============================================================================
+// SERVER-SIDE CLIENT (api - same interface as browser)
+// =============================================================================
+
+/**
+ * Server-side client for connecting to other api-ape servers
+ * 100% identical interface to the browser client
+ * 
+ * @example
+ * import api from 'api-ape'
+ * 
+ * // Configure connection (or set APE_SERVER env)
+ * api.connect('ws://other-server:3000/api/ape')
+ * 
+ * // Same usage as browser
+ * const result = await api.hello('World')
+ * api.on('message', (data) => console.log(data))
+ */
+export interface ApeServerClient extends ApeSender {
+    /** Subscribe to broadcasts from the remote server */
+    on<T = any>(type: string, handler: MessageHandler<T>): void
+    on(handler: MessageHandler): void
+    /** Subscribe to connection state changes */
+    onConnectionChange(handler: (state: ConnectionState) => void): () => void
+    /** Connect to a server (or set APE_SERVER env) */
+    connect(url: string): void
+    /** Close the connection */
+    close(): void
+    /** Current transport type (read-only) */
+    readonly transport: 'websocket' | null
+}
+
+/**
+ * The api client - works identically on browser and server
+ */
+declare const api: ApeServerClient
+
+// Named export for V3 (Server usage: const { ape } = require('api-ape'))
+export { ape, api }
+
+// Default export: api client (same interface on browser and server)
+export default api
 
 // =============================================================================
 // BROWSER CLIENT (Default export in browser context)

package/index.js

@@ -1,11 +1,26 @@
+/**
+ * api-ape unified entry point
+ * 
+ * V3 Server Usage:
+ *   const api = require('api-ape')              // Client factory (default)
+ *   const { ape } = require('api-ape')          // Server initializer (named)
+ *   import api, { ape } from 'api-ape'          // ESM both
+ * 
+ * Browser Usage:
+ *   import api from 'api-ape'                   // Auto-connecting client
+ */
 
 let apiApe;
 
 if ('undefined' === typeof window
   || 'undefined' === typeof window.document) {
+  // Server environment - exports: api (default), ape, broadcast, clients, createClient
   apiApe = require('./server');
 } else {
+  // Browser environment - client module has its own exports
   apiApe = require('./client');
 }
 
 module.exports = apiApe
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-ape",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": "Remote Procedure Events (RPE) - A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods with automatic reconnection, HTTP streaming fallback, and extended JSON encoding.",
   "main": "index.js",
   "browser": "./client/index.js",

package/server/README.md

@@ -49,7 +49,7 @@ npm i api-ape
 
 ```js
 const { createServer } = require('http')
-const ape = require('api-ape')
+const { ape } = require('api-ape')
 
 const server = createServer()
 
@@ -64,6 +64,32 @@ ape(server, {
 server.listen(3000)
 ```
 
+## Server-to-Server Connection
+
+Your server can connect to **another** api-ape server as a client. The API is 100% identical to browser usage:
+
+```js
+import api, { ape } from 'api-ape'
+
+// Start your own server
+ape(server, { where: 'api' })
+
+// Connect to another api-ape server
+api.connect('ws://other-server:3000/api/ape')
+
+// Now use it exactly like browser code!
+const result = await api.hello('World')
+api.on('message', ({ data }) => console.log(data))
+```
+
+**Or set the connection URL via environment variable:**
+
+```bash
+APE_SERVER=ws://other-server:3000/api/ape node app.js
+```
+
+This enables server-side microservice patterns while keeping the familiar api-ape interface.
+
 ## API
 
 ### `ape(server, options)`
@@ -273,7 +299,7 @@ The built-in polyfill implements:
 ### Quick Start
 
 ```js
-const ape = require('api-ape');
+const { ape } = require('api-ape');
 const { createClient } = require('redis');
 
 const redis = createClient();
@@ -453,7 +479,7 @@ ape.joinVia({
 
 **Server A (port 3001):**
 ```js
-const ape = require('api-ape');
+const { ape } = require('api-ape');
 const redis = createClient();
 await redis.connect();
 
@@ -465,7 +491,7 @@ server.listen(3001);
 
 **Server B (port 3002):**
 ```js
-const ape = require('api-ape');
+const { ape } = require('api-ape');
 const redis = createClient();
 await redis.connect();
 

package/server/client.js

@@ -0,0 +1,299 @@
+/**
+ * api-ape Node.js client
+ * 
+ * Mirrors the browser client API exactly - same usage on server and browser.
+ * 
+ * Usage (identical to browser):
+ *   import api from 'api-ape'
+ *   
+ *   api.message({ user: 'Bob', text: 'Hello!' })
+ *   api.on('message', (data) => console.log(data))
+ *   api.onConnectionChange((state) => console.log(state))
+ * 
+ * Configuration:
+ *   Set APE_SERVER environment variable to the WebSocket URL:
+ *   APE_SERVER=ws://other-server:3000/api/ape node app.js
+ * 
+ *   Or call api.connect(url) before first use
+ */
+
+const jss = require('../utils/jss')
+const { WebSocket: WsPolyfill } = require('./lib/ws')
+
+// Use native WebSocket if available (Node 22+), otherwise use polyfill
+const WebSocket = globalThis.WebSocket || WsPolyfill
+
+// Connection state enum
+const ConnectionState = {
+    Disconnected: 'disconnected',
+    Connecting: 'connecting',
+    Connected: 'connected',
+    Closing: 'closing'
+}
+
+// Shared state (mirrors browser client)
+let ws = null
+let connectionState = ConnectionState.Disconnected
+const connectionChangeListeners = []
+const waitingOn = {}
+const receiverArray = []
+const ofTypesOb = {}
+let queryCounter = 0
+let bufferedCalls = []
+let bufferedReceivers = []
+let ready = false
+let reconnectEnabled = true
+let reconnectTimer = null
+let serverUrl = process.env.APE_SERVER || null
+
+const joinKey = '/'
+const connectTimeout = 5000
+const totalRequestTimeout = 10000
+
+function notifyConnectionChange(newState) {
+    if (connectionState !== newState) {
+        connectionState = newState
+        connectionChangeListeners.forEach(fn => fn(newState))
+    }
+}
+
+function generateQueryId() {
+    return `q${Date.now().toString(36)}_${(queryCounter++).toString(36)}`
+}
+
+function connect(url) {
+    if (url) serverUrl = url
+
+    if (!serverUrl) {
+        console.warn('🦍 api-ape: No server URL configured. Set APE_SERVER env or call api.connect(url)')
+        return
+    }
+
+    if (ws && ws.readyState !== WebSocket.CLOSED) {
+        return
+    }
+
+    notifyConnectionChange(ConnectionState.Connecting)
+
+    ws = new WebSocket(serverUrl)
+
+    ws.onopen = () => {
+        ready = true
+        notifyConnectionChange(ConnectionState.Connected)
+
+        // Flush buffered receivers
+        bufferedReceivers.forEach(({ type, handler }) => {
+            setOnReceiver(type, handler)
+        })
+        bufferedReceivers = []
+
+        // Flush buffered calls
+        bufferedCalls.forEach(({ type, data, resolve, reject, createdAt, timer }) => {
+            clearTimeout(timer)
+            send(type, data, createdAt).then(resolve).catch(reject)
+        })
+        bufferedCalls = []
+    }
+
+    ws.onmessage = (event) => {
+        const msg = jss.parse(typeof event.data === 'string' ? event.data : event.data.toString())
+        const { err, type, queryId, data } = msg
+
+        // Response to a query
+        if (queryId && waitingOn[queryId]) {
+            waitingOn[queryId](err, data)
+            delete waitingOn[queryId]
+            return
+        }
+
+        // Broadcast message
+        if (ofTypesOb[type]) {
+            ofTypesOb[type].forEach(handler => handler({ err, type, data }))
+        }
+        receiverArray.forEach(handler => handler({ err, type, data }))
+    }
+
+    ws.onerror = (err) => {
+        console.error('🦍 api-ape client error:', err.message || err)
+    }
+
+    ws.onclose = () => {
+        ready = false
+        ws = null
+        notifyConnectionChange(ConnectionState.Disconnected)
+
+        if (reconnectEnabled && serverUrl) {
+            reconnectTimer = setTimeout(() => connect(), 1000)
+        }
+    }
+}
+
+function send(type, data, createdAt = Date.now()) {
+    const queryId = generateQueryId()
+
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            delete waitingOn[queryId]
+            reject(new Error(`Request timeout: ${type}`))
+        }, totalRequestTimeout)
+
+        waitingOn[queryId] = (err, result) => {
+            clearTimeout(timer)
+            if (err) {
+                reject(typeof err === 'string' ? new Error(err) : err)
+            } else {
+                resolve(result)
+            }
+        }
+
+        const message = jss.stringify({ type, data, queryId, createdAt })
+        ws.send(message)
+    })
+}
+
+function queueOrSend(type, data) {
+    if (ready && ws && ws.readyState === WebSocket.OPEN) {
+        return send(type, data)
+    }
+
+    // Queue the message
+    return new Promise((resolve, reject) => {
+        const createdAt = Date.now()
+        const timer = setTimeout(() => {
+            const idx = bufferedCalls.findIndex(m => m.createdAt === createdAt)
+            if (idx > -1) bufferedCalls.splice(idx, 1)
+            reject(new Error(`Connection timeout: ${type}`))
+        }, connectTimeout)
+
+        bufferedCalls.push({ type, data, resolve, reject, createdAt, timer })
+
+        // Ensure we're connecting
+        if (connectionState === ConnectionState.Disconnected && serverUrl) {
+            connect()
+        }
+    })
+}
+
+/**
+ * Subscribe to broadcasts from the server (same as browser api.on)
+ */
+function on(type, handler) {
+    if (typeof type === 'function') {
+        handler = type
+        type = null
+    }
+
+    if (ready) {
+        setOnReceiver(type, handler)
+    } else {
+        bufferedReceivers.push({ type, handler })
+        if (serverUrl) connect()
+    }
+}
+
+function setOnReceiver(type, handler) {
+    if (type === null) {
+        receiverArray.push(handler)
+    } else {
+        if (!ofTypesOb[type]) ofTypesOb[type] = []
+        ofTypesOb[type].push(handler)
+    }
+}
+
+/**
+ * Subscribe to connection state changes (same as browser api.onConnectionChange)
+ */
+function onConnectionChange(handler) {
+    connectionChangeListeners.push(handler)
+    handler(connectionState)
+    return () => {
+        const idx = connectionChangeListeners.indexOf(handler)
+        if (idx > -1) connectionChangeListeners.splice(idx, 1)
+    }
+}
+
+/**
+ * Create the sender proxy (mirrors browser client exactly)
+ */
+const handler = {
+    get(target, prop) {
+        // Reserved properties - same as browser
+        if (prop === 'on') return on
+        if (prop === 'onConnectionChange') return onConnectionChange
+        if (prop === 'transport') return ready ? 'websocket' : null
+        if (prop === 'connect') return connect
+        if (prop === 'close') return close
+        if (prop === 'then' || prop === 'catch') return undefined // Not a Promise
+
+        // Return a function that either calls directly or buffers
+        const wrapperFn = function (a, b) {
+            let path = joinKey + prop, body
+            if (arguments.length === 2) {
+                path += a
+                body = b
+            } else {
+                body = a
+            }
+            return queueOrSend(path, body)
+        }
+        return new Proxy(wrapperFn, handler)
+    }
+}
+
+function close() {
+    reconnectEnabled = false
+    if (reconnectTimer) {
+        clearTimeout(reconnectTimer)
+        reconnectTimer = null
+    }
+    if (ws) {
+        notifyConnectionChange(ConnectionState.Closing)
+        ws.close()
+    }
+}
+
+// Create the proxy (same interface as browser senderProxy)
+const api = new Proxy({}, handler)
+
+// Define properties on the proxy (same as browser)
+Object.defineProperty(api, 'on', {
+    value: on,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(api, 'onConnectionChange', {
+    value: onConnectionChange,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(api, 'connect', {
+    value: connect,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+Object.defineProperty(api, 'close', {
+    value: close,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})
+
+// Auto-connect if APE_SERVER is set
+if (serverUrl) {
+    connect()
+}
+
+// Export the same interface as browser
+module.exports = api
+module.exports.default = api
+module.exports.on = on
+module.exports.onConnectionChange = onConnectionChange
+module.exports.connect = connect
+module.exports.close = close
+module.exports.ConnectionState = ConnectionState

package/server/index.js

@@ -1,14 +1,37 @@
 /**
  * api-ape server entry point
- * Exports the main ape function and broadcast utilities
+ * 
+ * V3 Usage (100% identical on browser and server):
+ *   import api from 'api-ape'
+ *   api.hello('World')  // Works same on browser AND server
+ *   api.on('message', (data) => console.log(data))
+ * 
+ * Server Setup:
+ *   import api, { ape } from 'api-ape'
+ *   ape(server, { where: 'api' })  // Start your server
+ *   
+ *   // Connect to another server (set APE_SERVER env or call api.connect)
+ *   api.connect('ws://other-server:3000/api/ape')
+ *   api.hello('World')
+ * 
+ * Supports both CommonJS and ES Modules
  */
 
 const ape = require('./lib/main')
 const { broadcast, clients } = require('./lib/broadcast')
+const api = require('./client')
 
-// Attach broadcast utilities to the main function for clean exports
+// Attach broadcast utilities to the ape function
 ape.broadcast = broadcast
 ape.clients = clients
 
-module.exports = ape
+// Default export: api client (same interface as browser)
+module.exports = api
+
+// Named exports
+module.exports.ape = ape
+module.exports.api = api
+
+
+