@volter/twin-temporal 0.1.0

package/src/temporal-visibility.ts

@@ -0,0 +1,245 @@
+// VISIBILITY — Temporal's list filter language (https://docs.temporal.io/list-filter), read over the
+// runs' own fields. Temporal's language is a SQL WHERE subset: comparisons (`=`, `!=`, `>`, `>=`, `<`,
+// `<=`), `IN (...)`, `BETWEEN a AND b`, `STARTS_WITH`, `IS NULL`/`IS NOT NULL`, combined with `AND`,
+// `OR` and parentheses, then an optional `ORDER BY`. This reads that grammar and evaluates it against
+// one run's system attributes (WorkflowId, WorkflowType, ExecutionStatus, StartTime, CloseTime, …)
+// and its custom search attributes. What the language has and this reader does not (`ORDER BY` beyond
+// StartTime/CloseTime, `GROUP BY`) is refused with INVALID_ARGUMENT naming it, never ignored.
+
+export type VisibilityValue = string | number | boolean | null | string[];
+export type VisibilityRow = Record<string, VisibilityValue | undefined>;
+
+type Expr =
+  | { kind: 'and' | 'or'; left: Expr; right: Expr }
+  | { kind: 'not'; expr: Expr }
+  | { kind: 'cmp'; field: string; op: string; value: VisibilityValue }
+  | { kind: 'in'; field: string; values: VisibilityValue[]; negate: boolean }
+  | { kind: 'between'; field: string; low: VisibilityValue; high: VisibilityValue }
+  | { kind: 'starts'; field: string; prefix: string }
+  | { kind: 'null'; field: string; negate: boolean };
+
+export class VisibilityQueryError extends Error {}
+
+type Token = { kind: 'ident' | 'string' | 'number' | 'op' | 'lparen' | 'rparen' | 'comma'; text: string };
+
+function tokenize(query: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < query.length) {
+    const c = query[i]!;
+    if (/\s/.test(c)) { i += 1; continue; }
+    if (c === '(') { tokens.push({ kind: 'lparen', text: c }); i += 1; continue; }
+    if (c === ')') { tokens.push({ kind: 'rparen', text: c }); i += 1; continue; }
+    if (c === ',') { tokens.push({ kind: 'comma', text: c }); i += 1; continue; }
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      let text = '';
+      while (j < query.length && query[j] !== c) {
+        if (query[j] === '\\' && j + 1 < query.length) { text += query[j + 1]; j += 2; continue; }
+        text += query[j];
+        j += 1;
+      }
+      if (j >= query.length) throw new VisibilityQueryError(`unterminated string in query: ${query}`);
+      tokens.push({ kind: 'string', text });
+      i = j + 1;
+      continue;
+    }
+    if (c === '`') {
+      const j = query.indexOf('`', i + 1);
+      if (j < 0) throw new VisibilityQueryError(`unterminated backquote in query: ${query}`);
+      tokens.push({ kind: 'ident', text: query.slice(i + 1, j) });
+      i = j + 1;
+      continue;
+    }
+    const op = /^(>=|<=|!=|<>|=|>|<)/.exec(query.slice(i));
+    if (op) { tokens.push({ kind: 'op', text: op[1] === '<>' ? '!=' : op[1]! }); i += op[1]!.length; continue; }
+    const number = /^-?\d+(\.\d+)?/.exec(query.slice(i));
+    if (number) { tokens.push({ kind: 'number', text: number[0] }); i += number[0].length; continue; }
+    const ident = /^[A-Za-z_][A-Za-z0-9_.]*/.exec(query.slice(i));
+    if (ident) { tokens.push({ kind: 'ident', text: ident[0] }); i += ident[0].length; continue; }
+    throw new VisibilityQueryError(`unexpected character ${JSON.stringify(c)} in query: ${query}`);
+  }
+  return tokens;
+}
+
+export type ParsedQuery = { where: Expr | null; orderBy: Array<{ field: string; desc: boolean }> };
+
+export function parseVisibilityQuery(query: string): ParsedQuery {
+  const tokens = tokenize(query);
+  let pos = 0;
+  const peek = (): Token | undefined => tokens[pos];
+  const keyword = (word: string): boolean => {
+    const token = peek();
+    if (token?.kind === 'ident' && token.text.toUpperCase() === word) { pos += 1; return true; }
+    return false;
+  };
+  const expect = (kind: Token['kind']): Token => {
+    const token = tokens[pos];
+    if (!token || token.kind !== kind) throw new VisibilityQueryError(`expected ${kind} at ${token ? JSON.stringify(token.text) : 'end of query'}`);
+    pos += 1;
+    return token;
+  };
+  const literal = (): VisibilityValue => {
+    const token = tokens[pos];
+    if (!token) throw new VisibilityQueryError('expected a value at end of query');
+    pos += 1;
+    if (token.kind === 'string') return token.text;
+    if (token.kind === 'number') return Number(token.text);
+    if (token.kind === 'ident' && /^(true|false)$/i.test(token.text)) return token.text.toLowerCase() === 'true';
+    throw new VisibilityQueryError(`expected a value, got ${JSON.stringify(token.text)}`);
+  };
+  const primary = (): Expr => {
+    if (peek()?.kind === 'lparen') {
+      pos += 1;
+      const inner = or();
+      expect('rparen');
+      return inner;
+    }
+    if (keyword('NOT')) return { kind: 'not', expr: primary() };
+    const field = expect('ident').text;
+    if (keyword('IN')) {
+      expect('lparen');
+      const values = [literal()];
+      while (peek()?.kind === 'comma') { pos += 1; values.push(literal()); }
+      expect('rparen');
+      return { kind: 'in', field, values, negate: false };
+    }
+    if (keyword('NOT')) {
+      if (keyword('IN')) {
+        expect('lparen');
+        const values = [literal()];
+        while (peek()?.kind === 'comma') { pos += 1; values.push(literal()); }
+        expect('rparen');
+        return { kind: 'in', field, values, negate: true };
+      }
+      throw new VisibilityQueryError(`expected IN after NOT in ${field} NOT …`);
+    }
+    if (keyword('BETWEEN')) {
+      const low = literal();
+      if (!keyword('AND')) throw new VisibilityQueryError('expected AND in BETWEEN');
+      return { kind: 'between', field, low, high: literal() };
+    }
+    if (keyword('STARTS_WITH')) {
+      const prefix = literal();
+      return { kind: 'starts', field, prefix: String(prefix) };
+    }
+    if (keyword('IS')) {
+      const negate = keyword('NOT');
+      if (!keyword('NULL')) throw new VisibilityQueryError('expected NULL after IS');
+      return { kind: 'null', field, negate };
+    }
+    const op = expect('op').text;
+    return { kind: 'cmp', field, op, value: literal() };
+  };
+  const and = (): Expr => {
+    let left = primary();
+    while (keyword('AND')) left = { kind: 'and', left, right: primary() };
+    return left;
+  };
+  const or = (): Expr => {
+    let left = and();
+    while (keyword('OR')) left = { kind: 'or', left, right: and() };
+    return left;
+  };
+  let where: Expr | null = null;
+  if (tokens.length > 0 && !(tokens[0]!.kind === 'ident' && tokens[0]!.text.toUpperCase() === 'ORDER')) where = or();
+  const orderBy: Array<{ field: string; desc: boolean }> = [];
+  if (keyword('ORDER')) {
+    if (!keyword('BY')) throw new VisibilityQueryError('expected BY after ORDER');
+    do {
+      const field = expect('ident').text;
+      const desc = keyword('DESC');
+      if (!desc) keyword('ASC');
+      orderBy.push({ field, desc });
+      if (peek()?.kind !== 'comma') break;
+      pos += 1;
+    } while (pos < tokens.length);
+  }
+  if (keyword('GROUP')) throw new VisibilityQueryError('GROUP BY is not supported by this server');
+  if (pos !== tokens.length) throw new VisibilityQueryError(`unexpected ${JSON.stringify(tokens[pos]!.text)} in query`);
+  return { where, orderBy };
+}
+
+function compare(a: VisibilityValue | undefined, b: VisibilityValue): number | null {
+  if (a === undefined || a === null || b === null) return null;
+  if (typeof a === 'number' || typeof b === 'number') {
+    // a Datetime attribute is held as epoch milliseconds; its literal is an RFC 3339 string
+    const asNumber = (value: VisibilityValue): number => typeof value === 'number' ? value
+      : Number.isNaN(Number(value)) ? Date.parse(String(value)) : Number(value);
+    const x = asNumber(a);
+    const y = asNumber(b);
+    return Number.isNaN(x) || Number.isNaN(y) ? null : x - y;
+  }
+  const x = String(a);
+  const y = String(b);
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+
+function evaluate(expr: Expr, row: VisibilityRow, fieldOf: (name: string) => string): boolean {
+  switch (expr.kind) {
+    case 'and': return evaluate(expr.left, row, fieldOf) && evaluate(expr.right, row, fieldOf);
+    case 'or': return evaluate(expr.left, row, fieldOf) || evaluate(expr.right, row, fieldOf);
+    case 'not': return !evaluate(expr.expr, row, fieldOf);
+    case 'null': {
+      const value = row[fieldOf(expr.field)];
+      const absent = value === undefined || value === null;
+      return expr.negate ? !absent : absent;
+    }
+    case 'starts': {
+      const value = row[fieldOf(expr.field)];
+      return typeof value === 'string' && value.startsWith(expr.prefix);
+    }
+    case 'in': {
+      const value = row[fieldOf(expr.field)];
+      const hit = expr.values.some((candidate) => (Array.isArray(value) ? value.includes(String(candidate)) : compare(value, candidate) === 0));
+      return expr.negate ? !hit : hit;
+    }
+    case 'between': {
+      const value = row[fieldOf(expr.field)];
+      const low = compare(value, expr.low);
+      const high = compare(value, expr.high);
+      return low !== null && high !== null && low >= 0 && high <= 0;
+    }
+    case 'cmp': {
+      const value = row[fieldOf(expr.field)];
+      if (Array.isArray(value)) {
+        // a keyword list matches `=` when it holds the value (Temporal's KeywordList semantics)
+        if (expr.op === '=') return value.includes(String(expr.value));
+        if (expr.op === '!=') return !value.includes(String(expr.value));
+        return false;
+      }
+      const order = compare(value, expr.value);
+      if (order === null) return expr.op === '!=' && value !== undefined && value !== null;
+      switch (expr.op) {
+        case '=': return order === 0;
+        case '!=': return order !== 0;
+        case '>': return order > 0;
+        case '>=': return order >= 0;
+        case '<': return order < 0;
+        case '<=': return order <= 0;
+        default: return false;
+      }
+    }
+  }
+}
+
+/** Does `row` satisfy the query's filter? `fieldOf` maps a name as written to the row's key (it
+ *  throws INVALID_ARGUMENT's error for a name the namespace does not define). */
+export function matchesVisibilityQuery(parsed: ParsedQuery, row: VisibilityRow, fieldOf: (name: string) => string): boolean {
+  return parsed.where === null || evaluate(parsed.where, row, fieldOf);
+}
+
+/** Every field name a query mentions, so the caller can refuse an undefined one before evaluating. */
+export function visibilityFields(parsed: ParsedQuery): string[] {
+  const out = new Set<string>();
+  const walk = (expr: Expr | null): void => {
+    if (!expr) return;
+    if ('field' in expr) { out.add(expr.field); return; }
+    if (expr.kind === 'not') { walk(expr.expr); return; }
+    walk(expr.left);
+    walk(expr.right);
+  };
+  walk(parsed.where);
+  for (const order of parsed.orderBy) out.add(order.field);
+  return [...out];
+}