api-ape 1.1.0 → 2.0.0

package/README.md

@@ -24,18 +24,30 @@ yarn add api-ape
 
 ## Quick Start
 
-### Server (Express.js)
+### Server (Node.js)
 
 ```js
-const express = require('express')
+const { createServer } = require('http')
 const ape = require('api-ape')
 
-const app = express()
+const server = createServer()
 
 // Wire up api-ape - loads controllers from ./api folder
-ape(app, { where: 'api' })
+ape(server, { where: 'api' })
+
+server.listen(3000)
+```
+
+**With Express:**
+```js
+const express = require('express')
+const ape = require('api-ape')
+
+const app = express()
+const server = app.listen(3000)  // Get the HTTP server
 
-app.listen(3000)
+// Pass the HTTP server (not the Express app)
+ape(server, { where: 'api' })
 ```
 
 ### Create a Controller
@@ -86,12 +98,13 @@ Include the bundled client and start calling:
 
 ### Server
 
-#### `ape(app, options)`
+#### `ape(server, options)`
 
-Initialize api-ape on an Express app.
+Initialize api-ape on a Node.js HTTP/HTTPS server.
 
 | Option | Type | Description |
 |--------|------|-------------|
+| `server` | `http.Server` | Node.js HTTP or HTTPS server instance |
 | `where` | `string` | Directory containing controller files (default: `'api'`) |
 | `onConnent` | `function` | Connection lifecycle hook (see [Connection Lifecycle](#connection-lifecycle)) |
 
@@ -146,7 +159,7 @@ ape.on('notification', ({ data, err, type }) => {
 ### Default Options
 
 ```js
-ape(app, {
+ape(server, {
   where: 'api',           // Controller directory
   onConnent: undefined    // Lifecycle hook (optional)
 })
@@ -157,7 +170,7 @@ ape(app, {
 Customize behavior per connection:
 
 ```js
-ape(app, {
+ape(server, {
   where: 'api',
   onConnent(socket, req, hostId) {
     return {
@@ -328,7 +341,7 @@ docker-compose up --build
 
 ### CORS Errors in Browser
 
-Ensure your Express server allows WebSocket connections from your origin. api-ape uses `express-ws` which handles CORS automatically, but verify your Express CORS middleware allows WebSocket upgrade requests.
+Ensure your server allows WebSocket connections from your origin. api-ape uses the `ws` library which handles WebSocket upgrades on the HTTP server level.
 
 ### Controller Not Found
 
@@ -460,7 +473,7 @@ api-ape/
 │   └── connectSocket.js # WebSocket client with auto-reconnect
 ├── server/
 │   ├── lib/
-│   │   ├── main.js      # Express integration
+│   │   ├── main.js      # HTTP server integration
 │   │   ├── loader.js    # Auto-loads controller files
 │   │   ├── broadcast.js # Client tracking & broadcast
 │   │   └── wiring.js    # WebSocket handler setup

package/client/browser.js

@@ -4,7 +4,7 @@ import connectSocket from './connectSocket.js'
 const port = window.location.port || (window.location.protocol === 'https:' ? 443 : 80)
 connectSocket.configure({ port: parseInt(port, 10) })
 
-const { sender, setOnReciver } = connectSocket()
+const { sender, setOnReciver, onConnectionChange } = connectSocket()
 connectSocket.autoReconnect()
 
 // Global API - use defineProperty to bypass Proxy interception
@@ -15,3 +15,9 @@ Object.defineProperty(window.ape, 'on', {
     enumerable: false,
     configurable: false
 })
+Object.defineProperty(window.ape, 'onConnectionChange', {
+    value: onConnectionChange,
+    writable: false,
+    enumerable: false,
+    configurable: false
+})

package/client/connectSocket.js

@@ -1,9 +1,27 @@
 import messageHash from '../utils/messageHash'
 import jss from '../utils/jss'
 
-
 let connect;
 
+// Connection state enum
+const ConnectionState = {
+  Disconnected: 'disconnected',
+  Connecting: 'connecting',
+  Connected: 'connected',
+  Closing: 'closing'
+}
+
+// Connection state tracking
+let connectionState = ConnectionState.Disconnected
+const connectionChangeListeners = []
+
+function notifyConnectionChange(newState) {
+  if (connectionState !== newState) {
+    connectionState = newState
+    connectionChangeListeners.forEach(fn => fn(newState))
+  }
+}
+
 // Configuration
 let configuredPort = null
 let configuredHost = null
@@ -82,11 +100,13 @@ const ofTypesOb = {};
 function connectSocket() {
 
   if (!__socket) {
+    notifyConnectionChange(ConnectionState.Connecting)
     __socket = new WebSocket(getSocketUrl())
 
     __socket.onopen = event => {
       //console.log('socket connected()');
       ready = true;
+      notifyConnectionChange(ConnectionState.Connected)
       aWaitingSend.forEach(({ type, data, next, err, waiting, createdAt, timer }) => {
         clearTimeout(timer)
         //TODO: clear throw of wait for server
@@ -277,6 +297,7 @@ function connectSocket() {
       console.warn('socket disconnect:', event);
       __socket = false
       ready = false;
+      notifyConnectionChange(ConnectionState.Disconnected)
       setTimeout(() => reconnect && connectSocket(), 500);
     } // END onclose
 
@@ -531,13 +552,24 @@ function connectSocket() {
           reciverOnAr.push(onTypeStFn)
         }
       }
-    } // END setOnReciver
+    }, // END setOnReciver
+    onConnectionChange: (handler) => {
+      connectionChangeListeners.push(handler)
+      // Immediately call with current state
+      handler(connectionState)
+      // Return unsubscribe function
+      return () => {
+        const idx = connectionChangeListeners.indexOf(handler)
+        if (idx > -1) connectionChangeListeners.splice(idx, 1)
+      }
+    }
   } // END return
 } // END connectSocket
 
 connectSocket.autoReconnect = () => reconnect = true
 connectSocket.configure = configure
+connectSocket.ConnectionState = ConnectionState
 connect = connectSocket
 
 export default connect;
-export { configure };
+export { configure, ConnectionState };

package/example/Bun/README.md

@@ -0,0 +1,74 @@
+# 🦍 Bun — Example
+
+A minimal real-time chat app using Bun's native HTTP server with api-ape.
+
+## Quick Start
+
+```bash
+bun install
+bun run start
+```
+
+Open http://localhost:3000 in multiple browser windows.
+
+## Project Structure
+
+```
+Bun/
+├── server.ts         # Bun server with api-ape (TypeScript)
+├── api/
+│   └── message.ts    # Broadcast to other clients
+├── index.html        # Chat UI
+└── styles.css        # Styling
+```
+
+## How It Works
+
+### Server (server.js)
+
+```js
+const ape = require('api-ape')
+
+const server = Bun.serve({
+  port: 3000,
+  fetch(req) {
+    const url = new URL(req.url)
+    if (url.pathname === '/') {
+      return new Response(Bun.file('./index.html'))
+    }
+    return new Response('Not Found', { status: 404 })
+  }
+})
+
+// Pass Bun's server to api-ape
+ape(server, {
+  where: 'api',
+  onConnent: (socket, req, send) => {
+    send('init', { history: [], users: ape.online() })
+    ape.broadcast('users', { count: ape.online() })
+    
+    return {
+      onDisconnent: () => ape.broadcast('users', { count: ape.online() })
+    }
+  }
+})
+```
+
+## Why Bun?
+
+| Feature | Benefit |
+|---------|---------|
+| **No Express needed** | Bun has built-in HTTP server |
+| **Fast startup** | Bun starts in milliseconds |
+| **Native TypeScript** | No build step for TS files |
+| **Smaller footprint** | Fewer dependencies |
+
+## Key Concepts Demonstrated
+
+| Concept | Example |
+|---------|---------|
+| Auto-wiring | `ape(server, { where: 'api' })` loads `api/*.js` |
+| onConnect hook | `onConnent: (socket, req, send) => { ... }` |
+| Push on connect | `send('init', { history, users })` |
+| Broadcast all | `broadcast('users', { count })` |
+| Broadcast others | `this.broadcastOthers('message', data)` |

package/example/Bun/api/message.ts

@@ -0,0 +1,11 @@
+const messages: Array<{ user: string; text: string }> = []
+
+// Send message → broadcast to others
+module.exports = function (this: any, data: { user: string; text: string }) {
+    messages.push(data)
+    this.broadcastOthers('message', data)
+    return data
+}
+
+// Export messages for history
+module.exports._messages = messages

package/example/Bun/index.html

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Chat - api-ape</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="/styles.css">
+</head>
+
+<body>
+  <div id="app">
+    <div class="chat-container">
+      <div class="header">
+        <span class="title">💬 Chat</span>
+        <span class="online-count">🟢 {{ users }} online</span>
+        <span class="user-badge">● {{ user }}</span>
+      </div>
+      <div class="messages">
+        <div v-if="messages.length === 0" class="empty-state">No messages yet...</div>
+        <div v-for="(m, i) in messages" :key="i" :class="['message', m.user === user ? 'mine' : '']">
+          <span class="username">{{ m.user }}</span>
+          <span class="text">{{ m.text }}</span>
+        </div>
+      </div>
+      <div class="input-area">
+        <input class="message-input" placeholder="Type a message..." v-model="input" @keydown.enter="send" autofocus>
+      </div>
+    </div>
+  </div>
+
+  <script src="https://unpkg.com/vue@3"></script>
+  <script src="/api/ape.js"></script>
+  <script>
+    const { createApp, ref, onMounted } = Vue
+
+    createApp({
+      setup() {
+        const user = ref('User' + Math.random().toString(36).slice(2, 6))
+        const users = ref(0)
+        const messages = ref([])
+        const input = ref('')
+
+        onMounted(() => {
+          // Receive init with history + user count on connect
+          ape.on('init', ({ data }) => {
+            messages.value = data.history || []
+            users.value = data.users || 0
+          })
+
+          // Listen for user count updates
+          ape.on('users', ({ data }) => {
+            users.value = data.count
+          })
+
+          // Listen for new messages from others
+          ape.on('message', ({ data }) => {
+            messages.value.push(data)
+          })
+        })
+
+        function send() {
+          if (!input.value) return
+          const msg = { user: user.value, text: input.value }
+          ape.message(msg).then(() => {
+            messages.value.push(msg)
+          })
+          input.value = ''
+        }
+
+        return { user, users, messages, input, send }
+      }
+    }).mount('#app')
+  </script>
+</body>
+
+</html>

package/example/Bun/package.json

@@ -0,0 +1,9 @@
+{
+    "name": "bun-chat-example",
+    "scripts": {
+        "start": "bun run server.ts"
+    },
+    "dependencies": {
+        "api-ape": "file:../.."
+    }
+}

package/example/Bun/server.ts

@@ -0,0 +1,59 @@
+/**
+ * Bun server using api-ape library (TypeScript)
+ * Bun natively supports TypeScript - no build step needed!
+ */
+
+import { createServer, IncomingMessage, ServerResponse } from 'http'
+import path from 'path'
+import fs from 'fs'
+import ape from 'api-ape'
+
+const port = parseInt(process.env.PORT || '3000', 10)
+
+// Create HTTP server
+const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url || '/', `http://localhost:${port}`)
+
+    if (url.pathname === '/') {
+        res.writeHead(200, { 'Content-Type': 'text/html' })
+        res.end(fs.readFileSync(path.join(__dirname, 'index.html')))
+        return
+    }
+
+    if (url.pathname === '/styles.css') {
+        res.writeHead(200, { 'Content-Type': 'text/css' })
+        res.end(fs.readFileSync(path.join(__dirname, 'styles.css')))
+        return
+    }
+
+    res.writeHead(404)
+    res.end('Not Found')
+})
+
+// Initialize api-ape
+ape(server, {
+    where: 'api',
+    onConnent: (socket, req, send) => {
+        const messageModule = require('./api/message')
+        setTimeout(() => {
+            send('init', { history: messageModule._messages, users: ape.online() })
+            ape.broadcast('users', { count: ape.online() })
+        }, 100)
+
+        return {
+            onDisconnent: () => ape.broadcast('users', { count: ape.online() })
+        }
+    }
+})
+
+server.listen(port, () => {
+    console.log(`
+╔═══════════════════════════════════════════════════════╗
+║       🦍 api-ape Bun Example (TypeScript)             ║
+╠═══════════════════════════════════════════════════════╣
+║  HTTP:      http://localhost:${port}/                  ║
+║  WebSocket: ws://localhost:${port}/api/ape             ║
+║  Runtime:   Bun 🥖 + TypeScript                       ║
+╚═══════════════════════════════════════════════════════╝
+`)
+})

package/example/Bun/styles.css

@@ -0,0 +1,128 @@
+* {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+}
+
+body {
+    min-height: 100vh;
+    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%);
+    color: #fff;
+    font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif;
+    display: flex;
+    justify-content: center;
+    padding: 2rem;
+}
+
+#app {
+    max-width: 500px;
+    width: 100%;
+}
+
+.chat-container {
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 20px;
+    overflow: hidden;
+    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+}
+
+.header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 1rem 1.5rem;
+    background: rgba(255, 255, 255, 0.1);
+}
+
+.title {
+    font-size: 1.25rem;
+    font-weight: bold;
+    background: linear-gradient(90deg, #00d2ff, #3a7bd5);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+.user-badge {
+    font-size: 0.85rem;
+    color: #0f0;
+    font-weight: bold;
+}
+
+.messages {
+    height: 350px;
+    overflow-y: auto;
+    padding: 1rem;
+}
+
+.messages::-webkit-scrollbar {
+    width: 6px;
+}
+
+.messages::-webkit-scrollbar-track {
+    background: rgba(255, 255, 255, 0.05);
+}
+
+.messages::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.2);
+    border-radius: 3px;
+}
+
+.empty-state {
+    text-align: center;
+    color: #666;
+    margin-top: 140px;
+}
+
+.message {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 0.75rem 1rem;
+    margin-bottom: 0.5rem;
+    background: rgba(255, 255, 255, 0.05);
+    border-radius: 12px;
+    border-left: 3px solid #3a7bd5;
+}
+
+.message.mine {
+    background: rgba(0, 210, 255, 0.15);
+    border-left-color: #00d2ff;
+}
+
+.message .username {
+    color: #00d2ff;
+    font-size: 0.85rem;
+    font-weight: bold;
+}
+
+.message .text {
+    color: #fff;
+}
+
+.input-area {
+    display: flex;
+    gap: 0.5rem;
+    padding: 1rem;
+    border-top: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.message-input {
+    flex: 1;
+    padding: 0.75rem 1rem;
+    font-size: 1rem;
+    border: none;
+    border-radius: 50px;
+    background: rgba(255, 255, 255, 0.1);
+    color: #fff;
+    outline: none;
+    transition: background 0.2s;
+}
+
+.message-input::placeholder {
+    color: rgba(255, 255, 255, 0.5);
+}
+
+.message-input:focus {
+    background: rgba(255, 255, 255, 0.15);
+}

package/example/ExpressJs/README.md

@@ -33,25 +33,23 @@ npm i api-ape
 ```js
 const express = require('express')
 const ape = require('api-ape')
-const { online, broadcast } = require('api-ape/server/lib/broadcast')
 
 const app = express()
+const server = app.listen(3000)
 
-ape(app, {
+ape(server, {
   where: 'api',
   onConnent: (socket, req, send) => {
     // Push history + user count on connect
     const { _messages } = require('./api/message')
-    send('init', { history: _messages, users: online() })
-    broadcast('users', { count: online() })
+    send('init', { history: _messages, users: ape.online() })
+    ape.broadcast('users', { count: ape.online() })
 
     return {
-      onDisconnent: () => broadcast('users', { count: online() })
+      onDisconnent: () => ape.broadcast('users', { count: ape.online() })
     }
   }
 })
-
-app.listen(3000)
 ```
 
 ### Controller (api/message.js)

package/example/ExpressJs/backend.js

@@ -1,32 +1,15 @@
 const express = require('express')
-const scribbles = require('scribbles')
-const net = require('net')
 const path = require('path')
 const ape = require('api-ape')
 
 const app = express()
 
-const { online, broadcast } = require('api-ape/server/lib/broadcast')
-
-ape(app, {
-  where: 'api',
-  onConnent: (socket, req, send) => {
-    // Send history + user count on connect
-    const { _messages } = require('./api/message')
-    setTimeout(() => {
-      send('init', { history: _messages, users: online() })
-      broadcast('users', { count: online() })
-    }, 100)
-
-    return {
-      onDisconnent: () => broadcast('users', { count: online() })
-    }
-  }
-})
-
+// Serve static files
 app.get('/', (req, res) => res.sendFile(path.join(__dirname, 'index.html')))
 app.get('/styles.css', (req, res) => res.sendFile(path.join(__dirname, 'styles.css')))
 
+// Find available port
+const net = require('net')
 const findPort = (port, cb) => {
   const server = net.createServer()
   server.once('error', () => findPort(port + 1, cb))
@@ -34,4 +17,23 @@ const findPort = (port, cb) => {
   server.listen(port)
 }
 
-findPort(3000, port => app.listen(port, () => scribbles.log(`http://localhost:${port}`)))
+findPort(3000, port => {
+  // Create HTTP server from Express app
+  const server = app.listen(port, () => console.log(`http://localhost:${port}`))
+
+  // Initialize api-ape with the HTTP server
+  ape(server, {
+    where: 'api',
+    onConnent: (socket, req, send) => {
+      const { _messages } = require('./api/message')
+      setTimeout(() => {
+        send('init', { history: _messages, users: ape.online() })
+        ape.broadcast('users', { count: ape.online() })
+      }, 100)
+
+      return {
+        onDisconnent: () => ape.broadcast('users', { count: ape.online() })
+      }
+    }
+  })
+})

package/example/NextJs/ape/client.js

@@ -45,15 +45,15 @@ async function initClient() {
     const port = window.location.port || (window.location.protocol === 'https:' ? 443 : 80)
     connectSocket.configure({ port: parseInt(port, 10) })
 
-    // Connect and get sender/receiver
-    const { sender, setOnReciver } = connectSocket()
+    // Connect and get sender/receiver/connection state
+    const { sender, setOnReciver, onConnectionChange } = connectSocket()
 
     // Enable auto-reconnect
     connectSocket.autoReconnect()
 
     console.log('🦍 api-ape client initialized')
 
-    return { sender, setOnReciver, connectSocket }
+    return { sender, setOnReciver, onConnectionChange, connectSocket }
 }
 
 /**