ggaction 0.0.16 → 0.0.18

package/src/grammar/areaSeries.js

@@ -13,30 +13,31 @@ function indexSegments(segments) {
   return indexed;
 }
 
-export function deriveAreaSeries(rows, layer) {
+export function deriveAreaSeries(rows, layer, options = {}) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Area series derivation requires a semantic area mark.");
   }
   const { x, y, x2, y2 } = layer.encoding ?? {};
   const vertical =
-    ["quantitative", "temporal"].includes(x?.fieldType) &&
+    ["quantitative", "temporal", "nominal", "ordinal"].includes(x?.fieldType) &&
     y?.fieldType === "quantitative" &&
     y2?.fieldType === "quantitative" &&
     x2 === undefined;
   const horizontal =
-    ["quantitative", "temporal"].includes(y?.fieldType) &&
+    ["quantitative", "temporal", "nominal", "ordinal"].includes(y?.fieldType) &&
     x?.fieldType === "quantitative" &&
     x2?.fieldType === "quantitative" &&
     y2 === undefined;
   if (vertical === horizontal) {
     throw new Error(
-      `Area mark "${layer.id}" requires exactly one quantitative x/x2 or y/y2 range and one quantitative or temporal independent position.`
+      `Area mark "${layer.id}" requires exactly one quantitative x/x2 or y/y2 range and one quantitative, temporal, or categorical independent position.`
     );
   }
   const grouping = validatePathSeriesAppearance(rows, layer);
   const orientation = vertical ? "vertical" : "horizontal";
   const independent = vertical ? x : y;
-  const independentValues = independent.fieldType === "temporal"
+  const categorical = ["nominal", "ordinal"].includes(independent.fieldType);
+  const independentValues = categorical ? readNominalField(rows, independent.field) : independent.fieldType === "temporal"
     ? readTemporalField(rows, independent.field, independent.temporalUnit)
     : readQuantitativeField(rows, independent.field);
   if (Object.hasOwn(independent, "datum")) throw new Error("Area independent position requires a field.");
@@ -46,6 +47,9 @@ export function deriveAreaSeries(rows, layer) {
   const missing = layer.mark.missing ?? "error";
   const lower = readAreaEndpoint(rows, primary, missing);
   const upper = readAreaEndpoint(rows, secondary, missing);
+  const categoryOrder = categorical ? options[vertical ? "xDomain" : "yDomain"] ?? [...new Set(independentValues)] : undefined;
+  const ranks = new Map(categoryOrder?.map((value, index) => [value, index]));
+  if (categorical && independentValues.some(value => !ranks.has(value))) throw new Error("Area categorical domain must contain every observed position.");
   const pathOrder = layer.encoding?.pathOrder;
   const orderValues = pathOrder === undefined
     ? undefined
@@ -83,7 +87,7 @@ export function deriveAreaSeries(rows, layer) {
   const series = [...groups.values()].flatMap(item => {
     const key = vertical ? "x" : "y";
     const values = pathOrder === undefined
-      ? item.values.sort((left, right) => left[key] - right[key])
+      ? item.values.sort((left, right) => categorical ? ranks.get(left[key]) - ranks.get(right[key]) : left[key] - right[key])
       : stableOrderPathValues(
           item.values.map(({ pathOrder: _pathOrder, ...value }) => value),
           item.values.map(value => value.pathOrder),
@@ -125,13 +129,13 @@ export function deriveAreaSeries(rows, layer) {
   });
 }
 
-export function deriveCenteredAreaSeries(rows, layer) {
+export function deriveCenteredAreaSeries(rows, layer, options = {}) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Centered area series derivation requires an area mark.");
   }
   const { x, y, x2, y2, group, color } = layer.encoding ?? {};
   if (
-    !["quantitative", "temporal"].includes(x?.fieldType) ||
+    !["quantitative", "temporal", "nominal", "ordinal"].includes(x?.fieldType) ||
     y?.fieldType !== "quantitative" ||
     y?.stack !== "center" ||
     x2 !== undefined ||
@@ -149,7 +153,8 @@ export function deriveCenteredAreaSeries(rows, layer) {
       `Centered area color on mark "${layer.id}" must match its group field.`
     );
   }
-  const xValues = x.fieldType === "temporal"
+  const categorical = ["nominal", "ordinal"].includes(x.fieldType);
+  const xValues = categorical ? readNominalField(rows, x.field) : x.fieldType === "temporal"
     ? readTemporalField(rows, x.field, x.temporalUnit)
     : readQuantitativeField(rows, x.field);
   const yValues = readQuantitativeField(rows, y.field);
@@ -172,7 +177,10 @@ export function deriveCenteredAreaSeries(rows, layer) {
     values.set(xValues[index], yValues[index]);
     positions.add(xValues[index]);
   }
-  const orderedPositions = [...positions].sort((left, right) => left - right);
+  const orderedPositions = categorical
+    ? (options.xDomain ?? [...positions]).filter(value => positions.has(value))
+    : [...positions].sort((left, right) => left - right);
+  if (orderedPositions.length !== positions.size) throw new Error("Area categorical domain must contain every observed position.");
   if (groupOrder.length === 0 || orderedPositions.length < 2) {
     throw new Error(
       `Centered area mark "${layer.id}" requires at least two aligned positions.`

package/src/grammar/bars/geometry.js

@@ -1,3 +1,6 @@
+import { validateOptionObject } from "../../core/validation.js";
+import { floorUtcTimeUnit, offsetUtcTimeUnit, TIME_UNITS, validTimestamp } from "../timeUnit.js";
+import { mapContinuousScaleValues } from "../scales/mapping.js";
 import { cloneAndFreeze } from "../../core/immutable.js";
 
 export const DEFAULT_BAR_WIDTH = Object.freeze({ band: 0.72 });
@@ -9,8 +12,16 @@ export const DEFAULT_OFFSET_PADDING = Object.freeze({
 export function normalizeBarWidth(options = {}, existing) {
   const hasBand = options.band !== undefined;
   const hasPixels = options.pixels !== undefined;
-  if (hasBand && hasPixels) {
-    throw new Error("encodeBarWidth band and pixels are mutually exclusive.");
+  const hasInterval = options.interval !== undefined;
+  if (Number(hasBand) + Number(hasPixels) + Number(hasInterval) > 1) {
+    throw new Error("encodeBarWidth band, pixels, and interval are mutually exclusive.");
+  }
+  if (hasInterval) {
+    validateOptionObject(options.interval, ["unit", "insetStart", "insetEnd"], "Bar width interval");
+    const { unit, insetStart = 0, insetEnd = 0 } = options.interval;
+    if (!TIME_UNITS.includes(unit) || ["week", "weekday"].includes(unit)) throw new Error("Bar width interval requires year, quarter, month, day, hour, minute, or second.");
+    if (![insetStart, insetEnd].every(v => Number.isFinite(v) && v >= 0)) throw new RangeError("Bar interval insets must be non-negative finite pixels.");
+    return cloneAndFreeze({ interval: { unit, insetStart, insetEnd } });
   }
   if (!hasBand && !hasPixels) {
     return cloneAndFreeze(existing ?? DEFAULT_BAR_WIDTH);
@@ -90,9 +101,25 @@ export function normalizeOffsetScalePolicy(
 }
 
 export function resolveBarWidth(config, slotBandwidth) {
+  const normalized = normalizeBarWidth(config);
+  if (normalized.pixels !== undefined) return normalized.pixels;
   if (!Number.isFinite(slotBandwidth) || slotBandwidth <= 0) {
     throw new Error("Bar width requires a positive resolved slot bandwidth.");
   }
-  const normalized = normalizeBarWidth(config);
   return normalized.pixels ?? slotBandwidth * normalized.band;
 }
+
+
+// Width intent never buckets or aggregates data: category values are interval starts.
+export function resolveBarInterval(config, value, scale) {
+  if (scale.type !== "time") throw new Error("Bar interval width requires a temporal category scale.");
+  const { unit, insetStart, insetEnd } = normalizeBarWidth(config).interval;
+  const start = floorUtcTimeUnit(value, unit);
+  if (start !== value) throw new Error("Bar interval category values must be UTC interval starts.");
+  const end = offsetUtcTimeUnit(start, unit);
+  if (!validTimestamp(end)) throw new RangeError("Bar interval end exceeds the supported Date range.");
+  if (start < Math.min(...scale.domain) || end > Math.max(...scale.domain)) throw new RangeError("Bar interval endpoints must be inside the temporal scale domain; set an explicit covering domain.");
+  const [a, b] = mapContinuousScaleValues([start, end], scale), width = Math.abs(b - a) - insetStart - insetEnd;
+  if (width <= 0) throw new RangeError("Bar interval insets must leave a positive width.");
+  return { position: Math.min(a, b) + (b >= a ? insetStart : insetEnd), width };
+}

package/src/grammar/bars/policy.js

@@ -3,6 +3,7 @@ import { isAggregate } from "../aggregate.js";
 export const BAR_GRAINS = Object.freeze({
   histogram: "histogram",
   aggregate: "aggregate",
+  centered: "centered",
   ranged: "ranged"
 });
 
@@ -20,10 +21,17 @@ function isMeasure(encoding) {
     isAggregate(encoding.aggregate);
 }
 
+function hasNumericCenters(layer) {
+  return layer.mark.orientation !== undefined && [layer.encoding?.x, layer.encoding?.y].every(
+    encoding => encoding?.fieldType === "quantitative" && encoding.bin === undefined && encoding.aggregate === undefined
+  );
+}
+
 export function resolveBarOrientation(layer) {
   if (layer?.mark?.type !== "bar") return undefined;
   const x = layer.encoding?.x;
   const y = layer.encoding?.y;
+  if (hasNumericCenters(layer)) return layer.mark.orientation;
   if (x?.bin !== undefined && y?.aggregate === "count") {
     return BAR_ORIENTATIONS.vertical;
   }
@@ -56,6 +64,8 @@ export function resolveBarGrain(layer) {
   const x = layer.encoding?.x;
   const y = layer.encoding?.y;
 
+  if (hasNumericCenters(layer)) return BAR_GRAINS.centered;
+
   if (
     x?.bin !== undefined &&
     y?.aggregate === "count"
@@ -80,7 +90,7 @@ export function inferBarColorLayout(layer) {
   const grain = resolveBarGrain(layer);
   if (grain === BAR_GRAINS.histogram) return "stack";
   if (grain === BAR_GRAINS.aggregate) return "group";
-  if (grain === BAR_GRAINS.ranged) return "overlay";
+  if (grain === BAR_GRAINS.ranged || grain === BAR_GRAINS.centered) return "overlay";
   return undefined;
 }
 
@@ -89,6 +99,7 @@ export function resolveBarColorLayout(layer) {
   if (layer?.encoding?.color?.layout !== undefined) {
     return layer.encoding.color.layout;
   }
+  if (resolveBarGrain(layer) === BAR_GRAINS.centered) return "overlay";
   const channels = resolveBarChannels(layer);
   if (layer?.encoding?.[channels?.measure]?.stack === "normalize") return "fill";
   const offsetChannel = resolveBarOffsetChannel(layer);

package/src/grammar/bin.js

@@ -1,3 +1,5 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import {
   findHistogramBinIndex,
@@ -15,24 +17,12 @@ import {
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "field", "bin", "extent", "nice", "zero", "includeEmpty",
-  "members", "as", "weight", "resolved"
+  "members", "as", "weight", "missing", "resolved"
 ]);
 const AS_KEYS = Object.freeze(["lower", "upper", "count", "members"]);
 const RESOLVED_KEYS = Object.freeze(["domain", "step", "boundaries"]);
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown ${label} property "${unknown}".`);
-  }
-}
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function normalizeAs(field, value, members) {
   const requested = value ?? {};
@@ -59,7 +49,8 @@ export function normalizeBinTransform({
   includeEmpty,
   members,
   as,
-  weight
+  weight,
+  missing
 } = {}) {
   const selected = [maxBins, step, boundaries].filter(value => value !== undefined);
   if (selected.length > 1) {
@@ -83,7 +74,8 @@ export function normalizeBinTransform({
     as: normalizeAs(field, as, resolvedMembers),
     ...(weight === undefined
       ? {}
-      : { weight: normalizeStatisticalWeight(weight, "Bin weight") })
+      : { weight: normalizeStatisticalWeight(weight, "Bin weight") }),
+    ...(missing === undefined ? {} : { missing })
   };
   validateBinTransform(transform);
   return cloneAndFreeze(transform);
@@ -101,6 +93,9 @@ export function validateBinTransform(transform) {
   if (transform.weight !== undefined) {
     normalizeStatisticalWeight(transform.weight, "Bin weight");
   }
+  if (transform.missing !== undefined && !["error", "drop"].includes(transform.missing)) {
+    throw new Error('Bin missing must be "error" or "drop".');
+  }
   normalizeHistogramBin(transform.bin);
   if (
     transform.extent !== "auto" &&
@@ -142,22 +137,31 @@ export function validateBinTransform(transform) {
   return transform;
 }
 
-function readValues(rows, field) {
-  return rows.map((row, index) => {
+function readValues(rows, field, missing) {
+  const eligible = [];
+  let excluded = 0;
+  rows.forEach((row, index) => {
     const value = row[field];
+    if (value === null || value === undefined) {
+      if (missing === "drop") { excluded += 1; return; }
+      throw new TypeError(`Bin field "${field}" must contain a finite number at row ${index}.`);
+    }
     if (!Number.isFinite(value)) {
       throw new TypeError(`Bin field "${field}" must contain a finite number at row ${index}.`);
     }
-    return value;
+    eligible.push({ row, index });
   });
+  return { eligible, excluded };
 }
 
 export function deriveBinRows(rows, transform) {
   validateBinTransform(transform);
-  const values = readValues(rows, transform.field);
+  const selected = readValues(rows, transform.field, transform.missing);
+  const eligibleRows = selected.eligible.map(entry => entry.row);
+  const values = eligibleRows.map(row => row[transform.field]);
   const weights = transform.weight === undefined
     ? undefined
-    : readStatisticalWeights(rows, transform.weight, "Bin");
+    : readStatisticalWeights(eligibleRows, transform.weight, "Bin");
   if (weights !== undefined) {
     validateWeightedNumericFields(weights.entries, [transform.field], "Bin");
   }
@@ -188,7 +192,7 @@ export function deriveBinRows(rows, transform) {
   });
   const members = resolved.boundaries.slice(0, -1).map(() => []);
   const entries = weightSummary === undefined
-    ? rows.map((row, index) => ({ row, index }))
+    ? selected.eligible
     : weightSummary.positive;
   entries.forEach(entry => {
     const value = entry.row[transform.field];
@@ -217,7 +221,22 @@ export function deriveBinRows(rows, transform) {
       domain: resolved.domain,
       ...(resolved.step === undefined ? {} : { step: resolved.step }),
       boundaries: resolved.boundaries
-    }
+    },
+    ...(transform.missing === undefined ? {} : {
+      report: {
+        version: 1,
+        owner: { kind: "data", id: "pending" },
+        inputs: [],
+        units: [{
+          role: transform.as.count,
+          group: {},
+          inputRows: rows.length,
+          usedRows: eligibleRows.length,
+          excludedRows: selected.excluded,
+          excludedByReason: selected.excluded === 0 ? {} : { "missing-value": selected.excluded }
+        }]
+      }
+    })
   };
 }
 

package/src/grammar/bin2d.js

@@ -1,3 +1,4 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
 import {
   cloneAndFreeze,
   isPlainObject
@@ -18,12 +19,6 @@ const RESOLVED_KEYS = Object.freeze([
   "extent", "edges", "eligibleCount", "occupiedCount"
 ]);
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown ${label} property "${unknown}".`);
-  }
-}
 
 function requirePositiveInteger(value, label) {
   if (!Number.isInteger(value) || value <= 0) {

package/src/grammar/boxPlot.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { interpolateNumber, stableDecimal } from "./numeric.js";
+import { quantileSorted, stableDecimal } from "./numeric.js";
 
 export const BOX_FIELDS = Object.freeze({
   q1: "__boxPlot_q1", median: "__boxPlot_median", q3: "__boxPlot_q3",
@@ -9,7 +9,7 @@ export const BOX_FIELDS = Object.freeze({
 });
 
 const TRANSFORM_KEYS = [
-  "type", "category", "field", "method", "whisker", "factor", "as"
+  "type", "category", "field", "method", "whisker", "factor", "as", "summary"
 ];
 const OUTPUT_KEYS = Object.keys(BOX_FIELDS);
 
@@ -18,6 +18,36 @@ function field(value, label) {
   return value;
 }
 
+const SUMMARY_KEYS = Object.freeze(["min", "q1", "median", "q3", "max"]);
+
+export function normalizeBoxSummary(value) {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value) || Object.keys(value).length !== SUMMARY_KEYS.length ||
+      !SUMMARY_KEYS.every(key => Object.hasOwn(value, key))) {
+    throw new TypeError("Box summary requires min, q1, median, q3 and max field names.");
+  }
+  return cloneAndFreeze(Object.fromEntries(SUMMARY_KEYS.map(key => [key, field(value[key], `Box summary.${key}`)])));
+}
+
+function derivePrecomputedBoxData(rows, transform) {
+  const { category, summary, as } = transform;
+  const summaries = [];
+  for (const row of rows) {
+    const key = row[category];
+    if (key === undefined || key === null || key === "") continue;
+    const values = SUMMARY_KEYS.map(role => row[summary[role]]);
+    if (!values.every(Number.isFinite)) throw new TypeError("Precomputed box summaries require finite values for all five fields.");
+    if (values.some((value, index) => index > 0 && value < values[index - 1])) {
+      throw new RangeError("Box summary must satisfy min <= q1 <= median <= q3 <= max.");
+    }
+    const [min, q1, median, q3, max] = values;
+    summaries.push({ [category]: key, [as.q1]: q1, [as.median]: median, [as.q3]: q3,
+      [as.lowerWhisker]: min, [as.upperWhisker]: max });
+  }
+  if (summaries.length === 0) throw new Error("Box transform requires at least one valid row.");
+  return cloneAndFreeze({ summaries, outliers: [] });
+}
+
 function validateOutputs(as, occupied) {
   if (!isPlainObject(as)) throw new TypeError("Box as must be a plain object.");
   const keys = Object.keys(as);
@@ -40,6 +70,18 @@ export function validateBoxTransform(value) {
   }
   field(value.category, "Box category field");
   field(value.field, "Box measure field");
+  if (value.method === "precomputed") {
+    const summary = normalizeBoxSummary(value.summary);
+    if (summary === undefined || value.type !== "boxSummary" || value.field !== summary.median) {
+      throw new Error("Precomputed box summaries require a summary mapping and its median measure field.");
+    }
+    if (value.whisker !== undefined || value.factor !== undefined) {
+      throw new Error("Precomputed box summaries do not compute whiskers or factors.");
+    }
+    validateOutputs(value.as, new Set([value.category, ...Object.values(summary)]));
+    return value;
+  }
+  if (value.summary !== undefined) throw new Error("Box summary fields require the precomputed method.");
   if (value.method !== "linear") throw new Error(`Unsupported box quantile method "${value.method}".`);
   const whisker = value.whisker ?? "tukey";
   if (!["tukey", "minmax"].includes(whisker)) {
@@ -56,6 +98,16 @@ export function validateBoxTransform(value) {
 }
 
 export function normalizeBoxTransform(options = {}) {
+  if (options.summary !== undefined) {
+    const summary = normalizeBoxSummary(options.summary);
+    const normalized = { type: options.type ?? "boxSummary", category: options.category,
+      field: options.field ?? summary.median, method: "precomputed", summary, as: options.as ?? BOX_FIELDS };
+    if (options.factor !== undefined || (options.whisker !== undefined && options.whisker !== "minmax")) {
+      throw new Error("Precomputed box summaries require minmax whiskers without a factor.");
+    }
+    validateBoxTransform(normalized);
+    return cloneAndFreeze(normalized);
+  }
   const {
     type = "boxSummary",
     category,
@@ -79,16 +131,11 @@ export function normalizeBoxTransform(options = {}) {
   return cloneAndFreeze(normalized);
 }
 
-function quantile(sorted, p) {
-  const position = (sorted.length - 1) * p;
-  const lower = Math.floor(position);
-  const upper = Math.ceil(position);
-  return interpolateNumber(sorted[lower], sorted[upper], position - lower);
-}
 
 export function deriveBoxData(rows, transform) {
   if (!Array.isArray(rows)) throw new TypeError("Box rows must be an array.");
   validateBoxTransform(transform);
+  if (transform.method === "precomputed") return derivePrecomputedBoxData(rows, transform);
   const { category, field: measure, factor, as } = transform;
   const whisker = transform.whisker ?? "tukey";
   const groups = [];
@@ -111,7 +158,7 @@ export function deriveBoxData(rows, transform) {
   for (const group of groups) {
     const sorted = group.rows.map(row => row[measure]).sort((a, b) => a - b);
     const [q1, median, q3] = [0.25, 0.5, 0.75].map(probability =>
-      stableDecimal(quantile(sorted, probability))
+      stableDecimal(quantileSorted(sorted, probability))
     );
     const spread = q3 - q1;
     const lowerFence = whisker === "minmax"

package/src/grammar/categoryOrder.js

@@ -1,3 +1,4 @@
+import { requireStringValue as nonEmptyField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { isNominalValue, readNominalField } from "./scales/fields.js";
 import { aggregateScalarValues } from "./aggregate.js";
@@ -7,12 +8,6 @@ export const CATEGORY_ORDER_CHANNELS = Object.freeze(["x", "y", "theta"]);
 const DIRECTIONS = ["ascending", "descending"];
 const AGGREGATES = ["sum", "mean", "min", "max"];
 
-function nonEmptyField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 const sameValue = Object.is;
 

package/src/grammar/complete.js

@@ -1,3 +1,5 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 
 const TRANSFORM_KEYS = Object.freeze([
@@ -6,17 +8,7 @@ const TRANSFORM_KEYS = Object.freeze([
 const SEQUENCE_KEYS = Object.freeze(["start", "end", "step"]);
 const MAX_OUTPUT_ROWS = 10_000;
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) throw new Error(`Unknown ${label} property "${unknown}".`);
-}
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function scalarType(value, label) {
   if (value === null) return "null";
@@ -258,20 +250,24 @@ export function deriveCompleteRows(rows, transform) {
       if (!allowed.has(identity)) {
         throw new Error(`Complete observed key is outside the requested domain at row ${entry.index}.`);
       }
-      if (lookup.has(identity)) {
-        throw new Error("Complete source contains a duplicate group and key combination.");
-      }
-      lookup.set(identity, entry);
+      if (!lookup.has(identity)) lookup.set(identity, []);
+      lookup.get(identity).push(entry);
+    }
+    const groupSize = group.values.length + domain.length - lookup.size;
+    if (output.length + groupSize > MAX_OUTPUT_ROWS) {
+      throw new RangeError(`Complete output cannot exceed ${MAX_OUTPUT_ROWS} rows.`);
     }
     for (const keyValue of domain) {
       const identity = scalarKey(keyValue, "Complete domain value");
-      const entry = lookup.get(identity);
-      if (entry === undefined) {
+      const entries = lookup.get(identity);
+      if (entries === undefined) {
         output.push(syntheticRow(fields, group, keyValue, transform));
       } else {
-        const row = { ...entry.row };
-        if (transform.members !== undefined) define(row, transform.members, [entry.index]);
-        output.push(row);
+        for (const entry of entries) {
+          const row = { ...entry.row };
+          if (transform.members !== undefined) define(row, transform.members, [entry.index]);
+          output.push(row);
+        }
       }
     }
   }