api-ape 2.0.0 → 2.2.2

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

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

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

package/example/Vite/src/style.css

@@ -1,200 +0,0 @@
-* {
-    box-sizing: border-box;
-    margin: 0;
-    padding: 0;
-}
-
-.container {
-    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;
-}
-
-.main {
-    max-width: 600px;
-    margin: 0 auto;
-    padding: 2rem;
-    width: 100%;
-}
-
-.title {
-    font-size: 2.5rem;
-    text-align: center;
-    margin-bottom: 0.5rem;
-}
-
-.gradient {
-    background: linear-gradient(90deg, #00d2ff, #3a7bd5);
-    -webkit-background-clip: text;
-    -webkit-text-fill-color: transparent;
-    background-clip: text;
-}
-
-.subtitle {
-    text-align: center;
-    color: #0f0;
-    margin-bottom: 2rem;
-    font-weight: bold;
-}
-
-.join-form {
-    display: flex;
-    gap: 1rem;
-    justify-content: center;
-}
-
-.input {
-    padding: 1rem 1.5rem;
-    font-size: 1rem;
-    border: none;
-    border-radius: 50px;
-    background: rgba(255, 255, 255, 0.1);
-    color: #fff;
-    outline: none;
-    width: 250px;
-}
-
-.input::placeholder {
-    color: rgba(255, 255, 255, 0.5);
-}
-
-.button {
-    padding: 1rem 2rem;
-    font-size: 1rem;
-    border: none;
-    border-radius: 50px;
-    background: linear-gradient(90deg, #00d2ff, #3a7bd5);
-    color: #fff;
-    cursor: pointer;
-    font-weight: bold;
-    transition: opacity 0.2s;
-}
-
-.button:hover {
-    opacity: 0.9;
-}
-
-.button:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-}
-
-.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;
-    padding: 1rem 1.5rem;
-    background: rgba(255, 255, 255, 0.1);
-    font-weight: bold;
-}
-
-.user-count {
-    font-size: 0.85rem;
-    color: #0f0;
-}
-
-.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;
-}
-
-.my-message {
-    background: rgba(0, 210, 255, 0.15);
-    border-left-color: #00d2ff;
-}
-
-.message .username {
-    color: #00d2ff;
-    font-size: 0.85rem;
-}
-
-.message .time {
-    color: #666;
-    font-size: 0.7rem;
-}
-
-.input-form {
-    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);
-}
-
-.send-button {
-    padding: 0.75rem 1.5rem;
-    font-size: 1rem;
-    border: none;
-    border-radius: 50px;
-    background: #3a7bd5;
-    color: #fff;
-    cursor: pointer;
-    font-weight: bold;
-    transition: opacity 0.2s;
-}
-
-.send-button:hover {
-    opacity: 0.9;
-}
-
-.send-button:disabled {
-    opacity: 0.5;
-    cursor: not-allowed;
-}

package/example/Vite/src/vite-env.d.ts

@@ -1,7 +0,0 @@
-/// <reference types="vite/client" />
-
-declare module '*.vue' {
-    import type { DefineComponent } from 'vue'
-    const component: DefineComponent<{}, {}, any>
-    export default component
-}

package/example/Vite/vite.config.ts

@@ -1,20 +0,0 @@
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-
-export default defineConfig({
-    plugins: [vue()],
-    server: {
-        port: 5173,
-        proxy: {
-            '/api': {
-                target: 'http://localhost:3000',
-                ws: true,
-                changeOrigin: true
-            }
-        }
-    },
-    build: {
-        outDir: 'dist',
-        emptyOutDir: true
-    }
-})

package/todo.md

@@ -1,85 +0,0 @@
-# Query System - TODO
-
-A fluent, chainable query API for api-ape with filtering, field selection, and real-time subscriptions.
-
----
-
-## Client API Design
-```js
-const petsReq = ape.pets.list(data, (item) => shouldSubscribe)
-      petsReq.filter`name ! ${undefined} AND bio.checkin > ${10} OR bio.type = ${"admin"}`
-      petsReq.fields("*", {bio: ["email"]})
-      petsReq.then(pets => ...).catch(err => ...)
-```
-
----
-
-## Phase 1: Filter Parser
-- [ ] Create `client/utils/filter.js` - tagged template parser
-- [ ] Parse operators: `=`, `!` (not equal), `?` (exists), `>`, `<`
-- [ ] Parse `AND` / `OR` with correct precedence
-- [ ] Support nested paths (e.g., `bio.checkin`, `owner.type`)
-- [ ] Return serializable filter object to send over wire
-
-## Phase 2: Fields Selection  
-- [ ] Parse `fields("*", {relation: ["field1", "field2"]})`
-- [ ] `"*"` = all root-level fields
-- [ ] Object syntax for nested/related field selection
-- [ ] Max depth limit (≤ 4)
-
-## Phase 3: Query Builder (Client)
-- [ ] Refactor `client/index.js` → proper query builder
-- [ ] Chainable `.filter()` and `.fields()` methods
-- [ ] Integrate with existing `connectSocket.js` sender
-- [ ] Send query payload: `{ type, data, filter, fields, subscribe }`
-
-## Phase 4: Subscription Callback
-- [ ] Second arg: `(item) => boolean` subscription predicate
-- [ ] Register listener via `setOnReciver` for matching type
-- [ ] Filter incoming broadcasts client-side with predicate
-
-## Phase 5: Server Query Execution
-- [ ] Parse incoming `filter` object
-- [ ] Apply filter to controller response data
-- [ ] Respect `fields` selection (project/limit returned data)
-- [ ] Track subscribed queryIds for broadcast targeting
-
-## Phase 6: Skip/Have Optimization (Future)
-- [ ] `.dont([id1, id2])` - skip items client already has
-- [ ] Server tracks live refs per client
-- [ ] Only send missing/changed items
-
----
-
-## Open Questions
-
-### Query Method Semantics
-- `ape.pets.list(null, (pet) => { pet.owner == me })`:
-  - [ ] What does the first argument (`null`) represent? Initial filter data? Query options?
-  - [ ] What does the callback do? Live subscription filter? Server-side predicate?
-
-### Filter Syntax
-- `.filter\`name ! ${undefined} AND owner.checkin > ${10} OR owner.type = ${"nice"}\``:
-  - [ ] Confirm operators: `!` = not equal, `?` = exists, `>` `<` `=` = comparison
-  - [ ] Need additional operators? `>=`, `<=`, `LIKE`, `IN`, `BETWEEN`?
-  - [ ] Should `AND`/`OR` respect standard boolean precedence?
-  - [ ] Should `${10}DaysAgo` be a special relative time syntax?
-
-### Fields Selection
-- `.fields("*", {toys: ["type"]})`:
-  - [ ] `"*"` = all fields at root level?
-  - [ ] Object syntax `{relation: [...]}` for nested/related fields?
-  - [ ] Max depth limit? (code comment says ≤ 4)
-  - [ ] Support exclusion? (e.g., `"-password"`)
-
-### Real-time Subscriptions
-- [ ] How should live updates work? Push on any change to matching items?
-- [ ] Can the subscription filter differ from the initial query filter?
-- [ ] What events trigger updates? Create, Update, Delete?
-- [ ] Broadcast filtering - server-side or client-side predicate eval?
-
-### Additional Features (In Scope?)
-- [ ] Pagination: `.limit()`, `.offset()`, `.cursor()`
-- [ ] Sorting: `.orderBy()`
-- [ ] Aggregations: `.count()`, `.sum()`
-- [ ] Skip/Have optimization: `.dont([ids])` for delta updates