@quario/docx 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @quario/docx
 
+## 0.1.1
+
+### Patch 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.
+
+- Updated dependencies
+  - quario@0.9.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -11,7 +11,7 @@ npm install quario @quario/docx
 ```
 
 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 resolves a `Uint8Array`; you
+browser-ready through any standards-based ESM bundler. The renderer resolves a `Uint8Array`. You
 write the file.
 
 ## Quick start
@@ -39,8 +39,8 @@ writeFileSync("orders.docx", bytes);
 
 ## Options
 
-Both are optional, and both are validated at the factory call — an unknown option, or one of the
-wrong type, throws there rather than at the first render.
+Both are optional. The factory call validates both: an unknown option, or one of the wrong type,
+throws there rather than at the first render.
 
 ```js
 docx({
@@ -56,25 +56,25 @@ docx({
 
 ## What it renders
 
-A report's bands become paragraphs; a table detail becomes a **real Word table** carrying the
+A report's bands become paragraphs. A table detail becomes a **real Word table** carrying the
 author's column shares as a fixed grid, with `span` as `gridSpan` and a header row that repeats
-after every page break. A split is a borderless one-row table, and an image is an inline picture at its natural size, capped at the text
-column, carrying its `alt` as the drawing's description.
+after every page break. A split is a borderless one-row table. An image is an inline picture at
+its natural size, capped at the text column, carrying its `alt` as the drawing's description.
 
 The grouping becomes the **navigation pane**: a group header's first item takes `Heading{depth+1}`
 from this package's own `styles.xml`, so no theme typography leaks in. Everything a report declares
-is direct formatting on the runs and paragraphs that wear it — `Normal` stays empty, because a look
+is direct formatting on the runs and paragraphs that wear it. `Normal` stays empty, because a look
 that depends on a style lookup is a look three readers may resolve three ways.
 
 Page bands become a section's header and footer. A bare `{{ page.number }}` or `{{ page.total }}`
-becomes a live `PAGE` / `NUMPAGES` field the reader's own application recomputes; anything computed
-from them is frozen at the value the render saw. A group's `reset: "page"` opens a section that
+becomes a live `PAGE` / `NUMPAGES` field the reader's own application recomputes. Anything computed
+from them freezes at the value the render saw. A group's `reset: "page"` opens a section that
 restarts the numbering, and `break: "page"` starts the instance on a fresh page.
 
 ## Determinism
 
-Two renders of one report are byte-identical, on **every supported runtime**: `fflate` is pure
-JavaScript, so its deflate output does not vary by engine. Every entry in the package is stamped
+Two renders of one report are byte-identical, on **every supported runtime**. `fflate` is pure
+JavaScript, so its deflate output does not vary by engine. The package stamps every entry
 1980-01-01 and nothing in the document carries a clock, so a digest over the bytes is a fair test.
 
 ## Documentation
@@ -87,10 +87,10 @@ of a declaration.
 
 ## 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

@@ -18,7 +18,11 @@ export interface DocxMeta {
   subject?: string;
 }
 
-/** Host controls, taken and validated 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.
+ */
 export interface DocxOptions {
   page?: DocxPage;
   meta?: DocxMeta;

package/lib/index.js

@@ -11,7 +11,7 @@
  * `furniture.js` for the parts a page band becomes, `styles.js` for the base
  * every part inherits, and `text.js` for the runs all of them are made of.
  */
-import { walk } from "quario";
+import { hostMeta, hostOptions, walk } from "quario";
 import { bodyOf } from "./body.js";
 import { DOCUMENT_NS, furnish } from "./furniture.js";
 import { STYLES } from "./stylepart.js";
@@ -29,44 +29,6 @@ const WML = "application/vnd.openxmlformats-officedocument.wordprocessingml";
 // own default, and what the page bands will be laid against.
 const FURNITURE = 720;
 
-/** @type {(msg: string) => never} */
-let err = (msg) => {
-  throw Error(msg);
-};
-
-// Split from `object` below rather than inlined: the three terms together
-// breach the complexity budget `npm run fallow` holds this package to.
-/** @type {(value: any) => boolean} */
-let plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-
-/** @type {(value: any, at: string) => any} */
-let object = (value, at) => {
-  // oxlint-disable-next-line no-unused-expressions
-  value === undefined || plain(value) || err(at + ": expected an object");
-  return value;
-};
-
-/** @type {(value: any, keys: string[], at: string) => void} */
-let only = (value, keys, at) => {
-  for (let key in value) if (!keys.includes(key)) err(at + ': unknown option "' + key + '"');
-};
-
-// The three document properties a host may write.
-let PROPERTIES = ["title", "author", "subject"];
-
-// The document properties, validated: strings, and never a date. What a host
-// cannot write is what keeps a render deterministic -- `core.xml` is the one
-// part with a slot for a clock, and it has none of them.
-/** @type {(meta: any) => any} */
-let metaOf = (meta) => {
-  object(meta, "options.meta");
-  only(meta, PROPERTIES, "options.meta");
-  for (let key in meta)
-    // oxlint-disable-next-line no-unused-expressions
-    typeof meta[key] === "string" || err("options.meta." + key + ": expected a string");
-  return meta;
-};
-
 /**
  * One section. The child order is the schema's and Word is strict about it:
  * the part references, then `type`, the geometry, `pgNumType`, `cols`, and
@@ -191,15 +153,20 @@ let parts = (body, meta, furniture, rels) => ({
  * bytes described in SCHEMA.md ("The DOCX target"). Options are taken and
  * validated at the factory call.
  *
- * @param {any} [options] Host controls: `page` and `meta`.
+ * The options are described once, in the hand-written public declarations,
+ * and read back here -- a second copy in JSDoc is a copy that drifts.
+ * @import { DocxOptions } from './index.d.ts'
+ *
+ * @param {DocxOptions} [options] Host controls (see SCHEMA.md, "The DOCX target").
  * @returns {{name: "docx", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function docx(options) {
-  object(options, "options");
-  only(options, ["page", "meta"], "options");
-  let page = object(options?.page, "options.page");
-  let meta = metaOf(options?.meta);
+  hostOptions(options, ["page", "meta"], "options");
+  // Closed here rather than in `pageBox`, for the reason the layout package
+  // gives at the same call: the surface elements share that function.
+  let page = hostOptions(options?.page, ["size", "margin"], "options.page");
+  let meta = hostMeta(options?.meta, "options.meta");
   // The size fails here rather than at the first render: a host wrote it, so
   // a host hears about it where it was written. The margin is validated again
   // per render, because the document may be the one declaring it.

package/lib/page.js

@@ -25,7 +25,7 @@ let SIZES = /** @type {Record<string, [number, number]>} */ ({
 
 /** @type {(msg: string) => never} */
 let err = (msg) => {
-  throw Error(msg);
+  throw TypeError(msg);
 };
 
 /** @type {(value: number) => boolean} */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/docx",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The Word render target for quario — a flow target: real Word tables, a navigable outline, live page-number fields",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -41,12 +41,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": [
     {