ggaction 0.0.1

package/src/core/action.js

@@ -0,0 +1,120 @@
+import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
+
+function summarizeObject(value, ancestors = new WeakSet()) {
+  if (ancestors.has(value)) {
+    throw new TypeError("Action arguments must not contain circular references.");
+  }
+  ancestors.add(value);
+  const summary = {};
+
+  for (const [key, item] of Object.entries(value)) {
+    if (Array.isArray(item)) {
+      summary[`${key}Count`] = item.length;
+    } else if (isPlainObject(item)) {
+      summary[key] = summarizeObject(item, ancestors);
+    } else {
+      summary[key] = item;
+    }
+  }
+
+  ancestors.delete(value);
+  return summary;
+}
+
+export function summarizeArgs(args) {
+  if (!isPlainObject(args)) {
+    throw new TypeError("Action arguments must be a plain object.");
+  }
+
+  return cloneAndFreeze(summarizeObject(args));
+}
+
+export function countActionNodes(node) {
+  return node.children.reduce(
+    (count, child) => count + 1 + countActionNodes(child),
+    0
+  );
+}
+
+export function createActionNode({ id, op, description, args }) {
+  return freezeOwned({
+    id,
+    op,
+    description,
+    args,
+    children: freezeOwned([])
+  });
+}
+
+function nodeAtPath(root, path) {
+  let node = root;
+  for (const index of path) {
+    if (!Number.isInteger(index) || index < 0 || index >= node.children.length) {
+      throw new Error(`Unknown parent action path "${path.join(".")}".`);
+    }
+    node = node.children[index];
+  }
+  return node;
+}
+
+export function appendActionNodeAtPath(root, parentPath, actionNode) {
+  if (!Array.isArray(parentPath)) {
+    throw new TypeError("Parent action path must be an array.");
+  }
+  const parent = nodeAtPath(root, parentPath);
+  const path = [...parentPath, parent.children.length];
+
+  function append(node, depth) {
+    if (depth === parentPath.length) {
+      return freezeOwned({
+        ...node,
+        children: freezeOwned([...node.children, actionNode])
+      });
+    }
+    const index = parentPath[depth];
+    const children = [...node.children];
+    children[index] = append(children[index], depth + 1);
+    return freezeOwned({ ...node, children: freezeOwned(children) });
+  }
+
+  return { root: append(root, 0), path };
+}
+
+export function action(metadata, implementation) {
+  if (!isPlainObject(metadata)) {
+    throw new TypeError("Action metadata must be a plain object.");
+  }
+
+  if (typeof metadata.op !== "string" || metadata.op.length === 0) {
+    throw new TypeError("Action metadata requires a non-empty op.");
+  }
+
+  if (
+    typeof metadata.description !== "string" ||
+    metadata.description.length === 0
+  ) {
+    throw new TypeError("Action metadata requires a non-empty description.");
+  }
+
+  if (typeof implementation !== "function") {
+    throw new TypeError("Action implementation must be a function.");
+  }
+
+  return function wrappedAction(args = {}) {
+    if (!isPlainObject(args)) {
+      throw new TypeError("Action arguments must be a plain object.");
+    }
+
+    const entered = this._enterAction({
+      ...metadata,
+      args: summarizeArgs(args)
+    });
+    const result = implementation.call(entered, args);
+
+    if (!(result instanceof this.constructor)) {
+      throw new TypeError(`${metadata.op} must return a ChartProgram.`);
+    }
+
+    return result._exitAction();
+  };
+}

package/src/core/identifiers.js

@@ -0,0 +1,28 @@
+export const USER_ID_SOURCE = "[A-Za-z0-9_-]+";
+
+const USER_ID_PATTERN = new RegExp(`^${USER_ID_SOURCE}$`);
+
+export function validateUserId(id, label = "ID") {
+  if (typeof id !== "string" || !USER_ID_PATTERN.test(id)) {
+    throw new TypeError(
+      `${label} must contain only letters, numbers, _ or - and must not be empty.`
+    );
+  }
+
+  return id;
+}
+
+export function resolveOptionalUserId(id, {
+  defaultId,
+  label = "ID",
+  operation,
+  ambiguous = false
+}) {
+  if (id !== undefined) return validateUserId(id, label);
+  if (ambiguous) {
+    throw new Error(
+      `${operation} requires an explicit ${label.toLowerCase()} because its default is ambiguous.`
+    );
+  }
+  return validateUserId(defaultId, label);
+}

package/src/core/immutable.js

@@ -0,0 +1,94 @@
+const ownedValues = new WeakSet();
+
+export function isPlainObject(value) {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function freezeOwned(value) {
+  if (value !== null && typeof value === "object") {
+    Object.freeze(value);
+    ownedValues.add(value);
+  }
+
+  return value;
+}
+
+export function isOwned(value) {
+  return value !== null && typeof value === "object" && ownedValues.has(value);
+}
+
+export function cloneAndFreeze(value, ancestors = new WeakSet()) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  if (ancestors.has(value)) {
+    throw new TypeError("Cannot store cyclic values in a ChartProgram.");
+  }
+
+  ancestors.add(value);
+
+  let clone;
+
+  if (Array.isArray(value)) {
+    clone = value.map(item => cloneAndFreeze(item, ancestors));
+  } else if (isPlainObject(value)) {
+    clone = Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        cloneAndFreeze(item, ancestors)
+      ])
+    );
+  } else {
+    throw new TypeError("ChartProgram state only supports plain objects and arrays.");
+  }
+
+  ancestors.delete(value);
+  return freezeOwned(clone);
+}
+
+export function removeOwnedPath(source, path) {
+  if (!isPlainObject(source)) {
+    throw new TypeError("Structural removal requires a plain object source.");
+  }
+  if (
+    !Array.isArray(path) ||
+    path.length === 0 ||
+    !path.every(key => typeof key === "string" && key.length > 0)
+  ) {
+    throw new TypeError("Structural removal path must contain names.");
+  }
+
+  const [key, ...rest] = path;
+  if (!Object.hasOwn(source, key)) {
+    return { value: source, removed: false };
+  }
+
+  if (rest.length === 0) {
+    const { [key]: removedValue, ...remaining } = source;
+    void removedValue;
+    return { value: freezeOwned(remaining), removed: true };
+  }
+
+  const child = source[key];
+  if (!isPlainObject(child)) {
+    return { value: source, removed: false };
+  }
+  const removed = removeOwnedPath(child, rest);
+  if (!removed.removed) return { value: source, removed: false };
+
+  if (Object.keys(removed.value).length === 0) {
+    const { [key]: emptyChild, ...remaining } = source;
+    void emptyChild;
+    return { value: freezeOwned(remaining), removed: true };
+  }
+  return {
+    value: freezeOwned({ ...source, [key]: removed.value }),
+    removed: true
+  };
+}

package/src/core/specs.js

@@ -0,0 +1,29 @@
+import { cloneAndFreeze } from "./immutable.js";
+
+export function createEmptySemanticSpec() {
+  return cloneAndFreeze({
+    datasets: [],
+    layers: [],
+    scales: [],
+    coordinates: [],
+    guides: {},
+    title: {}
+  });
+}
+
+export function createEmptyGraphicSpec() {
+  return cloneAndFreeze({
+    objects: {},
+    order: []
+  });
+}
+
+export function createTraceRoot() {
+  return cloneAndFreeze({
+    id: "program",
+    op: "program",
+    description: "Program action trace root.",
+    args: {},
+    children: []
+  });
+}

package/src/core/textMetrics.js

@@ -0,0 +1,23 @@
+function codePointWidth(codePoint) {
+  if (/\s/u.test(codePoint)) return 0.28;
+  if (/[iIl1.,:;!'|]/u.test(codePoint)) return 0.27;
+  if (/[mwMW@#%&]/u.test(codePoint)) return 0.82;
+  if (/[A-Z]/u.test(codePoint)) return 0.61;
+  if (/[0-9]/u.test(codePoint)) return 0.53;
+  if (/[-_]/u.test(codePoint)) return 0.34;
+  if (codePoint.codePointAt(0) > 0x7f) return 1;
+  return 0.47;
+}
+
+export function measureTextWidth(text, { fontSize } = {}) {
+  if (typeof text !== "string") {
+    throw new TypeError("Text measurement requires a string.");
+  }
+  if (!Number.isFinite(fontSize) || fontSize <= 0) {
+    throw new RangeError("Text measurement requires a positive fontSize.");
+  }
+  return [...text].reduce(
+    (width, codePoint) => width + codePointWidth(codePoint) * fontSize,
+    0
+  );
+}

package/src/core/validation.js

@@ -0,0 +1,54 @@
+import { isPlainObject } from "./immutable.js";
+
+export function validateKeys(value, supported, label) {
+  for (const key of Object.keys(value)) {
+    if (!supported.includes(key)) {
+      throw new Error(`Unknown ${label} option "${key}".`);
+    }
+  }
+}
+
+export function noOptions(args, operation) {
+  if (!isPlainObject(args) || Object.keys(args).length > 0) {
+    throw new Error(`${operation} does not accept options.`);
+  }
+}
+
+export function sameOrderedValues(left, right) {
+  return (
+    Array.isArray(left) &&
+    Array.isArray(right) &&
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  );
+}
+
+export function validateNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+export function validateUnitInterval(value, label) {
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new RangeError(
+      `${label} must be between 0 and 1 (values from 0 to 1).`
+    );
+  }
+  return value;
+}
+
+export function validatePositiveFinite(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`${label} must be a positive finite number.`);
+  }
+  return value;
+}
+
+export function validateNonNegativeFinite(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}

package/src/core/vocabulary.js

@@ -0,0 +1,58 @@
+export const MARK_TYPES = Object.freeze([
+  "point",
+  "line",
+  "bar",
+  "area",
+  "rule"
+]);
+
+export const ENCODING_CHANNELS = Object.freeze([
+  "x",
+  "y",
+  "x2",
+  "y2",
+  "xOffset",
+  "theta",
+  "radius",
+  "color",
+  "strokeDash",
+  "size",
+  "shape",
+  "group",
+  "opacity"
+]);
+
+export const SCALED_ENCODING_CHANNELS = Object.freeze(
+  ENCODING_CHANNELS.filter(channel => channel !== "group")
+);
+
+export const POSITION_CHANNELS = Object.freeze(["x", "y"]);
+
+export const COLOR_LAYOUTS = Object.freeze([
+  "stack",
+  "fill",
+  "group",
+  "overlay",
+  "diverging"
+]);
+
+export const STACK_MODES = Object.freeze(["zero", "normalize"]);
+
+export const CATEGORICAL_LEGEND_CHANNELS = Object.freeze([
+  "color",
+  "strokeDash",
+  "shape"
+]);
+
+export const LEGEND_CONFIG_KINDS = Object.freeze([
+  "series",
+  "color",
+  "size",
+  "gradient",
+  "interval",
+  "opacity"
+]);
+
+export function includesVocabulary(vocabulary, value) {
+  return vocabulary.includes(value);
+}

package/src/extension.js

@@ -0,0 +1,2 @@
+export { action } from "./core/action.js";
+export { ChartProgram } from "./ChartProgram.js";

package/src/grammar/aggregate.js

@@ -0,0 +1,259 @@
+import { isPlainObject } from "../core/immutable.js";
+
+export const SCALAR_AGGREGATE_OPERATIONS = Object.freeze([
+  "count", "sum", "mean", "median", "min", "max",
+  "distinct", "valid", "missing",
+  "variance", "varianceP", "stdev", "stdevP", "stderr",
+  "q1", "q3", "ciLower", "ciUpper"
+]);
+
+const SCALAR_OPERATIONS = new Set(SCALAR_AGGREGATE_OPERATIONS);
+const NOMINAL_OPERATIONS = new Set(["count", "distinct", "valid", "missing"]);
+const PARAMETERIZED_OPERATIONS = new Set(["quantile", "first", "last"]);
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}
+
+export function isScalarAggregate(value) {
+  return typeof value === "string" && SCALAR_OPERATIONS.has(value);
+}
+
+export function isParameterizedAggregate(value) {
+  return isPlainObject(value) && PARAMETERIZED_OPERATIONS.has(value.op);
+}
+
+export function isAggregate(value) {
+  return isScalarAggregate(value) || isParameterizedAggregate(value);
+}
+
+export function validateAggregate(value) {
+  if (typeof value === "string") {
+    if (!SCALAR_OPERATIONS.has(value)) {
+      throw new Error(`Unsupported aggregate "${value}".`);
+    }
+    return value;
+  }
+  if (!isPlainObject(value)) {
+    throw new TypeError("Aggregate must be a supported operation or parameter object.");
+  }
+  if (value.op === "quantile") {
+    const unknown = Object.keys(value).find(
+      key => !["op", "probability"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(`Unknown quantile aggregate property "${unknown}".`);
+    }
+    if (
+      !Number.isFinite(value.probability) ||
+      value.probability < 0 ||
+      value.probability > 1
+    ) {
+      throw new RangeError("Quantile probability must be between 0 and 1.");
+    }
+    return { op: "quantile", probability: value.probability };
+  }
+  if (value.op === "first" || value.op === "last") {
+    const unknown = Object.keys(value).find(
+      key => !["op", "orderBy", "order"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(`Unknown ordered aggregate property "${unknown}".`);
+    }
+    nonEmptyString(value.orderBy, "Ordered aggregate orderBy");
+    if (
+      value.order !== undefined &&
+      !["ascending", "descending"].includes(value.order)
+    ) {
+      throw new Error(`Unsupported ordered aggregate order "${value.order}".`);
+    }
+    return {
+      op: value.op,
+      orderBy: value.orderBy,
+      order: value.order ?? "ascending"
+    };
+  }
+  throw new Error(`Unsupported aggregate "${value.op}".`);
+}
+
+export function validateAggregateFieldType(operation, fieldType) {
+  const aggregate = validateAggregate(operation);
+  if (isScalarAggregate(aggregate)) {
+    return validateScalarAggregateFieldType(aggregate, fieldType);
+  }
+  if (fieldType === "quantitative") return fieldType;
+  throw new Error(
+    `Aggregate "${aggregate.op}" does not support field type "${fieldType}".`
+  );
+}
+
+export function validateScalarAggregateFieldType(operation, fieldType) {
+  validateAggregate(operation);
+  if (!isScalarAggregate(operation)) {
+    throw new Error("Scalar aggregate calculation requires a scalar operation.");
+  }
+  if (fieldType === "quantitative") return fieldType;
+  if (fieldType === "nominal" && NOMINAL_OPERATIONS.has(operation)) {
+    return fieldType;
+  }
+  throw new Error(
+    `Aggregate "${operation}" does not support field type "${fieldType}".`
+  );
+}
+
+function isMissing(value) {
+  return value === null || value === undefined ||
+    (typeof value === "number" && Number.isNaN(value));
+}
+
+function isNominal(value) {
+  return typeof value === "string" || typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+export function validateAggregateFieldValues(rows, field, fieldType) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Aggregate rows must be an array.");
+  }
+  nonEmptyString(field, "Aggregate field");
+  for (const row of rows) {
+    const value = row[field];
+    if (isMissing(value)) continue;
+    if (fieldType === "quantitative" && typeof value !== "number") {
+      throw new TypeError(`Aggregate field "${field}" must contain numeric or missing values.`);
+    }
+    if (fieldType === "nominal" && !isNominal(value)) {
+      throw new TypeError(`Aggregate field "${field}" must contain nominal or missing values.`);
+    }
+  }
+}
+
+function finiteValues(values) {
+  return values.filter(value => typeof value === "number" && Number.isFinite(value));
+}
+
+function quantile(values, probability) {
+  const ordered = [...values].sort((left, right) => left - right);
+  const position = (ordered.length - 1) * probability;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  return ordered[lower] +
+    (ordered[upper] - ordered[lower]) * (position - lower);
+}
+
+function comparableOrderKey(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return { type: "number", value };
+  }
+  if (typeof value === "string") return { type: "string", value };
+  if (typeof value === "boolean") return { type: "boolean", value: Number(value) };
+  return undefined;
+}
+
+function compareOrderKeys(left, right) {
+  if (left.value < right.value) return -1;
+  if (left.value > right.value) return 1;
+  return 0;
+}
+
+function aggregateOrderedRows(rows, field, aggregate) {
+  const candidates = rows.flatMap((row, sourceIndex) => {
+    const key = comparableOrderKey(row[aggregate.orderBy]);
+    const value = row[field];
+    return key === undefined || !Number.isFinite(value)
+      ? []
+      : [{ key, value, sourceIndex }];
+  });
+  if (candidates.length === 0) return undefined;
+  const keyTypes = new Set(candidates.map(candidate => candidate.key.type));
+  if (keyTypes.size !== 1) return undefined;
+  const direction = aggregate.order === "descending" ? -1 : 1;
+  candidates.sort((left, right) =>
+    direction * compareOrderKeys(left.key, right.key) ||
+    left.sourceIndex - right.sourceIndex
+  );
+  return aggregate.op === "first"
+    ? candidates[0].value
+    : candidates.at(-1).value;
+}
+
+function moments(values) {
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  const squared = values.reduce(
+    (sum, value) => sum + (value - mean) ** 2,
+    0
+  );
+  return { mean, squared };
+}
+
+export function aggregateScalarValues(values, operation) {
+  if (!Array.isArray(values)) {
+    throw new TypeError("Aggregate values must be an array.");
+  }
+  validateAggregate(operation);
+  if (!isScalarAggregate(operation)) {
+    throw new Error("Scalar aggregate calculation requires a scalar operation.");
+  }
+
+  if (operation === "count") return values.length;
+  const valid = values.filter(value => !isMissing(value));
+  if (operation === "valid") return valid.length;
+  if (operation === "missing") return values.length - valid.length;
+  if (operation === "distinct") return new Set(valid).size;
+
+  const finite = finiteValues(values);
+  if (finite.length === 0) return undefined;
+  if (operation === "sum") {
+    return finite.reduce((sum, value) => sum + value, 0);
+  }
+  if (operation === "min") return Math.min(...finite);
+  if (operation === "max") return Math.max(...finite);
+  if (operation === "median") return quantile(finite, 0.5);
+  if (operation === "q1") return quantile(finite, 0.25);
+  if (operation === "q3") return quantile(finite, 0.75);
+
+  const { mean, squared } = moments(finite);
+  if (operation === "mean") return mean;
+  if (operation === "varianceP") return squared / finite.length;
+  if (operation === "stdevP") return Math.sqrt(squared / finite.length);
+  if (finite.length < 2) return undefined;
+
+  const variance = squared / (finite.length - 1);
+  if (operation === "variance") return variance;
+  if (operation === "stdev") return Math.sqrt(variance);
+  const stderr = Math.sqrt(variance) / Math.sqrt(finite.length);
+  if (operation === "stderr") return stderr;
+  if (operation === "ciLower") return mean - 1.96 * stderr;
+  if (operation === "ciUpper") return mean + 1.96 * stderr;
+  throw new Error(`Unsupported scalar aggregate "${operation}".`);
+}
+
+export function aggregateRows(rows, field, operation) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Aggregate rows must be an array.");
+  }
+  nonEmptyString(field, "Aggregate field");
+  const aggregate = validateAggregate(operation);
+  if (isScalarAggregate(aggregate)) {
+    return aggregateScalarValues(rows.map(row => row[field]), aggregate);
+  }
+  if (aggregate.op === "quantile") {
+    const values = finiteValues(rows.map(row => row[field]));
+    return values.length === 0
+      ? undefined
+      : quantile(values, aggregate.probability);
+  }
+  return aggregateOrderedRows(rows, field, aggregate);
+}
+
+export function formatAggregateTitle(operation, field) {
+  const aggregate = validateAggregate(operation);
+  nonEmptyString(field, "Aggregate field");
+  if (isScalarAggregate(aggregate)) return `${aggregate}(${field})`;
+  if (aggregate.op === "quantile") {
+    return `quantile(${field}, ${aggregate.probability})`;
+  }
+  return `${aggregate.op}(${field}, ${aggregate.orderBy} ${aggregate.order})`;
+}