@emuanalytics/flow-rdf-core 4.0.4 → 4.0.5

package/dist/lib/expressions/expression-parser.mjs

@@ -0,0 +1,198 @@
+import P from 'parsimmon';
+import { PREFIX, BINARY_RIGHT, BINARY_LEFT, TERNARY_RIGHT } from './parser-helpers.mjs';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+class ExpressionParser {
+  constructor() {
+    __publicField(this, "language");
+    this.language = this.createLanguage();
+  }
+  /**
+   * Parse an expression
+   *
+   * @param expr Expression to parse
+   */
+  parseExpression(expr) {
+    return this.language.Expr.parse(expr);
+  }
+  /**
+   * Parse a complete assignment program of the form:
+   * a: expr1;
+   * b: expr2;
+   *
+   * @param program Program to parse
+   */
+  parseProgram(program) {
+    return this.language.ProgramOrEmpty.parse(program);
+  }
+  createLanguage() {
+    const operatorTable = [
+      { type: PREFIX, ops: this.operators({ "-": "-", "!": "!" }) },
+      { type: BINARY_RIGHT, ops: this.operators({ "^": "**" }) },
+      { type: BINARY_LEFT, ops: this.operators({ "*": "*", "/": "/", "%": "%" }) },
+      { type: BINARY_LEFT, ops: this.operators({ "+": "+", "-": "-" }) },
+      { type: BINARY_LEFT, ops: this.operators({ ">=": ">=", "<=": "<=" }) },
+      { type: BINARY_LEFT, ops: this.operators({ "<": "<", ">": ">" }) },
+      {
+        type: BINARY_LEFT,
+        ops: this.operators({ regexi: "~*", equali: "=*", "==": "==", "!=": "!=", "~": "~" })
+      },
+      { type: BINARY_LEFT, ops: this.operators({ all: "&&" }) },
+      { type: BINARY_LEFT, ops: this.operators({ any: "||" }) },
+      { type: TERNARY_RIGHT, ops: this.operators({ case: "?" }) }
+    ];
+    return P.createLanguage({
+      Whitespace: () => P.regexp(/[ \n]*/).desc("whitespace"),
+      NotNewline: () => P.regexp(/[^\n]*/).desc("non-newline"),
+      LineComment: (r) => r.NotNewline.wrap(P.string("//"), P.alt(P.string("\n"), P.eof)),
+      BlockComment: () => P.regexp(/\/\*[\s\S]*?\*\//),
+      Comment: (r) => P.alt(r.LineComment, r.BlockComment).desc("comment"),
+      End: () => P.alt(P.string(";"), P.eof),
+      _: (r) => r.Comment.sepBy(r.Whitespace).trim(r.Whitespace),
+      Integer: () => {
+        return P.regexp(/-?[0-9]+/).map(Number);
+      },
+      Decimal: () => {
+        return P.regexp(/-?[0-9]+\.[0-9]+/).map(Number);
+      },
+      Number: (r) => {
+        return P.alt(r.Decimal, r.Integer).desc("number");
+      },
+      Boolean: () => {
+        return P.alt(P.string("true"), P.string("false")).map((val) => val === "true").desc("boolean");
+      },
+      Null: () => {
+        return P.string("null").result(null).desc("null");
+      },
+      DoubleQuoteString: () => {
+        return P.regexp(/"((?:\\.|.)*?)"/, 1).desc("string");
+      },
+      SingleQuoteString: () => {
+        return P.regexp(/'((?:\\.|.)*?)'/, 1).desc("string");
+      },
+      UnquotedString: () => {
+        return P.regexp(/[a-zA-Z_][a-zA-Z0-9_-]*/).desc("string");
+      },
+      HexColor: () => {
+        return P.regexp(/#(?:[0-9a-f]{3}){1,2}/i).desc("hex color");
+      },
+      String: (r) => {
+        return P.alt(r.SingleQuoteString, r.DoubleQuoteString, r.HexColor, r.UnquotedString).map(
+          (s) => s.replace(/\\n/gm, "\n")
+        );
+      },
+      Symbol: () => {
+        return P.regexp(/[a-zA-Z_][a-zA-Z0-9_-]*/).desc("symbol");
+      },
+      PartialSymbol: () => {
+        return P.regexp(/[a-zA-Z0-9_-]+/).desc("symbol");
+      },
+      Feature: (r) => {
+        return P.seqMap(
+          P.string("@"),
+          r.PartialSymbol.sepBy(P.string(".")),
+          (_feat, symbols) => ["get"].concat(symbols)
+        );
+      },
+      FeatureState: (r) => {
+        return P.seqMap(
+          P.string("@@"),
+          r.PartialSymbol.sepBy(P.string(".")),
+          (_feat, symbols) => this.expandFeatureState(symbols)
+        );
+      },
+      Array: (r) => P.string("[").trim(r._).then(r.Value.trim(r._).sepBy(P.string(","))).skip(P.string("]")),
+      State: (r) => {
+        return P.seqMap(
+          P.string("$"),
+          r.PartialSymbol.sepBy(P.string(".")),
+          (_state, symbols) => ["state"].concat(symbols)
+        );
+      },
+      Paren: (r) => {
+        return P.seqMap(P.string("("), r.Expr.trim(r._), P.string(")"), (_lb, expr, _rb) => expr);
+      },
+      Func: (r) => {
+        return P.seqMap(
+          r.Symbol.trim(r._),
+          P.string("("),
+          r.Expr.trim(r._).sepBy(P.string(",")),
+          P.string(")"),
+          (func, _lb, args, _rb) => [func, ...args]
+        );
+      },
+      Value: (r) => {
+        return P.alt(
+          r.Paren,
+          r.Array,
+          r.Func,
+          r.Boolean,
+          r.Null,
+          r.Number,
+          r.String,
+          r.FeatureState,
+          r.Feature,
+          r.State
+        );
+      },
+      Expr: (r) => {
+        return this.tableParser(operatorTable, r.Value);
+      },
+      PropertyName: () => {
+        return P.regexp(/[a-zA-Z_-][a-zA-Z0-9_-]*/).desc("symbol");
+      },
+      Assignment: (r) => {
+        return P.seqMap(
+          r.PropertyName,
+          P.string(":").trim(r._),
+          r.Expr.trim(r._).node("expr"),
+          r.End,
+          (key, _colon, node) => [key, { expr: node.value, start: node.start, end: node.end }]
+        );
+      },
+      Program: (r) => {
+        return r.Assignment.trim(r._).many().map((statements) => {
+          return statements.filter((s) => s !== "").reduce((acc, s) => {
+            acc[s[0]] = s[1];
+            return acc;
+          }, {});
+        });
+      },
+      EmptyProgram: (r) => {
+        return P.seqMap(r._, P.eof, () => null);
+      },
+      ProgramOrEmpty: (r) => {
+        return P.alt(r.EmptyProgram, r.Program);
+      }
+    });
+  }
+  /**
+   * Helper function to create a parser that parsers a set of operators at the same precedence level
+   *
+   * @param ops Operator table
+   */
+  operators(ops) {
+    const keys = Object.keys(ops);
+    const ps = keys.map((k) => P.string(ops[k]).trim(P.optWhitespace).result(k));
+    return P.alt.apply(null, ps);
+  }
+  /**
+   * Helper function to create a table-driver operator parser
+   *
+   */
+  tableParser(operatorTable, valueParser) {
+    return operatorTable.reduce((acc, level) => level.type(level.ops, acc), valueParser);
+  }
+  expandFeatureState(symbols) {
+    let expandedFeatureState = ["feature-state", symbols.shift()];
+    symbols.forEach((s) => expandedFeatureState = ["get", s, expandedFeatureState]);
+    return expandedFeatureState;
+  }
+}
+
+export { ExpressionParser };

package/dist/lib/expressions/functions/from-palette.mjs

@@ -0,0 +1,75 @@
+import colorbrewer from 'colorbrewer';
+import { isString, isArray } from '../../utils/type-checks.mjs';
+import { FlowCoreExpressionError } from '../../errors/flow-expression-error.mjs';
+
+const palettes = {};
+function registerColorBrewerPalettes() {
+  Object.keys(colorbrewer).filter((key) => key !== "schemeGroups").forEach(
+    (key) => palettes[key.toLowerCase()] = {
+      id: key,
+      colors: colorbrewer[key][5]
+    }
+  );
+}
+function fromPalette(expr, parentExpression) {
+  const paletteIdOrArray = expr[1];
+  const property = expr[2];
+  let colorStops = expr.slice(3);
+  let palette;
+  if (isString(paletteIdOrArray)) {
+    palette = palettes[paletteIdOrArray.toLowerCase()]?.colors || palettes["Greys"].colors;
+  } else if (isArray(paletteIdOrArray) && paletteIdOrArray[0] === "literal") {
+    palette = paletteIdOrArray[1];
+  } else {
+    throw new FlowCoreExpressionError(parentExpression.expression, "evaluationError", [
+      "from-palette requires palette id as string or custom palette array"
+    ]);
+  }
+  const numPaletteEntries = palette.length;
+  let reversePalette = false;
+  if (numPaletteEntries < 5) {
+    throw new FlowCoreExpressionError(parentExpression.expression, "evaluationError", [
+      "custom palette requires at least 5 color entries"
+    ]);
+  }
+  switch (colorStops.length) {
+    case 2:
+      break;
+    case 3:
+      reversePalette = !!colorStops[2];
+      colorStops = colorStops.slice(0, 2);
+      break;
+    case numPaletteEntries:
+      break;
+    case numPaletteEntries + 1:
+      reversePalette = !!colorStops[numPaletteEntries];
+      colorStops = colorStops.slice(0, numPaletteEntries);
+      break;
+    default:
+      throw new FlowCoreExpressionError(parentExpression.expression, "evaluationError", [
+        "incorrect color stop arguments"
+      ]);
+  }
+  if (colorStops.length === 2) {
+    const min = colorStops[0];
+    const max = colorStops[1];
+    colorStops = [];
+    const step = (max - min) / (numPaletteEntries - 1);
+    for (let i = 0; i < numPaletteEntries; i++) {
+      colorStops.push(min + i * step);
+    }
+  }
+  expr = ["interpolate-lab", ["linear"], property];
+  for (let i = 0; i < colorStops.length; i++) {
+    expr.push(colorStops[i]);
+    expr.push(reversePalette ? palette[colorStops.length - i - 1] : palette[i]);
+  }
+  return expr;
+}
+const customFromPaletteFn = {
+  name: "from-palette",
+  initialize: registerColorBrewerPalettes,
+  fn: fromPalette
+};
+
+export { customFromPaletteFn as default };

package/dist/lib/expressions/functions/regex.mjs

@@ -0,0 +1,25 @@
+function regexFunction(operator, caseSensitive = true) {
+  return (expr, _) => {
+    expr[0] = operator;
+    expr.push(["collator", { "case-sensitive": caseSensitive }]);
+    return expr;
+  };
+}
+const equal = {
+  name: "equal",
+  fn: regexFunction("==", true)
+};
+const equali = {
+  name: "iequal",
+  fn: regexFunction("==", false)
+};
+const regex = {
+  name: "regex",
+  fn: regexFunction("~", true)
+};
+const regexi = {
+  name: "regexi",
+  fn: regexFunction("~", false)
+};
+
+export { equal, equali, regex, regexi };

package/dist/lib/expressions/functions/state.mjs

@@ -0,0 +1,25 @@
+import { isNil } from '../../utils/type-checks.mjs';
+
+function stateCustomFunction(expr, parentExpression) {
+  if (!parentExpression.store) {
+    console.warn(
+      `The reactive expression '${parentExpression.expression}' references state properties but is not bound to a state store. The expression cannot be evaluated - returning null.`
+    );
+    return null;
+  }
+  const path = expr.slice(1).join(".");
+  const val = parentExpression.store.get(path);
+  if (isNil(val)) {
+    return null;
+  } else if (typeof val === "object") {
+    return ["literal", val];
+  } else {
+    return val;
+  }
+}
+const customStateFn = {
+  name: "state",
+  fn: stateCustomFunction
+};
+
+export { customStateFn as default };

package/dist/lib/expressions/parser-helpers.mjs

@@ -0,0 +1,37 @@
+import P from 'parsimmon';
+
+function PREFIX(operatorsParser, nextParser) {
+  const parser = P.lazy(() => {
+    return P.seq(operatorsParser, parser).or(nextParser);
+  });
+  return parser;
+}
+function BINARY_RIGHT(operatorsParser, nextParser) {
+  const parser = P.lazy(() => nextParser.chain((next) => P.seq(operatorsParser, P.of(next), parser).or(P.of(next))));
+  return parser;
+}
+function TERNARY_RIGHT(operatorsParser, nextParser) {
+  const parser = P.lazy(
+    () => nextParser.chain(
+      (next) => P.seqMap(
+        operatorsParser,
+        P.of(next),
+        parser,
+        P.string(":").trim(P.optWhitespace),
+        parser,
+        (op, cond, val1, _colon, val2) => [op, ["to-boolean", cond], val1, val2]
+      ).or(P.of(next))
+    )
+  );
+  return parser;
+}
+function BINARY_LEFT(operatorsParser, nextParser) {
+  return P.seqMap(nextParser, P.seq(operatorsParser, nextParser).many(), (first, rest) => {
+    return rest.reduce((acc, ch) => {
+      const [op, another] = ch;
+      return [op, acc, another];
+    }, first);
+  });
+}
+
+export { BINARY_LEFT, BINARY_RIGHT, PREFIX, TERNARY_RIGHT };

package/dist/lib/expressions/reactive-expression.mjs

@@ -0,0 +1,253 @@
+import * as maplibreSpec from '@emuanalytics/maplibre-gl-style-spec';
+import { makeObservable, observable, computed, action } from 'mobx';
+import { toStream } from 'mobx-utils';
+import { FlowCoreExpressionError } from '../errors/flow-expression-error.mjs';
+import { isDefined, isString } from '../utils/type-checks.mjs';
+import { ExpressionParser } from './expression-parser.mjs';
+import customFromPaletteFn from './functions/from-palette.mjs';
+import { regex, regexi, equal, equali } from './functions/regex.mjs';
+import customStateFn from './functions/state.mjs';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+const _ReactiveExpression = class _ReactiveExpression {
+  /**
+   * Constructs a new `ReactiveExpression`.
+   *
+   * @example
+   * ```js
+   * const ex = new ReactiveExpression('1 + 2');
+   * console.log(ex.value); // 3
+   * ```
+   *
+   * @param expression - the string representation of the expression
+   * @param parsedExpression - Used internally to bypass parsing when evaluating a program.
+   */
+  constructor(expression, parsedExpression) {
+    __publicField(this, "_expression", "");
+    __publicField(this, "parsedResult");
+    __publicField(this, "_store", null);
+    makeObservable(
+      this,
+      {
+        _store: observable.ref,
+        maplibreExpression: computed,
+        value: computed,
+        bindState: action
+      },
+      { name: this.formatName(expression) }
+    );
+    this._expression = expression;
+    if (isDefined(parsedExpression)) {
+      this.parsedResult = {
+        status: true,
+        value: parsedExpression
+      };
+    } else {
+      this.parsedResult = _ReactiveExpression.parser.parseExpression(expression);
+    }
+  }
+  /**
+   * Returns `true` if the specified custom function has been registered.
+   *
+   * @param fn - The custom function name
+   */
+  static hasCustomFunction(fn) {
+    return !!this.customFunctions[fn];
+  }
+  /**
+   * Register a custom function to be used in reactive expressions.
+   *
+   * @param fn - The custom function to register
+   */
+  static registerCustomFunction(fn) {
+    if (fn.initialize)
+      fn.initialize();
+    this.customFunctions[fn.name] = fn;
+  }
+  /**
+   * Parses a program string into a map of properties and their associated {@link ReactiveExpression}.
+   *
+   * The program string should be a series of property/expression pairs separated by semicolons as follows:
+   *
+   * ```js
+   * const program = `
+   *  prop1: 1 + 2;
+   *  prop2: 'a string';
+   *  prop3: $stateProp * 3;
+   * `;
+   *
+   * const parsedProgram = ReactiveExpression.parseProgram(program);
+   * // {
+   * //   prop1: ReactiveExpression,
+   * //   prop2: ReactiveExpression,
+   * //   prop3: ReactiveExpression
+   * // }
+   *
+   * ```
+   *
+   * @param program - The program to parse
+   * @returns A map of property names and their associated expressions.
+   */
+  static parseProgram(program) {
+    const parsedProgram = this.parser.parseProgram(program);
+    if (isString(program) && program.length === 0) {
+      return {};
+    }
+    if (parsedProgram.status) {
+      const keys = Object.keys(parsedProgram.value);
+      const expressions = keys.reduce((accum, key) => {
+        const expr = parsedProgram.value[key];
+        const expressionString = program.slice(expr.start.offset, expr.end.offset);
+        accum[key] = new _ReactiveExpression(expressionString, expr.expr);
+        return accum;
+      }, {});
+      return expressions;
+    } else {
+      throw new FlowCoreExpressionError(program, "parseError", [
+        `expected ${parsedProgram.expected.join(" ")} at line ${parsedProgram.index.line}, column ${parsedProgram.index.column}]`
+      ]);
+    }
+  }
+  /**
+   * Generates the MapLibre-compatible representation of this expression.
+   *
+   * This is used internally when creating MapLibre style specifications
+   * from Flo.w RDF {@link MapLayer} styles.
+   *
+   * This getter is a reactive `computed` and will re-evaluate within a
+   * reactive context when the expression value changes.
+   *
+   * @computed
+   *
+   * @returns The MapLibre-compatible representation of this expression
+   */
+  get maplibreExpression() {
+    if (this.isParseError(this.parsedResult)) {
+      throw this.parseError;
+    }
+    return this.expandCustomFunctions(this.parsedResult.value);
+  }
+  /**
+   * Evaluates the expression and returns the result.
+   *
+   * This getter is a reactive `computed` and will re-evaluate within a
+   * reactive context when the expression value changes.
+   *
+   * @example
+   * ```js
+   * const ex = new ReactiveExpression('1 + 2');
+   * console.log(ex.value); // 3
+   * ```
+   *
+   * @computed
+   *
+   * @returns - The result of evaluating the expression
+   */
+  get value() {
+    return this.evaluateExpression();
+  }
+  /**
+   * Returns  details of parsing errors if the expression could not be parsed.
+   */
+  get parseError() {
+    if (this.isParseError(this.parsedResult)) {
+      return new FlowCoreExpressionError(this._expression, "parseError", [
+        `index: ${this.parsedResult.index.offset}`,
+        `expected: ${this.parsedResult.expected.join(" ")}`
+      ]);
+    }
+    return null;
+  }
+  /**
+   * Returns the original expression string passed to the constructor.
+   */
+  get expression() {
+    return this._expression;
+  }
+  /**
+   * Returns the state store bound to the expression.
+   */
+  get store() {
+    return this._store;
+  }
+  /**
+   * Binds a {@link StateStore} to the expression. The state store is used to resolve
+   * state variables in the expression.
+   *
+   * Note: If no state store is bound, the expression will not be able to resolve
+   * state variables and will return `null` when evaluated. A console warning will
+   * be logged.
+   *
+   * @param store {@link StateStore} to bind to the expression
+   * @returns
+   */
+  bindState(store) {
+    this._store = store;
+    return this;
+  }
+  /**
+   * Returns a subscribable stream, which produces the value of the expression
+   * whenever a reactive update causes the expression to re-evaluate.
+   *
+   * @example
+   * ```js
+   * const ex = new ReactiveExpression('$val * 2');
+   * const subscription = ex.toStream().subscribe((value) => console.log(value));
+   * ...
+   * subscription.unsubscribe();
+   * ```
+   *
+   * @param fireImmediately - If `true`, the stream will fire immediately with the current value.
+   * If `false` the stream will only fire when the value changes.
+   *
+   * @returns A subscribable stream of the expression value
+   */
+  toStream(fireImmediately = true) {
+    return toStream(() => this.value, fireImmediately);
+  }
+  evaluateExpression() {
+    const { result, value } = maplibreSpec.expression.createExpression(this.maplibreExpression);
+    if (result === "success") {
+      return value.evaluate({ zoom: 0 });
+    }
+    throw new FlowCoreExpressionError(
+      this.expression,
+      "evaluationError",
+      value.map((value2) => value2.message)
+    );
+  }
+  expandCustomFunctions(expr) {
+    if (this.isFunctionExpression(expr)) {
+      const func = expr[0];
+      const args = expr.slice(1).map((arg) => this.expandCustomFunctions(arg));
+      expr = [func, ...args];
+      return _ReactiveExpression.hasCustomFunction(func) ? _ReactiveExpression.customFunctions[func].fn(expr, this) : expr;
+    }
+    return expr;
+  }
+  isParseError(val) {
+    return !val.status;
+  }
+  isFunctionExpression(expr) {
+    return Array.isArray(expr);
+  }
+  formatName(expr) {
+    return `FlowCoreExpression<${expr}>}`;
+  }
+};
+__publicField(_ReactiveExpression, "parser", new ExpressionParser());
+__publicField(_ReactiveExpression, "customFunctions", {});
+let ReactiveExpression = _ReactiveExpression;
+ReactiveExpression.registerCustomFunction(customStateFn);
+ReactiveExpression.registerCustomFunction(customFromPaletteFn);
+ReactiveExpression.registerCustomFunction(regex);
+ReactiveExpression.registerCustomFunction(regexi);
+ReactiveExpression.registerCustomFunction(equal);
+ReactiveExpression.registerCustomFunction(equali);
+
+export { ReactiveExpression };