dzql 0.1.0-alpha.3 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -15,6 +15,8 @@
     "src/database/migrations/**/*.sql",
     "README.md",
     "GETTING_STARTED.md",
+    "REFERENCE.md",
+    "CLAUDE.md",
     "LICENSE"
   ],
   "scripts": {
@@ -25,7 +27,6 @@
     "jose": "^6.1.0",
     "postgres": "^3.4.7"
   },
-
   "keywords": [
     "postgresql",
     "postgres",
@@ -61,7 +62,6 @@
     "bun": ">=1.0.0"
   },
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   }
 }

package/src/client/ws.js

@@ -1,5 +1,58 @@
+/**
+ * WebSocket manager for DZQL client-side real-time communication
+ *
+ * Provides:
+ * - WebSocket connection management with auto-reconnect
+ * - JSON-RPC 2.0 protocol for API calls
+ * - Proxy-based API matching server-side db.api pattern
+ * - Real-time broadcast event handling
+ * - Automatic JWT authentication
+ *
+ * @class WebSocketManager
+ *
+ * @example
+ * // Basic usage
+ * import { WebSocketManager } from 'dzql/client';
+ *
+ * const ws = new WebSocketManager();
+ * await ws.connect('ws://localhost:3000/ws');
+ *
+ * // Login
+ * const session = await ws.api.login_user({
+ *   email: 'user@example.com',
+ *   password: 'password123'
+ * });
+ *
+ * // CRUD operations
+ * const venue = await ws.api.get.venues({ id: 1 });
+ * const created = await ws.api.save.venues({ name: 'New Venue' });
+ *
+ * // Listen to real-time updates
+ * ws.onBroadcast((method, params) => {
+ *   console.log(`Event: ${method}`, params);
+ * });
+ *
+ * @example
+ * // Advanced search
+ * const results = await ws.api.search.venues({
+ *   filters: {
+ *     city: 'New York',
+ *     capacity: { gte: 1000 },
+ *     _search: 'garden'
+ *   },
+ *   sort: { field: 'name', order: 'asc' },
+ *   page: 1,
+ *   limit: 25
+ * });
+ */
 // Pure WebSocket manager class (no React dependencies)
 class WebSocketManager {
+  /**
+   * Create a WebSocketManager instance
+   *
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.maxReconnectAttempts=5] - Maximum reconnection attempts before giving up
+   */
   constructor(options = {}) {
     this.ws = null;
     this.messageId = 0;
@@ -22,6 +75,62 @@ class WebSocketManager {
       search: this.createEntityProxy("search"),
     };
 
+    /**
+     * API proxy for calling DZQL operations and custom functions
+     *
+     * @member {Object} api
+     * @memberof WebSocketManager
+     *
+     * @property {Object} get - Get single record by primary key
+     * @property {Object} save - Create or update record (upsert)
+     * @property {Object} delete - Delete record by primary key
+     * @property {Object} lookup - Autocomplete lookup by label field
+     * @property {Object} search - Advanced search with filters
+     *
+     * @example
+     * // Get operation
+     * const venue = await ws.api.get.venues({ id: 1 });
+     *
+     * @example
+     * // Save operation (create)
+     * const created = await ws.api.save.venues({
+     *   name: 'New Venue',
+     *   org_id: 3
+     * });
+     *
+     * @example
+     * // Save operation (update)
+     * const updated = await ws.api.save.venues({
+     *   id: 1,
+     *   name: 'Updated Name'
+     * });
+     *
+     * @example
+     * // Delete operation
+     * await ws.api.delete.venues({ id: 1 });
+     *
+     * @example
+     * // Lookup for autocomplete
+     * const results = await ws.api.lookup.venues({ p_filter: 'garden' });
+     *
+     * @example
+     * // Search with filters
+     * const results = await ws.api.search.venues({
+     *   filters: {
+     *     city: 'New York',
+     *     capacity: { gte: 1000, lt: 5000 },
+     *     name: { ilike: '%garden%' },
+     *     _search: 'madison'
+     *   },
+     *   sort: { field: 'name', order: 'asc' },
+     *   page: 1,
+     *   limit: 25
+     * });
+     *
+     * @example
+     * // Call custom function
+     * const result = await ws.api.myCustomFunction({ param: 'value' });
+     */
     this.api = new Proxy(dzqlOps, {
       get: (target, prop) => {
         // Return cached DZQL operation if it exists
@@ -102,6 +211,31 @@ class WebSocketManager {
     );
   }
 
+  /**
+   * Connect to DZQL WebSocket server
+   *
+   * Automatically detects environment (browser vs Node.js) and constructs WebSocket URL.
+   * If JWT token exists in localStorage, automatically includes it in connection.
+   *
+   * @param {string|null} [url=null] - WebSocket URL (auto-detected if not provided)
+   *   Browser: ws://current-host/ws or wss://current-host/ws
+   *   Node.js: ws://localhost:3000/ws
+   * @param {number} [timeout=5000] - Connection timeout in milliseconds
+   *
+   * @returns {Promise<void>} Resolves when connected, rejects on timeout or error
+   *
+   * @example
+   * // Auto-detect URL (browser)
+   * await ws.connect();
+   *
+   * @example
+   * // Explicit URL
+   * await ws.connect('ws://localhost:3000/ws');
+   *
+   * @example
+   * // Custom timeout
+   * await ws.connect(null, 10000); // 10 second timeout
+   */
   connect(url = null, timeout = 5000) {
     return new Promise((resolve, reject) => {
       let wsUrl;
@@ -214,6 +348,14 @@ class WebSocketManager {
     }
   }
 
+  /**
+   * Call a method via JSON-RPC over WebSocket
+   *
+   * @private
+   * @param {string} method - Method name (e.g., 'login_user' or 'dzql.get.venues')
+   * @param {Object} [params={}] - Method parameters
+   * @returns {Promise<*>} Resolves with method result, rejects on error
+   */
   call(method, params = {}) {
     return new Promise((resolve, reject) => {
       if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -234,6 +376,50 @@ class WebSocketManager {
     });
   }
 
+  /**
+   * Register callback for real-time broadcast events
+   *
+   * Broadcasts are sent when data changes (insert/update/delete operations).
+   * Method format: "{table}:{operation}" (e.g., "venues:update")
+   *
+   * @param {Function} callback - Callback function (method, params) => void
+   * @returns {Function} Cleanup function to remove the callback
+   *
+   * @example
+   * // Listen to all broadcasts
+   * ws.onBroadcast((method, params) => {
+   *   console.log(`Event: ${method}`, params);
+   * });
+   *
+   * @example
+   * // Listen to specific table events
+   * ws.onBroadcast((method, params) => {
+   *   if (method === 'venues:update') {
+   *     console.log('Venue updated:', params.after);
+   *   }
+   * });
+   *
+   * @example
+   * // With cleanup
+   * const cleanup = ws.onBroadcast((method, params) => {
+   *   console.log(method, params);
+   * });
+   *
+   * // Later: stop listening
+   * cleanup();
+   *
+   * @example
+   * // Event structure
+   * {
+   *   table: 'venues',
+   *   op: 'insert',     // 'insert', 'update', or 'delete'
+   *   pk: { id: 1 },
+   *   before: null,     // Old values (null for insert)
+   *   after: { ... },   // New values (null for delete)
+   *   user_id: 123,
+   *   at: '2025-01-15T10:30:00Z'
+   * }
+   */
   onBroadcast(callback) {
     this.broadcastCallbacks.add(callback);
     return () => this.broadcastCallbacks.delete(callback);

package/src/server/db.js

@@ -190,6 +190,79 @@ function createEntityProxy(operation) {
   );
 }
 
+/**
+ * DZQL database API
+ *
+ * Provides server-side access to DZQL operations and custom PostgreSQL functions.
+ * All operations require explicit userId parameter (unlike client API which auto-injects).
+ *
+ * @namespace db.api
+ *
+ * @property {Object} get - Get single record by primary key
+ * @property {Object} save - Create or update record (upsert)
+ * @property {Object} delete - Delete record by primary key
+ * @property {Object} lookup - Autocomplete lookup by label field
+ * @property {Object} search - Advanced search with filters, pagination, sorting
+ *
+ * @example
+ * // Get a single venue
+ * const venue = await db.api.get.venues({ id: 1 }, userId);
+ *
+ * @example
+ * // Create a new venue
+ * const venue = await db.api.save.venues({
+ *   name: 'Madison Square Garden',
+ *   org_id: 3,
+ *   address: '4 Pennsylvania Plaza, New York'
+ * }, userId);
+ *
+ * @example
+ * // Update existing venue
+ * const updated = await db.api.save.venues({
+ *   id: 1,
+ *   name: 'Updated Name'
+ * }, userId);
+ *
+ * @example
+ * // Delete venue
+ * await db.api.delete.venues({ id: 1 }, userId);
+ *
+ * @example
+ * // Lookup for autocomplete
+ * const results = await db.api.lookup.venues({
+ *   p_filter: 'garden'  // Searches label field
+ * }, userId);
+ * // Returns: [{ value: 1, label: 'Madison Square Garden' }, ...]
+ *
+ * @example
+ * // Advanced search with filters
+ * const results = await db.api.search.venues({
+ *   p_filters: {
+ *     city: 'New York',
+ *     capacity: { gte: 1000 },
+ *     _search: 'garden'  // Full-text search
+ *   },
+ *   p_sort: { field: 'name', order: 'asc' },
+ *   p_page: 1,
+ *   p_limit: 25
+ * }, userId);
+ * // Returns: { data: [...], total: 100, page: 1, limit: 25 }
+ *
+ * @example
+ * // Call custom PostgreSQL function
+ * const stats = await db.api.myCustomFunction({ param1: 'value' }, userId);
+ *
+ * @example
+ * // Call auth functions (no userId required)
+ * const user = await db.api.register_user({
+ *   email: 'user@example.com',
+ *   password: 'secure123'
+ * });
+ * const session = await db.api.login_user({
+ *   email: 'user@example.com',
+ *   password: 'secure123'
+ * });
+ */
 // DZQL database API proxy with custom function support
 export const db = {
   api: new Proxy(

package/src/server/index.js

@@ -8,6 +8,77 @@ export { sql, db } from "./db.js";
 export { metaRoute } from "./meta-route.js";
 export { createMCPRoute } from "./mcp.js";
 
+/**
+ * Create a DZQL server with WebSocket support, real-time updates, and automatic CRUD operations
+ *
+ * Sets up a Bun server with:
+ * - WebSocket endpoint at /ws for real-time communication
+ * - JSON-RPC 2.0 protocol for API calls
+ * - PostgreSQL NOTIFY/LISTEN for real-time broadcasts
+ * - Automatic JWT authentication
+ * - Health check endpoint at /health
+ *
+ * @param {Object} [options={}] - Server configuration options
+ * @param {number} [options.port=3000] - Port number to listen on (or process.env.PORT)
+ * @param {Object} [options.customApi={}] - Custom Bun functions to expose via WebSocket API
+ *   Each function receives (userId, params) and can return any JSON-serializable value
+ * @param {Object} [options.routes={}] - Additional HTTP routes as { path: handlerFunction }
+ * @param {string|null} [options.staticPath=null] - Path to static files directory for serving
+ * @param {Function} [options.onReady=null] - Callback invoked after server initialization
+ *   Receives { broadcast, routes } to allow dynamic route setup
+ *
+ * @returns {Object} Server instance with the following properties:
+ * @returns {number} .port - The port number the server is listening on
+ * @returns {Object} .server - The underlying Bun.Server instance
+ * @returns {Function} .shutdown - Async function to gracefully shutdown server and close DB connections
+ * @returns {Function} .broadcast - Function to send messages to connected WebSocket clients
+ *   Signature: broadcast(message: string, userIds?: number[])
+ *   If userIds provided, sends only to those users; otherwise broadcasts to all authenticated users
+ *
+ * @example
+ * // Basic server
+ * import { createServer } from 'dzql';
+ *
+ * const server = createServer({ port: 3000 });
+ *
+ * @example
+ * // Server with custom API functions
+ * import { createServer, db } from 'dzql';
+ *
+ * const server = createServer({
+ *   port: 3000,
+ *   customApi: {
+ *     async getVenueStats(userId, params) {
+ *       const { venueId } = params;
+ *       return db.api.get.venues({ id: venueId }, userId);
+ *     }
+ *   }
+ * });
+ *
+ * // Client can call: await ws.api.getVenueStats({ venueId: 1 })
+ *
+ * @example
+ * // Server with static files and custom routes
+ * const server = createServer({
+ *   port: 3000,
+ *   staticPath: './public',
+ *   routes: {
+ *     '/api/health': () => new Response(JSON.stringify({ status: 'ok' }))
+ *   }
+ * });
+ *
+ * @example
+ * // Server with onReady callback for dynamic setup
+ * const server = createServer({
+ *   onReady: ({ broadcast, routes }) => {
+ *     // Add routes dynamically
+ *     routes['/api/notify'] = (req) => {
+ *       broadcast(JSON.stringify({ method: 'alert', params: { msg: 'Hello!' } }));
+ *       return new Response('Sent');
+ *     };
+ *   }
+ * });
+ */
 export function createServer(options = {}) {
   const {
     port = process.env.PORT || 3000,