@quario/csv 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to @quario/csv 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
+
+- **CSV records in render order.** A bare interpolation stays typed text (a
+  number's decimal, a Date as ISO 8601 UTC); everything else is display text,
+  then an apostrophe on formula-like cells, then RFC 4180 quoting. The
+  unlicensed marking is a trailing line, so record 1 stays the report's.

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

@@ -0,0 +1,136 @@
+# @quario/csv
+
+**The CSV render target for [quario](https://www.npmjs.com/package/quario).** Renders a report
+definition to CSV records with typed fields: a bare number stays a number's decimal, a Date
+stays ISO 8601 UTC, and text that would open as a spreadsheet formula is neutralized.
+
+## Install
+
+```bash
+npm install quario @quario/csv
+```
+
+The engine is a peer dependency, installed beside the target. ESM-only, Node 22+, and
+browser-ready through any standards-based ESM bundler. The renderer returns a string; you
+encode the file.
+
+## Quick start
+
+```js
+import { writeFileSync } from "node:fs";
+import { csv } from "@quario/csv";
+import { quario } from "quario";
+
+const schema = {
+  data: "$.orders[*]",
+  detail: {
+    columns: [
+      { header: "Product", value: "{{ @.product }}" },
+      { header: "Price", value: "{{ @.price }}" },
+    ],
+  },
+};
+
+const data = {
+  orders: [
+    { product: "Desk", price: 250 },
+    { product: "Chair", price: 120 },
+    { product: "Lamp", price: 40 },
+  ],
+};
+
+const report = quario().report(schema);
+const records = await report.render(csv(), data);
+
+writeFileSync("sales.csv", records);
+```
+
+A licensed render of that table-only report:
+
+```
+Product,Price
+Desk,250
+Chair,120
+Lamp,40
+```
+
+Any schema the other targets render works here unchanged. A CSV file has no pages, so page
+bands are ignored. Interpolate the bare value, not a formatter, when you want a typed field:
+`{{ @.amount }}` writes `1000`; `{{ currency(@.amount) }}` writes text.
+
+## API
+
+### `csv()`
+
+The target factory takes no options and returns the target you pass to `render`.
+`report()` compiles once and `report.render(csv(), data)` resolves the string. Compile at
+startup, render per request. Definition problems throw at `report()`, at compile time.
+
+```js
+const report = quario().report(schema, funcs);
+const records = await report.render(csv(), data);
+```
+
+The compiled report carries `stream` (the raw event generator), `names`, `functions`, and
+`paths`, like every quario report. Engine-level options (`query` budgets, the license key)
+live on the instance, and `q.license` settles with the verification result.
+
+Rendering is asynchronous and hands the loop back between batches, so a large report never
+blocks the host. Render-time failures reject with located errors.
+
+## Mapping
+
+The banded walk flattened as records in render order: report-header items, then per group
+instance its header items, nested content, and footer items, then the table's header record,
+data records, and total record, then report-footer items. Grouping exists as that order
+alone. Group boundaries add no records of their own, and `break: "page"` and `reset: "page"`
+are ignored. This target is unpaginated: `report-start.page` band closures are ignored.
+
+Each item takes one record with one field. A report that is one table and no other bands has
+its column headers as record 1; any other band makes the file ragged.
+
+### Typed fields
+
+A cell whose value is one bare interpolation writes its pre-stringify value as text: a finite
+number as ECMAScript ToString, a boolean as `true`/`false`, a `Date` as ISO 8601 UTC. Every
+other cell joins to display text with `text()`, then the injection guard, then RFC 4180
+quoting.
+
+**Display-text fields that would open as spreadsheet formulas are mangled.** A leading `=`,
+`+`, `-`, `@`, TAB, or CR gets an apostrophe. A consumer that parses the file back does not
+round-trip those fields. The XLSX target does the opposite: it writes an inert string and
+does not mangle.
+
+A hidden cell keeps its column slot as an empty field.
+
+### Unread
+
+`style`, column `width`, page columns, page bands, and images: nothing looks at them. An
+image emits no record.
+
+### Text shape
+
+No BOM. Records separated by LF, not CRLF. The string ends with a newline. Quoting follows
+RFC 4180; the line ending does not.
+
+## Unlicensed marking
+
+An unlicensed render writes the wording from `report-start.marking` as one trailing line, one
+field, through the same quote and guard as any field. A licensed render omits it. The line's
+presence is normative. That a parser who stops before EOF will see it is best-effort.
+
+## Determinism
+
+Same schema and data produce an identical string.
+
+## 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 once, on the instance; it is verified offline:
+
+```js
+const q = quario({ license: "quario_..." });
+await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
+```

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+import type { Target } from "quario";
+
+/**
+ * The CSV render target:
+ * `quario().report(schema).render(csv(), data)` resolves the records
+ * described in SCHEMA.md ("The CSV target").
+ */
+export function csv(): Target<"csv", Promise<string>>;

package/lib/index.js

@@ -0,0 +1,63 @@
+/**
+ * @quario/csv — the CSV render target: a pure consumer of the engine's
+ * public event stream, passed to a compiled report's `render`, flattening the
+ * banded walk onto records in render order. A cell that is one bare
+ * interpolation keeps a typed string (a number stays decimal, a Date ISO 8601
+ * UTC); every other cell is display text, then the formula-injection guard,
+ * then RFC 4180 quoting. Styles, widths, page bands, and images go unread.
+ * The unlicensed marking is a trailing line, so record 1 stays the report's.
+ */
+import { text, typed, walk } from "quario";
+
+/** Formula guard, then RFC 4180 quoting. Typed fields skip this.
+ *  @type {(s: string) => string} */
+let format = (s) => {
+  if (/^[=+\-@\t\r]/.test(s)) s = "'" + s;
+  return /[",\n\r]/.test(s) ? '"' + s.replaceAll('"', '""') + '"' : s;
+};
+
+/** @type {(cell: { tokens: any[] }) => string} */
+let field = (cell) => {
+  let value = typed(cell.tokens);
+  if (value === undefined) return format(text(cell.tokens));
+  return value instanceof Date ? value.toISOString() : String(value);
+};
+
+/**
+ * The CSV render target:
+ * `quario().report(schema).render(csv(), data)` resolves the records as a
+ * string (the host encodes the file). Rendering runs the engine's `walk`
+ * driver over the handlers below, so large reports stay cooperative.
+ *
+ * @returns {{name: "csv", compile: (stream: any) => (data?: any) => Promise<string>}}
+ *   The target (see SCHEMA.md, "Instances and targets").
+ */
+export function csv() {
+  return {
+    name: "csv",
+    compile: (stream) => async (data) => {
+      let out = "";
+      /** @type {string | undefined} */
+      let marking;
+      let record = (/** @type {any} */ event) => {
+        out += event.cells.map(field).join(",") + "\n";
+      };
+      await walk(stream(data), {
+        "report-start": (event) => {
+          if (event.marking) marking = event.marking;
+        },
+        item: (event) => {
+          out += field(event) + "\n";
+        },
+        "table-start": (event) => {
+          out +=
+            event.columns.map((/** @type {any} */ column) => field(column.header)).join(",") + "\n";
+        },
+        row: record,
+        "total-row": record,
+      });
+      if (marking) out += format(marking) + "\n";
+      return out;
+    },
+  };
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@quario/csv",
+  "version": "0.1.0",
+  "description": "The CSV render target for quario — in the makings, not yet released",
+  "homepage": "https://getquario.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/csv"
+  },
+  "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"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "quario": "^0.1.0",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "quario": "^0.1.0"
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "limit": "1 kB",
+      "ignore": [
+        "quario"
+      ]
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}