@quario/csv 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @quario/csv
 
+## 0.8.0
+
+### Minor Changes
+
+- **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.
+
+  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.
+
+  **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

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,8 +100,8 @@ 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. See
 [The CSV target](https://getquario.com/docs/diving-deeper/csv-target/#design-decisions).
@@ -107,16 +110,16 @@ 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
 
@@ -141,10 +144,10 @@ specification of what a report may declare, and
 
 ## 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.1",
+  "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.8.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.8.0"
+    "quario": "^0.9.0"
   },
   "size-limit": [
     {