quario 0.0.1 → 0.2.0

package/lib/index.d.ts

@@ -0,0 +1,617 @@
+import type { PadvinderErrorCode, QueryOptions, QueryPath, TrefferErrorCode } from "padvinder";
+import type { XprsnErrorCode, XprsnSignature } from "xprsn";
+import type {
+  LiteralToken as SjabloonLiteralToken,
+  SjabloonBlock,
+  SjabloonErrorCode,
+  ValueToken as SjabloonValueToken,
+} from "sjabloon";
+
+// Re-exported so render targets type the stream's `paths` metadata from
+// 'quario' alone, without their own padvinder dependency.
+export type { QueryPath } from "padvinder";
+
+export type FunctionRegistry = Record<string, (...args: any[]) => any>;
+export type ExpressionValue<T = unknown> = T | `=${string}`;
+export type ReducerSpec = string;
+
+/**
+ * A value a JSON document can hold. `params` accepts these and nothing else:
+ * a Date, Map, Set or typed array is a definition error, as are `NaN` and
+ * `Infinity`, which this type cannot exclude but the traversal rejects.
+ */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * The closed, target-neutral style vocabulary. Literal values are validated
+ * strictly (unknown names and mistyped literals are definition errors);
+ * `=` expression results are coerced leniently by each target at render.
+ * Colors are `#rgb`/`#rrggbb` hex only. Each target maps the declarations to
+ * its own formatting model (the HTML target to inline CSS, the PDF target to
+ * faces, points, and rects).
+ */
+export interface StyleDeclarations {
+  /** `'sans'` | `'serif'` | `'mono'`, or an embedded font family name. */
+  family?: ExpressionValue<string>;
+  /** Font size in points. */
+  size?: ExpressionValue<number>;
+  bold?: ExpressionValue<boolean>;
+  italic?: ExpressionValue<boolean>;
+  underline?: ExpressionValue<boolean>;
+  strikethrough?: ExpressionValue<boolean>;
+  /** Render the text in capitals. Capitals, not small caps. */
+  uppercase?: ExpressionValue<boolean>;
+  /** Text color, `#rgb`/`#rrggbb`. */
+  color?: ExpressionValue<string>;
+  /** Background color, `#rgb`/`#rrggbb`. */
+  background?: ExpressionValue<string>;
+  /** Horizontal alignment within the cell. */
+  align?: ExpressionValue<Align>;
+}
+
+export interface SortKey {
+  by: `=${string}`;
+  dir?: "asc" | "desc";
+}
+
+/** A cell value: one template string. */
+export type CellValue = string;
+
+export type Align = "left" | "center" | "right";
+
+export interface Cell {
+  value: CellValue;
+  visible?: ExpressionValue<boolean>;
+  /** Literal only — never an expression. */
+  style?: StyleDeclarations;
+}
+
+export interface TextItem extends Cell {
+  type: "text";
+}
+
+/** How an image is sized: at its intrinsic size, or scaled to the content width. */
+export type ImageFit = "natural" | "width";
+
+/**
+ * The declarations an image item accepts. The rest of the vocabulary describes
+ * text, which an image does not have, so any other name on one is a definition
+ * error. A narrowing of the one vocabulary rather than a second list of its
+ * own, so the two cannot drift.
+ */
+export type ImageStyleDeclarations = Pick<StyleDeclarations, "background" | "align">;
+
+/**
+ * What a report default declares: the two declarations a typeface is made of.
+ * Anything else is a definition error, as on an image item.
+ */
+export type ReportStyleDeclarations = Pick<StyleDeclarations, "family" | "size">;
+
+/**
+ * A host-supplied raster graphic in the band flow. `source` is an expression
+ * (never a literal — JSON has no way to write bytes) yielding the complete
+ * image file as a `Uint8Array` of PNG or JPEG bytes; nullish skips the item
+ * silently, anything else invalid is a located render error.
+ */
+export interface ImageItem {
+  type: "image";
+  source: `=${string}`;
+  /** Defaults to `"natural"`. */
+  fit?: ImageFit;
+  /** The image's textual stand-in, as a cell value. */
+  alt?: CellValue;
+  visible?: ExpressionValue<boolean>;
+  style?: ImageStyleDeclarations;
+}
+
+/**
+ * One slot of a split: an ordinary item, plus the width share that is a slot
+ * property rather than an item one. A split may not stand in a slot —
+ * placement inside placement is the coordinate system quario does not have.
+ */
+export type SplitSlot = (TextItem | ImageItem) & {
+  /** Slot width as a percentage of the content width (0 < width <= 100). */
+  width?: number;
+};
+
+/**
+ * Items placed across the content width rather than stacked down the band —
+ * the invoice header's "seller left, customer right". A split is always the
+ * full content width and never nests; a slot that renders nothing keeps its
+ * width, so the line's geometry does not move with the data.
+ */
+export interface SplitItem {
+  type: "split";
+  slots: [SplitSlot, SplitSlot, ...SplitSlot[]];
+  visible?: ExpressionValue<boolean>;
+  style?: StyleDeclarations;
+}
+
+/** One item in a band: text, an image, or a split. Future types may be additive. */
+export type Item = TextItem | ImageItem | SplitItem;
+
+export interface TableHeader {
+  value: CellValue;
+  /** Literal only — never an expression. */
+  style?: StyleDeclarations;
+}
+
+export interface TableColumn extends Cell {
+  header: string | TableHeader;
+  /** Column width as a percentage of the table width (0 < width <= 100). */
+  width?: number;
+}
+
+export interface TableRow {
+  visible?: ExpressionValue<boolean>;
+  style?: StyleDeclarations;
+}
+
+export interface TableDetail {
+  row?: TableRow;
+  columns: [TableColumn, ...TableColumn[]];
+  total?: Cell[];
+}
+
+export interface Group {
+  name: string;
+  by: `=${string}`;
+  /** Start every instance of this group on a new page (paginated targets). */
+  break?: "page";
+  /**
+   * Restart `page.number` / `page.total` at every instance. Each instance also
+   * starts on a fresh page, the same rule `break` has.
+   */
+  reset?: "page";
+  /**
+   * Flow each instance's content in this many page columns (integer >= 2).
+   * Columned regions cannot nest.
+   */
+  columns?: number;
+  sort?: SortKey[];
+  /**
+   * Keep this many rows after this group's `sort`. Integer >= 1. Rows past
+   * the count are dropped from aggregates and runners, unlike `visible`.
+   */
+  take?: number;
+  aggregates?: Record<string, ReducerSpec>;
+  /** Running accumulators, read as `run.<name>` on detail rows. */
+  run?: Record<string, ReducerSpec>;
+  header?: Item[];
+  footer?: Item[];
+}
+
+/**
+ * Page header/footer bands, rendered once per page by paginated targets
+ * (unpaginated targets ignore them). Cells read `$` and the `page` anchor
+ * (`page.number` / `page.total`, 1-based, the current sequence); `@` stays unbound.
+ */
+export interface PageBands {
+  header?: Item[];
+  footer?: Item[];
+}
+
+export interface ReportSchema {
+  params?: Record<string, JsonValue>;
+  data: string;
+  where?: `=${string}`;
+  sort?: SortKey[];
+  /**
+   * Keep this many rows after the report `sort`. Integer >= 1. Rows past the
+   * count are dropped from aggregates and runners, unlike `visible`.
+   */
+  take?: number;
+  aggregates?: Record<string, ReducerSpec>;
+  /** Running accumulators, read as `run.<name>` on detail rows. */
+  run?: Record<string, ReducerSpec>;
+  /**
+   * The report default: the typeface this document is set in. It sits under
+   * the targets' band-role defaults and under every item's own `style`, so a
+   * declared `size` does not change a report header's headline size.
+   */
+  style?: ReportStyleDeclarations;
+  header?: Item[];
+  empty?: Item[];
+  /**
+   * Flow the report body in this many page columns (integer >= 2). Columned
+   * regions cannot nest.
+   */
+  columns?: number;
+  groups?: Group[];
+  detail?: Item[] | TableDetail;
+  footer?: Item[];
+  page?: PageBands;
+}
+
+/**
+ * One render target — the rollup-plugin shape: self-naming, with `compile`
+ * called per `render(target, data)` call against the public event stream, so
+ * it must be cheap and stateless; per-render work belongs in the renderer it
+ * returns. Official factories (`html()`, `pdf()`, `xlsx()`, `csv()`) return these; a
+ * custom target is any object honoring the contract (SCHEMA.md, "Instances
+ * and targets"). A renderer may return its output synchronously; `render` is
+ * always a promise.
+ */
+export interface Target<Name extends string = string, Out = unknown> {
+  /** A diagnostic label — a plain identifier naming what the target is. */
+  name: Name;
+  /** Builds this target's renderer over one compiled event stream. */
+  compile: (stream: ReportEventStream) => (data?: unknown) => Out;
+}
+
+export interface QuarioOptions {
+  query?: QueryOptions;
+  /**
+   * License key (LICENSE section 6). Verified offline once, when the instance
+   * is created; `license` settles with the result. Without a key, or with one
+   * whose validity window does not cover this version's release date, every
+   * report this instance compiles marks its output as unlicensed.
+   */
+  license?: string;
+}
+
+/** The settled result of an instance's license key verification. */
+export interface LicenseInfo {
+  licensed: boolean;
+  licensee?: string;
+  id?: string;
+}
+
+export type ItemRole =
+  | "report-header"
+  | "empty"
+  | "group-header"
+  | "detail"
+  | "group-footer"
+  | "report-footer"
+  | "page-header"
+  | "page-footer";
+
+/** One static text run of a cell's template, verbatim (sjabloon's literal token). */
+export type LiteralToken = SjabloonLiteralToken;
+
+/** One interpolation's pre-stringify value (sjabloon's value token). */
+export type ValueToken = SjabloonValueToken;
+
+export type Token = LiteralToken | ValueToken;
+
+export interface EventCell {
+  tokens: Token[];
+  style?: Record<string, unknown>;
+  /**
+   * The definition's schema path, on cells that belong to one: a `row` cell
+   * carries its column's (`detail.columns[i]`), a `total-row` cell its
+   * `detail.total[i]` entry. Absent on page-band cells reached by closure.
+   */
+  path?: string;
+}
+
+/** The page anchor a paginated target passes to page band closures. */
+export interface PageInfo {
+  /** 1-based page number of the current sequence. */
+  number: number;
+  /** Page count of the current sequence. */
+  total: number;
+}
+
+/**
+ * Per-render page band closures on `report-start` (present only when the
+ * schema declares page bands). A paginated target calls them once per page;
+ * each call returns resolved `page-header`/`page-footer` item events.
+ */
+export interface PageBandRenderers {
+  header?: (page: PageInfo) => (ItemEvent | ImageEvent)[];
+  footer?: (page: PageInfo) => (ItemEvent | ImageEvent)[];
+}
+
+export interface ReportStartEvent {
+  type: "report-start";
+  params: Record<string, JsonValue>;
+  aggregates: Record<string, unknown>;
+  page?: PageBandRenderers;
+  /** The declared page column count, present when the root declares one. */
+  columns?: number;
+  /**
+   * The resolved report default, present when the report declares one. It is
+   * a report-level fact rather than something merged into each item's style,
+   * so a consumer composes it once — under its own band-role defaults, and
+   * under every event's own `style`. Ignoring it renders the report in the
+   * consumer's own baseline, which is what a consumer written before this
+   * field already does.
+   */
+  style?: Record<string, unknown>;
+  /**
+   * The marking wording, present when this render is not covered by a valid
+   * license key — including while verification is still settling (await the
+   * stream's `license` promise first, as the shipped targets do). Absent
+   * otherwise. Each target renders this text in its own idiom; the engine
+   * states it so no target has to know it.
+   */
+  marking?: string;
+}
+
+export interface ItemEvent {
+  type: "item";
+  role: ItemRole;
+  /** The item definition's schema path, e.g. `detail[0]`. */
+  path: string;
+  tokens: Token[];
+  style?: Record<string, unknown>;
+  run?: Record<string, unknown>;
+}
+
+/** The format the engine sniffed from an image's bytes. */
+export type ImageFormat = "png" | "jpeg";
+
+export interface ImageEvent {
+  type: "image";
+  role: ItemRole;
+  /** The image definition's schema path. */
+  path: string;
+  /** The bytes exactly as the `source` expression yielded them. */
+  bytes: Uint8Array;
+  /** Sniffed from the bytes' magic numbers, so no consumer repeats it. */
+  format: ImageFormat;
+  fit: ImageFit;
+  /** The rendered `alt` template, present when the item declares one. */
+  alt?: Token[];
+  style?: Record<string, unknown>;
+  run?: Record<string, unknown>;
+}
+
+/**
+ * Opens a split: the slot geometry, then one ordinary `item` or `image` event
+ * per slot in order, then `split-end`. A consumer with no handler for the
+ * bracket still receives the slot items and renders them stacked.
+ */
+export interface SplitStartEvent {
+  type: "split-start";
+  role: ItemRole;
+  /** One entry per slot, in order; `width` is absent on a width-less slot. */
+  slots: { width?: number }[];
+  style?: Record<string, unknown>;
+}
+
+export interface SplitEndEvent {
+  type: "split-end";
+}
+
+export interface GroupStartEvent {
+  type: "group-start";
+  name: string;
+  /** The group definition's schema path, e.g. `groups[0]`. */
+  path: string;
+  depth: number;
+  key: unknown;
+  aggregates: Record<string, unknown>;
+  break?: "page";
+  /** Restart `page.number` / `page.total` at every instance (paginated targets). */
+  reset?: "page";
+  /** The declared page column count, present when the group declares one. */
+  columns?: number;
+}
+
+export interface GroupEndEvent {
+  type: "group-end";
+  name: string;
+  depth: number;
+}
+
+export interface TableStartEvent {
+  type: "table-start";
+  /** Always `detail` — the table definition's schema path. */
+  path: string;
+  columns: { header: EventCell; path: string; width?: number }[];
+}
+
+export interface RowEvent {
+  type: "row";
+  cells: EventCell[];
+  style?: Record<string, unknown>;
+  run?: Record<string, unknown>;
+}
+
+export interface TotalRowEvent {
+  type: "total-row";
+  cells: EventCell[];
+}
+
+export interface TableEndEvent {
+  type: "table-end";
+}
+
+export interface ReportEndEvent {
+  type: "report-end";
+}
+
+export type ReportEvent =
+  | ReportStartEvent
+  | ItemEvent
+  | ImageEvent
+  | SplitStartEvent
+  | SplitEndEvent
+  | GroupStartEvent
+  | GroupEndEvent
+  | TableStartEvent
+  | RowEvent
+  | TotalRowEvent
+  | TableEndEvent
+  | ReportEndEvent;
+
+/**
+ * One registry function a compiled report calls: its arity (the function's
+ * declared parameter count, or its own numeric `arity` where `length`
+ * misleads) and its own `doc` string when it carries one — xprsn's
+ * `signatures()` convention, in call-first-seen order. Aliased so hosts type
+ * the metadata from 'quario' alone, without their own xprsn dependency.
+ */
+export type FunctionSignature = XprsnSignature;
+
+export interface ReportEventStream {
+  (data?: unknown): Generator<ReportEvent, void, undefined>;
+  readonly names: readonly string[];
+  readonly functions: readonly FunctionSignature[];
+  readonly paths: readonly QueryPath[];
+}
+
+/**
+ * Per-event handlers for `walk`, keyed by event type; a missing handler
+ * ignores that event.
+ */
+export type WalkHandlers = {
+  [K in ReportEvent["type"]]?: (event: Extract<ReportEvent, { type: K }>) => void;
+};
+
+/**
+ * The walk driver: dispatch one render's event stream to per-event handlers,
+ * in stream order and exactly once each, pulling lazily and handing the loop
+ * back between batches. 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` there rather
+ * than pulling the stream itself; no opening event is required, and a stream
+ * that starts part-way through walks like any other.
+ */
+export function walk(events: Iterable<ReportEvent>, handlers: WalkHandlers): Promise<void>;
+
+/**
+ * Hand the event loop back to the host, resolving once it has had its turn.
+ * The walk driver calls it between batches; a target running a loop of its own
+ * calls it the same way, so a long report never blocks the host.
+ */
+export function breathe(): Promise<void>;
+
+/**
+ * Every code a located diagnostic can carry, which is a code from whichever
+ * engine decided the fault: quario relocates xprsn's directly, sjabloon
+ * carries xprsn's on a fault inside an expression, and padvinder carries
+ * treffer's on a pattern literal rejected when the query compiles.
+ *
+ * `TrefferErrorCode` reaches this union through padvinder, which re-exports
+ * it, so quario needs no treffer dependency to name it here.
+ */
+export type QuarioErrorCode =
+  | SjabloonErrorCode
+  | XprsnErrorCode
+  | PadvinderErrorCode
+  | TrefferErrorCode;
+
+export interface QuarioDiagnostic extends Error {
+  /** Absent on option and target-definition faults; present on every other diagnostic. */
+  readonly code?: QuarioErrorCode;
+  readonly start?: number;
+  readonly end?: number;
+  readonly limit?: number;
+  readonly actual?: number;
+  readonly blocks?: readonly SjabloonBlock[];
+}
+
+/** The compiled report: `stream` plus its metadata, rendered per target. */
+export interface CompiledReport {
+  /** The raw event seam: one generator of report events per call. */
+  stream(data?: unknown): Generator<ReportEvent, void, undefined>;
+  readonly names: readonly string[];
+  readonly functions: readonly FunctionSignature[];
+  readonly paths: readonly QueryPath[];
+  /**
+   * Render this compiled report through one target. Resolves the target's
+   * output, whether the target renders synchronously or not; target shape
+   * problems throw synchronously as definition errors.
+   */
+  render<Out>(target: Target<string, Out>, data?: unknown): Promise<Awaited<Out>>;
+}
+
+/**
+ * One definition problem, structurally: the schema path it sits at, the
+ * offending author source when the problem came from compiling one, the whole
+ * located message (`validate()`'s string is exactly this field), and the
+ * engine's located diagnostic when one authenticated the fault — every
+ * problem keeps its own, offsets included, not only the first.
+ */
+export interface Problem {
+  readonly path: string;
+  readonly source?: string;
+  readonly message: string;
+  readonly diagnostic?: QuarioDiagnostic;
+}
+
+/**
+ * The plan: both readings of the one traversal, kept. `report` is the
+ * compiled report, or null while the document has problems; `problems` is the
+ * structured list `validate()` flattens to strings; `anchors` maps each
+ * compiled source's schema path to the anchors and group handles it reads —
+ * the unfiltered complement of `names`, which excludes them.
+ */
+export interface Plan {
+  readonly report: CompiledReport | null;
+  readonly problems: readonly Problem[];
+  readonly anchors: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface Quario {
+  /**
+   * Settles when this instance's license key verification completes;
+   * `{ licensed: false }` without a key. Never rejects.
+   */
+  readonly license: Promise<LicenseInfo>;
+  /** Compile a definition once; every target renders from it. */
+  report(schema: ReportSchema, functions?: FunctionRegistry): CompiledReport;
+  /**
+   * The one traversal, whole: compiled report (null on problems), structured
+   * problems, and per-node anchor sets — one descent per edit for a host that
+   * validates and renders in a loop.
+   */
+  plan(schema: unknown, functions?: FunctionRegistry): Plan;
+}
+
+/**
+ * Create a configured instance: host-level options (license key, query
+ * budgets).
+ */
+export function quario(options?: QuarioOptions): Quario;
+
+export function validate(schema: unknown, functions?: FunctionRegistry): string[];
+
+/**
+ * True when a caught value is one of the stack's located diagnostics —
+ * re-thrown by quario with an engine original behind it, or thrown by
+ * xprsn/sjabloon/padvinder directly. Authenticated by identity: an error
+ * merely shaped like a diagnostic does not pass.
+ */
+export function isDiagnostic(e: unknown): e is QuarioDiagnostic;
+
+/**
+ * Join a token stream to display text: literals verbatim, values through
+ * `display()`. Re-exported from sjabloon.
+ */
+export function text(tokens: readonly Token[]): string;
+
+/**
+ * Display text for one token value — the scalar rule `text()` joins with,
+ * re-exported from sjabloon so targets stringify exactly as the stream does.
+ * A valid `Date` renders as ISO 8601 UTC (`toISOString()`), deterministically
+ * across machines; an invalid `Date` stays `"Invalid Date"`; nullish displays
+ * empty; everything else is `String(value)`.
+ */
+export function display(value: unknown): string;
+
+/**
+ * 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 — reports `undefined` and joins to display text.
+ */
+export function typed(tokens: readonly Token[]): number | boolean | Date | undefined;
+
+/**
+ * Whether a band item's `role` names one of the report's own bands — its
+ * header, its footer, the `empty` band that replaces its body, or a page band —
+ * rather than a group instance's. Shipped so a consumer that needs the split
+ * does not restate the list. Page-band roles answer true although no walk emits
+ * one: the question is whose band a role names, not what a walk can hand over.
+ */
+export function isReportBand(role: string | undefined): boolean;