@quario/csv 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,65 +1,116 @@
-# Changelog
+# @quario/csv
 
-All notable changes to @quario/csv are documented in this file.
+## 0.8.0
 
-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).
+### Minor Changes
 
-## [Unreleased]
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
 
-## [0.7.0] - 2026-09-07
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
 
-### Changed
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+
+## 0.7.1
+
+### Patch Changes
+
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - quario@0.8.0
+
+## 0.7.0
+
+### Minor Changes
 
 - **Styled runs flatten to their joined text.** A cell value written as a list of
   styled runs writes the runs' text as one field. This target withdraws every
   style, and a run's is no different.
 
-## [0.6.0] - 2026-09-07
+## 0.6.0
 
-### Changed
+### Minor Changes
 
-- Requires quario ^0.6.0
+- Updated dependencies
+  - quario@0.6.0
 
-## [0.5.0] - 2026-09-05
+## 0.5.0
 
-### Added
+### Minor Changes
 
 - **Spans keep the record rectangular.** A cell covering several columns writes
   its value in the first field it covers and leaves the rest empty, so every
   record is the same width. This target reads no geometry, so there is nothing
   here for a merge to mean.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Changed
+### Minor Changes
 
-- Requires quario ^0.4.0
+- Updated dependencies
+  - quario@0.4.0
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Changed
+### Minor Changes
 
 - **A table total emits N records.** Each `total-row` is one record, as
   each data row is.
-
 - **`format` is unread.** Bare interpolations stay `1000` / ISO dates, as
   every other style is unread here.
-
 - **`page.margin` and report-header `height` are unread.** This target has
   no page to inset or pin on.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **A split is one record, its slots the fields.** Slots are values beside
   each other, which is what a record is. Slot widths go unread, as every width
   is here. Images stay unread too, but a slot holding one still writes an
   empty field, so the fields either side keep their positions.
-
-### Changed
-
 - **Display-text `Date`s join as ISO 8601 UTC.** A `Date` inside a mixed
   cell (literal text plus interpolation) joined through `String(date)`, so
   the field carried the host's timezone and locale. It now joins through the
@@ -67,9 +118,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   typed single-`Date` field has always used, so every `Date` in a CSV now
   reads the same way.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **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,

package/README.md

@@ -1,8 +1,8 @@
 # @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.
+definition to CSV records with typed fields. A bare number stays a number's decimal, and a Date
+stays ISO 8601 UTC. This target neutralizes text that would open as a spreadsheet formula.
 
 ## Install
 
@@ -11,7 +11,7 @@ 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
+browser-ready through any standards-based ESM bundler. The renderer returns a string. You
 encode the file.
 
 ## Quick start
@@ -54,15 +54,16 @@ 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.
+Any schema the other targets render works here unchanged. A CSV file has no pages, so this target
+ignores page bands. Interpolate the bare value, not a formatter, when you want a typed field.
+`{{ @.amount }}` writes `1000`, and `{{ currency(@.amount) }}` writes text.
 
 ## API
 
 ### `csv()`
 
-The target factory takes no options and returns the target you pass to `render`.
+The target factory takes no options and returns the target you pass to `render`. It refuses an argument rather than
+discarding one. It throws a `TypeError` if you give it one.
 `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.
 
@@ -75,7 +76,7 @@ The compiled report carries `stream` (the raw event generator), `names`, `functi
 `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
+Rendering is asynchronous and returns the loop between batches, so a large report never
 blocks the host. Render-time failures reject with located errors.
 
 ## Mapping
@@ -83,12 +84,14 @@ blocks the host. Render-time failures reject with located errors.
 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 records, 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.
+alone. Group boundaries add no records of their own, and this target ignores `break: "page"`
+and `reset: "page"`. This target paginates nothing, so it ignores `report-start.page` band
+closures.
 
-Each item takes one record with one field; a split takes one record with a field per slot, and a
-spanning cell writes empty fields for the columns it covers so positions hold. A report that is one
-table and no other bands has its column headers as record 1; any other band makes the file ragged.
+Each item takes one record with one field. A split takes one record with a field per slot, and a
+spanning cell writes empty fields for the columns it covers so positions hold. 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
 
@@ -97,25 +100,26 @@ number as ECMAScript ToString, a boolean as `true`/`false`, a `Date` as ISO 8601
 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
+**This target mangles display-text fields that would open as spreadsheet formulas.** 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.
+does not mangle. See
+[The CSV target](https://getquario.com/docs/diving-deeper/csv-target/#design-decisions).
 
 A hidden cell keeps its column slot as an empty field.
 
 ### Withdrawn, and the unread page bands
 
-`style`, column `width`, slot `width`, page columns and images are withdrawn: a record carries no
-presentation, no width and no page, so there is nothing here for any of them to resolve against. An
-image emits no record, though an image in a slot still writes its empty field. Page bands are the
-one unread declaration — this target never calls their closures, so an expression inside one is
-never evaluated and never raises here.
+This target withdraws `style`, column `width`, slot `width`, page columns and images. A record
+carries no presentation, no width and no page, so there is nothing here for any of them to
+resolve against. An image emits no record, though an image in a slot still writes its empty
+field. Page bands are the one unread declaration. This target never calls their closures, so an
+expression inside one never runs and never raises here.
 
 ### 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.
+RFC 4180. The line ending does not.
 
 ## Unlicensed marking
 
@@ -127,12 +131,23 @@ presence is normative. That a parser who stops before EOF will see it is best-ef
 
 Same schema and data produce an identical string.
 
+The full contract is [The CSV target](https://getquario.com/docs/diving-deeper/csv-target/),
+with each declaration's fate in the
+[support matrix](https://getquario.com/docs/reference/support-matrix/).
+
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare, and
+[`@quario/csv`](https://getquario.com/docs/reference/csv/) is this package's own API.
+
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+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:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/index.d.ts

@@ -4,5 +4,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").
+ *
+ * It takes no options, and an argument is a `TypeError` at the call rather
+ * than an argument quietly discarded.
  */
 export function csv(): Target<"csv", Promise<string>>;

package/lib/index.js

@@ -32,10 +32,20 @@ let field = (cell) => {
  * string (the host encodes the file). Rendering runs the engine's `walk`
  * driver over the handlers below, so large reports stay cooperative.
  *
+ * This target reads no host options, and refuses an argument rather than
+ * discarding one: a host writing `csv({ delimiter: ";" })` believes something
+ * about the output that is not true, and nothing later would tell them
+ * (`docs/adr/0072`). The rule the other targets state over a key set, this
+ * one states over the whole call. Nullish is absence here as everywhere, so
+ * `csv(config.options)` over a config carrying none is not a mistake.
+ *
+ * @param {...never} rest Nothing: an option is a definition error.
  * @returns {{name: "csv", compile: (stream: any) => (data?: any) => Promise<string>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
-export function csv() {
+export function csv(...rest) {
+  if (rest.some((option) => option != null))
+    throw TypeError("options: this target takes no options");
   return {
     name: "csv",
     compile: (stream) => async (data) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/csv",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The CSV render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -38,12 +38,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.7.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.7.0"
+    "quario": "^0.9.0"
   },
   "size-limit": [
     {