@billdog.io/react-native 1.0.0-beta.2

package/src/xFlowTags.ts

@@ -0,0 +1,463 @@
+/**
+ * xFlow Tag Preprocessor — React Native SDK.
+ *
+ * Faithful port of src/lib/filters/xFlowTags.ts (the web reference). Implements
+ * the canonical grammar at src/schemas/xflow-grammar.md. Runs as a first pass
+ * before {{ }} interpolation. The conformance corpus
+ * (tests/parity/xflow-corpus/) is the cross-platform contract — web, iOS,
+ * Android, and React Native parsers must produce identical output.
+ *
+ * Tags: {% assign %} (with filter chains), {% if/elsif/else/endif %},
+ *       {% unless/endunless %}, {% case/when/else/endcase %}.
+ * Conditions: ==, !=, >, <, >=, <=, contains, and, or, unary !, postfix exists.
+ */
+
+import { getNestedValue, isTruthy, stringify, toNumber } from './valueUtils';
+import { applyFilterChain } from './filters';
+
+// ============= Public API =============
+
+export interface XFlowTagResult {
+  text: string;
+  variables: Record<string, any>;
+}
+
+export function processXFlowTags(
+  text: string,
+  variables: Record<string, any>,
+): XFlowTagResult {
+  if (!text || typeof text !== 'string' || !text.includes('{%')) {
+    return { text: text ?? '', variables };
+  }
+  const vars = { ...variables };
+  const tokens = tokenize(text);
+  const output = processTokens(tokens, vars);
+  return { text: output, variables: vars };
+}
+
+// ============= Tokenizer =============
+
+interface Token {
+  type: 'text' | 'tag';
+  content: string;
+  raw: string;
+}
+
+function tokenize(text: string): Token[] {
+  const tokens: Token[] = [];
+  let pos = 0;
+
+  while (pos < text.length) {
+    const tagStart = text.indexOf('{%', pos);
+    if (tagStart === -1) {
+      tokens.push({ type: 'text', content: text.slice(pos), raw: text.slice(pos) });
+      break;
+    }
+    if (tagStart > pos) {
+      const segment = text.slice(pos, tagStart);
+      tokens.push({ type: 'text', content: segment, raw: segment });
+    }
+    const tagEnd = text.indexOf('%}', tagStart);
+    if (tagEnd === -1) {
+      const segment = text.slice(tagStart);
+      tokens.push({ type: 'text', content: segment, raw: segment });
+      break;
+    }
+    const raw = text.slice(tagStart, tagEnd + 2);
+    const content = text.slice(tagStart + 2, tagEnd).trim();
+    tokens.push({ type: 'tag', content, raw });
+    pos = tagEnd + 2;
+  }
+  return tokens;
+}
+
+// ============= Token Processor =============
+
+function processTokens(tokens: Token[], vars: Record<string, any>): string {
+  let output = '';
+  let i = 0;
+
+  while (i < tokens.length) {
+    const token = tokens[i];
+
+    if (token.type === 'text') {
+      output += token.content;
+      i++;
+      continue;
+    }
+
+    const tagContent = token.content;
+
+    if (tagContent.startsWith('assign ')) {
+      processAssign(tagContent, vars);
+      i++;
+      continue;
+    }
+
+    if (tagContent.startsWith('if ')) {
+      const { result, endIndex } = processIfBlock(tokens, i, vars);
+      output += result;
+      i = endIndex + 1;
+      continue;
+    }
+
+    // {% unless X %}…{% endunless %} — Liquid's negated-if. Rewrite the open
+    // token to `if !(X)` and reuse processIfBlock (which also closes on
+    // `endunless`). elsif/else keep their if-semantics.
+    if (tagContent.startsWith('unless ')) {
+      const condition = tagContent.slice('unless '.length).trim();
+      const rewritten = tokens.slice();
+      rewritten[i] = { type: 'tag', content: `if !(${condition})`, raw: token.raw };
+      const { result, endIndex } = processIfBlock(rewritten, i, vars);
+      output += result;
+      i = endIndex + 1;
+      continue;
+    }
+
+    // {% case X %}{% when Y %}…{% else %}…{% endcase %}
+    if (tagContent.startsWith('case ')) {
+      const { result, endIndex } = processCaseBlock(tokens, i, vars);
+      output += result;
+      i = endIndex + 1;
+      continue;
+    }
+
+    // Unknown tag — keep raw.
+    output += token.raw;
+    i++;
+  }
+
+  return output;
+}
+
+// ============= Assign Processing =============
+
+function processAssign(tagContent: string, vars: Record<string, any>): void {
+  const assignMatch = tagContent.match(/^assign\s+(\w+)\s*=\s*(.+)$/);
+  if (!assignMatch) return;
+
+  const varName = assignMatch[1];
+  const expression = assignMatch[2].trim();
+  const { baseExpr, filterChain } = splitExpressionAndFilters(expression);
+
+  let value = resolveValue(baseExpr.trim(), vars);
+  if (filterChain) {
+    try {
+      value = applyFilterChain(value, filterChain);
+    } catch (error) {
+      console.warn(`[xFlowTags] Filter chain failed for assign "${varName}":`, error);
+    }
+  }
+  vars[varName] = value;
+}
+
+/** Split "value | filter1 | filter2" at the first unquoted pipe. */
+function splitExpressionAndFilters(
+  expression: string,
+): { baseExpr: string; filterChain: string | null } {
+  let inQuote = false;
+  let quoteChar = '';
+
+  for (let i = 0; i < expression.length; i++) {
+    const char = expression[i];
+    if ((char === '"' || char === "'") && expression[i - 1] !== '\\') {
+      if (!inQuote) { inQuote = true; quoteChar = char; }
+      else if (char === quoteChar) { inQuote = false; }
+    } else if (char === '|' && !inQuote) {
+      return {
+        baseExpr: expression.slice(0, i),
+        filterChain: expression.slice(i + 1).trim(),
+      };
+    }
+  }
+  return { baseExpr: expression, filterChain: null };
+}
+
+// ============= If / Unless Block Processing =============
+
+interface BlockResult {
+  result: string;
+  endIndex: number;
+}
+
+/**
+ * Process an {% if %} / {% unless %} block. `endif` and `endunless` are
+ * interchangeable terminators (grammar §2.3).
+ */
+function processIfBlock(
+  tokens: Token[],
+  startIndex: number,
+  vars: Record<string, any>,
+): BlockResult {
+  const openingCondition = tokens[startIndex].content.slice(3).trim(); // remove "if "
+
+  const branches: { condition: string | null; bodyTokens: Token[] }[] = [];
+  let currentCondition: string | null = openingCondition;
+  let currentBody: Token[] = [];
+  let depth = 0;
+  let i = startIndex + 1;
+
+  while (i < tokens.length) {
+    const token = tokens[i];
+
+    if (token.type === 'tag') {
+      const content = token.content;
+
+      if (content.startsWith('if ') || content.startsWith('unless ')) {
+        depth++;
+        currentBody.push(token);
+        i++;
+        continue;
+      }
+
+      if (content === 'endif' || content === 'endunless') {
+        if (depth > 0) {
+          depth--;
+          currentBody.push(token);
+          i++;
+          continue;
+        }
+        branches.push({ condition: currentCondition, bodyTokens: currentBody });
+        break;
+      }
+
+      if (depth === 0 && content.startsWith('elsif ')) {
+        branches.push({ condition: currentCondition, bodyTokens: currentBody });
+        currentCondition = content.slice(6).trim();
+        currentBody = [];
+        i++;
+        continue;
+      }
+
+      if (depth === 0 && content === 'else') {
+        branches.push({ condition: currentCondition, bodyTokens: currentBody });
+        currentCondition = null;
+        currentBody = [];
+        i++;
+        continue;
+      }
+    }
+
+    currentBody.push(token);
+    i++;
+  }
+
+  if (i >= tokens.length) {
+    branches.push({ condition: currentCondition, bodyTokens: currentBody });
+  }
+
+  for (const branch of branches) {
+    if (branch.condition === null || evaluateCondition(branch.condition, vars)) {
+      return { result: processTokens(branch.bodyTokens, vars), endIndex: i };
+    }
+  }
+  return { result: '', endIndex: i };
+}
+
+// ============= Case Block Processing =============
+
+/**
+ * Process {% case X %}{% when Y %}…{% when A, B %}…{% else %}…{% endcase %}.
+ * Evaluates X once; emits the first `when` whose value (any of its
+ * comma-separated candidates) is string-equal to X; falls back to `else`.
+ */
+function processCaseBlock(
+  tokens: Token[],
+  startIndex: number,
+  vars: Record<string, any>,
+): BlockResult {
+  const caseExpr = tokens[startIndex].content.slice('case '.length).trim();
+  const caseValue = resolveValue(caseExpr, vars);
+
+  const branches: { condition: string | null; bodyTokens: Token[] }[] = [];
+  let currentCondition: string | null = null;
+  let currentBody: Token[] = [];
+  let inBranch = false;
+  let depth = 0;
+  let i = startIndex + 1;
+
+  while (i < tokens.length) {
+    const token = tokens[i];
+
+    if (token.type === 'tag') {
+      const content = token.content;
+
+      if (content.startsWith('case ')) {
+        depth++;
+        currentBody.push(token);
+        i++;
+        continue;
+      }
+
+      if (content === 'endcase') {
+        if (depth > 0) {
+          depth--;
+          currentBody.push(token);
+          i++;
+          continue;
+        }
+        if (inBranch) branches.push({ condition: currentCondition, bodyTokens: currentBody });
+        break;
+      }
+
+      if (depth === 0 && content.startsWith('when ')) {
+        if (inBranch) branches.push({ condition: currentCondition, bodyTokens: currentBody });
+        currentCondition = content.slice('when '.length).trim();
+        currentBody = [];
+        inBranch = true;
+        i++;
+        continue;
+      }
+
+      if (depth === 0 && content === 'else') {
+        if (inBranch) branches.push({ condition: currentCondition, bodyTokens: currentBody });
+        currentCondition = null;
+        currentBody = [];
+        inBranch = true;
+        i++;
+        continue;
+      }
+    }
+
+    if (inBranch) currentBody.push(token);
+    i++;
+  }
+
+  if (i >= tokens.length && inBranch) {
+    branches.push({ condition: currentCondition, bodyTokens: currentBody });
+  }
+
+  const caseStr = stringify(caseValue);
+  for (const branch of branches) {
+    if (branch.condition === null) {
+      // else branch
+      return { result: processTokens(branch.bodyTokens, vars), endIndex: i };
+    }
+    // when supports comma-separated candidates: `when "a", "b"`.
+    const candidates = branch.condition.split(',').map((c) => c.trim());
+    for (const candidate of candidates) {
+      if (stringify(resolveValue(candidate, vars)) === caseStr) {
+        return { result: processTokens(branch.bodyTokens, vars), endIndex: i };
+      }
+    }
+  }
+  return { result: '', endIndex: i };
+}
+
+// ============= Condition Evaluation =============
+
+function evaluateCondition(condition: string, vars: Record<string, any>): boolean {
+  const trimmed = condition.trim();
+
+  // Unary `!` negation. Strips one optional outer paren pair so `!(a and b)`
+  // negates the whole inner condition.
+  if (trimmed.startsWith('!')) {
+    let inner = trimmed.slice(1).trim();
+    if (inner.startsWith('(') && inner.endsWith(')')) {
+      inner = inner.slice(1, -1).trim();
+    }
+    return !evaluateCondition(inner, vars);
+  }
+
+  const parts = splitLogical(trimmed);
+
+  if (parts.length === 1) {
+    return evaluateComparison(parts[0].expr.trim(), vars);
+  }
+
+  let result = evaluateComparison(parts[0].expr.trim(), vars);
+  for (let i = 1; i < parts.length; i++) {
+    const { operator, expr } = parts[i];
+    const right = evaluateComparison(expr.trim(), vars);
+    result = operator === 'and' ? result && right : result || right;
+  }
+  return result;
+}
+
+interface LogicalPart {
+  operator: 'and' | 'or' | null;
+  expr: string;
+}
+
+function splitLogical(condition: string): LogicalPart[] {
+  const segments = condition.split(/\b(and|or)\b/);
+  const result: LogicalPart[] = [];
+
+  for (let i = 0; i < segments.length; i++) {
+    if (i === 0) {
+      result.push({ operator: null, expr: segments[0] });
+    } else if (segments[i] === 'and' || segments[i] === 'or') {
+      result.push({ operator: segments[i] as 'and' | 'or', expr: segments[i + 1] || '' });
+      i++;
+    }
+  }
+  return result.length > 0 ? result : [{ operator: null, expr: condition }];
+}
+
+/** Evaluate "a == b", "a contains b", "a exists", or bare "a" (truthiness). */
+function evaluateComparison(expr: string, vars: Record<string, any>): boolean {
+  // Postfix `exists` — checked before binary operators so an identifier
+  // containing "exists" isn't mis-parsed.
+  if (expr.endsWith(' exists')) {
+    const leftStr = expr.slice(0, -' exists'.length).trim();
+    if (leftStr) {
+      const value = resolveValue(leftStr, vars);
+      return value !== null && value !== undefined && stringify(value) !== '';
+    }
+  }
+
+  const operators = ['!=', '>=', '<=', '==', '>', '<', ' contains '];
+  for (const op of operators) {
+    const opIndex = expr.indexOf(op);
+    if (opIndex !== -1) {
+      const left = resolveValue(expr.slice(0, opIndex).trim(), vars);
+      const right = resolveValue(expr.slice(opIndex + op.length).trim(), vars);
+      return compareValues(left, right, op.trim());
+    }
+  }
+
+  return isTruthy(resolveValue(expr.trim(), vars));
+}
+
+function isNullishEqual(a: any, b: any): boolean {
+  const an = a === null || a === undefined;
+  const bn = b === null || b === undefined;
+  if (an && bn) return true;
+  if (an || bn) return false;
+  return stringify(a) === stringify(b);
+}
+
+function compareValues(left: any, right: any, op: string): boolean {
+  switch (op) {
+    case '==': return isNullishEqual(left, right);
+    case '!=': return !isNullishEqual(left, right);
+    case '>': return toNumber(left) > toNumber(right);
+    case '<': return toNumber(left) < toNumber(right);
+    case '>=': return toNumber(left) >= toNumber(right);
+    case '<=': return toNumber(left) <= toNumber(right);
+    case 'contains': {
+      if (Array.isArray(left)) {
+        return left.some((el) => stringify(el) === stringify(right));
+      }
+      return stringify(left).includes(stringify(right));
+    }
+    default: return false;
+  }
+}
+
+// ============= Value Resolution =============
+
+function resolveValue(token: string, vars: Record<string, any>): any {
+  if (!token) return undefined;
+
+  if ((token.startsWith('"') && token.endsWith('"')) ||
+      (token.startsWith("'") && token.endsWith("'"))) {
+    return token.slice(1, -1);
+  }
+  if (token === 'true') return true;
+  if (token === 'false') return false;
+  if (token === 'nil' || token === 'null') return null;
+  if (/^-?\d+(\.\d+)?$/.test(token)) return Number(token);
+
+  return getNestedValue(vars, token);
+}