api-ape 2.2.3 → 3.0.0

package/index.d.ts

@@ -50,7 +50,7 @@ export interface ControllerContext {
         os: { name?: string; version?: string }
         device: { type?: string; vendor?: string; model?: string }
     }
-    /** Custom embedded values from onConnent */
+    /** Custom embedded values from onConnect */
     [key: string]: any
 }
 
@@ -63,7 +63,7 @@ export type ControllerFunction<T = any, R = any> = (
 ) => R | Promise<R>
 
 /**
- * Send function provided to onConnent
+ * Send function provided to onConnect
  */
 export type SendFunction = {
     (type: string, data: any): void
@@ -76,7 +76,7 @@ export type SendFunction = {
 export type AfterHook = (err: Error | null, result: any) => void
 
 /**
- * Connection lifecycle hooks returned from onConnent
+ * Connection lifecycle hooks returned from onConnect
  */
 export interface ConnectionHandlers {
     /** Values to embed into controller context */
@@ -88,11 +88,11 @@ export interface ConnectionHandlers {
     /** Called on error */
     onError?: (errorString: string) => void
     /** Called when client disconnects */
-    onDisconnent?: () => void
+    onDisconnect?: () => void
 }
 
 /**
- * onConnent callback signature
+ * onConnect callback signature
  */
 export type OnConnectCallback = (
     socket: ApeWebSocket,
@@ -107,36 +107,225 @@ export interface ApeServerOptions {
     /** Directory containing controller files */
     where: string
     /** Connection lifecycle hook */
-    onConnent?: OnConnectCallback
+    onConnect?: OnConnectCallback
+}
+
+// =============================================================================
+// 🌲 FOREST - DISTRIBUTED MESH TYPES
+// =============================================================================
+
+/**
+ * Supported database client types for Forest adapters
+ */
+export type ForestDatabaseClient =
+    | RedisClient
+    | MongoClient
+    | PostgresPool
+    | SupabaseClient
+    | FirebaseDatabase
+    | ForestCustomAdapter
+
+/** Redis client (node-redis or ioredis) */
+export interface RedisClient {
+    duplicate(): RedisClient
+    publish(channel: string, message: string): Promise<number>
+    subscribe(channel: string): Promise<void>
+    on(event: string, handler: (...args: any[]) => void): void
+}
+
+/** MongoDB client */
+export interface MongoClient {
+    db(name?: string): any
+}
+
+/** PostgreSQL pool (pg) */
+export interface PostgresPool {
+    query(text: string, values?: any[]): Promise<any>
+    connect(): Promise<any>
+}
+
+/** Supabase client */
+export interface SupabaseClient {
+    from(table: string): any
+    channel(name: string): any
+    removeChannel(channel: any): Promise<void>
+}
+
+/** Firebase Realtime Database */
+export interface FirebaseDatabase {
+    ref(path: string): any
+    goOnline?(): void
+    app?: any
+}
+
+/**
+ * Forest adapter instance interface
+ */
+export interface ForestAdapterInstance {
+    /** This server's unique ID */
+    readonly serverId: string
+
+    /** Join the distributed mesh */
+    join(serverId?: string): Promise<void>
+
+    /** Leave the mesh and cleanup */
+    leave(): Promise<void>
+
+    /** Client-to-server lookup operations */
+    lookup: {
+        /** Register a client on this server */
+        add(clientId: string): Promise<void>
+        /** Find which server owns a client */
+        read(clientId: string): Promise<string | null>
+        /** Remove a client mapping (must own it) */
+        remove(clientId: string): Promise<void>
+    }
+
+    /** Inter-server channel operations */
+    channels: {
+        /** Push message to a server's channel (empty string = broadcast) */
+        push(serverId: string, message: any): Promise<void>
+        /** Subscribe to a server's channel, returns unsubscribe function */
+        pull(serverId: string, handler: (message: any, senderServerId: string) => void): Promise<() => Promise<void>>
+    }
+}
+
+/**
+ * Custom adapter interface for implementing your own Forest adapter
+ */
+export interface ForestCustomAdapter {
+    join(serverId: string): Promise<void>
+    leave(): Promise<void>
+    lookup: {
+        add(clientId: string): Promise<void>
+        read(clientId: string): Promise<string | null>
+        remove(clientId: string): Promise<void>
+    }
+    channels: {
+        push(serverId: string, message: any): Promise<void>
+        pull(serverId: string, handler: (message: any, senderServerId: string) => void): Promise<() => Promise<void>>
+    }
+}
+
+/**
+ * Options for joinVia()
+ */
+export interface ForestOptions {
+    /** Prefix for keys/tables (default: 'ape') */
+    namespace?: string
+    /** Custom server ID (default: auto-generated) */
+    serverId?: string
 }
 
 /**
  * Initialize api-ape on a Node.js HTTP/HTTPS server
+ * 
+ * V3 Breaking Change:
+ * Old: const ape = require('api-ape')
+ * New: const { ape } = require('api-ape')
  */
 declare function ape(server: HttpServer, options: ApeServerOptions): void
 
 declare namespace ape {
     /** Broadcast to all connected clients */
     export function broadcast(type: string, data: any, excludeClientId?: string): void
-    /** Get count of connected clients */
-    export function online(): number
-    /** Get all connected client clientIds */
-    export function getClients(): string[]
+
+    /**
+     * Read-only Map of connected clients
+     * Each ClientWrapper provides: clientId, sessionId, embed, agent, sendTo(type, data)
+     */
+    export const clients: ReadonlyMap<string, ClientWrapper>
+
+    // =========================================================================
+    // 🌲 FOREST - DISTRIBUTED MESH
+    // =========================================================================
+
+    /**
+     * Join the distributed mesh for multi-server coordination.
+     * Pass any supported database client - APE auto-detects the type.
+     * 
+     * @example
+     * // Redis
+     * ape.joinVia(redisClient);
+     * 
+     * // With options
+     * ape.joinVia(mongoClient, { namespace: 'myapp', serverId: 'srv-1' });
+     * 
+     * // Custom adapter
+     * ape.joinVia({ join, leave, lookup, channels });
+     */
+    export function joinVia(client: ForestDatabaseClient, options?: ForestOptions): Promise<ForestAdapterInstance>
+
+    /**
+     * Leave the distributed mesh gracefully.
+     * Removes all client mappings and unsubscribes from channels.
+     */
+    export function leaveCluster(): Promise<void>
+
+    /**
+     * Current Forest adapter instance (null if not joined)
+     */
+    export const cluster: ForestAdapterInstance | null
+
+    /**
+     * This server's ID in the cluster (null if not joined)
+     */
+    export const serverId: string | null
 
     // Browser client methods (available when imported in browser context)
     /** Subscribe to broadcasts from the server */
     export function on<T = any>(type: string, handler: (message: { err?: Error; type: string; data: T }) => void): void
     /** Subscribe to connection state changes. Returns unsubscribe function. */
     export function onConnectionChange(handler: (state: 'offline' | 'walled' | 'disconnected' | 'connecting' | 'connected') => void): () => void
-    /** Get current transport type */
-    export function getTransport(): 'websocket' | 'polling' | null
+    /** Current transport type (read-only) */
+    export const transport: 'websocket' | 'polling' | null
 
     /** Call any server function dynamically (browser only) */
     export function message<T = any, R = any>(data?: T): Promise<R>
 }
 
-// Server-side default export (also works as browser client proxy)
-export default ape
+// =============================================================================
+// SERVER-SIDE CLIENT (api - same interface as browser)
+// =============================================================================
+
+/**
+ * Server-side client for connecting to other api-ape servers
+ * 100% identical interface to the browser client
+ * 
+ * @example
+ * import api from 'api-ape'
+ * 
+ * // Configure connection (or set APE_SERVER env)
+ * api.connect('ws://other-server:3000/api/ape')
+ * 
+ * // Same usage as browser
+ * const result = await api.hello('World')
+ * api.on('message', (data) => console.log(data))
+ */
+export interface ApeServerClient extends ApeSender {
+    /** Subscribe to broadcasts from the remote server */
+    on<T = any>(type: string, handler: MessageHandler<T>): void
+    on(handler: MessageHandler): void
+    /** Subscribe to connection state changes */
+    onConnectionChange(handler: (state: ConnectionState) => void): () => void
+    /** Connect to a server (or set APE_SERVER env) */
+    connect(url: string): void
+    /** Close the connection */
+    close(): void
+    /** Current transport type (read-only) */
+    readonly transport: 'websocket' | null
+}
+
+/**
+ * The api client - works identically on browser and server
+ */
+declare const api: ApeServerClient
+
+// Named export for V3 (Server usage: const { ape } = require('api-ape'))
+export { ape, api }
+
+// Default export: api client (same interface on browser and server)
+export default api
 
 // =============================================================================
 // BROWSER CLIENT (Default export in browser context)
@@ -161,8 +350,8 @@ export interface ApeBrowserClient extends ApeSender {
     /** Subscribe to connection state changes. Returns unsubscribe function. */
     onConnectionChange(handler: (state: ConnectionState) => void): () => void
 
-    /** Get current transport type ('websocket' | 'polling' | null) */
-    getTransport(): TransportType | null
+    /** Current transport type (read-only) */
+    readonly transport: TransportType | null
 }
 
 // =============================================================================
@@ -221,11 +410,11 @@ export type SetOnReceiver = {
  */
 export interface ApeClient {
     sender: ApeSender
-    setOnReciver: SetOnReceiver
+    setOnReceiver: SetOnReceiver
     /** Subscribe to connection state changes. Returns unsubscribe function. */
     onConnectionChange: (handler: (state: ConnectionState) => void) => () => void
-    /** Get current transport type ('websocket' | 'polling' | null) */
-    getTransport: () => TransportType | null
+    /** Current transport type (read-only) */
+    readonly transport: TransportType | null
 }
 
 /**
@@ -256,5 +445,24 @@ export { connectSocket }
 // =============================================================================
 
 export declare const broadcast: (type: string, data: any) => void
-export declare const online: () => number
-export declare const getClients: () => string[]
+export declare const clients: ReadonlyMap<string, ClientWrapper>
+
+/**
+ * Client wrapper providing client info and sendTo function
+ */
+export interface ClientWrapper {
+    /** Unique client identifier */
+    readonly clientId: string
+    /** Session ID from cookie (set by outer framework) */
+    readonly sessionId: string | null
+    /** Embedded values from onConnect */
+    readonly embed: Record<string, any>
+    /** Parsed user-agent info */
+    readonly agent: {
+        browser: { name?: string; version?: string }
+        os: { name?: string; version?: string }
+        device: { type?: string; vendor?: string; model?: string }
+    }
+    /** Send a message to this specific client */
+    sendTo(type: string, data: any): void
+}

package/index.js

@@ -1,11 +1,26 @@
+/**
+ * api-ape unified entry point
+ * 
+ * V3 Server Usage:
+ *   const api = require('api-ape')              // Client factory (default)
+ *   const { ape } = require('api-ape')          // Server initializer (named)
+ *   import api, { ape } from 'api-ape'          // ESM both
+ * 
+ * Browser Usage:
+ *   import api from 'api-ape'                   // Auto-connecting client
+ */
 
 let apiApe;
 
 if ('undefined' === typeof window
   || 'undefined' === typeof window.document) {
+  // Server environment - exports: api (default), ape, broadcast, clients, createClient
   apiApe = require('./server');
 } else {
+  // Browser environment - client module has its own exports
   apiApe = require('./client');
 }
 
 module.exports = apiApe
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-ape",
-  "version": "2.2.3",
+  "version": "3.0.0",
   "description": "Remote Procedure Events (RPE) - A lightweight WebSocket framework for building real-time APIs. Call server functions from the browser like local methods with automatic reconnection, HTTP streaming fallback, and extended JSON encoding.",
   "main": "index.js",
   "browser": "./client/index.js",
@@ -69,4 +69,4 @@
     "esbuild": "^0.27.2",
     "jest": "^29.3.1"
   }
-}
+}