ggaction 0.0.16 → 0.0.17

package/src/grammar/filter.js

@@ -39,33 +39,62 @@ function validateRange(range) {
     throw new TypeError("Filter range must be a plain object.");
   }
   const unknown = Object.keys(range).find(
-    key => !["min", "max", "inclusive"].includes(key)
+    key => !["min", "max", "inclusive", "minInclusive", "maxInclusive"].includes(key)
   );
   if (unknown !== undefined) {
     throw new Error(`Unknown filter range property "${unknown}".`);
   }
-  if (
-    !isFiniteOrString(range.min) ||
-    !isFiniteOrString(range.max) ||
-    typeof range.min !== typeof range.max
-  ) {
-    throw new TypeError(
-      "Filter range endpoints must be finite numbers or strings of one type."
-    );
+  const hasMin = Object.hasOwn(range, "min");
+  const hasMax = Object.hasOwn(range, "max");
+  if (!hasMin && !hasMax) throw new TypeError("Filter range requires min or max.");
+  if ((hasMin && !isFiniteOrString(range.min)) || (hasMax && !isFiniteOrString(range.max))) {
+    throw new TypeError("Filter range endpoints must be finite numbers or strings.");
+  }
+  if (hasMin && hasMax && typeof range.min !== typeof range.max) {
+    throw new TypeError("Filter range endpoints must use one type.");
   }
-  if (range.min > range.max) {
+  if (hasMin && hasMax && range.min > range.max) {
     throw new RangeError("Filter range min must not exceed max.");
   }
   if (range.inclusive !== undefined && typeof range.inclusive !== "boolean") {
     throw new TypeError("Filter range inclusive must be a boolean.");
   }
+  if (range.inclusive !== undefined && (
+    range.minInclusive !== undefined || range.maxInclusive !== undefined
+  )) throw new Error("Filter range cannot combine inclusive with endpoint inclusivity.");
+  for (const [key, endpoint] of [["minInclusive", "min"], ["maxInclusive", "max"]]) {
+    if (range[key] !== undefined && typeof range[key] !== "boolean") {
+      throw new TypeError(`Filter range ${key} must be a boolean.`);
+    }
+    if (range[key] !== undefined && !Object.hasOwn(range, endpoint)) {
+      throw new Error(`Filter range ${key} requires ${endpoint}.`);
+    }
+  }
+}
+
+function normalizeRange(range) {
+  validateRange(range);
+  const shared = range.inclusive;
+  return {
+    ...(Object.hasOwn(range, "min") ? { min: range.min, minInclusive: shared ?? range.minInclusive ?? true } : {}),
+    ...(Object.hasOwn(range, "max") ? { max: range.max, maxInclusive: shared ?? range.maxInclusive ?? true } : {})
+  };
+}
+
+function normalizeSet(values, name) {
+  if (!Array.isArray(values) || values.length === 0 ||
+      Array.from({ length: values.length }, (_, index) => index).some(index => !Object.hasOwn(values, index)) ||
+      values.some(value => value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value)))) {
+    throw new TypeError(`Filter ${name} must be a non-empty dense array of scalar values.`);
+  }
+  return [...new Set(values)];
 }
 
 export function validateFilterTransform(transform) {
   if (!isPlainObject(transform)) {
     throw new TypeError("Filter transform must be a plain object.");
   }
-  const supported = ["type", "field", "oneOf", "predicate", "range"];
+  const supported = ["type", "field", "oneOf", "noneOf", "predicate", "range", "nulls"];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
     throw new Error(`Unknown filter transform property "${unknown}".`);
@@ -73,12 +102,15 @@ export function validateFilterTransform(transform) {
   if (typeof transform.field !== "string" || transform.field.length === 0) {
     throw new TypeError("Filter field must be a non-empty field string.");
   }
-  const modes = ["oneOf", "predicate", "range"].filter(
+  if (transform.nulls !== undefined && !["include", "exclude"].includes(transform.nulls)) {
+    throw new Error('Filter nulls must be "include" or "exclude".');
+  }
+  const modes = ["oneOf", "noneOf", "predicate", "range"].filter(
     key => Object.hasOwn(transform, key)
   );
   if (modes.length !== 1) {
     throw new Error(
-      "Filter transform requires exactly one of oneOf, predicate, or range."
+      "Filter transform requires exactly one of oneOf, noneOf, predicate, or range."
     );
   }
   if (modes[0] === "predicate") {
@@ -89,46 +121,101 @@ export function validateFilterTransform(transform) {
     validateRange(transform.range);
     return;
   }
-  if (
-    !Array.isArray(transform.oneOf) ||
-    transform.oneOf.length === 0 ||
-    transform.oneOf.some(value =>
-      value !== null &&
-      typeof value !== "string" &&
-      typeof value !== "boolean" &&
-      !(typeof value === "number" && Number.isFinite(value))
-    )
-  ) {
-    throw new TypeError("Filter oneOf must be a non-empty array of scalar values.");
-  }
+  normalizeSet(transform[modes[0]], modes[0]);
 }
 
 export function normalizeFilterTransform({
   field,
   oneOf,
+  noneOf,
   predicate,
-  range
+  range,
+  nulls
 }) {
-  const modes = { oneOf, predicate, range };
+  const modes = { oneOf, noneOf, predicate, range };
   const selected = Object.keys(modes).filter(key => modes[key] !== undefined);
   const transform = {
     type: "filter",
     field,
-    ...(selected[0] === "oneOf" ? { oneOf } : {}),
+    ...(selected[0] === "oneOf" ? { oneOf: normalizeSet(oneOf, "oneOf") } : {}),
+    ...(selected[0] === "noneOf" ? { noneOf: normalizeSet(noneOf, "noneOf") } : {}),
     ...(selected[0] === "predicate" ? { predicate } : {}),
     ...(selected[0] === "range"
-      ? { range: { ...range, inclusive: range?.inclusive ?? true } }
-      : {})
+      ? { range: normalizeRange(range) }
+      : {}),
+    ...(nulls === undefined ? {} : { nulls })
   };
   if (selected.length !== 1) {
     throw new Error(
-      "filterData requires exactly one of oneOf, predicate, or range."
+      "filterData requires exactly one of oneOf, noneOf, predicate, or range."
     );
   }
   validateFilterTransform(transform);
   return cloneAndFreeze(transform);
 }
 
+export function normalizeFilterTransformEdit(transform, patch) {
+  const modes = ["oneOf", "noneOf", "predicate", "range"];
+  const previousMode = modes.find(key => Object.hasOwn(transform, key));
+  const requestedModes = modes.filter(key => Object.hasOwn(patch, key));
+  if (requestedModes.length > 1) {
+    throw new Error("Filter edit can replace only one filter mode.");
+  }
+  const fieldChanged = Object.hasOwn(patch, "field") && patch.field !== transform.field;
+  if (fieldChanged && requestedModes.length === 0) {
+    throw new Error("Changing a filter field requires a complete filter mode.");
+  }
+  let mode = previousMode;
+  let modeValue = transform[previousMode];
+  if (requestedModes.length === 1) {
+    mode = requestedModes[0];
+    if (mode === "range" && previousMode === "range" && !fieldChanged) {
+      if (!isPlainObject(patch.range)) throw new TypeError("Filter range patch must be a plain object.");
+      const legacy = normalizeRange(transform.range);
+      const next = { ...legacy };
+      const rangePatch = patch.range;
+      const unknown = Object.keys(rangePatch).find(key => !["min", "max", "inclusive", "minInclusive", "maxInclusive"].includes(key));
+      if (unknown !== undefined) throw new Error(`Unknown filter range property "${unknown}".`);
+      if (rangePatch.inclusive !== undefined && (rangePatch.minInclusive !== undefined || rangePatch.maxInclusive !== undefined)) {
+        throw new Error("Filter range cannot combine inclusive with endpoint inclusivity.");
+      }
+      for (const endpoint of ["min", "max"]) {
+        if (!Object.hasOwn(rangePatch, endpoint)) continue;
+        if (rangePatch[endpoint] === false) {
+          delete next[endpoint];
+          delete next[`${endpoint}Inclusive`];
+        } else {
+          next[endpoint] = rangePatch[endpoint];
+          next[`${endpoint}Inclusive`] = Object.hasOwn(legacy, endpoint)
+            ? legacy[`${endpoint}Inclusive`]
+            : true;
+        }
+      }
+      if (rangePatch.inclusive !== undefined) {
+        if (typeof rangePatch.inclusive !== "boolean") throw new TypeError("Filter range inclusive must be a boolean.");
+        if (Object.hasOwn(next, "min")) next.minInclusive = rangePatch.inclusive;
+        if (Object.hasOwn(next, "max")) next.maxInclusive = rangePatch.inclusive;
+      }
+      for (const endpoint of ["min", "max"]) {
+        const key = `${endpoint}Inclusive`;
+        if (rangePatch[key] !== undefined) {
+          if (!Object.hasOwn(next, endpoint)) throw new Error(`Filter range ${key} requires ${endpoint}.`);
+          next[key] = rangePatch[key];
+        }
+      }
+      modeValue = next;
+    } else {
+      modeValue = patch[mode];
+    }
+  }
+  const nulls = patch.nulls === false ? undefined : (patch.nulls ?? transform.nulls);
+  return normalizeFilterTransform({
+    field: patch.field ?? transform.field,
+    [mode]: modeValue,
+    ...(nulls === undefined ? {} : { nulls })
+  });
+}
+
 function comparable(value, operand) {
   return (
     Number.isFinite(value) && Number.isFinite(operand)
@@ -141,6 +228,7 @@ function matches(value, transform) {
   if (transform.oneOf !== undefined) {
     return transform.oneOf.includes(value);
   }
+  if (transform.noneOf !== undefined) return !transform.noneOf.includes(value);
   if (transform.predicate !== undefined) {
     const { op, value: operand } = transform.predicate;
     if (op === "eq") return value === operand;
@@ -151,11 +239,12 @@ function matches(value, transform) {
     if (op === "gt") return value > operand;
     return value >= operand;
   }
-  const { min, max, inclusive = true } = transform.range;
-  if (!comparable(value, min) || !comparable(value, max)) return false;
-  return inclusive
-    ? value >= min && value <= max
-    : value > min && value < max;
+  const { min, max, minInclusive = transform.range.inclusive ?? true, maxInclusive = transform.range.inclusive ?? true } = transform.range;
+  if (min !== undefined && !comparable(value, min)) return false;
+  if (max !== undefined && !comparable(value, max)) return false;
+  if (min !== undefined && (value < min || (value === min && !minInclusive))) return false;
+  if (max !== undefined && (value > max || (value === max && !maxInclusive))) return false;
+  return true;
 }
 
 export function deriveFilteredRows(values, transform) {
@@ -163,7 +252,12 @@ export function deriveFilteredRows(values, transform) {
     throw new TypeError("Filter source values must be an array.");
   }
   validateFilterTransform(transform);
-  return values.filter(row =>
-    isPlainObject(row) && matches(row[transform.field], transform)
-  );
+  return values.filter(row => {
+    if (!isPlainObject(row)) return false;
+    const value = row[transform.field];
+    if (value === null || value === undefined) {
+      if (transform.nulls !== undefined) return transform.nulls === "include";
+    }
+    return matches(value, transform);
+  });
 }

package/src/grammar/interval.js

@@ -16,6 +16,7 @@ const TRANSFORM_KEYS = [
   "extent",
   "method",
   "level",
+  "missing",
   "as"
 ];
 const OUTPUT_KEYS = ["center", "lower", "upper"];
@@ -82,6 +83,9 @@ export function validateIntervalTransform(transform) {
   if (!EXTENT_VALUES.includes(transform.extent)) {
     throw new Error(`Unsupported interval extent "${transform.extent}".`);
   }
+  if (transform.missing !== undefined && !["error", "drop"].includes(transform.missing)) {
+    throw new Error('Interval missing must be "error" or "drop".');
+  }
   if (
     (transform.center === "median") !== (transform.extent === "iqr")
   ) {
@@ -201,15 +205,24 @@ export function deriveInterval(rows, transform) {
   }
   validateIntervalTransform(transform);
   const groups = new Map();
+  let missingRows = 0;
   for (const row of rows) {
     if (!isPlainObject(row)) continue;
     const value = row[transform.field];
     if (isMissing(value) || !Number.isFinite(value)) {
+      const nullish = value === undefined || value === null;
+      if (transform.missing === "error" && nullish) {
+        throw new TypeError(`Interval field "${transform.field}" is missing.`);
+      }
+      if (transform.missing !== undefined && !nullish) {
+        throw new TypeError(`Interval field "${transform.field}" must contain finite numbers.`);
+      }
       if (value !== undefined && value !== null && typeof value !== "number") {
         throw new TypeError(
           `Interval field "${transform.field}" must contain numeric or missing values.`
         );
       }
+      if (nullish) missingRows += 1;
       continue;
     }
     const groupValues = transform.groupBy.map(field => row[field]);
@@ -240,7 +253,23 @@ export function deriveInterval(rows, transform) {
       [transform.as.upper]: stableDecimal(result.upper)
     });
   }
-  return cloneAndFreeze(output);
+  if (transform.missing === undefined) return cloneAndFreeze(output);
+  return cloneAndFreeze({
+    values: output,
+    report: {
+      version: 1,
+      owner: { kind: "data", id: "pending" },
+      inputs: [],
+      units: [{
+        role: transform.as.center,
+        group: {},
+        inputRows: rows.length,
+        usedRows: rows.length - missingRows,
+        excludedRows: missingRows,
+        excludedByReason: missingRows === 0 ? {} : { "missing-value": missingRows }
+      }]
+    }
+  });
 }
 
 export function normalizeIntervalTransform({
@@ -250,6 +279,7 @@ export function normalizeIntervalTransform({
   extent,
   method,
   level,
+  missing,
   as
 }) {
   nonEmptyString(field, "Interval field");
@@ -260,6 +290,7 @@ export function normalizeIntervalTransform({
     field,
     groupBy: grouping,
     ...parameters,
+    ...(missing === undefined ? {} : { missing }),
     as
   };
   validateIntervalTransform(transform);

package/src/grammar/itemMissing.js

@@ -0,0 +1,59 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+
+export const ITEM_MISSING_MARK_TYPES = Object.freeze([
+  "point", "bar", "rect", "tick", "rule", "text"
+]);
+
+export function validateItemMissing(value, label = "Mark missing") {
+  if (!["error", "skip"].includes(value)) {
+    throw new Error(`${label} must be "error" or "skip".`);
+  }
+  return value;
+}
+
+function collectFields(value, fields, seen) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (typeof value.field === "string" && value.field.length > 0) {
+    fields.add(value.field);
+  }
+  for (const child of Object.values(value)) collectFields(child, fields, seen);
+}
+
+export function itemMissingFields(layer) {
+  const fields = new Set();
+  collectFields(layer.encoding ?? {}, fields, new Set());
+  return [...fields];
+}
+
+export function applyItemMissingPolicy(layer, dataset) {
+  const policy = layer.mark?.missing;
+  if (policy === undefined) return dataset;
+  if (!ITEM_MISSING_MARK_TYPES.includes(layer.mark?.type)) return dataset;
+  validateItemMissing(policy, `${layer.mark.type} missing`);
+  const fields = itemMissingFields(layer);
+  if (fields.length === 0) return dataset;
+  const eligible = [];
+  for (const [index, row] of dataset.values.entries()) {
+    const missing = fields.find(field => row[field] === null || row[field] === undefined);
+    if (missing === undefined) {
+      eligible.push(row);
+    } else if (policy === "error") {
+      throw new Error(
+        `${layer.mark.type} mark "${layer.id}" field "${missing}" is missing at row ${index}.`
+      );
+    }
+  }
+  if (eligible.length === dataset.values.length) return dataset;
+  return cloneAndFreeze({ ...dataset, values: eligible });
+}
+
+export function applyRequestedItemMissingPolicy(layer, dataset, field) {
+  if (typeof field !== "string" || field.length === 0) {
+    return applyItemMissingPolicy(layer, dataset);
+  }
+  return applyItemMissingPolicy({
+    ...layer,
+    encoding: { ...layer.encoding, __requested: { field } }
+  }, dataset);
+}

package/src/grammar/regression/derive.js

@@ -27,7 +27,9 @@ export function deriveRegression(values, {
   confidenceMethod,
   level,
   confidence,
-  interval
+  interval,
+  predict,
+  missing
 } = {}) {
   if (!Array.isArray(values)) {
     throw new TypeError("Regression values must be an array.");
@@ -46,15 +48,29 @@ export function deriveRegression(values, {
     confidence,
     interval
   });
-  readQuantitativeField(values, x);
-  readQuantitativeField(values, y);
-  if (groupBy !== undefined) readNominalField(values, groupBy);
+  let missingRows = 0;
+  const eligibleValues = missing === undefined ? values : values.filter((row, index) => {
+    const xValue = row?.[x];
+    const yValue = row?.[y];
+    if (xValue === null || xValue === undefined || yValue === null || yValue === undefined) {
+      if (missing === "error") throw new TypeError(`Regression x/y pair is missing at row ${index}.`);
+      missingRows += 1;
+      return false;
+    }
+    if (!Number.isFinite(xValue) || !Number.isFinite(yValue)) {
+      throw new TypeError(`Regression x/y fields must contain finite numbers at row ${index}.`);
+    }
+    return true;
+  });
+  readQuantitativeField(eligibleValues, x);
+  readQuantitativeField(eligibleValues, y);
+  if (groupBy !== undefined) readNominalField(eligibleValues, groupBy);
 
   const groupedRows = new Map();
   if (groupBy === undefined) {
-    groupedRows.set(undefined, values);
+    groupedRows.set(undefined, eligibleValues);
   } else {
-    for (const row of values) {
+    for (const row of eligibleValues) {
       const group = row[groupBy];
       const rows = groupedRows.get(group) ?? [];
       rows.push(row);
@@ -68,13 +84,25 @@ export function deriveRegression(values, {
 
   for (const group of groups) {
     const groupRows = groupedRows.get(group);
-    const xCount = new Set(groupRows.map(row => row[x])).size;
-    validateGeneratedItemLimit(rows.length + xCount, "Regression generated row count");
+    const observedX = [...new Set(groupRows.map(row => row[x]))]
+      .sort((left, right) => left - right);
+    const xValues = predict?.values ?? (predict?.domain === undefined
+      ? observedX
+      : Array.from({ length: predict.steps }, (_, index) => {
+          if (index === 0) return predict.domain[0];
+          if (index === predict.steps - 1) return predict.domain[1];
+          const ratio = index / (predict.steps - 1);
+          return requireFiniteResult(
+            predict.domain[0] * (1 - ratio) + predict.domain[1] * ratio,
+            "Regression prediction grid"
+          );
+        }));
+    validateGeneratedItemLimit(rows.length + xValues.length, "Regression generated row count");
     if (parameters.method === "polynomial") {
       const size = parameters.degree + 1;
       work += groupRows.length * size ** 2 + size ** 3;
     } else if (parameters.method === "loess") {
-      work += groupRows.length * xCount *
+      work += groupRows.length * xValues.length *
         Math.ceil(Math.log2(groupRows.length + 1));
     }
     validateWorkLimit(work, "Regression computation");
@@ -84,8 +112,6 @@ export function deriveRegression(values, {
       group,
       parameters
     });
-    const xValues = [...new Set(groupRows.map(row => row[x]))]
-      .sort((left, right) => left - right);
     models.push({ ...(groupBy === undefined ? {} : { group }), ...model, xValues });
 
     for (const xValue of xValues) {
@@ -94,13 +120,13 @@ export function deriveRegression(values, {
         prediction.prediction,
         `Regression group "${group === undefined ? "all" : String(group)}" prediction`
       );
-      const lower = parameters.method === "loess"
+      const lower = parameters.method === "loess" || parameters.interval === false
         ? undefined
         : requireFiniteResult(
             fitted - prediction.margin,
             `Regression group "${group === undefined ? "all" : String(group)}" lower interval`
           );
-      const upper = parameters.method === "loess"
+      const upper = parameters.method === "loess" || parameters.interval === false
         ? undefined
         : requireFiniteResult(
             fitted + prediction.margin,
@@ -110,7 +136,7 @@ export function deriveRegression(values, {
         ...(groupBy === undefined ? {} : { [groupBy]: group }),
         [x]: xValue,
         [y]: fitted,
-        ...(parameters.method === "loess" ? {} : {
+        ...(parameters.method === "loess" || parameters.interval === false ? {} : {
           [REGRESSION_LOWER_FIELD]: lower,
           [REGRESSION_UPPER_FIELD]: upper
         })
@@ -123,7 +149,7 @@ export function deriveRegression(values, {
       x,
       y,
       ...(groupBy === undefined ? {} : { group: groupBy }),
-      ...(parameters.method === "loess" ? {} : {
+      ...(parameters.method === "loess" || parameters.interval === false ? {} : {
         lower: REGRESSION_LOWER_FIELD,
         upper: REGRESSION_UPPER_FIELD
       })
@@ -131,7 +157,22 @@ export function deriveRegression(values, {
     parameters,
     groups,
     models,
-    values: rows
+    values: rows,
+    ...(missing === undefined ? {} : {
+      report: {
+        version: 1,
+        owner: { kind: "data", id: "pending" },
+        inputs: [],
+        units: [{
+          role: "fit",
+          group: {},
+          inputRows: values.length,
+          usedRows: eligibleValues.length,
+          excludedRows: missingRows,
+          excludedByReason: missingRows === 0 ? {} : { "missing-value": missingRows }
+        }]
+      }
+    })
   });
 }
 

package/src/grammar/regression/index.js

@@ -9,6 +9,7 @@ export {
 } from "./derive.js";
 export {
   normalizeRegressionParameters,
+  normalizeRegressionPredict,
   normalizeRegressionTransform,
   validateRegressionTransform
 } from "./parameters.js";