@quario/xlsx 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @quario/xlsx
 
+## 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.
+
+- **`meta` is now read once, at the factory call.** It was read inside the render, so a host that
+  mutated its options object between renders got a different workbook from the same configured
+  target. The documented behaviour was always the factory call. If you were mutating an options
+  object to change the document properties, build a new target instead.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -13,12 +13,12 @@ can keep working in, not a grid of strings.
 npm install quario @quario/xlsx
 ```
 
-[exceljs](https://github.com/exceljs/exceljs) comes along as a dependency; the engine is a peer, installed beside it. ESM-only,
+[exceljs](https://github.com/exceljs/exceljs) arrives as a dependency. The engine is a peer, installed beside it. ESM-only,
 Node 22+, and browser-ready through any standards-based ESM bundler. The renderer returns bytes,
 so you decide where they go.
 
-> The writer is an implementation detail: exceljs is confined to a single internal module, so it
-> can be swapped behind this exact API without a breaking change.
+> The writer is an implementation detail. This package confines exceljs to a single internal
+> module, so a later version can swap it behind this exact API without a breaking change.
 
 ## Quick start
 
@@ -33,11 +33,11 @@ const bytes = await report.render(xlsx({ meta: { title: "Sales 2026" } }), data)
 writeFileSync("sales.xlsx", bytes);
 ```
 
-Any schema the other targets render works here unchanged. A spreadsheet has no pages, so page bands
-are ignored.
+Any schema the other targets render works here unchanged. A spreadsheet has no pages, so this
+target ignores page bands.
 
 One tip that changes the output a lot: **interpolate the bare value, not a formatter.** A cell
-written `{{ @.amount }}` becomes a real numeric cell; `{{ currency(@.amount) }}` becomes text,
+written `{{ @.amount }}` becomes a real numeric cell. `{{ currency(@.amount) }}` becomes text,
 because the formatter already turned the number into a string. Let the spreadsheet do the
 formatting it is good at.
 
@@ -45,8 +45,9 @@ formatting it is good at.
 
 ### `xlsx(options?)`
 
-The target factory: it takes this target's host options and returns the target you pass to
-`render`. `report()` compiles once and `report.render(xlsx(options), data)` resolves the
+The target factory takes this target's host options, validates them at the call, and returns the
+target you pass to `render`. The factory refuses an option it does not know. It throws a `TypeError` at the call for an unknown key. It throws one also for a key with a value of the wrong type. It also reads `meta` at the call. One configured target
+therefore always writes the same document. `report()` compiles once and `report.render(xlsx(options), data)` resolves the
 workbook bytes. Compile at startup, render per request. Definition problems throw at
 `report()`, at compile time.
 
@@ -59,7 +60,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 blocks the
+Rendering is asynchronous and returns the loop between batches, so a large report never blocks the
 host. Render-time failures reject with located errors.
 
 ### Options
@@ -74,12 +75,12 @@ host. Render-time failures reject with located errors.
 
 One worksheet, named `Report`, with the banded walk flattened onto it as rows in render order:
 report-header items, then per group instance its header items, nested content, and footer items,
-then the table's header row, data rows, and total rows, then report-footer items. Grouping shows up
-as that order alone. Group boundaries add no rows of their own, and `break: "page"` and
-`reset: "page"` are ignored, as are `page.margin` and a report header's `height`.
+then the table's header row, data rows, and total rows, then report-footer items. Grouping exists
+as that order alone. Group boundaries add no rows of their own. This target ignores `break: "page"`,
+`reset: "page"`, `page.margin`, and a report header's `height`.
 
-Each item takes one row with its cell in the first column, unmerged; a split takes one row with its
-slots as the cells across it (slot widths withdrawn, a slot rendering nothing an empty cell), and a
+Each item takes one row with its cell in the first column, unmerged. A split takes one row with its
+slots as the cells across it (slot widths withdrawn, a slot rendering nothing an empty cell). A
 spanning header or total cell is a merged range. Two band roles carry an
 omakase default that the author's own style always overrides: report-header items render bold at
 size 14, group-header items render bold.
@@ -99,9 +100,9 @@ A hidden cell keeps its column slot as an empty cell that retains its style.
 
 `format` writes a number format so the grid presents what the other targets do. `date` builds
 its pattern from the cell's `form` (`dd mmm yyyy` undeclared), with month and weekday names
-spelled by the reader's application; the number kinds build theirs from the declaration's
-fraction-digit count — an undeclared `number` is `#,##0.00`, `percent` is `0.00%`,
-`{ "kind": "number", "digits": 3 }` is `#,##0.000` — and `currency` is the code the cell wears
+spelled by the reader's application. The number kinds build theirs from the declaration's
+fraction-digit count: an undeclared `number` is `#,##0.00`, `percent` is `0.00%`, and
+`{ "kind": "number", "digits": 3 }` is `#,##0.000`. `currency` is the code the cell wears
 — its own `currency` when it declares one, else the instance's — over that currency's minor
 units unless `digits` says otherwise: `"USD"#,##0.00`, `"JPY"#,##0`, `"BHD"#,##0.000`. A kind
 on the wrong type, or a code the engine cannot read, writes no format.
@@ -119,18 +120,18 @@ every target alike.
 
 | Declaration                                            | Maps to                                                                                                                              |
 | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `family`                                               | `sans` → Calibri, `serif` → Times New Roman, `mono` → Courier New; any other name passes through for the host application to resolve |
+| `family`                                               | `sans` → Calibri, `serif` → Times New Roman, `mono` → Courier New. Any other name passes through for the host application to resolve |
 | `size`, `bold`, `italic`, `underline`, `strikethrough` | Font (`strikethrough` → writer's `strike`)                                                                                           |
 | `color`, `background`                                  | Font colour, solid fill                                                                                                              |
 | `align`                                                | Horizontal alignment                                                                                                                 |
-| `valign`                                               | Vertical alignment; undeclared writes nothing, so the spreadsheet application keeps its own default                                  |
-| `border*`                                              | Cell borders (`solid` → `thin`, `dashed`, `dotted`; width approximated); a row's borders arrive on its cells already                 |
+| `valign`                                               | Vertical alignment. Undeclared writes nothing, so the spreadsheet application keeps its own default                                  |
+| `border*`                                              | Cell borders (`solid` → `thin`, `dashed`, `dotted`, with width approximated). A row's borders arrive on its cells already            |
 | `format`, `currency`                                   | A number format — see [Number formats](#number-formats)                                                                              |
 | `uppercase`, `padding*`, `spaceBefore`, `spaceAfter`   | Not read: a grid has no text-transform, no cell inset of its own, and no flow                                                        |
 
 Style blocks layer row under cell, as everywhere in quario, with the report default outermost.
-Every cell is written at 10 points unless something declares otherwise, and a cell whose display
-contains a newline wraps.
+This target writes every cell at 10 points unless something declares otherwise, and a cell whose
+display contains a newline wraps.
 
 ### Freeze
 
@@ -148,20 +149,20 @@ table for a share to be a share of.
 ### Page columns are withdrawn
 
 A [page column](https://getquario.com/docs/reference/support-matrix/#page-and-pagination) count
-sizes and splits nothing here, and will not change, as `break: "page"` is ignored. Page columns
+sizes and splits nothing here, and will not change, as this target ignores `break: "page"`. Page columns
 are strips of a page, and this target has no page to strip.
 
 ## Unlicensed marking
 
 An unlicensed render writes the wording from `report-start.marking` twice: as a styled banner in
 row 1 (so the whole report, frozen view included, sits one row lower than a licensed render), and
-as the workbook's description property. Both are normative; banner styling is best-effort. A
+as the workbook's description property. Both are normative. Banner styling is best-effort. A
 licensed render has no banner and no description marking.
 
 ## Determinism
 
-The document model is deterministic: the workbook's dates are pinned rather than stamped, and
-`meta` is opt-in. The **bytes** are not. The writer stamps archive entries with the packing time.
+The document model is deterministic. This target pins the workbook's dates rather than stamping
+them, and `meta` is opt-in. The **bytes** are not. The writer stamps archive entries with the packing time.
 Compare extracted content, not digests.
 
 The full contract is [The XLSX target](https://getquario.com/docs/diving-deeper/xlsx-target/),
@@ -177,10 +178,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

@@ -7,7 +7,12 @@ export interface XlsxMeta {
   subject?: string;
 }
 
-/** Host controls, taken at the factory call. */
+/**
+ * Host controls, taken and validated at the factory call: an option this
+ * target does not understand, or one of the wrong type, throws a `TypeError`
+ * there rather than costing the host the option in silence. `meta` is read
+ * there too, so one configured target always writes the same document.
+ */
 export interface XlsxOptions {
   meta?: XlsxMeta;
 }

package/lib/index.js

@@ -15,7 +15,7 @@
  * the packing time. Byte-for-byte output is a goal for the writer that will
  * replace `workbook.js`.
  */
-import { walk } from "quario";
+import { hostMeta, hostOptions, walk } from "quario";
 import { field } from "./cell.js";
 import { merge as under } from "./style.js";
 import { append, create, embed, freeze, mark, place, save, sheet, span } from "./workbook.js";
@@ -66,14 +66,22 @@ let BANNER = { bold: true, background: "#fff2cc" };
  * runs the engine's `walk` driver over the handlers below, so large reports
  * stay cooperative.
  *
+ * Host controls are taken and validated here, at the factory call: an option
+ * this target does not understand, or one of the wrong type, throws where the
+ * host wrote it rather than costing them the option in silence
+ * (`docs/adr/0072`). `meta` is also *read* here, so a render is reproducible
+ * from the call that configured it.
+ *
  * @param {XlsxOptions} [options] Host controls (see SCHEMA.md, "The XLSX target").
  * @returns {{name: "xlsx", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function xlsx(options) {
+  hostOptions(options, ["meta"], "options");
+  let meta = hostMeta(options?.meta, "options.meta");
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
   let compile = (stream) => async (data) => {
-    let workbook = create(options?.meta);
+    let workbook = create(meta);
     let worksheet = sheet(workbook);
     // The first table anchors the frozen header row. It is global to the
     // sheet, so later tables never move it.

package/lib/workbook.js

@@ -10,12 +10,16 @@
 import ExcelJS from "exceljs";
 
 // Host metadata keys as the workbook properties they become -- `author` is the
-// only one exceljs names differently.
+// only one exceljs names differently, and this mapping is all this target owns
+// of `meta`. The contract itself (which properties, each a string, never a
+// date) is the engine's `hostMeta`, checked at the factory call, so nothing
+// here restates it: a present property is a string, and a nullish one is a
+// property the host did not write.
 /** @type {(workbook: any, meta: any) => void} */
 let describe = (workbook, meta) => {
-  if (typeof meta.title === "string") workbook.title = meta.title;
-  if (typeof meta.author === "string") workbook.creator = meta.author;
-  if (typeof meta.subject === "string") workbook.subject = meta.subject;
+  if (meta.title != null) workbook.title = meta.title;
+  if (meta.author != null) workbook.creator = meta.author;
+  if (meta.subject != null) workbook.subject = meta.subject;
 };
 
 // A fresh workbook. Never the current time: a timestamp would make the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "The spreadsheet render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -42,12 +42,12 @@
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/node": "^22.20.1",
-    "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": [
     {