dzql 0.1.0-alpha.3 → 0.1.0-alpha.4

package/GETTING_STARTED.md

@@ -2,6 +2,8 @@
 
 DZQL is a PostgreSQL framework that gives you **atomic real-time updates** via WebSocket. Every database change broadcasts instantly to all connected clients. Zero boilerplate.
 
+> **See also:** [REFERENCE.md](REFERENCE.md) for complete API documentation | [CLAUDE.md](../../CLAUDE.md) for AI development guide
+
 ## The Core Pattern
 
 1. **Schema = API**: Define a table → DZQL auto-creates CRUD endpoints

package/README.md

@@ -1,91 +1,27 @@
-# DZQL - Zero-Boilerplate Database Framework
+# DZQL
 
-PostgreSQL-powered framework with automatic CRUD operations, real-time WebSocket synchronization, and graph-based permissions. **No migrations. No schema files. No API boilerplate.**
+PostgreSQL-powered framework with automatic CRUD operations and real-time WebSocket synchronization.
 
-```bash
-npm install dzql
-# or with Bun (no Node.js required)
-bun add dzql
-```
-
-## Why DZQL?
-
-### Before DZQL
-```javascript
-// Traditional approach: Write everything
-app.post('/api/users', authenticate, validate, async (req, res) => {
-  try {
-    const user = await db.query('INSERT INTO users (...) VALUES (...)', [...]);
-    res.json(user);
-  } catch (error) {
-    res.status(500).json({ error: error.message });
-  }
-});
-// Repeat for GET, PUT, DELETE, SEARCH, LOOKUP... = 50+ lines of boilerplate
-```
+## Documentation
 
-### With DZQL
-```javascript
-// That's it. All 5 operations work automatically.
-// GET, SAVE, DELETE, LOOKUP, SEARCH
-const user = await ws.api.save.users({ name: 'John' });
-const results = await ws.api.search.users({ filters: {name: 'john'} });
-```
+All documentation is maintained in the repository root:
 
-## Features
+- **[README.md](../../README.md)** - Project overview and quick start
+- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Complete tutorial with working todo app
+- **[REFERENCE.md](REFERENCE.md)** - Complete API reference
+- **[CLAUDE.md](../../CLAUDE.md)** - Development guide for AI assistants
+- **[Venues Example](../venues/)** - Full working application
 
-✅ **Zero Boilerplate** - Register entity, get 5 CRUD operations automatically  
-✅ **Real-time WebSocket** - Automatic change notifications to all clients  
-✅ **PostgreSQL-native** - Leverage full SQL power when needed  
-✅ **Graph Rules** - Cascading operations without joins  
-✅ **Permissions & RLS** - Row-level security built-in  
-✅ **Full-text Search** - Built-in search with filters & pagination  
-✅ **Type-safe** - Uses PostgreSQL as source of truth  
-✅ **Framework-agnostic** - Works with any frontend (React, Vue, Svelte, plain JS)  
-✅ **Bun Native** - No Node.js required  
+## Quick Install
 
-## Quick Start
-
-### 1. Install
 ```bash
 bun add dzql
+# or
+npm install dzql
 ```
 
-### 2. Start PostgreSQL
-```bash
-docker run -d \
-  -e POSTGRES_PASSWORD=dzql \
-  -e POSTGRES_DB=dzql \
-  -p 5432:5432 \
-  postgres:latest
-```
-
-### 3. Create Server
-```javascript
-import { createServer } from 'dzql';
-
-const server = createServer({ port: 3000 });
-console.log('🚀 Server on ws://localhost:3000/ws');
-```
-
-### 4. Initialize Database
-```bash
-# Apply DZQL core migrations (included in package)
-psql -h localhost -U postgres -d dzql < node_modules/dzql/src/database/migrations/*.sql
-
-# Register your entities
-psql -h localhost -U postgres -d dzql << EOF
-CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT);
-
-SELECT dzql.register_entity(
-  'users',
-  'name',
-  array['name', 'email']
-);
-EOF
-```
+## Quick Example
 
-### 5. Use from Client
 ```javascript
 import { WebSocketManager } from 'dzql/client';
 
@@ -93,416 +29,16 @@ const ws = new WebSocketManager();
 await ws.connect();
 
 // All 5 operations work automatically
-const user = await ws.api.save.users({ name: 'Alice', email: 'alice@example.com' });
-const results = await ws.api.search.users({ filters: { name: { ilike: '%alice%' } } });
-const deleted = await ws.api.delete.users({ id: user.id });
-```
-
-## The 5 Operations
-
-Every registered entity automatically gets these 5 operations:
-
-### GET - Retrieve Single Record
-```javascript
-const user = await ws.api.get.users({ id: 1 });
-// Server: await db.api.get.users({ id: 1 }, userId);
-```
-
-### SAVE - Create or Update
-```javascript
-const user = await ws.api.save.users({
-  id: 1,           // Optional - omit for insert
-  name: 'Alice',
-  email: 'alice@example.com'
-});
-```
-
-### DELETE - Remove Record
-```javascript
-const deleted = await ws.api.delete.users({ id: 1 });
-```
-
-### LOOKUP - Autocomplete/Label Lookup
-```javascript
-const options = await ws.api.lookup.users({ p_filter: 'ali' });
-// Returns: [{ label: 'Alice', value: 1 }]
-```
-
-### SEARCH - Advanced Search with Pagination
-```javascript
-const results = await ws.api.search.users({
-  filters: {
-    name: { ilike: '%alice%' },
-    email: 'alice@example.com',
-    created_at: { gte: '2025-01-01' }
-  },
-  sort: { field: 'name', order: 'asc' },
-  page: 1,
-  limit: 25
-});
-// Returns: { data: [...], total: 42, page: 1, limit: 25 }
-```
-
-## Entity Registration
-
-Before DZQL works with a table, register it:
-
-```sql
-SELECT dzql.register_entity(
-  p_table_name := 'users',
-  p_label_field := 'name',                          -- For LOOKUP display
-  p_searchable_fields := array['name', 'email'],    -- For SEARCH
-  p_fk_includes := '{"department": "departments"}'::jsonb,  -- Dereference FKs
-  p_graph_rules := '{
-    "on_delete": {
-      "cascade": {
-        "actions": [{
-          "type": "delete",
-          "entity": "posts",
-          "condition": "user_id = @id"
-        }]
-      }
-    }
-  }'::jsonb
-);
-```
-
-## Core API
-
-### Server-Side (Bun/Node)
-
-```javascript
-import { createServer, db, sql } from 'dzql';
-
-// Direct SQL access
-const users = await sql`SELECT * FROM users WHERE active = true`;
-
-// DZQL operations (require userId for permissions)
-const user = await db.api.get.users({ id: 1 }, userId);
-const saved = await db.api.save.users({ name: 'Bob' }, userId);
-const searched = await db.api.search.users(
-  { filters: { name: 'bob' } },
-  userId
-);
-const deleted = await db.api.delete.users({ id: 1 }, userId);
-const options = await db.api.lookup.users({ p_filter: 'bo' }, userId);
-
-// Custom functions
-const result = await db.api.myCustomFunction({ param: 'value' }, userId);
-
-// Start server
-const server = createServer({
-  port: 3000,
-  customApi: {},           // Optional: add custom functions
-  staticPath: './public',  // Optional: serve static files
-  routes: {                // Optional: standard HTTP routes
-    '/health': () => new Response('OK')
-  },
-  onReady: async (broadcast) => {  // Optional: routes needing broadcast
-    return {
-      '/mcp': createMCPRoute(broadcast)  // Example: MCP integration
-    };
-  }
-});
-```
-
-### Client-Side (Browser/Bun)
-
-```javascript
-import { WebSocketManager } from 'dzql/client';
-
-// Create connection
-const ws = new WebSocketManager();
-await ws.connect();
-
-// Authentication
-const auth = await ws.api.login_user({
-  email: 'user@example.com',
-  password: 'password'
-});
-// Returns: { token, profile, user_id }
-
-// All DZQL operations
-const user = await ws.api.get.users({ id: 1 });
-const saved = await ws.api.save.users({ name: 'Charlie' });
-const deleted = await ws.api.delete.users({ id: 1 });
-const lookup = await ws.api.lookup.users({ p_filter: 'char' });
-const search = await ws.api.search.users({ filters: {} });
-
-// Custom functions
-const result = await ws.api.myCustomFunction({ foo: 'bar' });
-
-// Real-time events
-const unsubscribe = ws.onBroadcast((method, params) => {
-  console.log(`${method}:`, params.data);
-  // Events: "users:insert", "users:update", "users:delete"
-});
-
-// Cleanup
-ws.cleanDisconnect();
-```
-
-## Custom Functions
-
-Add functions alongside DZQL operations:
-
-### PostgreSQL Function
-```sql
-CREATE OR REPLACE FUNCTION transfer_amount(
-  p_user_id INT,
-  p_from_account INT,
-  p_to_account INT,
-  p_amount DECIMAL
-) RETURNS TABLE (success BOOLEAN, message TEXT) AS $$
-BEGIN
-  -- Your logic here
-  RETURN QUERY SELECT true, 'Transfer complete';
-END;
-$$ LANGUAGE plpgsql;
-```
-
-### Bun Function
-```javascript
-// server/api.js
-export async function transfer_amount(userId, params) {
-  const { from_account, to_account, amount } = params;
-  // Your logic here
-  return { success: true, message: 'Transfer complete' };
-}
-
-// server/index.js
-const customApi = await import('./api.js');
-const server = createServer({ customApi });
-```
-
-### Usage
-```javascript
-const result = await ws.api.transfer_amount({
-  from_account: 1,
-  to_account: 2,
-  amount: 100
-});
-```
-
-## Real-time Events
-
-Listen for database changes in real-time:
-
-```javascript
-ws.onBroadcast((method, params) => {
-  if (method === 'users:insert') {
-    console.log('New user:', params.data);
-    // params: { op: 'insert', table: 'users', data: {...}, notify_users: [...] }
-  }
-  if (method === 'users:update') {
-    console.log('User updated:', params.data);
-  }
-  if (method === 'users:delete') {
-    console.log('User deleted:', params.data);
-  }
-});
-```
-
-## Graph Rules - Cascading Operations
-
-Automatically cascade changes through relationships:
-
-```sql
-SELECT dzql.register_entity(
-  p_table_name := 'organisations',
-  p_label_field := 'name',
-  p_searchable_fields := array['name'],
-  p_graph_rules := '{
-    "on_delete": {
-      "cascade_to_teams": {
-        "actions": [{
-          "type": "delete",
-          "entity": "teams",
-          "condition": "org_id = @id"
-        }]
-      }
-    },
-    "on_create": {
-      "create_default_team": {
-        "actions": [{
-          "type": "create",
-          "entity": "teams",
-          "data": {
-            "org_id": "@id",
-            "name": "Default Team"
-          }
-        }]
-      }
-    }
-  }'::jsonb
-);
-```
-
-Available actions: `create`, `update`, `delete`, `insert`, `call_function`
-
-## Permissions & Row-Level Security
-
-Implement permissions in your entity registration:
-
-```sql
-SELECT dzql.register_entity(
-  p_table_name := 'posts',
-  p_label_field := 'title',
-  p_searchable_fields := array['title', 'content'],
-  p_permission_rules := '{
-    "view": {
-      "public_posts": {
-        "condition": "public = true OR author_id = @user_id"
-      }
-    },
-    "edit": {
-      "own_posts": {
-        "condition": "author_id = @user_id"
-      }
-    }
-  }'::jsonb
-);
-```
-
-## Search Filter Operators
-
-```javascript
-const results = await ws.api.search.venues({
-  filters: {
-    // Exact match
-    name: 'Madison Square Garden',
-    
-    // Comparison operators
-    capacity: { gt: 1000 },         // Greater than
-    capacity: { gte: 1000 },        // Greater or equal
-    capacity: { lt: 50000 },        // Less than
-    capacity: { lte: 50000 },       // Less or equal
-    capacity: { neq: 5000 },        // Not equal
-    
-    // Range
-    capacity: { between: [1000, 50000] },
-    
-    // Pattern matching
-    name: { like: '%garden%' },     // Case-sensitive
-    name: { ilike: '%GARDEN%' },    // Case-insensitive
-    
-    // NULL checks
-    description: null,               // IS NULL
-    description: { not_null: true }, // IS NOT NULL
-    
-    // Arrays
-    categories: ['sports', 'music'],  // IN array
-    categories: { not_in: ['adult'] }, // NOT IN array
-    
-    // Text search (across searchable_fields)
-    _search: 'madison garden'
-  },
-  page: 1,
-  limit: 25
-});
-```
-
-## Project Structure
-
-```
-my-app/
-├── server/
-│   ├── index.js           # Server entry point
-│   └── api.js             # Custom API functions (optional)
-├── database/
-│   ├── docker-compose.yml # PostgreSQL setup
-│   ├── init_db/
-│   │   ├── 001_schema.sql # Your tables
-│   │   └── 002_entities.sql # Entity registration
-│   └── seeds/             # Sample data (optional)
-├── client/
-│   └── index.html         # Frontend (optional)
-├── tests/
-│   └── app.test.js
-├── package.json
-└── bunfig.toml            # Bun config (optional)
-```
-
-## Environment Variables
-
-```bash
-# Database
-DATABASE_URL=postgresql://dzql:dzql@localhost:5432/dzql
-
-# Server
-PORT=3000
-NODE_ENV=development
-
-# JWT
-JWT_SECRET=your-secret-key-min-32-chars
-JWT_EXPIRES_IN=7d
-
-# WebSocket
-WS_PING_INTERVAL=30000        # Keep-alive ping (Heroku safe: <55s)
-WS_PING_TIMEOUT=5000
-
-# Logging
-LOG_LEVEL=INFO                # ERROR, WARN, INFO, DEBUG, TRACE
-LOG_CATEGORIES=ws:debug,db:debug
+const user = await ws.api.save.users({ name: 'Alice' });
+const results = await ws.api.search.users({ filters: { name: 'alice' } });
 ```
 
-## Examples
-
-See the [venues example](https://github.com/blueshed/dzql/tree/main/packages/venues) for a complete working application.
-
-### Todo App
-```javascript
-// Schema
-CREATE TABLE todos (
-  id SERIAL PRIMARY KEY,
-  user_id INT REFERENCES users(id),
-  title TEXT NOT NULL,
-  completed BOOLEAN DEFAULT FALSE,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
-SELECT dzql.register_entity('todos', 'title', array['title']);
-
-// Client
-const todo = await ws.api.save.todos({ title: 'Learn DZQL' });
-const list = await ws.api.search.todos({
-  filters: { completed: false },
-  limit: 100
-});
-await ws.api.save.todos({ id: todo.id, completed: true });
-await ws.api.delete.todos({ id: todo.id });
-```
-
-## Error Handling
+## License
 
-```javascript
-try {
-  const user = await ws.api.get.users({ id: 999 });
-} catch (error) {
-  // Common errors:
-  // "record not found" - Record doesn't exist
-  // "Permission denied: view on users" - Access denied
-  // "entity users not configured" - Entity not registered
-  // "Column foo does not exist in table users" - Invalid column
-  console.error(error.message);
-}
-```
+MIT
 
-## Getting Help
+## Links
 
-- **Documentation**: [GETTING_STARTED.md](./GETTING_STARTED.md)
 - **GitHub**: https://github.com/blueshed/dzql
 - **Issues**: https://github.com/blueshed/dzql/issues
-- **Email**: support@blueshed.com
-
-## License
-
-MIT - See LICENSE file
-
-## Authors
-
-Created by [Blueshed](https://blueshed.com)
-
----
-
-**Ready to build?** Start with [GETTING_STARTED.md](./GETTING_STARTED.md) 🚀
+- **npm**: https://www.npmjs.com/package/dzql

package/REFERENCE.md

@@ -0,0 +1,891 @@
+# DZQL API Reference
+
+Complete API documentation for DZQL framework. For tutorials, see [GETTING_STARTED.md](GETTING_STARTED.md). For AI development guide, see [CLAUDE.md](../../CLAUDE.md).
+
+## Table of Contents
+
+- [The 5 Operations](#the-5-operations)
+- [Entity Registration](#entity-registration)
+- [Search Operators](#search-operators)
+- [Graph Rules](#graph-rules)
+- [Permission & Notification Paths](#permission--notification-paths)
+- [Custom Functions](#custom-functions)
+- [Authentication](#authentication)
+- [Real-time Events](#real-time-events)
+- [Temporal Relationships](#temporal-relationships)
+- [Error Messages](#error-messages)
+
+---
+
+## The 5 Operations
+
+Every registered entity automatically gets these 5 operations via the proxy API:
+
+### GET - Retrieve Single Record
+
+Fetch a single record by primary key with foreign keys dereferenced.
+
+**Client:**
+```javascript
+const record = await ws.api.get.{entity}({id: 1});
+```
+
+**Server:**
+```javascript
+const record = await db.api.get.{entity}({id: 1}, userId);
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | any | yes | Primary key value |
+| `on_date` | string | no | Temporal filtering (ISO 8601 date) |
+
+**Returns:** Object with all fields + dereferenced FKs
+
+**Throws:** `"record not found"` if not exists
+
+**Example:**
+```javascript
+const venue = await ws.api.get.venues({id: 1});
+// {id: 1, name: "MSG", org: {id: 3, name: "Org"}, sites: [...]}
+
+// With temporal filtering
+const historical = await ws.api.get.venues({id: 1, on_date: '2023-01-01'});
+```
+
+---
+
+### SAVE - Create or Update (Upsert)
+
+Insert new record (no `id`) or update existing (with `id`).
+
+**Client:**
+```javascript
+const record = await ws.api.save.{entity}({...fields});
+```
+
+**Server:**
+```javascript
+const record = await db.api.save.{entity}({...fields}, userId);
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | any | no | Omit for insert, include for update |
+| ...fields | any | varies | Entity-specific fields |
+
+**Returns:** Created/updated record
+
+**Behavior:**
+- **No `id`**: INSERT new record
+- **With `id`**: UPDATE existing record (partial update supported)
+- Triggers graph rules if configured
+- Generates real-time event
+
+**Example:**
+```javascript
+// Insert
+const venue = await ws.api.save.venues({
+  name: 'Madison Square Garden',
+  address: 'NYC',
+  org_id: 1
+});
+
+// Update (partial)
+const updated = await ws.api.save.venues({
+  id: 1,
+  name: 'Updated Name'  // Only updates name
+});
+```
+
+---
+
+### DELETE - Remove Record
+
+Delete a record by primary key.
+
+**Client:**
+```javascript
+const result = await ws.api.delete.{entity}({id: 1});
+```
+
+**Server:**
+```javascript
+const result = await db.api.delete.{entity}({id: 1}, userId);
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | any | yes | Primary key value |
+
+**Returns:** Deleted record
+
+**Behavior:**
+- Hard delete (unless soft delete configured)
+- Triggers graph rules if configured
+- Generates real-time event
+
+**Example:**
+```javascript
+const deleted = await ws.api.delete.venues({id: 1});
+```
+
+---
+
+### LOOKUP - Autocomplete/Typeahead
+
+Get label-value pairs for autocomplete inputs.
+
+**Client:**
+```javascript
+const options = await ws.api.lookup.{entity}({p_filter: 'search'});
+```
+
+**Server:**
+```javascript
+const options = await db.api.lookup.{entity}({p_filter: 'search'}, userId);
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `p_filter` | string | no | Search term (matches label field) |
+
+**Returns:** Array of `{label, value}` objects
+
+**Example:**
+```javascript
+const options = await ws.api.lookup.venues({p_filter: 'madison'});
+// [{label: "Madison Square Garden", value: 1}, ...]
+```
+
+---
+
+### SEARCH - Advanced Search with Pagination
+
+Search with filters, sorting, and pagination.
+
+**Client:**
+```javascript
+const results = await ws.api.search.{entity}({
+  filters: {...},
+  sort: {field, order},
+  page: 1,
+  limit: 25
+});
+```
+
+**Server:**
+```javascript
+const results = await db.api.search.{entity}({...}, userId);
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `filters` | object | no | See [Search Operators](#search-operators) |
+| `sort` | object | no | `{field: 'name', order: 'asc' | 'desc'}` |
+| `page` | number | no | Page number (1-indexed, default: 1) |
+| `limit` | number | no | Records per page (default: 25) |
+
+**Returns:**
+```javascript
+{
+  data: [...],    // Array of records
+  total: 100,     // Total matching records
+  page: 1,        // Current page
+  limit: 25       // Records per page
+}
+```
+
+**Example:**
+```javascript
+const results = await ws.api.search.venues({
+  filters: {
+    city: 'New York',
+    capacity: {gte: 1000, lt: 5000},
+    name: {ilike: '%garden%'},
+    _search: 'madison'  // Text search across searchable fields
+  },
+  sort: {field: 'name', order: 'asc'},
+  page: 1,
+  limit: 25
+});
+```
+
+---
+
+## Entity Registration
+
+Register an entity to enable all 5 operations via `dzql.register_entity()`.
+
+### Full Signature
+
+```sql
+SELECT dzql.register_entity(
+  p_table_name TEXT,
+  p_label_field TEXT,
+  p_searchable_fields TEXT[],
+  p_fk_includes JSONB DEFAULT '{}'::jsonb,
+  p_soft_delete BOOLEAN DEFAULT false,
+  p_temporal_fields JSONB DEFAULT '{}'::jsonb,
+  p_notification_paths JSONB DEFAULT '{}'::jsonb,
+  p_permission_paths JSONB DEFAULT '{}'::jsonb,
+  p_graph_rules JSONB DEFAULT '{}'::jsonb
+);
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `p_table_name` | TEXT | **yes** | Table name in database |
+| `p_label_field` | TEXT | **yes** | Field used for LOOKUP display |
+| `p_searchable_fields` | TEXT[] | **yes** | Fields searchable by SEARCH (min: 1) |
+| `p_fk_includes` | JSONB | no | Foreign keys to dereference in GET |
+| `p_soft_delete` | BOOLEAN | no | Enable soft delete (default: false) |
+| `p_temporal_fields` | JSONB | no | Temporal field config (valid_from/valid_to) |
+| `p_notification_paths` | JSONB | no | Who receives real-time updates |
+| `p_permission_paths` | JSONB | no | CRUD permission rules |
+| `p_graph_rules` | JSONB | no | Automatic relationship management |
+
+### FK Includes
+
+Configure which foreign keys to dereference in GET operations:
+
+```sql
+-- Single object dereference
+'{"org": "organisations"}'  -- venue.org_id -> full org object
+
+-- Child array inclusion
+'{"sites": "sites"}'  -- Include all child sites (auto-detects FK)
+
+-- Multiple
+'{"org": "organisations", "sites": "sites", "venue": "venues"}'
+```
+
+**Result example:**
+```javascript
+{
+  id: 1,
+  name: "Madison Square Garden",
+  org_id: 3,
+  org: {id: 3, name: "Venue Management", ...},  // Dereferenced
+  sites: [                                       // Child array
+    {id: 1, name: "Main Entrance", ...},
+    {id: 2, name: "Concourse", ...}
+  ]
+}
+```
+
+### Temporal Fields
+
+Enable temporal relationships with `valid_from`/`valid_to`:
+
+```sql
+'{
+  "valid_from": "valid_from",  -- Column name for start date
+  "valid_to": "valid_to"       -- Column name for end date
+}'
+```
+
+**Usage:**
+```javascript
+// Current relationships (default)
+const rights = await ws.api.get.contractor_rights({id: 1});
+
+// Historical relationships
+const past = await ws.api.get.contractor_rights({id: 1, on_date: '2023-01-01'});
+```
+
+### Example Registration
+
+```sql
+SELECT dzql.register_entity(
+  'venues',                              -- table name
+  'name',                                -- label field
+  array['name', 'address', 'description'], -- searchable
+  '{"org": "organisations", "sites": "sites"}', -- FK includes
+  false,                                 -- soft delete
+  '{}',                                  -- temporal (none)
+  '{                                     -- notifications
+    "ownership": ["@org_id->acts_for[org_id=$]{active}.user_id"]
+  }',
+  '{                                     -- permissions
+    "create": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+    "update": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+    "delete": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+    "view": []
+  }',
+  '{                                     -- graph rules
+    "on_create": {
+      "establish_site": {
+        "description": "Create default site",
+        "actions": [{
+          "type": "create",
+          "entity": "sites",
+          "data": {"name": "Main Site", "venue_id": "@id"}
+        }]
+      }
+    }
+  }'
+);
+```
+
+---
+
+## Search Operators
+
+The SEARCH operation supports advanced filtering via the `filters` object.
+
+### Operator Reference
+
+| Operator | Syntax | Description | Example |
+|----------|--------|-------------|---------|
+| **Exact match** | `field: value` | Equality | `{name: 'Alice'}` |
+| **Greater than** | `{gt: n}` | `>` | `{age: {gt: 18}}` |
+| **Greater or equal** | `{gte: n}` | `>=` | `{age: {gte: 18}}` |
+| **Less than** | `{lt: n}` | `<` | `{age: {lt: 65}}` |
+| **Less or equal** | `{lte: n}` | `<=` | `{age: {lte: 65}}` |
+| **Not equal** | `{neq: v}` | `!=` | `{status: {neq: 'deleted'}}` |
+| **Between** | `{between: [a, b]}` | `BETWEEN a AND b` | `{age: {between: [18, 65]}}` |
+| **LIKE** | `{like: 'pattern'}` | Case-sensitive pattern | `{name: {like: '%Garden%'}}` |
+| **ILIKE** | `{ilike: 'pattern'}` | Case-insensitive pattern | `{name: {ilike: '%garden%'}}` |
+| **IS NULL** | `field: null` | NULL check | `{description: null}` |
+| **IS NOT NULL** | `{not_null: true}` | NOT NULL check | `{description: {not_null: true}}` |
+| **IN array** | `field: [...]` | `IN (...)` | `{city: ['NYC', 'LA']}` |
+| **NOT IN array** | `{not_in: [...]}` | `NOT IN (...)` | `{status: {not_in: ['deleted']}}` |
+| **Text search** | `_search: 'terms'` | Across searchable fields | `{_search: 'madison garden'}` |
+
+### Complete Example
+
+```javascript
+const results = await ws.api.search.venues({
+  filters: {
+    // Exact match
+    city: 'New York',
+    
+    // Comparison
+    capacity: {gte: 1000, lt: 5000},
+    
+    // Pattern matching
+    name: {ilike: '%garden%'},
+    
+    // NULL checks
+    description: {not_null: true},
+    
+    // Arrays
+    categories: ['sports', 'music'],
+    status: {not_in: ['deleted', 'closed']},
+    
+    // Text search (across all searchable_fields)
+    _search: 'madison square'
+  },
+  sort: {field: 'capacity', order: 'desc'},
+  page: 1,
+  limit: 25
+});
+```
+
+---
+
+## Graph Rules
+
+Automatically manage entity relationships when data changes.
+
+### Structure
+
+```jsonb
+{
+  "on_create": {
+    "rule_name": {
+      "description": "Human-readable description",
+      "actions": [
+        {
+          "type": "create|update|delete",
+          "entity": "target_table",
+          "data": {"field": "@variable"},      // for create/update
+          "match": {"field": "@variable"}      // for update/delete
+        }
+      ]
+    }
+  },
+  "on_update": { /* same structure */ },
+  "on_delete": { /* same structure */ }
+}
+```
+
+### Action Types
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `create` | `entity`, `data` | INSERT new record |
+| `update` | `entity`, `match`, `data` | UPDATE matching records |
+| `delete` | `entity`, `match` | DELETE matching records |
+
+### Variables
+
+Variables reference data from the triggering operation:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `@user_id` | Current authenticated user | `"created_by": "@user_id"` |
+| `@id` | Primary key of the record | `"org_id": "@id"` |
+| `@field_name` | Any field from the record | `"org_id": "@org_id"` |
+| `@now` | Current timestamp | `"created_at": "@now"` |
+| `@today` | Current date | `"valid_from": "@today"` |
+
+### Common Patterns
+
+#### Creator Becomes Owner
+```jsonb
+{
+  "on_create": {
+    "establish_ownership": {
+      "description": "Creator becomes member of organisation",
+      "actions": [{
+        "type": "create",
+        "entity": "acts_for",
+        "data": {
+          "user_id": "@user_id",
+          "org_id": "@id",
+          "valid_from": "@today"
+        }
+      }]
+    }
+  }
+}
+```
+
+#### Cascade Delete
+```jsonb
+{
+  "on_delete": {
+    "cascade_venues": {
+      "description": "Delete all venues when org is deleted",
+      "actions": [{
+        "type": "delete",
+        "entity": "venues",
+        "match": {"org_id": "@id"}
+      }]
+    }
+  }
+}
+```
+
+#### Temporal Transition
+```jsonb
+{
+  "on_create": {
+    "expire_previous": {
+      "description": "End previous temporal relationship",
+      "actions": [{
+        "type": "update",
+        "entity": "acts_for",
+        "match": {
+          "user_id": "@user_id",
+          "org_id": "@org_id",
+          "valid_to": null
+        },
+        "data": {
+          "valid_to": "@valid_from"
+        }
+      }]
+    }
+  }
+}
+```
+
+### Execution
+
+- **Atomic**: All rules execute in the same transaction
+- **Sequential**: Actions execute in order within each rule
+- **Rollback**: If any action fails, entire transaction rolls back
+- **Events**: Each action generates its own audit event
+
+---
+
+## Permission & Notification Paths
+
+Paths use a unified syntax for both permissions and notifications.
+
+### Path Syntax
+
+```
+@field->table[filter]{temporal}.target_field
+```
+
+**Components:**
+- `@field` - Start from a field in the current record
+- `->table` - Navigate to related table
+- `[filter]` - WHERE clause (`$` = current field value)
+- `{temporal}` - Apply temporal filtering (`{active}` = valid now)
+- `.target_field` - Extract this field as result
+
+### Permission Paths
+
+Control who can perform CRUD operations:
+
+```sql
+'{
+  "create": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+  "update": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+  "delete": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+  "view": []  -- Empty array = public access
+}'
+```
+
+**Permission types:**
+- `create` - Who can create records
+- `update` - Who can modify records
+- `delete` - Who can remove records
+- `view` - Who can read records (empty = public)
+
+**Behavior:**
+- User's `user_id` must be in resolved set of user_ids
+- Checked before operation executes
+- Empty array = allow all
+- Missing permission type = deny all
+
+### Notification Paths
+
+Determine who receives real-time updates:
+
+```sql
+'{
+  "ownership": ["@org_id->acts_for[org_id=$]{active}.user_id"],
+  "sponsorship": ["@sponsor_org_id->acts_for[org_id=$]{active}.user_id"]
+}'
+```
+
+**Behavior:**
+- Resolves to array of user_ids or `null`
+- `null` = broadcast to all authenticated users
+- Array = send only to specified users
+- Multiple paths = union of all resolved user_ids
+
+### Path Examples
+
+```sql
+-- Direct user reference
+'@user_id'
+
+-- Via organization
+'@org_id->acts_for[org_id=$]{active}.user_id'
+
+-- Via nested relationship
+'@venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id'
+
+-- Via multiple relationships
+'@package_id->packages.owner_org_id->acts_for[org_id=$]{active}.user_id'
+```
+
+---
+
+## Custom Functions
+
+Extend DZQL with custom PostgreSQL or Bun functions.
+
+### PostgreSQL Functions
+
+Create stored procedures and call via proxy API:
+
+```sql
+CREATE OR REPLACE FUNCTION my_function(
+  p_user_id INT,           -- REQUIRED: First parameter
+  p_param TEXT DEFAULT 'default'
+) RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+BEGIN
+  -- Your logic here
+  RETURN jsonb_build_object('result', p_param);
+END;
+$$;
+```
+
+**Call:**
+```javascript
+const result = await ws.api.my_function({param: 'value'});
+```
+
+**Conventions:**
+- First parameter **must** be `p_user_id INT`
+- Can access full PostgreSQL ecosystem
+- Automatically transactional
+- Optional registration in `dzql.registry`
+
+### Bun Functions
+
+Create JavaScript functions in server:
+
+```javascript
+// server/api.js
+export async function myBunFunction(userId, params = {}) {
+  const { param = 'default' } = params;
+  
+  // Can use db.api for database access
+  // const data = await db.api.get.users({id: userId}, userId);
+  
+  return { result: param };
+}
+```
+
+**Server setup:**
+```javascript
+import * as customApi from './server/api.js';
+const server = createServer({ customApi });
+```
+
+**Call:**
+```javascript
+const result = await ws.api.myBunFunction({param: 'value'});
+```
+
+**Conventions:**
+- First parameter is `userId` (number)
+- Second parameter is `params` object
+- Can access `db.api.*` operations
+- Can use any npm packages
+- Return JSON-serializable data
+
+### Function Comparison
+
+| Feature | PostgreSQL | Bun |
+|---------|-----------|-----|
+| **Language** | SQL/PL/pgSQL | JavaScript |
+| **Access to** | Database only | Database + npm ecosystem |
+| **Transaction** | Automatic | Manual (via db.api) |
+| **Performance** | Faster (no network) | Slower (WebSocket overhead) |
+| **Use case** | Data-heavy operations | Complex business logic |
+
+---
+
+## Authentication
+
+JWT-based authentication with automatic user_id injection.
+
+### Register User
+
+```javascript
+const result = await ws.api.register_user({
+  email: 'user@example.com',
+  password: 'secure-password'
+});
+```
+
+**Returns:**
+```javascript
+{
+  user_id: 1,
+  email: 'user@example.com',
+  token: 'eyJ...',
+  profile: {...}
+}
+```
+
+### Login
+
+```javascript
+const result = await ws.api.login_user({
+  email: 'user@example.com',
+  password: 'password'
+});
+```
+
+**Returns:** Same as register
+
+### Logout
+
+```javascript
+await ws.api.logout();
+```
+
+### Token Storage
+
+```javascript
+// Save token
+localStorage.setItem('dzql_token', result.token);
+
+// Auto-connect with token
+const ws = new WebSocketManager();
+await ws.connect();  // Automatically uses token from localStorage
+```
+
+### User ID Injection
+
+- **Client**: `user_id` automatically injected from JWT
+- **Server**: `user_id` must be passed explicitly as second parameter
+
+```javascript
+// Client
+const user = await ws.api.get.users({id: 1});  // userId auto-injected
+
+// Server
+const user = await db.api.get.users({id: 1}, userId);  // userId explicit
+```
+
+---
+
+## Real-time Events
+
+All database changes trigger WebSocket events.
+
+### Event Flow
+
+1. Database trigger fires on INSERT/UPDATE/DELETE
+2. Notification paths resolve affected user_ids
+3. Event written to `dzql.events` table
+4. PostgreSQL NOTIFY on 'dzql' channel
+5. Bun server filters by `notify_users`
+6. WebSocket message sent to affected clients
+
+### Listening for Events
+
+```javascript
+const unsubscribe = ws.onBroadcast((method, params) => {
+  console.log(`Event: ${method}`, params);
+});
+
+// Stop listening
+unsubscribe();
+```
+
+### Event Format
+
+**Method:** `"{table}:{operation}"`
+- Examples: `"users:insert"`, `"venues:update"`, `"sites:delete"`
+
+**Params:**
+```javascript
+{
+  table: 'venues',
+  op: 'insert' | 'update' | 'delete',
+  pk: {id: 1},           // Primary key
+  before: {...},         // Old values (null for insert)
+  after: {...},          // New values (null for delete)
+  user_id: 123,          // Who made the change
+  at: '2025-01-01T...',  // Timestamp
+  notify_users: [1, 2]   // Who to notify (null = all)
+}
+```
+
+### Event Handling Pattern
+
+```javascript
+ws.onBroadcast((method, params) => {
+  const data = params.after || params.before;
+  
+  if (method === 'todos:insert') {
+    state.todos.push(data);
+  } else if (method === 'todos:update') {
+    const idx = state.todos.findIndex(t => t.id === data.id);
+    if (idx !== -1) state.todos[idx] = data;
+  } else if (method === 'todos:delete') {
+    state.todos = state.todos.filter(t => t.id !== data.id);
+  }
+  
+  render();
+});
+```
+
+---
+
+## Temporal Relationships
+
+Handle time-based relationships with `valid_from`/`valid_to` fields.
+
+### Configuration
+
+```sql
+SELECT dzql.register_entity(
+  'contractor_rights',
+  'contractor_name',
+  array['contractor_name'],
+  '{"contractor_org": "organisations", "venue": "venues"}',
+  false,
+  '{
+    "valid_from": "valid_from",
+    "valid_to": "valid_to"
+  }',
+  '{}', '{}'
+);
+```
+
+### Usage
+
+```javascript
+// Get current relationships (default)
+const rights = await ws.api.get.contractor_rights({id: 1});
+
+// Get historical relationships
+const past = await ws.api.get.contractor_rights({
+  id: 1,
+  on_date: '2023-01-01'
+});
+```
+
+### Path Syntax with Temporal
+
+```sql
+-- Current relationships only
+'@org_id->acts_for[org_id=$]{active}.user_id'
+
+-- All relationships (past and present)
+'@org_id->acts_for[org_id=$].user_id'
+```
+
+---
+
+## Error Messages
+
+Common error messages and their meanings:
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `"record not found"` | GET on non-existent ID | Check ID exists, handle 404 |
+| `"Permission denied: view on users"` | User not in permission path | Check permissions, authenticate |
+| `"entity users not configured"` | Entity not registered | Call `dzql.register_entity()` |
+| `"Column foo does not exist in table users"` | Invalid filter field | Check searchable_fields config |
+| `"Invalid function name: foo"` | Function doesn't exist | Create function or check spelling |
+| `"Function not found"` | Custom function not registered | Export from api.js or create SQL function |
+| `"Authentication required"` | Not logged in | Call `login_user()` first |
+| `"Invalid token"` | Expired/invalid JWT | Re-authenticate |
+
+---
+
+## Server-Side API
+
+For backend/Bun scripts, use `db.api`:
+
+```javascript
+import { db, sql } from 'dzql';
+
+// Direct SQL queries
+const users = await sql`SELECT * FROM users WHERE active = true`;
+
+// DZQL operations (require explicit userId)
+const user = await db.api.get.users({id: 1}, userId);
+const saved = await db.api.save.users({name: 'John'}, userId);
+const results = await db.api.search.users({filters: {}}, userId);
+const deleted = await db.api.delete.users({id: 1}, userId);
+const options = await db.api.lookup.users({p_filter: 'jo'}, userId);
+
+// Custom functions
+const result = await db.api.myCustomFunction({param: 'value'}, userId);
+```
+
+**Key difference:** Server-side requires explicit `userId` as second parameter; client-side auto-injects from JWT.
+
+---
+
+## See Also
+
+- [GETTING_STARTED.md](GETTING_STARTED.md) - Hands-on tutorial
+- [CLAUDE.md](../../CLAUDE.md) - AI development guide
+- [README.md](../../README.md) - Project overview
+- [Venues Example](../venues/) - Complete working application

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -15,6 +15,7 @@
     "src/database/migrations/**/*.sql",
     "README.md",
     "GETTING_STARTED.md",
+    "REFERENCE.md",
     "LICENSE"
   ],
   "scripts": {