api-ape 0.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,261 @@
+# 🦍 api-ape
+
+**Remote Procedure Events (RPE)** — A lightweight WebSocket framework for real-time APIs.
+
+Call server functions from the browser like local methods. Get real-time broadcasts with zero setup.
+
+```js
+// Client: call server function, get result
+const pets = await ape.pets.list()
+
+// Client: listen for broadcasts
+ape.on('newPet', ({ data }) => console.log('New pet:', data))
+```
+
+file: api/pets/list.js
+```js
+// Server: define function, broadcast to others
+module.exports = function list() {
+  return getPetList()
+}
+```
+
+file: api/pets/newPet.js
+```js
+// Server: define function, broadcast to others
+module.exports = function newPet(data) {
+    // broadcast to all other clients
+  this.broadcastOthers('newPet', data)
+  return savePet(data)
+}
+```
+
+---
+
+## Features
+
+- **🔌 Auto-wiring** — Drop JS files in a folder, they become API endpoints
+- **📡 Real-time** — Built-in broadcast to all or other clients
+- **🔄 Reconnection** — Client auto-reconnects on disconnect
+- **📦 JJS Encoding** — Supports Date, RegExp, Error, Set, Map, undefined over the wire
+- **🎯 Simple API** — Promise-based calls with chainable paths
+
+---
+
+## Installation
+
+```bash
+npm install api-ape
+```
+
+---
+
+## Quick Start
+
+### Server (Express.js)
+
+```js
+const express = require('express')
+const ape = require('api-ape')
+
+const app = express()
+
+// Wire up api-ape - loads controllers from ./api folder
+ape(app, { where: 'api' })
+
+app.listen(3000)
+```
+
+### Controllers
+
+Create files in your `api/` folder. Each export becomes an endpoint:
+
+```js
+// api/hello.js
+module.exports = function(name) {
+  return `Hello, ${name}!`
+}
+```
+
+```js
+// api/message.js
+module.exports = function(data) {
+  // Broadcast to all OTHER connected clients
+  this.broadcastOthers('message', data)
+  return data
+}
+```
+
+### Client (Browser)
+
+Include the bundled client:
+
+```html
+<script src="/api/ape.js"></script>
+<script>
+  // Call server functions
+  ape.hello('World').then(result => console.log(result)) // "Hello, World!"
+  
+  // Listen for broadcasts
+  ape.on('message', ({ data }) => {
+    console.log('New message:', data)
+  })
+</script>
+```
+
+---
+
+## API Reference
+
+### Server
+
+#### `ape(app, options)`
+
+Initialize api-ape on an Express app.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where` | `string` | Directory containing controller files |
+| `onConnent` | `function` | Connection lifecycle hook (see below) |
+
+#### Controller Context (`this`)
+
+Inside controller functions, `this` provides:
+
+| Property | Description |
+|----------|-------------|
+| `this.broadcast(type, data)` | Send to ALL connected clients |
+| `this.broadcastOthers(type, data)` | Send to all EXCEPT the caller |
+| `this.online()` | Get count of connected clients |
+| `this.getClients()` | Get array of connected hostIds |
+| `this.hostId` | Unique ID of the calling client |
+| `this.req` | Original HTTP request |
+| `this.socket` | WebSocket instance |
+| `this.agent` | Parsed user-agent (browser, OS, device) |
+
+#### Connection Lifecycle
+
+```js
+ape(app, {
+  where: 'api',
+  onConnent(socket, req, send) {
+    return {
+      // Embed values into `this` for all controllers
+      embed: {
+        userId: req.session?.userId,
+        clientId: send + '' // hostId as string
+      },
+      
+      // Before/after hooks
+      onReceive: (queryId, data, type) => {
+        console.log(`→ ${type}`)
+        return (err, result) => console.log(`← ${type}`, err || result)
+      },
+      
+      onSend: (data, type) => {
+        console.log(`⇐ ${type}`)
+        return (err, result) => console.log(`Sent: ${type}`)
+      },
+      
+      onError: (errStr) => console.error(errStr),
+      onDisconnent: () => console.log('Client left')
+    }
+  }
+})
+```
+
+### Client
+
+#### `ape.<path>.<method>(data)`
+
+Call a server function. Returns a Promise.
+
+```js
+// Calls api/users/list.js
+ape.users.list().then(users => ...)
+
+// Calls api/users/create.js with data
+ape.users.create({ name: 'Alice' }).then(user => ...)
+
+// Nested paths work too
+ape.admin.users.delete(userId).then(() => ...)
+```
+
+#### `ape.on(type, handler)`
+
+Listen for server broadcasts.
+
+```js
+ape.on('notification', ({ data, err, type }) => {
+  console.log('Received:', data)
+})
+```
+
+---
+
+## JJS Encoding
+
+api-ape uses **JJS (JSON SuperSet)** encoding, which extends JSON to support:
+
+| Type | Supported |
+|------|-----------|
+| `Date` | ✅ Preserved as Date objects |
+| `RegExp` | ✅ Preserved as RegExp |
+| `Error` | ✅ Preserved with name, message, stack |
+| `undefined` | ✅ Preserved (not converted to null) |
+| `Set` | ✅ Preserved as Set |
+| `Map` | ✅ Preserved as Map |
+| Circular refs | ✅ Handled via pointers |
+
+This is automatic — send a Date, receive a Date.
+
+---
+
+## Examples
+
+See the [`example/`](./example) folder:
+
+- **ExpressJs/** — Simple chat app with broadcast
+- **NextJs/** — Integration with Next.js
+
+Run the Express example:
+
+```bash
+cd example/ExpressJs
+npm install
+npm start
+```
+
+---
+
+## Project Structure
+
+```
+api-ape/
+├── client/
+│   ├── browser.js       # Browser entry point (window.ape)
+│   └── connectSocket.js # WebSocket client with auto-reconnect
+├── server/
+│   ├── lib/
+│   │   ├── main.js      # Express integration
+│   │   ├── loader.js    # Auto-loads controller files
+│   │   ├── broadcast.js # Client tracking & broadcast
+│   │   └── wiring.js    # WebSocket handler setup
+│   ├── socket/
+│   │   ├── receive.js   # Incoming message handler
+│   │   └── send.js      # Outgoing message handler
+│   └── security/
+│       └── reply.js     # Duplicate request protection
+├── utils/
+│   ├── jss.js           # JSON SuperSet encoder/decoder
+│   └── messageHash.js   # Request deduplication
+└── example/
+    ├── ExpressJs/       # Chat app example
+    └── NextJs/          # Next.js integration
+```
+
+---
+
+## License
+
+MIT © [Brian Shannon](https://github.com/codemeasandwich)

package/client/README.md

@@ -0,0 +1,69 @@
+# 🦍 api-ape Client
+
+WebSocket client library with auto-reconnection and proxy-based API calls.
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `browser.js` | Browser entry point - exposes `window.ape` |
+| `connectSocket.js` | WebSocket client with auto-reconnect, queuing, and JJS encoding |
+
+## Usage
+
+### Browser (via script tag)
+
+```html
+<script src="/api/ape.js"></script>
+<script>
+  // Call server functions
+  ape.hello('World').then(result => console.log(result))
+  
+  // Listen for broadcasts
+  ape.on('message', ({ data }) => console.log(data))
+</script>
+```
+
+### ES Module Import
+
+```bash
+npm i api-ape
+```
+
+```js
+import ape from 'api-ape'
+
+// Configure
+ape.configure({ port: 3000 })
+
+// Connect and enable auto-reconnect
+const { sender, setOnReciver } = ape()
+ape.autoReconnect()
+
+// Use sender as API
+sender.users.list().then(users => ...)
+
+// Listen for broadcasts
+setOnReciver('newUser', ({ data }) => ...)
+```
+
+## Features
+
+- **Proxy-based API** — `ape.path.method(data)` converts to WebSocket calls
+- **Auto-reconnect** — Reconnects on disconnect with queued messages
+- **Promise-based** — All calls return promises with matched responses via queryId
+- **JJS encoding** — Supports Date, RegExp, Error, Set, Map, undefined over the wire
+- **Request timeout** — Configurable timeout (default: 10s)
+
+## Configuration
+
+```js
+ape.configure({
+  port: 3000,    // WebSocket port
+  host: 'api.example.com'  // WebSocket host
+})
+```
+
+Default port detection:
+- Local (`localhost`, `127.0.0.1`): `9010`
+- Remote: Uses current page port or `443`/`80`

package/client/browser.js

@@ -0,0 +1,17 @@
+import connectSocket from './connectSocket.js'
+
+// Auto-configure for current page
+const port = window.location.port || (window.location.protocol === 'https:' ? 443 : 80)
+connectSocket.configure({ port: parseInt(port, 10) })
+
+const { sender, setOnReciver } = connectSocket()
+connectSocket.autoReconnect()
+
+// Global API - use defineProperty to bypass Proxy interception
+window.ape = sender
+Object.defineProperty(window.ape, 'on', {
+    value: setOnReciver,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})

package/client/connectSocket.js

@@ -0,0 +1,260 @@
+import messageHash from '../utils/messageHash'
+import jss from '../utils/jss'
+
+
+let connect;
+
+// Configuration
+let configuredPort = null
+let configuredHost = null
+
+/**
+ * Configure api-ape client connection
+ * @param {object} opts
+ * @param {number} [opts.port] - WebSocket port (default: 9010 for local, 443/80 for remote)
+ * @param {string} [opts.host] - WebSocket host (default: auto-detect from window.location)
+ */
+function configure(opts = {}) {
+  if (opts.port) configuredPort = opts.port
+  if (opts.host) configuredHost = opts.host
+}
+
+/**
+ * Get WebSocket URL - auto-detects from window.location, keeps /api/ape path
+ */
+function getSocketUrl() {
+  const hostname = configuredHost || window.location.hostname
+  const localServers = ["localhost", "127.0.0.1", "[::1]"]
+  const isLocal = localServers.includes(hostname)
+  const isHttps = window.location.protocol === "https:"
+
+  // Default port: 9010 for local dev, otherwise use window.location.port or implicit 443/80
+  const defaultPort = isLocal ? 9010 : (window.location.port || (isHttps ? 443 : 80))
+  const port = configuredPort || defaultPort
+
+  // Build URL - keep /api/ape path
+  const protocol = isHttps ? "wss" : "ws"
+  const portSuffix = (isLocal || port !== 80 && port !== 443) ? `:${port}` : ""
+
+  return `${protocol}://${hostname}${portSuffix}/api/ape`
+}
+
+let reconnect = false
+const connentTimeout = 5000
+const totalRequestTimeout = 10000
+//const location = window.location
+
+const joinKey = "/"
+// Properties accessed directly on `ape` that should NOT be intercepted
+const reservedKeys = new Set(['on'])
+const handler = {
+  get(fn, key) {
+    // Skip proxy interception for reserved keys - return actual property
+    if (reservedKeys.has(key)) {
+      return fn[key]
+    }
+    const wrapperFn = function (a, b) {
+      let path = joinKey + key, body;
+      if (2 === arguments.length) {
+        path += a
+        body = b
+      } else {
+        body = a
+      }
+      return fn(path, body)
+    }
+    return new Proxy(wrapperFn, handler)
+  } // END get
+}
+
+function wrap(api) {
+  return new Proxy(api, handler)
+}
+
+let __socket = false, ready = false, wsSend = false;
+const waitingOn = {};
+const reciverOn = [];
+
+let aWaitingSend = []
+const reciverOnAr = [];
+const ofTypesOb = {};
+
+function connectSocket() {
+
+  if (!__socket) {
+    __socket = new WebSocket(getSocketUrl())
+
+    __socket.onopen = event => {
+      //console.log('socket connected()');
+      ready = true;
+      aWaitingSend.forEach(({ type, data, next, err, waiting, createdAt, timer }) => {
+        clearTimeout(timer)
+        //TODO: clear throw of wait for server
+        const resultPromise = wsSend(type, data, createdAt)
+        if (waiting) {
+          resultPromise.then(next)
+            .catch(err)
+        }
+      })
+      // cloudfler drops the connetion and the client has to remake,
+      // we clear the array as we dont need this info every RE-connent
+      aWaitingSend = []
+    } // END onopen
+
+    __socket.onmessage = function (event) {
+      //console.log('WebSocket message:', event);
+      const { err, type, queryId, data } = jss.parse(event.data)
+
+      // Messages with queryId must fulfill matching promise
+      if (queryId) {
+        if (waitingOn[queryId]) {
+          waitingOn[queryId](err, data)
+          delete waitingOn[queryId]
+        } else {
+          // No matching promise - error and ignore
+          console.error(`🦍 No matching queryId: ${queryId}`)
+        }
+        return
+      }
+
+      // Only messages WITHOUT queryId go to setOnReciver
+      if (ofTypesOb[type]) {
+        ofTypesOb[type].forEach(worker => worker({ err, type, data }))
+      } // if ofTypesOb[type]
+      reciverOnAr.forEach(worker => worker({ err, type, data }))
+
+    } // END onmessage
+
+    __socket.onerror = function (err) {
+      console.error('socket ERROR:', err);
+    } // END onerror
+
+    __socket.onclose = function (event) {
+      console.warn('socket disconnect:', event);
+      __socket = false
+      ready = false;
+      setTimeout(() => reconnect && connectSocket(), 500);
+    } // END onclose
+
+  } // END if ! __socket
+  wsSend = function (type, data, createdAt, dirctCall) {
+    let rej, promiseIsLive = false;
+    const timeLetForReqToBeMade = (createdAt + totalRequestTimeout) - Date.now()
+
+    const timer = setTimeout(() => {
+      if (promiseIsLive) {
+        rej(new Error("Request Timedout for :" + type))
+      }
+    }, timeLetForReqToBeMade);
+    const payload = {
+      type,
+      data,
+      //referer:window.location.href,
+      createdAt: new Date(createdAt),
+      requestedAt: dirctCall ? undefined
+        : new Date()
+    }
+    const message = jss.stringify(payload)
+    const queryId = messageHash(message);
+
+    const replyPromise = new Promise((resolve, reject) => {
+      rej = reject
+      waitingOn[queryId] = (err, result) => {
+        clearTimeout(timer)
+        replyPromise.then = next.bind(replyPromise)
+        if (err) {
+          reject(err)
+        } else {
+          resolve(result)
+        }
+      }
+      __socket.send(message);
+    });
+    const next = replyPromise.then;
+    replyPromise.then = worker => {
+      promiseIsLive = true;
+      replyPromise.then = next.bind(replyPromise)
+      replyPromise.catch = err.bind(replyPromise)
+      return next.call(replyPromise, worker)
+    }
+    const err = replyPromise.catch;
+    replyPromise.catch = worker => {
+      promiseIsLive = true;
+      replyPromise.catch = err.bind(replyPromise)
+      replyPromise.then = next.bind(replyPromise)
+      return err.call(replyPromise, worker)
+    }
+    return replyPromise
+  } // END wsSend
+
+
+  const sender = (type, data) => {
+    if ("string" !== typeof type) {
+      throw new Error("Missing Path vaule")
+    }
+
+    const createdAt = Date.now()
+
+    if (ready) {
+      return wsSend(type, data, createdAt, true)
+    }
+
+    const timeLetForReqToBeMade = (createdAt + connentTimeout) - Date.now() // 5sec for reconnent
+
+    const timer = setTimeout(() => {
+      const errMessage = "Request not sent for :" + type
+      if (payload.waiting) {
+        payload.err(new Error(errMessage))
+      } else {
+        throw new Error(errMessage)
+      }
+    }, timeLetForReqToBeMade);
+
+    const payload = { type, data, next: undefined, err: undefined, waiting: false, createdAt, timer };
+    const waitingOnOpen = new Promise((res, er) => { payload.next = res; payload.err = er; })
+
+    const waitingOnOpenThen = waitingOnOpen.then;
+    const waitingOnOpenCatch = waitingOnOpen.catch;
+    waitingOnOpen.then = worker => {
+      payload.waiting = true;
+      waitingOnOpen.then = waitingOnOpenThen.bind(waitingOnOpen)
+      waitingOnOpen.catch = waitingOnOpenCatch.bind(waitingOnOpen)
+      return waitingOnOpenThen.call(waitingOnOpen, worker)
+    }
+    waitingOnOpen.catch = worker => {
+      payload.waiting = true;
+      waitingOnOpen.catch = waitingOnOpenCatch.bind(waitingOnOpen)
+      waitingOnOpen.then = waitingOnOpenThen.bind(waitingOnOpen)
+      return waitingOnOpenCatch.call(waitingOnOpen, worker)
+    }
+
+    aWaitingSend.push(payload)
+    if (!__socket) {
+      connectSocket()
+    }
+
+    return waitingOnOpen
+  } // END sender
+
+  return {
+    sender: wrap(sender),
+    setOnReciver: (onTypeStFn, handlerFn) => {
+      if ("string" === typeof onTypeStFn) {
+        // Replace handler for this type (prevents duplicates in React StrictMode)
+        ofTypesOb[onTypeStFn] = [handlerFn]
+      } else {
+        // For general receivers, prevent duplicates by checking
+        if (!reciverOnAr.includes(onTypeStFn)) {
+          reciverOnAr.push(onTypeStFn)
+        }
+      }
+    } // END setOnReciver
+  } // END return
+} // END connectSocket
+
+connectSocket.autoReconnect = () => reconnect = true
+connectSocket.configure = configure
+connect = connectSocket
+
+export default connect;
+export { configure };