@startsimpli/funnels 0.1.4 → 0.1.5

package/src/core/field-resolver.ts

@@ -0,0 +1,247 @@
+/**
+ * @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'
+ */
+
+/** Segments that would allow prototype pollution. */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Parse a field path into segments
+ *
+ * Examples:
+ * - 'name' → ['name']
+ * - 'firm.stage' → ['firm', 'stage']
+ * - 'tags[0]' → ['tags', '0']
+ * - 'investors[2].email' → ['investors', '2', 'email']
+ * - 'company.address.city.zipCode' → ['company', 'address', 'city', 'zipCode']
+ */
+function parseFieldPath(fieldPath: string): string[] {
+  const segments: string[] = [];
+  let current = '';
+  let inBracket = false;
+
+  for (let i = 0; i < fieldPath.length; i++) {
+    const char = fieldPath[i];
+
+    if (char === '[') {
+      if (current) {
+        segments.push(current);
+        current = '';
+      }
+      inBracket = true;
+    } else if (char === ']') {
+      if (current) {
+        segments.push(current);
+        current = '';
+      }
+      inBracket = false;
+    } else if (char === '.' && !inBracket) {
+      if (current) {
+        segments.push(current);
+        current = '';
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) {
+    segments.push(current);
+  }
+
+  return segments;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function resolveField<T>(entity: T, fieldPath: string): any {
+  // Handle null/undefined entity
+  if (entity == null) {
+    return undefined;
+  }
+
+  // Handle empty path
+  if (!fieldPath || fieldPath.trim() === '') {
+    return undefined;
+  }
+
+  const segments = parseFieldPath(fieldPath);
+  let current: any = entity;
+
+  for (const segment of segments) {
+    // Check if current is null/undefined before accessing
+    if (current == null) {
+      return undefined;
+    }
+
+    // Block prototype pollution
+    if (DANGEROUS_KEYS.has(segment)) {
+      return undefined;
+    }
+
+    // Handle array/object access
+    if (typeof current === 'object' && segment in current) {
+      current = current[segment];
+    } else {
+      return undefined;
+    }
+  }
+
+  return current;
+}
+
+/**
+ * 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 }
+ * ```
+ */
+export function setField<T>(entity: T, fieldPath: string, value: any): void {
+  // Handle null/undefined entity
+  if (entity == null) {
+    throw new Error('Cannot set field on null or undefined entity');
+  }
+
+  // Handle empty path
+  if (!fieldPath || fieldPath.trim() === '') {
+    throw new Error('Field path cannot be empty');
+  }
+
+  const segments = parseFieldPath(fieldPath);
+  let current: any = entity;
+
+  // Navigate to parent of target field
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const nextSegment = segments[i + 1];
+
+    // Block prototype pollution
+    if (DANGEROUS_KEYS.has(segment)) {
+      throw new Error(`Dangerous field path segment: "${segment}"`);
+    }
+
+    // Create intermediate object or array if missing
+    if (!(segment in current)) {
+      // Check if next segment is numeric (array index)
+      const isNextArray = /^\d+$/.test(nextSegment);
+      current[segment] = isNextArray ? [] : {};
+    }
+
+    current = current[segment];
+  }
+
+  // Set the final value
+  const lastSegment = segments[segments.length - 1];
+  if (DANGEROUS_KEYS.has(lastSegment)) {
+    throw new Error(`Dangerous field path segment: "${lastSegment}"`);
+  }
+  current[lastSegment] = value;
+}
+
+/**
+ * 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
+ * ```
+ */
+export function hasField<T>(entity: T, fieldPath: string): boolean {
+  const value = resolveField(entity, fieldPath);
+  return value !== undefined;
+}
+
+/**
+ * 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' }
+ * ```
+ */
+export function getFields<T>(
+  entity: T,
+  fieldPaths: string[]
+): Record<string, any> {
+  const result: Record<string, any> = {};
+
+  for (const path of fieldPaths) {
+    result[path] = resolveField(entity, path);
+  }
+
+  return result;
+}

package/src/core/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @startsimpli/funnels/core
+ *
+ * Core funnel engine - NO React dependencies
+ * Use this in server-side workers, CLI tools, or anywhere without React.
+ *
+ * @packageDocumentation
+ */
+
+// Export field resolver
+export {
+  resolveField,
+  setField,
+  hasField,
+  getFields,
+} from './field-resolver';
+
+// Export rule evaluator
+export {
+  evaluateRule,
+  evaluateRuleWithResult,
+  evaluateRules,
+  evaluateRulesAND,
+  evaluateRulesOR,
+  evaluateRulesWithResults,
+  filterEntities,
+} from './evaluator';
+
+// Export operators
+export { applyOperator } from './operators';
+
+// Export funnel engine
+export { FunnelEngine } from './engine';
+export type { ExecutionResult } from './engine';