quario 0.6.0 → 0.7.0

package/lib/reducers.js

@@ -150,6 +150,53 @@ export let namesFor = (role) =>
  */
 export let runnerFor = (fn) => REGISTRY[fn].run();
 
+// Nullish never reaches here, so what is left is a type name -- and only the
+// article in front of it needs a decision.
+/** @type {(value: any) => string} */
+let typeOf = (value) => (typeof value === "object" ? "an object" : "a " + typeof value);
+// One demand, stated twice: what the argument must be, and the sentence that
+// says so.
+/** @type {(ok: (value: any) => boolean, says: string) => (fn: string, value: any) => void} */
+let demands = (ok, says) => (fn, value) => {
+  if (value != null && !ok(value)) throw new TypeError(fn + says + typeOf(value));
+};
+let anArray = demands(Array.isArray, " is a reducer over an array, not a scalar function; got ");
+let aLambda = demands(
+  (value) => typeof value === "function",
+  " takes a lambda as its second argument; got ",
+);
+
+// What an author actually wrote, in the words the spec uses for it. A reducer
+// reached an expression as an ordinary registry function, so a call the
+// registry cannot honour used to fold anyway and fail inside: `min(1, 2)`
+// arrived as "(rows || []).map is not a function", the fold's own internals
+// located at the cell but naming neither the reducer nor the mistake
+// (quario-4lys). Two of them did not even fail: `count` and `avg` reach for a
+// `length` before they fold, so `count('ab')` answered 2 -- a string's own
+// length, counted as rows -- and `count(1)` and `avg(1, 2)` answered with
+// nothing at all.
+//
+// The guard wraps the table's own entries because this is the one place the
+// reducer's name is in hand to say. Only one of the two consumers can carry an
+// authored mistake -- `plan.js` spreads this record into an expression's
+// function scope, where the arguments are whatever the author wrote -- while
+// `scope.js` folds rows the engine grouped through a compiled lambda, so
+// neither demand can fire there. That dead check is the price of one door
+// instead of two, and it is a comparison per fold, not per row. Nullish passes
+// both: an absent read is null, so `sum(@.lines)` on a row with no lines folds
+// the empty array, which is the answer the spec's six give.
+//
+// It carries no engine code: the mistake is quario's own verdict on an
+// authored call, like `round`'s bad `n`, and SCHEMA.md's "Validation" tells a
+// host to recognise a located error with `isDiagnostic` rather than by probing
+// a `code` anything could fake.
+/** @type {(fn: string, fold: Reducer) => Reducer} */
+let guarded = (fn, fold) => (rows, of) => {
+  anArray(fn, rows);
+  aLambda(fn, of);
+  return fold(rows, of);
+};
+
 /**
  * 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
@@ -161,5 +208,5 @@ 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)]),
+  namesFor("aggregate").map((fn) => [fn, guarded(fn, /** @type {Reducer} */ (REGISTRY[fn].fold))]),
 );

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 { record } from "./names.js";
 import { kindOf } from "./style.js";
 
 /** @type {(value: any) => boolean} */
@@ -104,12 +105,83 @@ export let reviveDate = (value) => {
  * @returns {number | boolean | Date | undefined} The native value, if any.
  */
 export function typed(tokens, decl) {
-  let [token] = tokens;
-  if (tokens.length !== 1 || !("value" in token)) return undefined;
+  if (!oneValue(tokens)) return undefined;
   // `??` and not `||`: a boolean cell's own `false` is a typed value.
+  let [token] = tokens;
   return asTyped(token.value) ?? asDeclared(token.value, decl);
 }
 
+/**
+ * Whether a token list renders exactly one value token -- the seam `typed()`
+ * gates on, and the same one `format` is read under. A run holding a literal
+ * and an interpolation, or two interpolations, presents no single value, so a
+ * declaration that presents a value has nothing to speak about (ADR 0061).
+ *
+ * Internal to the package: `typed()` is the public reading of it, and the
+ * traversal asks it of the tokens each style block governs.
+ *
+ * @type {(tokens: any[]) => boolean}
+ */
+export let oneValue = (tokens) => tokens.length === 1 && "value" in tokens[0];
+
+// Two objects holding the same own names, each pair judged by `alike`. The
+// one shape both levels of style equality are written in.
+/** @type {(a: any, b: any, alike: (x: any, y: any) => boolean) => boolean} */
+let sameRecord = (a, b, alike) =>
+  Object.keys(a).length === Object.keys(b).length &&
+  Object.keys(a).every((name) => Object.hasOwn(b, name) && alike(a[name], b[name]));
+
+/** @type {(a: any, b: any) => boolean} */
+let strictly = (a, b) => a === b;
+
+// Value equality one level deep, which is exhaustive rather than approximate
+// for a resolved style block: `format` is the only object-valued declaration
+// and is itself flat (SCHEMA.md, "Event stream"). Identity short-circuits,
+// which is the common case -- the engine shares one resolved object across a
+// run's tokens.
+/** @type {(a: any, b: any) => boolean} */
+let sameValue = (a, b) => a === b || (record(a) && record(b) ? sameRecord(a, b, strictly) : false);
+
+/**
+ * Whether two token styles resolve identically. `null` is the absence of one,
+ * so an unstyled token and one carrying an empty block are not two cases.
+ *
+ * @type {(a: any, b: any) => boolean}
+ */
+export let sameStyle = (a, b) => a === b || (a && b ? sameRecord(a, b, sameValue) : false);
+
+// Whether a token wearing `style` belongs to the run being built.
+/** @type {(last: any, style: any) => boolean} */
+let joins = (last, style) => !!last && sameStyle(last.style, style);
+
+/**
+ * Group a cell's tokens into its styled runs, in order. Consecutive tokens
+ * with equal styles are one run — a lossless rule, because equal styles render
+ * identically, so grouping survives a JSON round trip and a target that
+ * reserialized the stream reads the same runs back.
+ *
+ * Shipped so the built-in targets and a custom one cannot drift: the stream
+ * carries a cell's runs flattened into one `tokens` array with an optional
+ * per-token `style`, and this is the whole rule for reading them back
+ * (SCHEMA.md, "Event stream"; ADR 0061).
+ *
+ * @param {any[]} tokens A cell's tokens.
+ * @returns {{ style: any, tokens: any[] }[]} The runs, each with the style its
+ *   tokens carry — `null` where they carry none, and the cell's own `style`
+ *   applies.
+ */
+export function styledRuns(tokens) {
+  /** @type {{ style: any, tokens: any[] }[]} */
+  let out = [];
+  for (let token of tokens) {
+    let style = token.style ?? null;
+    let last = out[out.length - 1];
+    if (joins(last, style)) last.tokens.push(token);
+    else out.push({ style, tokens: [token] });
+  }
+  return out;
+}
+
 // The report's own bands, by the role their items wear (CONTEXT.md, "Band").
 // The page ones are in it although no walk emits them: the question is whose
 // band a role names, not what a walk hands over (ADR 0028).

package/lib/style.js

@@ -207,6 +207,14 @@ let checkFormat = (value) => {
 // in. They share every site, so the places that refuse one refuse both from
 // this list rather than from two lists that have to be compared (ADR 0041).
 let VALUE_NAMES = ["format", "currency"];
+/**
+ * Whether a name is one of the two. The counterpart of `isBoxName`, and the
+ * one place the question is answered: the traversal withdraws both together
+ * from a style whose tokens are not a single value token (ADR 0061).
+ *
+ * @type {(name: string) => boolean}
+ */
+export let isValueName = (name) => VALUE_NAMES.includes(name);
 let POINTS = spec(
   "expected a non-negative number of points",
   (value) => finite(value) && value >= 0,
@@ -326,6 +334,44 @@ let withoutNames = (names, check, subject) => (name, value) =>
 let withoutFlow = (check, subject) => withoutNames(FLOW_NAMES, check, subject);
 
 export let checkCellStyle = withoutFlow(checkStyle, "a table cell");
+// The inline half of the vocabulary: what a stretch of text inside a cell can
+// wear. The box and flow spacing describe a block and `align` describes a
+// line, and neither means anything on part of one -- so a styled run is
+// narrowed from the other end than an image item is, which keeps only what a
+// picture can wear (SCHEMA.md, "Style declarations").
+let RUN_STYLES = [
+  "family",
+  "size",
+  "bold",
+  "italic",
+  "underline",
+  "strikethrough",
+  "color",
+  "background",
+  "uppercase",
+  "format",
+  "currency",
+];
+/**
+ * The inline half as a list, in the vocabulary's own order — the same bargain
+ * `STYLE_NAMES` is: a tool that offers what a styled run may wear (the
+ * editor's style rail) imports this rather than keeping a copy that has to be
+ * told about every change here.
+ */
+/** @type {readonly string[]} */
+export let RUN_STYLE_NAMES = Object.freeze(STYLE_NAMES.filter((name) => RUN_STYLES.includes(name)));
+let RUN = new Set(RUN_STYLES);
+/**
+ * Whether a name is one a styled run may wear. The counterpart of
+ * `isBoxName`, and what the traversal composes a run's block through: a cell's
+ * declarations reach its runs, but only the ones a run could have declared
+ * itself, so a cell's padding or `align` never rides down onto a stretch of
+ * its text (ADR 0061).
+ *
+ * @type {(name: string) => boolean}
+ */
+export let isRunName = (name) => RUN.has(name);
+export let checkRunStyle = narrowed(RUN_STYLES, "a styled run");
 export let checkSlotStyle = withoutFlow(checkStyle, "a split slot");
 // `valign` is legal exactly where a box has height it did not ask for
 // (CONTEXT.md "Box": slack). A slot's box is the split's height, so a slot --
@@ -384,7 +430,7 @@ export let SKIP = Symbol("skip");
  * them to a value no target can read. It is the rule for the box too: side
  * ownership is settled over the names a block declares, before any of this
  * resolves, so dropping a rejected `borderTopColor` cannot hand the cell its
- * row's other two (docs/adr/0056).
+ * row's other two (docs/adr/0062).
  *
  * **Voided** is `currency` alone. Its fallback is not the layer below but the
  * instance's own code, so omitting would present one denomination's money
@@ -549,7 +595,7 @@ let BORDER_NAMES = Object.fromEntries(
  * name it declares whatever the values resolve to. Composing the totals block
  * into its rows uses it at compile time, so no third style level survives to
  * render (docs/adr/0049); fanning a row's box onto its cells uses it for the
- * same reason (docs/adr/0056).
+ * same reason (docs/adr/0062).
  *
  * @type {(names: Iterable<string>) => Set<string>}
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -51,7 +51,7 @@
         "sjabloon",
         "padvinder"
       ],
-      "limit": "13 kB"
+      "limit": "14 kB"
     }
   ],
   "engines": {