dzql 0.1.0 → 0.1.2

package/GETTING_STARTED.md

@@ -2,7 +2,7 @@
 
 DZQL is a PostgreSQL framework that gives you **atomic real-time updates** via WebSocket. Every database change broadcasts instantly to all connected clients. Zero boilerplate.
 
-> **See also:** [REFERENCE.md](REFERENCE.md) for complete API documentation | [CLAUDE.md](../../CLAUDE.md) for AI development guide
+> **See also:** [REFERENCE.md](REFERENCE.md) for complete API documentation | [CLAUDE.md](../../docs/CLAUDE.md) for AI development guide
 
 ## The Core Pattern
 

package/README.md

@@ -9,7 +9,7 @@ All documentation is maintained in the repository root:
 - **[README.md](../../README.md)** - Project overview and quick start
 - **[GETTING_STARTED.md](GETTING_STARTED.md)** - Complete tutorial with working todo app
 - **[REFERENCE.md](REFERENCE.md)** - Complete API reference
-- **[CLAUDE.md](../../CLAUDE.md)** - Development guide for AI assistants
+- **[CLAUDE.md](../../docs/CLAUDE.md)** - Development guide for AI assistants
 - **[Venues Example](../venues/)** - Full working application
 
 ## Quick Install

package/REFERENCE.md

@@ -1,6 +1,6 @@
 # DZQL API Reference
 
-Complete API documentation for DZQL framework. For tutorials, see [GETTING_STARTED.md](GETTING_STARTED.md). For AI development guide, see [CLAUDE.md](../../CLAUDE.md).
+Complete API documentation for DZQL framework. For tutorials, see [GETTING_STARTED.md](GETTING_STARTED.md). For AI development guide, see [CLAUDE.md](../../docs/CLAUDE.md).
 
 ## Table of Contents
 
@@ -403,12 +403,16 @@ Automatically manage entity relationships when data changes.
   "on_create": {
     "rule_name": {
       "description": "Human-readable description",
+      "condition": "@after.field = 'value'",  // Optional: only run if condition is true
       "actions": [
         {
-          "type": "create|update|delete",
-          "entity": "target_table",
+          "type": "create|update|delete|validate|execute",
+          "entity": "target_table",            // for create/update/delete
           "data": {"field": "@variable"},      // for create/update
-          "match": {"field": "@variable"}      // for update/delete
+          "match": {"field": "@variable"},     // for update/delete
+          "function": "function_name",         // for validate/execute
+          "params": {"param": "@variable"},    // for validate/execute
+          "error_message": "Validation failed" // for validate (optional)
         }
       ]
     }
@@ -425,6 +429,8 @@ Automatically manage entity relationships when data changes.
 | `create` | `entity`, `data` | INSERT new record |
 | `update` | `entity`, `match`, `data` | UPDATE matching records |
 | `delete` | `entity`, `match` | DELETE matching records |
+| `validate` | `function`, `params`, `error_message` | Call validation function, rollback if returns false |
+| `execute` | `function`, `params` | Fire-and-forget function execution |
 
 ### Variables
 
@@ -499,6 +505,69 @@ Variables reference data from the triggering operation:
 }
 ```
 
+#### Data Validation
+```jsonb
+{
+  "on_create": {
+    "validate_positive_price": {
+      "description": "Ensure price is positive",
+      "actions": [{
+        "type": "validate",
+        "function": "validate_positive_value",
+        "params": {"p_value": "@price"},
+        "error_message": "Price must be positive"
+      }]
+    }
+  }
+}
+```
+
+**Note:** Validation function must return BOOLEAN:
+```sql
+CREATE FUNCTION validate_positive_value(p_value INT)
+RETURNS BOOLEAN AS $$
+  SELECT p_value > 0;
+$$ LANGUAGE sql;
+```
+
+#### Conditional Execution
+```jsonb
+{
+  "on_update": {
+    "prevent_posted_changes": {
+      "description": "Prevent modification of posted records",
+      "condition": "@before.status = 'posted'",
+      "actions": [{
+        "type": "validate",
+        "function": "always_false",
+        "params": {},
+        "error_message": "Cannot modify posted records"
+      }]
+    }
+  }
+}
+```
+
+**Available in conditions:** `@before.field`, `@after.field`, `@user_id`, and SQL expressions.
+
+#### Fire-and-Forget Actions
+```jsonb
+{
+  "on_create": {
+    "send_notification": {
+      "description": "Notify external system",
+      "actions": [{
+        "type": "execute",
+        "function": "log_event",
+        "params": {"p_event": "New record created", "p_record_id": "@id"}
+      }]
+    }
+  }
+}
+```
+
+**Note:** Execute actions don't affect transaction. Function errors are logged but don't rollback.
+
 ### Execution
 
 - **Atomic**: All rules execute in the same transaction
@@ -886,6 +955,6 @@ const result = await db.api.myCustomFunction({param: 'value'}, userId);
 ## See Also
 
 - [GETTING_STARTED.md](GETTING_STARTED.md) - Hands-on tutorial
-- [CLAUDE.md](../../CLAUDE.md) - AI development guide
+- [CLAUDE.md](../../docs/CLAUDE.md) - AI development guide
 - [README.md](../../README.md) - Project overview
 - [Venues Example](../venues/) - Complete working application

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -16,17 +16,17 @@
     "README.md",
     "GETTING_STARTED.md",
     "REFERENCE.md",
-    "CLAUDE.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "bun test",
-    "prepublishOnly": "echo '⚠️  Publishing DZQL alpha release...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL v0.1.2...'"
   },
   "dependencies": {
     "jose": "^6.1.0",
     "postgres": "^3.4.7"
   },
+
   "keywords": [
     "postgresql",
     "postgres",

package/src/database/migrations/002_functions.sql

@@ -149,6 +149,82 @@ BEGIN
   RETURN l_result;
 END $$;
 
+-- === Condition Evaluation ===
+-- Evaluates a condition string with variable substitution
+CREATE OR REPLACE FUNCTION dzql.evaluate_condition(
+  p_condition text,
+  p_record_before jsonb,
+  p_record_after jsonb,
+  p_user_id int
+) RETURNS boolean
+LANGUAGE plpgsql AS $$
+DECLARE
+  l_resolved_condition text;
+  l_result boolean;
+  l_match_array text[];
+  l_field_name text;
+  l_field_value text;
+BEGIN
+  -- Replace variables in condition
+  l_resolved_condition := p_condition;
+
+  -- Replace @before.field references
+  IF p_record_before IS NOT NULL THEN
+    LOOP
+      l_match_array := regexp_match(l_resolved_condition, '@before\.(\w+)');
+      EXIT WHEN l_match_array IS NULL;
+
+      l_field_name := l_match_array[1];
+      l_field_value := COALESCE(p_record_before->>l_field_name, 'null');
+      l_resolved_condition := regexp_replace(
+        l_resolved_condition,
+        '@before\.' || l_field_name,
+        quote_literal(l_field_value),
+        1
+      );
+    END LOOP;
+  END IF;
+
+  -- Replace @after.field references
+  IF p_record_after IS NOT NULL THEN
+    LOOP
+      l_match_array := regexp_match(l_resolved_condition, '@after\.(\w+)');
+      EXIT WHEN l_match_array IS NULL;
+
+      l_field_name := l_match_array[1];
+      l_field_value := COALESCE(p_record_after->>l_field_name, 'null');
+      l_resolved_condition := regexp_replace(
+        l_resolved_condition,
+        '@after\.' || l_field_name,
+        quote_literal(l_field_value),
+        1
+      );
+    END LOOP;
+  END IF;
+
+  -- Replace @user_id
+  l_resolved_condition := replace(l_resolved_condition, '@user_id', p_user_id::text);
+
+  -- Replace @id (use after if available, otherwise before)
+  IF p_record_after IS NOT NULL THEN
+    l_resolved_condition := replace(l_resolved_condition, '@id',
+      COALESCE(p_record_after->>'id', 'null'));
+  ELSIF p_record_before IS NOT NULL THEN
+    l_resolved_condition := replace(l_resolved_condition, '@id',
+      COALESCE(p_record_before->>'id', 'null'));
+  END IF;
+
+  -- Execute the condition
+  BEGIN
+    EXECUTE 'SELECT (' || l_resolved_condition || ')::boolean' INTO l_result;
+    RETURN COALESCE(l_result, false);
+  EXCEPTION WHEN OTHERS THEN
+    -- If condition evaluation fails, log and return false
+    RAISE WARNING 'Graph rule condition evaluation failed: % (condition: %)', SQLERRM, l_resolved_condition;
+    RETURN false;
+  END;
+END $$;
+
 -- === Path Resolution Functions ===
 -- Resolve notification/permission paths to user IDs
 -- === Path Resolution Functions ===
@@ -651,8 +727,8 @@ BEGIN
       LOOP
         l_action_type := l_action->>'type';
 
-        -- Check valid action types
-        IF l_action_type NOT IN ('create', 'update', 'delete') THEN
+        -- Check valid action types (includes new 'validate' and 'execute' types)
+        IF l_action_type NOT IN ('create', 'update', 'delete', 'validate', 'execute') THEN
           RAISE WARNING 'Invalid action type: %', l_action_type;
           RETURN false;
         END IF;
@@ -672,6 +748,17 @@ BEGIN
           RAISE WARNING 'Action type % requires "match" field', l_action_type;
           RETURN false;
         END IF;
+
+        -- Validate new action types
+        IF l_action_type IN ('validate', 'execute') AND NOT l_action ? 'function' THEN
+          RAISE WARNING 'Action type % requires "function" field', l_action_type;
+          RETURN false;
+        END IF;
+
+        IF l_action_type IN ('validate', 'execute') AND NOT l_action ? 'params' THEN
+          RAISE WARNING 'Action type % requires "params" field', l_action_type;
+          RETURN false;
+        END IF;
       END LOOP;
     END LOOP;
   END LOOP;

package/src/database/migrations/003_operations.sql

@@ -301,8 +301,16 @@ BEGIN
     EXECUTE l_sql_stmt INTO l_existing_record;
 
     IF l_existing_record IS NULL THEN
-      -- User provided ID but record doesn't exist - this is an error
-      RAISE EXCEPTION 'DZQL: record with id % not found in %', l_args_json ->> l_pk_cols[1], p_entity;
+      -- Record doesn't exist. For composite keys, treat as INSERT.
+      -- For single-column PKs, this is an error (user provided non-existent ID).
+      IF array_length(l_pk_cols, 1) > 1 THEN
+        -- Composite key: treat as INSERT
+        l_is_insert := true;
+      ELSE
+        -- Single PK: this is an error
+        RAISE EXCEPTION 'DZQL: record with %=% not found in %',
+          l_pk_cols[1], l_args_json ->> l_pk_cols[1], p_entity;
+      END IF;
     END IF;
   END IF;
 

package/src/database/migrations/005_entities.sql

@@ -163,6 +163,90 @@ BEGIN
   );
 END $$;
 
+-- === Validate Action ===
+-- Calls a validation function and raises exception if it returns false
+CREATE OR REPLACE FUNCTION dzql.execute_graph_validate(
+  p_function_name text,
+  p_params jsonb,
+  p_error_message text DEFAULT 'Validation failed'
+) RETURNS void
+LANGUAGE plpgsql AS $$
+DECLARE
+  l_result boolean;
+  l_sql text;
+  l_param_list text[];
+  l_key text;
+  l_value text;
+BEGIN
+  -- Validate function name (prevent SQL injection)
+  IF NOT p_function_name ~ '^[a-z_][a-z0-9_]*$' THEN
+    RAISE EXCEPTION 'Invalid function name: %', p_function_name;
+  END IF;
+
+  -- Build parameter list
+  l_param_list := array[]::text[];
+  FOR l_key, l_value IN SELECT * FROM jsonb_each_text(p_params)
+  LOOP
+    l_param_list := l_param_list || (l_key || ' => ' || quote_literal(l_value));
+  END LOOP;
+
+  -- Build and execute function call
+  IF array_length(l_param_list, 1) > 0 THEN
+    l_sql := format('SELECT %I(%s)', p_function_name, array_to_string(l_param_list, ', '));
+  ELSE
+    l_sql := format('SELECT %I()', p_function_name);
+  END IF;
+
+  EXECUTE l_sql INTO l_result;
+
+  -- Raise exception if validation failed
+  IF NOT COALESCE(l_result, false) THEN
+    RAISE EXCEPTION '%', p_error_message;
+  END IF;
+END $$;
+
+-- === Execute Action ===
+-- Calls a custom function with parameters (fire-and-forget)
+CREATE OR REPLACE FUNCTION dzql.execute_graph_function(
+  p_function_name text,
+  p_params jsonb
+) RETURNS jsonb
+LANGUAGE plpgsql AS $$
+DECLARE
+  l_result jsonb;
+  l_sql text;
+  l_param_list text[];
+  l_key text;
+  l_value text;
+BEGIN
+  -- Validate function name (prevent SQL injection)
+  IF NOT p_function_name ~ '^[a-z_][a-z0-9_]*$' THEN
+    RAISE EXCEPTION 'Invalid function name: %', p_function_name;
+  END IF;
+
+  -- Build parameter list
+  l_param_list := array[]::text[];
+  FOR l_key, l_value IN SELECT * FROM jsonb_each_text(p_params)
+  LOOP
+    l_param_list := l_param_list || (l_key || ' => ' || quote_literal(l_value));
+  END LOOP;
+
+  -- Build and execute function call
+  IF array_length(l_param_list, 1) > 0 THEN
+    l_sql := format('SELECT %I(%s)', p_function_name, array_to_string(l_param_list, ', '));
+  ELSE
+    l_sql := format('SELECT %I()', p_function_name);
+  END IF;
+
+  EXECUTE l_sql INTO l_result;
+
+  RETURN COALESCE(l_result, '{}'::jsonb);
+EXCEPTION WHEN OTHERS THEN
+  -- Log error but don't fail the transaction
+  RAISE WARNING 'Graph rule function execution failed: % (function: %)', SQLERRM, p_function_name;
+  RETURN jsonb_build_object('error', SQLERRM);
+END $$;
+
 -- Main graph rules execution engine
 CREATE OR REPLACE FUNCTION dzql.execute_graph_rules(
   p_table_name text,
@@ -189,6 +273,10 @@ DECLARE
   l_execution_log jsonb := '[]'::jsonb;
   l_condition text;
   l_condition_result boolean;
+  l_function_name text;
+  l_function_params jsonb;
+  l_error_message text;
+  l_function_result jsonb;
 BEGIN
   -- Get entity configuration
   SELECT * INTO l_entity_config FROM dzql.entities WHERE table_name = p_table_name;
@@ -230,69 +318,88 @@ BEGIN
     l_condition := l_rule_config->>'condition';
     l_condition_result := true;  -- Default to true if no condition
 
-    -- TODO: Implement condition evaluation
-    -- IF l_condition IS NOT NULL THEN
-    --   l_condition_result := dzql.evaluate_condition(l_condition, p_record_before, p_record_after, p_user_id);
-    -- END IF;
+    IF l_condition IS NOT NULL THEN
+      l_condition_result := dzql.evaluate_condition(l_condition, p_record_before, p_record_after, p_user_id);
+    END IF;
 
     IF l_condition_result THEN
       -- Execute each action in the rule
       FOR l_action IN SELECT * FROM jsonb_array_elements(l_rule_config->'actions')
       LOOP
         l_action_type := l_action->>'type';
-        l_target_entity := l_action->>'entity';
-        l_action_data := l_action->'data';
-        l_action_match := l_action->'match';
-
-        -- Resolve variables in data and match objects
-        IF l_action_data IS NOT NULL THEN
-          l_resolved_data := dzql.resolve_graph_data(l_action_data, p_record_before, p_record_after, p_user_id);
-        END IF;
 
-        IF l_action_match IS NOT NULL THEN
-          l_resolved_match := dzql.resolve_graph_data(l_action_match, p_record_before, p_record_after, p_user_id);
-        END IF;
-
-        -- Execute the action
+        -- Execute the action based on type
         BEGIN
           CASE l_action_type
+            -- Existing action types
             WHEN 'create' THEN
+              l_target_entity := l_action->>'entity';
+              l_action_data := l_action->'data';
+              l_resolved_data := dzql.resolve_graph_data(l_action_data, p_record_before, p_record_after, p_user_id);
               PERFORM dzql.execute_graph_insert(l_target_entity, l_resolved_data, p_user_id);
 
             WHEN 'update' THEN
+              l_target_entity := l_action->>'entity';
+              l_action_data := l_action->'data';
+              l_action_match := l_action->'match';
+              l_resolved_data := dzql.resolve_graph_data(l_action_data, p_record_before, p_record_after, p_user_id);
+              l_resolved_match := dzql.resolve_graph_data(l_action_match, p_record_before, p_record_after, p_user_id);
               PERFORM dzql.execute_graph_update(l_target_entity, l_resolved_match, l_resolved_data, p_user_id);
 
             WHEN 'delete' THEN
+              l_target_entity := l_action->>'entity';
+              l_action_match := l_action->'match';
+              l_resolved_match := dzql.resolve_graph_data(l_action_match, p_record_before, p_record_after, p_user_id);
               PERFORM dzql.execute_graph_delete(l_target_entity, l_resolved_match, p_user_id);
+
+            -- NEW: Validation action
+            WHEN 'validate' THEN
+              l_function_name := l_action->>'function';
+              l_function_params := l_action->'params';
+              l_error_message := COALESCE(l_action->>'error_message', 'Validation failed');
+              l_resolved_data := dzql.resolve_graph_data(l_function_params, p_record_before, p_record_after, p_user_id);
+              PERFORM dzql.execute_graph_validate(l_function_name, l_resolved_data, l_error_message);
+
+            -- NEW: Execute function action
+            WHEN 'execute' THEN
+              l_function_name := l_action->>'function';
+              l_function_params := l_action->'params';
+              l_resolved_data := dzql.resolve_graph_data(l_function_params, p_record_before, p_record_after, p_user_id);
+              l_function_result := dzql.execute_graph_function(l_function_name, l_resolved_data);
+
+            ELSE
+              RAISE WARNING 'Unknown graph rule action type: %', l_action_type;
           END CASE;
 
           -- Log successful execution
           l_execution_log := l_execution_log || jsonb_build_object(
             'rule', l_rule_name,
-            'action_type', l_action_type,
-            'target_entity', l_target_entity,
+            'action', l_action_type,
             'status', 'success'
           );
 
-        EXCEPTION
-          WHEN OTHERS THEN
-            -- Log failed execution but continue with other rules
-            l_execution_log := l_execution_log || jsonb_build_object(
-              'rule', l_rule_name,
-              'action_type', l_action_type,
-              'target_entity', l_target_entity,
-              'status', 'error',
-              'error', SQLERRM
-            );
+        EXCEPTION WHEN OTHERS THEN
+          -- Log error and re-raise for validate actions, otherwise just log
+          l_execution_log := l_execution_log || jsonb_build_object(
+            'rule', l_rule_name,
+            'action', l_action_type,
+            'status', 'error',
+            'error', SQLERRM
+          );
+
+          -- Re-raise exceptions from validate actions to prevent operation
+          IF l_action_type = 'validate' THEN
+            RAISE;
+          END IF;
         END;
       END LOOP;
     END IF;
   END LOOP;
 
   RETURN jsonb_build_object(
-    'status', 'completed',
+    'status', 'success',
     'trigger', l_trigger_key,
-    'execution_log', l_execution_log
+    'executed_actions', l_execution_log
   );
 END $$;