ggaction 0.0.12 → 0.0.15

package/src/grammar/transforms.js

@@ -1,29 +1,274 @@
-import { isPlainObject } from "../core/immutable.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { validateBoxTransform } from "./boxPlot.js";
+import { normalizeBinTransform, validateBinTransform } from "./bin.js";
 import {
+  normalizeBin2DTransform,
   requestedBin2DTransform,
   validateBin2DTransform
 } from "./bin2d.js";
-import { validateDensityTransform } from "./density.js";
-import { validateFilterTransform } from "./filter.js";
+import {
+  normalizeDensityTransform,
+  validateDensityTransform
+} from "./density.js";
+import {
+  normalizeECDFTransform,
+  validateECDFTransform
+} from "./ecdf.js";
+import {
+  normalizeComputedTransform,
+  validateComputedTransform
+} from "./computed.js";
+import {
+  normalizeCompleteTransform,
+  validateCompleteTransform
+} from "./complete.js";
+import {
+  normalizeFilterTransform,
+  validateFilterTransform
+} from "./filter.js";
+import { normalizeFoldTransform, validateFoldTransform } from "./fold.js";
 import {
   requestedGradientProfileTransform,
   validateGradientProfileTransform
 } from "./gradientProfile.js";
-import { validateIntervalTransform } from "./interval.js";
+import {
+  normalizeIntervalTransform,
+  validateIntervalTransform
+} from "./interval.js";
+import {
+  normalizeImputeTransform,
+  validateImputeTransform
+} from "./impute.js";
 import {
   requestedHorizonTransform,
   validateHorizonTransform
 } from "./horizon.js";
 import { validateMarkFilterTransform } from "./markFilter.js";
-import { validateRegressionTransform } from "./regression/index.js";
-import { validateWindowTransform } from "./window.js";
-import { validateTimeUnitTransform } from "./timeUnit.js";
+import {
+  normalizeNormalizeTransform,
+  validateNormalizeTransform
+} from "./normalize.js";
+import {
+  normalizeRegressionTransform,
+  validateRegressionTransform
+} from "./regression/index.js";
+import { normalizeWindowTransform, validateWindowTransform } from "./window.js";
+import {
+  normalizeTimeUnitTransform,
+  validateTimeUnitTransform
+} from "./timeUnit.js";
+import {
+  normalizeSummaryTransform,
+  validateSummaryTransform
+} from "./summary.js";
+import { normalizeStackTransform, validateStackTransform } from "./stack.js";
+import { validateStatisticalReferenceTransform } from
+  "./statisticalReference.js";
 import { findTransformTopology } from "./transformTopology.js";
 
-function requestedDensityTransform(transform) {
+function requestedTransform(transform) {
   const { resolved: _resolved, ...requested } = transform;
-  return requested;
+  return cloneAndFreeze(requested);
+}
+
+const requestedDensityTransform = requestedTransform;
+
+function requestedOptions(transform) {
+  const { type: _type, resolved: _resolved, ...options } = transform;
+  return options;
+}
+
+function mergedOptions(transform, patch) {
+  const options = { ...requestedOptions(transform) };
+  if (patch.weight === false) delete options.weight;
+  return {
+    ...options,
+    ...Object.fromEntries(
+      Object.entries(patch).filter(
+        ([key, value]) => !(key === "weight" && value === false)
+      )
+    )
+  };
+}
+
+function replaceExclusive(options, patch, keys) {
+  if (!keys.some(key => Object.hasOwn(patch, key))) return options;
+  const next = { ...options };
+  for (const key of keys) delete next[key];
+  return next;
+}
+
+function normalizeSimple(normalize) {
+  return (transform, patch) => normalize(mergedOptions(transform, patch));
+}
+
+function normalizeFilterEdit(transform, patch) {
+  const base = replaceExclusive(
+    requestedOptions(transform),
+    patch,
+    ["oneOf", "predicate", "range"]
+  );
+  return normalizeFilterTransform({ ...base, ...patch });
+}
+
+function normalizeBinEdit(transform, patch) {
+  const prior = requestedOptions(transform);
+  const base = replaceExclusive(
+    { ...prior, ...prior.bin },
+    patch,
+    ["maxBins", "step", "boundaries"]
+  );
+  delete base.bin;
+  if (patch.weight === false) delete base.weight;
+  return normalizeBinTransform({
+    ...base,
+    ...Object.fromEntries(
+      Object.entries(patch).filter(
+        ([key, value]) => !(key === "weight" && value === false)
+      )
+    )
+  });
+}
+
+function normalizeBin2DEdit(transform, patch, owner) {
+  const base = requestedOptions(transform);
+  const members = patch.members ?? base.members;
+  let as = patch.as ?? base.as;
+  if (!Object.hasOwn(patch, "as")) {
+    as = { ...as };
+    if (members && as.members === undefined) {
+      as.members = `__${owner}_members`;
+    } else if (!members) {
+      delete as.members;
+    }
+  }
+  return normalizeBin2DTransform({
+    id: owner,
+    ...base,
+    ...patch,
+    members,
+    as
+  });
+}
+
+function normalizeCompleteEdit(transform, patch) {
+  const base = replaceExclusive(
+    requestedOptions(transform),
+    patch,
+    ["values", "sequence"]
+  );
+  return normalizeCompleteTransform({ ...base, ...patch });
+}
+
+function normalizeImputeEdit(transform, patch) {
+  const base = { ...requestedOptions(transform) };
+  if (Object.hasOwn(patch, "method") && patch.method !== base.method) {
+    delete base.value;
+    if (patch.method === "constant") base.sortBy = [];
+  }
+  return normalizeImputeTransform({ ...base, ...patch });
+}
+
+function normalizeIntervalEdit(transform, patch) {
+  const base = { ...requestedOptions(transform) };
+  const extent = patch.extent ?? base.extent;
+  if (extent !== "ci") {
+    delete base.method;
+    delete base.level;
+  }
+  return normalizeIntervalTransform({ ...base, ...patch, extent });
+}
+
+function normalizeNormalizeEdit(transform, patch) {
+  const base = { ...requestedOptions(transform) };
+  const method = patch.method ?? base.method;
+  if (method !== base.method) {
+    if (method !== "zscore") delete base.variance;
+    if (method === "change") delete base.zeroDenominator;
+    if (!["index", "change", "percentChange"].includes(method)) {
+      delete base.baseline;
+      delete base.sortBy;
+    }
+    if (
+      !["index", "change", "percentChange"].includes(base.method) &&
+      ["index", "change", "percentChange"].includes(method)
+    ) {
+      delete base.baseline;
+      delete base.sortBy;
+    }
+  }
+  return normalizeNormalizeTransform({ ...base, ...patch, method });
+}
+
+function normalizeRegressionEdit(transform, patch) {
+  const base = { ...requestedOptions(transform) };
+  const method = patch.method ?? base.method;
+  if (method !== base.method) {
+    if (method !== "polynomial") delete base.degree;
+    if (method !== "loess") delete base.span;
+    if (method === "loess" || base.method === "loess") {
+      for (const key of [
+        "confidenceMethod", "level", "confidence", "interval"
+      ]) delete base[key];
+    }
+  }
+  return normalizeRegressionTransform({ ...base, ...patch, method });
+}
+
+function normalizeTimeUnitEdit(transform, patch) {
+  const base = { ...requestedOptions(transform) };
+  const unit = patch.unit ?? base.unit;
+  if (unit !== "week" && unit !== base.unit) {
+    delete base.weekStartsOn;
+    delete base.weekRule;
+  }
+  return normalizeTimeUnitTransform({ ...base, ...patch, unit });
+}
+
+function fixedRoles(as, roles) {
+  return Object.fromEntries(roles.flatMap(role =>
+    typeof as?.[role] === "string" ? [[role, as[role]]] : []
+  ));
+}
+
+function uniqueRoles(values, key, field = "as") {
+  const counts = new Map();
+  for (const value of values) {
+    const role = key(value);
+    counts.set(role, (counts.get(role) ?? 0) + 1);
+  }
+  return Object.fromEntries(values.flatMap(value => {
+    const role = key(value);
+    return counts.get(role) === 1 && typeof value[field] === "string"
+      ? [[role, value[field]]]
+      : [];
+  }));
+}
+
+function summaryOutputRoles(transform) {
+  return {
+    ...uniqueRoles(
+      transform.aggregates,
+      aggregate => `aggregate:${JSON.stringify(aggregate.op)}:${aggregate.field ?? ""}`
+    ),
+    ...(typeof transform.members === "string"
+      ? { members: transform.members }
+      : {})
+  };
+}
+
+function windowOutputRoles(transform) {
+  return uniqueRoles(
+    transform.operations,
+    operation => [
+      "operation",
+      operation.op,
+      operation.field ?? "",
+      operation.offset ?? "",
+      JSON.stringify(operation.frame ?? null)
+    ].join(":"),
+    "as"
+  );
 }
 
 function facetHorizonTransform(transform, { scales = {} } = {}) {
@@ -44,11 +289,49 @@ function facetHorizonTransform(transform, { scales = {} } = {}) {
 }
 
 const TRANSFORM_POLICIES = Object.freeze({
+  bin: Object.freeze({
+    ...findTransformTopology("bin"),
+    validate: validateBinTransform,
+    materializeOp: "materializeBinData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeBinEdit,
+    outputRoles: transform => fixedRoles(
+      transform.as,
+      ["lower", "upper", "count", "members"]
+    )
+  }),
   bin2d: Object.freeze({
     ...findTransformTopology("bin2d"),
     validate: validateBin2DTransform,
     materializeOp: "materializeBin2DData",
-    replayTransform: requestedBin2DTransform
+    replayTransform: requestedBin2DTransform,
+    editable: true,
+    normalizeEdit: normalizeBin2DEdit,
+    outputRoles: transform => fixedRoles(
+      transform.as,
+      ["x0", "x1", "y0", "y1", "count", "members"]
+    )
+  }),
+  computed: Object.freeze({
+    ...findTransformTopology("computed"),
+    validate: validateComputedTransform,
+    materializeOp: "materializeComputedData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeComputedTransform),
+    outputRoles: transform => ({ value: transform.as })
+  }),
+  complete: Object.freeze({
+    ...findTransformTopology("complete"),
+    validate: validateCompleteTransform,
+    materializeOp: "materializeCompleteData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeCompleteEdit,
+    outputRoles: transform => typeof transform.members === "string"
+      ? { members: transform.members }
+      : {}
   }),
   boxOutlier: Object.freeze({
     ...findTransformTopology("boxOutlier"),
@@ -64,12 +347,43 @@ const TRANSFORM_POLICIES = Object.freeze({
     ...findTransformTopology("density"),
     validate: validateDensityTransform,
     materializeOp: "materializeDensityData",
-    replayTransform: requestedDensityTransform
+    replayTransform: requestedDensityTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeDensityTransform),
+    outputRoles: transform => ({
+      value: transform.as[0],
+      density: transform.as[1]
+    })
+  }),
+  ecdf: Object.freeze({
+    ...findTransformTopology("ecdf"),
+    validate: validateECDFTransform,
+    materializeOp: "materializeECDFData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeECDFTransform),
+    outputRoles: transform => fixedRoles(
+      transform.as,
+      ["value", "cumulative", "probability"]
+    )
   }),
   filter: Object.freeze({
     ...findTransformTopology("filter"),
     validate: validateFilterTransform,
-    materializeOp: "materializeFilteredData"
+    materializeOp: "materializeFilteredData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeFilterEdit,
+    outputRoles: () => ({})
+  }),
+  fold: Object.freeze({
+    ...findTransformTopology("fold"),
+    validate: validateFoldTransform,
+    materializeOp: "materializeFoldData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeFoldTransform),
+    outputRoles: transform => fixedRoles(transform.as, ["key", "value"])
   }),
   gradientProfile: Object.freeze({
     ...findTransformTopology("gradientProfile"),
@@ -87,27 +401,91 @@ const TRANSFORM_POLICIES = Object.freeze({
   interval: Object.freeze({
     ...findTransformTopology("interval"),
     validate: validateIntervalTransform,
-    materializeOp: "materializeIntervalData"
+    materializeOp: "materializeIntervalData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeIntervalEdit,
+    outputRoles: transform => fixedRoles(
+      transform.as,
+      ["center", "lower", "upper"]
+    )
+  }),
+  impute: Object.freeze({
+    ...findTransformTopology("impute"),
+    validate: validateImputeTransform,
+    materializeOp: "materializeImputedData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeImputeEdit,
+    outputRoles: () => ({})
   }),
   markFilter: Object.freeze({
     ...findTransformTopology("markFilter"),
     validate: validateMarkFilterTransform,
     materializeOp: "materializeMarkFilteredData"
   }),
+  normalize: Object.freeze({
+    ...findTransformTopology("normalize"),
+    validate: validateNormalizeTransform,
+    materializeOp: "materializeNormalizedData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeNormalizeEdit,
+    outputRoles: transform => ({ value: transform.as })
+  }),
   regression: Object.freeze({
     ...findTransformTopology("regression"),
     validate: validateRegressionTransform,
-    materializeOp: "materializeRegressionData"
+    materializeOp: "materializeRegressionData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeRegressionEdit,
+    outputRoles: () => ({})
+  }),
+  summary: Object.freeze({
+    ...findTransformTopology("summary"),
+    validate: validateSummaryTransform,
+    materializeOp: "materializeSummaryData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeSummaryTransform),
+    outputRoles: summaryOutputRoles
+  }),
+  stack: Object.freeze({
+    ...findTransformTopology("stack"),
+    validate: validateStackTransform,
+    materializeOp: "materializeStackData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeStackTransform),
+    outputRoles: transform => fixedRoles(
+      transform.as,
+      ["start", "end", "value", "share"]
+    )
+  }),
+  statisticalReference: Object.freeze({
+    ...findTransformTopology("statisticalReference"),
+    validate: validateStatisticalReferenceTransform,
+    materializeOp: "materializeStatisticalReferenceData",
+    replayTransform: requestedTransform
   }),
   timeUnit: Object.freeze({
     ...findTransformTopology("timeUnit"),
     validate: validateTimeUnitTransform,
-    materializeOp: "materializeTimeUnitData"
+    materializeOp: "materializeTimeUnitData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeTimeUnitEdit,
+    outputRoles: transform => ({ value: transform.as })
   }),
   window: Object.freeze({
     ...findTransformTopology("window"),
     validate: validateWindowTransform,
-    materializeOp: "materializeWindowData"
+    materializeOp: "materializeWindowData",
+    replayTransform: requestedTransform,
+    editable: true,
+    normalizeEdit: normalizeSimple(normalizeWindowTransform),
+    outputRoles: windowOutputRoles
   })
 });
 
@@ -119,6 +497,30 @@ export function findTransformValidator(type) {
   return findTransformPolicy(type)?.validate;
 }
 
+export function requestedDatasetTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Requested dataset transform must be a plain object.");
+  }
+  const policy = findTransformPolicy(transform.type);
+  if (policy?.editable !== true) {
+    throw new Error(`Dataset transform "${transform.type ?? "unknown"}" is not editable.`);
+  }
+  return policy.replayTransform?.(transform) ?? requestedTransform(transform);
+}
+
+export function normalizeDatasetTransformEdit(transform, patch, owner) {
+  const policy = findTransformPolicy(transform?.type);
+  if (policy?.editable !== true || typeof policy.normalizeEdit !== "function") {
+    throw new Error(`Dataset transform "${transform?.type ?? "unknown"}" is not editable.`);
+  }
+  return policy.normalizeEdit(transform, patch, owner);
+}
+
+export function datasetTransformOutputRoles(transform) {
+  const policy = findTransformPolicy(transform?.type);
+  return policy?.outputRoles?.(transform) ?? {};
+}
+
 export function validateDatasetTransforms(value) {
   if (!Array.isArray(value) || value.length !== 1 || !isPlainObject(value[0])) {
     throw new TypeError(

package/src/grammar/valueFormat.js

@@ -0,0 +1,112 @@
+const NUMERIC_FORMAT = /^\.(0?\d|1[0-2])(f|%|e)$/;
+const TIME_DIRECTIVES = new Set(["Y", "m", "d", "b", "%"]);
+const MONTH_NAMES = Object.freeze([
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
+]);
+
+export function isUtcValueFormat(format) {
+  if (typeof format !== "string") return false;
+  let directives = 0;
+  for (let index = 0; index < format.length; index += 1) {
+    if (format[index] !== "%") continue;
+    const directive = format[index + 1];
+    if (!TIME_DIRECTIVES.has(directive)) return false;
+    if (directive !== "%") directives += 1;
+    index += 1;
+  }
+  return directives > 0;
+}
+
+export function validateValueFormat(format, label = "Label format", {
+  allowDecimalsObject = false
+} = {}) {
+  if (format === undefined || format === "auto") return format ?? "auto";
+  if (
+    format !== null &&
+    typeof format === "object" &&
+    Number.isInteger(format.decimals) &&
+    format.decimals >= 0 &&
+    format.decimals <= 100 &&
+    Object.keys(format).length === 1
+  ) {
+    if (allowDecimalsObject) return format;
+  }
+  if (typeof format === "string" && (
+    NUMERIC_FORMAT.test(format) || isUtcValueFormat(format)
+  )) {
+    return format;
+  }
+  const numericCandidate = typeof format === "string"
+    ? format.match(/^\.(\d+)(f|%|e)$/)
+    : undefined;
+  if (numericCandidate && Number(numericCandidate[1]) > 12) {
+    throw new RangeError(`${label} numeric format supports at most 12 decimals.`);
+  }
+  throw new TypeError(
+    `${label} must be auto${allowDecimalsObject ? ", { decimals }," : ","} or a supported format string (numeric or UTC).`
+  );
+}
+
+function pad(value, length = 2) {
+  return String(value).padStart(length, "0");
+}
+
+function formatUtcValue(value, format, label) {
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) {
+    throw new TypeError(`${label} requires a valid date or timestamp.`);
+  }
+  const values = {
+    Y: pad(date.getUTCFullYear(), 4),
+    m: pad(date.getUTCMonth() + 1),
+    d: pad(date.getUTCDate()),
+    b: MONTH_NAMES[date.getUTCMonth()]
+  };
+  return format.replace(/%([Ymdb%])/g, (_, directive) =>
+    directive === "%" ? "%" : values[directive]
+  );
+}
+
+export function formatValue(value, {
+  format = "auto",
+  valueType,
+  autoFormatter = current => String(current),
+  label = "Label format",
+  allowDecimalsObject = false
+} = {}) {
+  const resolved = validateValueFormat(format, label, {
+    allowDecimalsObject
+  });
+  if (value === undefined || value === null) return undefined;
+  if (resolved === "auto") return autoFormatter(value);
+  if (["nominal", "ordinal", "discrete"].includes(valueType)) {
+    throw new Error('Discrete labels require format "auto".');
+  }
+  const utc = isUtcValueFormat(resolved);
+  if (valueType === "temporal") {
+    if (!utc) throw new Error("Temporal labels require a supported UTC format string.");
+    return formatUtcValue(value, resolved, label);
+  }
+  if (utc) {
+    if (valueType === "quantitative") {
+      throw new Error("Quantitative labels cannot use a UTC format string.");
+    }
+    return formatUtcValue(value, resolved, label);
+  }
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${label} "${typeof resolved === "string" ? resolved : "decimals"}" requires a finite number.`);
+  }
+  if (typeof resolved === "object") return value.toFixed(resolved.decimals);
+  const match = resolved.match(NUMERIC_FORMAT);
+  const precision = Number(match[1]);
+  if (match[2] === "f") return value.toFixed(precision);
+  if (match[2] === "%") {
+    const percentage = value * 100;
+    if (!Number.isFinite(percentage)) {
+      throw new RangeError(`${label} percent format overflow.`);
+    }
+    return `${percentage.toFixed(precision)}%`;
+  }
+  return value.toExponential(precision);
+}