quario 0.4.0 → 0.6.0

package/lib/precision.js

@@ -0,0 +1,75 @@
+/**
+ * How many fraction digits a `format` kind presents when the declaration
+ * names no count of its own. One table, read once — by `./style.js`, where a
+ * `format` declaration resolves — so an author's own `digits` beats a default
+ * here exactly as it beats any other (docs/adr/0056).
+ *
+ * The counts are fixed rather than maxima — `number` and `percent` are 2 —
+ * and they are stated here rather than read back out of Intl's own defaults,
+ * which would tie a workbook's bytes to the host's ICU version (docs/adr/0025)
+ * and would settle `percent` at whatever ICU happens to prefer.
+ *
+ * `currency` is the one hybrid: its minor units come from Intl, because the
+ * alternative is vendoring ISO 4217. Nothing else asks ICU anything.
+ *
+ * The public `fractionDigits` helper is **not** here, and the split is the
+ * point. A resolved `format` crosses the stream carrying its own `digits`, so
+ * every target reads the count off the declaration it already has and asks
+ * nothing (docs/adr/0054's authority moved from this table to the stream).
+ * What remains public is a reader of that resolved declaration, and it lives
+ * beside the resolution in `./style.js`.
+ */
+
+/** Fixed counts for the kinds that carry one of their own. @type {Record<string, number>} */
+let COUNTS = { number: 2, percent: 2 };
+
+// Minor units are a property of the currency, not of the locale — Intl gives
+// JPY 0 under every one — so the code alone is the whole key. Bounded by the
+// distinct codes a process ever sees, and memoising a fact that cannot change
+// within an ICU version: an uncached probe costs ~10 µs, so ~100 ms for every
+// ten thousand currency cells a target presents, against ~19 ns memoised.
+/** @type {Map<string, number | undefined>} */
+let minorUnits = new Map();
+
+// Every unreadable code lands in the catch and memoises as nothing — a
+// missing one included, since Intl demands a currency under this style. So
+// there is no separate guard: one answer, reached one way.
+/** @type {(currency: unknown) => number | undefined} */
+let unitsOf = (currency) => {
+  // Gate before the map, not inside the try: a non-string would otherwise be
+  // retained as a key for the life of the process for no answer.
+  if (typeof currency !== "string") return undefined;
+  if (minorUnits.has(currency)) return minorUnits.get(currency);
+  let units;
+  try {
+    // Intl takes any well-formed three-letter code and throws on the rest,
+    // which is the same line `format()` already falls back on.
+    units = new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: /** @type {string} */ (currency),
+    }).resolvedOptions().maximumFractionDigits;
+  } catch {
+    units = undefined;
+  }
+  minorUnits.set(currency, units);
+  return units;
+};
+
+/**
+ * The count a kind presents when the declaration names none.
+ *
+ * @param {string} kind A `format` kind.
+ * @param {unknown} [currency] The code the cell wears, under `"currency"`.
+ * @returns {number | undefined} The digits, or nothing when the kind carries
+ *   no count — `date`, an unknown kind, and a `currency` whose code Intl will
+ *   not read. A kind that resolves to no count presents no digits anywhere:
+ *   `format()` falls back to `display()` and the worksheet writes no number
+ *   format at all.
+ */
+export function defaultDigits(kind, currency) {
+  if (kind === "currency") return unitsOf(currency);
+  // Own-key lookup, as everywhere a name from a document indexes a table: a
+  // kind named after an Object.prototype member is unknown, not an inherited
+  // function (`style.js`).
+  return Object.hasOwn(COUNTS, kind) ? COUNTS[kind] : undefined;
+}

package/lib/reducers.js

@@ -0,0 +1,165 @@
+/**
+ * Every fact the engine holds about a reducer, in one table.
+ *
+ * A reducer is three things at once: a fold over a whole array — the function
+ * form `sum(@.lines, l => l.total)` and a declared aggregate alike — a step
+ * folded across rows in render order for a declared running value, and a
+ * spelling rule, since `count` is the one declared form that takes no
+ * expression. Those three used to live in two hand-enumerated tables, a
+ * derived name set, and a reducer named in the validator, so adding a reducer
+ * was three edits and forgetting the runner passed validation and threw a raw
+ * TypeError at render. One entry per reducer; every role derives from it.
+ *
+ * `prev` is the entry with no fold. There is no whole-array "previous", so it
+ * is a running value only — and that missing half is exactly what keeps it out
+ * of an `aggregates` block, where `RUN = AGG ∪ {prev}` used to say so by hand.
+ *
+ * Coercion is quiet: only a finite number contributes, everything else folds
+ * to 0, as the spec promises.
+ */
+
+/** @typedef {(rows: any[] | null | undefined, of?: ((row: any) => any) | null) => any} Reducer */
+/** @typedef {{ fold: Reducer | null, run: () => (value: any) => any, expr: boolean }} Entry */
+/** @typedef {"aggregate" | "run"} Role */
+
+/** @type {(value: any) => number} */
+let num = (value) => {
+  let n = +value;
+  return Number.isFinite(n) ? n : 0;
+};
+// The per-row read every reducer but `count` makes of its lambda: a projection
+// rather than a predicate. `count` is the one that filters instead, which is
+// why `countDistinct` reads its lambda this way despite the shared prefix.
+/** @type {(rows: any[] | null | undefined, of?: ((row: any) => any) | null) => any[]} */
+let project = (rows, of) => (rows || []).map((row) => (of ? of(row) : row));
+// `min`/`max` share one shape: project through the lambda, then pick a winner.
+/** @type {(pick: (a: any, b: any) => any) => Reducer} */
+let extreme = (pick) => (rows, of) => {
+  let values = project(rows, of);
+  return values.length ? values.reduce(pick) : null;
+};
+/** @type {Reducer} */
+let sum = (rows, of) => (rows || []).reduce((total, row) => total + num(of ? of(row) : row), 0);
+
+/**
+ * The table. Each entry is one reducer entire: how it folds an array, how it
+ * steps a row, and whether its declared form carries `:=<expression>`.
+ *
+ * The running halves fold in render order. `min`/`max` have no zero, so they
+ * seed to the first row's value — the one deliberate `undefined` here, since
+ * xprsn reads absent values as null.
+ * @type {Record<string, Entry>}
+ */
+let REGISTRY = {
+  sum: {
+    fold: sum,
+    run: () => {
+      let total = 0;
+      return (value) => (total += num(value));
+    },
+    expr: true,
+  },
+  count: {
+    fold: (rows, of) => (of ? (rows || []).filter(of) : rows || []).length,
+    run: () => {
+      let seen = 0;
+      return () => ++seen;
+    },
+    expr: false,
+  },
+  countDistinct: {
+    // Distinctness is a `Set`'s — SameValueZero, which is also what
+    // `Map.groupBy` gives a group's `by` key, so this counts exactly what that
+    // key would partition into. Objects compare by reference there and here
+    // alike.
+    fold: (rows, of) => new Set(project(rows, of)).size,
+    run: () => {
+      let seen = new Set();
+      return (value) => seen.add(value).size;
+    },
+    expr: true,
+  },
+  avg: {
+    fold: (rows, of) => (rows && rows.length ? sum(rows, of) / rows.length : null),
+    run: () => {
+      let total = 0,
+        seen = 0;
+      return (value) => (total += num(value)) / ++seen;
+    },
+    expr: true,
+  },
+  min: {
+    fold: extreme((a, b) => (a < b ? a : b)),
+    run: () => {
+      let lowest = /** @type {any} */ (undefined);
+      return (value) => (lowest = lowest === undefined || value < lowest ? value : lowest);
+    },
+    expr: true,
+  },
+  max: {
+    fold: extreme((a, b) => (a > b ? a : b)),
+    run: () => {
+      let highest = /** @type {any} */ (undefined);
+      return (value) => (highest = highest === undefined || value > highest ? value : highest);
+    },
+    expr: true,
+  },
+  prev: {
+    fold: null,
+    run: () => {
+      let previous = /** @type {any} */ (null);
+      return (value) => {
+        let out = previous;
+        previous = value;
+        return out;
+      };
+    },
+    expr: true,
+  },
+};
+
+/**
+ * The reducer a declaration names, in the role it is declared under, or
+ * `undefined` if that role does not have it: an entry with no fold is a
+ * running value only, which is what refuses `prev` in an `aggregates` block.
+ *
+ * The name comes from splitting an author's spec string, so the lookup asks
+ * for an own property — `"constructor:=@.v"` must be an unknown reducer, not
+ * a function off `Object.prototype`.
+ * @type {(role: Role, fn: string) => Entry | undefined}
+ */
+export let reducerFor = (role, fn) => {
+  if (!Object.hasOwn(REGISTRY, fn)) return undefined;
+  let entry = REGISTRY[fn];
+  return role === "run" || entry.fold ? entry : undefined;
+};
+
+/**
+ * Every reducer name a role accepts, in table order. The vocabulary as a whole,
+ * where `reducerFor` answers about one name — a sweep over the registry needs
+ * it, so nothing re-enumerates the reducers to iterate them.
+ * @type {(role: Role) => string[]}
+ */
+export let namesFor = (role) =>
+  Object.keys(REGISTRY).filter((fn) => reducerFor(role, fn) !== undefined);
+
+/**
+ * The running step a declared run value folds with. Only ever asked for a name
+ * `reducerFor("run", …)` has already accepted, so every entry answers.
+ * @type {(fn: string) => (value: any) => any}
+ */
+export let runnerFor = (fn) => REGISTRY[fn].run();
+
+/**
+ * The reducers as a plain name→function record: what an expression's function
+ * scope spreads in, and what a declared aggregate evaluates through. It is the
+ * aggregate role's own entries, so it asks for them rather than restating the
+ * has-a-fold rule `reducerFor` already owns.
+ * @type {Record<string, Reducer>}
+ */
+export let REDUCERS = Object.fromEntries(
+  // The cast is the derivation's own guarantee: the aggregate role is exactly
+  // the entries carrying a fold, which is why this asks for that role rather
+  // than testing for the fold a second time.
+  namesFor("aggregate").map((fn) => [fn, /** @type {Reducer} */ (REGISTRY[fn].fold)]),
+);

package/lib/scope.js

@@ -1,8 +1,10 @@
 /**
- * The scope model at render time: the anchors a band binds, the reducers that
- * fold a scope's rows, and the runners that fold them in render order. One
- * home for every running value, so a new fold has one place to be declared.
+ * The scope model at render time: the anchors a band binds, and the runner set
+ * a band renders under. What a reducer *is* — its fold, its step, its spelling
+ * — lives in `reducers.js`; this module only asks it for the step and folds
+ * the result in render order.
  */
+import { REDUCERS, runnerFor } from "./reducers.js";
 /** @typedef {Record<string, any>} Scope */
 /** @typedef {(scope: Scope) => any} Eval */
 /** @typedef {{ fn: string, per: Eval | null }} Fold */
@@ -15,42 +17,6 @@
  *   bind: (scope: Scope, row: any) => Scope }} RunnerSet
  */
 
-// Built-in reducers. Each takes an array and an optional xprsn lambda, so an
-// author can aggregate a row's own sub-array inline (`sum(@.lines, l => l.total)`);
-// the same reducers back the declared group aggregates. Coercion is quiet: only
-// a finite number contributes, everything else folds to 0, as the spec promises.
-/** @type {(value: any) => number} */
-let num = (value) => {
-  let n = +value;
-  return Number.isFinite(n) ? n : 0;
-};
-/** @typedef {(rows: any[] | null | undefined, of?: ((row: any) => any) | null) => any} Reducer */
-// The per-row read every reducer but `count` makes of its lambda: a projection
-// rather than a predicate. `count` is the one that filters instead, which is
-// why `countDistinct` reads its lambda this way despite the shared prefix.
-/** @type {(rows: any[] | null | undefined, of?: ((row: any) => any) | null) => any[]} */
-let project = (rows, of) => (rows || []).map((row) => (of ? of(row) : row));
-// `min`/`max` share one shape: project through the lambda, then pick a winner.
-/** @type {(pick: (a: any, b: any) => any) => Reducer} */
-let extreme = (pick) => (rows, of) => {
-  let values = project(rows, of);
-  return values.length ? values.reduce(pick) : null;
-};
-/** @type {Record<string, Reducer>} */
-export let REDUCERS = {
-  sum: (rows, of) => (rows || []).reduce((total, row) => total + num(of ? of(row) : row), 0),
-  count: (rows, of) => (of ? (rows || []).filter(of) : rows || []).length,
-  // Distinctness is a `Set`'s — SameValueZero, which is also what `Map.groupBy`
-  // gives a group's `by` key, so this counts exactly what that key would
-  // partition into. Objects compare by reference there and here alike.
-  countDistinct: (rows, of) => new Set(project(rows, of)).size,
-  avg: (rows, of) => (rows && rows.length ? REDUCERS.sum(rows, of) / rows.length : null),
-  min: extreme((a, b) => (a < b ? a : b)),
-  max: extreme((a, b) => (a > b ? a : b)),
-};
-export let AGG = new Set(Object.keys(REDUCERS));
-export let RUN = new Set([...AGG, "prev"]);
-
 // Bind a row as `@` on a child of `scope`, ready for an xprsn per-row read.
 /** @type {(scope: Scope, row: any) => Scope} */
 export let withRow = (scope, row) => {
@@ -68,57 +34,12 @@ export let withPage = (scope, page) => {
   return child;
 };
 
-// Evaluate one declared aggregate over `rows` by delegating to the same reducers
+// Evaluate one declared aggregate over `rows` by delegating to the same folds
 // authors call inline: the per-row xprsn expression becomes the lambda.
 /** @type {(fold: Fold, rows: any[], scope: Scope) => any} */
 export let aggregateValue = ({ fn, per }, rows, scope) =>
   REDUCERS[fn](rows, per ? (row) => per(withRow(scope, row)) : null);
 
-// Folded across rows in render order, one factory per name. `min`/`max` have
-// no zero, so they seed to the first row's value — the one deliberate
-// `undefined` here, since xprsn reads absent values as null.
-//
-// Every name in `REDUCERS` needs a factory here. `RUN` derives from `AGG`
-// rather than enumerating a second list, so a reducer added there without a
-// runner added here passes validation and then throws at render. The invariant
-// is a test rather than a comment alone — semantics.test.js, "every reducer
-// the run block accepts has a runner behind it".
-/** @type {Record<string, () => (value: any) => any>} */
-let RUNNERS = {
-  sum: () => {
-    let total = 0;
-    return (value) => (total += num(value));
-  },
-  count: () => {
-    let seen = 0;
-    return () => ++seen;
-  },
-  countDistinct: () => {
-    let seen = new Set();
-    return (value) => seen.add(value).size;
-  },
-  avg: () => {
-    let total = 0,
-      seen = 0;
-    return (value) => (total += num(value)) / ++seen;
-  },
-  min: () => {
-    let lowest = /** @type {any} */ (undefined);
-    return (value) => (lowest = lowest === undefined || value < lowest ? value : lowest);
-  },
-  max: () => {
-    let highest = /** @type {any} */ (undefined);
-    return (value) => (highest = highest === undefined || value > highest ? value : highest);
-  },
-  prev: () => {
-    let previous = /** @type {any} */ (null);
-    return (value) => {
-      let out = previous;
-      previous = value;
-      return out;
-    };
-  },
-};
 // The runner set as a value, and the two things a band does with it. `extend`
 // is the whole of persist-vs-reset: a group's own runners are fresh per
 // instance, the outer ones fold on unchanged.
@@ -131,7 +52,7 @@ let runnerSet = (runners) => {
       // block is absent renders under this very value rather than a copy.
       if (!folds.length) return value;
       let started = folds.map(([name, { fn, per }]) => {
-        let step = RUNNERS[fn]();
+        let step = runnerFor(fn);
         return /** @type {[string, Eval]} */ ([name, (scope) => step(per ? per(scope) : 1)]);
       });
       return runnerSet([...runners, ...started]);

package/lib/stream.js

@@ -12,6 +12,7 @@
 // the scalar `display()` rule — re-exported together so event consumers
 // derive display text from a cell's tokens without hand-rolling the join.
 export { display, text } from "sjabloon";
+import { kindOf } from "./style.js";
 
 /** @type {(value: any) => boolean} */
 export let finiteNum = (value) => typeof value === "number" && Number.isFinite(value);
@@ -24,9 +25,14 @@ let asTyped = (value) => {
   if (finiteDate(value)) return value;
   return undefined;
 };
-// The seam's one coercion, kept behind the declared kind (ADR 0041).
-/** @type {(value: any, kind: unknown) => Date | undefined} */
-let asDeclared = (value, kind) => (kind === "date" ? reviveDate(value) : undefined);
+// The seam's one coercion, kept behind the declared kind (ADR 0041). It asks
+// `kindOf` rather than reading `decl.kind`, because the stream carries the
+// resolved object while a host may still hold the shorthand and both must
+// answer alike -- and because reading one field is all this needs, where
+// resolving the whole declaration would allocate per cell for nothing
+// (docs/adr/0056).
+/** @type {(value: any, decl: unknown) => Date | undefined} */
+let asDeclared = (value, decl) => (kindOf(decl) === "date" ? reviveDate(value) : undefined);
 
 // The two RFC 3339 forms a JSON document conventionally carries a date in:
 // a calendar date, and a timestamp that names its offset. A zoneless
@@ -38,8 +44,6 @@ let asDeclared = (value, kind) => (kind === "date" ? reviveDate(value) : undefin
 let RFC3339 =
   /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2})))?$/;
 
-/** @type {(year: string, month: string) => number} */
-let monthLength = (year, month) => new Date(Date.UTC(+year, +month, 0)).getUTCDate();
 // An absent group is the timestamp half of an optional match, not a breach.
 /** @type {(bound: [string | undefined, number, number]) => boolean} */
 let within = ([n, lo, hi]) => n === undefined || (+n >= lo && +n <= hi);
@@ -69,7 +73,7 @@ export let reviveDate = (value) => {
   /** @type {[string | undefined, number, number][]} */
   let bounds = [
     [month, 1, 12],
-    [day, 1, monthLength(year, month)],
+    [day, 1, new Date(Date.UTC(+year, +month, 0)).getUTCDate()],
     [hour, 0, 23],
     [minute, 0, 59],
     [second, 0, 59],
@@ -86,23 +90,24 @@ export let reviveDate = (value) => {
  * including a lone null, matching the display-text treatment everywhere
  * else — reports `undefined` and joins to text.
  *
- * Passing the cell's declared `format` kind opts into the one coercion the
- * seam performs: under `"date"`, a string in either accepted RFC 3339 form
- * revives to the `Date` it names. The gate is the declaration, and the kind
- * is `date` alone, because a date is the one type a JSON document cannot
- * carry — a number arrives as a number, so no other kind has anything to
- * revive (ADR 0041). Callers that read no style omit the argument and see
+ * Passing the cell's resolved `format` declaration opts into the one coercion
+ * the seam performs: under the `date` kind, a string in either accepted RFC
+ * 3339 form revives to the `Date` it names. The gate is the declaration, and
+ * the kind is `date` alone, because a date is the one type a JSON document
+ * cannot carry — a number arrives as a number, so no other kind has anything
+ * to revive (ADR 0041). Callers that read no style omit the argument and see
  * the seam exactly as it was.
  *
  * @param {any[]} tokens A cell's tokens.
- * @param {unknown} [kind] The cell's resolved `format` declaration.
+ * @param {unknown} [decl] The cell's resolved `format` declaration — the
+ *   `{ kind, digits? | form? }` object the stream carries (docs/adr/0056).
  * @returns {number | boolean | Date | undefined} The native value, if any.
  */
-export function typed(tokens, kind) {
+export function typed(tokens, decl) {
   let [token] = tokens;
   if (tokens.length !== 1 || !("value" in token)) return undefined;
   // `??` and not `||`: a boolean cell's own `false` is a typed value.
-  return asTyped(token.value) ?? asDeclared(token.value, kind);
+  return asTyped(token.value) ?? asDeclared(token.value, decl);
 }
 
 // The report's own bands, by the role their items wear (CONTEXT.md, "Band").