dzql 0.4.4 → 0.4.5

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.5",
   "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"
   ],