@plures/praxis 1.0.2 → 1.1.0

package/dist/browser/engine-BjdqxeXG.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Core Praxis Protocol
+ *
+ * Language-neutral, JSON-friendly protocol that forms the foundation of Praxis.
+ * This protocol is designed to be stable and portable across languages (TypeScript, C#, PowerShell, etc.)
+ *
+ * The protocol defines the conceptual core of the engine:
+ * - Pure, deterministic, data in → data out
+ * - No side effects, no global state
+ * - All higher-level TypeScript APIs are built on top of this protocol
+ *
+ * ## Protocol Versioning
+ *
+ * The Praxis protocol follows semantic versioning (MAJOR.MINOR.PATCH):
+ * - MAJOR: Breaking changes to core protocol types or semantics
+ * - MINOR: Backward-compatible additions to protocol (new optional fields)
+ * - PATCH: Clarifications, documentation updates, no functional changes
+ *
+ * Current version: 1.0.0
+ *
+ * ### Stability Guarantees
+ *
+ * 1. **Core Types Stability**: The following types are considered stable and will not
+ *    change in backward-incompatible ways within the same major version:
+ *    - PraxisFact (tag, payload structure)
+ *    - PraxisEvent (tag, payload structure)
+ *    - PraxisState (context, facts, meta structure)
+ *    - PraxisStepFn signature
+ *
+ * 2. **JSON Compatibility**: All protocol types will remain JSON-serializable.
+ *    No non-JSON-safe types (functions, symbols, etc.) will be added to the protocol.
+ *
+ * 3. **Cross-Language Compatibility**: Protocol changes will be coordinated across
+ *    all official language implementations (TypeScript, C#, PowerShell) to ensure
+ *    interoperability.
+ *
+ * 4. **Migration Path**: Major version changes will be accompanied by:
+ *    - Migration guide
+ *    - Deprecation warnings in previous version
+ *    - Compatibility shims where possible
+ */
+/**
+ * Protocol version following semantic versioning
+ */
+declare const PRAXIS_PROTOCOL_VERSION: "1.0.0";
+/**
+ * A fact is a typed proposition about the domain.
+ * Examples: UserLoggedIn, CartItem, NetworkOnline
+ */
+interface PraxisFact {
+    /** Tag identifying the fact type */
+    tag: string;
+    /** Payload containing the fact data */
+    payload: unknown;
+}
+/**
+ * An event is a temporally ordered fact meant to drive change.
+ * Examples: LOGIN, LOGOUT, ADD_TO_CART
+ */
+interface PraxisEvent {
+    /** Tag identifying the event type */
+    tag: string;
+    /** Payload containing the event data */
+    payload: unknown;
+}
+/**
+ * The state of the Praxis engine at a point in time.
+ */
+interface PraxisState {
+    /** Application context (domain-specific data) */
+    context: unknown;
+    /** Current facts about the domain */
+    facts: PraxisFact[];
+    /** Optional metadata (timestamps, version, etc.) */
+    meta?: Record<string, unknown>;
+    /** Protocol version (for cross-language compatibility) */
+    protocolVersion?: string;
+}
+/**
+ * Diagnostic information about constraint violations or rule errors.
+ */
+interface PraxisDiagnostics {
+    /** Kind of diagnostic */
+    kind: 'constraint-violation' | 'rule-error';
+    /** Human-readable message */
+    message: string;
+    /** Additional diagnostic data */
+    data?: unknown;
+}
+/**
+ * Configuration for a step execution.
+ * Specifies which rules and constraints to apply.
+ */
+interface PraxisStepConfig {
+    /** IDs of rules to apply during this step */
+    ruleIds: string[];
+    /** IDs of constraints to check during this step */
+    constraintIds: string[];
+}
+/**
+ * Result of a step execution.
+ */
+interface PraxisStepResult {
+    /** New state after applying rules and checking constraints */
+    state: PraxisState;
+    /** Diagnostics from rule execution and constraint checking */
+    diagnostics: PraxisDiagnostics[];
+}
+/**
+ * The core step function of the Praxis engine.
+ *
+ * This is the conceptual heart of the engine:
+ * - Takes current state, events, and configuration
+ * - Applies rules and checks constraints
+ * - Returns new state and diagnostics
+ *
+ * Pure, deterministic, data in → data out.
+ * No side effects, no global state.
+ */
+type PraxisStepFn = (state: PraxisState, events: PraxisEvent[], config: PraxisStepConfig) => PraxisStepResult;
+
+/**
+ * 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.
+ */
+
+/**
+ * Unique identifier for a rule
+ */
+type RuleId = string;
+/**
+ * Unique identifier for a constraint
+ */
+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
+ */
+type RuleFn<TContext = unknown> = (state: PraxisState & {
+    context: TContext;
+}, events: PraxisEvent[]) => PraxisFact[];
+/**
+ * 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
+ */
+type ConstraintFn<TContext = unknown> = (state: PraxisState & {
+    context: TContext;
+}) => boolean | string;
+/**
+ * Descriptor for a rule, including its ID, description, and implementation.
+ */
+interface RuleDescriptor<TContext = unknown> {
+    /** Unique identifier for the rule */
+    id: RuleId;
+    /** Human-readable description */
+    description: string;
+    /** Implementation function */
+    impl: RuleFn<TContext>;
+    /** Optional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Descriptor for a constraint, including its ID, description, and implementation.
+ */
+interface ConstraintDescriptor<TContext = unknown> {
+    /** Unique identifier for the constraint */
+    id: ConstraintId;
+    /** Human-readable description */
+    description: string;
+    /** Implementation function */
+    impl: ConstraintFn<TContext>;
+    /** Optional metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * A Praxis module bundles rules and constraints.
+ * Modules can be composed and registered with the engine.
+ */
+interface PraxisModule<TContext = unknown> {
+    /** Rules in this module */
+    rules: RuleDescriptor<TContext>[];
+    /** Constraints in this module */
+    constraints: ConstraintDescriptor<TContext>[];
+    /** Optional module metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Registry for rules and constraints.
+ * Maps IDs to their descriptors.
+ */
+declare class PraxisRegistry<TContext = unknown> {
+    private rules;
+    private constraints;
+    /**
+     * Register a rule
+     */
+    registerRule(descriptor: RuleDescriptor<TContext>): void;
+    /**
+     * Register a constraint
+     */
+    registerConstraint(descriptor: ConstraintDescriptor<TContext>): void;
+    /**
+     * Register a module (all its rules and constraints)
+     */
+    registerModule(module: PraxisModule<TContext>): void;
+    /**
+     * Get a rule by ID
+     */
+    getRule(id: RuleId): RuleDescriptor<TContext> | undefined;
+    /**
+     * Get a constraint by ID
+     */
+    getConstraint(id: ConstraintId): ConstraintDescriptor<TContext> | undefined;
+    /**
+     * Get all registered rule IDs
+     */
+    getRuleIds(): RuleId[];
+    /**
+     * Get all registered constraint IDs
+     */
+    getConstraintIds(): ConstraintId[];
+    /**
+     * Get all rules
+     */
+    getAllRules(): RuleDescriptor<TContext>[];
+    /**
+     * Get all constraints
+     */
+    getAllConstraints(): ConstraintDescriptor<TContext>[];
+}
+
+/**
+ * Praxis Logic Engine
+ *
+ * The logic engine manages state, processes events through rules,
+ * checks constraints, and provides a strongly-typed API for application logic.
+ */
+
+/**
+ * Options for creating a Praxis engine
+ */
+interface PraxisEngineOptions<TContext = unknown> {
+    /** Initial context */
+    initialContext: TContext;
+    /** Registry of rules and constraints */
+    registry: PraxisRegistry<TContext>;
+    /** Initial facts (optional) */
+    initialFacts?: PraxisFact[];
+    /** Initial metadata (optional) */
+    initialMeta?: Record<string, unknown>;
+}
+/**
+ * The Praxis Logic Engine
+ *
+ * Manages application logic through facts, events, rules, and constraints.
+ * The engine is strongly typed and functional - all state updates are immutable.
+ */
+declare class LogicEngine<TContext = unknown> {
+    private state;
+    private readonly registry;
+    constructor(options: PraxisEngineOptions<TContext>);
+    /**
+     * Get the current state (immutable copy)
+     */
+    getState(): Readonly<PraxisState & {
+        context: TContext;
+    }>;
+    /**
+     * Get the current context
+     */
+    getContext(): TContext;
+    /**
+     * Get current facts
+     */
+    getFacts(): PraxisFact[];
+    /**
+     * Process events through the engine.
+     * Applies all registered rules and checks all registered constraints.
+     *
+     * @param events Events to process
+     * @returns Result with new state and diagnostics
+     */
+    step(events: PraxisEvent[]): PraxisStepResult;
+    /**
+     * Process events with specific rule and constraint configuration.
+     *
+     * @param events Events to process
+     * @param config Step configuration
+     * @returns Result with new state and diagnostics
+     */
+    stepWithConfig(events: PraxisEvent[], config: PraxisStepConfig): PraxisStepResult;
+    /**
+     * Update the context directly (for exceptional cases).
+     * Generally, context should be updated through rules.
+     *
+     * @param updater Function that produces new context from old context
+     */
+    updateContext(updater: (context: TContext) => TContext): void;
+    /**
+     * Add facts directly (for exceptional cases).
+     * Generally, facts should be added through rules.
+     *
+     * @param facts Facts to add
+     */
+    addFacts(facts: PraxisFact[]): void;
+    /**
+     * Clear all facts
+     */
+    clearFacts(): void;
+    /**
+     * Reset the engine to initial state
+     */
+    reset(options: PraxisEngineOptions<TContext>): void;
+}
+/**
+ * Create a new Praxis logic engine.
+ *
+ * @param options Engine options
+ * @returns New LogicEngine instance
+ */
+declare function createPraxisEngine<TContext = unknown>(options: PraxisEngineOptions<TContext>): LogicEngine<TContext>;
+
+export { type ConstraintDescriptor as C, LogicEngine as L, type PraxisState as P, type RuleDescriptor as R, type PraxisEvent as a, PraxisRegistry as b, type PraxisFact as c, type RuleFn as d, type ConstraintFn as e, type PraxisModule as f, type PraxisDiagnostics as g, type PraxisStepConfig as h, type PraxisStepResult as i, type PraxisStepFn as j, PRAXIS_PROTOCOL_VERSION as k, type RuleId as l, type ConstraintId as m, type PraxisEngineOptions as n, createPraxisEngine as o };