dzql 0.5.33 → 0.6.0

package/docs/guides/composite-primary-keys.md

@@ -1,158 +0,0 @@
-# Composite Primary Keys
-
-DZQL supports tables with composite (compound) primary keys. This guide explains how to register entities with composite keys and how the generated CRUD functions work.
-
-## When to Use Composite Keys
-
-Composite primary keys are useful for:
-
-- **Junction tables** with additional data (beyond simple M2M)
-- **Position/state tables** keyed by entity type and ID
-- **Multi-tenant tables** keyed by tenant + entity
-- **Versioned records** keyed by ID + version
-
-## Registering an Entity with a Composite Key
-
-To register an entity with a composite primary key, add `primary_key` to the `graph_rules` parameter:
-
-```sql
--- Create a table with composite primary key
-CREATE TABLE canvas_positions (
-  entity_type VARCHAR(50) NOT NULL,
-  entity_id INTEGER NOT NULL,
-  x INTEGER NOT NULL,
-  y INTEGER NOT NULL,
-  width INTEGER DEFAULT 100,
-  height INTEGER DEFAULT 100,
-  PRIMARY KEY (entity_type, entity_id)
-);
-
--- Register with DZQL using composite key
-SELECT dzql.register_entity(
-  'canvas_positions',                          -- table_name
-  'entity_type',                               -- label_field
-  array['x', 'y', 'width', 'height'],          -- searchable_fields
-  '{}',                                        -- fk_includes
-  false,                                       -- soft_delete
-  '{}',                                        -- temporal_fields
-  '{}',                                        -- notification_paths
-  jsonb_build_object(                          -- permission_paths
-    'view', array[]::text[],
-    'create', array[]::text[],
-    'update', array[]::text[],
-    'delete', array[]::text[]
-  ),
-  jsonb_build_object(                          -- graph_rules
-    'primary_key', array['entity_type', 'entity_id']
-  )
-);
-```
-
-The `primary_key` array specifies the columns that form the composite key, in order.
-
-## Generated Function Signatures
-
-When you compile an entity with a composite primary key, the generated functions have different signatures:
-
-### GET Function
-
-```sql
--- Accepts JSONB with all PK fields
-SELECT get_canvas_positions(
-  1,                                           -- user_id
-  '{"entity_type": "node", "entity_id": 42}'   -- composite PK as JSONB
-);
-```
-
-### SAVE Function
-
-```sql
--- Insert: provide all PK fields plus data
-SELECT save_canvas_positions(
-  1,                                           -- user_id
-  '{"entity_type": "node", "entity_id": 42, "x": 100, "y": 200}'
-);
-
--- Update: same signature, existing record detected by PK
-SELECT save_canvas_positions(
-  1,
-  '{"entity_type": "node", "entity_id": 42, "x": 150, "y": 250}'
-);
-```
-
-The save function determines insert vs update by checking if a record with the composite key exists.
-
-### DELETE Function
-
-```sql
--- Accepts JSONB with all PK fields
-SELECT delete_canvas_positions(
-  1,                                           -- user_id
-  '{"entity_type": "node", "entity_id": 42}'   -- composite PK as JSONB
-);
-```
-
-### SEARCH Function
-
-Search works the same as simple PK entities - it returns paginated results with all fields.
-
-## Type Casting
-
-DZQL automatically determines type casting for PK columns:
-
-- Columns named `id` or ending with `_id` are cast to `::int`
-- Other columns (like `entity_type`) are left as text
-
-This means for a key like `(entity_type, entity_id)`:
-- `entity_type` is compared as text
-- `entity_id` is cast to integer
-
-## Events and Notifications
-
-Events for composite PK entities include the full composite key in the `pk` field:
-
-```json
-{
-  "table_name": "canvas_positions",
-  "op": "insert",
-  "pk": {"entity_type": "node", "entity_id": 42},
-  "data": {"entity_type": "node", "entity_id": 42, "x": 100, "y": 200}
-}
-```
-
-## Limitations
-
-- **M2M relationships**: Tables with composite PKs can have M2M relationships, but this is an advanced use case. The M2M sync uses the first PK column for junction table lookups.
-- **Auto-increment**: Composite keys don't support auto-increment. All PK values must be provided on insert.
-
-## Example: Template Dependencies
-
-A practical example - tracking dependencies between templates:
-
-```sql
-CREATE TABLE template_dependencies (
-  template_id INTEGER NOT NULL REFERENCES templates(id),
-  depends_on_template_id INTEGER NOT NULL REFERENCES templates(id),
-  dependency_type VARCHAR(20) DEFAULT 'requires',
-  PRIMARY KEY (template_id, depends_on_template_id)
-);
-
-SELECT dzql.register_entity(
-  'template_dependencies',
-  'dependency_type',
-  array['dependency_type'],
-  '{"template": "templates", "depends_on": "templates"}',
-  false,
-  '{}',
-  '{}',
-  jsonb_build_object(
-    'view', array[]::text[],
-    'create', array[]::text[],
-    'update', array[]::text[],
-    'delete', array[]::text[]
-  ),
-  jsonb_build_object(
-    'primary_key', array['template_id', 'depends_on_template_id']
-  )
-);
-```

package/docs/guides/custom-functions.md

@@ -1,362 +0,0 @@
-# Custom Functions
-
-Add custom business logic to your entities with automatic compilation support.
-
-## Overview
-
-DZQL's compiler now automatically includes custom SQL functions defined after entity registration. This eliminates the need to manually maintain functions in multiple locations.
-
-## Benefits
-
-- **Single Source of Truth** - Define functions once in entity files
-- **No Manual Syncing** - Compiler handles everything
-- **Functions Stay With Entities** - Clear organization
-- **Automatic Registration** - Registry entries included
-
-## How It Works
-
-### Before (Manual Duplication)
-
-You had to maintain functions in two places:
-
-```sql
--- entities/calendar.sql (source)
-SELECT dzql.register_entity('tags', ...);
-
-CREATE FUNCTION toggle_resource_tag(...) RETURNS JSONB AS $$ ... $$;
-INSERT INTO dzql.registry (fn_regproc) VALUES ('toggle_resource_tag'::regproc);
-```
-
-Then manually copy to:
-
-```sql
--- init_db/002_schema.sql (deployment)
-CREATE FUNCTION toggle_resource_tag(...) RETURNS JSONB AS $$ ... $$;
-INSERT INTO dzql.registry (fn_regproc) VALUES ('toggle_resource_tag'::regproc);
-```
-
-**Problems:**
-- Functions exist in two places
-- Easy to forget to sync
-- Unclear which is source of truth
-
-### After (Automatic Pass-through)
-
-Just define functions once after entity registration:
-
-```sql
--- entities/calendar.sql
-SELECT dzql.register_entity('tags', 'name', ...);
-
--- Custom function - automatically passed through by compiler!
-CREATE OR REPLACE FUNCTION toggle_resource_tag(
-  p_user_id INT,
-  p_resource_id INT,
-  p_tag_id INT
-) RETURNS JSONB AS $$
-DECLARE
-  v_exists BOOLEAN;
-BEGIN
-  SELECT EXISTS(
-    SELECT 1 FROM resource_tags
-    WHERE resource_id = p_resource_id AND tag_id = p_tag_id
-  ) INTO v_exists;
-
-  IF v_exists THEN
-    DELETE FROM resource_tags
-    WHERE resource_id = p_resource_id AND tag_id = p_tag_id;
-  ELSE
-    INSERT INTO resource_tags (resource_id, tag_id)
-    VALUES (p_resource_id, p_tag_id);
-  END IF;
-
-  RETURN jsonb_build_object('success', true, 'exists', NOT v_exists);
-END;
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-
--- Register for RPC access
-INSERT INTO dzql.registry (fn_regproc)
-VALUES ('toggle_resource_tag'::regproc);
-```
-
-After `dzql compile`, the custom function automatically appears in:
-- `init_db/tags.sql` under "Custom Functions" section
-
-## What Gets Passed Through
-
-The compiler extracts:
-
-1. **CREATE FUNCTION statements**
-   ```sql
-   CREATE FUNCTION my_function(...) RETURNS ... AS $$ ... $$;
-   CREATE OR REPLACE FUNCTION my_function(...) RETURNS ... AS $$ ... $$;
-   ```
-
-2. **Registry registrations**
-   ```sql
-   INSERT INTO dzql.registry (fn_regproc) VALUES ('my_function'::regproc);
-   ```
-
-3. **Alternative registration syntax** (if you use it)
-   ```sql
-   SELECT dzql.register_function('my_function');
-   ```
-
-## Scope
-
-Custom functions are extracted from **after** the entity registration until:
-- The next `dzql.register_entity()` call, OR
-- End of file
-
-```sql
--- Entity 1
-SELECT dzql.register_entity('users', ...);
-CREATE FUNCTION user_helper() ...;  -- Included with users entity
-
--- Entity 2
-SELECT dzql.register_entity('posts', ...);
-CREATE FUNCTION post_helper() ...;  -- Included with posts entity
-```
-
-Each entity gets its own custom functions isolated in the compiled output.
-
-## Compiled Output Format
-
-```sql
--- ============================================================================
--- DZQL Compiled Functions for: tags
--- Generated: 2025-11-20T15:00:00.000Z
--- ============================================================================
-
--- [Generated CRUD functions: get_tags, save_tags, delete_tags, etc.]
-
--- ============================================================================
--- Custom Functions for: tags
--- Pass-through from entity definition
--- ============================================================================
-
-CREATE OR REPLACE FUNCTION toggle_resource_tag(...) ...;
-
-INSERT INTO dzql.registry (fn_regproc) VALUES ('toggle_resource_tag'::regproc);
-```
-
-## Use Cases
-
-### Toggle Relationships
-
-```sql
-CREATE OR REPLACE FUNCTION toggle_favorite(
-  p_user_id INT,
-  p_item_id INT
-) RETURNS JSONB AS $$
-  -- Toggle logic here
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-```
-
-### Computed Fields
-
-```sql
-CREATE OR REPLACE FUNCTION calculate_item_score(
-  p_user_id INT,
-  p_item_id INT
-) RETURNS JSONB AS $$
-  -- Scoring logic here
-$$ LANGUAGE plpgsql;
-```
-
-### Bulk Operations
-
-```sql
-CREATE OR REPLACE FUNCTION bulk_assign_tags(
-  p_user_id INT,
-  p_resource_ids INT[],
-  p_tag_id INT
-) RETURNS JSONB AS $$
-  -- Bulk assignment here
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-```
-
-### Complex Business Logic
-
-```sql
-CREATE OR REPLACE FUNCTION approve_workflow(
-  p_user_id INT,
-  p_document_id INT
-) RETURNS JSONB AS $$
-  -- Multi-step approval logic
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-```
-
-## Best Practices
-
-### 1. Keep Functions Close to Entities
-
-Define functions right after the related entity registration:
-
-```sql
-SELECT dzql.register_entity('documents', ...);
-
--- Related custom functions
-CREATE FUNCTION approve_document(...) ...;
-CREATE FUNCTION reject_document(...) ...;
-```
-
-### 2. Always Register Functions
-
-Don't forget to register for RPC access:
-
-```sql
-CREATE FUNCTION my_function(...) ...;
-
--- Required for client access!
-INSERT INTO dzql.registry (fn_regproc) VALUES ('my_function'::regproc);
-```
-
-### 3. Use SECURITY DEFINER Carefully
-
-Only use `SECURITY DEFINER` when the function needs elevated privileges:
-
-```sql
--- Needs elevated privileges (good use of SECURITY DEFINER)
-CREATE FUNCTION admin_delete_user(...)
-RETURNS void AS $$ ... $$
-LANGUAGE plpgsql SECURITY DEFINER;
-
--- User operates on own data (use SECURITY INVOKER or default)
-CREATE FUNCTION update_profile(...)
-RETURNS jsonb AS $$ ... $$
-LANGUAGE plpgsql;  -- SECURITY INVOKER is default
-```
-
-### 4. Include Permission Checks
-
-Custom functions should validate permissions:
-
-```sql
-CREATE OR REPLACE FUNCTION custom_operation(
-  p_user_id INT,
-  p_item_id INT
-) RETURNS JSONB AS $$
-BEGIN
-  -- Always check permission first!
-  IF NOT dzql.check_permission(p_user_id, 'update', 'items',
-    (SELECT to_jsonb(items.*) FROM items WHERE id = p_item_id)
-  ) THEN
-    RAISE EXCEPTION 'Permission denied';
-  END IF;
-
-  -- Business logic here
-  ...
-END;
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-```
-
-## Limitations
-
-### Functions Not Related to Entities
-
-If you have utility functions not tied to a specific entity, you have two options:
-
-**Option 1:** Create a dedicated entity file
-```sql
--- entities/utils.sql
--- No entity registration, just functions
-
-CREATE FUNCTION general_utility(...) ...;
-INSERT INTO dzql.registry (fn_regproc) VALUES ('general_utility'::regproc);
-```
-
-**Option 2:** Keep in manual migration file
-```sql
--- init_db/002_utilities.sql
-CREATE FUNCTION general_utility(...) ...;
-```
-
-### Detection Logic
-
-The compiler extracts SQL between entity registrations. Only these patterns are recognized:
-
-- `CREATE FUNCTION ...` or `CREATE OR REPLACE FUNCTION ...`
-- `INSERT INTO dzql.registry ...`
-- `SELECT dzql.register_function(...)`
-
-Other SQL (like `CREATE TYPE`, `CREATE INDEX`) is **not** automatically passed through.
-
-## Migration
-
-### For Existing Projects
-
-If you already have custom functions duplicated:
-
-1. **Keep functions in entity files** (e.g., `entities/calendar.sql`)
-2. **Remove from manual migration files** (e.g., `init_db/002_schema.sql`)
-3. **Recompile:** `dzql compile entities/*.sql`
-4. **Deploy:** Updated compiled functions
-
-Your entity files become the single source of truth!
-
-## Example: Complete Entity with Custom Functions
-
-```sql
--- entities/resources.sql
-
--- Create table
-CREATE TABLE resources (
-  id serial PRIMARY KEY,
-  org_id integer REFERENCES organisations(id),
-  title text NOT NULL,
-  description text,
-  owner_id integer REFERENCES users(id)
-);
-
--- Register entity
-SELECT dzql.register_entity(
-  'resources',
-  'title',
-  ARRAY['title', 'description'],
-  '{"org": "organisations"}',
-  false,
-  '{}',
-  '{}',
-  '{"view": [], "create": [], "update": ["@owner_id"], "delete": ["@owner_id"]}',
-  '{}',
-  '{"owner_id": "@user_id"}'
-);
-
--- Custom function (automatically passed through)
-CREATE OR REPLACE FUNCTION assign_resource_to_user(
-  p_user_id INT,
-  p_resource_id INT,
-  p_target_user_id INT
-) RETURNS JSONB
-LANGUAGE plpgsql SECURITY DEFINER AS $$
-BEGIN
-  -- Check permission
-  IF NOT dzql.check_permission(p_user_id, 'update', 'resources',
-    (SELECT to_jsonb(resources.*) FROM resources WHERE id = p_resource_id)
-  ) THEN
-    RAISE EXCEPTION 'Permission denied';
-  END IF;
-
-  -- Update owner
-  UPDATE resources
-  SET owner_id = p_target_user_id
-  WHERE id = p_resource_id;
-
-  -- Return updated resource
-  RETURN (SELECT to_jsonb(resources.*) FROM resources WHERE id = p_resource_id);
-END;
-$$;
-
--- Register for RPC access
-INSERT INTO dzql.registry (fn_regproc)
-VALUES ('assign_resource_to_user'::regproc);
-```
-
-After compilation, everything is in `init_db/resources.sql` - no manual copying needed!
-
-## See Also
-
-- [Many-to-Many Support](./many-to-many.md) - M2M relationships eliminate many toggle functions
-- [Field Defaults](./field-defaults.md) - Auto-populate fields
-- [Graph Rules](../reference/api.md#graph-rules) - Automatic relationship management