feat: Binary runtime helper. (#255)

amiller-gh · web-flow · commit 959fb8b2c5bd · 2019-05-23T11:42:50.000-07:00
diff --git a/packages/@css-blocks/runtime/src/ExpressionContainer.ts b/packages/@css-blocks/runtime/src/ExpressionContainer.ts
@@ -0,0 +1,265 @@
+import { OP_CODE, runtime } from "./runtime";
+
+// Convenience re-exports for ergonomic APIs (see test file).
+export const OR  = OP_CODE.OR;
+export const AND = OP_CODE.AND;
+export const EQ  = OP_CODE.EQUAL;
+// the NOT operation only exists transiently because negation is expressed in the
+// arguments of the other operations. This allows it to use the 3rd bit while
+// there's only two bits at runtime.
+const NOT_OP: 4 = 4;
+
+// Maps OP_CODE values to human readable strings.
+const OP_STR = {
+  [OR]: "OR",
+  [AND]: "AND",
+  [EQ]: "EQ",
+  [NOT_OP]: "NOT",
+  [OP_CODE.SEP]: "SEP",
+};
+
+/**
+ * The index of an input value to be resolved at runtime.
+ **/
+export type Value = number;
+type UID = number;
+
+/**
+ * Represents the negation of a resolved or computed value.
+ **/
+export interface NotValue {
+  val: Value | Expression;
+  op: typeof NOT_OP;
+}
+
+/**
+ * Constructs an expression that negates a value or expression.
+ */
+export function NOT(val: Value | Expression): NotValue {
+  return { val, op: NOT_OP };
+}
+
+/**
+ * Determine if a provided value is a `NotValue` interface.
+ * @param v Any value.
+ */
+function isNotValue(v: Operand): v is NotValue { return typeof v === "object" && v.op === NOT_OP; }
+
+/**
+ * Represents a single node in a boolean expression binary tree.
+ */
+export interface Expression {
+  left: Expression | Value;
+  notLeft: boolean;
+  op: OP_CODE;
+  right: Expression | Value;
+  notRight: boolean;
+}
+
+/**
+ * Valid operand values for our expr() function.
+ **/
+export type Operand = Value | Expression | NotValue;
+
+/**
+ * SimpleExpression objects are a special representation of Expressions
+ * that will only reference resolved values at runtime. They are completely flat.
+ */
+export interface SimpleExpression extends Expression {
+  left: Value;
+  right: Value;
+}
+
+/**
+ * The flattened representation of an Expression binary tree.
+ * This is converted basically 1:1 to the binary runtime shapes.
+ */
+export interface Flattened {
+  arguments: Set<number>;
+  expressions: SimpleExpression[];
+  indices: Map<UID, number>;
+}
+
+/**
+ * Given a left operand, opcode, and right expression, return an expression object.
+ * Left and right operands may be the index of an input value, a `NotValue` expression,
+ * or another Expression object, making this a very fancy binary tree.
+ * @param left The Left Operand
+ * @param op OP_CODE to process left and right with
+ * @param right The Right Operand.
+ */
+export function expr(left: Operand, op: OP_CODE, right: Operand): Expression {
+  let notLeft = false;
+  let notRight = false;
+  if (isNotValue(left)) {
+    notLeft = true;
+    left = left.val;
+  }
+  if (isNotValue(right)) {
+    notRight = true;
+    right = right.val;
+  }
+  return { left, op, right, notLeft, notRight };
+}
+
+/**
+ * Generate a human readable string for any SimpleExpression.
+ * @param expr The SimpleExpression we're generating a UID for.
+ */
+export function debugExpression(expr: SimpleExpression): string {
+  return `VAR ${expr.notLeft ? "!" : ""}${expr.left} ${OP_STR[expr.op]} VAR ${expr.notRight ? "!" : ""}${expr.right}`;
+}
+
+/**
+ * Generates a unique identifier for an expression.
+ * This only works for values referencing an index of 16383 or less.
+ */
+function genUID(expr: SimpleExpression): UID {
+  if (expr.left > 16383 || expr.right > 16383) {
+    throw new Error("index out of bounds."); // just in case
+  }
+  let uid = (expr.notLeft ? 1 : 0) << 31;
+  uid |= expr.left << 17;
+  uid |= (expr.notRight ? 1 : 0) << 16;
+  uid |= (expr.right) << 2;
+  uid |= expr.op;
+  return uid;
+}
+
+/**
+ * Discover all `Value`s referenced in a boolean Expression tree.
+ * @param expr The Expression tree to crawl.
+ * @param out The Flattened output object to read values in to.
+ */
+function getArgs(expr: Expression, out: Flattened) {
+  if (typeof expr.left === "number") { out.arguments.add(expr.left); }
+  else { getArgs(expr.left, out); }
+
+  if (typeof expr.right === "number") { out.arguments.add(expr.right); }
+  else { getArgs(expr.right, out); }
+}
+
+/**
+ * Provided an Expression binary tree, read all values in to the Flattened data object.
+ * @param expr The Expression tree to crawl.
+ * @param out The Flattened object to read data in to.
+ */
+function visit(expr: Expression, out: Flattened): number {
+
+  // Convert this expression to a SimpleExpression
+  let simpleExpr: SimpleExpression = {
+    left: (typeof expr.left  !== "number") ? visit(expr.left, out) : expr.left,
+    right: (typeof expr.right  !== "number") ? visit(expr.right, out) : expr.right,
+    op: expr.op,
+    notLeft: expr.notLeft,
+    notRight: expr.notRight,
+  };
+
+  // Generate a UID for this expression.
+  let uid = genUID(simpleExpr);
+
+  // Save this expression in the simple expressions array, if an equivalent expression is not there.
+  if (!out.indices.has(uid)) {
+    out.expressions.push(simpleExpr);
+    out.indices.set(uid, out.expressions.length - 1);
+  }
+
+  // Return the expression's index reference.
+  return out.indices.get(uid)! + out.arguments.size;
+}
+
+/**
+ * Flatten an ExpressionContainer object, reading values in to a Flattened data structure.
+ * @param el The ExpressionContainer to flatten.
+ */
+function flattenExpressions(el: ExpressionContainer): Flattened {
+  const out: Flattened = {
+    arguments: new Set(),
+    expressions: [],
+    indices: new Map(),
+  };
+
+  // Fetch all referenced args.
+  el.forEachClass((_c, e) => getArgs(e, out));
+
+  // For every root note, crawl its descendents and populate the Flattened object
+  // with the used expressions.
+  const classExprs = el.getExprs().map((expr): SimpleExpression => ({
+    left: (typeof expr.left  !== "number") ? visit(expr.left, out) : expr.left,
+    right: (typeof expr.right  !== "number") ? visit(expr.right, out) : expr.right,
+    op: expr.op,
+    notLeft: expr.notLeft,
+    notRight: expr.notRight,
+  }));
+
+  // Ensure all classExpr root nodes are at the end of the Flattened expression list.
+  out.expressions = [...out.expressions, ...classExprs];
+
+  return out;
+}
+
+export class ExpressionContainer {
+
+  private classes: {[key: string]: Expression} = {};
+
+  /**
+   * Add a new class to this ExpressionContainer.
+   * @param name The class name we're determining presence for.
+   * @param expr The Expression that evaluates to true or false, representing class application.
+   */
+  class(name: string, expr: Expression) { this.classes[name] = expr; }
+
+  /**
+   * Iterate over all classes stored on this ExpressionContainer.
+   * @param cb forEachClass callback function. Passed the class name, and Expression.
+   */
+  forEachClass(cb: (c: string, e: Expression) => void): ExpressionContainer {
+    for (let key of Object.keys(this.classes)) { cb(key, this.classes[key]); }
+    return this;
+  }
+
+  // Expression and Class introspection methods.
+  getExprs(): Expression[] { return Object.values(this.classes); }
+  getClasses(): string[]   { return Object.keys(this.classes);   }
+
+  /**
+   * Get the binary string (ex: "1001001001010") that represents all the registered classes'
+   * application logic in this ExpressionContainer.
+   */
+  getBinaryString(): string {
+    const flattened = flattenExpressions(this);
+    const argCount = flattened.arguments.size;
+    const classesCount = Object.keys(this.classes).length;
+    let exprCount = 0;
+    let out = "";
+    for (let idx = 0; idx < flattened.expressions.length; idx++) {
+      let expr = flattened.expressions[idx];
+      let isSep = (flattened.expressions.length - classesCount) === idx;
+      let size = ~~Math.log2(exprCount + argCount - 1) + 1;
+      let left  = expr.left.toString(2).padStart(size, "0") + (expr.notLeft ? "1" : "0");
+      let op    = expr.op.toString(2).padStart(2, "0");
+      let right = expr.right.toString(2).padStart(size, "0") + (expr.notRight ? "1" : "0");
+      out += (isSep ? OP_CODE.SEP.toString(2) : "") + op + left + right;
+      exprCount++;
+      // console.log(`${debugExpression(expr)}:`, op, left, right);
+    }
+
+    return out;
+  }
+
+  /**
+   * Calculate the base36 binary string encoding of this expression's logic shape.
+   */
+  getBinaryEncoding(): string[] {
+    return this.getBinaryString().match(/.{1,32}/g)!.map((s) => parseInt(s.split("").reverse().join(""), 2).toString(36));
+  }
+
+  /**
+   * Convenience method to test class application. Calls the binary runtime using
+   * the binary encoded expression shapes and provided arguments.
+   * @param args Arguments to evaluate this expression using.
+   */
+  exec(...args: unknown[]) {
+    return runtime(this.getBinaryEncoding(), this.getClasses(), args);
+  }
+}
diff --git a/packages/@css-blocks/runtime/src/runtime.ts b/packages/@css-blocks/runtime/src/runtime.ts
@@ -0,0 +1,116 @@
+// All four op codes that we can find in one of our binary strings.
+// The SEP opcode is found when we have finished processing all
+// sub-expressions required by the class boolean expressions. Remaining
+// triples map directly to input classes.
+export const enum OP_CODE {
+  OR    = 0,
+  AND   = 1,
+  EQUAL = 2,
+  SEP   = 3,
+}
+
+// The three discovery states that our parser can be in. Looking for an
+// op code, the left operand, or the right operand.
+const enum STATE {
+  OP = 0,
+  LEFT = 1,
+  RIGHT = 2,
+}
+
+/* I'm special. (The rules don't apply when you're coding for a minifier) */
+/* tslint:disable:triple-equals typedef-whitespace no-unnecessary-type-assertion prefer-for-of*/
+export function runtime(shape: string[], classes: string[], args: unknown[]): string {
+
+  const exprs = args.slice();  // Expressions storage.
+  let exprCount = args.length; // Running count of expressions.
+
+  let out = ""; // Output class string.
+
+  let left: boolean; // The left side of a boolean expression.
+  let op:   OP_CODE; // The operator for a boolean expression.
+  let val:  boolean; // Stores the right side of a boolean expression, and the final expression result.
+
+  // Holds state on token ingestion.
+  // We're either discovering an OP_CODE, a left, or a right value.
+  let state: STATE  = STATE.OP;
+
+  let classIdx = -1; // The class index we're determining presence for – set to 0 when `SEP` is encountered.
+  let working  = 0;  // Next ingested value will be stored here.
+  let size     = 2;  // Variable window size, re-computed as expressions are calculated and added.
+
+  // For every binary encoded string...
+  for (let i = 0; i < shape.length; i++) {
+
+    // Convert binary string segment to a base 10 integer.
+    let integer = parseInt(shape[i], 36);
+
+    // Process each bit in this integer. The parser ensures 32 bit integers
+    // are emitted. This is important because bitwise operations in JS clamp
+    // app operands to 32 bit integers.
+    // Note: `while` loop is faster than a `for` loop here.
+    let iters = 32;
+    while (iters--) {
+
+      // If we've discovered the separator opcode, begin applying classes.
+      if (op! == OP_CODE.SEP) { state = classIdx = 0; }
+
+      // Variable token size is dependant on the number of values it is possible to reference.
+      // Add an extra bit to token size to accommodate the "not" bit encoded with every var reference.
+      // This code block must happen *before* the !size check below to properly construct opcode vals.
+      if (!size) {
+        // This is a very clever way to do Math.ceil(Math.log2(exprCount-1)).
+        while(exprCount - 1 >> size++); // tslint:disable-line
+        // If state == 0, we know we're looking for an opcode and size is 2.
+        size = (!state) ? 2 : size;
+      }
+
+      // Construct our next value and "pop" a bit off the end. `<<` serves as a faster Base2 Math.pow()
+      working += integer % 2 * (1 << (--size) || 1); // tslint:disable-line
+      integer >>>= 1;                                // tslint:disable-line
+
+      // If we have a full value or opcode, process the expression.
+      // Otherwise, continue to consume the next bit until we do.
+      if (!size) {
+
+        // Fetch the resolved expression value if we're looking for the LEFT or RIGHT value.
+        // The last bit of every VAL token is the NOT bit. If `1`, invert the recovered value.
+        // This is a throwaway value if we're discovering the OP.
+        val = !!(state && (+!!exprs[working >>> 1] ^ (working % 2))); // tslint:disable-line
+
+        // If discovering as opcode, save as an opcode.
+        if (state == STATE.OP) { op = working; }
+
+        // If discovering a left side operation value, save as the left value.
+        if (state == STATE.LEFT) { left = val; }
+
+        // If we've found the right side value...
+        if (state == STATE.RIGHT) {
+
+          // Run the correct operation on our left and right values.
+          // Not a switch for code size reasons.
+          if (op == OP_CODE.OR)    { val = left! || val;  }
+          if (op == OP_CODE.AND)   { val = left! && val;  }
+          if (op == OP_CODE.EQUAL) { val = left! === val; }
+
+          // Save our computed expression value to the next expression index.
+          exprs[exprCount++] = val;
+
+          // If classIdx > -1, start concatenating classes based on result of `val`.
+          // Increment to the next class. If this was the last class, break
+          // out of the loops so we don't process extra 0's.
+          if (!!~classIdx) {
+            out += val ? (out ? " " : "") + classes[classIdx] : "";
+            if (++classIdx == classes.length) { break; }
+          }
+        }
+
+        // Reset our working state and begin discovering the next token.
+        working = 0;
+        state = ++state % 3;
+      }
+    }
+  }
+
+  // Return the concatenated classes!
+  return out;
+}
diff --git a/packages/@css-blocks/runtime/test/expression-test.ts b/packages/@css-blocks/runtime/test/expression-test.ts
