@jarenjs/json 0.46.4 → 0.49.2

package/schemas/jaren-query.llm-profile.schema.json

@@ -160,6 +160,15 @@
         },
         {
           "$ref": "#/$defs/schemaOperatorPhrase"
+        },
+        {
+          "$ref": "#/$defs/seriesSpecPhrase"
+        },
+        {
+          "$ref": "#/$defs/asOfPhrase"
+        },
+        {
+          "$ref": "#/$defs/timeBucketPhrase"
         }
       ]
     },
@@ -607,6 +616,226 @@
         "maxItems": 2
       }
     },
+    "seriesSpec": {
+      "description": "A $resample or $rolling spec (QUERY-FORMAT.md section 8.16): a VERBATIM literal, never an expression, so the width, the aggregate, the fill policy, the wall clock and the row selectors are read once when the query compiles. Closed: an unknown member is JQ0003. 'every'/'width' is an ISO 8601 duration or a count of milliseconds; 'origin'/'start'/'end' are epoch milliseconds or an RFC 3339 string; 'at'/'value' are singular paths where '$' reads as the ROW. A named 'zone' needs an injected zoneProvider - this suite bundles no time-zone database.",
+      "type": "object",
+      "properties": {
+        "every": {
+          "$ref": "#/$defs/seriesSpan"
+        },
+        "width": {
+          "$ref": "#/$defs/seriesSpan"
+        },
+        "origin": {
+          "$ref": "#/$defs/seriesInstant"
+        },
+        "start": {
+          "$ref": "#/$defs/seriesInstant"
+        },
+        "end": {
+          "$ref": "#/$defs/seriesInstant"
+        },
+        "aggregate": {
+          "enum": [
+            "sum",
+            "mean",
+            "min",
+            "max",
+            "first",
+            "last",
+            "count"
+          ]
+        },
+        "fill": {
+          "enum": [
+            "omit",
+            "null",
+            "zero",
+            "locf",
+            "linear"
+          ]
+        },
+        "minPeriods": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "at": {
+          "$ref": "#/$defs/rowSelector"
+        },
+        "value": {
+          "$ref": "#/$defs/rowSelector"
+        },
+        "zone": {
+          "type": "string",
+          "minLength": 1
+        },
+        "offset": {
+          "type": "number"
+        },
+        "disambiguation": {
+          "enum": [
+            "reject",
+            "earlier",
+            "later"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "seriesSpan": {
+      "description": "A width: an ISO 8601 duration string ('PT1H', 'P1M') or a count of milliseconds. A duration mixing the calendar and clock families ('P1MT1H') is refused by the compiler.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      ]
+    },
+    "seriesInstant": {
+      "description": "An instant: epoch milliseconds, or an RFC 3339 string. A full-time names no instant and is refused by the compiler.",
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string",
+          "minLength": 1
+        }
+      ]
+    },
+    "rowSelector": {
+      "description": "Where a member lives in a source row: a singular JSONPath whose '$' is the ROW rather than the document ('$.on', \"$['recorded at']\", '$.meta.at'). Wildcards, descendants and filters are refused (JQ0003) - a selector names one member.",
+      "type": "string",
+      "pattern": "^\\$[.\\[]"
+    },
+    "seriesSpecPhrase": {
+      "description": "$resample / $rolling [series, spec]: an operand expression and a VERBATIM spec literal. $resample returns sorted {at, value, count} buckets one per 'every'; $rolling returns one row per input instant over a window measured in time. (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "additionalProperties": {
+        "type": "array",
+        "prefixItems": [
+          {
+            "$ref": "#/$defs/expression"
+          },
+          {
+            "$ref": "#/$defs/seriesSpec"
+          }
+        ],
+        "items": false,
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "asOfSpec": {
+      "description": "The $asof spec (QUERY-FORMAT.md section 8.16): a VERBATIM literal. 'by' joins within groups; 'leftAt'/'rightAt' say where each side keeps its instant when the two documents spell it differently. Closed: an unknown member is JQ0003.",
+      "type": "object",
+      "properties": {
+        "direction": {
+          "enum": [
+            "backward",
+            "forward",
+            "nearest"
+          ]
+        },
+        "tolerance": {
+          "$ref": "#/$defs/seriesSpan"
+        },
+        "by": {
+          "$ref": "#/$defs/rowSelector"
+        },
+        "leftAt": {
+          "$ref": "#/$defs/rowSelector"
+        },
+        "rightAt": {
+          "$ref": "#/$defs/rowSelector"
+        }
+      },
+      "additionalProperties": false
+    },
+    "asOfPhrase": {
+      "description": "$asof [left, right] or [left, right, spec]: two operand expressions and an optional VERBATIM spec literal. Answers one {left, right, distance} per left row; a left row with no match keeps right: null and stays in the answer.",
+      "type": "object",
+      "properties": {
+        "$asof": {
+          "type": "array",
+          "prefixItems": [
+            {
+              "$ref": "#/$defs/expression"
+            },
+            {
+              "$ref": "#/$defs/expression"
+            },
+            {
+              "$ref": "#/$defs/asOfSpec"
+            }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 3
+        }
+      },
+      "required": [
+        "$asof"
+      ],
+      "additionalProperties": false
+    },
+    "calendarContext": {
+      "description": "$time-bucket's optional fourth position: the wall clock its boundaries fall on. UTC is the default and needs nothing; a named 'zone' needs an injected zoneProvider.",
+      "type": "object",
+      "properties": {
+        "zone": {
+          "type": "string",
+          "minLength": 1
+        },
+        "offset": {
+          "type": "number"
+        },
+        "disambiguation": {
+          "enum": [
+            "reject",
+            "earlier",
+            "later"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "timeBucketPhrase": {
+      "description": "$time-bucket [at, every] / [at, every, origin] / [at, every, origin, context]: the instant labelling the bucket 'at' falls in. The first three positions are operand expressions ('origin' may be null for the ladder's own default); the fourth is a VERBATIM calendar context literal.",
+      "type": "object",
+      "properties": {
+        "$time-bucket": {
+          "type": "array",
+          "prefixItems": [
+            {
+              "$ref": "#/$defs/expression"
+            },
+            {
+              "$ref": "#/$defs/expression"
+            },
+            {
+              "$ref": "#/$defs/expression"
+            },
+            {
+              "$ref": "#/$defs/calendarContext"
+            }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 4
+        }
+      },
+      "required": [
+        "$time-bucket"
+      ],
+      "additionalProperties": false
+    },
     "asClause": {
       "description": "The $as clause: variable-name to JSON Schema literal members, applied per tuple after $for/$let binding and before $where. Each name must be bound by the same phrase's $for (including $at names) or $let - a compiler rule (JQ0005); each binding validates per item at runtime (JQ2008). (LLM profile: a member-name constraint is relaxed here; the canonical schema enforces it)",
       "type": "object",

package/schemas/jaren-query.schema.json

@@ -93,7 +93,10 @@
         { "$ref": "#/$defs/geohashPhrase" },
         { "$ref": "#/$defs/ternaryOperatorPhrase" },
         { "$ref": "#/$defs/replacePhrase" },
-        { "$ref": "#/$defs/schemaOperatorPhrase" }
+        { "$ref": "#/$defs/schemaOperatorPhrase" },
+        { "$ref": "#/$defs/seriesSpecPhrase" },
+        { "$ref": "#/$defs/asOfPhrase" },
+        { "$ref": "#/$defs/timeBucketPhrase" }
       ]
     },
     "mapConstructor": {
@@ -308,7 +311,7 @@
           "$index-of", "$range", "$get",
           "$start-of", "$end-of", "$date-format",
           "$distance", "$within", "$bbox-intersects", "$geo-simplify",
-          "$similarity", "$default"
+          "$similarity", "$overlaps", "$default"
         ]
       },
       "additionalProperties": {
@@ -433,6 +436,123 @@
         "maxItems": 2
       }
     },
+    "seriesSpec": {
+      "description": "A $resample or $rolling spec (QUERY-FORMAT.md section 8.16): a VERBATIM literal, never an expression, so the width, the aggregate, the fill policy, the wall clock and the row selectors are read once when the query compiles. Closed: an unknown member is JQ0003. 'every'/'width' is an ISO 8601 duration or a count of milliseconds; 'origin'/'start'/'end' are epoch milliseconds or an RFC 3339 string; 'at'/'value' are singular paths where '$' reads as the ROW. A named 'zone' needs an injected zoneProvider - this suite bundles no time-zone database.",
+      "type": "object",
+      "properties": {
+        "every": { "$ref": "#/$defs/seriesSpan" },
+        "width": { "$ref": "#/$defs/seriesSpan" },
+        "origin": { "$ref": "#/$defs/seriesInstant" },
+        "start": { "$ref": "#/$defs/seriesInstant" },
+        "end": { "$ref": "#/$defs/seriesInstant" },
+        "aggregate": { "enum": ["sum", "mean", "min", "max", "first", "last", "count"] },
+        "fill": { "enum": ["omit", "null", "zero", "locf", "linear"] },
+        "minPeriods": { "type": "integer", "minimum": 1 },
+        "at": { "$ref": "#/$defs/rowSelector" },
+        "value": { "$ref": "#/$defs/rowSelector" },
+        "zone": { "type": "string", "minLength": 1 },
+        "offset": { "type": "number" },
+        "disambiguation": { "enum": ["reject", "earlier", "later"] }
+      },
+      "additionalProperties": false
+    },
+    "seriesSpan": {
+      "description": "A width: an ISO 8601 duration string ('PT1H', 'P1M') or a count of milliseconds. A duration mixing the calendar and clock families ('P1MT1H') is refused by the compiler.",
+      "anyOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "number", "exclusiveMinimum": 0 }
+      ]
+    },
+    "seriesInstant": {
+      "description": "An instant: epoch milliseconds, or an RFC 3339 string. A full-time names no instant and is refused by the compiler.",
+      "anyOf": [
+        { "type": "number" },
+        { "type": "string", "minLength": 1 }
+      ]
+    },
+    "rowSelector": {
+      "description": "Where a member lives in a source row: a singular JSONPath whose '$' is the ROW rather than the document ('$.on', \"$['recorded at']\", '$.meta.at'). Wildcards, descendants and filters are refused (JQ0003) - a selector names one member.",
+      "type": "string",
+      "pattern": "^\\$[.\\[]"
+    },
+    "seriesSpecPhrase": {
+      "description": "$resample / $rolling [series, spec]: an operand expression and a VERBATIM spec literal. $resample returns sorted {at, value, count} buckets one per 'every'; $rolling returns one row per input instant over a window measured in time.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": { "enum": ["$resample", "$rolling"] },
+      "additionalProperties": {
+        "type": "array",
+        "prefixItems": [
+          { "$ref": "#/$defs/expression" },
+          { "$ref": "#/$defs/seriesSpec" }
+        ],
+        "items": false,
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "asOfSpec": {
+      "description": "The $asof spec (QUERY-FORMAT.md section 8.16): a VERBATIM literal. 'by' joins within groups; 'leftAt'/'rightAt' say where each side keeps its instant when the two documents spell it differently. Closed: an unknown member is JQ0003.",
+      "type": "object",
+      "properties": {
+        "direction": { "enum": ["backward", "forward", "nearest"] },
+        "tolerance": { "$ref": "#/$defs/seriesSpan" },
+        "by": { "$ref": "#/$defs/rowSelector" },
+        "leftAt": { "$ref": "#/$defs/rowSelector" },
+        "rightAt": { "$ref": "#/$defs/rowSelector" }
+      },
+      "additionalProperties": false
+    },
+    "asOfPhrase": {
+      "description": "$asof [left, right] or [left, right, spec]: two operand expressions and an optional VERBATIM spec literal. Answers one {left, right, distance} per left row; a left row with no match keeps right: null and stays in the answer.",
+      "type": "object",
+      "properties": {
+        "$asof": {
+          "type": "array",
+          "prefixItems": [
+            { "$ref": "#/$defs/expression" },
+            { "$ref": "#/$defs/expression" },
+            { "$ref": "#/$defs/asOfSpec" }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 3
+        }
+      },
+      "required": ["$asof"],
+      "additionalProperties": false
+    },
+    "calendarContext": {
+      "description": "$time-bucket's optional fourth position: the wall clock its boundaries fall on. UTC is the default and needs nothing; a named 'zone' needs an injected zoneProvider.",
+      "type": "object",
+      "properties": {
+        "zone": { "type": "string", "minLength": 1 },
+        "offset": { "type": "number" },
+        "disambiguation": { "enum": ["reject", "earlier", "later"] }
+      },
+      "additionalProperties": false
+    },
+    "timeBucketPhrase": {
+      "description": "$time-bucket [at, every] / [at, every, origin] / [at, every, origin, context]: the instant labelling the bucket 'at' falls in. The first three positions are operand expressions ('origin' may be null for the ladder's own default); the fourth is a VERBATIM calendar context literal.",
+      "type": "object",
+      "properties": {
+        "$time-bucket": {
+          "type": "array",
+          "prefixItems": [
+            { "$ref": "#/$defs/expression" },
+            { "$ref": "#/$defs/expression" },
+            { "$ref": "#/$defs/expression" },
+            { "$ref": "#/$defs/calendarContext" }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 4
+        }
+      },
+      "required": ["$time-bucket"],
+      "additionalProperties": false
+    },
     "asClause": {
       "description": "The $as clause: variable-name to JSON Schema literal members, applied per tuple after $for/$let binding and before $where. Each name must be bound by the same phrase's $for (including $at names) or $let - a compiler rule (JQ0005); each binding validates per item at runtime (JQ2008).",
       "type": "object",

package/src/query/normalize.js

@@ -433,6 +433,25 @@ const OPERATOR_ALIASES = {
   "$nearest-neighbours": "$orderby on a $similarity key, then $subsequence",
   "$nearest-neighbors": "$orderby on a $similarity key, then $subsequence",
   "$top-k": "$orderby then $subsequence", $embed: null, $normalize: null,
+  // time series: the spellings a writer arrives with from Timescale,
+  // pandas, SQL and kdb+. The bucketing family all points at the two
+  // operators that exist - the scalar label and the aggregating one -
+  // and the fill policies point at `$resample`, because a fill is a
+  // MEMBER of a resample spec rather than an operation of its own
+  $time_bucket: "$time-bucket", "$date-bin": "$time-bucket",
+  $date_bin: "$time-bucket", $bucket: "$time-bucket",
+  "$time-bucket-gapfill": "$resample with a 'fill'",
+  $gapfill: "$resample with a 'fill'", $locf: "$resample with fill 'locf'",
+  $interpolate: "$resample with fill 'linear'",
+  $downsample: "$resample", $upsample: "$resample with a 'fill'",
+  $rollup: "$resample", $groupbytime: "$resample",
+  "$moving-average": "$rolling with aggregate 'mean'",
+  $rollingwindow: "$rolling", "$time-window": "$rolling",
+  "$as-of": "$asof", "$asof-join": "$asof", $aj: "$asof",
+  "$merge-asof": "$asof", "$latest-at": "$asof",
+  $overlap: "$overlaps", "$interval-overlaps": "$overlaps",
+  $during: "$overlaps", $meets: null, $abuts: null,
+  $now: null, "$current-timestamp": null,
 };
 
 // JQ0002 for an unknown $-key, with a "did you mean" suggestion. A
@@ -577,6 +596,11 @@ function argCards(args) {
   return cards;
 }
 
+// The operators that read a calendar boundary, and so may be given a
+// named zone. `$asof` and `$overlaps` are pure instant arithmetic and
+// have no clock to resolve.
+const CLOCK_OPERATORS = new Set(['$time-bucket', '$resample', '$rolling']);
+
 // A registry operator call: arity and shape come uniformly from the
 // table's `params` descriptor (JQ0003), the static cardinality from its
 // `result` - individual operators never re-check structure.
@@ -590,6 +614,11 @@ function normalizeOperatorCall(key, entry, arg, docPath, opPath, scope, ctx) {
   // configurable through the compilation's limits (compileOp hands the
   // node through to the entry's compile)
   if (key === '$range' && ctx.limits !== null) node.limits = ctx.limits;
+  // the series operators resolve their wall clock when the query
+  // compiles, and a named zone needs the tzdb this suite does not bundle
+  // (SERIES D7). The provider is a compilation capability, like a
+  // collation, so it reaches the entry the same way $range's guard does
+  if (ctx.zoneProvider !== null && CLOCK_OPERATORS.has(key)) node.zoneProvider = ctx.zoneProvider;
   return Object.freeze(node);
 }
 
@@ -1258,6 +1287,19 @@ function validateNamedFunctions(value, what) {
   return value;
 }
 
+// Validate the injected time-zone provider (options.zoneProvider): the
+// two-question seam SERIES D7 fixes, because this suite bundles no
+// tzdb and a JSON document cannot carry one. Violations are host
+// programming errors (TypeError), like options.extensions.
+function validateZoneProvider(value) {
+  if (value === null || typeof value !== 'object'
+    || typeof value.toParts !== 'function' || typeof value.toEpoch !== 'function') {
+    throw new TypeError('options.zoneProvider must be an object with'
+      + ' toParts(epoch, zone) and toEpoch(parts, zone, disambiguation)');
+  }
+  return value;
+}
+
 // The known limits (section 8.12). Only limits the engine actually
 // enforces are accepted - an accepted-but-unenforced limit would be a
 // silent false guarantee.
@@ -1423,6 +1465,7 @@ export function normalizeQuery(doc, options = {}) {
   const extensions = options.extensions == null ? null : validateExtensions(options.extensions);
   const functions = options.functions == null ? null : validateNamedFunctions(options.functions, 'functions');
   const collations = options.collations == null ? null : validateNamedFunctions(options.collations, 'collations');
+  const zoneProvider = options.zoneProvider == null ? null : validateZoneProvider(options.zoneProvider);
   const limits = options.limits == null ? null : validateLimits(options.limits);
   const declaredExternals = options.externals == null
     ? null
@@ -1436,7 +1479,7 @@ export function normalizeQuery(doc, options = {}) {
     : { pathFunctions: options.pathFunctions };
   const ctx = {
     nextSlot: 1, externals: new Map(), compileTypeTest, extensions,
-    functions, collations, limits, pathOptions, declaredExternals,
+    functions, collations, zoneProvider, limits, pathOptions, declaredExternals,
     // package-internal: set only by analyzeQuery (Appendix C.1); the
     // compile entry point never passes it
     analysis: options.analysis === true,