@jarenjs/json 0.9.2 → 0.34.2

package/src/query/operators.js

@@ -30,10 +30,44 @@
 // All runtime error conditions of the operator library (JQ2xxx,
 // QUERY-FORMAT.md section 10.3) are raised here.
 
-import { equalsJson } from '@jarenjs/core/object';
+import { equalsJson, compareJsonScalarLt } from '@jarenjs/core/object';
 import { countCodePoints, compareCodePoints } from '@jarenjs/core/string';
 import { compileIRegexp } from '@jarenjs/core/text/iregexp';
-import { JsonQueryRuntimeError } from './errors.js';
+import {
+  parseRFC3339Parts,
+  epochOfRFC3339Parts,
+  formatRFC3339Parts,
+  partsFromEpoch,
+  isDateOnlyRFC3339,
+  isTimeOnlyRFC3339,
+  isDateTimeRFC3339,
+  isValidDuration,
+  isDateUnit,
+  addToParts,
+  startOfParts,
+  endOfParts,
+  parseDuration,
+  addDuration,
+  monthsBetween,
+  daysFromCivil,
+  isoWeekOfYear,
+  isoWeekdayFromDays,
+  quarterOfYear,
+  fixedUnitMs,
+  compileDateFormat,
+} from '@jarenjs/core/dates';
+import {
+  isPosition,
+  bboxOf,
+  bboxIntersects,
+  geometryArea,
+  geometryLength,
+  centroidOf,
+  containsPosition,
+  geoDistance,
+  geohashEncode,
+} from '@jarenjs/core/geo';
+import { JsonQueryCompileError, JsonQueryRuntimeError } from './errors.js';
 import {
   EMPTY, Seq, seqOf, appendItem, ebv, itemCount, firstItem,
   stableKeyString, describeItem,
@@ -67,6 +101,23 @@ const resultOfOperand = (cards) => cards[0];
 // a singleton operand stays a singleton; anything else may come out empty
 const resultEmptyPropagates = (cards) => (cards[0] === CARD_ONE ? CARD_ONE : CARD_OPT);
 
+// Static result-type declarations for `annotateTypes` (QUERY-FORMAT.md
+// Appendix C.8): `resultType(argTypes)` returns a tag name from the
+// closed lattice, or null for unknown. Declared only for the
+// comparison, arithmetic, string and aggregate families, and only where
+// the answer is certain — a wrong tag is a defect, `unknown` never is.
+const RT_BOOLEAN = () => 'boolean';
+const RT_NUMBER = () => 'number';
+const RT_INTEGER = () => 'integer';
+const RT_STRING = () => 'string';
+// $min/$max keep their operand family: numbers yield a number, strings
+// a string, anything else stays unknown (mixed input is JQ2001 anyway).
+const RT_MINMAX = (types) => {
+  const t = types[0].type;
+  if (t === 'number' || t === 'integer') return 'number';
+  return t === 'string' ? 'string' : null;
+};
+
 //#endregion
 
 //#region runtime argument helpers
@@ -166,18 +217,10 @@ function itemNe(a, b) {
   return !equalsJson(a, b);
 }
 function itemLt(a, b) {
-  if (typeof a === 'number')
-    return typeof b === 'number' && a < b;
-  if (typeof a === 'string')
-    return typeof b === 'string' && compareCodePoints(a, b) < 0;
-  return false;
+  return compareJsonScalarLt(a, b);
 }
 function itemLe(a, b) {
-  if (typeof a === 'number')
-    return typeof b === 'number' && a <= b;
-  if (typeof a === 'string')
-    return typeof b === 'string' && compareCodePoints(a, b) <= 0;
-  return false;
+  return compareJsonScalarLt(a, b, true);
 }
 function itemGt(a, b) {
   return itemLt(b, a);
@@ -194,6 +237,7 @@ function comparisonEntry(itemCmp) {
   return {
     params: ARGS_2,
     result: RESULT_ONE,
+    resultType: RT_BOOLEAN,
     compile: (gets, args) => {
       const left = gets[0];
       const right = gets[1];
@@ -247,10 +291,11 @@ function arithOperandError(v, docPath) {
 // non-number singletons and longer sequences are JQ2001. `makeApply`
 // builds the two-number kernel (it closes over the operator docPath for
 // the JQ2002 zero-divisor errors of $idiv/$mod).
-function arithmeticEntry(makeApply) {
+function arithmeticEntry(makeApply, resultType = RT_NUMBER) {
   return {
     params: ARGS_2,
     result: (cards) => (cards[0] === CARD_ONE && cards[1] === CARD_ONE ? CARD_ONE : CARD_OPT),
+    resultType,
     compile: (gets, args, docPath) => {
       const apply = makeApply(docPath);
       const left = gets[0];
@@ -311,10 +356,11 @@ function logicEntry(stopOn) {
 //#region string operators
 
 // unary string operator: coerce per stringArg, apply the kernel
-function stringUnaryEntry(apply) {
+function stringUnaryEntry(apply, resultType = RT_STRING) {
   return {
     params: UNARY,
     result: RESULT_ONE,
+    resultType,
     compile: (gets, args) => {
       const get = gets[0];
       const docPath = args[0].docPath;
@@ -328,6 +374,7 @@ function stringPairEntry(test) {
   return {
     params: ARGS_2,
     result: RESULT_ONE,
+    resultType: RT_BOOLEAN,
     compile: (gets, args) => {
       const aGet = gets[0];
       const aPath = args[0].docPath;
@@ -367,6 +414,7 @@ function regexTestEntry(fullMatch) {
   return {
     params: ARGS_2,
     result: RESULT_ONE,
+    resultType: RT_BOOLEAN,
     compile: (gets, args) => {
       const inGet = gets[0];
       const inPath = args[0].docPath;
@@ -473,6 +521,7 @@ function minmaxEntry(isMax) {
   return {
     params: UNARY,
     result: resultEmptyPropagates,
+    resultType: RT_MINMAX,
     compile: (gets, args) => {
       const get = gets[0];
       const docPath = args[0].docPath;
@@ -543,11 +592,211 @@ function rangeBoundError(v, docPath) {
   return runtimeError('JQ2001', `'$range' bounds must be integral numbers, got ${describeItem(v)}`, docPath);
 }
 
+/**
+ * Check one evaluated `$range` bound. Shared with the compiler's
+ * iteration fast path (compile.js), so a range that is iterated rather
+ * than materialized still rejects exactly the same bounds.
+ * @param {any} v - an evaluated bound
+ * @param {string} docPath - the bound's document pointer
+ * @returns {number} the bound
+ * @throws {JsonQueryRuntimeError} JQ2001 when it is not an integer
+ */
+export function checkRangeBound(v, docPath) {
+  if (typeof v !== 'number' || !Number.isInteger(v))
+    throw rangeBoundError(v, docPath);
+  return v;
+}
+
 // the resource guard of $range (section 10.3, JQ2007)
 const RANGE_LIMIT = 4294967296; // 2^32
 
 //#endregion
 
+//#region date and time operators (section 8.13)
+// Dates are RFC 3339 strings - JSON has no date type - and every operator
+// here is a pure function of its operand: there is deliberately no
+// `current-dateTime`, because a query must give the same answer for the
+// same input document forever (it is cached by document identity, saved
+// as a rule, and used as a validation keyword).
+//
+// Components are read LEXICALLY, in the value's own offset, which is
+// what `fn:year-from-dateTime` returns and what grouping by year or
+// month means. Cross-offset comparison and arithmetic go through
+// `$epoch`, which is the one place a value is shifted to UTC.
+
+// a single RFC 3339 operand, decomposed (JQ2001 on anything else)
+function dateParts(v, docPath) {
+  const parts = parseRFC3339Parts(v);
+  if (parts === null) {
+    // a malformed string is the common case here, so show it rather than
+    // reporting the useless fact that it was a string
+    throw runtimeError('JQ2001', 'expected an RFC 3339 date, time, or date-time string, got '
+      + (typeof v === 'string' ? JSON.stringify(v) : describeItem(v)), docPath);
+  }
+  return parts;
+}
+
+// a lexical component operator: empty propagates, a value whose half is
+// missing (asking a full-date for its hours) is JQ2001
+function dateComponentEntry(pick, half) {
+  return {
+    params: UNARY,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        const n = pick(dateParts(v, docPath));
+        if (n < 0)
+          throw runtimeError('JQ2001', `'${v}' carries no ${half} component`, docPath);
+        return n;
+      };
+    },
+  };
+}
+
+// A calendar unit argument. Units are data, not vocabulary, so a bad one
+// is a runtime JQ2001 rather than a compile error - the same treatment
+// `$orderby`'s registered collation names get.
+function unitArg(v, docPath) {
+  if (!isDateUnit(v)) {
+    throw runtimeError('JQ2001',
+      `expected a calendar unit ('year', 'month', 'day', ...), got ${describeItem(v)}`, docPath);
+  }
+  return v;
+}
+
+// The shared shape of $date-add / $date-sub: [date, duration] applies an
+// ISO 8601 duration, [date, amount, unit] applies one unit. Both return
+// the same lexical form they were given, so a full-date stays a
+// full-date - a query that buckets dates should not silently start
+// producing date-times.
+function dateShiftEntry(sign) {
+  return {
+    params: ARGS_2_3,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const dateGet = gets[0];
+      const datePath = args[0].docPath;
+      const secondGet = gets[1];
+      const secondPath = args[1].docPath;
+      const unitGet = gets.length === 3 ? gets[2] : null;
+      const unitPath = unitGet === null ? '' : args[2].docPath;
+      return (f) => {
+        const value = dateGet(f);
+        if (value === EMPTY)
+          return EMPTY;
+        const parts = dateParts(value, datePath);
+        const second = secondGet(f);
+        if (second === EMPTY)
+          return EMPTY;
+        if (unitGet === null) {
+          const duration = parseDuration(second);
+          if (duration === null) {
+            throw runtimeError('JQ2001', 'expected an ISO 8601 duration, got '
+              + (typeof second === 'string' ? JSON.stringify(second) : describeItem(second)),
+            secondPath);
+          }
+          return formatRFC3339Parts(addDuration(parts, duration, sign));
+        }
+        if (typeof second !== 'number')
+          throw runtimeError('JQ2001', `expected a number of units, got ${describeItem(second)}`, secondPath);
+        const unit = unitArg(unitGet(f), unitPath);
+        return formatRFC3339Parts(addToParts(parts, sign * second, unit));
+      };
+    },
+  };
+}
+
+// $start-of / $end-of: truncate to a calendar unit, keeping the lexical
+// form. A full-date's end of month is that month's last day, not its
+// last millisecond - there is nowhere in a full-date to put one.
+function dateTruncEntry(truncate) {
+  return {
+    params: ARGS_2,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const dateGet = gets[0];
+      const datePath = args[0].docPath;
+      const unitGet = gets[1];
+      const unitPath = args[1].docPath;
+      return (f) => {
+        const value = dateGet(f);
+        if (value === EMPTY)
+          return EMPTY;
+        const parts = dateParts(value, datePath);
+        return formatRFC3339Parts(truncate(parts, unitArg(unitGet(f), unitPath)));
+      };
+    },
+  };
+}
+
+//#region spatial operators (section 8.14)
+// PostGIS's ST_* set, in the vocabulary this language already has. The
+// operand is GeoJSON (RFC 7946) — a bare position, a geometry, a Feature
+// or a FeatureCollection — because that is what a JSON document holds;
+// there is no geometry type to construct first.
+//
+// Coordinates are longitude, latitude, in WGS 84 decimal degrees, and
+// measurements are geodesic. That matters: a degree of longitude is not
+// a fixed distance, so a planar answer is wrong by two thirds at Dutch
+// latitudes. These operators never return a planar number.
+//
+// What is deliberately absent is real geometry-to-geometry intersection.
+// `$bbox-intersects` says exactly what it tests, because an operator
+// named `$intersects` that only compared bounding boxes would be a lie
+// the first time two L-shapes shared a box and nothing else.
+
+// A spatial operand, rejected uniformly: the empty sequence propagates
+// at the call site, so this only ever sees a real item.
+function geoArg(v, docPath) {
+  if (v === EMPTY || v instanceof Seq || v === null || typeof v !== 'object') {
+    throw runtimeError('JQ2001',
+      `expected a GeoJSON value or a [longitude, latitude] position, got ${describeItem(v)}`,
+      docPath);
+  }
+  return v;
+}
+
+// a unary spatial measurement: empty propagates, anything else is JQ2001
+function geoUnaryEntry(measure, resultCard = resultEmptyPropagates) {
+  return {
+    params: UNARY,
+    result: resultCard,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        const out = measure(geoArg(v, docPath));
+        return out === null ? EMPTY : out;
+      };
+    },
+  };
+}
+
+//#endregion
+
+// the RFC 3339 type tests, shaped like the section 8.10 $is-* family:
+// one item of the right lexical form, never an error
+function dateTestEntry(test) {
+  return {
+    params: UNARY,
+    result: RESULT_ONE,
+    compile: (gets) => {
+      const get = gets[0];
+      return (f) => test(get(f));
+    },
+  };
+}
+
+//#endregion
+
 //#region the registry
 
 /**
@@ -632,7 +881,7 @@ export const OPERATORS = Object.freeze({
     if (b === 0)
       throw runtimeError('JQ2002', "'$idiv' by zero", docPath);
     return Math.trunc(a / b);
-  }),
+  }, RT_INTEGER),
   // XQuery double mod takes the sign of the dividend = JS %
   '$mod': arithmeticEntry((docPath) => (a, b) => {
     if (b === 0)
@@ -689,6 +938,7 @@ export const OPERATORS = Object.freeze({
   '$concat': {
     params: ARGS_0N,
     result: RESULT_ONE,
+    resultType: RT_STRING,
     compile: (gets, args) => {
       if (gets.length === 0)
         return () => '';
@@ -709,6 +959,7 @@ export const OPERATORS = Object.freeze({
   '$string-join': {
     params: ARGS_1_2,
     result: RESULT_ONE,
+    resultType: RT_STRING,
     compile: (gets, args) => {
       const seqGet = gets[0];
       const seqPath = args[0].docPath;
@@ -733,6 +984,7 @@ export const OPERATORS = Object.freeze({
   '$substring': {
     params: ARGS_2_3,
     result: RESULT_ONE,
+    resultType: RT_STRING,
     compile: (gets, args) => {
       const sGet = gets[0];
       const sPath = args[0].docPath;
@@ -772,7 +1024,7 @@ export const OPERATORS = Object.freeze({
 
   '$upper': stringUnaryEntry((s) => s.toUpperCase()),
   '$lower': stringUnaryEntry((s) => s.toLowerCase()),
-  '$string-length': stringUnaryEntry(countCodePoints),
+  '$string-length': stringUnaryEntry(countCodePoints, RT_INTEGER),
   '$normalize-space': stringUnaryEntry(normalizeSpace),
 
   '$match': regexTestEntry(true),
@@ -781,6 +1033,7 @@ export const OPERATORS = Object.freeze({
   '$replace': {
     params: ARGS_3,
     result: RESULT_ONE,
+    resultType: RT_STRING,
     compile: compileReplace,
   },
 
@@ -793,6 +1046,7 @@ export const OPERATORS = Object.freeze({
   '$count': {
     params: UNARY,
     result: RESULT_ONE,
+    resultType: RT_INTEGER,
     compile: (gets) => {
       const get = gets[0];
       return (f) => itemCount(get(f));
@@ -802,6 +1056,7 @@ export const OPERATORS = Object.freeze({
   '$sum': {
     params: UNARY,
     result: RESULT_ONE,
+    resultType: RT_NUMBER,
     compile: (gets, args) => {
       const get = gets[0];
       const docPath = args[0].docPath;
@@ -824,6 +1079,7 @@ export const OPERATORS = Object.freeze({
   '$avg': {
     params: UNARY,
     result: resultEmptyPropagates,
+    resultType: RT_NUMBER,
     compile: (gets, args) => {
       const get = gets[0];
       const docPath = args[0].docPath;
@@ -1008,25 +1264,28 @@ export const OPERATORS = Object.freeze({
   '$range': {
     params: ARGS_2,
     result: RESULT_MANY,
-    compile: (gets, args, docPath) => {
+    compile: (gets, args, docPath, node) => {
       const fromGet = gets[0];
       const fromPath = args[0].docPath;
       const toGet = gets[1];
       const toPath = args[1].docPath;
+      // the compilation's limits.sequenceItems tightens the resource
+      // guard below its 2^32 ceiling
+      const cap = node !== undefined && node.limits != null && node.limits.sequenceItems !== null
+        ? Math.min(node.limits.sequenceItems, RANGE_LIMIT)
+        : RANGE_LIMIT;
       return (f) => {
         const a = fromGet(f);
         const b = toGet(f);
         if (a === EMPTY || b === EMPTY) // XQuery `to`: empty operand, empty range
           return EMPTY;
-        if (typeof a !== 'number' || !Number.isInteger(a))
-          throw rangeBoundError(a, fromPath);
-        if (typeof b !== 'number' || !Number.isInteger(b))
-          throw rangeBoundError(b, toPath);
+        checkRangeBound(a, fromPath);
+        checkRangeBound(b, toPath);
         if (a > b)
           return EMPTY;
         const n = b - a + 1;
-        if (n > RANGE_LIMIT)
-          throw runtimeError('JQ2007', `'$range' of ${n} items exceeds the 2^32-item resource guard`, docPath);
+        if (n > cap)
+          throw runtimeError('JQ2007', `'$range' of ${n} items exceeds the ${cap === RANGE_LIMIT ? '2^32-item' : String(cap) + '-item'} resource guard`, docPath);
         const out = new Array(n);
         for (let i = 0; i < n; i++)
           out[i] = a + i;
@@ -1063,6 +1322,59 @@ export const OPERATORS = Object.freeze({
     },
   },
 
+  '$entries': {
+    params: UNARY,
+    result: RESULT_MANY,
+    compile: (gets) => {
+      const get = gets[0];
+      // the member-pair counterpart of `[*]` (which yields values only):
+      // each OBJECT item contributes one `{ "key": name, "value": v }`
+      // per member, in member order; non-object items contribute
+      // nothing, like every other type mismatch in this family
+      return (f) => {
+        const v = get(f);
+        const items = v instanceof Seq ? v.items : (v === EMPTY ? [] : [v]);
+        const out = [];
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i];
+          if (typeof item !== 'object' || item === null || Array.isArray(item))
+            continue;
+          for (const key of Object.keys(item))
+            out.push({ key, value: item[key] });
+        }
+        return seqOf(out);
+      };
+    },
+  },
+
+  '$from-entries': {
+    params: UNARY,
+    result: RESULT_ONE,
+    compile: (gets) => {
+      const get = gets[0];
+      // the inverse of $entries: assemble one object from
+      // `{ "key": name, "value": v }` items, in sequence order. Later
+      // pairs win on duplicate keys, like the $map constructor; items
+      // without a string `key` contribute nothing; a missing `value`
+      // member reads as null (undefined is not a JSON value)
+      return (f) => {
+        const v = get(f);
+        const items = v instanceof Seq ? v.items : (v === EMPTY ? [] : [v]);
+        /** @type {Record<string, any>} */
+        const out = {};
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i];
+          if (typeof item !== 'object' || item === null || Array.isArray(item))
+            continue;
+          if (typeof item.key !== 'string')
+            continue;
+          out[item.key] = hasOwn(item, 'value') ? item.value : null;
+        }
+        return out;
+      };
+    },
+  },
+
   //#endregion
 
   //#region section 8.10 - types and casts
@@ -1191,6 +1503,291 @@ export const OPERATORS = Object.freeze({
   },
 
   //#endregion
+
+  //#region section 8.13 - dates and times
+
+  '$is-date': dateTestEntry(isDateOnlyRFC3339),
+  '$is-time': dateTestEntry(isTimeOnlyRFC3339),
+  '$is-datetime': dateTestEntry(isDateTimeRFC3339),
+  '$is-duration': dateTestEntry(isValidDuration),
+
+  //#endregion
+
+  //#region section 8.14 - spatial
+
+  '$bbox': geoUnaryEntry(bboxOf),
+  '$area': geoUnaryEntry(geometryArea, RESULT_ONE),
+  '$length': geoUnaryEntry(geometryLength, RESULT_ONE),
+  '$centroid': geoUnaryEntry(centroidOf),
+
+  '$distance': { // metres between two values' representative positions
+    params: ARGS_2,
+    result: RESULT_OPT,
+    compile: (gets, args) => {
+      const aGet = gets[0];
+      const aPath = args[0].docPath;
+      const bGet = gets[1];
+      const bPath = args[1].docPath;
+      return (f) => {
+        const a = aGet(f);
+        const b = bGet(f);
+        if (a === EMPTY || b === EMPTY)
+          return EMPTY;
+        const out = geoDistance(geoArg(a, aPath), geoArg(b, bPath));
+        return out === null ? EMPTY : out;
+      };
+    },
+  },
+
+  '$within': { // is the first value's position inside the second's surface
+    params: ARGS_2,
+    result: RESULT_ONE,
+    compile: (gets, args) => {
+      const pointGet = gets[0];
+      const pointPath = args[0].docPath;
+      const areaGet = gets[1];
+      const areaPath = args[1].docPath;
+      return (f) => {
+        const point = pointGet(f);
+        const area = areaGet(f);
+        if (point === EMPTY || area === EMPTY)
+          return false; // nothing is inside nothing
+        const p = geoArg(point, pointPath);
+        // a bare position is itself; anything else is represented by its
+        // centroid, the same rule $distance uses
+        const at = isPosition(p) ? p : centroidOf(p);
+        if (at === null)
+          return false;
+        return containsPosition(geoArg(area, areaPath), at[0], at[1]);
+      };
+    },
+  },
+
+  '$bbox-intersects': { // do the two values' bounding boxes overlap
+    params: ARGS_2,
+    result: RESULT_ONE,
+    compile: (gets, args) => {
+      const aGet = gets[0];
+      const aPath = args[0].docPath;
+      const bGet = gets[1];
+      const bPath = args[1].docPath;
+      return (f) => {
+        const a = aGet(f);
+        const b = bGet(f);
+        if (a === EMPTY || b === EMPTY)
+          return false;
+        const boxA = bboxOf(geoArg(a, aPath));
+        const boxB = bboxOf(geoArg(b, bPath));
+        return boxA !== null && boxB !== null && bboxIntersects(boxA, boxB);
+      };
+    },
+  },
+
+  '$geohash': { // a position as a base-32 cell string
+    params: ARGS_1_2,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      const precisionGet = gets.length === 2 ? gets[1] : null;
+      const precisionPath = precisionGet === null ? '' : args[1].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        const value = geoArg(v, docPath);
+        const at = isPosition(value) ? value : centroidOf(value);
+        if (at === null)
+          return EMPTY;
+        let precision = 9;
+        if (precisionGet !== null) {
+          precision = precisionGet(f);
+          if (!Number.isInteger(precision) || precision < 1 || precision > 12) {
+            throw runtimeError('JQ2001',
+              `a geohash precision must be an integer from 1 to 12, got ${describeItem(precision)}`,
+              precisionPath);
+          }
+        }
+        return geohashEncode(at[0], at[1], precision);
+      };
+    },
+  },
+
+  //#endregion
+
+  //#region section 8.13 - dates and times, continued
+
+  '$date-add': dateShiftEntry(1),
+  '$date-sub': dateShiftEntry(-1),
+  '$start-of': dateTruncEntry(startOfParts),
+  '$end-of': dateTruncEntry(endOfParts),
+
+  '$date-diff': { // whole units from the first date to the second
+    params: ARGS_3,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const fromGet = gets[0];
+      const fromPath = args[0].docPath;
+      const toGet = gets[1];
+      const toPath = args[1].docPath;
+      const unitGet = gets[2];
+      const unitPath = args[2].docPath;
+      return (f) => {
+        const fromValue = fromGet(f);
+        const toValue = toGet(f);
+        if (fromValue === EMPTY || toValue === EMPTY)
+          return EMPTY;
+        const from = dateParts(fromValue, fromPath);
+        const to = dateParts(toValue, toPath);
+        const unit = unitArg(unitGet(f), unitPath);
+        // months, quarters and years have no fixed width, so they are
+        // counted on the calendar; everything else divides an exact span
+        if (unit === 'month' || unit === 'quarter' || unit === 'year') {
+          const months = monthsBetween(from, to);
+          return unit === 'month' ? months
+            : Math.trunc(months / (unit === 'quarter' ? 3 : 12));
+        }
+        const fromMs = epochOfRFC3339Parts(from);
+        const toMs = epochOfRFC3339Parts(to);
+        if (fromMs !== fromMs || toMs !== toMs)
+          throw runtimeError('JQ2001', 'cannot measure a span from a value with no date', fromPath);
+        return Math.trunc((toMs - fromMs) / fixedUnitMs(unit));
+      };
+    },
+  },
+
+  '$date-format': { // an LDML pattern, compiled once when it is literal
+    params: ARGS_2,
+    result: resultEmptyPropagates,
+    compile: (gets, args, docPath) => {
+      const dateGet = gets[0];
+      const datePath = args[0].docPath;
+      const patternNode = args[1];
+      // the common case is a literal pattern: compile it at query
+      // compile time, so a bad one is a compile error, not a surprise
+      if (patternNode.kind === 'literal' && typeof patternNode.value === 'string') {
+        let format;
+        try {
+          format = compileDateFormat(patternNode.value);
+        }
+        catch (e) {
+          // a literal pattern is authored, not data: reject the document
+          throw new JsonQueryCompileError('JQ0003',
+            `'$date-format' pattern: ${e instanceof Error ? e.message : 'invalid'}`,
+            docPath, { cause: e });
+        }
+        return (f) => {
+          const v = dateGet(f);
+          return v === EMPTY ? EMPTY : format(dateParts(v, datePath));
+        };
+      }
+      // a dynamic pattern gets the monomorphic per-callsite cache the
+      // regex operators use: a filter almost always sees one pattern
+      const patternGet = gets[1];
+      const patternPath = patternNode.docPath;
+      let lastPattern = null;
+      let lastFormat = null;
+      return (f) => {
+        const v = dateGet(f);
+        if (v === EMPTY)
+          return EMPTY;
+        const pattern = patternGet(f);
+        if (typeof pattern !== 'string')
+          throw runtimeError('JQ2001', `expected a date pattern, got ${describeItem(pattern)}`, patternPath);
+        if (pattern !== lastPattern) {
+          lastPattern = pattern;
+          try {
+            lastFormat = compileDateFormat(pattern);
+          }
+          catch (e) {
+            lastFormat = null;
+            throw runtimeError('JQ2001',
+              `'$date-format' pattern: ${e instanceof Error ? e.message : 'invalid'}`, patternPath);
+          }
+        }
+        return lastFormat(dateParts(v, datePath));
+      };
+    },
+  },
+
+  '$week': dateComponentEntry(
+    (p) => (p.year < 0 ? -1 : isoWeekOfYear(p).week), 'date'),
+  '$week-year': dateComponentEntry(
+    (p) => (p.year < 0 ? -1 : isoWeekOfYear(p).year), 'date'),
+  '$quarter': dateComponentEntry(
+    (p) => (p.year < 0 ? -1 : quarterOfYear(p)), 'date'),
+  '$weekday': dateComponentEntry(
+    (p) => (p.year < 0 ? -1 : isoWeekdayFromDays(daysFromCivil(p.year, p.month, p.day))), 'date'),
+
+  '$year': dateComponentEntry((p) => p.year, 'date'),
+  '$month': dateComponentEntry((p) => p.month, 'date'),
+  '$day': dateComponentEntry((p) => p.day, 'date'),
+  '$hours': dateComponentEntry((p) => p.hours, 'time'),
+  '$minutes': dateComponentEntry((p) => p.minutes, 'time'),
+  '$seconds': dateComponentEntry((p) => p.seconds, 'time'),
+
+  '$offset': { // minutes east of UTC; a bare full-date carries none
+    params: UNARY,
+    result: RESULT_OPT,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        const offset = dateParts(v, docPath).offset;
+        return offset === null ? EMPTY : offset;
+      };
+    },
+  },
+
+  '$epoch': { // the one shift to UTC: milliseconds since 1970-01-01Z
+    params: UNARY,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        const ms = epochOfRFC3339Parts(dateParts(v, docPath));
+        if (ms !== ms) // a full-time has no instant to place
+          throw runtimeError('JQ2001', `'${v}' carries no date component`, docPath);
+        return ms;
+      };
+    },
+  },
+
+  '$datetime': { // the inverse of $epoch, in canonical UTC form
+    params: UNARY,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        if (typeof v !== 'number')
+          throw runtimeError('JQ2001',
+            `'$datetime' takes epoch milliseconds, got ${describeItem(v)}`, docPath);
+        // outside ±8.64e15 ms, and outside years 0000-9999, there is no
+        // RFC 3339 spelling of the instant. Rendering goes through the
+        // kernel like every other date operator, so one query cannot
+        // emit two spellings of the same fraction.
+        const iso = Number.isFinite(v) && Math.abs(v) <= 8.64e15
+          ? formatRFC3339Parts(partsFromEpoch(v))
+          : '';
+        if (!isDateTimeRFC3339(iso))
+          throw runtimeError('JQ2001', `${v} is outside the range RFC 3339 can spell`, docPath);
+        return iso;
+      };
+    },
+  },
+
+  //#endregion
 });
 
 // singleton type predicates (section 8.10): true iff the operand is one