@startsimpli/funnels 0.1.3 → 0.1.5

package/src/core/evaluator.ts

@@ -0,0 +1,261 @@
+/**
+ * @startsimpli/funnels - Rule Evaluator
+ *
+ * BRUTALLY GENERIC rule evaluation engine.
+ *
+ * Evaluates FilterRule against ANY entity type by:
+ * 1. Resolving field value from entity
+ * 2. Applying operator comparison
+ * 3. Handling negate flag
+ * 4. Returning boolean result
+ */
+
+import type { FilterRule, RuleResult } from '../types';
+import { resolveField } from './field-resolver';
+import { applyOperator } from './operators';
+
+/**
+ * Evaluate a single filter rule against an entity
+ *
+ * @param entity - The entity to evaluate
+ * @param rule - The filter rule to apply
+ * @returns Whether the rule matches
+ *
+ * @example
+ * ```typescript
+ * const investor = { name: 'John', firm: { stage: 'Series A' } };
+ *
+ * evaluateRule(investor, {
+ *   field_path: 'firm.stage',
+ *   operator: 'eq',
+ *   value: 'Series A'
+ * }); // true
+ *
+ * evaluateRule(investor, {
+ *   field_path: 'firm.stage',
+ *   operator: 'eq',
+ *   value: 'Seed',
+ *   negate: true
+ * }); // true (negated: stage !== 'Seed')
+ * ```
+ */
+export function evaluateRule<T>(entity: T, rule: FilterRule): boolean {
+  // Resolve field value from entity
+  const actualValue = resolveField(entity, rule.field_path);
+
+  // Apply operator
+  const result = applyOperator(rule.operator, actualValue, rule.value);
+
+  // Handle negate flag
+  return rule.negate ? !result : result;
+}
+
+/**
+ * Evaluate a rule and return detailed result with diagnostics
+ *
+ * @param entity - The entity to evaluate
+ * @param rule - The filter rule to apply
+ * @returns Detailed rule result with actual value and match status
+ *
+ * @example
+ * ```typescript
+ * const result = evaluateRuleWithResult(investor, {
+ *   field_path: 'firm.stage',
+ *   operator: 'eq',
+ *   value: 'Series A'
+ * });
+ * // {
+ * //   field_path: 'firm.stage',
+ * //   operator: 'eq',
+ * //   value: 'Series A',
+ * //   actual_value: 'Series A',
+ * //   matched: true
+ * // }
+ * ```
+ */
+export function evaluateRuleWithResult<T>(
+  entity: T,
+  rule: FilterRule
+): RuleResult {
+  try {
+    // Resolve field value
+    const actualValue = resolveField(entity, rule.field_path);
+
+    // Apply operator
+    const operatorResult = applyOperator(rule.operator, actualValue, rule.value);
+
+    // Handle negate flag
+    const matched = rule.negate ? !operatorResult : operatorResult;
+
+    return {
+      field_path: rule.field_path,
+      operator: rule.operator,
+      value: rule.value,
+      actual_value: actualValue,
+      matched,
+    };
+  } catch (error) {
+    // Handle evaluation errors gracefully
+    return {
+      field_path: rule.field_path,
+      operator: rule.operator,
+      value: rule.value,
+      actual_value: undefined,
+      matched: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Evaluate multiple rules with AND logic
+ *
+ * @param entity - The entity to evaluate
+ * @param rules - Array of filter rules
+ * @returns Whether ALL rules match
+ *
+ * @example
+ * ```typescript
+ * const investor = { name: 'John', firm: { stage: 'Series A', aum: 100000000 } };
+ *
+ * evaluateRulesAND(investor, [
+ *   { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+ *   { field_path: 'firm.aum', operator: 'gte', value: 50000000 }
+ * ]); // true (both rules match)
+ * ```
+ */
+export function evaluateRulesAND<T>(entity: T, rules: FilterRule[]): boolean {
+  if (!rules || rules.length === 0) return true; // Empty rules = match
+
+  return rules.every(rule => evaluateRule(entity, rule));
+}
+
+/**
+ * Evaluate multiple rules with OR logic
+ *
+ * @param entity - The entity to evaluate
+ * @param rules - Array of filter rules
+ * @returns Whether AT LEAST ONE rule matches
+ *
+ * @example
+ * ```typescript
+ * const investor = { name: 'John', firm: { stage: 'Seed' } };
+ *
+ * evaluateRulesOR(investor, [
+ *   { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+ *   { field_path: 'firm.stage', operator: 'eq', value: 'Seed' }
+ * ]); // true (second rule matches)
+ * ```
+ */
+export function evaluateRulesOR<T>(entity: T, rules: FilterRule[]): boolean {
+  if (!rules || rules.length === 0) return true; // Empty rules = match
+
+  return rules.some(rule => evaluateRule(entity, rule));
+}
+
+/**
+ * Evaluate multiple rules with specified logic (AND/OR)
+ *
+ * @param entity - The entity to evaluate
+ * @param rules - Array of filter rules
+ * @param logic - Combination logic ('AND' or 'OR')
+ * @returns Whether rules match based on logic
+ *
+ * @example
+ * ```typescript
+ * evaluateRules(investor, rules, 'AND'); // All must match
+ * evaluateRules(investor, rules, 'OR');  // At least one must match
+ * ```
+ */
+export function evaluateRules<T>(
+  entity: T,
+  rules: FilterRule[],
+  logic: 'AND' | 'OR' = 'AND'
+): boolean {
+  return logic === 'AND'
+    ? evaluateRulesAND(entity, rules)
+    : evaluateRulesOR(entity, rules);
+}
+
+/**
+ * Evaluate rules and return detailed results for each rule
+ *
+ * @param entity - The entity to evaluate
+ * @param rules - Array of filter rules
+ * @param logic - Combination logic ('AND' or 'OR')
+ * @returns Object with overall match status and per-rule results
+ *
+ * @example
+ * ```typescript
+ * const result = evaluateRulesWithResults(investor, [
+ *   { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+ *   { field_path: 'firm.aum', operator: 'gte', value: 50000000 }
+ * ], 'AND');
+ * // {
+ * //   matched: true,
+ * //   logic: 'AND',
+ * //   rule_results: [
+ * //     { field_path: 'firm.stage', operator: 'eq', value: 'Series A', actual_value: 'Series A', matched: true },
+ * //     { field_path: 'firm.aum', operator: 'gte', value: 50000000, actual_value: 100000000, matched: true }
+ * //   ]
+ * // }
+ * ```
+ */
+export function evaluateRulesWithResults<T>(
+  entity: T,
+  rules: FilterRule[],
+  logic: 'AND' | 'OR' = 'AND'
+): {
+  matched: boolean;
+  logic: 'AND' | 'OR';
+  rule_results: RuleResult[];
+} {
+  const ruleResults = rules.map(rule => evaluateRuleWithResult(entity, rule));
+
+  const matched =
+    logic === 'AND'
+      ? ruleResults.every(r => r.matched)
+      : ruleResults.some(r => r.matched);
+
+  return {
+    matched,
+    logic,
+    rule_results: ruleResults,
+  };
+}
+
+/**
+ * Filter an array of entities using rules
+ *
+ * @param entities - Array of entities to filter
+ * @param rules - Filter rules to apply
+ * @param logic - Combination logic ('AND' or 'OR')
+ * @returns Entities that match the rules
+ *
+ * @example
+ * ```typescript
+ * const investors = [
+ *   { name: 'John', firm: { stage: 'Seed' } },
+ *   { name: 'Jane', firm: { stage: 'Series A' } },
+ *   { name: 'Bob', firm: { stage: 'Series B' } }
+ * ];
+ *
+ * filterEntities(investors, [
+ *   { field_path: 'firm.stage', operator: 'in', value: ['Series A', 'Series B'] }
+ * ]);
+ * // [
+ * //   { name: 'Jane', firm: { stage: 'Series A' } },
+ * //   { name: 'Bob', firm: { stage: 'Series B' } }
+ * // ]
+ * ```
+ */
+export function filterEntities<T>(
+  entities: T[],
+  rules: FilterRule[],
+  logic: 'AND' | 'OR' = 'AND'
+): T[] {
+  if (!entities || entities.length === 0) return [];
+  if (!rules || rules.length === 0) return entities; // No rules = return all
+
+  return entities.filter(entity => evaluateRules(entity, rules, logic));
+}

package/src/core/field-resolver.example.ts

@@ -0,0 +1,175 @@
+/**
+ * @startsimpli/funnels - Field Resolver Usage Examples
+ *
+ * This file demonstrates how to use the field resolver utilities
+ * for accessing and modifying entity properties.
+ */
+
+import { resolveField, setField, hasField, getFields } from './field-resolver';
+
+// Example 1: Simple investor entity
+const investor = {
+  id: '123',
+  name: 'John Doe',
+  email: 'john@example.com',
+  firm: {
+    id: 'firm-456',
+    name: 'Sequoia Capital',
+    stage: 'Series A',
+    aum_usd: 100000000,
+  },
+  tags: ['active', 'qualified', 'enterprise'],
+  profile: {
+    linkedin_url: 'https://linkedin.com/in/johndoe',
+    bio: 'Venture capitalist specializing in early-stage fintech',
+  },
+  metrics: {
+    response_rate: 0.85,
+    deal_count: 12,
+  },
+  created_at: new Date('2024-01-01'),
+};
+
+// Resolve simple fields
+console.log('Name:', resolveField(investor, 'name')); // 'John Doe'
+console.log('Email:', resolveField(investor, 'email')); // 'john@example.com'
+
+// Resolve nested fields
+console.log('Firm Name:', resolveField(investor, 'firm.name')); // 'Sequoia Capital'
+console.log('AUM:', resolveField(investor, 'firm.aum_usd')); // 100000000
+console.log('LinkedIn:', resolveField(investor, 'profile.linkedin_url'));
+
+// Resolve array elements
+console.log('First Tag:', resolveField(investor, 'tags[0]')); // 'active'
+console.log('Second Tag:', resolveField(investor, 'tags[1]')); // 'qualified'
+
+// Check field existence
+console.log('Has email?', hasField(investor, 'email')); // true
+console.log('Has phone?', hasField(investor, 'phone')); // false
+
+// Get multiple fields at once
+const fields = getFields(investor, [
+  'name',
+  'firm.stage',
+  'metrics.response_rate',
+  'tags[0]',
+]);
+console.log('Multiple fields:', fields);
+// {
+//   name: 'John Doe',
+//   'firm.stage': 'Series A',
+//   'metrics.response_rate': 0.85,
+//   'tags[0]': 'active'
+// }
+
+// Example 2: Recipe entity
+const recipe = {
+  id: 'recipe-789',
+  title: 'Chocolate Chip Cookies',
+  cuisine: 'American',
+  difficulty: 'easy',
+  ingredients: [
+    { name: 'flour', amount: '2 cups', unit: 'cup' },
+    { name: 'sugar', amount: '1 cup', unit: 'cup' },
+    { name: 'chocolate chips', amount: '2 cups', unit: 'cup' },
+  ],
+  steps: [
+    { order: 1, instruction: 'Mix dry ingredients' },
+    { order: 2, instruction: 'Add wet ingredients' },
+    { order: 3, instruction: 'Bake at 350°F for 12 minutes' },
+  ],
+  metadata: {
+    prep_time_minutes: 15,
+    cook_time_minutes: 12,
+    servings: 24,
+  },
+};
+
+// Access nested array objects
+console.log('First ingredient:', resolveField(recipe, 'ingredients[0].name')); // 'flour'
+console.log('Ingredient amount:', resolveField(recipe, 'ingredients[2].amount')); // '2 cups'
+console.log('Third step:', resolveField(recipe, 'steps[2].instruction'));
+
+// Example 3: Using setField for tag assignment
+const entity: any = {
+  id: '456',
+  name: 'Jane Smith',
+};
+
+// Add tags dynamically
+setField(entity, 'tags', ['new_lead', 'high_priority']);
+console.log('Entity with tags:', entity);
+// { id: '456', name: 'Jane Smith', tags: ['new_lead', 'high_priority'] }
+
+// Add nested metadata
+setField(entity, 'metadata.score', 95);
+setField(entity, 'metadata.tier', 'premium');
+console.log('Entity with metadata:', entity);
+// {
+//   id: '456',
+//   name: 'Jane Smith',
+//   tags: ['new_lead', 'high_priority'],
+//   metadata: { score: 95, tier: 'premium' }
+// }
+
+// Example 4: Real-world funnel rule evaluation
+interface FunnelEntity {
+  id: string;
+  firm?: {
+    stage?: string;
+    check_size_usd?: number;
+  };
+  tags?: string[];
+  metrics?: {
+    response_rate?: number;
+  };
+}
+
+function evaluateRule(entity: FunnelEntity, fieldPath: string, operator: string, value: any): boolean {
+  const actualValue = resolveField(entity, fieldPath);
+
+  switch (operator) {
+    case 'eq':
+      return actualValue === value;
+    case 'gt':
+      return actualValue > value;
+    case 'in':
+      return Array.isArray(value) && value.includes(actualValue);
+    case 'has_tag':
+      return Array.isArray(actualValue) && actualValue.includes(value);
+    default:
+      return false;
+  }
+}
+
+// Test the rule evaluator
+const testEntity: FunnelEntity = {
+  id: '1',
+  firm: {
+    stage: 'Series A',
+    check_size_usd: 5000000,
+  },
+  tags: ['qualified', 'enterprise'],
+  metrics: {
+    response_rate: 0.85,
+  },
+};
+
+console.log('Stage is Series A?', evaluateRule(testEntity, 'firm.stage', 'eq', 'Series A')); // true
+console.log('Check size > $1M?', evaluateRule(testEntity, 'firm.check_size_usd', 'gt', 1000000)); // true
+console.log('Has qualified tag?', evaluateRule(testEntity, 'tags', 'has_tag', 'qualified')); // true
+console.log('Response rate > 0.9?', evaluateRule(testEntity, 'metrics.response_rate', 'gt', 0.9)); // false
+
+// Example 5: Safe navigation with missing paths
+const partialEntity = {
+  id: '999',
+  name: 'Incomplete Entity',
+};
+
+// These all return undefined safely (no errors)
+console.log('Missing firm:', resolveField(partialEntity, 'firm.stage')); // undefined
+console.log('Missing tags:', resolveField(partialEntity, 'tags[0]')); // undefined
+console.log('Deep missing:', resolveField(partialEntity, 'a.b.c.d.e.f')); // undefined
+
+// hasField returns false for missing paths
+console.log('Has firm.stage?', hasField(partialEntity, 'firm.stage')); // false