dzql 0.5.33 → 0.6.0

package/docs/compiler/QUICKSTART.md

@@ -1,326 +0,0 @@
-# DZQL Compiler - Quick Start Guide
-
-Get up and running with the DZQL Compiler in 5 minutes.
-
-## Installation
-
-```bash
-cd /home/user/dzql/packages/dzql-compiler
-bun install
-```
-
-## Basic Usage
-
-### 1. Compile Your First Entity
-
-```bash
-# Compile the venues domain (9 entities)
-bun src/cli/index.js /home/user/dzql/packages/venues/database/init_db/009_venues_domain.sql -o compiled/
-
-# Output will be in compiled/ directory
-```
-
-### 2. Examine the Output
-
-```bash
-# View generated SQL for venues
-cat compiled/venues.sql
-
-# Check checksums
-cat compiled/checksums.json
-```
-
-### 3. Run the Tests
-
-```bash
-# All tests should pass
-bun test
-```
-
-## What You Get
-
-For each entity, the compiler generates:
-
-### Permission Functions
-```sql
-can_create_venues(p_user_id INT, p_record JSONB) → BOOLEAN
-can_update_venues(p_user_id INT, p_record JSONB) → BOOLEAN
-can_delete_venues(p_user_id INT, p_record JSONB) → BOOLEAN
-can_view_venues(p_user_id INT, p_record JSONB) → BOOLEAN
-```
-
-### CRUD Operations
-```sql
-get_venues(p_user_id INT, p_id INT) → JSONB
-save_venues(p_user_id INT, p_data JSONB) → JSONB
-delete_venues(p_user_id INT, p_id INT) → JSONB
-lookup_venues(p_user_id INT, p_filter TEXT) → JSONB
-search_venues(p_user_id INT, p_filters JSONB, p_search TEXT, ...) → JSONB
-```
-
-> **Note:** `p_user_id` is always the first parameter in all functions. See [CODING_STANDARDS.md](./CODING_STANDARDS.md).
-
-## Example: Compile a Simple Entity
-
-Create `examples/todos.sql`:
-
-```sql
-select dzql.register_entity(
-  'todos',
-  'title',
-  array['title', 'description'],
-  '{}',  -- no FK includes
-  false, -- no soft delete
-  '{}',  -- no temporal fields
-  '{}',  -- no notifications
-  jsonb_build_object(
-    'view', array[]::text[],      -- public
-    'create', array[]::text[],    -- public
-    'update', array['@owner_id'], -- owner only
-    'delete', array['@owner_id']  -- owner only
-  )
-);
-```
-
-Compile it:
-
-```bash
-bun src/cli/index.js examples/todos.sql -o compiled/
-```
-
-Result: `compiled/todos.sql` with 5 operations + 4 permission checks.
-
-## Using Compiled Functions
-
-Once deployed to PostgreSQL:
-
-```sql
--- Get a todo (p_user_id first, then p_id)
-SELECT get_todos(42, 1);  -- user_id=42, id=1
-
--- Create a todo (p_user_id first, then p_data)
-SELECT save_todos(42, '{"title": "Learn DZQL", "owner_id": 42}'::jsonb);
-
--- Search todos (p_user_id first)
-SELECT search_todos(
-  42,             -- user_id
-  '{}',           -- filters
-  'DZQL',         -- search text
-  '{"field": "title", "order": "asc"}', -- sort
-  1,              -- page
-  25              -- limit
-);
-
--- Delete a todo (p_user_id first, then p_id)
-SELECT delete_todos(42, 1);
-```
-
-## Development Workflow
-
-### 1. Define Entity
-
-Edit `entities/my_entity.sql`:
-
-```sql
-select dzql.register_entity(
-  'my_entity',
-  'name',
-  array['name'],
-  '{}',
-  false
-);
-```
-
-### 2. Compile
-
-```bash
-bun src/cli/index.js entities/my_entity.sql -o compiled/
-```
-
-### 3. Deploy
-
-```bash
-psql -U dzql -d dzql < compiled/my_entity.sql
-```
-
-### 4. Use
-
-```sql
-SELECT save_my_entity(1, '{"name": "Test"}'::jsonb);  -- user_id first, then data
-```
-
-## Programmatic API
-
-```javascript
-import { DZQLCompiler } from './src/compiler.js';
-
-const compiler = new DZQLCompiler();
-
-// Compile from object
-const result = compiler.compile({
-  tableName: 'posts',
-  labelField: 'title',
-  searchableFields: ['title', 'body'],
-  permissionPaths: {
-    view: [],
-    update: ['@author_id']
-  }
-});
-
-console.log(result.sql);
-console.log(result.checksum);
-
-// Compile from SQL
-import { readFileSync } from 'fs';
-
-const sql = readFileSync('entities/posts.sql', 'utf-8');
-const results = compiler.compileFromSQL(sql);
-
-for (const entity of results.results) {
-  console.log(`Compiled ${entity.tableName}: ${entity.checksum}`);
-}
-```
-
-## Verifying Compilation
-
-### Check Checksums
-
-```javascript
-import { readFileSync } from 'fs';
-
-const checksums = JSON.parse(readFileSync('compiled/checksums.json', 'utf-8'));
-
-console.log(checksums.venues);
-// {
-//   checksum: "9c116484...",
-//   generatedAt: "2025-11-16T01:38:54.321Z",
-//   compilationTime: 12
-// }
-```
-
-### Test Functions
-
-```sql
--- Test permission check (p_user_id first)
-SELECT can_update_venues(42, '{"org_id": 1}'::jsonb);
-
--- Test GET with FK expansion (p_user_id first, then p_id)
-SELECT get_venues(42, 1);
--- Returns: { id: 1, name: "...", org: { id: 1, name: "..." }, sites: [...] }
-
--- Test SEARCH (p_user_id first)
-SELECT search_venues(42, '{}', 'garden', null, 1, 10);
--- Returns: { data: [...], total: 5, page: 1, limit: 10 }
-```
-
-## Common Patterns
-
-### Public Read, Owner Write
-
-```sql
-select dzql.register_entity(
-  'blog_posts',
-  'title',
-  array['title', 'body'],
-  '{}',
-  false,
-  '{}',
-  '{}',
-  jsonb_build_object(
-    'view', array[]::text[],      -- anyone can read
-    'create', array[]::text[],    -- anyone can create
-    'update', array['@author_id'], -- only author can update
-    'delete', array['@author_id']  -- only author can delete
-  )
-);
-```
-
-### Organization-Scoped
-
-```sql
-select dzql.register_entity(
-  'projects',
-  'name',
-  array['name', 'description'],
-  '{"org": "organisations"}',
-  false,
-  '{}',
-  '{}',
-  jsonb_build_object(
-    'view', array['@org_id->members[org_id=$]{active}.user_id'],
-    'update', array['@org_id->members[org_id=$,role=admin]{active}.user_id'],
-    'delete', array['@org_id->members[org_id=$,role=admin]{active}.user_id'],
-    'create', array['@org_id->members[org_id=$]{active}.user_id']
-  )
-);
-```
-
-### Temporal Data
-
-```sql
-select dzql.register_entity(
-  'memberships',
-  'user_id',
-  array['user_id', 'org_id'],
-  '{"user": "users", "org": "organisations"}',
-  false,
-  '{"valid_from": "valid_from", "valid_to": "valid_to"}', -- temporal!
-  '{}',
-  '{}'
-);
-```
-
-## Debugging
-
-### View Generated SQL
-
-```bash
-# Pretty print generated SQL
-cat compiled/venues.sql | less
-
-# Search for specific function
-grep -A 20 "CREATE OR REPLACE FUNCTION get_venues" compiled/venues.sql
-```
-
-### Check Compilation Errors
-
-```bash
-# Compile with verbose output
-DZQL_COMPILER_VERBOSE=true bun src/cli/index.js entities/my_entity.sql -o compiled/
-```
-
-### Test in PostgreSQL
-
-```sql
--- Enable query logging
-SET log_statement = 'all';
-
--- Test function (p_user_id first)
-SELECT get_venues(42, 1);
-
--- View execution plan
-EXPLAIN ANALYZE SELECT get_venues(42, 1);
-```
-
-## Next Steps
-
-1. **Compile existing entities** - Try compiling your current DZQL entities
-2. **Review generated SQL** - Understand what the compiler produces
-3. **Test in staging** - Deploy to a test database and verify behavior
-4. **Benchmark performance** - Compare runtime vs compiled versions
-5. **Report issues** - Let us know what works and what doesn't!
-
-## Need Help?
-
-- **README.md** - Complete documentation
-- **SUMMARY.md** - What was built and how
-- **tests/compiler.test.js** - Usage examples
-- **examples/compiled/** - Real compiled output
-
-## Resources
-
-- Vision document: `/home/user/dzql/vision.md`
-- Current DZQL: `/home/user/dzql/packages/dzql/`
-- Example apps: `/home/user/dzql/packages/venues/`
-
-Happy compiling! 🚀

package/docs/compiler/README.md

@@ -1,134 +0,0 @@
-# DZQL Compiler Documentation
-
-The DZQL Compiler transforms declarative entity definitions into optimized PostgreSQL stored procedures.
-
-## Quick Start
-
-- **[Quickstart Guide](QUICKSTART.md)** - Get started with the compiler in 5 minutes
-
-## Reference
-
-- **[Advanced Filters](ADVANCED_FILTERS.md)** - Complex search operators and patterns
-- **[Coding Standards](CODING_STANDARDS.md)** - Best practices for DZQL code
-- **[Comparison](COMPARISON.md)** - Runtime vs compiled side-by-side
-
-## Using the Compiler
-
-### Via CLI
-
-```bash
-dzql compile database/domain.sql -o compiled/
-```
-
-### Programmatically
-
-```javascript
-import { DZQLCompiler } from 'dzql/compiler';
-
-const compiler = new DZQLCompiler();
-const result = compiler.compileFromSQL(sqlContent);
-
-console.log(result.sql);  // Generated PostgreSQL
-```
-
-### Registering Entities
-
-```sql
-SELECT dzql.register_entity(
-  'todos',                              -- Table name
-  'title',                              -- Label field
-  array['title', 'description'],        -- Searchable fields
-  '{}'::jsonb,                          -- FK includes
-  false,                                -- Soft delete
-  '{}'::jsonb,                          -- Temporal config
-  '{}'::jsonb,                          -- Notification paths
-  '{}'::jsonb,                          -- Permission paths
-  '{}'::jsonb,                          -- Graph rules (including M2M)
-  '{}'::jsonb                           -- Field defaults
-);
-```
-
-This generates 5 PostgreSQL functions:
-- `get_todos(params, user_id)` - Retrieve single record
-- `save_todos(params, user_id)` - Create or update
-- `delete_todos(params, user_id)` - Delete record
-- `lookup_todos(params, user_id)` - Autocomplete
-- `search_todos(params, user_id)` - Search with filters
-
-## Compiler Features (v0.3.1+)
-
-The compiler generates **static, optimized SQL** with zero runtime interpretation:
-
-### Many-to-Many Relationships
-```sql
-SELECT dzql.register_entity(
-  'brands', 'name', ARRAY['name'],
-  '{}', false, '{}', '{}', '{}',
-  '{
-    "many_to_many": {
-      "tags": {
-        "junction_table": "brand_tags",
-        "local_key": "brand_id",
-        "foreign_key": "tag_id",
-        "target_entity": "tags",
-        "id_field": "tag_ids",
-        "expand": false
-      }
-    }
-  }',
-  '{}'
-);
-```
-
-**Generated code:** Static M2M sync blocks (50-100x faster than generic operations)
-- No runtime loops
-- All table/column names are literals
-- PostgreSQL can fully optimize and cache plans
-
-See [Many-to-Many Guide](../guides/many-to-many.md) for details.
-
-### Composite Primary Keys
-```sql
-SELECT dzql.register_entity(
-  'product_task_template_dependencies', 'template_id', ARRAY[]::text[],
-  '{}', false, '{}', '{}', '{}',
-  '{
-    "primary_key": ["template_id", "depends_on_template_id"]
-  }',
-  '{}'
-);
-```
-
-**Generated code:** Event records use all primary key columns
-- Default assumes `id` column
-- Composite keys generate `jsonb_build_object('col1', v_result.col1, 'col2', v_result.col2)`
-- Required for junction tables and other composite PK scenarios
-
-### Field Defaults
-```sql
-'{
-  "owner_id": "@user_id",
-  "created_at": "@now",
-  "status": "draft"
-}'
-```
-
-**Generated code:** Auto-populates fields on INSERT
-
-See [Field Defaults Guide](../guides/field-defaults.md) for details.
-
-## Architecture
-
-The compiler uses a three-phase approach:
-
-1. **Parse** - Extract entity definitions from SQL
-2. **Generate** - Create optimized PostgreSQL functions
-3. **Deploy** - Execute generated SQL
-
-All business logic runs in PostgreSQL, not application code.
-
-## See Also
-
-- [Main Documentation](../) - Full DZQL documentation
-- [API Reference](../reference/api.md) - The 5 operations
-- [For AI](../for-ai/claude-guide.md) - AI-assisted development

package/docs/examples/README.md

@@ -1,38 +0,0 @@
-# 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

@@ -1,160 +0,0 @@
--- ============================================================================
--- 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

@@ -1,8 +0,0 @@
--- 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

@@ -1,45 +0,0 @@
--- 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'
-      )
-    )
-  )
-);