@plures/praxis 1.0.2 → 1.1.0

package/dist/node/engine-1iqLe6_P.d.ts

@@ -0,0 +1,214 @@
+import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.js';
+
+/**
+ * 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, PraxisRegistry as P, type RuleDescriptor as R, type RuleFn as a, type ConstraintFn as b, type PraxisModule as c, type RuleId as d, type ConstraintId as e, type PraxisEngineOptions as f, createPraxisEngine as g };

package/dist/node/engine-CVJobhHm.d.cts

@@ -0,0 +1,214 @@
+import { P as PraxisState, a as PraxisEvent, b as PraxisFact, c as PraxisStepResult, d as PraxisStepConfig } from './protocol-Qek7ebBl.cjs';
+
+/**
+ * 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, PraxisRegistry as P, type RuleDescriptor as R, type RuleFn as a, type ConstraintFn as b, type PraxisModule as c, type RuleId as d, type ConstraintId as e, type PraxisEngineOptions as f, createPraxisEngine as g };