dzql 0.4.4 → 0.4.6

package/docs/compiler/README.md

@@ -6,17 +6,11 @@ The DZQL Compiler transforms declarative entity definitions into optimized Postg
 
 - **[Quickstart Guide](QUICKSTART.md)** - Get started with the compiler in 5 minutes
 
-## Guides
+## Reference
 
 - **[Advanced Filters](ADVANCED_FILTERS.md)** - Complex search operators and patterns
 - **[Coding Standards](CODING_STANDARDS.md)** - Best practices for DZQL code
-
-## Reference
-
-- **[Comparison](COMPARISON.md)** - How DZQL compares to other approaches
-- **[Session Summary](SESSION_SUMMARY.md)** - Development session documentation
-- **[Summary](SUMMARY.md)** - Compiler overview and architecture
-- **[Overnight Build](OVERNIGHT_BUILD.md)** - Batch compilation process
+- **[Comparison](COMPARISON.md)** - Runtime vs compiled side-by-side
 
 ## Using the Compiler
 

package/docs/examples/README.md

@@ -0,0 +1,38 @@
+# DZQL Examples
+
+SQL examples demonstrating DZQL entity registration patterns.
+
+## Files
+
+### blog.sql
+A complete blog application with:
+- Multiple entities (users, posts, comments, tags)
+- Many-to-many relationships (posts ↔ tags)
+- Soft delete
+- FK includes
+- Permission paths
+- Notification paths
+
+### venue-detail-simple.sql
+Basic subscribable definition for venue data.
+
+### venue-detail-subscribable.sql
+Full subscribable with relations and permission paths. Demonstrates:
+- Root entity with FK includes
+- Child entity filtering
+- Permission path syntax
+
+## Usage
+
+These files are meant to be run after DZQL core migrations. See the [Tutorial](../getting-started/tutorial.md) for complete setup instructions.
+
+```bash
+# After setting up your database with DZQL migrations
+psql $DATABASE_URL < examples/blog.sql
+```
+
+## See Also
+
+- [API Reference](../reference/api.md) - Entity registration parameters
+- [Many-to-Many Guide](../guides/many-to-many.md) - M2M configuration
+- [Subscriptions Guide](../guides/subscriptions.md) - Subscribable patterns

package/docs/examples/blog.sql

@@ -0,0 +1,160 @@
+-- ============================================================================
+-- Blog Application Example
+-- ============================================================================
+--
+-- This example demonstrates:
+--   - Multiple related entities (users, posts, comments, tags)
+--   - Many-to-many relationships (posts <-> tags via post_tags junction)
+--   - Soft delete (posts.deleted_at)
+--   - FK includes (dereferencing author, post)
+--   - Permission paths (author can edit/delete own content)
+--   - Notification paths (notify post author when comments added)
+--
+-- To use this example:
+--   1. Create tables first (see CREATE TABLE statements below)
+--   2. Run the dzql.register_entity() calls to enable CRUD operations
+--   3. Use the generated API: save_posts, get_posts, search_posts, etc.
+--
+-- For a complete working example with Docker, tests, and frontend:
+--   See packages/blog/ in the DZQL repository
+--
+-- ============================================================================
+
+-- Create tables
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id SERIAL PRIMARY KEY,
+  title VARCHAR(500) NOT NULL,
+  content TEXT NOT NULL,
+  summary TEXT,
+  author_id INT REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT NOW(),
+  deleted_at TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS comments (
+  id SERIAL PRIMARY KEY,
+  content TEXT NOT NULL,
+  post_id INT REFERENCES posts(id),
+  author_id INT REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Tags table for categorizing posts
+CREATE TABLE IF NOT EXISTS tags (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(50) UNIQUE NOT NULL,
+  color VARCHAR(7) DEFAULT '#3788d8'
+);
+
+-- Junction table for post-tag many-to-many relationship
+CREATE TABLE IF NOT EXISTS post_tags (
+  post_id INT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  tag_id INT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+  PRIMARY KEY (post_id, tag_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_post_tags_post_id ON post_tags(post_id);
+CREATE INDEX IF NOT EXISTS idx_post_tags_tag_id ON post_tags(tag_id);
+
+-- ============================================================================
+-- DZQL Entity Registrations
+-- ============================================================================
+
+-- Users entity - blog authors
+select dzql.register_entity(
+  'users',
+  'name',
+  array['name', 'email'],
+  '{}',  -- no FK includes
+  false, -- hard delete
+  '{}',  -- no reverse FK
+  '{}',  -- no notifications
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view users
+    'create', array[]::text[],         -- Anyone can register
+    'update', array['@id'],            -- Only update own profile
+    'delete', array['@id']             -- Only delete own account
+  )
+);
+
+-- Register tags entity first
+select dzql.register_entity(
+  'tags',
+  'name',
+  array['name'],
+  '{}',  -- no FK includes
+  false, -- hard delete
+  '{}',  -- no temporal
+  '{}',  -- no notifications
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view tags
+    'create', array[]::text[],         -- Anyone can create tags
+    'update', array[]::text[],         -- Anyone can update tags
+    'delete', array[]::text[]          -- Anyone can delete tags
+  )
+);
+
+-- Posts entity - blog posts with M2M tags
+select dzql.register_entity(
+  'posts',
+  'title',
+  array['title', 'content', 'summary'],
+  jsonb_build_object(
+    'author', 'users'  -- FK to users
+  ),
+  true,  -- soft delete (deleted_at)
+  '{}',  -- no temporal
+  '{}',  -- no notification paths
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view posts
+    'create', array[]::text[],         -- Anyone can create posts
+    'update', array['@author_id'],     -- Only author can update
+    'delete', array['@author_id']      -- Only author can delete
+  ),
+  jsonb_build_object(
+    'many_to_many', jsonb_build_object(
+      'tags', jsonb_build_object(
+        'junction_table', 'post_tags',
+        'local_key', 'post_id',
+        'foreign_key', 'tag_id',
+        'target_entity', 'tags',
+        'id_field', 'tag_ids',
+        'expand', true  -- Include full tag objects in response
+      )
+    )
+  )  -- graph_rules with M2M
+);
+
+-- Comments entity - blog comments
+select dzql.register_entity(
+  'comments',
+  'content',
+  array['content'],
+  jsonb_build_object(
+    'post', 'posts',
+    'author', 'users'
+  ),
+  false, -- hard delete
+  '{}',  -- no reverse FK
+  jsonb_build_object(
+    'post_author', array['@post_id->posts.author_id'],
+    'commenters', array['@post_id']
+  ),
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view comments
+    'create', array[]::text[],         -- Anyone can comment
+    'update', array['@author_id'],     -- Only author can update
+    'delete', array[
+      '@author_id',                    -- Author can delete
+      '@post_id->posts.author_id'      -- Post author can delete
+    ]
+  )
+);

package/docs/examples/venue-detail-simple.sql

@@ -0,0 +1,8 @@
+-- Simplified test subscribable for initial testing
+SELECT dzql.register_subscribable(
+  'venue_detail',
+  '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,
+  '{"venue_id": "int"}'::jsonb,
+  'venues',
+  '{"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb
+);

package/docs/examples/venue-detail-subscribable.sql

@@ -0,0 +1,45 @@
+-- Example: Venue Detail Subscribable
+-- This subscribable builds a denormalized document containing:
+-- - The venue record
+-- - The organization (FK expanded)
+-- - All sites belonging to the venue
+-- - All packages with their allocations
+
+SELECT dzql.register_subscribable(
+  'venue_detail',
+
+  -- Permission: who can subscribe?
+  -- Users who act_for the venue's organization (active roles only)
+  jsonb_build_object(
+    'subscribe', ARRAY['@org_id->acts_for[org_id=$]{active}.user_id']
+  ),
+
+  -- Parameters: subscription key
+  jsonb_build_object(
+    'venue_id', 'int'
+  ),
+
+  -- Root entity
+  'venues',
+
+  -- Relations to include in document
+  jsonb_build_object(
+    -- FK expansion: organisation
+    'org', 'organisations',
+
+    -- Child collection: sites
+    'sites', jsonb_build_object(
+      'entity', 'sites',
+      'filter', 'venue_id=$venue_id'
+    ),
+
+    -- Child collection: packages with nested allocations
+    'packages', jsonb_build_object(
+      'entity', 'packages',
+      'filter', 'venue_id=$venue_id',
+      'include', jsonb_build_object(
+        'allocations', 'allocations'
+      )
+    )
+  )
+);

package/docs/guides/subscriptions.md

@@ -28,7 +28,7 @@ Live Query Subscriptions (Pattern 1 from vision.md) enable clients to subscribe
 Create a SQL file with your subscribable definition:
 
 ```sql
--- examples/subscribables/venue_detail.sql
+-- examples/venue-detail-subscribable.sql
 SELECT dzql.register_subscribable(
   'venue_detail',
   '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,
@@ -56,7 +56,7 @@ SELECT dzql.register_subscribable(
 ```bash
 # Compile subscribable to SQL functions
 bun packages/dzql/src/compiler/cli/compile-subscribable.js \
-  examples/subscribables/venue_detail.sql \
+  examples/venue-detail-subscribable.sql \
   > /tmp/venue_detail.sql
 
 # Deploy to database

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -19,6 +19,7 @@
     "src/**/*.js",
     "src/database/migrations/**/*.sql",
     "docs/**/*.md",
+    "docs/examples/*.sql",
     "README.md",
     "LICENSE"
   ],

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

@@ -0,0 +1,147 @@
+/**
+ * Auth Code Generator
+ * Generates PostgreSQL functions for user authentication
+ * Only generated when the entity is named 'users'
+ */
+
+export class AuthCodegen {
+  constructor(entity) {
+    this.entity = entity;
+    this.tableName = entity.tableName;
+  }
+
+  /**
+   * Check if this entity should have auth functions generated
+   * @returns {boolean}
+   */
+  shouldGenerate() {
+    return this.tableName === 'users';
+  }
+
+  /**
+   * Generate all auth functions
+   * @returns {string} SQL for auth functions
+   */
+  generateAll() {
+    if (!this.shouldGenerate()) {
+      return '';
+    }
+
+    return [
+      this._generateProfileFunction(),
+      this._generateRegisterFunction(),
+      this._generateLoginFunction()
+    ].join('\n\n');
+  }
+
+  /**
+   * Generate _profile function
+   * Returns all user columns except sensitive fields
+   * @private
+   */
+  _generateProfileFunction() {
+    return `-- ============================================================================
+-- Auth: _profile function for ${this.tableName}
+-- Returns user record minus sensitive fields
+-- ============================================================================
+CREATE OR REPLACE FUNCTION _profile(p_user_id INT)
+RETURNS JSONB
+LANGUAGE SQL
+SECURITY DEFINER
+AS $$
+  SELECT jsonb_build_object('user_id', u.id) || (to_jsonb(u.*) - 'id' - 'password_hash' - 'password' - 'secret' - 'token')
+  FROM ${this.tableName} u
+  WHERE id = p_user_id;
+$$;`;
+  }
+
+  /**
+   * Generate register_user function
+   * Supports optional extra 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
+-- 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 '{}')
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+  v_user_id INT;
+  v_salt TEXT;
+  v_hash TEXT;
+  v_insert_data JSONB;
+BEGIN
+  -- Generate salt and hash password
+  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);
+
+  -- Dynamic INSERT from JSONB (same pattern as compiled save functions)
+  EXECUTE (
+    SELECT format(
+      'INSERT INTO ${this.tableName} (%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';
+END $$;`;
+  }
+
+  /**
+   * Generate login_user function
+   * @private
+   */
+  _generateLoginFunction() {
+    return `-- ============================================================================
+-- Auth: login_user function for ${this.tableName}
+-- ============================================================================
+CREATE OR REPLACE FUNCTION login_user(p_email TEXT, p_password TEXT)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+  v_user_record RECORD;
+BEGIN
+  SELECT id, email, password_hash
+  INTO v_user_record
+  FROM ${this.tableName}
+  WHERE email = p_email;
+
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Invalid credentials' USING errcode = '28000';
+  END IF;
+
+  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(v_user_record.id);
+END $$;`;
+  }
+}
+
+/**
+ * Generate auth functions for an entity (only if it's the users table)
+ * @param {Object} entity - Entity configuration
+ * @returns {string} SQL for auth functions (empty string if not users table)
+ */
+export function generateAuthFunctions(entity) {
+  const codegen = new AuthCodegen(entity);
+  return codegen.generateAll();
+}

package/src/compiler/compiler.js

@@ -10,6 +10,7 @@ import { generateOperations } from './codegen/operation-codegen.js';
 import { generateNotificationFunction } from './codegen/notification-codegen.js';
 import { generateGraphRuleFunctions } from './codegen/graph-rules-codegen.js';
 import { generateSubscribable } from './codegen/subscribable-codegen.js';
+import { generateAuthFunctions } from './codegen/auth-codegen.js';
 import crypto from 'crypto';
 
 export class DZQLCompiler {
@@ -53,6 +54,12 @@ export class DZQLCompiler {
     const operationSQL = generateOperations(normalizedEntity);
     sections.push(operationSQL);
 
+    // Auth functions (only for users table)
+    const authSQL = generateAuthFunctions(normalizedEntity);
+    if (authSQL) {
+      sections.push(authSQL);
+    }
+
     // Notification path resolution (if needed)
     if (normalizedEntity.notificationPaths &&
         Object.keys(normalizedEntity.notificationPaths).length > 0) {

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

@@ -5,37 +5,51 @@
 create extension if not exists pgcrypto;
 
 -- === Users Table ===
+-- Core auth table with optional name field
+-- Applications can add additional columns as needed
+-- 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,
-  name text not null,
-  password_hash text not null,
-  created_at timestamptz default now()
+  password_hash text not null
 );
 
 -- === Auth Functions ===
 
 -- Register new user
-create or replace function register_user(p_email text, p_password text)
+-- p_extra: 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 '{}')
 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);
+  v_salt := gen_salt('bf', 10);
+  v_hash := crypt(p_password, v_salt);
 
-  -- Insert user
-  insert into users (email, name, password_hash)
-  values (p_email, split_part(p_email, '@', 1), hash)
-  returning id into user_id;
+  -- 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);
 
-  return _profile(user_id);
+  -- Dynamic INSERT from JSONB (same pattern as compiled save functions)
+  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';
@@ -50,7 +64,7 @@ as $$
 declare
   user_record record;
 begin
-  select id, email, name, password_hash
+  select id, email, password_hash
   into user_record
   from users
   where email = p_email;
@@ -67,17 +81,14 @@ begin
 end $$;
 
 -- Get user profile (private function)
+-- Returns all user columns except sensitive fields (password_hash, password, secret, token)
+-- This allows the users table to have any additional columns without modifying this function
 create or replace function _profile(p_user_id int)
 returns jsonb
 language sql
 security definer
 as $$
-  select jsonb_build_object(
-    'user_id', id,
-    'email', email,
-    'name', name,
-    'created_at', created_at
-  )
-  from users
+  select jsonb_build_object('user_id', u.id) || (to_jsonb(u.*) - 'id' - 'password_hash' - 'password' - 'secret' - 'token')
+  from users u
   where id = p_user_id;
 $$;