api-ape 0.0.0 → 1.0.2

package/example/NextJs/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "apiape_example",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "node server.js",
+    "build": "next build",
+    "start": "node server.js",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@types/node": "18.11.13",
+    "@types/react": "18.0.26",
+    "@types/react-dom": "18.0.9",
+    "api-ape": "file:../..",
+    "eslint": "8.29.0",
+    "eslint-config-next": "13.0.6",
+    "express": "^4.18.2",
+    "next": "13.0.6",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "typescript": "4.9.4",
+    "ws": "^8.14.0"
+  }
+}

package/example/NextJs/pages/Info.tsx

@@ -0,0 +1,153 @@
+import styles from '../styles/Chat.module.css'
+
+export default function Info() {
+  return (
+    <div className={styles.codeSection}>
+      <h3 className={styles.codeTitle}>📚 How api-ape Works</h3>
+      
+      <div className={styles.gridContainer}>
+        <div className={styles.gridLayout}>
+          {/* Top Left: Key Concepts */}
+          <div>
+            <h4 className={styles.sectionHeading}>
+              💡 Key Concepts
+            </h4>
+            <pre className={styles.code}>
+              {`• Proxy Pattern: api.message() → api/message.js
+• Auto-wiring: Drop files in api/ folder, they become endpoints
+• Promises: All calls return Promises automatically
+• Broadcasts: Use this.broadcast() or this.broadcastOthers()
+• Context: this.broadcast, this.hostId, this.req available in controllers
+• Auto-reconnect: Client reconnects automatically on disconnect`}
+            </pre>
+          </div>
+
+          {/* Top Right: Data Flow */}
+          <div>
+            <h4 className={styles.sectionHeadingLarge}>
+              🔄 Data Flow
+            </h4>
+            <div className={styles.dataFlowGrid}>
+              {/* Column Headers */}
+              <div className={styles.columnHeaderClient}>
+                Client
+              </div>
+              <div className={styles.gridCell}></div>
+              <div className={styles.columnHeaderServer}>
+                Server
+              </div>
+
+              {/* Step 1: Client sends */}
+              <div className={styles.clientBoxSpan3}>
+                api.message(data)
+              </div>
+              <div className={styles.arrowContainerRow2}>
+                <div className={styles.arrowLineSend}></div>
+                <span className={styles.arrowLabelBlue}>Send</span>
+                <div className={styles.arrowHeadRight}></div>
+              </div>
+              <div className={styles.emptyGridCell}></div>
+
+              {/* Step 2: Server receives */}
+              <div className={styles.emptyGridCellRow3}></div>
+              <div className={styles.arrowContainerRow3}>
+                <div className={styles.arrowHeadLeft}></div>
+                <span className={styles.arrowLabelGreen}>Return</span>
+                <div className={styles.arrowLineReturn}></div>
+              </div>
+              <div className={styles.serverBoxSpan2}>
+                api/message.js
+              </div>
+
+              {/* Step 3: Server broadcasts */}
+              <div className={styles.emptyGridCellRow4}></div>
+              <div className={styles.arrowContainerRow4}>
+                <div className={styles.arrowLineBroadcast}></div>
+                <span className={styles.arrowLabelGreen}>Broadcast</span>
+                <div className={styles.arrowHeadRight}></div>
+              </div>
+              <div className={styles.serverBoxSpan3}>
+                Broadcast to others
+              </div>
+
+              {/* Step 4: Other clients receive */}
+              <div className={styles.clientBoxSingle}>
+                Other clients
+              </div>
+              <div className={styles.arrowContainerRow5}>
+                <div className={styles.arrowHeadLeftBlue}></div>
+                <span className={styles.arrowLabelBlue}>Broadcast</span>
+                <div className={styles.arrowLineBroadcastReturn}></div>
+              </div>
+              <div className={styles.emptyGridCellRow5}></div>
+
+            </div>
+          </div>
+
+          {/* Bottom Left: Client-Side */}
+          <div>
+            <h4 className={styles.sectionHeading}>
+              🔵 Client-Side (Browser)
+            </h4>
+            <pre className={styles.code}>
+              {`// 1. Initialize api-ape client
+const client = await getApeClient()
+const api = client.sender  // Proxy object
+
+// 2. Call server function - property name = file path
+//    api.message() → calls api/message.js
+api.message({ user: 'Alice', text: 'Hello!' })
+  .then(response => {
+    // Server returned: { ok: true, message: {...} }
+    console.log('Response:', response)
+  })
+  .catch(err => {
+    // Server threw an error
+    console.error('Error:', err)
+  })
+
+// 3. Listen for server broadcasts
+client.setOnReciver('message', ({ data }) => {
+  // Server called: this.broadcastOthers('message', data)
+  // This fires for ALL clients except the sender
+  console.log('Broadcast received:', data.message)
+})`}
+            </pre>
+          </div>
+
+          {/* Bottom Right: Server-Side */}
+          <div>
+            <h4 className={styles.sectionHeading}>
+              🟢 Server-Side (api/message.js)
+            </h4>
+            <pre className={styles.code}>
+              {`// File: api/message.js
+// This function is called when client does: api.message(data)
+
+module.exports = function message(data) {
+  const { user, text } = data
+  
+  // Validate input
+  if (!user || !text) {
+    throw new Error('Missing user or text')
+  }
+  
+  const msg = {
+    user,
+    text,
+    time: new Date().toISOString()
+  }
+  
+  // Broadcast to ALL OTHER clients (not the sender)
+  this.broadcastOthers('message', { message: msg })
+  
+  // Return response to sender (fulfills Promise)
+  return { ok: true, message: msg }
+}`}
+            </pre>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/example/NextJs/pages/_app.tsx

@@ -0,0 +1,6 @@
+import '../styles/globals.css'
+import type { AppProps } from 'next/app'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />
+}

package/example/NextJs/pages/index.tsx

@@ -0,0 +1,264 @@
+/**
+ * 🦍 api-ape Next.js Chat Example
+ * 
+ * This component demonstrates how to use api-ape in a React/Next.js application:
+ * 
+ * 1. **Client Initialization**: Connect to api-ape WebSocket server
+ * 2. **Proxy Pattern**: Use `client.sender` as a Proxy to call server functions
+ * 3. **Event Listeners**: Listen for server broadcasts using `setOnReciver`
+ * 4. **Promise-based Calls**: Server functions return Promises automatically
+ * 
+ * Server-side: api/message.js handles incoming messages and broadcasts to other clients
+ * Client-side: This component sends messages and receives broadcasts
+ * 
+ * Key api-ape concepts:
+ * - `client.sender` is a Proxy - accessing `sender.message()` calls server function
+ * - Property name (`message`) maps to server file: `api/message.js`
+ * - `setOnReciver(type, handler)` listens for server broadcasts
+ * - All calls return Promises - server response is automatically matched by queryId
+ */
+
+import Head from 'next/head'
+import { useState, useEffect, useRef } from 'react'
+import styles from '../styles/Chat.module.css'
+import { getApeClient } from '../ape/client'
+import Info from './Info'
+
+export default function Home() {
+  // Component state
+  const [messages, setMessages] = useState([])
+  const [input, setInput] = useState('')
+  const [username, setUsername] = useState('')
+  const [joined, setJoined] = useState(false)
+  const [userCount, setUserCount] = useState(0)
+  const [sending, setSending] = useState(false)
+  const [connected, setConnected] = useState(false)
+  
+  // Refs
+  const apiRef = useRef(null) // Stores the api-ape sender Proxy
+
+  /**
+   * Initialize api-ape client on component mount
+   * 
+   * This effect:
+   * 1. Gets the api-ape client singleton (connects to WebSocket)
+   * 2. Stores the `sender` Proxy in a ref for later use
+   * 3. Sets up event listeners for server broadcasts
+   * 
+   * The client auto-reconnects if the connection drops.
+   */
+  useEffect(() => {
+    // Skip on server-side rendering
+    if (typeof window === 'undefined') return
+
+    getApeClient().then((client) => {
+      if (!client) return
+
+      /**
+       * Store the sender Proxy
+       * 
+       * `client.sender` is a Proxy object that allows you to call server functions
+       * by accessing properties. For example:
+       * - `sender.message(data)` calls `api/message.js` on the server
+       * - The property name (`message`) maps to the server file path
+       * - All calls return Promises that resolve with the server's response
+       */
+      apiRef.current = client.sender
+      setConnected(true)
+      console.log('🦍 api-ape client connected')
+
+      /**
+       * Set up event listeners for server broadcasts
+       * 
+       * `setOnReciver(type, handler)` listens for broadcasts from the server.
+       * The server can broadcast using `this.broadcast()` or `this.broadcastOthers()`
+       * in controller functions (see api/message.js).
+       * 
+       * Broadcast types:
+       * - 'init': Initial data when client connects (history, user count)
+       * - 'message': New message from another client
+       * - 'users': Updated user count
+       */
+      client.setOnReciver('init', ({ data }) => {
+        // Server sent initial data (happens on connect)
+        setMessages(data.history || [])
+        setUserCount(data.users || 0)
+        console.log('🦍 Initialized with', data.history?.length || 0, 'messages')
+      })
+
+      client.setOnReciver('message', ({ data }) => {
+        // Server broadcasted a new message from another client
+        // This is NOT the response to our own send - it's a broadcast!
+        setMessages(prev => [...prev, data.message])
+      })
+
+      client.setOnReciver('users', ({ data }) => {
+        // Server broadcasted updated user count
+        setUserCount(data.count)
+      })
+    })
+  }, [])
+
+  /**
+   * Send a message to the server
+   * 
+   * This demonstrates the api-ape Proxy pattern:
+   * 
+   * 1. Access `api.message()` - the property name 'message' maps to `api/message.js`
+   * 2. Call it with data - returns a Promise
+   * 3. Server processes the request in `api/message.js`
+   * 4. Server can:
+   *    - Return a value (fulfills the Promise)
+   *    - Broadcast to other clients using `this.broadcastOthers()`
+   *    - Throw an error (rejects the Promise)
+   * 
+   * The Promise resolves with whatever the server function returns.
+   * The server also broadcasts to other clients (see api/message.js).
+   */
+  const sendMessage = (e) => {
+    e.preventDefault()
+    if (!input.trim() || !apiRef.current || sending) return
+
+    const api = apiRef.current
+    setSending(true)
+
+    /**
+     * Call server function using Proxy pattern
+     * 
+     * `api.message({ user, text })`:
+     * - Calls the `message` function in `api/message.js`
+     * - Sends `{ user, text }` as the function argument
+     * - Returns a Promise that resolves with the server's return value
+     * - Server automatically broadcasts to other clients (see api/message.js)
+     * 
+     * The server function receives the data and can:
+     * - Validate input
+     * - Store the message
+     * - Broadcast to others: `this.broadcastOthers('message', { message: msg })`
+     * - Return a response: `return { ok: true, message: msg }`
+     */
+    api.message({ user: username, text: input })
+      .then((response) => {
+        /**
+         * Server responded successfully
+         * 
+         * The response is whatever the server function returned.
+         * In this case, api/message.js returns: `{ ok: true, message: msg }`
+         * 
+         * Note: Other clients receive the message via broadcast (setOnReciver above),
+         * but we add it here from the server's response to show it immediately.
+         */
+        if (response?.message) {
+          setMessages(prev => [...prev, response.message])
+        }
+        setSending(false)
+      })
+      .catch((err) => {
+        /**
+         * Server function threw an error or connection failed
+         * 
+         * Errors from server functions are automatically caught and
+         * the Promise is rejected with the error.
+         */
+        console.error('Send failed:', err)
+        setSending(false)
+      })
+
+    setInput('')
+  }
+
+  /**
+   * Handle user joining the chat
+   * Simply sets the joined state to show the chat interface
+   */
+  const handleJoin = (e) => {
+    e.preventDefault()
+    if (username.trim()) {
+      setJoined(true)
+    }
+  }
+
+  return (
+    <div className={styles.container}>
+      <Head>
+        <title>🦍 api-ape Chat</title>
+        <meta name="description" content="Real-time WebSocket chat using api-ape" />
+      </Head>
+
+      <main className={styles.main}>
+        <h1 className={styles.title}>
+          🦍 <span className={styles.gradient}>api-ape</span> Chat
+        </h1>
+        <p className={styles.subtitle}>
+          {connected ? (
+            userCount === 1 
+              ? '✅ Connected • Only You are online'
+              : userCount > 1
+              ? `✅ Connected • You + ${userCount - 1} are online`
+              : '✅ Connected'
+          ) : '⏳ Connecting...'}
+        </p>
+
+        {!joined ? (
+          <form onSubmit={handleJoin} className={styles.joinForm}>
+            <input
+              type="text"
+              placeholder="Enter your name..."
+              value={username}
+              onChange={(e) => setUsername(e.target.value)}
+              className={styles.input}
+              autoFocus
+            />
+            <button type="submit" className={styles.button} disabled={!connected}>
+              {connected ? 'Join Chat →' : 'Connecting...'}
+            </button>
+          </form>
+        ) : (
+          <div className={styles.chatContainer}>
+            <div className={styles.header}>
+              <span>💬 {username}</span>
+              <span className={styles.userCount}>
+                🟢 {userCount} online
+              </span>
+            </div>
+
+            <div className={styles.messages}>
+              {messages.length === 0 && (
+                <p className={styles.emptyState}>No messages yet. Say hi! 👋</p>
+              )}
+              {messages.map((msg, i) => (
+                <div
+                  key={i}
+                  className={`${styles.message} ${msg.user === username ? styles.myMessage : ''}`}
+                >
+                  <strong className={styles.username}>{msg.user}</strong>
+                  <span>{msg.text}</span>
+                  <span className={styles.time}>
+                    {new Date(msg.time).toLocaleTimeString()}
+                  </span>
+                </div>
+              ))}
+            </div>
+
+            <form onSubmit={sendMessage} className={styles.inputForm}>
+              <input
+                type="text"
+                placeholder="Type a message..."
+                value={input}
+                onChange={(e) => setInput(e.target.value)}
+                className={styles.messageInput}
+                disabled={sending}
+                autoFocus
+              />
+              <button type="submit" className={styles.sendButton} disabled={sending}>
+                {sending ? '...' : 'Send'}
+              </button>
+            </form>
+          </div>
+        )}
+
+        <Info />
+      </main>
+    </div>
+  )
+}

package/example/NextJs/public/vercel.svg

@@ -0,0 +1,4 @@
+<svg width="283" height="64" viewBox="0 0 283 64" fill="none" 
+    xmlns="http://www.w3.org/2000/svg">
+    <path d="M141.04 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.5-8.54 3.5-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-17.99-19-17.99zm-9.46 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9zM248.72 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.5-8.54 3.5-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-17.99-19-17.99zm-9.45 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9zM200.24 34c0 6 3.92 10 10 10 4.12 0 7.21-1.87 8.8-4.92l7.68 4.43c-3.18 5.3-9.14 8.49-16.48 8.49-11.05 0-19-7.2-19-18s7.96-18 19-18c7.34 0 13.29 3.19 16.48 8.49l-7.68 4.43c-1.59-3.05-4.68-4.92-8.8-4.92-6.07 0-10 4-10 10zm82.48-29v46h-9V5h9zM36.95 0L73.9 64H0L36.95 0zm92.38 5l-27.71 48L73.91 5H84.3l17.32 30 17.32-30h10.39zm58.91 12v9.69c-1-.29-2.06-.49-3.2-.49-5.81 0-10 4-10 10V51h-9V17h9v9.2c0-5.08 5.91-9.2 13.2-9.2z" fill="#000"/>
+</svg>

package/example/NextJs/server.js

@@ -0,0 +1,40 @@
+/**
+ * Custom Next.js server using actual api-ape library with Express
+ */
+
+const express = require('express')
+const next = require('next')
+const ape = require('api-ape')
+const { onConnect } = require('./ape/onConnect')
+
+const dev = process.env.NODE_ENV !== 'production'
+const hostname = '0.0.0.0'
+const port = parseInt(process.env.PORT, 10) || 3000
+
+const app = next({ dev, hostname, port })
+const handle = app.getRequestHandler()
+
+app.prepare().then(() => {
+    const server = express()
+
+    // Initialize api-ape - it handles EVERYTHING
+    // Developer never touches WebSocket!
+    ape(server, { where: 'api', onConnent: onConnect })
+
+    // Let Next.js handle all other routes
+    server.all('*', (req, res) => {
+        return handle(req, res)
+    })
+
+    server.listen(port, () => {
+        console.log(`
+╔═══════════════════════════════════════════════════════╗
+║       🦍 api-ape NextJS Demo                          ║
+╠═══════════════════════════════════════════════════════╣
+║  HTTP:      http://localhost:${port}/                  ║
+║  WebSocket: ws://localhost:${port}/api/ape             ║
+║  ape(app, { where: "api", onConnent })                ║
+╚═══════════════════════════════════════════════════════╝
+    `)
+    })
+})