@delali/narsil 0.2.4-next.54 → 0.2.4-next.59

package/dist/{chunk-5T6AOR37.mjs → chunk-ZNZBXMP5.mjs}

@@ -1,6 +1,6 @@
-import { flattenSchema, SORTABLE_TEXT_FIELD_TYPE, MAX_SORT_FIELDS, MAX_SORT_FIELD_NAME_LENGTH, MAX_CURSOR_LENGTH, RESULT_WINDOW, DEFAULT_PAGE_SIZE, PROTOTYPE_POLLUTION_KEYS, isTextFieldType, PREFIX_MAX_EXPANSIONS, MAX_CURSOR_ANCHOR_CODE_POINTS } from './chunk-L225SHNB.mjs';
-import { compareCodePoints, compareComparableKeys, toComparableSortValue, readSortField, SORT_VALUE_MAX_CODE_POINTS, compareSortValues } from './chunk-2GWVQWGA.mjs';
-import { createNarsilError, ErrorCodes, NarsilError } from './chunk-FRQVMFY7.mjs';
+import { isTextFieldType, flattenSchema, SORTABLE_TEXT_FIELD_TYPE, isGeopointOrVectorType, MAX_SORT_FIELDS, MAX_SORT_FIELD_NAME_LENGTH, MAX_CURSOR_LENGTH, RESULT_WINDOW, DEFAULT_FUZZY_PREFIX_LENGTH, DEFAULT_PAGE_SIZE, PROTOTYPE_POLLUTION_KEYS, PREFIX_MAX_EXPANSIONS, MAX_CURSOR_ANCHOR_CODE_POINTS } from './chunk-L6TNPLAR.mjs';
+import { compareCodePoints, sortModeOf, defaultSortMode, toReducedSortValue, readSortField, compareComparableKeys, toComparableSortValue, isSortMode, SORT_MODES, SORT_VALUE_MAX_CODE_POINTS, compareSortValues } from './chunk-YMZCMH5M.mjs';
+import { createNarsilError, ErrorCodes, NarsilError } from './chunk-USKFU7J5.mjs';
 
 // src/core/tokenizer/constants.ts
 var TOKEN_CACHE_SIZE_FLOOR = 5e4;
@@ -673,34 +673,6 @@ function heapPop(heap) {
   return top;
 }
 
-// src/search/facets.ts
-function mergeFacets(partitionFacets) {
-  const merged = /* @__PURE__ */ new Map();
-  const bounds = /* @__PURE__ */ new Map();
-  for (const partition of partitionFacets) {
-    for (const [field, facetResult] of Object.entries(partition)) {
-      let fieldMap = merged.get(field);
-      if (!fieldMap) {
-        fieldMap = /* @__PURE__ */ new Map();
-        merged.set(field, fieldMap);
-      }
-      bounds.set(field, (bounds.get(field) ?? 0) + facetResult.errorBound);
-      for (const [value, count] of Object.entries(facetResult.values)) {
-        fieldMap.set(value, (fieldMap.get(value) ?? 0) + count);
-      }
-    }
-  }
-  const result = {};
-  for (const [field, valueMap] of merged) {
-    const values = {};
-    for (const [value, count] of valueMap) {
-      values[value] = count;
-    }
-    result[field] = { values, count: valueMap.size, errorBound: bounds.get(field) ?? 0 };
-  }
-  return result;
-}
-
 // src/core/bitset.ts
 function createBitSet(capacity) {
   return new Uint32Array(capacity + 31 >>> 5 || 1);
@@ -762,7 +734,288 @@ function bitsetFromSet(set, capacity) {
   return bs;
 }
 
+// src/core/partition/utils.ts
+function getOrCreateFieldNameIndex(table, fieldName) {
+  const existing = table.indexMap.get(fieldName);
+  if (existing !== void 0) return existing;
+  const idx = table.names.length;
+  table.names.push(fieldName);
+  table.indexMap.set(fieldName, idx);
+  return idx;
+}
+function getNestedValue(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (let i = 0; i < parts.length; i++) {
+    if (current === null || current === void 0 || typeof current !== "object") return void 0;
+    if (!Object.hasOwn(current, parts[i])) return void 0;
+    current = current[parts[i]];
+  }
+  return current;
+}
+function stringArraysEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function textFieldsChanged(oldDoc, newDoc, flatSchema) {
+  for (const [path, fieldType] of Object.entries(flatSchema)) {
+    if (!isTextFieldType(fieldType) && fieldType !== "string[]") continue;
+    const oldVal = getNestedValue(oldDoc, path);
+    const newVal = getNestedValue(newDoc, path);
+    if (fieldType !== "string[]") {
+      if (oldVal !== newVal) return true;
+    } else {
+      if (!stringArraysEqual(oldVal, newVal)) return true;
+    }
+  }
+  return false;
+}
+function tokenizeOptions(options) {
+  return {
+    stem: true,
+    removeStopWords: true,
+    collectSurfaces: options?.collectSurfaces === true,
+    stopWordOverride: options?.stopWordOverride,
+    customTokenizer: options?.customTokenizer
+  };
+}
+function getFlatSchema(state, schema) {
+  if (state.lastSchemaRef === schema && state.flatSchemaCache) return state.flatSchemaCache;
+  state.flatSchemaCache = flattenSchema(schema);
+  state.lastSchemaRef = schema;
+  return state.flatSchemaCache;
+}
+function getFieldValueForDoc(docStore, docId, fieldPath) {
+  const stored = docStore.get(docId);
+  if (!stored) return void 0;
+  return getNestedValue(stored.fields, fieldPath);
+}
+function getFieldValueByInternalId(docStore, internalId, fieldPath) {
+  const externalId = docStore.getExternalId(internalId);
+  if (externalId === void 0) return void 0;
+  return getFieldValueForDoc(docStore, externalId, fieldPath);
+}
+function getAllInternalDocIds(docStore) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const internalId of docStore.allInternalIds()) {
+    ids.add(internalId);
+  }
+  return ids;
+}
+
+// src/core/partition/facets.ts
+var UNDECLARED_FIELD_TYPE = "";
+function keptFacetValues(limit) {
+  return limit !== void 0 && limit > 0 ? Math.floor(limit) : void 0;
+}
+function ordinalBitsetOf(state, matched) {
+  if ("ordinalBitset" in matched) return matched.ordinalBitset;
+  const bitset = createBitSet(state.docStore.internalIdCapacity());
+  for (const docId of matched) {
+    const ordinal = state.docStore.getInternalId(docId);
+    if (ordinal !== void 0) bitsetSet(bitset, ordinal);
+  }
+  return bitset;
+}
+function* matchedFieldValues(state, fieldPath, matched) {
+  if ("ordinalBitset" in matched) {
+    const bits = matched.ordinalBitset;
+    for (let wordIndex = 0; wordIndex < bits.length; wordIndex++) {
+      let word = bits[wordIndex];
+      if (word === 0) continue;
+      const base = wordIndex << 5;
+      while (word !== 0) {
+        const trailingZeros = Math.clz32(word & -word) ^ 31;
+        yield getFieldValueByInternalId(state.docStore, base + trailingZeros, fieldPath);
+        word &= word - 1;
+      }
+    }
+    return;
+  }
+  for (const docId of matched) {
+    yield getFieldValueForDoc(state.docStore, docId, fieldPath);
+  }
+}
+function countValuesFromDocuments(state, fieldPath, matched) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const value of matchedFieldValues(state, fieldPath, matched)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const key = String(item);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+      }
+    } else {
+      const key = String(value);
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+  }
+  return counts;
+}
+function countRangeFromDocuments(state, fieldPath, fieldType, range, matched) {
+  let count = 0;
+  for (const value of matchedFieldValues(state, fieldPath, matched)) {
+    if ((fieldType === "number[]" || fieldType === UNDECLARED_FIELD_TYPE) && Array.isArray(value)) {
+      for (const v of value) {
+        if (v >= range.from && v < range.to) {
+          count++;
+          break;
+        }
+      }
+    } else if (typeof value === "number" && value >= range.from && value < range.to) {
+      count++;
+    }
+  }
+  return count;
+}
+function countNumericRanges(state, fieldPath, fieldType, ranges, bitset, matched) {
+  const counts = /* @__PURE__ */ new Map();
+  const index = state.numericIndexes.get(fieldPath);
+  for (const range of ranges) {
+    const label = `${range.from}-${range.to}`;
+    if (index === void 0) {
+      counts.set(label, countRangeFromDocuments(state, fieldPath, fieldType, range, matched));
+    } else if (Number.isNaN(range.from) || Number.isNaN(range.to)) {
+      counts.set(label, 0);
+    } else {
+      counts.set(label, index.facetRangeCount(range.from, range.to, bitset()));
+    }
+  }
+  return counts;
+}
+function countFieldValues(state, fieldPath, fieldType, bitset, matched) {
+  if (fieldType === "enum" || fieldType === "enum[]") {
+    const index = state.enumIndexes.get(fieldPath);
+    if (index !== void 0) return index.facetCounts(bitset());
+  } else if (fieldType === "boolean" || fieldType === "boolean[]") {
+    const index = state.booleanIndexes.get(fieldPath);
+    if (index !== void 0) {
+      const { trueCount, falseCount } = index.facetCounts(bitset());
+      const counts = /* @__PURE__ */ new Map();
+      if (trueCount > 0) counts.set("true", trueCount);
+      if (falseCount > 0) counts.set("false", falseCount);
+      return counts;
+    }
+  } else if (fieldType === "number" || fieldType === "number[]") {
+    const index = state.numericIndexes.get(fieldPath);
+    if (index !== void 0) {
+      const counts = /* @__PURE__ */ new Map();
+      for (const [value, count] of index.facetValueCounts(bitset())) {
+        counts.set(String(value), count);
+      }
+      return counts;
+    }
+  }
+  return countValuesFromDocuments(state, fieldPath, matched);
+}
+function computeFacets(state, matched, config, schema) {
+  const result = {};
+  const flatSchema = getFlatSchema(state, schema);
+  let matchedBitset = null;
+  const bitset = () => {
+    if (matchedBitset === null) matchedBitset = ordinalBitsetOf(state, matched);
+    return matchedBitset;
+  };
+  for (const [fieldPath, facetOpts] of Object.entries(config)) {
+    const fieldType = flatSchema[fieldPath] ?? UNDECLARED_FIELD_TYPE;
+    const valueCounts = facetOpts.ranges && (fieldType === "number" || fieldType === "number[]" || fieldType === UNDECLARED_FIELD_TYPE) ? countNumericRanges(state, fieldPath, fieldType, facetOpts.ranges, bitset, matched) : countFieldValues(state, fieldPath, fieldType, bitset, matched);
+    const ordered = Array.from(valueCounts.entries());
+    const sortDir = facetOpts.sort ?? "desc";
+    ordered.sort((a, b) => (sortDir === "asc" ? a[1] - b[1] : b[1] - a[1]) || compareCodePoints(a[0], b[0]));
+    const keep = Math.min(keptFacetValues(facetOpts.limit) ?? ordered.length, ordered.length);
+    const entries = ordered.slice(0, keep);
+    let errorBound = 0;
+    for (let index = keep; index < ordered.length; index++) {
+      if (ordered[index][1] > errorBound) errorBound = ordered[index][1];
+    }
+    const values = {};
+    for (const [key, count] of entries) {
+      values[key] = count;
+    }
+    result[fieldPath] = { values, count: entries.length, errorBound };
+  }
+  return result;
+}
+
+// src/search/oversample.ts
+function oversampledShardSize(size) {
+  return Math.ceil(size * 1.5) + 10;
+}
+
+// src/search/facets.ts
+function keptValueCount(fieldConfig) {
+  return keptFacetValues(fieldConfig?.limit);
+}
+function everyValueFacetConfig(config) {
+  const widened = {};
+  for (const [field, fieldConfig] of Object.entries(config)) {
+    widened[field] = { ...fieldConfig, limit: void 0 };
+  }
+  return widened;
+}
+function oversampledFacetConfig(config) {
+  const widened = {};
+  for (const [field, fieldConfig] of Object.entries(config)) {
+    if (fieldConfig?.ranges !== void 0 || fieldConfig?.sort === "asc") {
+      widened[field] = { ...fieldConfig, limit: void 0 };
+      continue;
+    }
+    const kept = keptValueCount(fieldConfig);
+    widened[field] = kept === void 0 ? fieldConfig : { ...fieldConfig, limit: oversampledShardSize(kept) };
+  }
+  return widened;
+}
+function mergeFacets(partitionFacets, config) {
+  const merged = /* @__PURE__ */ new Map();
+  const bounds = /* @__PURE__ */ new Map();
+  for (const partition of partitionFacets) {
+    for (const [field, facetResult] of Object.entries(partition)) {
+      let fieldMap = merged.get(field);
+      if (!fieldMap) {
+        fieldMap = /* @__PURE__ */ new Map();
+        merged.set(field, fieldMap);
+      }
+      bounds.set(field, (bounds.get(field) ?? 0) + facetResult.errorBound);
+      for (const [value, count] of Object.entries(facetResult.values)) {
+        fieldMap.set(value, (fieldMap.get(value) ?? 0) + count);
+      }
+    }
+  }
+  const result = {};
+  for (const [field, valueMap] of merged) {
+    const fieldConfig = config[field];
+    const ascending = fieldConfig?.sort === "asc";
+    const ordered = Array.from(valueMap.entries());
+    ordered.sort((a, b) => (ascending ? a[1] - b[1] : b[1] - a[1]) || compareCodePoints(a[0], b[0]));
+    const kept = Math.min(keptValueCount(fieldConfig) ?? ordered.length, ordered.length);
+    let largestLeftOut = 0;
+    for (let index = kept; index < ordered.length; index++) {
+      if (ordered[index][1] > largestLeftOut) largestLeftOut = ordered[index][1];
+    }
+    const errorBound = (bounds.get(field) ?? 0) + largestLeftOut;
+    const values = {};
+    for (let index = 0; index < kept; index++) {
+      values[ordered[index][0]] = ordered[index][1];
+    }
+    result[field] = { values, count: kept, errorBound };
+  }
+  return result;
+}
+
 // src/core/fuzzy.ts
+function fuzzyTermMatches(queryTerm, indexTerm, tolerance, prefixLength) {
+  if (queryTerm === indexTerm) return true;
+  if (tolerance <= 0) return false;
+  if (prefixLength > 0 && queryTerm.length >= prefixLength && !indexTerm.startsWith(queryTerm.slice(0, prefixLength))) {
+    return false;
+  }
+  return boundedLevenshtein(queryTerm, indexTerm, tolerance).withinTolerance;
+}
 function boundedLevenshtein(a, b, tolerance) {
   if (tolerance < 0) return { distance: -1, withinTolerance: false };
   if (a === b) return { distance: 0, withinTolerance: true };
@@ -827,6 +1080,234 @@ function decodeCursorText(encoded) {
   return new TextDecoder().decode(bytes);
 }
 
+// src/geo/constants.ts
+var DEG_TO_RAD = Math.PI / 180;
+var MIN_POLYGON_POINTS = 3;
+var ANTIMERIDIAN_SPAN_DEGREES = 180;
+var FULL_TURN_DEGREES = 360;
+var VINCENTY_MAX_ITERATIONS = 200;
+var VINCENTY_CONVERGENCE_THRESHOLD = 1e-12;
+
+// src/geo/polygon.ts
+function requirePolygonRing(points) {
+  if (!Array.isArray(points) || points.length < MIN_POLYGON_POINTS) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_FILTER,
+      `A polygon encloses an area only with at least ${MIN_POLYGON_POINTS} points`,
+      { points: Array.isArray(points) ? points.length : typeof points, minimum: MIN_POLYGON_POINTS }
+    );
+  }
+  points.forEach((point, position) => {
+    const { lat, lon } = point ?? {};
+    if (typeof lat === "number" && Number.isFinite(lat) && typeof lon === "number" && Number.isFinite(lon)) return;
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_FILTER,
+      `A polygon point carries a finite "lat" and "lon", and the point at position ${position} does not`,
+      { position }
+    );
+  });
+}
+function signedArea(polygon) {
+  let area = 0;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    area += polygon[j].lon * polygon[i].lat - polygon[i].lon * polygon[j].lat;
+  }
+  return area;
+}
+function crossesAntimeridian(polygon) {
+  let west = Number.POSITIVE_INFINITY;
+  let east = Number.NEGATIVE_INFINITY;
+  for (const point of polygon) {
+    if (point.lon < west) west = point.lon;
+    if (point.lon > east) east = point.lon;
+  }
+  return east - west >= ANTIMERIDIAN_SPAN_DEGREES && signedArea(polygon) < 0;
+}
+function eastward(lon) {
+  return lon < 0 ? lon + FULL_TURN_DEGREES : lon;
+}
+function polygonContainment(polygon) {
+  const n = polygon.length;
+  if (n < MIN_POLYGON_POINTS) return () => false;
+  const unwrap = crossesAntimeridian(polygon);
+  const lats = new Float64Array(n);
+  const lons = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    lats[i] = polygon[i].lat;
+    lons[i] = unwrap ? eastward(polygon[i].lon) : polygon[i].lon;
+  }
+  return (lat, rawLon) => {
+    const lon = unwrap ? eastward(rawLon) : rawLon;
+    let inside = false;
+    for (let i = 0, j = n - 1; i < n; j = i++) {
+      const lonI = lons[i];
+      const lonJ = lons[j];
+      if (lonI > lon !== lonJ > lon) {
+        const intersectLat = lats[i] + (lats[j] - lats[i]) / (lonJ - lonI) * (lon - lonI);
+        if (lat < intersectLat) inside = !inside;
+      }
+    }
+    return inside;
+  };
+}
+
+// src/filters/constants.ts
+var MAX_FILTER_DEPTH = 30;
+
+// src/filters/operands.ts
+var RANGE_OPERATORS = ["gt", "lt", "gte", "lte"];
+var TEXT_OPERATORS = ["startsWith", "endsWith"];
+var EQUALITY_OPERATORS = ["eq", "ne"];
+var LIST_OPERATORS = ["in", "nin"];
+function operandKindOf(type) {
+  if (type === void 0) return void 0;
+  if (type === "number" || type === "number[]") return "number";
+  if (type === "boolean" || type === "boolean[]") return "boolean";
+  if (type === "geopoint") return "geopoint";
+  if (type.startsWith("vector[")) return "vector";
+  return "text";
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function kindOfValue(value) {
+  if (isFiniteNumber(value)) return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "string") return "text";
+  return void 0;
+}
+function invalid(message, fieldPath, operator) {
+  throw new NarsilError(ErrorCodes.SEARCH_INVALID_FILTER, message, { fieldPath, operator });
+}
+function requireFieldKind(fieldPath, operator, type, accepted) {
+  const kind = operandKindOf(type);
+  if (kind === void 0 || accepted.includes(kind)) return;
+  invalid(
+    `The engine applies "${operator}" to ${accepted.join(" or ")} fields alone, and the schema declares field "${fieldPath}" as "${type}"`,
+    fieldPath,
+    operator
+  );
+}
+function requireRadius(fieldPath, radius) {
+  const circle = radius;
+  if (circle === null || typeof circle !== "object") {
+    invalid(`"radius" on field "${fieldPath}" must be an object`, fieldPath, "radius");
+  }
+  for (const key of ["lat", "lon", "distance"]) {
+    if (!isFiniteNumber(circle[key])) {
+      invalid(`"radius.${key}" on field "${fieldPath}" must be a finite number`, fieldPath, "radius");
+    }
+  }
+  if (circle.distance < 0) {
+    invalid(
+      `"radius.distance" on field "${fieldPath}" must be zero or more, and this filter sets ${String(circle.distance)}`,
+      fieldPath,
+      "radius"
+    );
+  }
+}
+function invalidShape(message) {
+  throw new NarsilError(ErrorCodes.SEARCH_INVALID_FILTER, message);
+}
+function isObjectRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function undeclaredFieldOnStrictIndex(field, option) {
+  return new NarsilError(
+    ErrorCodes.SEARCH_INVALID_FIELD,
+    `The index is strict and its schema declares no field "${field}", so no stored document has a value in that field for this ${option}`,
+    { field, option }
+  );
+}
+function requireValidExpression(expression, rules, depth) {
+  if (depth > MAX_FILTER_DEPTH) invalidShape(`A filter expression nests at most ${MAX_FILTER_DEPTH} levels deep`);
+  if (!isObjectRecord(expression)) invalidShape("Each filter expression must be an object");
+  const { fields, and, or, not } = expression;
+  if (fields !== void 0) {
+    if (!isObjectRecord(fields)) invalidShape('"fields" in a filter expression must be an object keyed by field path');
+    for (const [fieldPath, filter] of Object.entries(fields)) {
+      if (rules.declaredOnly && !Object.hasOwn(rules.fieldTypes, fieldPath)) {
+        throw undeclaredFieldOnStrictIndex(fieldPath, "filter");
+      }
+      if (isObjectRecord(filter)) requireValidOperands(fieldPath, filter, rules.fieldTypes[fieldPath]);
+    }
+  }
+  for (const [clause, list] of [
+    ["and", and],
+    ["or", or]
+  ]) {
+    if (list === void 0) continue;
+    if (!Array.isArray(list)) invalidShape(`"${clause}" in a filter expression must be a list of filter expressions`);
+    for (const nested of list) requireValidExpression(nested, rules, depth + 1);
+  }
+  if (not !== void 0) requireValidExpression(not, rules, depth + 1);
+}
+function requireValidFilter(expression, fieldTypes, declaredOnly = false) {
+  if (expression === void 0 || expression === null) return;
+  requireValidExpression(expression, { fieldTypes, declaredOnly }, 0);
+}
+function requireValidOperands(fieldPath, filter, type) {
+  for (const operator of RANGE_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    if (!isFiniteNumber(filter[operator])) {
+      invalid(`"${operator}" on field "${fieldPath}" must be a finite number`, fieldPath, operator);
+    }
+    requireFieldKind(fieldPath, operator, type, ["number"]);
+  }
+  if (filter.between !== void 0) {
+    const bounds = filter.between;
+    if (!Array.isArray(bounds) || bounds.length !== 2 || !isFiniteNumber(bounds[0]) || !isFiniteNumber(bounds[1])) {
+      invalid(
+        `"between" on field "${fieldPath}" must be two finite numbers, the lower bound first`,
+        fieldPath,
+        "between"
+      );
+    }
+    requireFieldKind(fieldPath, "between", type, ["number"]);
+  }
+  for (const operator of TEXT_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    if (typeof filter[operator] !== "string") {
+      invalid(`"${operator}" on field "${fieldPath}" must be a string`, fieldPath, operator);
+    }
+    requireFieldKind(fieldPath, operator, type, ["text"]);
+  }
+  for (const operator of EQUALITY_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    const kind = kindOfValue(filter[operator]);
+    if (kind === void 0) {
+      invalid(
+        `"${operator}" on field "${fieldPath}" must be a string, a finite number, or a boolean`,
+        fieldPath,
+        operator
+      );
+    }
+    requireFieldKind(fieldPath, operator, type, [kind]);
+  }
+  for (const operator of LIST_OPERATORS) {
+    if (filter[operator] === void 0) continue;
+    const values = filter[operator];
+    if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) {
+      invalid(`"${operator}" on field "${fieldPath}" must be a list of strings`, fieldPath, operator);
+    }
+    requireFieldKind(fieldPath, operator, type, ["text"]);
+  }
+  if (filter.size !== void 0) {
+    const size = filter.size;
+    if (size === null || typeof size !== "object") {
+      invalid(`"size" on field "${fieldPath}" must be a comparison object`, fieldPath, "size");
+    }
+    requireValidOperands(`${fieldPath}.size`, size, "number");
+  }
+  if (filter.radius !== void 0) requireRadius(fieldPath, filter.radius);
+  if (filter.polygon !== void 0) {
+    if (!isObjectRecord(filter.polygon)) {
+      invalid(`"polygon" on field "${fieldPath}" must be an object`, fieldPath, "polygon");
+    }
+    requirePolygonRing(filter.polygon.points);
+  }
+}
+
 // src/search/sorting.ts
 function isFieldList(sort) {
   return Array.isArray(sort);
@@ -834,29 +1315,71 @@ function isFieldList(sort) {
 function normalizeSort(sort) {
   if (sort === void 0) return [];
   if (isFieldList(sort)) {
-    return sort.map((entry) => ({ field: entry.field, direction: entry.direction }));
+    return sort.map(
+      (entry) => entry.mode === void 0 ? { field: entry.field, direction: entry.direction } : { field: entry.field, direction: entry.direction, mode: entry.mode }
+    );
   }
   return Object.entries(sort).map(([field, direction]) => ({ field, direction }));
 }
-function requireSortableFields(sort, schema) {
-  const fields = normalizeSort(sort);
-  if (fields.length === 0) return;
-  const flatSchema = flattenSchema(schema);
-  for (const entry of fields) {
-    if (flatSchema[entry.field] !== "string") continue;
+function sortModesOf(fields) {
+  return fields.map(sortModeOf);
+}
+function sortSignatureEntry(entry) {
+  const mode = sortModeOf(entry);
+  return mode === defaultSortMode(entry.direction) ? [entry.field, entry.direction] : [entry.field, entry.direction, mode];
+}
+function requireSortMode(entry, fieldType) {
+  if (entry.mode === void 0) return;
+  if (!isSortMode(entry.mode)) {
+    throw new NarsilError(
+      ErrorCodes.SEARCH_INVALID_MODE,
+      `A sort mode is one of ${SORT_MODES.map((mode) => `"${mode}"`).join(", ")}, and the mode on "${entry.field}" is "${String(entry.mode)}"`,
+      { field: entry.field, mode: String(entry.mode) }
+    );
+  }
+  const averages = entry.mode === "avg" || entry.mode === "median";
+  if (averages && fieldType !== void 0 && fieldType !== "number" && fieldType !== "number[]") {
     throw new NarsilError(
       ErrorCodes.SEARCH_INVALID_FIELD,
-      `A sort names text field "${entry.field}" only where the schema declares it "${SORTABLE_TEXT_FIELD_TYPE}", because ordering text costs far more memory per document than ordering a number`,
-      { field: entry.field, fieldType: "string" }
+      `The engine applies the "${entry.mode}" mode to a number field alone, and "${entry.field}" is a ${fieldType} field`,
+      { field: entry.field, fieldType, mode: entry.mode }
     );
   }
 }
-function readFieldValue(obj, path) {
-  return readSortField(obj, path);
+function requireSortableFields(sort, schema, strict = false) {
+  const fields = normalizeSort(sort);
+  if (fields.length === 0) return;
+  const flatSchema = flattenSchema(schema);
+  for (const entry of fields) {
+    const fieldType = flatSchema[entry.field];
+    if (strict && fieldType === void 0) throw undeclaredFieldOnStrictIndex(entry.field, "sort");
+    if (entry.direction !== "asc" && entry.direction !== "desc") {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_MODE,
+        `A sort direction is "asc" or "desc", and the direction on "${entry.field}" is "${String(entry.direction)}"`,
+        { field: entry.field, direction: String(entry.direction) }
+      );
+    }
+    requireSortMode(entry, fieldType);
+    if (fieldType === "string") {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_FIELD,
+        `The engine sorts by text field "${entry.field}" only where the schema declares it "${SORTABLE_TEXT_FIELD_TYPE}", because ordering text takes far more memory per document than ordering a number`,
+        { field: entry.field, fieldType }
+      );
+    }
+    if (isGeopointOrVectorType(fieldType)) {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_FIELD,
+        `The engine sorts by a number, boolean, enum, or sortable text field, and "${entry.field}" is a ${fieldType} field`,
+        { field: entry.field, fieldType }
+      );
+    }
+  }
 }
-function readSortValues(document, fields) {
-  if (!document) return fields.map(() => void 0);
-  return fields.map((field) => readFieldValue(document, field));
+function readSortValues(document, fields, modes) {
+  if (!document) return fields.map(() => null);
+  return fields.map((field, index) => toReducedSortValue(readSortField(document, field), modes[index] ?? "min"));
 }
 function applySorting(hits, sort, sortKeyOf) {
   const normalized = normalizeSort(sort);
@@ -874,7 +1397,7 @@ function applySorting(hits, sort, sortKeyOf) {
 }
 
 // src/search/cursor.ts
-var CURSOR_VERSION = 3;
+var CURSOR_VERSION = 4;
 function invalidCursor(cursor, reason) {
   const shown = cursor.length > 100 ? `${cursor.slice(0, 100)}...` : cursor;
   return new NarsilError(ErrorCodes.SEARCH_INVALID_CURSOR, `Failed to decode cursor: ${reason}`, { cursor: shown });
@@ -914,7 +1437,7 @@ function sortSignatureOf(sort) {
       );
     }
   }
-  return JSON.stringify(fields.map((entry) => [entry.field, entry.direction]));
+  return JSON.stringify(fields.map(sortSignatureEntry));
 }
 function encodePageCursor(cursor) {
   const payload = { v: CURSOR_VERSION, a: cursor.anchor };
@@ -924,6 +1447,7 @@ function encodePageCursor(cursor) {
   } else if (cursor.score !== null) {
     payload.s = cursor.score;
   }
+  if (cursor.depth !== void 0 && cursor.depth > 0) payload.d = cursor.depth;
   payload.q = cursor.binding;
   return encodeCursorText(JSON.stringify(payload));
 }
@@ -969,7 +1493,7 @@ function decodePageCursor(cursor) {
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw invalidCursor(cursor, "expected an object");
   }
-  const { v, a, s, k, o, q } = parsed;
+  const { v, a, s, k, o, d, q } = parsed;
   if (v !== CURSOR_VERSION) throw invalidCursor(cursor, `unsupported cursor version ${String(v)}`);
   if (typeof q !== "string" || !/^[0-9a-f]{8}$/.test(q)) {
     throw invalidCursor(cursor, '"q" must be 8 lowercase hex digits');
@@ -982,6 +1506,9 @@ function decodePageCursor(cursor) {
     throw invalidCursor(cursor, '"s" must be a finite number');
   }
   if (s !== void 0 && k !== void 0) throw invalidCursor(cursor, 'a cursor carries "s" or "k", never both');
+  if (d !== void 0 && (typeof d !== "number" || !Number.isSafeInteger(d) || d < 1)) {
+    throw invalidCursor(cursor, '"d" must be a positive integer');
+  }
   const sortKey = k === void 0 ? null : decodeSortKey(k, cursor);
   if (o !== void 0 && typeof o !== "string") throw invalidCursor(cursor, '"o" must be a string');
   if (sortKey === null !== (o === void 0)) {
@@ -992,6 +1519,7 @@ function decodePageCursor(cursor) {
     score: typeof s === "number" ? s : null,
     sortKey,
     sortSignature: typeof o === "string" ? o : null,
+    depth: typeof d === "number" ? d : 0,
     binding: q
   };
 }
@@ -1069,18 +1597,21 @@ function applyPagination(results, limit, offset, binding, cursor, sort, pinnedId
   let nextCursor;
   const hasMore = afterOffset + limit < results.length;
   const lastResult = lastOrganicResult(sliced, pinnedIds);
+  const depth = afterOffset + sliced.length;
   if (hasMore && lastResult !== void 0) {
     nextCursor = sort !== void 0 ? encodePageCursor({
       anchor: lastResult.id,
       score: null,
       sortKey: sort.sortKeyOf(lastResult.id).map(toComparableSortValue),
       sortSignature: sort.signature,
+      depth,
       binding
     }) : encodePageCursor({
       anchor: lastResult.id,
       score: lastResult.score ?? null,
       sortKey: null,
       sortSignature: null,
+      depth,
       binding
     });
   }
@@ -1152,7 +1683,7 @@ function fulltextMatches(partition, params, language, schema, options) {
     prefixExpansion: prepared.prefixExpansion,
     fields: params.fields,
     tolerance: params.tolerance ?? 0,
-    prefixLength: params.prefixLength ?? 2,
+    prefixLength: params.prefixLength ?? DEFAULT_FUZZY_PREFIX_LENGTH,
     exact: params.exact ?? false,
     filterBitset: prepared.filterBitset
   });
@@ -1173,7 +1704,7 @@ function fulltextSearch(partition, params, language, schema, options) {
     fields: params.fields,
     boost: params.boost,
     tolerance: params.tolerance ?? 0,
-    prefixLength: params.prefixLength ?? 2,
+    prefixLength: params.prefixLength ?? DEFAULT_FUZZY_PREFIX_LENGTH,
     exact: params.exact ?? false,
     bm25Params: options?.bm25Params,
     globalStats: options?.globalStats,
@@ -1333,20 +1864,21 @@ async function fanOutQuery(manager, params, language, schema, config, searchOpti
   if (config.dispatcher) {
     outcomes = await dispatchWithDispatcher(partitions, params, language, schema, options, config.dispatcher);
     if (params.facets) {
-      facets = collectAndMergeFacets(outcomes, params, schema);
+      facets = collectAndMergeFacets(outcomes, params.facets, schema);
     }
   } else {
     outcomes = [];
     const partitionFacets = [];
+    const everyValue = params.facets ? everyValueFacetConfig(params.facets) : void 0;
     for (const partition of partitions) {
       const result = dispatchSinglePartition(partition, params, language, schema, options);
-      if (params.facets) {
-        partitionFacets.push(partition.computeFacets(facetMatchSetOf(result), params.facets, schema));
+      if (everyValue) {
+        partitionFacets.push(partition.computeFacets(facetMatchSetOf(result), everyValue, schema));
       }
       outcomes.push({ result, partition });
     }
     if (params.facets) {
-      facets = mergeFacets(partitionFacets);
+      facets = mergeFacets(partitionFacets, params.facets);
     }
   }
   const allScoredArrays = outcomes.map((o) => o.result.scored);
@@ -1384,14 +1916,13 @@ function dispatchWithDispatcher(partitions, params, language, schema, options, d
 function dispatchSinglePartition(partition, params, language, schema, options) {
   return fulltextSearch(partition, params, language, schema, options);
 }
-function collectAndMergeFacets(outcomes, params, schema) {
+function collectAndMergeFacets(outcomes, facetConfig, schema) {
+  const everyValue = everyValueFacetConfig(facetConfig);
   const partitionFacets = [];
   for (const outcome of outcomes) {
-    if (!params.facets) continue;
-    const facetResult = outcome.partition.computeFacets(facetMatchSetOf(outcome.result), params.facets, schema);
-    partitionFacets.push(facetResult);
+    partitionFacets.push(outcome.partition.computeFacets(facetMatchSetOf(outcome.result), everyValue, schema));
   }
-  return mergeFacets(partitionFacets);
+  return mergeFacets(partitionFacets, facetConfig);
 }
 
 // src/partitioning/match-count.ts
@@ -1550,6 +2081,16 @@ function fnv1aBytes(bytes) {
   }
   return hash >>> 0;
 }
+function fnv1aUint32s(values) {
+  let hash = FNV_OFFSET_BASIS;
+  for (const value of values) {
+    for (let shift = 24; shift >= 0; shift -= 8) {
+      hash ^= value >>> shift & 255;
+      hash = Math.imul(hash, FNV_PRIME);
+    }
+  }
+  return hash >>> 0;
+}
 function fnv1a(input) {
   return fnv1aBytes(encoder.encode(input));
 }
@@ -1573,4 +2114,4 @@ function setNestedValue(obj, path, value) {
   current[segments[segments.length - 1]] = value;
 }
 
-export { applyPagination, applyProjection, applySorting, bitsetAnd, bitsetFromSet, bitsetHas, bitsetNot, bitsetOr, bitsetSet, boundedLevenshtein, clampRowCount, clearNormalizationCache, cloneProjected, collectQueryTermStats, configureNormalizationCache, countsWithoutScores, createBitSet, decodePageCursor, encodePageCursor, fanOutMatchCount, fanOutQuery, fnv1a, fnv1aBytes, fulltextMatches, getNormalizationCacheSize, kWayMerge, mergeFacets, mergePartitionStats, normalizeSort, partitionsIn, projectionKeepsField, pruneStatsToQueryTerms, readSortValues, requireMatchingCursor, requireSortableFields, requireWithinResultWindow, resetNormalizationCache, resolveProjection, sanitizeGlobalStats, setNestedValue, sortSignatureOf, tokenize, tokenizeIterator, visitTokens };
+export { DEG_TO_RAD, MAX_FILTER_DEPTH, MIN_POLYGON_POINTS, VINCENTY_CONVERGENCE_THRESHOLD, VINCENTY_MAX_ITERATIONS, applyPagination, applyProjection, applySorting, bitsetAnd, bitsetFromSet, bitsetHas, bitsetNot, bitsetOr, bitsetSet, boundedLevenshtein, clampRowCount, clearNormalizationCache, cloneProjected, collectQueryTermStats, computeFacets, configureNormalizationCache, countsWithoutScores, createBitSet, decodePageCursor, encodePageCursor, everyValueFacetConfig, fanOutMatchCount, fanOutQuery, fnv1a, fnv1aBytes, fnv1aUint32s, fulltextMatches, fuzzyTermMatches, getAllInternalDocIds, getFieldValueByInternalId, getFlatSchema, getNestedValue, getNormalizationCacheSize, getOrCreateFieldNameIndex, kWayMerge, mergeFacets, mergePartitionStats, normalizeSort, oversampledFacetConfig, oversampledShardSize, partitionsIn, polygonContainment, projectionKeepsField, pruneStatsToQueryTerms, readSortValues, requireMatchingCursor, requirePolygonRing, requireSortableFields, requireValidFilter, requireValidOperands, requireWithinResultWindow, resetNormalizationCache, resolveProjection, sanitizeGlobalStats, setNestedValue, sortModesOf, sortSignatureEntry, sortSignatureOf, textFieldsChanged, tokenize, tokenizeIterator, tokenizeOptions, undeclaredFieldOnStrictIndex, visitTokens };