@jarenjs/linq 0.46.5 → 0.49.2

package/README.md

@@ -52,6 +52,13 @@ played by the provider seam below.
   spatial measurements are `geoArea`/`geoLength` because `length` on
   this surface is already `$string-length` — the mapping table says so
   in its own row.
+- **Time is spellable.** The whole RFC 3339 date family is on the surface —
+  `e.on.startOf('month')`, `e.on.dateAdd(3, 'day')`, `e.on.week()` — and so are
+  the five time-series operators: `rows.all().resample({ every: 'PT1H', fill:
+  'locf' })`, `rows.all().rolling({ width: 60000 })` and
+  `left.all().asof(right, { by: '$.symbol' })`. A series spec is a literal and
+  is embedded verbatim, so every rule about what it may say stays in the
+  compiler rather than being restated here.
 - **Meaning is spellable too.** `m.embedding.similarity(query)` emits
   §8.15's `$similarity`, and k-nearest is the chain it already looks
   like — `.orderByDescending(..., { empty: 'least' }).thenBy(m => m.id)

package/docs/LINQ-FORMAT.md

@@ -114,7 +114,9 @@ is part of THIS design.
 | `OfType<S>` | `$valid` filter with a JSON Schema literal | native | `(schema)` → `Seq<S>`; needs `compileTypeTest` (`JL0003`) |
 | `Cast<S>` | `$assert` per item | native | `(schema)` → `Seq<S>`; needs `compileTypeTest` (`JL0003`) |
 | `Zip` | — no positional co-iteration in the grammar | unsupported (`JL0006`) | — |
-| expression methods | `eq ne lt le gt ge` → `$eq…$ge`; `and or not`; `add sub mul div idiv mod neg`; `startsWith endsWith contains matches upper lower length concat substring replace` → §8.7; `count sum avg min max` → §8.8 (aggregates as expressions, e.g. over a group); `year month day epoch` → §8.13; `exists isEmpty`; `at all get` | native | on `Expr<…>`, per the typed-surface order |
+| expression methods | `eq ne lt le gt ge` → `$eq…$ge`; `and or not`; `add sub mul div idiv mod neg`; `startsWith endsWith contains matches upper lower length concat substring replace` → §8.7; `count sum avg min max` → §8.8 (aggregates as expressions, e.g. over a group); `exists isEmpty`; `at all get` | native | on `Expr<…>`, per the typed-surface order |
+| date family (§8.13) | the whole family, one method per operator. Components `year month day hours minutes seconds offset week weekYear quarter weekday`; instants `epoch datetime`; predicates `isDate isTime isDatetime isDuration`; arithmetic `startOf(unit) endOf(unit) dateAdd(duration \| amount, unit?) dateSub(…) dateDiff(to, unit) dateFormat(pattern)`. `dateAdd`/`dateSub`/`dateFormat` carry the prefix because `add`, `sub` and `format` are taken or ambiguous on this surface — the same reason §8.14 spells `geoArea`. There is no `now()`: §8.13 has no clock, and a fluent surface does not get to add one | native | on `DateTimeExpr` (the `DateTime` brand) and on `UnknownExpr` |
+| series family (§8.16) | `overlaps(other)` → `$overlaps`; `timeBucket(every, origin?, context?)` → `$time-bucket`; `resample(spec)`, `rolling(spec)` and `asof(right, spec?)` → the three sequence operators. A **spec is a literal** and is embedded verbatim — it is read once when the query compiles, so a spec built from the row is `JL0005`, and every rule about what it may *say* stays in the compiler (`JQ0003`). Note that a member literally named `at` is read with `get('at')`: `at(index)` is path navigation on this surface | native | on `ArrayExpr`/fanned paths for the three sequence operators, on `Expr<…>` for the two scalar ones |
 | spatial family (§8.14) | `bbox geoArea geoLength centroid` → `$bbox $area $length $centroid`; `distance within bboxIntersects` → `$distance $within $bbox-intersects`; `geohash(precision?)` → `$geohash` (optional arity, like `substring`); `geoParse geoText geohashBounds geohashNeighbours` → the conversion family; `geoSimplify(tolerance)` → `$geo-simplify`. A plain JSON polygon embeds as a literal (`p.at.within(poly)`); `.params({ region })` makes it an external instead | native | on `Expr<…>`, per the typed-surface order |
 | vector family (§8.15) | `similarity(other)` → `$similarity`. The other operand is an array of numbers: a captured one embeds as a literal, `.params({ query })` binds it at call time. There is no `knn` method — k-nearest is `orderByDescending(...).take(k)`, which is the composition the emitted document already is | native | on `Expr<…>`, per the typed-surface order |
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.49.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -47,7 +47,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.5",
-    "@jarenjs/json": "^0.46.5"
+    "@jarenjs/core": "^0.49.2",
+    "@jarenjs/json": "^0.49.2"
   }
 }

package/src/expression.js

@@ -171,6 +171,43 @@ const unary = (op) => function (/** @type {any} */ record) {
   return makeExpr({ [op]: record.doc }, record.epoch, false);
 };
 
+/**
+ * `$date-add` / `$date-sub`: `[date, duration]` or `[date, amount, unit]`.
+ * @param {any} record
+ * @param {any} amount - an ISO 8601 duration, or a number of units
+ * @param {any} [unit] - the calendar unit, when `amount` is a number
+ * @returns {any[]}
+ */
+function shiftArgs(record, amount, unit) {
+  return unit === undefined
+    ? [record.doc, toExpression(amount)]
+    : [record.doc, toExpression(amount), toExpression(unit)];
+}
+
+/**
+ * A §8.16 spec: captured data, embedded verbatim.
+ *
+ * These are the one place this surface hands the compiler something it
+ * must NOT evaluate — a width, an aggregate, a fill policy and a row
+ * selector are read once when the query compiles, which is what makes
+ * them checkable at all. `toExpression` would turn `{ every: 'PT1H' }`
+ * into a map constructor and `{ at: '$.on' }` into a path; the spec is
+ * therefore embedded as it was written, and every rule about what it may
+ * contain stays where it already is, in the query compiler (`JQ0003`).
+ *
+ * @param {any} spec
+ * @param {string} method - for the message
+ * @returns {any} the spec, verbatim
+ */
+function literalSpec(spec, method) {
+  if (!isPlainJson(spec) || spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+    throw new LinqBuildError('JL0005',
+      `${method}() takes a plain literal spec object; it is read once when the query`
+      + ' compiles, so it cannot be an expression or carry a captured value');
+  }
+  return spec;
+}
+
 /**
  * The operator methods, name → builder(record, ...args). One table so
  * the mapping in LINQ-FORMAT.md §4 has exactly one code counterpart.
@@ -212,10 +249,65 @@ const METHODS = {
   // `(u, g) => ({ n: g.count() })`)
   count: unary('$count'), sum: unary('$sum'), avg: unary('$avg'),
   min: unary('$min'), max: unary('$max'),
-  // §8.13 dates (the scalar component family; the full date surface
-  // arrives with the relational order)
+  // §8.13 dates — the whole family, not a corner of it. A date in this
+  // suite is an RFC 3339 STRING, so every one of these is an ordinary
+  // string operator with a calendar's worth of rules behind it, and
+  // every one lowers to the operator of the same name: there is no
+  // LINQ-only date semantics to learn and nothing here a hand-written
+  // document could not have said.
+  //
+  // `dateFormat` rather than `format`, and `dateAdd`/`dateSub` rather
+  // than `add`/`sub`, because `add` is already `$add` on this surface —
+  // the same reason §8.14 spells `geoArea`. Where no method name is
+  // taken, the operator's own name is used unprefixed (`week`,
+  // `quarter`, `startOf`).
   year: unary('$year'), month: unary('$month'), day: unary('$day'),
-  epoch: unary('$epoch'),
+  hours: unary('$hours'), minutes: unary('$minutes'), seconds: unary('$seconds'),
+  offset: unary('$offset'), epoch: unary('$epoch'), datetime: unary('$datetime'),
+  week: unary('$week'), weekYear: unary('$week-year'),
+  quarter: unary('$quarter'), weekday: unary('$weekday'),
+  isDate: unary('$is-date'), isTime: unary('$is-time'),
+  isDatetime: unary('$is-datetime'), isDuration: unary('$is-duration'),
+  startOf: binary('$start-of'), endOf: binary('$end-of'),
+  dateFormat: binary('$date-format'),
+  dateAdd(record, amount, unit) {
+    return makeExpr({ '$date-add': shiftArgs(record, amount, unit) }, record.epoch, false);
+  },
+  dateSub(record, amount, unit) {
+    return makeExpr({ '$date-sub': shiftArgs(record, amount, unit) }, record.epoch, false);
+  },
+  dateDiff(record, to, unit) {
+    return makeExpr(
+      { '$date-diff': [record.doc, toExpression(to), toExpression(unit)] },
+      record.epoch, false);
+  },
+  // §8.16 time series. The three sequence-valued operators take a
+  // VERBATIM spec literal, so the argument is embedded with `$const`'s
+  // discipline - it is captured data, never an expression - and the
+  // compiler owns every rule about what it may say.
+  overlaps: binary('$overlaps'),
+  timeBucket(record, every, origin, context) {
+    const args = [record.doc, toExpression(every)];
+    if (origin !== undefined || context !== undefined)
+      args.push(origin === undefined ? null : toExpression(origin));
+    if (context !== undefined)
+      args.push(literalSpec(context, 'timeBucket'));
+    return makeExpr({ '$time-bucket': args }, record.epoch, false);
+  },
+  resample(record, spec) {
+    return makeExpr({ $resample: [record.doc, literalSpec(spec, 'resample')] },
+      record.epoch, false);
+  },
+  rolling(record, spec) {
+    return makeExpr({ $rolling: [record.doc, literalSpec(spec, 'rolling')] },
+      record.epoch, false);
+  },
+  asof(record, right, spec) {
+    const args = [record.doc, toExpression(right)];
+    if (spec !== undefined)
+      args.push(literalSpec(spec, 'asof'));
+    return makeExpr({ $asof: args }, record.epoch, false);
+  },
   // §8.14 spatial. `geoArea`/`geoLength` rather than `area`/`length`:
   // `length` is already `$string-length` on this surface and renaming a
   // shipped method for symmetry is a breaking change for a cosmetic

package/types/index.d.ts

@@ -14,9 +14,9 @@
 
 /**
  * The nominal date-time brand: annotate a model property as `DateTime`
- * and the date operators (`year()`, `month()`, `day()`, `epoch()`)
- * become available on its expression without making EVERY string a
- * date. Purely a type-level marker — the runtime value is a plain
+ * and the whole §8.13 date family (`year()`, `startOf()`, `dateAdd()`,
+ * `timeBucket()`, …) becomes available on its expression without making
+ * EVERY string a date. Purely a type-level marker — the runtime value is a plain
  * RFC 3339 string; there is no constructor and no runtime cost.
  */
 export type DateTime = string & { readonly __jarenTag: 'date-time' };
@@ -59,6 +59,10 @@ export interface NumberExpr extends ExprBase<number>, EqExpr<number> {
   idiv(value: number | NumberExpr): NumberExpr;
   mod(value: number | NumberExpr): NumberExpr;
   neg(): NumberExpr;
+  /** An epoch is a number, so the two instant operators live here too. */
+  datetime(): DateTimeExpr;
+  timeBucket(every: string | number, origin?: string | number | null,
+    context?: CalendarContext): NumberExpr;
 }
 
 export interface StringExpr extends ExprBase<string>, EqExpr<string> {
@@ -79,25 +83,165 @@ export interface StringExpr extends ExprBase<string>, EqExpr<string> {
   replace(pattern: string, replacement: string): StringExpr;
 }
 
-/** A `DateTime`-branded string: the string surface plus the date
- * component operators. */
-export interface DateTimeExpr extends ExprBase<DateTime> {
+/** A calendar unit, as QUERY-FORMAT §8.13 fixes it. The unit is DATA
+ * rather than vocabulary, so an unknown one is a runtime `JQ2001`; this
+ * type is what keeps the common spelling mistake a compile error. */
+export type DateUnit =
+  | 'year' | 'quarter' | 'month' | 'week' | 'day'
+  | 'hour' | 'minute' | 'second' | 'millisecond';
+
+/** The date family (`$is-date` … `$date-format`), available on any
+ * expression whose value carries a date. Every method lowers to the §8.13
+ * operator of the same name; there is no LINQ-only date semantics. */
+export interface DateMethods {
+  /** Lexical date components; a value with no date half is `JQ2001`. */
+  year(): NumberExpr;
+  month(): NumberExpr;
+  day(): NumberExpr;
+  /** Lexical time components; `seconds` carries its fraction. */
+  hours(): NumberExpr;
+  minutes(): NumberExpr;
+  seconds(): NumberExpr;
+  /** Minutes east of UTC; a bare `full-date` yields the empty sequence. */
+  offset(): NumberExpr;
+  /** ISO 8601 week number, and its week-numbering year. */
+  week(): NumberExpr;
+  weekYear(): NumberExpr;
+  /** Calendar quarter 1-4; ISO weekday 1 (Monday) to 7 (Sunday). */
+  quarter(): NumberExpr;
+  weekday(): NumberExpr;
+  /** Epoch milliseconds (`$epoch`) — the one shift to UTC. */
+  epoch(): NumberExpr;
+  /** The inverse: epoch milliseconds → a canonical UTC `date-time`. */
+  datetime(): DateTimeExpr;
+  /** The RFC 3339 lexical-form predicates; these never raise. */
+  isDate(): BoolExpr;
+  isTime(): BoolExpr;
+  isDatetime(): BoolExpr;
+  isDuration(): BoolExpr;
+  /** Truncate to a unit, keeping the lexical form (`$start-of`/`$end-of`). */
+  startOf(unit: DateUnit): DateTimeExpr;
+  endOf(unit: DateUnit): DateTimeExpr;
+  /** Shift by an ISO 8601 duration, or by an amount and a unit. */
+  dateAdd(duration: string): DateTimeExpr;
+  dateAdd(amount: number | NumberExpr, unit: DateUnit): DateTimeExpr;
+  dateSub(duration: string): DateTimeExpr;
+  dateSub(amount: number | NumberExpr, unit: DateUnit): DateTimeExpr;
+  /** Whole units from this value to another; negative when it precedes. */
+  dateDiff(to: string | DateTimeExpr, unit: DateUnit): NumberExpr;
+  /** Render through a Unicode LDML pattern (`yyyy-MM-dd`). */
+  dateFormat(pattern: string): StringExpr;
+  /** The instant labelling the bucket this one falls in (`$time-bucket`). */
+  timeBucket(every: string | number, origin?: string | number | null,
+    context?: CalendarContext): NumberExpr;
+}
+
+/** A `DateTime`-branded string: the string surface plus the whole §8.13
+ * date family. */
+export interface DateTimeExpr extends ExprBase<DateTime>, DateMethods {
   eq(value: string | DateTimeExpr | null): BoolExpr;
   ne(value: string | DateTimeExpr | null): BoolExpr;
   lt(value: string | DateTimeExpr): BoolExpr;
   le(value: string | DateTimeExpr): BoolExpr;
   gt(value: string | DateTimeExpr): BoolExpr;
   ge(value: string | DateTimeExpr): BoolExpr;
-  year(): NumberExpr;
-  month(): NumberExpr;
-  day(): NumberExpr;
-  /** Epoch milliseconds (`$epoch`). */
-  epoch(): NumberExpr;
 }
 
-export interface ArrayExpr<E> extends ExprBase<E[]> {
+/** The wall clock a calendar boundary falls on (QUERY-FORMAT §8.16).
+ * UTC is the default; a named `zone` needs an injected `zoneProvider`. */
+export interface CalendarContext {
+  zone?: string;
+  offset?: number;
+  disambiguation?: 'reject' | 'earlier' | 'later';
+}
+
+/** The aggregates `$resample` and `$rolling` share. */
+export type SeriesAggregate =
+  'sum' | 'mean' | 'min' | 'max' | 'first' | 'last' | 'count';
+
+/** What an EMPTY bucket says, and nothing else. */
+export type SeriesFill = 'omit' | 'null' | 'zero' | 'locf' | 'linear';
+
+/** A width: an ISO 8601 duration, or a count of milliseconds. */
+export type SeriesSpan = string | number;
+
+/** An instant: epoch milliseconds, or an RFC 3339 string. */
+export type SeriesInstant = string | number;
+
+/** A row selector: a singular path whose `$` is the ROW rather than the
+ * document (`'$.on'`, `"$['recorded at']"`). */
+export type RowSelector = string;
+
+/** The `$resample` spec — a literal, read once when the query compiles. */
+export interface ResampleSpec extends CalendarContext {
+  every: SeriesSpan;
+  origin?: SeriesInstant;
+  start?: SeriesInstant;
+  end?: SeriesInstant;
+  aggregate?: SeriesAggregate;
+  fill?: SeriesFill;
+  at?: RowSelector;
+  value?: RowSelector;
+}
+
+/** The `$rolling` spec — a window measured in time, not in rows. */
+export interface RollingSpec extends CalendarContext {
+  width: SeriesSpan;
+  aggregate?: SeriesAggregate;
+  minPeriods?: number;
+  at?: RowSelector;
+  value?: RowSelector;
+}
+
+/** The `$asof` spec — every member optional: backward, unkeyed, unbounded. */
+export interface AsOfSpec {
+  direction?: 'backward' | 'forward' | 'nearest';
+  tolerance?: SeriesSpan;
+  by?: RowSelector;
+  leftAt?: RowSelector;
+  rightAt?: RowSelector;
+}
+
+/** One canonical sample the series operators answer with. */
+export interface SeriesBucket {
+  at: number;
+  value: number | null;
+  count: number;
+}
+
+/** One row of an as-of join; `right` is `null` when nothing matched, and
+ * the row stays in the answer. */
+export interface AsOfMatch {
+  left: unknown;
+  right: unknown;
+  distance: number | null;
+}
+
+/** A half-open interval: `[start, end)`, in epoch milliseconds. */
+export interface Interval {
+  start: SeriesInstant;
+  end: SeriesInstant;
+}
+
+/** The §8.16 operators that take a whole series and answer another one.
+ * Available wherever a MANY-cardinality expression is (an array member,
+ * or a fanned path). */
+export interface SeriesMethods {
+  /** Sorted `{at, value, count}` buckets, one per `every` (`$resample`). */
+  resample(spec: ResampleSpec): Expr<SeriesBucket[]> & AggregatableExpr;
+  /** One row per input instant, over a window measured in time. */
+  rolling(spec: RollingSpec): Expr<SeriesBucket[]> & AggregatableExpr;
+  /** The right row that was current when each left row happened. */
+  asof(right: ExprBase<unknown> | readonly unknown[], spec?: AsOfSpec):
+    Expr<AsOfMatch[]> & AggregatableExpr;
+}
+
+export interface ArrayExpr<E> extends ExprBase<E[]>, SeriesMethods {
   eq(value: readonly E[] | ArrayExpr<E> | null): BoolExpr;
   ne(value: readonly E[] | ArrayExpr<E> | null): BoolExpr;
+  /** Do two half-open `{start, end}` intervals share an instant?
+   * Touching spans do not. */
+  overlaps(other: Interval | ExprBase<unknown>): BoolExpr;
   /** Fan the elements out (`[*]`) — a MANY-cardinality expression the
    * aggregates apply to (`u.tags.all().count()`). */
   all(): Expr<E> & AggregatableExpr;
@@ -126,7 +270,8 @@ export type ObjectExpr<T> = ExprBase<T> & EqExpr<T> & {
 /** The honest top: everything is available, nothing is precise. Used
  * where inference ends (dynamic `get`, post-operator members, unknown
  * elements) — wide, never wrong. */
-export interface UnknownExpr extends ExprBase<unknown>, AggregatableExpr {
+export interface UnknownExpr
+  extends ExprBase<unknown>, AggregatableExpr, DateMethods, SeriesMethods {
   eq(value: unknown): BoolExpr;
   ne(value: unknown): BoolExpr;
   lt(value: unknown): BoolExpr;
@@ -153,12 +298,10 @@ export interface UnknownExpr extends ExprBase<unknown>, AggregatableExpr {
   concat(value: unknown): UnknownExpr;
   substring(start: number, length?: number): UnknownExpr;
   replace(pattern: string, replacement: string): UnknownExpr;
-  year(): NumberExpr;
-  month(): NumberExpr;
-  day(): NumberExpr;
-  epoch(): NumberExpr;
   all(): UnknownExpr;
   at(index: number): UnknownExpr;
+  /** Do two half-open `{start, end}` intervals share an instant? */
+  overlaps(other: Interval | ExprBase<unknown>): BoolExpr;
 }
 
 /** Value type → expression type. Order matters: the DateTime brand is