quario 0.0.1 → 0.2.0

package/lib/scope.js

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ */
+/** @typedef {Record<string, any>} Scope */
+/** @typedef {(scope: Scope) => any} Eval */
+/** @typedef {{ fn: string, per: Eval | null }} Fold */
+/** @typedef {[string, Fold][]} Folds */
+/** @typedef {[string, Eval][]} Runners */
+/**
+ * The runner set a band renders under: every runner in scope, as one value.
+ * `bind` steps them, so a band calls it exactly once per detail row.
+ * @typedef {{ extend: (folds: Folds) => RunnerSet,
+ *   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) => {
+  let child = Object.create(scope);
+  child["@"] = row;
+  return child;
+};
+
+// Bind the page anchor (`{ number, total }`) on a child of `scope` for a page
+// band render. `@` stays unbound — a page band has no current row.
+/** @type {(scope: Scope, page: any) => Scope} */
+export let withPage = (scope, page) => {
+  let child = Object.create(scope);
+  child.page = page;
+  return child;
+};
+
+// Evaluate one declared aggregate over `rows` by delegating to the same reducers
+// 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.
+/** @type {(runners: Runners) => RunnerSet} */
+let runnerSet = (runners) => {
+  /** @type {RunnerSet} */
+  let value = {
+    extend: (folds) => {
+      // Declaring no runners is not a change of set, so a band whose `run`
+      // 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]();
+        return /** @type {[string, Eval]} */ ([name, (scope) => step(per ? per(scope) : 1)]);
+      });
+      return runnerSet([...runners, ...started]);
+    },
+    // The per-row detail scope: `@` bound to the row, its running values folded
+    // in render order and exposed as `run`. With no runners in scope, `run`
+    // stays unbound so a stray `run.x` throws instead of silently reading null
+    // — the same fail-loud stance as `@` outside detail bands.
+    bind: (scope, row) => {
+      let child = withRow(scope, row);
+      if (!runners.length) return child;
+      /** @type {Scope} */
+      let run = {};
+      // Every runner steps once per row, outer first; the traversal's shared
+      // `runNames` register keeps run names unique across the whole report, so
+      // no name is ever written twice and the order decides nothing.
+      for (let [name, runner] of runners) run[name] = runner(child);
+      child.run = run;
+      return child;
+    },
+  };
+  return value;
+};
+
+// A report starts its runners the way every band under it does: by extending
+// the set it renders in, which for the report itself is the empty one.
+/** @type {(folds: Folds) => RunnerSet} */
+export let startRunners = (folds) => runnerSet([]).extend(folds);

package/lib/stream.js

@@ -0,0 +1,177 @@
+/**
+ * The event stream's own rules: when a cell's tokens keep their native value,
+ * which format an image item's bytes hold, whose band an item's role names,
+ * how an optional field reaches an event, and the driver a target consumes the
+ * stream through.
+ *
+ * `breathe` sits here because the driver batches on it, not because handing the
+ * loop back is a stream rule — the two are independent, and a target breathes
+ * while stamping finished pages, which is no walk at all (CONTEXT.md).
+ */
+// The token-join sjabloon renders with — literals verbatim, values through
+// 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";
+
+/** @type {(value: any) => boolean} */
+let finiteNum = (value) => typeof value === "number" && Number.isFinite(value);
+/** @type {(value: any) => boolean} */
+let finiteDate = (value) => value instanceof Date && Number.isFinite(value.getTime());
+/** @type {(value: any) => number | boolean | Date | undefined} */
+let asTyped = (value) => {
+  if (finiteNum(value)) return value;
+  if (typeof value === "boolean") return value;
+  if (finiteDate(value)) return value;
+  return undefined;
+};
+
+/**
+ * The typed-cell seam: exactly one value token holding a finite number, a
+ * boolean, or a valid Date keeps its pre-stringify value. Anything else —
+ * including a lone null, matching the display-text treatment everywhere
+ * else — reports `undefined` and joins to text.
+ *
+ * @param {any[]} tokens A cell's tokens.
+ * @returns {number | boolean | Date | undefined} The native value, if any.
+ */
+export function typed(tokens) {
+  let [token] = tokens;
+  if (tokens.length !== 1 || !("value" in token)) return undefined;
+  return asTyped(token.value);
+}
+
+// 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).
+let REPORT_BANDS = new Set([
+  "report-header",
+  "report-footer",
+  "empty",
+  "page-header",
+  "page-footer",
+]);
+
+/**
+ * Whether a band item's `role` names one of the report's own bands rather than
+ * a group instance's. This says whose band it is, never how to lay one out —
+ * what a consumer does with the answer is its own. See SCHEMA.md ("Event
+ * stream") for the contract and ADR 0028 for why the engine classifies rather
+ * than carrying a verdict on the events themselves.
+ *
+ * @param {string} role An item or image event's `role`.
+ * @returns {boolean} True for the report's own bands.
+ */
+export function isReportBand(role) {
+  return REPORT_BANDS.has(role);
+}
+
+// The two raster formats an image item may carry, as the bytes announce
+// themselves: PNG's 8-byte signature and JPEG's start-of-image marker. Read,
+// never decoded -- the engine answers which format the bytes are, not what
+// they depict.
+let PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+let JPEG = [0xff, 0xd8, 0xff];
+
+/**
+ * The image seam: name the format a `source` expression's bytes hold, or null
+ * when they are not image bytes at all -- including when they are not bytes.
+ * The traversal sniffs once per image event and the answer rides on the event,
+ * so no consumer repeats it.
+ *
+ * @param {any} bytes The value a `source` expression yielded.
+ * @returns {"png" | "jpeg" | null} The format, or null when unreadable.
+ */
+export function sniff(bytes) {
+  if (!(bytes instanceof Uint8Array)) return null;
+  if (PNG.every((byte, i) => bytes[i] === byte)) return "png";
+  if (JPEG.every((byte, i) => bytes[i] === byte)) return "jpeg";
+  return null;
+}
+
+// The cooperative hand-back's plumbing. A timer is the slowest way a runtime will
+// hand the loop back and, until this landed, the only one quario used: measured
+// on an M-series Mac it costs ~1.20ms per hand-back against ~0.015ms for
+// setImmediate, so a 10k-row render spent about 30% of its wall-clock waiting
+// on timers. Browsers are worse — once nested-timer depth passes five, the
+// HTML spec clamps a zero timer to 4ms, i.e. ~4ms per batch on a long report.
+// Deliberately not scheduler.yield(): it is Chrome-only, and its continuation
+// is scheduled ahead of other host tasks, which is the opposite of what handing
+// the loop back is for. The timer stays as the last rung for a runtime that
+// offers neither of the others; no runtime quario supports reaches it.
+//
+// setImmediate is Node's alone, so reaching it is a feature detection and not
+// an import: this module runs in browsers too, where importing node:timers
+// would not resolve. The lookup goes through globalThis because the package's
+// types are deliberately DOM-only (only @quario/xlsx pulls Node's in) — a
+// typed global would mean a dependency for one name.
+let immediate = /** @type {any} */ (globalThis).setImmediate;
+/** @type {MessageChannel | undefined} */
+let channel;
+/** @type {(() => void)[]} */
+let waiting = [];
+
+/**
+ * Hand the event loop back to the host, resolving once it has had its turn.
+ * The walk driver calls it between batches, and a target running a loop of its
+ * own — a paginated target stamping its finished pages, say — calls it the
+ * same way, so a long report never blocks the host. Which kind of task the turn
+ * is taken as is current behaviour rather than a promise. See SCHEMA.md
+ * ("Handing the loop back"), which is normative.
+ *
+ * @returns {Promise<void>} Resolves once the host has had its turn.
+ */
+export async function breathe() {
+  if (typeof immediate === "function") {
+    await new Promise((resolve) => immediate(resolve));
+  } else if (typeof MessageChannel === "function") {
+    if (!channel) {
+      channel = new MessageChannel();
+      // One message wakes exactly one waiter, so concurrent renders take their
+      // turns in order instead of racing for a single slot — a lost wake-up
+      // here would hang a render, not merely slow it down.
+      channel.port1.onmessage = () => waiting.shift()?.();
+    }
+    let port = channel.port2;
+    await new Promise((resolve) => {
+      waiting.push(/** @type {() => void} */ (resolve));
+      port.postMessage(0);
+    });
+  } else {
+    await new Promise((resolve) => setTimeout(resolve));
+  }
+}
+
+/**
+ * The walk driver: dispatch one render's event stream to per-event handlers,
+ * so a target writes no event loop of its own — in stream order, exactly once
+ * each, pulled lazily, handing the loop back every 1000 events. A missing
+ * handler ignores that event, a handler that throws rejects without draining
+ * the rest, and handlers are synchronous: a promise one returns is not
+ * awaited. The stream's first event reaches its handler before a second one is
+ * pulled, so a target settles what it needs from `report-start` — page band
+ * closures, the marking — in that handler rather than pulling the stream
+ * itself. No opening event is required: the driver reads `event.type` and
+ * nothing else, so a stream that starts part-way through walks like any other.
+ * See SCHEMA.md ("The walk driver"), which is normative.
+ *
+ * @param {Iterable<any>} events One render's event stream.
+ * @param {Record<string, (event: any) => void>} handlers Per-event handlers.
+ * @returns {Promise<void>} Resolves when the stream is exhausted.
+ */
+export async function walk(events, handlers) {
+  let seen = 0;
+  for (let event of events) {
+    handlers[event.type]?.(event);
+    if (++seen % 1000 === 0) await breathe();
+  }
+}
+
+// Optional public event fields are present only when truthy — the one rule
+// for optional event data, owned here. What rides it is therefore any value
+// whose falsy form means "undeclared"; a field whose zero or empty string is
+// meaningful cannot use this seam.
+/** @type {(base: any, extra: any) => any} */
+export let opt = (base, extra) => {
+  for (let key in extra) if (extra[key]) base[key] = extra[key];
+  return base;
+};

package/lib/style.js

@@ -0,0 +1,81 @@
+/**
+ * The closed style vocabulary, as the traversal checks it: target-neutral names
+ * with typed literal values. Unknown names and mistyped literals are definition
+ * errors; `=` results stay lenient at render. Each target maps these names to
+ * its own formatting model, and nothing here knows about any of them.
+ *
+ * `finite`/`HEX` are restated per target on purpose: those coercions are each
+ * target's own edge, never shared engine code — unlike the stream rules
+ * (`typed`), which every target reads from `./stream.js`.
+ */
+/** @type {(value: any) => boolean} */
+let finite = (value) => typeof value === "number" && Number.isFinite(value);
+let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+/** @type {(value: any) => boolean} */
+let isHex = (value) => typeof value === "string" && HEX.test(value);
+/** @typedef {{ ok: (value: any) => boolean, msg: string }} StyleSpec */
+/** @type {(msg: string, ok: (value: any) => boolean) => StyleSpec} */
+let spec = (msg, ok) => ({ ok, msg });
+let COLOR = spec("expected a #rgb or #rrggbb color", isHex);
+let FLAG = spec("expected a boolean", (value) => typeof value === "boolean");
+let ALIGNMENTS = ["left", "center", "right"];
+// The declarations an image item accepts. The rest of the vocabulary describes
+// text, which an image does not have, so anything else on one is a definition
+// error rather than a silent no-op (SCHEMA.md, "Image item"). The subset lives
+// beside the vocabulary it narrows, and `checkImageStyle` below is how the
+// traversal asks for it -- it keeps no second list of its own.
+let IMAGE_STYLES = ["align", "background"];
+// The declarations a report default accepts. A report default states what the
+// document is set in, so it carries only the two declarations that describe a
+// typeface -- and, unlike the rest of the vocabulary, only the two no band-role
+// default has to argue with. Anything else is a definition error rather than a
+// silent no-op, exactly as on an image (SCHEMA.md, "Report default").
+let REPORT_STYLES = ["family", "size"];
+/** @type {Record<string, StyleSpec>} */
+let STYLES = {
+  family: spec(
+    "expected a font family name",
+    (value) => typeof value === "string" && value.length > 0,
+  ),
+  size: spec("expected a positive number of points", (value) => finite(value) && value > 0),
+  bold: FLAG,
+  italic: FLAG,
+  underline: FLAG,
+  strikethrough: FLAG,
+  uppercase: FLAG,
+  color: COLOR,
+  background: COLOR,
+  align: spec("expected left, center, or right", (value) => ALIGNMENTS.includes(value)),
+};
+// One check for both the validating traversal and the compile path: an error
+// message for a declaration, or null when it is acceptable (expressions defer
+// to render).
+/** @type {(value: any) => boolean} */
+let isExpr = (value) => typeof value === "string" && value[0] === "=";
+/** @type {(name: string, value: any) => string | null} */
+export let checkStyle = (name, value) => {
+  // Own-key lookup: a declaration named after an Object.prototype member
+  // (`toString`, `constructor`) is unknown, not an inherited function.
+  if (!Object.hasOwn(STYLES, name)) return 'unknown style "' + name + '"';
+  if (isExpr(value)) return null;
+  let rule = STYLES[name];
+  return rule.ok(value) ? null : rule.msg;
+};
+
+// The same check narrowed to a subset of the vocabulary, so a declaration a
+// node cannot wear is refused as pointedly as an unknown name rather than
+// silently doing nothing. A node that takes part of the vocabulary names the
+// checker this makes rather than passing a flag, which is what keeps each
+// subset and its wording together, here.
+//
+// `subject` completes "does not apply to ___", so it carries its own article.
+/** @type {(allowed: string[], subject: string) => (name: string, value: any) => string | null} */
+let narrowed = (allowed, subject) => (name, value) =>
+  Object.hasOwn(STYLES, name) && !allowed.includes(name)
+    ? 'style "' + name + '" does not apply to ' + subject
+    : checkStyle(name, value);
+
+export let checkImageStyle = narrowed(IMAGE_STYLES, "an image");
+// "a report default" rather than the key's name: the key is `style` like every
+// other one, so the message has to say which `style` refused it.
+export let checkReportStyle = narrowed(REPORT_STYLES, "a report default");

package/package.json

@@ -1,7 +1,60 @@
 {
   "name": "quario",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
-  "license": "UNLICENSED"
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/quario"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "test:browser": "node test/browser/setup.js",
+    "test:types": "tsc && attw --pack . --profile esm-only",
+    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "prepack": "../../scripts/release-date.mjs && node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
+  },
+  "dependencies": {
+    "padvinder": "^0.9.0",
+    "sjabloon": "^0.12.0",
+    "xprsn": "^0.11.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "ignore": [
+        "xprsn",
+        "sjabloon",
+        "padvinder"
+      ],
+      "limit": "9 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
 }