api-ape 2.0.0 → 2.2.2

package/example/NextJs/package.json

@@ -1,24 +0,0 @@
-{
-  "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",
-    "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

@@ -1,153 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,275 +0,0 @@
-/**
- * 🦍 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 [connectionState, setConnectionState] = useState('connecting')
-
-  // 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
-      console.log('🦍 api-ape client connected')
-
-      /**
-       * Subscribe to connection state changes
-       * 
-       * `onConnectionChange` gets called with the current state immediately,
-       * then on each state transition. States: 'disconnected' | 'connecting' | 'connected'
-       */
-      const unsubscribe = client.onConnectionChange(setConnectionState)
-
-      /**
-       * 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)
-      })
-
-      return () => unsubscribe()
-    })
-  }, [])
-
-  /**
-   * 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}>
-          {connectionState === 'connected' ? (
-            userCount === 1
-              ? '✅ Connected • Only You are online'
-              : userCount > 1
-                ? `✅ Connected • You + ${userCount - 1} are online`
-                : '✅ Connected'
-          ) : connectionState === 'connecting'
-            ? '⏳ Connecting...'
-            : '❌ Disconnected'}
-        </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={connectionState !== 'connected'}>
-              {connectionState === '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

@@ -1,4 +0,0 @@
-<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

@@ -1,36 +0,0 @@
-/**
- * Custom Next.js server using api-ape library without Express
- */
-
-const { createServer } = require('http')
-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 = createServer((req, res) => {
-        return handle(req, res)
-    })
-
-    // Initialize api-ape with the raw http server
-    ape(server, { where: 'api', onConnent: onConnect })
-
-    server.listen(port, () => {
-        console.log(`
-╔═══════════════════════════════════════════════════════╗
-║       🦍 api-ape NextJS Demo                          ║
-╠═══════════════════════════════════════════════════════╣
-║  HTTP:      http://localhost:${port}/                  ║
-║  WebSocket: ws://localhost:${port}/api/ape             ║
-║  ape(server, { where: "api", onConnent })             ║
-╚═══════════════════════════════════════════════════════╝
-    `)
-    })
-})