ggaction 0.0.13 → 0.0.16

package/src/actions/data/edit.js

@@ -0,0 +1,551 @@
+import { action, closedAction } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  findTransformPolicy,
+  normalizeDatasetTransformEdit,
+  requestedDatasetTransform
+} from "../../grammar/transforms.js";
+import {
+  findDataset,
+  hasDataset
+} from "../../selectors/datasets.js";
+import { applyLayerDataRematerialization } from
+  "../../materialization/dependencies.js";
+import {
+  outputFieldChanges,
+  rebindLayerOutputFields,
+  rebindMaterializationDataReferences
+} from "./revisionBindings.js";
+
+const GENERIC_OPTIONS = Object.freeze([
+  "target", "definition", "dependents"
+]);
+const DEPENDENT_POLICIES = new Set(["reject", "recompute"]);
+const CREATOR_BY_TYPE = Object.freeze({
+  bin: "createBinData",
+  bin2d: "createBin2DData",
+  complete: "createCompleteData",
+  computed: "createComputedData",
+  density: "createDensityData",
+  ecdf: "createECDFData",
+  filter: "filterData",
+  fold: "createFoldData",
+  impute: "createImputedData",
+  interval: "createIntervalData",
+  normalize: "createNormalizedData",
+  regression: "createRegressionData",
+  stack: "createStackData",
+  summary: "createSummaryData",
+  timeUnit: "createTimeUnitData",
+  window: "createWindowData"
+});
+const REVISION_ROLE = Object.freeze({
+  bin: "BinData",
+  bin2d: "Bin2DData",
+  complete: "CompleteData",
+  computed: "ComputedData",
+  density: "DensityData",
+  ecdf: "ECDFData",
+  filter: "FilteredData",
+  fold: "FoldData",
+  impute: "ImputedData",
+  interval: "IntervalData",
+  normalize: "NormalizedData",
+  regression: "RegressionData",
+  stack: "StackData",
+  summary: "SummaryData",
+  timeUnit: "TimeUnitData",
+  window: "WindowData"
+});
+
+function ownerRecords(program, type) {
+  const families = program.materializationConfigs.data ?? {};
+  return Object.entries(families).flatMap(([family, owners]) =>
+    Object.entries(owners ?? {}).flatMap(([owner, config]) => {
+      if (typeof config?.current !== "string") return [];
+      const dataset = findDataset(program, config.current);
+      const currentType = dataset?.transform?.[0]?.type ?? family;
+      if (type !== undefined && currentType !== type) return [];
+      return [{ family, owner, current: config.current, dataset }];
+    })
+  );
+}
+
+function escapedPattern(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function staleOwnerRecord(program, requested, type) {
+  return ownerRecords(program, type).find(record => {
+    const transformType = record.dataset?.transform?.[0]?.type ?? record.family;
+    const role = REVISION_ROLE[transformType];
+    if (role === undefined || requested === record.current) return false;
+    return new RegExp(
+      `^${escapedPattern(record.owner)}${role}Revision\\d+$`
+    ).test(requested);
+  });
+}
+
+function topLevelCreatorRecorded(program, dataset) {
+  const creator = CREATOR_BY_TYPE[dataset.transform?.[0]?.type];
+  return creator !== undefined && program.trace.children.some(node =>
+    node.op === creator && node.args?.id === dataset.id
+  );
+}
+
+export function resolveDerivedDataOwner(program, target, type) {
+  const requested = validateUserId(target, "Derived dataset target");
+  const matching = ownerRecords(program, type).filter(record =>
+    record.owner === requested || record.current === requested
+  );
+  if (matching.length > 1) {
+    throw new Error(`Derived dataset target "${requested}" is ambiguous.`);
+  }
+  if (matching.length === 1) {
+    const record = matching[0];
+    if (record.dataset === undefined) {
+      throw new Error(
+        `Derived dataset owner "${record.owner}" has no current dataset.`
+      );
+    }
+    return { ...record, lazy: false };
+  }
+
+  const dataset = findDataset(program, requested);
+  if (dataset === undefined) {
+    throw new Error(staleOwnerRecord(program, requested, type) !== undefined
+      ? `Derived dataset revision "${requested}" is stale.`
+      : `Unknown derived dataset owner "${requested}".`
+    );
+  }
+  if (staleOwnerRecord(program, requested, type) !== undefined) {
+    throw new Error(`Derived dataset revision "${requested}" is stale.`);
+  }
+  if (dataset.source === undefined || dataset.transform?.length !== 1) {
+    throw new Error(
+      `Dataset "${requested}" is a source dataset and cannot be edited.`
+    );
+  }
+  const currentType = dataset.transform[0].type;
+  if (type !== undefined && currentType !== type) {
+    throw new Error(
+      `Derived dataset "${requested}" is ${currentType}, not ${type}.`
+    );
+  }
+  if (
+    findTransformPolicy(currentType)?.editable !== true ||
+    !topLevelCreatorRecorded(program, dataset)
+  ) {
+    throw new Error(
+      `Derived dataset "${requested}" is chart-owned; use its owning chart editor.`
+    );
+  }
+  return {
+    family: currentType,
+    owner: dataset.id,
+    current: dataset.id,
+    dataset,
+    lazy: true
+  };
+}
+
+export function normalizeDerivedDependentPolicy(value) {
+  const policy = value ?? "reject";
+  if (!DEPENDENT_POLICIES.has(policy)) {
+    throw new Error(
+      'Derived data dependents must be "reject" or "recompute".'
+    );
+  }
+  return policy;
+}
+
+function downstreamDatasets(program, root) {
+  const order = new Map(
+    program.semanticSpec.datasets.map((dataset, index) => [dataset.id, index])
+  );
+  const bySource = new Map();
+  for (const dataset of program.semanticSpec.datasets) {
+    if (dataset.source === undefined) continue;
+    const children = bySource.get(dataset.source) ?? [];
+    children.push(dataset);
+    bySource.set(dataset.source, children);
+  }
+  for (const children of bySource.values()) {
+    children.sort((left, right) => order.get(left.id) - order.get(right.id));
+  }
+
+  const result = [];
+  const visiting = new Set();
+  const visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) {
+      throw new Error(`Derived dataset dependency graph contains a cycle at "${id}".`);
+    }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const child of bySource.get(id) ?? []) {
+      if (child.transform?.length !== 1) {
+        throw new Error(
+          `Derived dataset "${child.id}" requires one replayable transform.`
+        );
+      }
+      const policy = findTransformPolicy(child.transform[0].type);
+      if (typeof policy?.materializeOp !== "string") {
+        throw new Error(
+          `Derived dataset "${child.id}" has unsupported transform ` +
+          `"${child.transform[0].type ?? "unknown"}".`
+        );
+      }
+      // Statistical reference data is an owned cache. Its mark lifecycle
+      // reconnects and recomputes it after the visible source mark is rebound.
+      if (child.transform[0].type === "statisticalReference") continue;
+      result.push(child);
+      visit(child.id);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  }
+  visit(root);
+  return result;
+}
+
+function ownerForCurrent(program, dataset) {
+  const matches = ownerRecords(program).filter(record =>
+    record.current === dataset.id
+  );
+  if (matches.length > 1) {
+    throw new Error(
+      `Derived dataset "${dataset.id}" has ambiguous logical ownership.`
+    );
+  }
+  return matches[0];
+}
+
+function nextRevisionId(program, owner, role, reserved) {
+  let revision = 1;
+  const prefix = `${owner}${role}Revision`;
+  while (
+    hasDataset(program, `${prefix}${revision}`) ||
+    reserved.has(`${prefix}${revision}`)
+  ) revision += 1;
+  const id = `${prefix}${revision}`;
+  reserved.add(id);
+  return id;
+}
+
+function buildRevisionPlan(
+  program,
+  resolved,
+  definition,
+  dependents,
+  rootSource = resolved.dataset.source
+) {
+  const downstream = downstreamDatasets(program, resolved.current);
+  if (dependents === "reject" && downstream.length > 0) {
+    throw new Error(
+      `Cannot edit derived dataset "${resolved.owner}" while derived dataset ` +
+      `"${downstream[0].id}" depends on it; use dependents: "recompute".`
+    );
+  }
+  if (downstream.some(dataset => dataset.id === rootSource)) {
+    throw new Error(
+      `Derived dataset "${resolved.owner}" cannot use one of its dependents as source.`
+    );
+  }
+  const reserved = new Set(resolved.revision === undefined ? [] : [resolved.revision]);
+  const revisions = [];
+  const replacements = new Map();
+  const add = (dataset, ownerRecord, transform, requestedSource) => {
+    const owner = ownerRecord?.owner ?? dataset.id;
+    const role = REVISION_ROLE[transform.type] ?? "DerivedData";
+    const id = nextRevisionId(program, owner, role, reserved);
+    const originalSource = requestedSource ?? dataset.source;
+    const source = replacements.get(originalSource) ?? originalSource;
+    const revision = {
+      old: dataset.id,
+      id,
+      source,
+      transform,
+      family: ownerRecord?.family,
+      owner: ownerRecord?.owner
+    };
+    revisions.push(revision);
+    replacements.set(dataset.id, id);
+  };
+  if (resolved.revision === undefined) {
+    add(resolved.dataset, resolved, definition, rootSource);
+  } else {
+    revisions.push({ old: resolved.current, id: resolved.revision });
+    replacements.set(resolved.current, resolved.revision);
+  }
+  if (dependents === "recompute") {
+    for (const dataset of downstream) {
+      const policy = findTransformPolicy(dataset.transform[0].type);
+      const transform = policy.replayTransform?.(dataset.transform[0]) ??
+        dataset.transform[0];
+      add(dataset, ownerForCurrent(program, dataset), transform);
+    }
+  }
+  return { revisions, replacements };
+}
+
+function directLayerConsumers(program, data) {
+  return program.semanticSpec.layers
+    .filter(layer => layer.data === data)
+    .map(layer => layer.id);
+}
+
+export function applyRevisionPlan(program, resolved, plan, { retain = new Set() } = {}) {
+  const root = plan.revisions[0];
+  const changes = resolved === undefined ? new Map() : outputFieldChanges(
+    resolved.dataset.transform[0],
+    root.transform
+  );
+  let next = program;
+  for (const revision of plan.revisions) {
+    if (revision.transform === undefined) continue;
+    const policy = findTransformPolicy(revision.transform.type);
+    next = next.createDerivedData({
+      id: revision.id,
+      source: revision.source,
+      transform: [revision.transform]
+    });
+    if (revision.transform.type === "markFilter") {
+      next = next.rebindLayerData({
+        id: revision.transform.target,
+        data: revision.source
+      });
+    }
+    next = next[policy.materializeOp]({ id: revision.id });
+  }
+
+  const consumers = plan.revisions.flatMap(revision =>
+    directLayerConsumers(program, revision.old).map(id => ({
+      id,
+      old: revision.old,
+      data: revision.id,
+      root: revision.old === root.old
+    }))
+  );
+  for (const consumer of consumers) {
+    next = next.rebindLayerData({ id: consumer.id, data: consumer.data });
+  }
+  for (const consumer of consumers) {
+    if (consumer.root) {
+      next = rebindLayerOutputFields(next, consumer.id, changes);
+    }
+  }
+
+  next = rebindMaterializationDataReferences(next, plan.replacements);
+  for (const revision of plan.revisions) {
+    if (revision.owner !== undefined) {
+      next = next._withMaterializationConfig(
+        ["data", revision.family, revision.owner],
+        { current: revision.id }
+      );
+    }
+  }
+  for (const consumer of consumers) {
+    next = applyLayerDataRematerialization(next, consumer.id);
+  }
+  for (const revision of [...plan.revisions].reverse()) {
+    if (retain.has(revision.old)) continue;
+    next = next.releaseDerivedData({ id: revision.old });
+  }
+
+  const currentData = plan.replacements.get(program.context.currentData) ??
+    program.context.currentData;
+  return next._withContext({ ...program.context, currentData });
+}
+
+export function buildSourceRevisionPlan(program, source, id) {
+  return buildRevisionPlan(program, {
+    current: source, dataset: findDataset(program, source), revision: id
+  }, undefined, "recompute");
+}
+
+function sameRequested(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function reviseDerivedData(program, {
+  resolved,
+  definition,
+  dependents = "reject",
+  source = resolved.dataset.source
+}) {
+  const policy = normalizeDerivedDependentPolicy(dependents);
+  const plan = buildRevisionPlan(
+    program,
+    resolved,
+    definition,
+    policy,
+    source
+  );
+  applyRevisionPlan(program, resolved, plan);
+  return applyRevisionPlan(program, resolved, plan);
+}
+
+export const editDerivedData = /* @__PURE__ */ closedAction(
+  {
+    op: "editDerivedData",
+    description: "Atomically revise one standalone derived-data definition."
+  }, GENERIC_OPTIONS,
+  function (args = {}) {
+    if (!Object.hasOwn(args, "target")) {
+      throw new TypeError("editDerivedData requires target.");
+    }
+    if (!isPlainObject(args.definition)) {
+      throw new TypeError("editDerivedData definition must be a plain object.");
+    }
+    for (const forbidden of ["id", "source", "resolved", "current"]) {
+      if (Object.hasOwn(args.definition, forbidden)) {
+        throw new Error(`editDerivedData definition cannot include ${forbidden}.`);
+      }
+    }
+    const dependents = normalizeDerivedDependentPolicy(args.dependents);
+    const resolved = resolveDerivedDataOwner(
+      this,
+      args.target,
+      args.definition.type
+    );
+    const definition = requestedDatasetTransform(args.definition);
+    findTransformPolicy(definition.type).validate(definition);
+    const previous = requestedDatasetTransform(resolved.dataset.transform[0]);
+    if (sameRequested(definition, previous)) return this;
+
+    return reviseDerivedData(this, { resolved, definition, dependents });
+  }
+);
+
+function focusedEditor(op, type, properties) {
+  const supported = Object.freeze(["target", "dependents", ...properties]);
+  return action(
+    { op, description: `Partially revise one standalone ${type} dataset.` },
+    function (args = {}) {
+      validateKeys(args, supported, op);
+      if (!Object.hasOwn(args, "target")) {
+        throw new TypeError(`${op} requires target.`);
+      }
+      const patch = Object.fromEntries(Object.entries(args).filter(
+        ([key]) => key !== "target" && key !== "dependents"
+      ));
+      if (Object.keys(patch).length === 0) {
+        throw new Error(`${op} requires at least one transform option.`);
+      }
+      const undefinedKey = Object.keys(patch).find(
+        key => patch[key] === undefined
+      );
+      if (undefinedKey !== undefined) {
+        throw new TypeError(
+          `${op} ${undefinedKey} cannot be undefined; omission preserves it.`
+        );
+      }
+      const resolved = resolveDerivedDataOwner(this, args.target, type);
+      const definition = normalizeDatasetTransformEdit(
+        resolved.dataset.transform[0],
+        patch,
+        resolved.owner
+      );
+      return this.editDerivedData({
+        target: args.target,
+        definition,
+        ...(args.dependents === undefined
+          ? {}
+          : { dependents: args.dependents })
+      });
+    }
+  );
+}
+
+export const editComputedData = /* @__PURE__ */ focusedEditor(
+  "editComputedData", "computed", ["as", "expression"]
+);
+export const editFilteredData = /* @__PURE__ */ focusedEditor(
+  "editFilteredData", "filter", ["field", "oneOf", "predicate", "range"]
+);
+export const editFoldData = /* @__PURE__ */ focusedEditor(
+  "editFoldData", "fold", ["fields", "as"]
+);
+export const editSummaryData = /* @__PURE__ */ focusedEditor(
+  "editSummaryData", "summary", ["groupBy", "aggregates", "members", "weight"]
+);
+export const editBinData = /* @__PURE__ */ focusedEditor(
+  "editBinData", "bin", [
+    "field", "maxBins", "step", "boundaries", "extent", "nice", "zero",
+    "includeEmpty", "members", "as", "weight"
+  ]
+);
+export const editTimeUnitData = /* @__PURE__ */ focusedEditor(
+  "editTimeUnitData", "timeUnit", [
+    "field", "unit", "as", "temporalUnit", "timeZone", "weekStartsOn",
+    "weekRule"
+  ]
+);
+export const editWindowData = /* @__PURE__ */ focusedEditor(
+  "editWindowData", "window", [
+    "partitionBy", "sortBy", "operations", "temporalUnit"
+  ]
+);
+export const editDensityData = /* @__PURE__ */ focusedEditor(
+  "editDensityData", "density", [
+    "field", "groupBy", "bandwidth", "extent", "steps", "kernel",
+    "normalization", "as", "weight"
+  ]
+);
+export const editStackData = /* @__PURE__ */ focusedEditor(
+  "editStackData", "stack", ["category", "group", "value", "mode", "as"]
+);
+export const editRegressionData = /* @__PURE__ */ focusedEditor(
+  "editRegressionData", "regression", [
+    "x", "y", "groupBy", "method", "degree", "span", "confidenceMethod",
+    "level", "confidence", "interval"
+  ]
+);
+export const editIntervalData = /* @__PURE__ */ focusedEditor(
+  "editIntervalData", "interval", [
+    "field", "groupBy", "center", "extent", "method", "level", "as"
+  ]
+);
+export const editECDFData = /* @__PURE__ */ focusedEditor(
+  "editECDFData", "ecdf", [
+    "field", "groupBy", "weight", "missing", "as"
+  ]
+);
+export const editNormalizedData = /* @__PURE__ */ focusedEditor(
+  "editNormalizedData", "normalize", [
+    "field", "as", "groupBy", "method", "variance", "zeroDenominator",
+    "baseline", "sortBy"
+  ]
+);
+export const editCompleteData = /* @__PURE__ */ focusedEditor(
+  "editCompleteData", "complete", [
+    "key", "groupBy", "values", "sequence", "fill", "members"
+  ]
+);
+export const editImputedData = /* @__PURE__ */ focusedEditor(
+  "editImputedData", "impute", [
+    "fields", "groupBy", "sortBy", "method", "value", "edges", "maxGap"
+  ]
+);
+
+export const EDIT_DERIVED_DATA_ACTIONS = Object.freeze({
+  editDerivedData,
+  editComputedData,
+  editFilteredData,
+  editFoldData,
+  editSummaryData,
+  editBinData,
+  editTimeUnitData,
+  editWindowData,
+  editDensityData,
+  editStackData,
+  editRegressionData,
+  editIntervalData,
+  editECDFData,
+  editNormalizedData,
+  editCompleteData,
+  editImputedData
+});

package/src/actions/data/filter.js

@@ -1,6 +1,6 @@
-import { action } from "../../core/action.js";
+import { closedAction } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
-import { validateKeys } from "../../core/validation.js";
+
 import { withPreviewDatasetValues } from
   "../primitives/semanticAction.js";
 import {
@@ -22,6 +22,7 @@ import {
 import {
   hasDataset,
   findDataset,
+  resolveDatasetReference,
   requireLayer,
   resolveEligibleLayer
 } from "../../selectors/index.js";
@@ -49,10 +50,9 @@ function retainedHistogramBoundaries(layer, items) {
   return boundaries.length < 2 ? undefined : boundaries;
 }
 
-export const materializeFilteredData = action(
-  { op: "materializeFilteredData", description: "Materialize one filtered derived dataset." },
+export const materializeFilteredData = /* @__PURE__ */ closedAction(
+  { op: "materializeFilteredData", description: "Materialize one filtered derived dataset." }, MATERIALIZE_OPTIONS,
   function (args = {}) {
-    validateKeys(args, MATERIALIZE_OPTIONS, "materializeFilteredData");
     const { id, source, transform } = requireDerivedDataset(
       this,
       args.id,
@@ -65,33 +65,42 @@ export const materializeFilteredData = action(
   }
 );
 
-export const filterData = action(
-  { op: "filterData", description: "Create a named dataset from one field filter." },
+export const filterData = /* @__PURE__ */ closedAction(
+  { op: "filterData", description: "Create a named dataset from one field filter." }, OPTIONS,
   function (args = {}) {
-    validateKeys(args, OPTIONS, "filterData");
     const id = validateUserId(args.id, "Filtered dataset id");
-    const source = validateUserId(
+    const requestedSource = validateUserId(
       args.source ?? this.context.currentData,
       "Source dataset id"
     );
+    const source = resolveDatasetReference(
+      this,
+      requestedSource,
+      "Filter source dataset"
+    ).id;
     const transform = normalizeFilterTransform(args);
-    return this
+    const next = this
       .createDerivedData({
         id,
         source,
         transform: [transform]
       })
       .materializeFilteredData({ id });
+    return this.actionStack.length === 1
+      ? next._withMaterializationConfig(
+          ["data", "filter", id],
+          { current: id }
+        )
+      : next;
   }
 );
 
-export const materializeMarkFilteredData = action(
+export const materializeMarkFilteredData = /* @__PURE__ */ closedAction(
   {
     op: "materializeMarkFilteredData",
     description: "Materialize member rows retained by one final-item mark selection."
-  },
+  }, MATERIALIZE_OPTIONS,
   function (args = {}) {
-    validateKeys(args, MATERIALIZE_OPTIONS, "materializeMarkFilteredData");
     const { id, dataset, source, transform } = requireDerivedDataset(
       this,
       args.id,
@@ -158,13 +167,12 @@ export const materializeMarkFilteredData = action(
   }
 );
 
-export const materializeEmptyMark = action(
+export const materializeEmptyMark = /* @__PURE__ */ closedAction(
   {
     op: "materializeEmptyMark",
     description: "Clear one active empty-filter mark without changing its domains."
-  },
+  }, EMPTY_MARK_OPTIONS,
   function (args = {}) {
-    validateKeys(args, EMPTY_MARK_OPTIONS, "materializeEmptyMark");
     const id = validateUserId(args.id, "Empty mark id");
     const layer = requireLayer(this, id);
     const owner = this.markConfigs[id]?.markFilter;
@@ -249,13 +257,12 @@ function sameSelector(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
-export const removeMarkFilter = action(
+export const removeMarkFilter = /* @__PURE__ */ closedAction(
   {
     op: "removeMarkFilter",
     description: "Remove one active final-item filter and restore its source."
-  },
+  }, REMOVE_MARK_FILTER_OPTIONS,
   function (args = {}) {
-    validateKeys(args, REMOVE_MARK_FILTER_OPTIONS, "removeMarkFilter");
     const target = args.target === undefined
       ? undefined
       : validateUserId(args.target, "Mark filter target id");
@@ -268,13 +275,12 @@ export const removeMarkFilter = action(
   }
 );
 
-export const filterMarks = action(
+export const filterMarks = /* @__PURE__ */ closedAction(
   {
     op: "filterMarks",
     description: "Retain selected final mark items through immutable derived data."
-  },
+  }, MARK_OPTIONS,
   function (args = {}) {
-    validateKeys(args, MARK_OPTIONS, "filterMarks");
     if (args.mode !== undefined && !["replace", "compose"].includes(args.mode)) {
       throw new Error(`Unknown mark filter mode "${args.mode}".`);
     }

package/src/actions/data/fold.js

@@ -6,14 +6,14 @@ import { derivedCreator, derivedMaterializer } from "./shared.js";
 
 const OPTIONS = Object.freeze(["id", "source", "fields", "as"]);
 
-export const materializeFoldData = derivedMaterializer(
+export const materializeFoldData = /* @__PURE__ */ derivedMaterializer(
   "materializeFoldData",
   "Materialize one immutable wide-to-long dataset.",
   "fold",
   deriveFoldRows
 );
 
-export const createFoldData = derivedCreator(
+export const createFoldData = /* @__PURE__ */ derivedCreator(
   "createFoldData",
   "Create reusable key/value rows from selected wide fields.",
   OPTIONS,