dzql 0.4.8 → 0.5.2

package/bin/cli.js

@@ -230,33 +230,49 @@ CREATE TRIGGER dzql_events_notify
       }
 
       // Generate auth functions (required for WebSocket server)
-      const authSQL = `-- Authentication Functions
+      // This is a fallback for when there's no users entity - otherwise users.sql has these
+      const authSQL = `-- Authentication Functions (fallback)
 -- Required for DZQL WebSocket server
+-- Note: If you have a users entity, auth functions are in users.sql instead
 
 -- Enable pgcrypto extension for password hashing
 CREATE EXTENSION IF NOT EXISTS pgcrypto;
 
 -- Register new user
-CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT)
+-- p_options: optional JSON object with additional fields to set on the user record
+CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSON DEFAULT NULL)
 RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
 AS $$
 DECLARE
-  user_id INT;
-  salt TEXT;
-  hash TEXT;
+  v_user_id INT;
+  v_salt TEXT;
+  v_hash TEXT;
+  v_insert_data JSONB;
 BEGIN
   -- Generate salt and hash password
-  salt := gen_salt('bf', 10);
-  hash := crypt(p_password, salt);
-
-  -- Insert user (assumes users table has: id, email, name, password_hash)
-  INSERT INTO users (email, name, password_hash)
-  VALUES (p_email, split_part(p_email, '@', 1), hash)
-  RETURNING id INTO user_id;
+  v_salt := gen_salt('bf', 10);
+  v_hash := crypt(p_password, v_salt);
+
+  -- Build insert data: options fields + email + password_hash
+  -- Cast p_options to JSONB for internal operations (JSON type is for API boundary convenience)
+  v_insert_data := jsonb_build_object('email', p_email, 'password_hash', v_hash);
+  IF p_options IS NOT NULL THEN
+    v_insert_data := (p_options::jsonb - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
+  END IF;
 
-  RETURN _profile(user_id);
+  -- Dynamic INSERT from JSONB
+  EXECUTE (
+    SELECT format(
+      'INSERT INTO users (%s) VALUES (%s) RETURNING id',
+      string_agg(quote_ident(key), ', '),
+      string_agg(quote_nullable(value), ', ')
+    )
+    FROM jsonb_each_text(v_insert_data) kv(key, value)
+  ) INTO v_user_id;
+
+  RETURN _profile(v_user_id);
 EXCEPTION
   WHEN unique_violation THEN
     RAISE EXCEPTION 'Email already exists' USING errcode = '23505';
@@ -269,10 +285,10 @@ LANGUAGE plpgsql
 SECURITY DEFINER
 AS $$
 DECLARE
-  user_record RECORD;
+  v_user_record RECORD;
 BEGIN
-  SELECT id, email, name, password_hash
-  INTO user_record
+  SELECT id, email, password_hash
+  INTO v_user_record
   FROM users
   WHERE email = p_email;
 
@@ -280,14 +296,15 @@ BEGIN
     RAISE EXCEPTION 'Invalid credentials' USING errcode = '28000';
   END IF;
 
-  IF NOT (user_record.password_hash = crypt(p_password, user_record.password_hash)) THEN
+  IF NOT (v_user_record.password_hash = crypt(p_password, v_user_record.password_hash)) THEN
     RAISE EXCEPTION 'Invalid credentials' USING errcode = '28000';
   END IF;
 
-  RETURN _profile(user_record.id);
+  RETURN _profile(v_user_record.id);
 END $$;
 
 -- Get user profile (private function, called after login/register)
+-- Returns all columns except sensitive fields
 CREATE OR REPLACE FUNCTION _profile(p_user_id INT)
 RETURNS JSONB
 LANGUAGE sql
@@ -299,8 +316,12 @@ AS $$
 $$;
 `;
 
-      writeFileSync(resolve(options.output, '002_auth.sql'), authSQL, 'utf-8');
-      console.log(`   ✓ 002_auth.sql`);
+      // Only generate 002_auth.sql if there's no users entity (which has its own auth functions)
+      const hasUsersEntity = result.results.some(r => r.tableName === 'users');
+      if (!hasUsersEntity) {
+        writeFileSync(resolve(options.output, '002_auth.sql'), authSQL, 'utf-8');
+        console.log(`   ✓ 002_auth.sql`);
+      }
 
       const checksums = {};
 

package/docs/compiler/CODING_STANDARDS.md

@@ -72,6 +72,72 @@ CREATE FUNCTION lookup_users(p_user_id INT, p_filter TEXT, ...)
 CREATE FUNCTION search_users(p_user_id INT, p_filters JSONB, ...)
 ```
 
+## JSON vs JSONB for Function Parameters
+
+### External API Parameters: Use JSON
+
+When defining function parameters that accept JSON from external callers (API boundary), use `JSON` type (text-based) rather than `JSONB`. This allows callers to pass `JSON.stringify(options)` as a plain string without needing special serialization like `sql.json()`.
+
+```sql
+-- ✅ CORRECT - JSON for external input parameters
+CREATE FUNCTION register_user(
+  p_email TEXT,
+  p_password TEXT,
+  p_options JSON DEFAULT NULL  -- Accepts plain JSON string from API
+)
+
+-- ❌ WRONG - JSONB requires special serialization from clients
+CREATE FUNCTION register_user(
+  p_email TEXT,
+  p_password TEXT,
+  p_options JSONB DEFAULT NULL  -- Harder to call from JavaScript
+)
+```
+
+### Internal Operations: Cast to JSONB
+
+Inside the function, cast to JSONB if you need JSONB operators (`->`, `->>`, `-`, `||`, `?`, etc.):
+
+```sql
+CREATE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSON DEFAULT NULL)
+RETURNS JSONB AS $$
+DECLARE
+  v_insert_data JSONB;
+BEGIN
+  v_insert_data := jsonb_build_object('email', p_email);
+  
+  IF p_options IS NOT NULL THEN
+    -- Cast to JSONB for internal operations
+    v_insert_data := (p_options::jsonb - 'id' - 'password') || v_insert_data;
+  END IF;
+  
+  -- ...
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### Table Columns: Use JSONB
+
+Table columns should still use `JSONB` for efficient storage and indexing:
+
+```sql
+-- ✅ CORRECT - JSONB for table columns
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  metadata JSONB DEFAULT '{}'  -- Efficient storage & indexing
+);
+```
+
+### Summary
+
+| Context | Type | Reason |
+|---------|------|--------|
+| Function input parameters | `JSON` | Easy to pass from JavaScript (`JSON.stringify()`) |
+| Internal function operations | `::jsonb` cast | Access to JSONB operators |
+| Table columns | `JSONB` | Efficient storage and indexing |
+
+This pattern - **JSON for input parameters, JSONB for storage** - eliminates serialization confusion at the API boundary.
+
 ## Function Categories
 
 ### Public API Functions (No underscore)

package/docs/for-ai/claude-guide.md

@@ -635,7 +635,8 @@ invokej dzql.lookup organisations '{"query": "acme"}'
 ### Real-time Events
 - Listen using `ws.onBroadcast((method, params) => {})`
 - Method format: `{table}:{operation}` (e.g., "venues:update")
-- Params include: `{table, op, pk, before, after, user_id, at}`
+- Params include: `{table, op, pk, data, user_id, at}`
+- `data` contains: new state for insert/update, `null` for delete
 - Target users via notification paths or broadcast to all
 
 ### Permissions
@@ -684,8 +685,7 @@ TABLE dzql.events {
   table_name TEXT NOT NULL,
   op TEXT NOT NULL,          -- 'insert' | 'update' | 'delete'
   pk JSONB NOT NULL,         -- Primary key: {id: 1}
-  before JSONB,              -- Old values (null for insert)
-  after JSONB,               -- New values (null for delete)
+  data JSONB,                -- Record data (new state for insert/update, null for delete)
   user_id INT,               -- Who made the change
   notify_users INT[],        -- Who to notify (null = all)
   at TIMESTAMPTZ DEFAULT NOW()
@@ -753,43 +753,46 @@ try {
   table: 'venues',              // Table name
   op: 'insert',                 // Operation: 'insert' | 'update' | 'delete'
   pk: {id: 1},                  // Primary key object
-  before: {                     // Old values (null for insert)
-    id: 1,
-    name: 'Old Name',
-    address: 'Old Address'
-  },
-  after: {                      // New values (null for delete)
+  data: {                       // Record data (new state for insert/update, null for delete)
     id: 1,
     name: 'New Name',
     address: 'New Address'
   },
   user_id: 123,                 // User who made the change
-  at: '2025-01-01T12:00:00Z',  // Timestamp
-  notify_users: [1, 2, 3]       // Targeted users (null = all authenticated)
+  at: '2025-01-01T12:00:00Z'   // Timestamp
 }
 ```
 
+**Event data by operation:**
+| Operation | `data` field contains |
+|-----------|----------------------|
+| `insert` | Full new record |
+| `update` | Full updated record (new state only) |
+| `delete` | `null` |
+
+**Note:** The `notify_users` field is used internally for routing but is stripped from the broadcast message sent to clients.
+
 ### Using Event Data
 
 ```javascript
 ws.onBroadcast((method, params) => {
+  const { table, op, pk, data } = params;
+  
   // For insert
   if (method === 'venues:insert') {
-    const newRecord = params.after;
-    // params.before is null
+    const newRecord = data;
   }
   
   // For update
   if (method === 'venues:update') {
-    const oldRecord = params.before;
-    const newRecord = params.after;
-    // Compare to detect what changed
+    const updatedRecord = data;
+    // Note: only new state is available, not the previous state
   }
   
   // For delete
   if (method === 'venues:delete') {
-    const deletedRecord = params.before;
-    // params.after is null
+    // data is null for delete, use pk to identify the deleted record
+    const deletedId = pk.id;
   }
 });
 ```

package/docs/reference/api.md

@@ -892,6 +892,25 @@ const result = await ws.api.register_user({
 });
 ```
 
+**With options (for extended registration):**
+```javascript
+const result = await ws.api.register_user({
+  email: 'user@example.com',
+  password: 'secure-password',
+  options: {
+    org_name: 'Acme Corp',
+    role: 'admin'
+  }
+});
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | yes | User email address |
+| `password` | string | yes | User password |
+| `options` | object | no | Additional JSONB data passed to `register_user()` function |
+
 **Returns:**
 ```javascript
 {
@@ -902,6 +921,17 @@ const result = await ws.api.register_user({
 }
 ```
 
+**Note:** The `options` parameter requires your `register_user` PostgreSQL function to accept a third parameter:
+```sql
+CREATE OR REPLACE FUNCTION register_user(
+  p_email TEXT,
+  p_password TEXT,
+  p_options JSONB DEFAULT NULL
+) RETURNS JSONB AS $$
+  -- Access options: p_options->>'org_name'
+$$;
+```
+
 ### Login
 
 ```javascript
@@ -911,8 +941,38 @@ const result = await ws.api.login_user({
 });
 ```
 
+**With options:**
+```javascript
+const result = await ws.api.login_user({
+  email: 'user@example.com',
+  password: 'password',
+  options: {
+    device_id: 'abc123',
+    remember_me: true
+  }
+});
+```
+
+**Parameters:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `email` | string | yes | User email address |
+| `password` | string | yes | User password |
+| `options` | object | no | Additional JSONB data passed to `login_user()` function |
+
 **Returns:** Same as register
 
+**Note:** The `options` parameter requires your `login_user` PostgreSQL function to accept a third parameter:
+```sql
+CREATE OR REPLACE FUNCTION login_user(
+  p_email TEXT,
+  p_password TEXT,
+  p_options JSONB DEFAULT NULL
+) RETURNS JSONB AS $$
+  -- Access options: p_options->>'device_id'
+$$;
+```
+
 ### Logout
 
 ```javascript
@@ -980,27 +1040,34 @@ unsubscribe();
   table: 'venues',
   op: 'insert' | 'update' | 'delete',
   pk: {id: 1},           // Primary key
-  before: {...},         // Old values (null for insert)
-  after: {...},          // New values (null for delete)
+  data: {...},           // Record data (new state for insert/update, null for delete)
   user_id: 123,          // Who made the change
-  at: '2025-01-01T...',  // Timestamp
-  notify_users: [1, 2]   // Who to notify (null = all)
+  at: '2025-01-01T...'   // Timestamp
 }
 ```
 
+**Event data by operation:**
+| Operation | `data` field contains |
+|-----------|----------------------|
+| `insert` | Full new record |
+| `update` | Full updated record (new state only) |
+| `delete` | `null` |
+
+**Note:** The `notify_users` field is used internally for routing but is stripped from the broadcast message sent to clients.
+
 ### Event Handling Pattern
 
 ```javascript
 ws.onBroadcast((method, params) => {
-  const data = params.after || params.before;
+  const { table, op, pk, data } = params;
   
   if (method === 'todos:insert') {
     state.todos.push(data);
   } else if (method === 'todos:update') {
-    const idx = state.todos.findIndex(t => t.id === data.id);
+    const idx = state.todos.findIndex(t => t.id === pk.id);
     if (idx !== -1) state.todos[idx] = data;
   } else if (method === 'todos:delete') {
-    state.todos = state.todos.filter(t => t.id !== data.id);
+    state.todos = state.todos.filter(t => t.id !== pk.id);
   }
   
   render();

package/docs/reference/client.md

@@ -82,6 +82,47 @@ async function login() {
 </template>
 ```
 
+**Registration with options (e.g., organisation name):**
+```vue
+<script setup>
+import { ref } from 'vue'
+import { useWsStore } from 'dzql/client/stores'
+
+const wsStore = useWsStore()
+const email = ref('')
+const password = ref('')
+const orgName = ref('')
+
+async function register() {
+  try {
+    await wsStore.register({
+      email: email.value,
+      password: password.value,
+      options: { org_name: orgName.value }
+    })
+  } catch (err) {
+    alert(err.message)
+  }
+}
+</script>
+
+<template>
+  <form @submit.prevent="register">
+    <input v-model="email" type="email" placeholder="Email" required />
+    <input v-model="password" type="password" placeholder="Password" required />
+    <input v-model="orgName" type="text" placeholder="Organisation Name" />
+    <button type="submit">Register</button>
+  </form>
+</template>
+```
+
+The `options` parameter allows passing additional JSONB data to the `register_user` and `login_user` PostgreSQL functions. This is useful for:
+- Organisation name during registration
+- Device ID for login tracking
+- Any custom fields your auth functions support
+
+See [API Reference - Authentication](./api.md#authentication) for details on configuring your PostgreSQL functions.
+
 ## 4. Setup main.js
 
 **src/main.js:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.4.8",
+  "version": "0.5.2",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

package/src/client/ws.js

@@ -23,6 +23,13 @@
  *   password: 'password123'
  * });
  *
+ * // Register with options (e.g., organisation name)
+ * const session = await ws.api.register_user({
+ *   email: 'user@example.com',
+ *   password: 'password123',
+ *   options: { org_name: 'Acme Corp' }
+ * });
+ *
  * // CRUD operations
  * const venue = await ws.api.get.venues({ id: 1 });
  * const created = await ws.api.save.venues({ name: 'New Venue' });

package/src/compiler/codegen/auth-codegen.js

@@ -28,6 +28,9 @@ export class AuthCodegen {
     }
 
     return [
+      '-- Enable pgcrypto extension for password hashing',
+      'CREATE EXTENSION IF NOT EXISTS pgcrypto;',
+      '',
       this._generateProfileFunction(),
       this._generateRegisterFunction(),
       this._generateLoginFunction()
@@ -57,16 +60,16 @@ $$;`;
 
   /**
    * Generate register_user function
-   * Supports optional extra fields via JSON parameter
+   * Supports optional fields via JSON parameter
    * @private
    */
   _generateRegisterFunction() {
     return `-- ============================================================================
 -- Auth: register_user function for ${this.tableName}
--- p_extra: optional JSON object with additional fields to set on the user record
+-- p_options: optional JSON object with additional fields to set on the user record
 -- Example: register_user('test@example.com', 'password', '{"name": "Test User"}')
 -- ============================================================================
-CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_extra JSONB DEFAULT '{}')
+CREATE OR REPLACE FUNCTION register_user(p_email TEXT, p_password TEXT, p_options JSON DEFAULT NULL)
 RETURNS JSONB
 LANGUAGE plpgsql
 SECURITY DEFINER
@@ -81,9 +84,12 @@ BEGIN
   v_salt := gen_salt('bf', 10);
   v_hash := crypt(p_password, v_salt);
 
-  -- Build insert data: extra fields + email + password_hash (extra cannot override core fields)
-  v_insert_data := (p_extra - 'id' - 'email' - 'password_hash' - 'password')
-                   || jsonb_build_object('email', p_email, 'password_hash', v_hash);
+  -- Build insert data: options fields + email + password_hash (options cannot override core fields)
+  -- Cast p_options to JSONB for internal operations (JSON type is for API boundary convenience)
+  v_insert_data := jsonb_build_object('email', p_email, 'password_hash', v_hash);
+  IF p_options IS NOT NULL THEN
+    v_insert_data := (p_options::jsonb - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
+  END IF;
 
   -- Dynamic INSERT from JSONB (same pattern as compiled save functions)
   EXECUTE (

package/src/database/migrations/006_auth.sql

@@ -5,12 +5,10 @@
 create extension if not exists pgcrypto;
 
 -- === Users Table ===
--- Core auth table with optional name field
--- Applications can add additional columns as needed
+-- Minimal auth table - applications can add columns via migrations
 -- Note: created_at is tracked via the action log, not here
 create table if not exists users (
   id serial primary key,
-  name text,
   email text unique not null,
   password_hash text not null
 );
@@ -18,9 +16,9 @@ create table if not exists users (
 -- === Auth Functions ===
 
 -- Register new user
--- p_extra: optional JSON object with additional fields to set on the user record
+-- p_options: optional JSON object with additional fields to set on the user record
 -- Example: register_user('test@example.com', 'password', '{"name": "Test User"}')
-create or replace function register_user(p_email text, p_password text, p_extra jsonb default '{}')
+create or replace function register_user(p_email text, p_password text, p_options jsonb default null)
 returns jsonb
 language plpgsql
 security definer
@@ -35,9 +33,11 @@ begin
   v_salt := gen_salt('bf', 10);
   v_hash := crypt(p_password, v_salt);
 
-  -- Build insert data: extra fields + email + password_hash (extra cannot override core fields)
-  v_insert_data := (p_extra - 'id' - 'email' - 'password_hash' - 'password')
-                   || jsonb_build_object('email', p_email, 'password_hash', v_hash);
+  -- Build insert data: options fields + email + password_hash (options cannot override core fields)
+  v_insert_data := jsonb_build_object('email', p_email, 'password_hash', v_hash);
+  if p_options is not null then
+    v_insert_data := (p_options - 'id' - 'email' - 'password_hash' - 'password') || v_insert_data;
+  end if;
 
   -- Dynamic INSERT from JSONB (same pattern as compiled save functions)
   execute (

package/src/server/db.js

@@ -54,7 +54,13 @@ export async function setCache(key, data) {
 }
 
 // Auth helpers
-export async function callAuthFunction(method, email, password) {
+export async function callAuthFunction(method, email, password, options = null) {
+  if (options !== null) {
+    const result = await sql`
+      SELECT ${sql(method)}(${email}, ${password}, ${options}) as result
+    `;
+    return result[0].result;
+  }
   const result = await sql`
     SELECT ${sql(method)}(${email}, ${password}) as result
   `;
@@ -380,7 +386,7 @@ export const db = {
           // Special handling for auth functions that don't require userId
           if (prop === 'register_user' || prop === 'login_user') {
             // For auth functions, first param is the args object
-            return callAuthFunction(prop, userIdOrArgs.email, userIdOrArgs.password);
+            return callAuthFunction(prop, userIdOrArgs.email, userIdOrArgs.password, userIdOrArgs.options || null);
           }
 
           // For other functions, userId is required as first parameter

package/src/server/ws.js

@@ -231,6 +231,7 @@ export function createRPCHandler(customHandlers = {}) {
           "login_user",
           params.email,
           params.password,
+          params.options || null,
         );
 
         // On successful auth, set user_id on WebSocket connection
@@ -268,6 +269,7 @@ export function createRPCHandler(customHandlers = {}) {
           "register_user",
           params.email,
           params.password,
+          params.options || null,
         );
 
         // On successful registration, set user_id on WebSocket connection