@criterionx/react 0.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomas Maritano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+import * as react from 'react';
+import { Engine, ProfileRegistry, Result, RunOptions, Decision } from '@criterionx/core';
+
+/**
+ * State returned by useDecision hook
+ */
+interface UseDecisionState<TOutput> {
+    /** Current result (null if not yet evaluated) */
+    result: Result<TOutput> | null;
+    /** Whether an evaluation is in progress */
+    isEvaluating: boolean;
+    /** Error from the last evaluation (null if no error) */
+    error: Error | null;
+}
+/**
+ * Actions returned by useDecision hook
+ */
+interface UseDecisionActions<TInput, TProfile> {
+    /** Evaluate the decision with given input and options */
+    evaluate: (input: TInput, options: RunOptions<TProfile>) => void;
+    /** Reset the state (clear result and error) */
+    reset: () => void;
+}
+/**
+ * Complete return type for useDecision hook
+ */
+type UseDecisionReturn<TInput, TOutput, TProfile> = UseDecisionState<TOutput> & UseDecisionActions<TInput, TProfile>;
+/**
+ * Options for useDecision hook
+ */
+interface UseDecisionOptions<TProfile> {
+    /** Custom engine instance (uses default if not provided) */
+    engine?: Engine;
+    /** Profile registry for ID-based profile resolution */
+    registry?: ProfileRegistry<TProfile>;
+}
+/**
+ * Context value for CriterionProvider
+ */
+interface CriterionContextValue {
+    /** Engine instance */
+    engine: Engine;
+    /** Optional profile registry */
+    registry?: ProfileRegistry<any>;
+}
+/**
+ * Props for CriterionProvider
+ */
+interface CriterionProviderProps {
+    /** React children */
+    children: React.ReactNode;
+    /** Custom engine instance (creates default if not provided) */
+    engine?: Engine;
+    /** Profile registry for shared profiles */
+    registry?: ProfileRegistry<any>;
+}
+
+/**
+ * React Context for Criterion
+ */
+declare const CriterionContext: react.Context<CriterionContextValue>;
+/**
+ * Provider component for Criterion context
+ *
+ * Provides an Engine instance and optional ProfileRegistry to all child components.
+ * If no engine is provided, a default singleton instance is used.
+ *
+ * @example
+ * ```tsx
+ * import { CriterionProvider } from "@criterionx/react";
+ * import { createProfileRegistry } from "@criterionx/core";
+ *
+ * const registry = createProfileRegistry();
+ * registry.register("default", { threshold: 100 });
+ *
+ * function App() {
+ *   return (
+ *     <CriterionProvider registry={registry}>
+ *       <MyComponent />
+ *     </CriterionProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function CriterionProvider({ children, engine, registry, }: CriterionProviderProps): React.ReactElement;
+/**
+ * Hook to access the Criterion context
+ *
+ * Returns the engine and optional registry from the nearest CriterionProvider.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { engine, registry } = useCriterion();
+ *   // Use engine directly if needed
+ * }
+ * ```
+ */
+declare function useCriterion(): CriterionContextValue;
+/**
+ * Hook to access the Engine instance
+ *
+ * Shorthand for accessing just the engine from context.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const engine = useEngine();
+ *   const result = engine.run(decision, input, { profile });
+ * }
+ * ```
+ */
+declare function useEngine(): Engine;
+/**
+ * Hook to access the ProfileRegistry
+ *
+ * Returns the registry from context, or undefined if not provided.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const registry = useProfileRegistry();
+ *   if (registry) {
+ *     const profile = registry.get("default");
+ *   }
+ * }
+ * ```
+ */
+declare function useProfileRegistry<TProfile>(): ProfileRegistry<TProfile> | undefined;
+
+/**
+ * React hook for evaluating Criterion decisions
+ *
+ * Provides a convenient way to run decisions in React components with
+ * automatic state management for results, loading state, and errors.
+ *
+ * @param decision - The decision to evaluate
+ * @param options - Optional configuration (custom engine, registry)
+ * @returns State and actions for decision evaluation
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useDecision } from "@criterionx/react";
+ * import { pricingDecision } from "./decisions";
+ *
+ * function PricingComponent() {
+ *   const { result, isEvaluating, error, evaluate } = useDecision(pricingDecision);
+ *
+ *   const handleCalculate = () => {
+ *     evaluate(
+ *       { quantity: 10, customerType: "premium" },
+ *       { profile: { basePrice: 100, premiumDiscount: 0.2 } }
+ *     );
+ *   };
+ *
+ *   if (isEvaluating) return <div>Calculating...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleCalculate}>Calculate Price</button>
+ *       {result && <div>Price: ${result.data?.price}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With profile registry
+ * ```tsx
+ * function PricingComponent() {
+ *   const { evaluate, result } = useDecision(pricingDecision);
+ *
+ *   // Use profile ID from registry
+ *   const handleCalculate = () => {
+ *     evaluate({ quantity: 10 }, { profile: "premium-pricing" });
+ *   };
+ *
+ *   // ...
+ * }
+ * ```
+ */
+declare function useDecision<TInput, TOutput, TProfile>(decision: Decision<TInput, TOutput, TProfile>, options?: UseDecisionOptions<TProfile>): UseDecisionReturn<TInput, TOutput, TProfile>;
+
+export { CriterionContext, type CriterionContextValue, CriterionProvider, type CriterionProviderProps, type UseDecisionActions, type UseDecisionOptions, type UseDecisionReturn, type UseDecisionState, useCriterion, useDecision, useEngine, useProfileRegistry };

package/dist/index.js

@@ -0,0 +1,80 @@
+// src/context.tsx
+import { createContext, useContext, useMemo } from "react";
+import { Engine } from "@criterionx/core";
+import { jsx } from "react/jsx-runtime";
+var defaultEngine = new Engine();
+var CriterionContext = createContext({
+  engine: defaultEngine
+});
+function CriterionProvider({
+  children,
+  engine,
+  registry
+}) {
+  const value = useMemo(
+    () => ({
+      engine: engine ?? defaultEngine,
+      registry
+    }),
+    [engine, registry]
+  );
+  return /* @__PURE__ */ jsx(CriterionContext.Provider, { value, children });
+}
+function useCriterion() {
+  return useContext(CriterionContext);
+}
+function useEngine() {
+  const { engine } = useContext(CriterionContext);
+  return engine;
+}
+function useProfileRegistry() {
+  const { registry } = useContext(CriterionContext);
+  return registry;
+}
+
+// src/useDecision.ts
+import { useCallback, useState } from "react";
+function useDecision(decision, options) {
+  const context = useCriterion();
+  const engine = options?.engine ?? context.engine;
+  const registry = options?.registry ?? context.registry;
+  const [result, setResult] = useState(null);
+  const [isEvaluating, setIsEvaluating] = useState(false);
+  const [error, setError] = useState(null);
+  const evaluate = useCallback(
+    (input, runOptions) => {
+      setIsEvaluating(true);
+      setError(null);
+      try {
+        const evalResult = engine.run(decision, input, runOptions, registry);
+        setResult(evalResult);
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        setResult(null);
+      } finally {
+        setIsEvaluating(false);
+      }
+    },
+    [decision, engine, registry]
+  );
+  const reset = useCallback(() => {
+    setResult(null);
+    setError(null);
+    setIsEvaluating(false);
+  }, []);
+  return {
+    result,
+    isEvaluating,
+    error,
+    evaluate,
+    reset
+  };
+}
+export {
+  CriterionContext,
+  CriterionProvider,
+  useCriterion,
+  useDecision,
+  useEngine,
+  useProfileRegistry
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@criterionx/react",
+  "version": "0.3.5",
+  "description": "React hooks for Criterion decision engine",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "criterion",
+    "react",
+    "hooks",
+    "decision-engine",
+    "rules-engine",
+    "business-rules"
+  ],
+  "author": {
+    "name": "Tomas Maritano",
+    "url": "https://github.com/tomymaritano"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomymaritano/criterionx.git",
+    "directory": "packages/react"
+  },
+  "dependencies": {
+    "@criterionx/core": "0.3.5"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "zod": "^3.24.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --external react",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}