Initial push of Plunk Next

2025-12-01 09:56:56 +01:00
parent 07cea20262
commit ff1876d580
566 changed files with 89036 additions and 28423 deletions
@@ -0,0 +1,151 @@
+/**
+ * Operator Behavior Documentation
+ *
+ * This file documents the consistent behavior of operators across the entire application.
+ * These operators are used in:
+ * - Segment filtering (SegmentService)
+ * - Workflow CONDITION steps (WorkflowExecutionService)
+ *
+ * IMPORTANT: Both implementations MUST behave identically for consistency.
+ */
+
+/**
+ * All supported operators
+ */
+export const OPERATORS = {
+  // String operators
+  EQUALS: 'equals',
+  NOT_EQUALS: 'notEquals',
+  CONTAINS: 'contains',
+  NOT_CONTAINS: 'notContains',
+
+  // Numeric operators
+  GREATER_THAN: 'greaterThan',
+  LESS_THAN: 'lessThan',
+  GREATER_THAN_OR_EQUAL: 'greaterThanOrEqual',
+  LESS_THAN_OR_EQUAL: 'lessThanOrEqual',
+
+  // Existence operators
+  EXISTS: 'exists',
+  NOT_EXISTS: 'notExists',
+
+  // Temporal operators (segments only)
+  WITHIN: 'within',
+} as const;
+
+/**
+ * Operators available for segments
+ */
+export const SEGMENT_OPERATORS = [
+  OPERATORS.EQUALS,
+  OPERATORS.NOT_EQUALS,
+  OPERATORS.CONTAINS,
+  OPERATORS.NOT_CONTAINS,
+  OPERATORS.GREATER_THAN,
+  OPERATORS.LESS_THAN,
+  OPERATORS.GREATER_THAN_OR_EQUAL,
+  OPERATORS.LESS_THAN_OR_EQUAL,
+  OPERATORS.EXISTS,
+  OPERATORS.NOT_EXISTS,
+  OPERATORS.WITHIN,
+] as const;
+
+/**
+ * Operators available for workflow conditions
+ * Note: 'within' is NOT supported in workflow conditions
+ */
+export const WORKFLOW_CONDITION_OPERATORS = [
+  OPERATORS.EQUALS,
+  OPERATORS.NOT_EQUALS,
+  OPERATORS.CONTAINS,
+  OPERATORS.NOT_CONTAINS,
+  OPERATORS.GREATER_THAN,
+  OPERATORS.LESS_THAN,
+  OPERATORS.GREATER_THAN_OR_EQUAL,
+  OPERATORS.LESS_THAN_OR_EQUAL,
+  OPERATORS.EXISTS,
+  OPERATORS.NOT_EXISTS,
+] as const;
+
+/**
+ * Operator Behavior Rules
+ *
+ * CRITICAL: These rules apply to BOTH SegmentService and WorkflowExecutionService
+ *
+ * 1. EQUALS (=)
+ *    - Matches when actualValue === expectedValue
+ *    - CAN match null/undefined if expectedValue is also null/undefined
+ *    - String fields: case-insensitive (email)
+ *    - Boolean fields: strict comparison
+ *
+ * 2. NOT_EQUALS (≠)
+ *    - ONLY matches when field EXISTS and actualValue !== expectedValue
+ *    - Does NOT match missing fields (undefined/null)
+ *    - Use notExists operator if you want to find missing fields
+ *    - Use OR[notEquals, notExists] if you want both
+ *
+ * 3. CONTAINS (substring)
+ *    - ONLY matches when field EXISTS and contains substring
+ *    - Does NOT match missing fields (undefined/null)
+ *    - String fields: case-insensitive (email)
+ *    - Converts values to strings before comparison
+ *
+ * 4. NOT_CONTAINS (not substring)
+ *    - ONLY matches when field EXISTS and does NOT contain substring
+ *    - Does NOT match missing fields (undefined/null)
+ *    - Use notExists operator if you want to find missing fields
+ *    - Use OR[notContains, notExists] if you want both
+ *
+ * 5. GREATER_THAN (>)
+ *    - ONLY matches when field EXISTS and Number(actualValue) > Number(expectedValue)
+ *    - Does NOT match missing fields (undefined/null)
+ *    - Converts values to numbers before comparison
+ *
+ * 6. LESS_THAN (<)
+ *    - ONLY matches when field EXISTS and Number(actualValue) < Number(expectedValue)
+ *    - Does NOT match missing fields (undefined/null)
+ *    - Converts values to numbers before comparison
+ *
+ * 7. GREATER_THAN_OR_EQUAL (≥)
+ *    - ONLY matches when field EXISTS and Number(actualValue) >= Number(expectedValue)
+ *    - Does NOT match missing fields (undefined/null)
+ *    - Converts values to numbers before comparison
+ *
+ * 8. LESS_THAN_OR_EQUAL (≤)
+ *    - ONLY matches when field EXISTS and Number(actualValue) <= Number(expectedValue)
+ *    - Does NOT match missing fields (undefined/null)
+ *    - Converts values to numbers before comparison
+ *
+ * 9. EXISTS
+ *    - Matches when actualValue !== undefined && actualValue !== null
+ *    - Matches empty strings, zero, false (these are valid existing values)
+ *
+ * 10. NOT_EXISTS
+ *     - Matches when actualValue === undefined || actualValue === null
+ *     - Does NOT match empty strings, zero, or false
+ *
+ * 11. WITHIN (temporal - segments only)
+ *     - Matches when date field is within specified time period
+ *     - Requires unit: 'days' | 'hours' | 'minutes'
+ *     - Example: within 7 days = createdAt >= (now - 7 days)
+ */
+
+/**
+ * Example: Finding contacts without a field vs with a different value
+ *
+ * To find contacts where plan is NOT "basic":
+ * - Use: { field: 'data.plan', operator: 'notEquals', value: 'basic' }
+ * - Result: Matches contacts with plan='premium', plan='free', etc.
+ * - Does NOT match: Contacts without plan field
+ *
+ * To find contacts WITHOUT a plan field:
+ * - Use: { field: 'data.plan', operator: 'notExists' }
+ * - Result: Matches contacts where plan is undefined or null
+ *
+ * To find contacts where plan is NOT "basic" OR plan doesn't exist:
+ * - Use: OR[
+ *     { field: 'data.plan', operator: 'notEquals', value: 'basic' },
+ *     { field: 'data.plan', operator: 'notExists' }
+ *   ]
+ * - Result: Matches all except contacts with plan='basic'
+ */