api-ape 1.1.0 → 2.0.0

package/example/Vite/src/App.vue

@@ -0,0 +1,170 @@
+<script setup lang="ts">
+/**
+ * 🦍 api-ape Vue Chat Example
+ * 
+ * This component demonstrates how to use api-ape in a Vue 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
+ */
+
+import { ref, onMounted } from 'vue'
+import { getApeClient } from '../ape/client'
+import Info from './components/Info.vue'
+
+interface Message {
+  user: string
+  text: string
+  time: string
+}
+
+// Component state
+const messages = ref<Message[]>([])
+const input = ref('')
+const username = ref('')
+const joined = ref(false)
+const userCount = ref(0)
+const sending = ref(false)
+const connectionState = ref<'disconnected' | 'connecting' | 'connected'>('connecting')
+
+// Store the api-ape sender Proxy
+let api: any = null
+
+onMounted(async () => {
+  const client = await getApeClient()
+  if (!client) return
+
+  // Store the sender Proxy
+  api = client.sender
+  console.log('🦍 api-ape client connected')
+
+  // Subscribe to connection state changes
+  client.onConnectionChange((state: string) => {
+    connectionState.value = state as any
+  })
+
+  // Set up event listeners for server broadcasts
+  client.setOnReciver('init', ({ data }: { data: { history: Message[], users: number } }) => {
+    messages.value = data.history || []
+    userCount.value = data.users || 0
+    console.log('🦍 Initialized with', data.history?.length || 0, 'messages')
+  })
+
+  client.setOnReciver('message', ({ data }: { data: { message: Message } }) => {
+    messages.value.push(data.message)
+  })
+
+  client.setOnReciver('users', ({ data }: { data: { count: number } }) => {
+    userCount.value = data.count
+  })
+})
+
+async function sendMessage() {
+  if (!input.value.trim() || !api || sending.value) return
+
+  sending.value = true
+
+  try {
+    const response = await api.message({ user: username.value, text: input.value })
+    if (response?.message) {
+      messages.value.push(response.message)
+    }
+  } catch (err) {
+    console.error('Send failed:', err)
+  } finally {
+    sending.value = false
+  }
+
+  input.value = ''
+}
+
+function handleJoin() {
+  if (username.value.trim()) {
+    joined.value = true
+  }
+}
+
+function formatTime(time: string) {
+  return new Date(time).toLocaleTimeString()
+}
+
+function getConnectionStatus() {
+  if (connectionState.value === 'connected') {
+    if (userCount.value === 1) return '✅ Connected • Only You are online'
+    if (userCount.value > 1) return `✅ Connected • You + ${userCount.value - 1} are online`
+    return '✅ Connected'
+  }
+  if (connectionState.value === 'connecting') return '⏳ Connecting...'
+  return '❌ Disconnected'
+}
+</script>
+
+<template>
+  <div class="container">
+    <main class="main">
+      <h1 class="title">
+        🦍 <span class="gradient">api-ape</span> Chat
+      </h1>
+      <p class="subtitle">{{ getConnectionStatus() }}</p>
+
+      <!-- Join Form -->
+      <form v-if="!joined" @submit.prevent="handleJoin" class="join-form">
+        <input
+          type="text"
+          placeholder="Enter your name..."
+          v-model="username"
+          class="input"
+          autofocus
+        />
+        <button 
+          type="submit" 
+          class="button" 
+          :disabled="connectionState !== 'connected'"
+        >
+          {{ connectionState === 'connected' ? 'Join Chat →' : 'Connecting...' }}
+        </button>
+      </form>
+
+      <!-- Chat Interface -->
+      <div v-else class="chat-container">
+        <div class="header">
+          <span>💬 {{ username }}</span>
+          <span class="user-count">🟢 {{ userCount }} online</span>
+        </div>
+
+        <div class="messages">
+          <p v-if="messages.length === 0" class="empty-state">
+            No messages yet. Say hi! 👋
+          </p>
+          <div
+            v-for="(msg, i) in messages"
+            :key="i"
+            :class="['message', msg.user === username ? 'my-message' : '']"
+          >
+            <strong class="username">{{ msg.user }}</strong>
+            <span>{{ msg.text }}</span>
+            <span class="time">{{ formatTime(msg.time) }}</span>
+          </div>
+        </div>
+
+        <form @submit.prevent="sendMessage" class="input-form">
+          <input
+            type="text"
+            placeholder="Type a message..."
+            v-model="input"
+            class="message-input"
+            :disabled="sending"
+            autofocus
+          />
+          <button type="submit" class="send-button" :disabled="sending">
+            {{ sending ? '...' : 'Send' }}
+          </button>
+        </form>
+      </div>
+
+      <Info />
+    </main>
+  </div>
+</template>

package/example/Vite/src/components/Info.vue

@@ -0,0 +1,352 @@
+<script setup lang="ts">
+/**
+ * Info component - explains how api-ape works
+ */
+</script>
+
+<template>
+  <div class="code-section">
+    <h3 class="code-title">📚 How api-ape Works</h3>
+    
+    <div class="grid-container">
+      <div class="grid-layout">
+        <!-- Top Left: Key Concepts -->
+        <div>
+          <h4 class="section-heading">💡 Key Concepts</h4>
+          <pre class="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 class="section-heading-large">🔄 Data Flow</h4>
+          <div class="data-flow-grid">
+            <!-- Column Headers -->
+            <div class="column-header-client">Client</div>
+            <div class="grid-cell"></div>
+            <div class="column-header-server">Server</div>
+
+            <!-- Step 1: Client sends -->
+            <div class="client-box-span3">api.message(data)</div>
+            <div class="arrow-container-row2">
+              <div class="arrow-line-send"></div>
+              <span class="arrow-label-blue">Send</span>
+              <div class="arrow-head-right"></div>
+            </div>
+            <div class="empty-grid-cell"></div>
+
+            <!-- Step 2: Server receives -->
+            <div class="empty-grid-cell-row3"></div>
+            <div class="arrow-container-row3">
+              <div class="arrow-head-left"></div>
+              <span class="arrow-label-green">Return</span>
+              <div class="arrow-line-return"></div>
+            </div>
+            <div class="server-box-span2">api/message.js</div>
+
+            <!-- Step 3: Server broadcasts -->
+            <div class="empty-grid-cell-row4"></div>
+            <div class="arrow-container-row4">
+              <div class="arrow-line-broadcast"></div>
+              <span class="arrow-label-green">Broadcast</span>
+              <div class="arrow-head-right"></div>
+            </div>
+            <div class="server-box-span3">Broadcast to others</div>
+
+            <!-- Step 4: Other clients receive -->
+            <div class="client-box-single">Other clients</div>
+            <div class="arrow-container-row5">
+              <div class="arrow-head-left-blue"></div>
+              <span class="arrow-label-blue">Broadcast</span>
+              <div class="arrow-line-broadcast-return"></div>
+            </div>
+            <div class="empty-grid-cell-row5"></div>
+          </div>
+        </div>
+
+        <!-- Bottom Left: Client-Side -->
+        <div>
+          <h4 class="section-heading">🔵 Client-Side (Browser)</h4>
+          <pre class="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 class="section-heading">🟢 Server-Side (api/message.js)</h4>
+          <pre class="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>
+</template>
+
+<style scoped>
+.code-section {
+  margin-top: 2rem;
+}
+
+.code-title {
+  margin-bottom: 0.5rem;
+  color: #0f0;
+}
+
+.grid-container {
+  max-width: 1200px;
+  margin: 1.5rem auto 0;
+  padding: 0 1rem;
+  width: 100%;
+  box-sizing: border-box;
+}
+
+.grid-layout {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 2rem;
+  width: 100%;
+}
+
+@media (min-width: 768px) {
+  .grid-layout {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+
+.section-heading {
+  margin-bottom: 0.5rem;
+  font-size: 0.9rem;
+  font-weight: bold;
+}
+
+.section-heading-large {
+  margin-bottom: 1rem;
+  font-size: 0.9rem;
+  font-weight: bold;
+}
+
+.code {
+  background: rgba(0, 0, 0, 0.4);
+  padding: 1.5rem;
+  border-radius: 12px;
+  font-size: 0.75rem;
+  color: #0f0;
+  overflow: auto;
+  white-space: pre-wrap;
+  font-family: monospace;
+}
+
+.data-flow-grid {
+  display: grid;
+  grid-template-columns: 200px 1fr 200px;
+  grid-template-rows: auto auto auto auto auto;
+  gap: 1rem;
+  align-items: stretch;
+}
+
+.column-header-client {
+  font-size: 0.8rem;
+  font-weight: bold;
+  text-align: center;
+  grid-row: 1;
+  grid-column: 1;
+  color: #00d2ff;
+}
+
+.column-header-server {
+  font-size: 0.8rem;
+  font-weight: bold;
+  text-align: center;
+  grid-row: 1;
+  grid-column: 3;
+  color: #00e676;
+}
+
+.client-box-span3 {
+  background: linear-gradient(135deg, #3a7bd5, #00d2ff);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(58, 123, 213, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 1;
+  grid-row: 2 / 5;
+}
+
+.client-box-single {
+  background: linear-gradient(135deg, #3a7bd5, #00d2ff);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(58, 123, 213, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 1;
+  grid-row: 5;
+}
+
+.server-box-span2 {
+  background: linear-gradient(135deg, #00c851, #00e676);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(0, 200, 81, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 3;
+  grid-row: 2 / 4;
+}
+
+.server-box-span3 {
+  background: linear-gradient(135deg, #00c851, #00e676);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: bold;
+  box-shadow: 0 4px 12px rgba(0, 200, 81, 0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  grid-column: 3;
+  grid-row: 4 / 6;
+}
+
+.arrow-container-row2,
+.arrow-container-row3,
+.arrow-container-row4,
+.arrow-container-row5 {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  grid-column: 2;
+}
+
+.arrow-container-row2 { grid-row: 2; }
+.arrow-container-row3 { grid-row: 3; }
+.arrow-container-row4 { grid-row: 4; }
+.arrow-container-row5 { grid-row: 5; }
+
+.arrow-line-send {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, #00d2ff, #00e676);
+}
+
+.arrow-line-return {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, #00e676, transparent);
+}
+
+.arrow-line-broadcast {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, transparent, #00e676);
+}
+
+.arrow-line-broadcast-return {
+  flex: 1;
+  height: 2px;
+  background: linear-gradient(90deg, #00d2ff, transparent);
+}
+
+.arrow-label-blue {
+  font-size: 0.7rem;
+  white-space: nowrap;
+  padding: 0 0.5rem;
+  color: #00d2ff;
+}
+
+.arrow-label-green {
+  font-size: 0.7rem;
+  white-space: nowrap;
+  padding: 0 0.5rem;
+  color: #00e676;
+}
+
+.arrow-head-right {
+  width: 0;
+  height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-left: 8px solid #00e676;
+}
+
+.arrow-head-left {
+  width: 0;
+  height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-right: 8px solid #00e676;
+}
+
+.arrow-head-left-blue {
+  width: 0;
+  height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-right: 8px solid #00d2ff;
+}
+
+.empty-grid-cell { grid-row: 2; grid-column: 3; }
+.empty-grid-cell-row3 { grid-row: 3; grid-column: 1; }
+.empty-grid-cell-row4 { grid-row: 4; grid-column: 1; }
+.empty-grid-cell-row5 { grid-row: 5; grid-column: 3; }
+</style>

package/example/Vite/src/main.ts

@@ -0,0 +1,5 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+import './style.css'
+
+createApp(App).mount('#app')