@plures/praxis 1.0.2 → 1.1.0

package/src/core/reactive-engine.ts

@@ -0,0 +1,67 @@
+/**
+ * Praxis Reactive Logic Engine
+ * 
+ * A Svelte 5 native implementation of the Praxis Logic Engine.
+ * Uses Runes ($state, $derived, $effect) for fine-grained reactivity.
+ */
+
+console.log("Reactive Engine Loaded");
+
+export interface ReactiveEngineOptions<TContext> {
+    initialContext: TContext;
+    initialFacts?: any[];
+    initialMeta?: Record<string, unknown>;
+}
+
+export class ReactiveLogicEngine<TContext extends object> {
+    // The single source of truth, reactive by default
+    // We use $state.raw for things that shouldn't be deeply reactive if needed,
+    // but for context we usually want deep reactivity.
+    state = $state<{
+        context: TContext;
+        facts: any[];
+        meta: Record<string, unknown>;
+    }>({
+        context: {} as TContext,
+        facts: [],
+        meta: {}
+    });
+
+    constructor(options: ReactiveEngineOptions<TContext>) {
+        this.state.context = options.initialContext;
+        this.state.facts = options.initialFacts ?? [];
+        this.state.meta = options.initialMeta ?? {};
+    }
+
+    /**
+     * Access the reactive context directly.
+     * Consumers can use this in $derived() or $effect().
+     */
+    get context() {
+        return this.state.context;
+    }
+
+    /**
+     * Access the reactive facts list.
+     */
+    get facts() {
+        return this.state.facts;
+    }
+
+    /**
+     * Apply a mutation to the state.
+     * This is the "Action" or "Rule" equivalent.
+     * 
+     * @param mutator A function that receives the state and modifies it.
+     */
+    apply(mutator: (state: { context: TContext; facts: any[]; meta: Record<string, unknown> }) => void) {
+        mutator(this.state);
+    }
+
+    /**
+     * Access the reactive meta.
+     */
+    get meta() {
+        return this.state.meta;
+    }
+}

package/src/core/rules.ts

@@ -1,12 +1,12 @@
 /**
  * Rules and Constraints System
- * 
+ *
  * This module defines the types and registry for rules and constraints.
  * Rules and constraints are identified by stable IDs and can be described as data,
  * making them portable across languages and suitable for DSL-based definitions.
  */
 
-import type { PraxisEvent, PraxisFact, PraxisState } from "./protocol.js";
+import type { PraxisEvent, PraxisFact, PraxisState } from './protocol.js';
 
 /**
  * Unique identifier for a rule
@@ -21,7 +21,7 @@ export type ConstraintId = string;
 /**
  * A rule function derives new facts or transitions from context + input facts/events.
  * Rules must be pure - no side effects.
- * 
+ *
  * @param state Current Praxis state
  * @param events Events to process
  * @returns Array of new facts to add to the state
@@ -34,7 +34,7 @@ export type RuleFn<TContext = unknown> = (
 /**
  * A constraint function checks that an invariant holds.
  * Constraints must be pure - no side effects.
- * 
+ *
  * @param state Current Praxis state
  * @returns true if constraint is satisfied, false or error message if violated
  */

package/src/core/schema/loader.common.ts

@@ -0,0 +1,150 @@
+/**
+ * Praxis Schema Loader (Common/Browser Compatible)
+ *
+ * Core schema loading and validation functions that don't depend on Node.js APIs.
+ */
+
+import { load as yamlLoad } from 'js-yaml';
+import type { PraxisSchema, ValidationResult } from './types.js';
+import { validateSchema } from './types.js';
+
+/**
+ * Loader options
+ */
+export interface LoaderOptions {
+  /** Validate schema after loading */
+  validate?: boolean;
+  /** Base directory for resolving relative paths */
+  baseDir?: string;
+}
+
+/**
+ * Loader result
+ */
+export interface LoaderResult {
+  /** Loaded schema */
+  schema?: PraxisSchema;
+  /** Validation result */
+  validation?: ValidationResult;
+  /** Load errors */
+  errors: string[];
+}
+
+/**
+ * Create a new empty schema
+ */
+export function createSchema(name: string): PraxisSchema {
+  return {
+    version: '1.0.0',
+    name,
+    description: `Schema for ${name}`,
+    models: [],
+    components: [],
+    logic: [],
+  };
+}
+
+/**
+ * Load schema from JSON string
+ */
+export function loadSchemaFromJson(json: string, options: LoaderOptions = {}): LoaderResult {
+  const errors: string[] = [];
+
+  try {
+    const schema = JSON.parse(json) as PraxisSchema;
+
+    // Validate if requested
+    let validation: ValidationResult | undefined;
+    if (options.validate !== false) {
+      validation = validateSchema(schema);
+      if (!validation.valid) {
+        errors.push('Schema validation failed:');
+        validation.errors.forEach((error) => {
+          errors.push(`  ${error.path}: ${error.message}`);
+        });
+      }
+    }
+
+    return {
+      schema,
+      validation,
+      errors,
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      errors.push(`Failed to parse JSON: ${error.message}`);
+    } else {
+      errors.push('Failed to parse JSON: Unknown error');
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Load schema from YAML string
+ */
+export function loadSchemaFromYaml(yaml: string, options: LoaderOptions = {}): LoaderResult {
+  const errors: string[] = [];
+
+  try {
+    const schema = yamlLoad(yaml) as PraxisSchema;
+
+    // Validate if requested
+    let validation: ValidationResult | undefined;
+    if (options.validate !== false) {
+      validation = validateSchema(schema);
+      if (!validation.valid) {
+        errors.push('Schema validation failed:');
+        validation.errors.forEach((error) => {
+          errors.push(`  ${error.path}: ${error.message}`);
+        });
+      }
+    }
+
+    return {
+      schema,
+      validation,
+      errors,
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      errors.push(`Failed to parse YAML: ${error.message}`);
+    } else {
+      errors.push('Failed to parse YAML: Unknown error');
+    }
+    return { errors };
+  }
+}
+
+/**
+ * Validate that a loaded schema has required fields for generation
+ */
+export function validateForGeneration(schema: PraxisSchema): ValidationResult {
+  const errors: string[] = [];
+
+  // Check for entities/models
+  if (!schema.models || schema.models.length === 0) {
+    errors.push('Schema must define at least one model for generation');
+  }
+
+  // Check that models have valid fields
+  schema.models?.forEach((model, index) => {
+    if (!model.fields || model.fields.length === 0) {
+      errors.push(`Model "${model.name}" at index ${index} must have at least one field`);
+    }
+
+    model.fields?.forEach((field, fieldIndex) => {
+      if (!field.name) {
+        errors.push(`Field at index ${fieldIndex} in model "${model.name}" must have a name`);
+      }
+      if (!field.type) {
+        errors.push(`Field "${field.name}" in model "${model.name}" must have a type`);
+      }
+    });
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors: errors.map((message) => ({ path: 'schema', message })),
+  };
+}

package/src/core/schema/loader.ts

@@ -1,36 +1,22 @@
 /**
  * Praxis Schema Loader
- * 
+ *
  * Loads and validates Praxis schema files.
  */
 
 import { readFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
-import { load as yamlLoad } from 'js-yaml';
 import type { PraxisSchema, ValidationResult } from './types.js';
 import { validateSchema } from './types.js';
+import {
+  loadSchemaFromJson,
+  loadSchemaFromYaml,
+  LoaderOptions,
+  LoaderResult,
+} from './loader.common.js';
 
-/**
- * Loader options
- */
-export interface LoaderOptions {
-  /** Validate schema after loading */
-  validate?: boolean;
-  /** Base directory for resolving relative paths */
-  baseDir?: string;
-}
-
-/**
- * Loader result
- */
-export interface LoaderResult {
-  /** Loaded schema */
-  schema?: PraxisSchema;
-  /** Validation result */
-  validation?: ValidationResult;
-  /** Load errors */
-  errors: string[];
-}
+// Re-export common functions
+export * from './loader.common.js';
 
 /**
  * Load a Praxis schema from a file
@@ -40,20 +26,20 @@ export async function loadSchema(
   options: LoaderOptions = {}
 ): Promise<LoaderResult> {
   const errors: string[] = [];
-  
+
   try {
     // Only .js files are supported. TypeScript schema files must be compiled to .js first.
     // Use a compiled JavaScript file for your schema.
     // Dynamic import is used, which works with .js files only.
-    
+
     // Convert to absolute URL for ES module import
     let fileUrl = pathToFileURL(filePath).href;
-    
+
     // Attempt to import .ts or .js files directly. If import fails, error will be caught below.
-    
+
     // Dynamic import of the schema file
     const module = await import(fileUrl);
-    
+
     // Look for common schema export names
     let schema: PraxisSchema | undefined;
     if (module.default) {
@@ -67,23 +53,20 @@ export async function loadSchema(
       const exports = Object.values(module);
       const possibleSchema = exports.find(
         (exp): exp is PraxisSchema =>
-          typeof exp === 'object' &&
-          exp !== null &&
-          'version' in exp &&
-          'name' in exp
+          typeof exp === 'object' && exp !== null && 'version' in exp && 'name' in exp
       );
       if (possibleSchema) {
         schema = possibleSchema;
       }
     }
-    
+
     if (!schema) {
       errors.push(
         'Schema file must export a PraxisSchema object (as default, schema, or appSchema)'
       );
       return { errors };
     }
-    
+
     // Validate if requested
     let validation: ValidationResult | undefined;
     if (options.validate !== false) {
@@ -95,7 +78,7 @@ export async function loadSchema(
         });
       }
     }
-    
+
     return {
       schema,
       validation,
@@ -111,83 +94,7 @@ export async function loadSchema(
   }
 }
 
-/**
- * Load schema from JSON string
- */
-export function loadSchemaFromJson(
-  json: string,
-  options: LoaderOptions = {}
-): LoaderResult {
-  const errors: string[] = [];
-  
-  try {
-    const schema = JSON.parse(json) as PraxisSchema;
-    
-    // Validate if requested
-    let validation: ValidationResult | undefined;
-    if (options.validate !== false) {
-      validation = validateSchema(schema);
-      if (!validation.valid) {
-        errors.push('Schema validation failed:');
-        validation.errors.forEach((error) => {
-          errors.push(`  ${error.path}: ${error.message}`);
-        });
-      }
-    }
-    
-    return {
-      schema,
-      validation,
-      errors,
-    };
-  } catch (error) {
-    if (error instanceof Error) {
-      errors.push(`Failed to parse JSON: ${error.message}`);
-    } else {
-      errors.push('Failed to parse JSON: Unknown error');
-    }
-    return { errors };
-  }
-}
 
-/**
- * Load schema from YAML string
- */
-export function loadSchemaFromYaml(
-  yaml: string,
-  options: LoaderOptions = {}
-): LoaderResult {
-  const errors: string[] = [];
-  
-  try {
-    const schema = yamlLoad(yaml) as PraxisSchema;
-    
-    // Validate if requested
-    let validation: ValidationResult | undefined;
-    if (options.validate !== false) {
-      validation = validateSchema(schema);
-      if (!validation.valid) {
-        errors.push('Schema validation failed:');
-        validation.errors.forEach((error) => {
-          errors.push(`  ${error.path}: ${error.message}`);
-        });
-      }
-    }
-    
-    return {
-      schema,
-      validation,
-      errors,
-    };
-  } catch (error) {
-    if (error instanceof Error) {
-      errors.push(`Failed to parse YAML: ${error.message}`);
-    } else {
-      errors.push('Failed to parse YAML: Unknown error');
-    }
-    return { errors };
-  }
-}
 
 /**
  * Load schema from file (supports .ts, .json, and .yaml/.yml)
@@ -207,41 +114,4 @@ export async function loadSchemaFromFile(
   }
 }
 
-/**
- * Validate that a loaded schema has required fields for generation
- */
-export function validateForGeneration(schema: PraxisSchema): ValidationResult {
-  const errors: string[] = [];
-  
-  // Check for entities/models
-  if (!schema.models || schema.models.length === 0) {
-    errors.push('Schema must define at least one model for generation');
-  }
-  
-  // Check that models have valid fields
-  schema.models?.forEach((model, index) => {
-    if (!model.fields || model.fields.length === 0) {
-      errors.push(
-        `Model "${model.name}" at index ${index} must have at least one field`
-      );
-    }
-    
-    model.fields?.forEach((field, fieldIndex) => {
-      if (!field.name) {
-        errors.push(
-          `Field at index ${fieldIndex} in model "${model.name}" must have a name`
-        );
-      }
-      if (!field.type) {
-        errors.push(
-          `Field "${field.name}" in model "${model.name}" must have a type`
-        );
-      }
-    });
-  });
-  
-  return {
-    valid: errors.length === 0,
-    errors: errors.map((message) => ({ path: 'schema', message })),
-  };
-}
+

package/src/core/schema/normalize.ts

@@ -1,6 +1,6 @@
 /**
  * Praxis Schema Normalizer
- * 
+ *
  * Expands and normalizes schema definitions for code generation.
  */
 
@@ -74,19 +74,13 @@ export function normalizeSchema(
   options: NormalizationOptions = {}
 ): NormalizedSchema {
   const schemaPrefix = options.schemaPrefix || schema.name;
-  
+
   // Normalize models
-  const normalizedModels = normalizeModels(
-    schema.models || [],
-    schemaPrefix,
-    options
-  );
-  
+  const normalizedModels = normalizeModels(schema.models || [], schemaPrefix, options);
+
   // Create model lookup map
-  const modelMap = new Map(
-    normalizedModels.map((model) => [model.name, model])
-  );
-  
+  const modelMap = new Map(normalizedModels.map((model) => [model.name, model]));
+
   // Normalize components
   const normalizedComponents = normalizeComponents(
     schema.components || [],
@@ -94,14 +88,10 @@ export function normalizeSchema(
     modelMap,
     options
   );
-  
+
   // Normalize logic
-  const normalizedLogic = normalizeLogic(
-    schema.logic || [],
-    schemaPrefix,
-    options
-  );
-  
+  const normalizedLogic = normalizeLogic(schema.logic || [], schemaPrefix, options);
+
   return {
     ...schema,
     models: normalizedModels,
@@ -121,11 +111,11 @@ function normalizeModels(
   return models.map((model) => {
     const fullName = `${schemaPrefix}.${model.name}`;
     const dependencies = extractModelDependencies(model);
-    
+
     // For now, allFields is the same as fields
     // In the future, this could include inherited fields
     const allFields = [...model.fields];
-    
+
     return {
       ...model,
       fullName,
@@ -140,20 +130,20 @@ function normalizeModels(
  */
 function extractModelDependencies(model: ModelDefinition): string[] {
   const dependencies = new Set<string>();
-  
+
   for (const field of model.fields) {
     if (typeof field.type === 'object' && 'reference' in field.type) {
       dependencies.add(field.type.reference);
     }
   }
-  
+
   // Add relationship dependencies
   if (model.relationships) {
     for (const rel of model.relationships) {
       dependencies.add(rel.target);
     }
   }
-  
+
   return Array.from(dependencies);
 }
 
@@ -168,10 +158,8 @@ function normalizeComponents(
 ): NormalizedComponent[] {
   return components.map((component) => {
     const fullName = `${schemaPrefix}.${component.name}`;
-    const resolvedModel = component.model
-      ? modelMap.get(component.model)
-      : undefined;
-    
+    const resolvedModel = component.model ? modelMap.get(component.model) : undefined;
+
     return {
       ...component,
       fullName,
@@ -190,7 +178,7 @@ function normalizeLogic(
 ): NormalizedLogic[] {
   return logic.map((logicDef) => {
     const fullId = `${schemaPrefix}.${logicDef.id}`;
-    
+
     return {
       ...logicDef,
       fullId,
@@ -201,30 +189,27 @@ function normalizeLogic(
 /**
  * Expand field type to fully qualified type string
  */
-export function expandFieldType(
-  fieldType: any,
-  schemaPrefix: string = ''
-): string {
+export function expandFieldType(fieldType: any, schemaPrefix: string = ''): string {
   if (typeof fieldType === 'string') {
     return fieldType;
   }
-  
+
   if (typeof fieldType === 'object') {
     if ('array' in fieldType) {
       const innerType = expandFieldType(fieldType.array, schemaPrefix);
       return `${innerType}[]`;
     }
-    
+
     if ('object' in fieldType) {
       return 'object';
     }
-    
+
     if ('reference' in fieldType) {
       const refName = fieldType.reference;
       return schemaPrefix ? `${schemaPrefix}.${refName}` : refName;
     }
   }
-  
+
   return 'unknown';
 }
 
@@ -250,13 +235,13 @@ export function fieldTypeToTypeScript(fieldType: any): string {
         return 'unknown';
     }
   }
-  
+
   if (typeof fieldType === 'object') {
     if ('array' in fieldType) {
       const innerType = fieldTypeToTypeScript(fieldType.array);
       return `${innerType}[]`;
     }
-    
+
     if ('object' in fieldType) {
       const fields = fieldType.object;
       const fieldTypes = Object.entries(fields)
@@ -267,30 +252,28 @@ export function fieldTypeToTypeScript(fieldType: any): string {
         .join('; ');
       return `{ ${fieldTypes} }`;
     }
-    
+
     if ('reference' in fieldType) {
       return fieldType.reference;
     }
   }
-  
+
   return 'unknown';
 }
 
 /**
  * Sort models by dependency order (models with no dependencies first)
  */
-export function sortModelsByDependencies(
-  models: NormalizedModel[]
-): NormalizedModel[] {
+export function sortModelsByDependencies(models: NormalizedModel[]): NormalizedModel[] {
   const sorted: NormalizedModel[] = [];
   const visited = new Set<string>();
   const visiting = new Set<string>();
-  
+
   function visit(model: NormalizedModel) {
     if (visited.has(model.name)) {
       return;
     }
-    
+
     if (visiting.has(model.name)) {
       // Circular dependency detected, just add it
       visiting.delete(model.name);
@@ -298,9 +281,9 @@ export function sortModelsByDependencies(
       visited.add(model.name);
       return;
     }
-    
+
     visiting.add(model.name);
-    
+
     // Visit dependencies first
     for (const depName of model.dependencies) {
       const dep = models.find((m) => m.name === depName);
@@ -308,15 +291,15 @@ export function sortModelsByDependencies(
         visit(dep);
       }
     }
-    
+
     visiting.delete(model.name);
     visited.add(model.name);
     sorted.push(model);
   }
-  
+
   for (const model of models) {
     visit(model);
   }
-  
+
   return sorted;
 }