@startsimpli/funnels 0.1.3 → 0.1.5

package/dist/core/index.d.ts

@@ -1,359 +0,0 @@
-import { h as FilterRule, R as RuleResult, O as Operator, j as FunnelResult, o as StageStats, i as Funnel } from '../index-BGDEXbuz.js';
-
-/**
- * @startsimpli/funnels - Field Resolver Utility
- *
- * Safely resolves and sets field values using dot-notation paths on arbitrary objects.
- * Used by rule evaluator and execution engine to access entity properties.
- *
- * Examples:
- * - resolveField({name: 'John'}, 'name') → 'John'
- * - resolveField({firm: {stage: 'Seed'}}, 'firm.stage') → 'Seed'
- * - resolveField({tags: ['a', 'b']}, 'tags[0]') → 'a'
- * - resolveField({investors: [{email: 'a@b.com'}]}, 'investors[0].email') → 'a@b.com'
- */
-/**
- * Resolve a field value from an entity using dot-notation path
- *
- * Features:
- * - Dot notation: 'firm.name', 'recipe.ingredients.name'
- * - Array access: 'tags[0]', 'investors[2].email'
- * - Nested paths: 'company.address.city.zipCode'
- * - Safe navigation: Returns undefined for missing paths (no errors)
- * - Type preservation: Maintains number/boolean/date types
- *
- * @param entity - The object to resolve the field from
- * @param fieldPath - Dot-notation path to the field
- * @returns The resolved value, or undefined if path doesn't exist
- *
- * @example
- * ```typescript
- * const investor = {
- *   name: 'John Doe',
- *   firm: { stage: 'Seed', aum: 100000000 },
- *   tags: ['active', 'qualified'],
- *   metadata: { score: 85 }
- * };
- *
- * resolveField(investor, 'name'); // 'John Doe'
- * resolveField(investor, 'firm.stage'); // 'Seed'
- * resolveField(investor, 'tags[0]'); // 'active'
- * resolveField(investor, 'metadata.score'); // 85
- * resolveField(investor, 'firm.missing'); // undefined
- * ```
- */
-declare function resolveField<T>(entity: T, fieldPath: string): any;
-/**
- * Set a field value on an entity using dot-notation path
- *
- * Features:
- * - Creates intermediate objects/arrays as needed
- * - Handles array index assignment
- * - Mutates the entity in place
- * - Safe for missing intermediate paths
- *
- * @param entity - The object to set the field on
- * @param fieldPath - Dot-notation path to the field
- * @param value - The value to set
- *
- * @example
- * ```typescript
- * const investor = { name: 'John' };
- *
- * setField(investor, 'firm.stage', 'Series A');
- * // investor = { name: 'John', firm: { stage: 'Series A' } }
- *
- * setField(investor, 'tags[0]', 'qualified');
- * // investor.tags = ['qualified']
- *
- * setField(investor, 'metadata.score', 85);
- * // investor.metadata = { score: 85 }
- * ```
- */
-declare function setField<T>(entity: T, fieldPath: string, value: any): void;
-/**
- * Check if a field path exists on an entity
- *
- * @param entity - The object to check
- * @param fieldPath - Dot-notation path to check
- * @returns true if the path exists and has a defined value
- *
- * @example
- * ```typescript
- * const investor = { name: 'John', firm: { stage: 'Seed' } };
- *
- * hasField(investor, 'name'); // true
- * hasField(investor, 'firm.stage'); // true
- * hasField(investor, 'firm.missing'); // false
- * hasField(investor, 'tags[0]'); // false
- * ```
- */
-declare function hasField<T>(entity: T, fieldPath: string): boolean;
-/**
- * Get multiple field values at once
- *
- * @param entity - The object to resolve fields from
- * @param fieldPaths - Array of field paths to resolve
- * @returns Object mapping field paths to their values
- *
- * @example
- * ```typescript
- * const investor = { name: 'John', firm: { stage: 'Seed' }, tags: ['active'] };
- *
- * getFields(investor, ['name', 'firm.stage', 'tags[0]']);
- * // { name: 'John', 'firm.stage': 'Seed', 'tags[0]': 'active' }
- * ```
- */
-declare function getFields<T>(entity: T, fieldPaths: string[]): Record<string, any>;
-
-/**
- * @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
- */
-
-/**
- * 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')
- * ```
- */
-declare function evaluateRule<T>(entity: T, rule: FilterRule): boolean;
-/**
- * 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
- * // }
- * ```
- */
-declare function evaluateRuleWithResult<T>(entity: T, rule: FilterRule): RuleResult;
-/**
- * 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)
- * ```
- */
-declare function evaluateRulesAND<T>(entity: T, rules: FilterRule[]): boolean;
-/**
- * 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)
- * ```
- */
-declare function evaluateRulesOR<T>(entity: T, rules: FilterRule[]): boolean;
-/**
- * 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
- * ```
- */
-declare function evaluateRules<T>(entity: T, rules: FilterRule[], logic?: 'AND' | 'OR'): boolean;
-/**
- * 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 }
- * //   ]
- * // }
- * ```
- */
-declare function evaluateRulesWithResults<T>(entity: T, rules: FilterRule[], logic?: 'AND' | 'OR'): {
-    matched: boolean;
-    logic: 'AND' | 'OR';
-    rule_results: RuleResult[];
-};
-/**
- * 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' } }
- * // ]
- * ```
- */
-declare function filterEntities<T>(entities: T[], rules: FilterRule[], logic?: 'AND' | 'OR'): T[];
-
-/**
- * @startsimpli/funnels - Operator Implementation
- *
- * BRUTALLY GENERIC operator logic that works with ANY data type.
- *
- * Each operator is a pure function: (actual, expected) => boolean
- */
-
-/**
- * Apply an operator to compare actual vs expected values
- *
- * @param operator - The comparison operator
- * @param actual - The actual value from entity
- * @param expected - The expected value from rule
- * @returns Whether the comparison passes
- */
-declare function applyOperator(operator: Operator, actual: any, expected: any): boolean;
-
-/**
- * @startsimpli/funnels - Core Funnel Execution Engine
- *
- * BRUTALLY GENERIC - Works for ANY entity type:
- * - Investors, firms, contacts, organizations
- * - Recipes, ingredients, users
- * - Leads, tasks, projects
- * - GitHub repos, pull requests, issues
- *
- * The engine processes entities through stages sequentially,
- * evaluating rules and applying actions based on match results.
- */
-
-/**
- * Complete result of funnel execution
- */
-interface ExecutionResult<T = any> {
-    /** Entities that matched and are in output */
-    matched: FunnelResult<T>[];
-    /** Entities that were excluded */
-    excluded: FunnelResult<T>[];
-    /** Total entities processed */
-    total_input: number;
-    /** Total entities that matched */
-    total_matched: number;
-    /** Total entities excluded */
-    total_excluded: number;
-    /** Total entities tagged */
-    total_tagged: number;
-    /** Per-stage statistics */
-    stage_stats: Record<string, StageStats>;
-    /** Execution duration in milliseconds */
-    duration_ms: number;
-    /** Errors encountered (non-fatal) */
-    errors?: string[];
-}
-/**
- * Core funnel execution engine
- *
- * Processes entities through stages sequentially, evaluating rules
- * and applying actions based on match results.
- *
- * Generic over entity type T - works with ANY data structure.
- */
-declare class FunnelEngine<T = any> {
-    /**
-     * Execute a funnel on a set of entities
-     *
-     * @param funnel - The funnel definition to execute
-     * @param entities - Input entities to process
-     * @returns ExecutionResult with matched/excluded entities and stats
-     */
-    execute(funnel: Funnel<T>, entities: T[]): ExecutionResult<T>;
-    /**
-     * Process a single entity through a stage
-     *
-     * @param stage - The stage to process
-     * @param entity - The entity to evaluate
-     * @returns StageResult with match status and actions taken
-     */
-    private processStage;
-}
-
-export { type ExecutionResult, FunnelEngine, applyOperator, evaluateRule, evaluateRuleWithResult, evaluateRules, evaluateRulesAND, evaluateRulesOR, evaluateRulesWithResults, filterEntities, getFields, hasField, resolveField, setField };