quario 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to quario are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-27
+
+### Added
+
+- **A compile-once report engine.** You hand it a JSON report definition and
+  data; it plans once and streams render events that every target consumes.
+  Text cells go through sjabloon, everything else through xprsn, rows through
+  padvinder. Unlicensed output carries a marking on the opening event; each
+  target only decides where that wording goes.

package/LICENSE

@@ -0,0 +1,219 @@
+# Quario License Agreement
+
+> **In short:** Quario is commercial software with visible source.
+> Evaluate it free for as long as you like. Evaluation output is
+> watermarked. Anything else needs a per-developer license, after
+> which deployment is unlimited and royalty-free. This summary is not
+> the license; the full terms below govern.
+
+Version 1.0, August 2026
+
+This agreement is between you and Webstronauts, trading as Quario,
+established in the Netherlands ("we", "us"), and governs the Software
+defined below.
+
+Quario is commercial software. Its packages ship with readable source
+code, but it is not open source. No rights are granted beyond those in
+this agreement.
+
+## 1. Definitions
+
+- The **Software** is any software we publish under the Quario name,
+  including the `quario` and `@quario/*` packages, except where a
+  product states its own terms. Each release states the edition of this
+  agreement that governs it.
+- **You** means the individual exercising rights under this agreement
+  and, where that individual acts for a company or other organization,
+  that organization. In that case the organization is the licensee, and
+  the rights and limits in this agreement apply to it as a whole.
+- An **Application** is software you create that incorporates the
+  Software and adds substantial functionality beyond it. A
+  licensee-operated service that embeds the Software and renders
+  reports for your End Users is an Application under this agreement,
+  even if it does little more than render.
+- A **Developer** is any individual (employee or contractor working on
+  your behalf) who writes or maintains code that uses the Software's
+  APIs, or who creates or maintains report definitions for use with the
+  Software. That includes people who never install or run the Software
+  themselves, when their definitions are rendered by a service that
+  embeds it.
+- A **Seat** is a paid license for one named Developer, purchased from
+  us or an authorized reseller.
+- **End Users** are people who interact with the Software only through
+  an Application: running it, viewing the reports it produces, or
+  supplying parameters or other input to existing report definitions
+  the Application provides. Creating or maintaining report definitions
+  makes someone a Developer. End Users do not purchase a license; their
+  rights come from section 5.
+
+## 2. Acceptance
+
+This file is our standing offer. Anyone who exercises the evaluation
+rights in section 3 accepts them, subject to their conditions. All
+other rights arise when Seats are purchased. Where a purchase is made
+for an organization, the person completing it confirms that they are
+authorized to accept this agreement on the organization's behalf, and
+acceptance covers the whole organization. If you do not accept this
+agreement, do not use the Software.
+
+## 3. Evaluation
+
+You may download, install, and use the Software free of charge to
+evaluate it: assessing whether it suits your purposes, and building
+prototypes or proofs of concept. Evaluation covers the full feature
+set, needs no key, and has no fixed time limit. The Software marks
+evaluation output as described in section 6.
+
+Evaluation is limited to assessment: you may not distribute any
+Application containing the Software, use the Software in live business
+operations, or expose it in services offered to third parties. The
+moment your use goes beyond evaluating the Software, it requires Seats
+under section 4.
+
+## 4. Developer licenses
+
+Any use of the Software beyond section 3 requires a Seat for every
+Developer, whether or not an Application has shipped. With those Seats
+in place:
+
+- Each licensed Developer may install and use the Software on any number
+  of machines for developing Applications.
+- Automated build, test, and CI systems do not consume Seats.
+- Seats are per named individual. They may be reassigned when a
+  Developer stops working with the Software, but not shared or pooled
+  between concurrently active Developers. Contractors' work for you is
+  covered by your Seats; work they do for other clients is not.
+
+## 5. Distribution and runtime
+
+With Seats under section 4 in place, you may deploy and operate your
+Applications yourself, and distribute the Software as an embedded part
+of them, **royalty-free**: no additional fees or per-deployment
+licenses are required for any number of servers, copies, or End Users.
+You may embed your license key in an Application and ship it at no
+charge, so section 6 does not mark that Application's output.
+
+For that purpose, we grant you the right to pass through to each End
+User, and to anyone who distributes or operates your Application on your
+behalf, a limited, non-exclusive, non-transferable right to execute the
+Software only as embedded in the Application. You must not permit them
+to extract the Software from the Application or use it to develop
+software of their own.
+
+If you operate a service that embeds the Software and renders reports
+for your End Users, that service is an Application under section 1. You
+may run it royalty-free under this section, and you may put your license
+key in it as in any Application. Calling applications that only request
+renders from it need not incorporate the Software. People who use those
+applications only as End Users under section 1 get the pass-through
+rights above.
+
+You may not:
+
+- distribute the Software on its own, or as part of a product whose
+  primary purpose is to provide report-engine, report-design, or
+  document-generation capability to third-party developers;
+- expose the Software's APIs to third parties as a development tool or
+  service that substitutes for those parties buying their own Seats. A
+  licensee-operated service that embeds the Software and renders for
+  your own End Users falls outside that ban;
+- fork, mirror, repackage, rename, or wrap the Software, or republish
+  it on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+For as long as this agreement is in force, you may not create any tool,
+library, product, or service that competes with the Software or any
+other Quario product, whether the competition is direct or indirect;
+this restriction does not survive termination. You may not remove or
+alter copyright or license notices in the Software. If your Application
+is itself a closed development product for third-party developers (OEM
+redistribution), contact us for separate terms.
+
+## 6. License keys and output marking
+
+The Software accepts a license key that evidences your Seats under
+section 4. Key checks run offline.
+
+Without a valid key, or with a key whose validity period does not cover
+the installed version's release date, the Software runs with its full
+feature set but marks its output as unlicensed. Using a key you are not
+entitled to is a material breach of this agreement.
+
+You may not remove, disable, or circumvent the key check or the output
+marking, or distribute anything that does.
+
+## 7. Term, updates, and perpetual fallback
+
+Seats are sold as an annual subscription. While the subscription is
+active, licensed Developers receive all Software versions we release,
+and support for the Software through our issue tracker and by email. We
+provide support with commercially reasonable effort; we do not guarantee
+specific response times.
+
+If the subscription lapses, your license to the versions released during
+your subscription is **perpetual, for the number of Seats held at the
+lapse**: up to that many Developers may keep using those versions, and
+your Applications may keep shipping them, forever, at no further cost.
+Versions released after the lapse require renewal. We encode this rule
+in purchased keys: a key remains valid for every version released
+during its validity period, with no end date.
+
+## 8. Source availability
+
+The Software's packages ship with readable source code so that you can
+review and debug what you run. Readable source does not grant extra
+rights: this agreement governs all use of the source, and you may
+publish the Software (modified or not) only as part of an Application
+under section 5.
+
+## 9. Ownership, trademarks, and feedback
+
+We license the Software; we retain all intellectual property rights in
+it. Report definitions, data, and output you create with the Software
+are yours. "Quario" and the Quario logo are our trademarks; this
+agreement grants no rights to use them beyond identifying the Software.
+If you send us feedback or suggestions, we may use them without
+obligation.
+
+## 10. Warranty and liability
+
+We provide the Software as is. To the fullest extent the law allows, we
+disclaim all warranties and conditions, express or implied, including
+merchantability, fitness for a particular purpose, and non-infringement.
+
+To the fullest extent the law allows: we are not liable for indirect or
+consequential damages, loss of profits, loss of data, or business
+interruption; and our total aggregate liability under this agreement is
+limited to the greater of EUR 100 and the fees you paid us in the
+twelve months preceding the event giving rise to the claim. These
+limitations do not apply where the damage results from the intent or
+deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
+management, or where mandatory law does not permit them.
+
+## 11. Termination and survival
+
+If you materially breach this agreement, we may terminate it by notice.
+If the breach can be remedied, we will first allow 30 days from that
+notice to remedy it, and termination takes effect only if the breach
+remains. On termination, the licenses granted here end.
+Perpetual-fallback rights under section 7 survive termination only if
+they arose from a lapse that predates the breach, and section 5
+survives with them to the extent needed to keep exercising them.
+Sections 8 through 12 survive any termination.
+
+## 12. General
+
+Dutch law governs this agreement. Disputes go to the competent court for
+our registered office. You may not assign this agreement without our
+consent, except to a successor of your whole business; we may assign it
+to a successor of ours. If a provision is unenforceable, the remainder
+stays in force. Failure to enforce a provision does not waive it. This
+agreement, together with your order for Seats, is the entire agreement
+about the Software, unless we agree otherwise in writing.
+
+---
+
+**Purchasing and contact:** <contact@getquario.com> ·
+<https://getquario.com>
+
+Copyright © 2026 Webstronauts. All rights reserved.

package/README.md

@@ -1 +1,222 @@
-quario — in the makings, not yet released.
+# quario
+
+**The report engine.** Turns a JSON report definition plus data into a stream of structured render
+events. Every render target ([`@quario/html`](https://www.npmjs.com/package/@quario/html),
+[`@quario/pdf`](https://www.npmjs.com/package/@quario/pdf),
+[`@quario/xlsx`](https://www.npmjs.com/package/@quario/xlsx),
+[`@quario/csv`](https://www.npmjs.com/package/@quario/csv), or your own) consumes that
+stream.
+
+The engine does not escape text, emit HTML, or format pages or cells. Install a target when you
+want output. Use this package when you want to _build_ a target, or to consume report structure
+as data.
+
+## Install
+
+```bash
+npm install quario
+```
+
+ESM-only, Node 22+. Dependencies: [xprsn](https://github.com/getquario/xprsn) (expressions),
+[sjabloon](https://github.com/getquario/sjabloon) (templates),
+[padvinder](https://github.com/getquario/padvinder) (JSONPath).
+
+## Quick start
+
+```js
+import { quario, text } from "quario";
+
+const schema = {
+  data: "$.orders[*]",
+  aggregates: { total: "sum:=@.price * @.qty" },
+  detail: [{ type: "text", value: "{{ @.product }} — {{ @.price * @.qty }}" }],
+  footer: [{ type: "text", value: "Total {{ $.total }}" }],
+};
+
+const report = quario().report(schema);
+
+for (const e of report.stream({ orders: [{ product: "Desk", price: 250, qty: 2 }] })) {
+  if (e.type === "item") console.log(e.role, text(e.tokens));
+}
+// detail       Desk — 500
+// report-footer Total 500
+```
+
+`report()` compiles the definition **once** into a tree of closures. You render the compiled
+report per dataset with `report.render(target, data)`, passing the target and its configuration
+at the call, so one compile serves any number of target configurations. Definition errors
+surface at compile time, so compile at startup and render in your request path.
+
+## API
+
+### `quario(options?)`
+
+Creates a configured instance with host-level controls: `{ query?, license? }`. Returns
+`{ report, license }`. `license` settles with this instance's key verification as
+`{ licensed, licensee?, id? }`.
+
+### `report(schema, functions?)`
+
+Compiles a report and returns the compiled report. `stream(data)` is the raw event generator.
+`render(target, data)` takes a self-naming `{ name, compile }` object from a target factory
+(e.g. `html()` from `@quario/html`) or your own.
+
+A render is async: quario awaits key verification before the target sees its first event. A
+malformed target throws at compile time, like any other definition error.
+
+The data pre-pass (select, filter, sort, aggregate) runs when you call the renderer, because a
+report header may interpolate a report aggregate. Event emission pulls on demand, so a consumer
+that stops early does not pay for the rest of the walk.
+
+The compiled report carries metadata:
+
+```js
+report.names; // free variable names the expressions read, excluding engine anchors
+report.functions; // registry function names the definition calls
+report.paths; // padvinder's deeply frozen dependency topology for the `data` query
+```
+
+Events arrive in render order: `report-start`, report `header` items, then either the `empty`
+items or the group/detail walk, then `footer` items, `report-end`. Group instances bracket their
+content with `group-start`/`group-end`; a table detail yields `table-start`, one `row` per visible
+row, an optional `total-row`, and `table-end`.
+
+| Event          | Carries                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| `report-start` | `params`, resolved report `aggregates`, optional `page` band closures, `columns`, `marking` |
+| `item`         | `role`, `tokens`, optional `style`, `run`                                                   |
+| `image`        | `role`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`          |
+| `group-start`  | `name`, `depth`, `key`, `aggregates`, optional `break`, `reset`, `columns`                  |
+| `group-end`    | `name`, `depth`                                                                             |
+| `table-start`  | `columns` (each `header`, optional `width`)                                                 |
+| `row`          | `cells`, optional `style`, `run`                                                            |
+| `total-row`    | `cells`                                                                                     |
+| `table-end`    | -                                                                                           |
+| `report-end`   | -                                                                                           |
+
+**Cells carry tokens.** A cell is `{ tokens, style? }`. Each token is either `{ literal }`
+(static template text, verbatim) or `{ value }` (one interpolation's _pre-format_ value, the
+expression result before any stringification). This is the typed seam: a cell whose template is `{{ @.amount }}` holds one value token with the
+number itself, so a spreadsheet consumer writes a real numeric cell. `Total: {{ @.amount }}` mixes
+a literal and a value, so the cell is text only.
+
+**Escaping is the consumer's job.** A target that embeds values in markup must escape them at its
+own edge.
+
+**`report-start.marking`** carries the evaluation wording when the render is unlicensed, or while
+verification is still settling. Licensed streams omit it. Targets place the marking; they do not
+author its wording. **`columns`** on `report-start` / `group-start` is the declared
+page column count when present. No shipped target honors it yet;
+xlsx never will.
+
+### `text(tokens)`
+
+Joins a token stream to display text: literals verbatim, values as `String(value ?? "")`, run
+styles ignored. Re-exported from sjabloon so consumers do not hand-roll the join.
+
+### `typed(tokens)`
+
+Exactly one value token holding a finite number, a boolean, or a valid `Date` keeps that
+pre-stringify value. Anything else, including a lone null, reports `undefined` and joins to
+display text. Spreadsheet consumers use this for real numeric cells;
+[`@quario/csv`](https://www.npmjs.com/package/@quario/csv) is the short form.
+
+### `walk(events, handlers)` / `breathe()`
+
+`walk` is the delivery driver every official target uses. Pass one render's event iterable and
+per-event handlers keyed by type; a missing handler ignores that event. It pulls on demand, hands
+the loop back between batches, and delivers the opening event before pulling a second, so a
+target can settle `report-start` (page bands, marking) there instead of draining the stream
+itself.
+
+`breathe()` is that hand-back alone. Await it between batches of a loop you own; `walk` already
+calls it for you.
+
+### `validate(schema, functions?)`
+
+Checks a definition without rendering it. Returns every problem as a path-prefixed string; an
+empty array means valid.
+
+```js
+validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
+// ['sort[0].dir: unknown sort direction "up"']
+```
+
+`report()` throws on the first problem instead. Validation and compilation share one traversal,
+so `validate()` can never disagree with what `report()` accepts.
+
+### `isDiagnostic(error)`
+
+True when a caught value is one of the stack's located errors: quario's own, or one thrown
+directly by xprsn, sjabloon, or padvinder. Authentication checks identity. An error that only
+matches the shape does not pass.
+
+Located errors name their band path and offending source while keeping their original type
+(`SyntaxError`, `TypeError`, `RangeError`). They carry `code`, `start`/`end` offsets, and (for
+query budget failures) `limit` and `actual`.
+
+```js
+try {
+  await renderer(data);
+} catch (e) {
+  if (isDiagnostic(e)) console.error("report problem:", e.message);
+  else throw e; // one of your own functions failed
+}
+```
+
+## The scope model
+
+| Anchor        | Is                                                                  |
+| ------------- | ------------------------------------------------------------------- |
+| `@`           | The current row. Unbound outside detail rows, so `@.x` throws there |
+| `$`           | The report root: `$.input`, `$.params`, and report aggregates       |
+| `<groupName>` | A named handle per enclosing group: `.key` plus its aggregates      |
+| `run.<name>`  | Running accumulator values on the current detail row                |
+
+Each anchor is a distinct object. Absent reads are `null`, so `x == null` holds for a missing
+field; reading _through_ a null base still throws, so use `?.`.
+
+## Options
+
+```js
+quario({ query: { maxNodes: 10_000, maxDepth: 64, maxResults: 1_000 } }).report(schema, functions);
+```
+
+`query` bounds the JSONPath data selection. Hosts set budgets through this API argument;
+definitions do not carry it. Failures are located at `data`, keep their `RangeError` type, and
+carry `code`, `limit`, and `actual`. Every render starts with fresh counters.
+
+## Writing a render target
+
+Read the stream through the public API. Do not reach for engine internals. A complete, tested
+Markdown target lives in the repository at `example/markdown.js` in about 70 lines. The built-in
+targets are written against the same public API.
+
+Two rules a target owes its users: escape or neutralize every `value` token at your own edge, and
+map the style vocabulary to your own formatting model rather than expecting CSS.
+
+The stream is additive. The walk driver skips any event you register no handler for, so a target
+that ignores a newer event (for example, `example/markdown.js` has none for `image`) keeps rendering
+when a schema uses one.
+
+A target that runs a loop of its own can `await breathe()` between batches to hand the event loop
+back, as `walk` does for the targets that drive through it.
+
+## Content Security Policy
+
+Expressions and templates compile to closures. There is no string-to-code path anywhere in this
+package, so it runs under a script policy that omits `unsafe-eval`. The test suite enforces it
+under Node's `--disallow-code-generation-from-strings` flag, a source scan, and a Playwright
+harness that loads the published files under a strict CSP.
+
+## License
+
+Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
+licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+
+Pass your license key in the options; it is verified offline:
+
+```js
+const q = quario({ license: "quario_..." });
+await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
+```