@loancrate/json-selector 2.0.0 → 2.1.0

package/src/evaluate.ts

@@ -0,0 +1,229 @@
+import deepEqual from "fast-deep-equal";
+import { JsonSelector, JsonSelectorCompareOperator } from "./ast";
+import { findId, getField, getIndex, isArray, isFalseOrEmpty } from "./util";
+import { visitJsonSelector } from "./visitor";
+
+export function evaluateJsonSelector(
+  selector: JsonSelector,
+  context: unknown
+): unknown {
+  return visitJsonSelector<unknown, unknown>(
+    selector,
+    {
+      current() {
+        return context;
+      },
+      literal({ value }) {
+        return value;
+      },
+      identifier({ id }) {
+        return getField(context, id);
+      },
+      fieldAccess({ expression, field }) {
+        return getField(evaluateJsonSelector(expression, context), field);
+      },
+      indexAccess({ expression, index }) {
+        return getIndex(evaluateJsonSelector(expression, context), index);
+      },
+      idAccess({ expression, id }) {
+        return findId(evaluateJsonSelector(expression, context), id);
+      },
+      project({ expression, projection }) {
+        return project(evaluateJsonSelector(expression, context), projection);
+      },
+      filter({ expression, condition }) {
+        return filter(evaluateJsonSelector(expression, context), condition);
+      },
+      slice({ expression, start, end, step }) {
+        return slice(
+          evaluateJsonSelector(expression, context),
+          start,
+          end,
+          step
+        );
+      },
+      flatten({ expression }) {
+        return flatten(evaluateJsonSelector(expression, context));
+      },
+      not({ expression }) {
+        return isFalseOrEmpty(evaluateJsonSelector(expression, context));
+      },
+      compare({ lhs, rhs, operator }) {
+        const lv = evaluateJsonSelector(lhs, context);
+        const rv = evaluateJsonSelector(rhs, context);
+        return compare(lv, rv, operator);
+      },
+      and({ lhs, rhs }) {
+        const lv = evaluateJsonSelector(lhs, context);
+        return isFalseOrEmpty(lv) ? lv : evaluateJsonSelector(rhs, context);
+      },
+      or({ lhs, rhs }) {
+        const lv = evaluateJsonSelector(lhs, context);
+        return !isFalseOrEmpty(lv) ? lv : evaluateJsonSelector(rhs, context);
+      },
+      pipe({ lhs, rhs }) {
+        return evaluateJsonSelector(rhs, evaluateJsonSelector(lhs, context));
+      },
+    },
+    context
+  );
+}
+
+export function project(
+  value: unknown[],
+  projection: JsonSelector | undefined
+): unknown[];
+export function project(
+  value: unknown,
+  projection: JsonSelector | undefined
+): unknown[] | null;
+export function project(
+  value: unknown,
+  projection: JsonSelector | undefined
+): unknown[] | null {
+  if (!isArray(value)) {
+    return null;
+  }
+  if (!projection) {
+    return value;
+  }
+  const result = value
+    .map((e) => evaluateJsonSelector(projection, e))
+    .filter((e) => e != null);
+  return result;
+}
+
+export function filter(value: unknown[], condition: JsonSelector): unknown[];
+export function filter(
+  value: unknown,
+  condition: JsonSelector
+): unknown[] | null;
+export function filter(
+  value: unknown,
+  condition: JsonSelector
+): unknown[] | null {
+  if (!isArray(value)) {
+    return null;
+  }
+  const result = value.filter(
+    (e) => !isFalseOrEmpty(evaluateJsonSelector(condition, e))
+  );
+  return result;
+}
+
+export function slice(
+  value: unknown[],
+  start: number | undefined,
+  end?: number,
+  step?: number
+): unknown[];
+export function slice(
+  value: unknown,
+  start: number | undefined,
+  end?: number,
+  step?: number
+): unknown[] | null;
+export function slice(
+  value: unknown,
+  start: number | undefined,
+  end?: number,
+  step?: number
+): unknown[] | null {
+  if (!isArray(value)) {
+    return null;
+  }
+  ({ start, end, step } = normalizeSlice(value.length, start, end, step));
+  const collected: unknown[] = [];
+  if (step > 0) {
+    for (let i = start; i < end; i += step) {
+      collected.push(value[i]);
+    }
+  } else {
+    for (let i = start; i > end; i += step) {
+      collected.push(value[i]);
+    }
+  }
+  return collected;
+}
+
+export function normalizeSlice(
+  length: number,
+  start?: number,
+  end?: number,
+  step?: number
+): { start: number; end: number; step: number } {
+  if (step == null) {
+    step = 1;
+  } else if (step === 0) {
+    throw new Error("Invalid slice: step cannot be 0");
+  }
+  if (start == null) {
+    start = step < 0 ? length - 1 : 0;
+  } else {
+    start = limitSlice(start, step, length);
+  }
+  if (end == null) {
+    end = step < 0 ? -1 : length;
+  } else {
+    end = limitSlice(end, step, length);
+  }
+  return { start, end, step };
+}
+
+function limitSlice(value: number, step: number, length: number): number {
+  if (value < 0) {
+    value += length;
+    if (value < 0) {
+      value = step < 0 ? -1 : 0;
+    }
+  } else if (value >= length) {
+    value = step < 0 ? length - 1 : length;
+  }
+  return value;
+}
+
+export function flatten(value: unknown[]): unknown[];
+export function flatten(value: unknown): unknown[] | null;
+export function flatten(value: unknown): unknown[] | null {
+  return isArray(value) ? value.flat() : null;
+}
+
+export function compare(
+  lv: number,
+  rv: number,
+  operator: JsonSelectorCompareOperator
+): boolean;
+export function compare(
+  lv: unknown,
+  rv: unknown,
+  operator: JsonSelectorCompareOperator
+): boolean | null;
+export function compare(
+  lv: unknown,
+  rv: unknown,
+  operator: JsonSelectorCompareOperator
+): boolean | null {
+  switch (operator) {
+    case "==":
+      return deepEqual(lv, rv);
+    case "!=":
+      return !deepEqual(lv, rv);
+    case "<":
+    case "<=":
+    case ">":
+    case ">=":
+      if (typeof lv === "number" && typeof rv === "number") {
+        switch (operator) {
+          case "<":
+            return lv < rv;
+          case "<=":
+            return lv <= rv;
+          case ">":
+            return lv > rv;
+          case ">=":
+            return lv >= rv;
+        }
+      }
+  }
+  return null;
+}

package/src/format.ts

@@ -0,0 +1,141 @@
+import { JsonSelector, JsonSelectorNodeType } from "./ast";
+import { formatIdentifier, formatLiteral, formatRawString } from "./util";
+import { visitJsonSelector } from "./visitor";
+
+const PRECEDENCE_ACCESS = 1;
+const PRECEDENCE_NOT = 2;
+const PRECEDENCE_COMPARE = 3;
+const PRECEDENCE_AND = 4;
+const PRECEDENCE_OR = 5;
+const PRECEDENCE_PIPE = 6;
+const PRECEDENCE_MAX = 7;
+
+const operatorPrecedence: { [type in JsonSelectorNodeType]?: number } = {
+  fieldAccess: PRECEDENCE_ACCESS,
+  idAccess: PRECEDENCE_ACCESS,
+  indexAccess: PRECEDENCE_ACCESS,
+  project: PRECEDENCE_ACCESS,
+  filter: PRECEDENCE_ACCESS,
+  slice: PRECEDENCE_ACCESS,
+  flatten: PRECEDENCE_ACCESS,
+  not: PRECEDENCE_NOT,
+  compare: PRECEDENCE_COMPARE,
+  and: PRECEDENCE_AND,
+  or: PRECEDENCE_OR,
+  pipe: PRECEDENCE_PIPE,
+};
+
+function formatSubexpression(
+  expr: JsonSelector,
+  options: Partial<FormatJsonSelectorOptions>,
+  precedence: number
+): string {
+  // Ensure @ is only used as a bare expression
+  if (!options.currentImplied) {
+    options = { ...options, currentImplied: true };
+  }
+  let result = formatJsonSelector(expr, options);
+  const subPrecedence = operatorPrecedence[expr.type];
+  if (subPrecedence != null && subPrecedence > precedence) {
+    result = `(${result})`;
+  }
+  return result;
+}
+
+const projectionNodeTypes = new Set<JsonSelectorNodeType>([
+  "project",
+  "filter",
+  "slice",
+  "flatten",
+]);
+
+export interface FormatJsonSelectorOptions {
+  currentImplied: boolean;
+}
+
+export function formatJsonSelector(
+  selector: JsonSelector,
+  options: Partial<FormatJsonSelectorOptions> = {}
+): string {
+  return visitJsonSelector<string, undefined>(
+    selector,
+    {
+      current() {
+        return !options.currentImplied ? "@" : "";
+      },
+      literal({ value }) {
+        return formatLiteral(value);
+      },
+      identifier({ id }) {
+        return formatIdentifier(id);
+      },
+      fieldAccess({ expression, field }) {
+        const lv = formatSubexpression(expression, options, PRECEDENCE_ACCESS);
+        return `${lv}.${formatIdentifier(field)}`;
+      },
+      indexAccess({ expression, index }) {
+        const lv = formatSubexpression(expression, options, PRECEDENCE_ACCESS);
+        return `${lv}[${index}]`;
+      },
+      idAccess({ expression, id }) {
+        const lv = formatSubexpression(expression, options, PRECEDENCE_ACCESS);
+        return `${lv}[${formatRawString(id)}]`;
+      },
+      project({ expression, projection }) {
+        let result = formatSubexpression(
+          expression,
+          options,
+          PRECEDENCE_ACCESS
+        );
+        // Wildcard operator is only needed if expression is not already a projection
+        if (!projectionNodeTypes.has(expression.type)) {
+          result += "[*]";
+        }
+        if (projection) {
+          result += formatSubexpression(projection, options, PRECEDENCE_MAX);
+        }
+        return result;
+      },
+      filter({ expression, condition }) {
+        const lv = formatSubexpression(expression, options, PRECEDENCE_ACCESS);
+        const rv = formatSubexpression(condition, options, PRECEDENCE_MAX);
+        return `${lv}[?${rv}]`;
+      },
+      slice({ expression, start, end, step }) {
+        const lv = formatSubexpression(expression, options, PRECEDENCE_ACCESS);
+        const rv = `${start ?? ""}:${end ?? ""}${
+          step != null ? `:${step}` : ""
+        }`;
+        return `${lv}[${rv}]`;
+      },
+      flatten({ expression }) {
+        const lv = formatSubexpression(expression, options, PRECEDENCE_ACCESS);
+        return `${lv}[]`;
+      },
+      not({ expression }) {
+        return `!${formatSubexpression(expression, options, PRECEDENCE_NOT)}`;
+      },
+      compare({ lhs, operator, rhs }) {
+        const lv = formatSubexpression(lhs, options, PRECEDENCE_COMPARE);
+        const rv = formatSubexpression(rhs, options, PRECEDENCE_COMPARE - 1);
+        return `${lv} ${operator} ${rv}`;
+      },
+      and({ lhs, rhs }) {
+        const lv = formatSubexpression(lhs, options, PRECEDENCE_AND);
+        const rv = formatSubexpression(rhs, options, PRECEDENCE_AND - 1);
+        return `${lv} && ${rv}`;
+      },
+      or({ lhs, rhs }) {
+        const lv = formatSubexpression(lhs, options, PRECEDENCE_OR);
+        const rv = formatSubexpression(rhs, options, PRECEDENCE_OR - 1);
+        return `${lv} || ${rv}`;
+      },
+      pipe({ lhs, rhs }) {
+        const lv = formatSubexpression(lhs, options, PRECEDENCE_PIPE);
+        const rv = formatSubexpression(rhs, options, PRECEDENCE_PIPE - 1);
+        return `${lv} | ${rv}`;
+      },
+    },
+    undefined
+  );
+}

package/src/get.ts

@@ -0,0 +1,9 @@
+import { accessWithJsonSelector } from "./access";
+import { JsonSelector } from "./ast";
+
+export function getWithJsonSelector(
+  selector: JsonSelector,
+  context: unknown
+): unknown {
+  return accessWithJsonSelector(selector, context).get();
+}

package/src/grammar.pegjs

@@ -0,0 +1,217 @@
+// Based on https://jmespath.org/specification.html#grammar
+
+{
+  function binaryExpression(type, head, tail) {
+    return tail.reduce((lhs, rhs) => (
+      {
+        type,
+        lhs,
+        rhs
+      }
+    ), head);
+  }
+
+  function reduceProjection(lhs, rhs) {
+    return rhs.reduce((result, fn) => fn(result), lhs);
+  }
+
+  function maybeProject(expression, pfns) {
+    return !pfns.length ? expression : (
+      {
+        type: "project",
+        expression: unwrapTrivialProjection(expression),
+        projection: pfns.reduce((result, pfn) => pfn(result), { type: "current" })
+      });
+  }
+
+  function unwrapTrivialProjection(expression) {
+    const { type, projection } = expression;
+    return type === "project" && (!projection || projection.type === "current") ? expression.expression : expression;
+  }
+}
+
+selector = ws @pipe_expression ws
+
+pipe_expression = head:or_expression tail:(ws "|" ws @or_expression)*
+{ return binaryExpression("pipe", head, tail); }
+
+or_expression = head:and_expression tail:(ws "||" ws @and_expression)*
+{ return binaryExpression("or", head, tail); }
+
+and_expression = head:compare_expression tail:(ws "&&" ws @compare_expression)*
+{ return binaryExpression("and", head, tail); }
+
+compare_expression = head:not_expression tail:(ws @("<=" / ">=" / "<" / ">" / "==" / "!=") ws @not_expression)*
+{
+  return tail.reduce((result, [operator, rhs]) => (
+    {
+      type: "compare",
+      operator,
+      lhs: result,
+      rhs
+    }
+  ), head);
+}
+
+not_expression =
+    "!" expression:not_expression { return { type: "not", expression }; }
+  / flatten_expression
+
+flatten_expression = lhs:flatten_lhs rhs:flatten_rhs* { return reduceProjection(lhs, rhs); }
+
+flatten_lhs =
+    flatten:flatten { return flatten({ type: "current" }); }
+  / filter_expression
+
+flatten_rhs =
+    flatten:flatten pfns:filter_rhs* { return (expression) => maybeProject(flatten(expression), pfns); }
+  / filter_rhs
+
+flatten = ws "[]" { return (expression) => ({ type: "flatten", expression }); }
+
+filter_expression = lhs:filter_lhs rhs:filter_rhs* { return reduceProjection(lhs, rhs); }
+
+filter_lhs =
+    filter:filter { return filter({ type: "current" }); }
+  / projection_expression
+
+filter_rhs = 
+    filter:filter pfns:filter_rhs* { return (expression) => maybeProject(filter(expression), pfns); }
+  / projection_rhs
+  / dot_rhs
+
+filter = ws "[?" condition:selector "]" { return (expression) => ({ type: "filter", expression, condition }); }
+
+projection_expression = lhs:projection_lhs rhs:projection_rhs* { return reduceProjection(lhs, rhs); }
+
+projection_lhs =
+    projection:projection { return projection({ type: "current" }); }
+  / index_expression
+
+projection_rhs =
+    projection:projection pfns:filter_rhs* { return (expression) => maybeProject(projection(expression), pfns); }
+  / index_rhs
+
+projection =
+    ws "[" ws "*" ws "]" { return (expression) => ({ type: "project", expression, projection: { type: "current" } }); }
+  / ws "[" ws @slice ws "]"
+
+slice = start:number? ws ":" ws end:number? ws ":"? ws step:number?
+{ return (expression) => ({ type: "slice", expression, start, end, step }); }
+
+index_expression = lhs:index_lhs rhs:index_rhs* { return reduceProjection(lhs, rhs); }
+
+index_lhs =
+    index:index_rhs { return index({ type: "current" }); }
+  / member_expression
+
+index_rhs =
+    ws "[" ws index:number ws "]" { return (expression) => ({ type: "indexAccess", expression, index }); }
+  / ws "[" ws id:raw_string ws "]" { return (expression) => ({ type: "idAccess", expression, id }); }
+
+dot_rhs = ws "." ws field:identifier
+{ return (expression) => ({ type: "fieldAccess", expression, field }); }
+
+member_expression = lhs:primary_expression rhs:dot_rhs* { return reduceProjection(lhs, rhs); }
+
+primary_expression =
+    id:identifier { return { type: "identifier", id }; }
+  / "@" { return { type: "current" }; }
+  / literal
+  / value:raw_string { return { type: "literal", value }; }
+  / "(" @selector ")"
+
+literal = "`" ws value:(json_value / unquoted_json_string) ws "`"
+{ return { type: "literal", value }; }
+
+// Identifiers and double-quoted strings
+
+identifier = unquoted_string / quoted_string
+
+unquoted_string = head:[a-z_]i tail:[0-9a-z_]i* { return head + tail.join(""); }
+
+quoted_string = '"' chars:char* '"' { return chars.join(""); }
+
+char = unescaped_char / escaped_char
+
+unescaped_char = [^\0-\x1F"\\]
+
+escaped_char = "\\" @(
+      '"'
+    / "\\"
+    / "/"
+    / "b" { return "\b"; }
+    / "f" { return "\f"; }
+    / "n" { return "\n"; }
+    / "r" { return "\r"; }
+    / "t" { return "\t"; }
+    / "u" digits:$(HEXDIG HEXDIG HEXDIG HEXDIG) {
+        return String.fromCharCode(parseInt(digits, 16));
+      }
+  )
+
+HEXDIG = [0-9a-f]i
+
+// Raw strings (single-quoted)
+
+raw_string = "'" chars:raw_string_char* "'" { return chars.join(""); }
+
+raw_string_char = unescaped_raw_string_char / preserved_escape / raw_string_escape
+
+// Despite what the specification says, JMESPath implementations accept control characters
+unescaped_raw_string_char = [^'\\]
+
+preserved_escape = "\\" [^'] { return text(); }
+
+raw_string_escape = "\\" @"'"
+
+// Numbers
+
+number = int { return parseInt(text()); }
+
+int = "-"? ("0" / ([1-9] [0-9]*))
+
+// JSON
+
+json_value =
+    "null" { return null; }
+  / "false" { return false; }
+  / "true" { return true; }
+  / json_number
+  / json_string
+  / json_object
+  / json_array
+
+json_number = int ("." [0-9]+)? ([eE] [+-]? [0-9]+)? { return parseFloat(text()); }
+
+json_string = '"' @unquoted_json_string '"'
+
+unquoted_json_string = chars:(unescaped_literal / escaped_literal)* { return chars.join(""); }
+
+unescaped_literal = [^\0-\x1F"\\`]
+
+escaped_literal = escaped_char / "\\" @"`"
+
+json_object =
+  "{" ws members:(
+    head:json_member
+    tail:(ws "," ws @json_member)*
+    { return [head].concat(tail); }
+  )?
+  ws "}"
+  { return Object.fromEntries(members ?? []); }
+
+json_member = name:json_string ws ":" ws value:json_value
+{ return [name, value]; }
+
+json_array =
+  "[" ws values:(
+    head:json_value
+    tail:(ws "," ws @json_value)*
+    { return [head].concat(tail); }
+  )? ws "]"
+  { return values ?? []; }
+
+// Whitespace
+
+ws "whitespace" = [ \t\n\r]*

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./access";
+export * from "./ast";
+export { evaluateJsonSelector } from "./evaluate";
+export * from "./format";
+export * from "./get";
+export * from "./parse";
+export * from "./set";

package/src/parse.ts

@@ -0,0 +1,7 @@
+import { JsonSelector } from "./ast";
+import { parse } from "./__generated__/parser";
+
+export function parseJsonSelector(selectorExpression: string): JsonSelector {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  return parse(selectorExpression);
+}

package/src/set.ts

@@ -0,0 +1,13 @@
+import { accessWithJsonSelector } from "./access";
+import { JsonSelector } from "./ast";
+
+export function setWithJsonSelector(
+  selector: JsonSelector,
+  context: unknown,
+  value: unknown
+): unknown {
+  const accessor = accessWithJsonSelector(selector, context);
+  const oldValue = accessor.get();
+  accessor.set(value);
+  return oldValue;
+}

package/src/util.ts

@@ -0,0 +1,70 @@
+import { JsonValue } from "type-fest";
+
+export function isArray(value: unknown): value is unknown[] {
+  return Array.isArray(value);
+}
+
+export function asArray(value: unknown): unknown[] {
+  return value == null ? [] : isArray(value) ? value : [value];
+}
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value != null;
+}
+
+export function isFalseOrEmpty(value: unknown): boolean {
+  return (
+    value == null ||
+    value === false ||
+    value === "" ||
+    (isArray(value) && value.length === 0) ||
+    (isObject(value) && !hasOwnProperties(value))
+  );
+}
+
+function hasOwnProperties(value: Record<string, unknown>): boolean {
+  for (const key in value) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function getField(obj: unknown, name: string): unknown {
+  return isObject(obj) ? obj[name] ?? null : null;
+}
+
+export function getIndex(obj: unknown, index: number): unknown {
+  return isArray(obj)
+    ? obj[index < 0 ? obj.length + index : index] ?? null
+    : null;
+}
+
+export function findId(obj: unknown, id: string | number): unknown {
+  return isArray(obj)
+    ? obj.find((e) => isObject(e) && e.id === id) ?? null
+    : null;
+}
+
+export function findIdIndex(arr: unknown[], id: string | number): number {
+  return arr.findIndex((e) => isObject(e) && e.id === id);
+}
+
+export function formatLiteral(value: JsonValue): string {
+  return "`" + JSON.stringify(value).replace(/`/g, "\\`") + "`";
+}
+
+export function isValidIdentifier(s: string): boolean {
+  return /^[a-z_][0-9a-z_]*$/i.test(s);
+}
+
+export function formatIdentifier(s: string): string {
+  return isValidIdentifier(s) ? s : JSON.stringify(s);
+}
+
+export function formatRawString(s: string): string {
+  // https://jmespath.org/specification.html#raw-string-literals
+  // eslint-disable-next-line no-control-regex
+  return `'${s.replace(/[\0-\x1F]/g, "").replace(/['\\]/g, (c) => `\\${c}`)}'`;
+}