ggaction 0.0.13 → 0.0.15

package/src/actions/coordinates/edit.js

@@ -0,0 +1,76 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { normalizeCoordinateAspect } from "../../grammar/coordinates.js";
+import { normalizePolarFrameOptions } from "../../grammar/polar.js";
+import {
+  applyMaterializationPlan,
+  planCoordinateRematerialization
+} from "../../materialization/dependencies.js";
+import { requireCoordinate } from "../../selectors/coordinates.js";
+
+const EDIT_COORDINATE_OPTIONS = Object.freeze(["target", "aspect", "polarFrame"]);
+
+function applyCoordinatePatch(program, target, property, value) {
+  const coordinate = requireCoordinate(program, target);
+  if (value === "auto") {
+    return coordinate[property] === undefined
+      ? program
+      : program.editSemantic({
+          property: `coordinate[${target}].${property}`,
+          remove: true
+        });
+  }
+  return program.editSemantic({
+    property: `coordinate[${target}].${property}`,
+    value
+  });
+}
+
+export const editCoordinate = action(
+  {
+    op: "editCoordinate",
+    description: "Edit coordinate layout constraints and rematerialize its consumers."
+  },
+  function (args = {}) {
+    validateOptionObject(args, EDIT_COORDINATE_OPTIONS, "editCoordinate", {
+      allowEmpty: false,
+      emptyMessage: "editCoordinate requires aspect or polarFrame changes.",
+      emptyError: Error
+    });
+    const target = validateUserId(args.target, "Coordinate id");
+    const coordinate = requireCoordinate(this, target);
+    const hasAspect = Object.hasOwn(args, "aspect");
+    const hasPolarFrame = Object.hasOwn(args, "polarFrame");
+    if (!hasAspect && !hasPolarFrame) {
+      throw new Error("editCoordinate requires aspect or polarFrame changes.");
+    }
+    const aspect = hasAspect ? normalizeCoordinateAspect(args.aspect) : undefined;
+    if (hasPolarFrame && coordinate.type !== "polar") {
+      throw new Error("editCoordinate polarFrame requires a Polar coordinate.");
+    }
+    const polarFrame = hasPolarFrame
+      ? normalizePolarFrameOptions(args.polarFrame)
+      : undefined;
+    let proposed = this;
+    if (hasAspect) {
+      proposed = applyCoordinatePatch(proposed, target, "aspect", aspect);
+    }
+    if (hasPolarFrame) {
+      proposed = applyCoordinatePatch(
+        proposed,
+        target,
+        "polarFrame",
+        polarFrame
+      );
+    }
+    const plan = planCoordinateRematerialization(proposed, target);
+    // Validate the complete dependent geometry on a discarded immutable branch.
+    applyMaterializationPlan(proposed, plan);
+    return applyMaterializationPlan(proposed, plan);
+  }
+);
+
+export function registerCoordinateEditActions(ProgramClass) {
+  ProgramClass.prototype.editCoordinate = editCoordinate;
+}

package/src/actions/data/bin.js

@@ -7,7 +7,7 @@ import { derivedCreator, derivedMaterializer } from "./shared.js";
 
 const OPTIONS = Object.freeze([
   "id", "source", "field", "maxBins", "step", "boundaries", "extent",
-  "nice", "zero", "includeEmpty", "members", "as"
+  "nice", "zero", "includeEmpty", "members", "as", "weight"
 ]);
 
 export const materializeBinData = derivedMaterializer(

package/src/actions/data/bin2d.js

@@ -6,24 +6,28 @@ import {
   normalizeBin2DTransform,
   requestedBin2DTransform
 } from "../../grammar/bin2d.js";
-import { applyLayerDataRematerialization } from
-  "../../materialization/dependencies.js";
-import { planDerivedDataRevision } from
-  "../../materialization/dataProvenance.js";
 import {
   findDataset,
-  findDatasetConsumer
+  resolveDatasetReference
 } from "../../selectors/datasets.js";
-import { requireLayer } from "../../selectors/layers.js";
+import {
+  normalizeDerivedDependentPolicy,
+  resolveDerivedDataOwner,
+  reviseDerivedData
+} from "./edit.js";
+import { normalizeDatasetTransformEdit } from "../../grammar/transforms.js";
 export { materializeBin2DData } from "./bin2dMaterialize.js";
 
 const OPTIONS = Object.freeze([
   "id", "source", "x", "y", "bins", "extent", "includeEmpty", "members", "as"
 ]);
 const EDIT_OPTIONS = Object.freeze([
-  "target", "source", "x", "y", "bins", "extent", "includeEmpty", "members", "as"
+  "target", "source", "x", "y", "bins", "extent", "includeEmpty",
+  "members", "as", "dependents"
 ]);
-const EDITABLE = Object.freeze(EDIT_OPTIONS.slice(1));
+const EDITABLE = Object.freeze(EDIT_OPTIONS.filter(option =>
+  !["target", "dependents"].includes(option)
+));
 const OUTPUT_FIELDS = Object.freeze([
   "x0", "x1", "y0", "y1", "count", "members"
 ]);
@@ -69,122 +73,6 @@ function requireCurrentBin2D(program, id, config) {
   return current;
 }
 
-function directLayerConsumers(program, data) {
-  return program.semanticSpec.layers
-    .filter(layer => layer.data === data)
-    .map(layer => layer.id);
-}
-
-function outputFieldChanges(previous, next) {
-  return new Map(OUTPUT_FIELDS.flatMap(role => {
-    const from = previous.as[role];
-    const to = next.as[role];
-    return from !== undefined && from !== to
-      ? [[from, [role, to]]]
-      : [];
-  }));
-}
-
-function changedConsumerField(field, changes) {
-  const change = changes.get(field);
-  if (change === undefined) return field;
-  const [role, next] = change;
-  if (next === undefined) {
-    throw new Error(
-      `Cannot remove referenced 2D bin ${role} output field "${field}".`
-    );
-  }
-  return next;
-}
-
-function rebindLayerOutputFields(program, id, changes) {
-  const layer = requireLayer(program, id);
-  let next = program;
-  const changed = field => changedConsumerField(field, changes);
-  const editField = (property, field) => {
-    if (field === undefined) return;
-    const value = changed(field);
-    if (value !== field) next = next.editSemantic({ property, value });
-  };
-  for (const [channel, encoding] of Object.entries(layer.encoding ?? {})) {
-    editField(
-      `layer[${id}].encoding.${channel}.field`,
-      encoding?.field
-    );
-    const summary = encoding?.categoryOrder?.by;
-    if (summary?.field !== undefined) {
-      const field = changed(summary.field);
-      if (field !== summary.field) {
-        next = next.editSemantic({
-          property: `layer[${id}].encoding.${channel}.categoryOrder`,
-          value: { ...encoding.categoryOrder, by: { ...summary, field } }
-        });
-      }
-    }
-  }
-  editField(
-    `layer[${id}].encoding.theta.weight`,
-    layer.encoding?.theta?.weight
-  );
-
-  const parallel = layer.encoding?.parallel;
-  if (parallel?.dimensions !== undefined) {
-    const dimensions = parallel.dimensions.map(dimension => {
-      const field = changed(dimension.field);
-      return { ...dimension, field };
-    });
-    if (dimensions.some((dimension, index) =>
-      dimension.field !== parallel.dimensions[index].field
-    )) {
-      next = next.editSemantic({
-        property: `layer[${id}].encoding.parallel.dimensions`,
-        value: dimensions
-      });
-    }
-  }
-  editField(
-    `layer[${id}].encoding.parallel.key`,
-    parallel?.key
-  );
-
-  for (const [selectionId, config] of Object.entries(
-    program.materializationConfigs.selections ?? {}
-  )) {
-    if (config.target !== id) continue;
-    const selector = { ...config.selector };
-    if (selector.field !== undefined) {
-      selector.field = changed(selector.field);
-    }
-    if (selector.groupBy !== undefined) {
-      selector.groupBy = selector.groupBy.map(changed);
-    }
-    if (JSON.stringify(selector) !== JSON.stringify(config.selector)) {
-      next = next._withSelectionConfig(selectionId, { ...config, selector });
-    }
-  }
-
-  const jitter = program.materializationConfigs.jitters?.[id];
-  const key = jitter?.key === undefined
-    ? undefined
-    : changed(jitter.key);
-  if (key !== undefined && key !== jitter.key) {
-    next = next._withMaterializationConfig(
-      ["jitters", id], { ...jitter, key }
-    );
-  }
-  return next;
-}
-
-function rejectDerivedConsumers(program, data) {
-  const dependent = findDatasetConsumer(program, data);
-  if (dependent !== undefined) {
-    throw new Error(
-      `Cannot replace 2D bin dataset "${data}" while derived dataset ` +
-      `"${dependent.id}" depends on it.`
-    );
-  }
-}
-
 function preflight(program, sourceId, transform) {
   const source = findDataset(program, sourceId);
   if (source?.values === undefined) {
@@ -204,32 +92,18 @@ function requireCompleteEditOutputFields(value, members) {
 }
 
 function editedTransform(owner, previous, args) {
-  const prior = requestedBin2DTransform(previous.transform[0]);
-  const option = property => Object.hasOwn(args, property)
-    ? args[property]
-    : prior[property];
-  const members = option("members");
-  let as = option("as");
-  if (!Object.hasOwn(args, "as")) {
-    as = { ...as };
-    if (members && as.members === undefined) {
-      as.members = `__${owner}_members`;
-    } else if (!members) {
-      delete as.members;
-    }
-  }
-  const transform = normalizeBin2DTransform({
-    id: owner,
-    x: option("x"),
-    y: option("y"),
-    bins: option("bins"),
-    extent: option("extent"),
-    includeEmpty: option("includeEmpty"),
-    members,
-    as
-  });
+  const patch = Object.fromEntries(EDITABLE.flatMap(property =>
+    property !== "source" && Object.hasOwn(args, property)
+      ? [[property, args[property]]]
+      : []
+  ));
+  const transform = normalizeDatasetTransformEdit(
+    previous.transform[0],
+    patch,
+    owner
+  );
   if (Object.hasOwn(args, "as")) {
-    requireCompleteEditOutputFields(args.as, members);
+    requireCompleteEditOutputFields(args.as, transform.members);
   }
   return transform;
 }
@@ -238,29 +112,18 @@ function sameRequestedTransform(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
-function applyBin2DRevision(program, { owner, previous, source, transform }) {
-  rejectDerivedConsumers(program, previous.id);
-  const consumers = directLayerConsumers(program, previous.id);
-  const changes = outputFieldChanges(previous.transform[0], transform);
-  const revision = planDerivedDataRevision(program, {
-    owner,
-    role: "Bin2DData",
-    previous: previous.id,
-    consumers
+function applyBin2DRevision(program, {
+  owner,
+  source,
+  transform,
+  dependents = "reject"
+}) {
+  return reviseDerivedData(program, {
+    resolved: resolveDerivedDataOwner(program, owner, "bin2d"),
+    definition: transform,
+    dependents,
+    source
   });
-  let next = program
-    .createDerivedData({ id: revision.id, source, transform: [transform] })
-    .materializeBin2DData({ id: revision.id });
-  for (const rebind of revision.rebinds) {
-    next = next.rebindLayerData(rebind);
-    next = rebindLayerOutputFields(next, rebind.id, changes);
-    next = applyLayerDataRematerialization(next, rebind.id);
-  }
-  next = next.releaseDerivedData(revision.release);
-  return next._withMaterializationConfig(
-    ["data", "bin2d", owner],
-    { current: revision.id }
-  );
 }
 
 export const createBin2DData = action(
@@ -275,10 +138,14 @@ export const createBin2DData = action(
     const previous = config === undefined
       ? undefined
       : requireCurrentBin2D(this, owner, config);
-    const source = validateUserId(
-      args.source ?? previous?.source ?? this.context.currentData,
-      "Source dataset id"
-    );
+    const source = resolveDatasetReference(
+      this,
+      validateUserId(
+        args.source ?? previous?.source ?? this.context.currentData,
+        "Source dataset id"
+      ),
+      "Source dataset"
+    ).id;
     const transform = normalizeBin2DTransform({ ...args, id: owner });
     preflight(this, source, transform);
 
@@ -313,10 +180,15 @@ export const editBin2DData = action(
     }
     const owner = resolveBin2DOwner(this, args.target);
     const previous = requireCurrentBin2D(this, owner, ownerConfig(this, owner));
-    const source = validateUserId(
-      args.source ?? previous.source,
-      "2D bin source dataset id"
-    );
+    const dependents = normalizeDerivedDependentPolicy(args.dependents);
+    const source = resolveDatasetReference(
+      this,
+      validateUserId(
+        args.source ?? previous.source,
+        "2D bin source dataset id"
+      ),
+      "2D bin source dataset"
+    ).id;
     const transform = editedTransform(owner, previous, args);
     if (
       source === previous.source &&
@@ -328,11 +200,11 @@ export const editBin2DData = action(
       throw new Error("editBin2DData requires an actual transform or source change.");
     }
     preflight(this, source, transform);
-    const revision = { owner, previous, source, transform };
-
-    // Execute one speculative immutable branch so every consumer plan is known
-    // to succeed before the returned action trace records its first child.
-    applyBin2DRevision(this, revision);
-    return applyBin2DRevision(this, revision);
+    return applyBin2DRevision(this, {
+      owner,
+      source,
+      transform,
+      dependents
+    });
   }
 );

package/src/actions/data/complete.js

@@ -0,0 +1,26 @@
+import {
+  deriveCompleteRows,
+  normalizeCompleteTransform
+} from "../../grammar/complete.js";
+import { derivedCreator, derivedMaterializer } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "key", "groupBy", "values", "sequence", "fill", "members"
+]);
+
+export const materializeCompleteData = derivedMaterializer(
+  "materializeCompleteData",
+  "Materialize one immutable completed-key dataset.",
+  "complete",
+  deriveCompleteRows
+);
+
+export const createCompleteData = derivedCreator(
+  "createCompleteData",
+  "Complete one key domain independently within observed groups.",
+  OPTIONS,
+  "Complete dataset id",
+  "Complete source dataset id",
+  normalizeCompleteTransform,
+  "materializeCompleteData"
+);

package/src/actions/data/computed.js

@@ -8,14 +8,14 @@ const OPTIONS = Object.freeze(["id", "source", "as", "expression"]);
 
 export const materializeComputedData = derivedMaterializer(
   "materializeComputedData",
-  "Materialize one immutable row-level arithmetic dataset.",
+  "Materialize one immutable row-level typed expression dataset.",
   "computed",
   deriveComputedRows
 );
 
 export const createComputedData = derivedCreator(
   "createComputedData",
-  "Create a finite computed field from a closed arithmetic expression.",
+  "Create a typed computed field from a closed expression.",
   OPTIONS,
   "Computed dataset id",
   "Computed source dataset id",

package/src/actions/data/create.js

@@ -2,7 +2,7 @@ import { action } from "../../core/action.js";
 import { resolveOptionalUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateKeys } from "../../core/validation.js";
-import { hasDataset } from "../../selectors/index.js";
+import { hasDataset, hasDatasetOwner } from "../../selectors/index.js";
 
 const OPTIONS = Object.freeze(["id", "values"]);
 
@@ -22,7 +22,7 @@ export const createData = action(
     if (!args.values.every(isPlainObject)) {
       throw new TypeError("createData requires every row to be a plain object.");
     }
-    if (hasDataset(this, id)) {
+    if (hasDataset(this, id) || hasDatasetOwner(this, id)) {
       throw new Error(`Dataset "${id}" already exists.`);
     }
     return this.editSemantic({

package/src/actions/data/density.js

@@ -1,28 +1,15 @@
-import { deriveKernelDensity } from "../../grammar/density.js";
+import {
+  deriveKernelDensity,
+  normalizeDensityTransform
+} from "../../grammar/density.js";
 import { derivedCreator, derivedMaterializer } from "./shared.js";
 
 const OPTIONS = Object.freeze([
   "id", "source", "field", "groupBy", "bandwidth", "extent", "steps",
-  "kernel", "normalization", "as"
+  "kernel", "normalization", "as", "weight"
 ]);
 const CATEGORICAL_OPTIONS = Object.freeze([...OPTIONS, "placement"]);
 
-function densityTransform(args, placement) {
-  return {
-    type: "density",
-    field: args.field,
-    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
-    bandwidth: args.bandwidth ?? "auto",
-    extent: args.extent ?? "auto",
-    steps: args.steps ?? 100,
-    kernel: args.kernel ?? "gaussian",
-    normalization: args.normalization ?? "unit",
-    as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
-    resolve: "shared",
-    ...(placement === undefined ? {} : { placement })
-  };
-}
-
 function requestedTransform(args, op, categorical = false) {
   if (typeof args.field !== "string" || args.field.length === 0) {
     throw new TypeError(`${op} requires a non-empty field string.`);
@@ -32,7 +19,10 @@ function requestedTransform(args, op, categorical = false) {
       "createCategoricalDensityData requires normalized category placement."
     );
   }
-  return densityTransform(args, categorical ? args.placement : undefined);
+  return normalizeDensityTransform({
+    ...args,
+    ...(categorical ? { placement: args.placement } : {})
+  });
 }
 
 export const materializeDensityData = derivedMaterializer(
@@ -43,7 +33,9 @@ export const materializeDensityData = derivedMaterializer(
   (result, transform) => [{
     ...transform,
     resolved: {
-      bandwidth: result.bandwidth,
+      ...(result.bandwidth === undefined
+        ? { bandwidths: result.bandwidths }
+        : { bandwidth: result.bandwidth }),
       extent: result.extent,
       ...(result.splitDomain === undefined
         ? {}

package/src/actions/data/derived.js

@@ -1,11 +1,16 @@
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
-import { hasDataset } from "../../selectors/index.js";
-import { findDataset } from "../../selectors/datasets.js";
+import {
+  findDataset,
+  hasDataset,
+  hasDatasetOwner,
+  resolveDatasetReference
+} from "../../selectors/datasets.js";
 import { requireLayer } from "../../selectors/layers.js";
 import { applyLayerDataRematerialization } from
   "../../materialization/dependencies.js";
+import { collectResourceReferences } from "../../core/resourceReferences.js";
 
 const OPTIONS = Object.freeze(["id", "source", "transform"]);
 const RELEASE_OPTIONS = Object.freeze(["id"]);
@@ -18,7 +23,8 @@ const OWNED_MARK_ROLES = Object.freeze([
   "errorBar",
   "gradientPlot",
   "ecdfPlot",
-  "regression"
+  "regression",
+  "statisticalReference"
 ]);
 
 export const createDerivedData = action(
@@ -26,8 +32,13 @@ export const createDerivedData = action(
   function (args = {}) {
     validateKeys(args, OPTIONS, "createDerivedData");
     const id = validateUserId(args.id, "Derived dataset id");
-    const source = validateUserId(args.source, "Source dataset id");
-    if (hasDataset(this, id)) {
+    const requestedSource = validateUserId(args.source, "Source dataset id");
+    const source = resolveDatasetReference(
+      this,
+      requestedSource,
+      "Source dataset"
+    ).id;
+    if (hasDataset(this, id) || hasDatasetOwner(this, id)) {
       throw new Error(`Dataset "${id}" already exists.`);
     }
     if (!hasDataset(this, source)) {
@@ -51,17 +62,26 @@ export const releaseDerivedData = action(
     if (dataset === undefined || dataset.source === undefined) {
       throw new Error(`Unknown derived dataset "${validatedId}".`);
     }
-    const referenced = this.semanticSpec.layers.some(
-      layer => layer.data === validatedId
-    ) || this.semanticSpec.datasets.some(
-      candidate => candidate.source === validatedId
+    const references = collectResourceReferences(this, {
+      kind: "data",
+      id: validatedId
+    });
+    const selfOwners = references.filter(reference =>
+      reference.ownerKind === "dataOwner" &&
+      reference.path.at(-1) === "current"
     );
-    return referenced
-      ? this
-      : this.editSemantic({
-          property: `dataset[${validatedId}]`,
-          remove: true
-        });
+    if (references.some(reference =>
+      reference.strength === "live" && !selfOwners.includes(reference)
+    )) return this;
+    let next = this.editSemantic({
+      property: `dataset[${validatedId}]`,
+      remove: true
+    });
+    for (const owner of selfOwners) {
+      const [, family, ownerId] = owner.path;
+      next = next._withoutMaterializationConfig(["data", family, ownerId]);
+    }
+    return next;
   }
 );
 
@@ -73,7 +93,12 @@ export const rebindLayerData = action(
   function (args = {}) {
     validateKeys(args, REBIND_OPTIONS, "rebindLayerData");
     const id = validateUserId(args.id, "Layer id");
-    const data = validateUserId(args.data, "Layer dataset id");
+    const requestedData = validateUserId(args.data, "Layer dataset id");
+    const data = resolveDatasetReference(
+      this,
+      requestedData,
+      "Layer dataset"
+    ).id;
     requireLayer(this, id);
     if (!hasDataset(this, data)) {
       throw new Error(`Layer dataset "${data}" does not exist.`);
@@ -117,7 +142,12 @@ export const bindMarkData = action(
   function (args = {}) {
     validateKeys(args, BIND_OPTIONS, "bindMarkData");
     const target = validateUserId(args.target, "Mark target id");
-    const data = validateUserId(args.data, "Mark dataset id");
+    const requestedData = validateUserId(args.data, "Mark dataset id");
+    const data = resolveDatasetReference(
+      this,
+      requestedData,
+      "Mark dataset"
+    ).id;
     const layer = requireLayer(this, target);
     const dataset = findDataset(this, data);
     if (dataset === undefined) {