@jackens/nnn 2026.2.26 → 2026.4.11

package/nnn.d.ts

@@ -128,6 +128,24 @@ export declare const s: {
     <N extends Node>(node: N, ...args1: HArgs1[]): N;
     (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
 };
+/**
+ * Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
+ *
+ * Equivalent to: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
+ *
+ * @param id
+ *
+ * The ID of the symbol to reference (without the `#` prefix).
+ *
+ * @param args
+ *
+ * Additional arguments passed to the outer `<svg>` element.
+ *
+ * @returns
+ *
+ * An `SVGSVGElement` containing a `<use>` element.
+ */
+export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
  * Checks whether an object has the specified key as its own property.
  *
@@ -253,40 +271,18 @@ export declare const monokai: CRoot;
  * An array of {@link HArgs1} elements suitable for rendering with {@link h}.
  */
 export declare const nanolightTs: (code: string) => HArgs1[];
-/**
- * A map from value constructors (or `null`/`undefined`) to escape functions.
- *
- * Used by {@link escapeValues} and {@link newEscape}.
- */
-export type EscapeMap = Map<unknown, (value?: unknown) => string>;
-/**
- * Escapes an array of values using the provided escape map.
- *
- * @param escapeMap
- *
- * A map where keys are constructors (e.g., `String`, `Number`) and values are escape functions.
- *
- * @param values
- *
- * The array of values to escape.
- *
- * @returns
- *
- * An array of escaped strings.
- */
-export declare const escapeValues: (escapeMap: EscapeMap, values: unknown[]) => string[];
 /**
  * Creates a tag function for escaping interpolated values in template literals.
  *
- * @param escapeMap
+ * @param escapeFn
  *
- * A map where keys are constructors and values are escape functions.
+ * A function that takes a value and returns its escaped string representation.
  *
  * @returns
  *
  * A tag function that escapes interpolated values using the provided escape map.
  */
-export declare const newEscape: (escapeMap: EscapeMap) => (template: TemplateStringsArray, ...values: unknown[]) => string;
+export declare const newEscape: (escapeFn: (value: any) => string) => (template: TemplateStringsArray, ...values: unknown[]) => string;
 /**
  * Creates a function that returns the appropriate noun form based on a numeric value using `Intl.PluralRules`.
  *
@@ -403,24 +399,6 @@ export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T,
  * - `height` (optional, default `1`): number of vertical cells the element spans.
  */
 export declare const rwd: (root: CRoot, selector: string, cellWidthPx: number, cellHeightPx: number, ...specs: [number, number?, number?][]) => void;
-/**
- * Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
- *
- * Equivalent to: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
- *
- * @param id
- *
- * The ID of the symbol to reference (without the `#` prefix).
- *
- * @param args
- *
- * Additional arguments passed to the outer `<svg>` element.
- *
- * @returns
- *
- * An `SVGSVGElement` containing a `<use>` element.
- */
-export declare const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
  * Generates a UUID v1 (time-based) identifier.
  *

package/nnn.js

@@ -66,66 +66,64 @@ var csvParse = (csv, separator = ",") => {
 var isRecord = (arg) => typeof arg === "object" && arg != null && !isArray(arg);
 
 // src/nnn/h.ts
-var _h = (namespaceUri) => {
+var XLINK_NS = "http://www.w3.org/1999/xlink";
+var _h = (namespaceUri, tagOrNode, ...args) => {
   const createElement = namespaceUri == null ? (tag) => document.createElement(tag) : (tag) => document.createElementNS(namespaceUri, tag);
-  const h = (tagOrNode, ...args) => {
-    const node = isString(tagOrNode) ? createElement(tagOrNode) : tagOrNode;
-    args.forEach((arg) => {
-      let child = null;
-      if (arg instanceof Node) {
-        child = arg;
-      } else if (isArray(arg)) {
-        child = h(...arg);
-      } else if (isRecord(arg)) {
-        for (const name in arg) {
-          const value = arg[name];
-          if (name[0] === "$") {
-            const name1 = name.slice(1);
-            if (isRecord(value)) {
-              node[name1] ??= {};
-              Object.assign(node[name1], value);
-            } else {
-              node[name1] = value;
-            }
-          } else if (node instanceof Element) {
-            const indexOfColon = name.indexOf(":");
-            if (indexOfColon >= 0) {
-              const nsKey = name.slice(0, indexOfColon);
-              if (nsKey === "xlink") {
-                const ns = "http://www.w3.org/1999/xlink";
-                const basename = name.slice(indexOfColon + 1);
-                if (value === true) {
-                  node.setAttributeNS(ns, basename, "");
-                } else if (value === false) {
-                  node.removeAttributeNS(ns, basename);
-                } else {
-                  node.setAttributeNS(ns, basename, "" + value);
-                }
-              }
-            } else {
+  const node = isString(tagOrNode) ? createElement(tagOrNode) : tagOrNode;
+  args.forEach((arg) => {
+    let child = null;
+    if (arg instanceof Node) {
+      child = arg;
+    } else if (isArray(arg)) {
+      child = _h(namespaceUri, ...arg);
+    } else if (isRecord(arg)) {
+      for (const name in arg) {
+        const value = arg[name];
+        if (name[0] === "$") {
+          const name1 = name.slice(1);
+          if (isRecord(value)) {
+            node[name1] ??= {};
+            Object.assign(node[name1], value);
+          } else {
+            node[name1] = value;
+          }
+        } else if (node instanceof Element) {
+          const indexOfColon = name.indexOf(":");
+          if (indexOfColon >= 0) {
+            const nsKey = name.slice(0, indexOfColon);
+            if (nsKey === "xlink") {
+              const basename = name.slice(indexOfColon + 1);
               if (value === true) {
-                node.setAttribute(name, "");
+                node.setAttributeNS(XLINK_NS, basename, "");
               } else if (value === false) {
-                node.removeAttribute(name);
+                node.removeAttributeNS(XLINK_NS, basename);
               } else {
-                node.setAttribute(name, "" + value);
+                node.setAttributeNS(XLINK_NS, basename, "" + value);
               }
             }
+          } else {
+            if (value === true) {
+              node.setAttribute(name, "");
+            } else if (value === false) {
+              node.removeAttribute(name);
+            } else {
+              node.setAttribute(name, "" + value);
+            }
           }
         }
-      } else if (isString(arg) || isNumber(arg)) {
-        child = document.createTextNode(arg);
-      }
-      if (child != null) {
-        node.appendChild(child);
       }
-    });
-    return node;
-  };
-  return h;
+    } else if (isString(arg) || isNumber(arg)) {
+      child = document.createTextNode(arg);
+    }
+    if (child != null) {
+      node.appendChild(child);
+    }
+  });
+  return node;
 };
-var h = /* @__PURE__ */ _h();
-var s = /* @__PURE__ */ _h("http://www.w3.org/2000/svg");
+var h = _h.bind(null, null);
+var s = _h.bind(null, "http://www.w3.org/2000/svg");
+var svgUse = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
 
 // src/nnn/fixPlTypography.ts
 var TAGS_TO_SKIP = ["IFRAME", "NOSCRIPT", "PRE", "SCRIPT", "STYLE", "TEXTAREA"];
@@ -298,8 +296,7 @@ var PUNCTUATION = "punctuation";
 var STRING = "string";
 var nanolightTs = /* @__PURE__ */ newTokenizer((chunk, name) => name != null ? ["span", { class: name }, chunk] : chunk, [COMMENT, /\/\*.*?\*\//s], [COMMENT, /(?<!\\)\/\/.*?(?=\n)/], [STRING, /".*?"/], [STRING, /'.*?'/], [STRING, /`.*?`/s], [STRING, /\/[^\s]*[^\\]\/[dgimsuvy]*/], [NUMBER, /0b[01_]+/], [NUMBER, /0o[01234567_]+/], [NUMBER, /0x[\dabcdef_]+/], [NUMBER, /\d[\d_]*(\.[\d_]+)?(e[+-]?[\d_]+)?/], [OPERATOR, "!"], [OPERATOR, "!="], [OPERATOR, "!=="], [OPERATOR, "%"], [OPERATOR, "%="], [OPERATOR, "&&"], [OPERATOR, "&&="], [OPERATOR, "&"], [OPERATOR, "&="], [OPERATOR, "*"], [OPERATOR, "**"], [OPERATOR, "**="], [OPERATOR, "*="], [OPERATOR, "+"], [OPERATOR, "++"], [OPERATOR, "+="], [OPERATOR, "-"], [OPERATOR, "--"], [OPERATOR, "-="], [OPERATOR, "..."], [OPERATOR, "/"], [OPERATOR, "/="], [OPERATOR, ":"], [OPERATOR, "<"], [OPERATOR, "<<"], [OPERATOR, "<<="], [OPERATOR, "<="], [OPERATOR, "="], [OPERATOR, "=="], [OPERATOR, "==="], [OPERATOR, "=>"], [OPERATOR, ">"], [OPERATOR, ">="], [OPERATOR, ">>"], [OPERATOR, ">>="], [OPERATOR, ">>>"], [OPERATOR, ">>>="], [OPERATOR, "?"], [OPERATOR, "?"], [OPERATOR, "??"], [OPERATOR, "??="], [OPERATOR, "^"], [OPERATOR, "^="], [OPERATOR, "|"], [OPERATOR, "|="], [OPERATOR, "||"], [OPERATOR, "||="], [OPERATOR, "~"], [OPERATOR, "~="], [OPERATOR, /(?<=\s):/], [PUNCTUATION, "("], [PUNCTUATION, ")"], [PUNCTUATION, ","], [PUNCTUATION, "."], [PUNCTUATION, ":"], [PUNCTUATION, ";"], [PUNCTUATION, "?."], [PUNCTUATION, "["], [PUNCTUATION, "]"], [PUNCTUATION, "{"], [PUNCTUATION, "}"], [KEYWORD_1, "as"], [KEYWORD_1, "async"], [KEYWORD_1, "await"], [KEYWORD_1, "break"], [KEYWORD_1, "case"], [KEYWORD_1, "catch"], [KEYWORD_1, "class"], [KEYWORD_1, "const"], [KEYWORD_1, "continue"], [KEYWORD_1, "debugger"], [KEYWORD_1, "default"], [KEYWORD_1, "delete"], [KEYWORD_1, "do"], [KEYWORD_1, "else"], [KEYWORD_1, "export"], [KEYWORD_1, "extends"], [KEYWORD_1, "finally"], [KEYWORD_1, "for"], [KEYWORD_1, "from"], [KEYWORD_1, "function"], [KEYWORD_1, "function*"], [KEYWORD_1, "goto"], [KEYWORD_1, "if"], [KEYWORD_1, "import"], [KEYWORD_1, "in"], [KEYWORD_1, "instanceof"], [KEYWORD_1, "is"], [KEYWORD_1, "keyof"], [KEYWORD_1, "let"], [KEYWORD_1, "new"], [KEYWORD_1, "of"], [KEYWORD_1, "package"], [KEYWORD_1, "return"], [KEYWORD_1, "super"], [KEYWORD_1, "switch"], [KEYWORD_1, "this"], [KEYWORD_1, "throw"], [KEYWORD_1, "try"], [KEYWORD_1, "type"], [KEYWORD_1, "typeof"], [KEYWORD_1, "var"], [KEYWORD_1, "void"], [KEYWORD_1, "while"], [KEYWORD_1, "with"], [KEYWORD_1, "yield"], [KEYWORD_1, "yield*"], [KEYWORD_2, "false"], [KEYWORD_2, "Infinity"], [KEYWORD_2, "NaN"], [KEYWORD_2, "null"], [KEYWORD_2, "true"], [KEYWORD_2, "undefined"], [KEYWORD_3, "any"], [KEYWORD_3, "bigint"], [KEYWORD_3, "boolean"], [KEYWORD_3, "eval"], [KEYWORD_3, "number"], [KEYWORD_3, "string"], [KEYWORD_3, "symbol"], [KEYWORD_3, "unknown"], [IDENTIFIER_1, /[\p{Lu}_$][\p{Lu}\d_$]*/u], [IDENTIFIER_2, /[\p{L}_$][\p{L}\d_$]*(?=[(`])/u], [IDENTIFIER_3, /\p{Lu}[\p{L}\d_$]*/u], [IDENTIFIER_4, /[\p{L}_$][\p{L}\d_$]*/u]);
 // src/nnn/newEscape.ts
-var escapeValues = (escapeMap, values) => values.map((value) => (value == null ? escapeMap.get(value) : escapeMap.get(value?.constructor))?.(value) ?? "");
-var newEscape = (escapeMap) => (template, ...values) => String.raw(template, ...escapeValues(escapeMap, values));
+var newEscape = (escapeFn) => (template, ...values) => String.raw(template, ...values.map(escapeFn));
 // src/nnn/newNounForm.ts
 var PLURAL_RULES = {};
 var newNounForm = (locale, forms) => (value) => forms[(PLURAL_RULES[locale] ??= new Intl.PluralRules(locale)).select(value)] ?? forms.other ?? "";
@@ -352,8 +349,6 @@ var rwd = (root, selector, cellWidthPx, cellHeightPx, ...specs) => {
     node.height = `${cellHeightPx * height}px`;
   }
 };
-// src/nnn/svgUse.ts
-var svgUse = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
 // src/nnn/uuidV1.ts
 var ZEROS = /* @__PURE__ */ "0".repeat(16);
 var counter = 0;
@@ -384,7 +379,6 @@ export {
   hasOwn,
   h,
   fixPlTypography,
-  escapeValues,
   csvParse,
   c
 };

package/package.json

@@ -44,5 +44,5 @@
   "name": "@jackens/nnn",
   "type": "module",
   "types": "nnn.d.ts",
-  "version": "2026.2.26"
+  "version": "2026.4.11"
 }

package/readme.md

@@ -1,6 +1,6 @@
 # nnn
 
-A collection of Jackens’ JavaScript helper utilities (version: `2026.2.26`).
+A collection of Jackens’ JavaScript helper utilities (version: `2026.4.11`).
 
 ## Installation
 
@@ -20,7 +20,6 @@ npm i @jackens/nnn
 import {
   c,
   csvParse,
-  escapeValues,
   fixPlTypography,
   h,
   hasOwn,
@@ -50,12 +49,10 @@ import {
 
 - [`CNode`](#CNode): Represents a CSS rule node for the [`c`](#c) helper. Keys are CSS properties or nested selectors.
 - [`CRoot`](#CRoot): Represents the root CSS object for the [`c`](#c) helper. Keys are top-level selectors or at-rules.
-- [`EscapeMap`](#EscapeMap): A map from value constructors (or `null`/`undefined`) to escape functions.
 - [`HArgs`](#HArgs): Tuple argument type for the [`h`](#h) and [`s`](#s) helpers.
 - [`HArgs1`](#HArgs1): Single argument type for the [`h`](#h) and [`s`](#s) helpers.
 - [`c`](#c): A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
 - [`csvParse`](#csvParse): Parses a CSV string into a two-dimensional array of strings.
-- [`escapeValues`](#escapeValues): Escapes an array of values using the provided escape map.
 - [`fixPlTypography`](#fixPlTypography): Applies Polish-specific typographic corrections to a DOM subtree.
 - [`h`](#h): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also [`s`](#s)).
 - [`hasOwn`](#hasOwn): Checks whether an object has the specified key as its own property.
@@ -97,16 +94,6 @@ type CRoot = Record<PropertyKey, CNode>;
 
 Represents the root CSS object for the [`c`](#c) helper. Keys are top-level selectors or at-rules.
 
-### EscapeMap
-
-```ts
-type EscapeMap = Map<unknown, (value?: unknown) => string>;
-```
-
-A map from value constructors (or `null`/`undefined`) to escape functions.
-
-Used by [`escapeValues`](#escapeValues) and [`newEscape`](#newEscape).
-
 ### HArgs
 
 ```ts
@@ -162,8 +149,8 @@ const actual1 = c({
     color: 'red',
     margin: 1,
     '.c': { margin: 2, padding: 2 },
-    padding: 1
-  }
+    padding: 1,
+  },
 })
 
 const expected1 = `
@@ -187,9 +174,9 @@ const actual2 = c({
       color: 'red',
       margin: 1,
       '.c': { margin: 2, padding: 2 },
-      padding: 1
-    }
-  }
+      padding: 1,
+    },
+  },
 })
 
 const expected2 = `
@@ -214,26 +201,26 @@ const actual3 = c({
     src$$2: "url(otf/jackens.otf) format('opentype')," +
       "url(svg/jackens.svg) format('svg')",
     font_weight: 'normal',
-    'font-style': 'normal'
+    'font-style': 'normal',
   },
   '@font-face$$2': {
     font_family: 'C64',
-    src: 'url(fonts/C64_Pro_Mono-STYLE.woff)'
+    src: 'url(fonts/C64_Pro_Mono-STYLE.woff)',
   },
   '@keyframes spin': {
     '0%': { transform: 'rotate(0deg)' },
-    '100%': { transform: 'rotate(360deg)' }
+    '100%': { transform: 'rotate(360deg)' },
   },
   div: {
     border: 'solid red 1px',
     '.c1': { 'background-color': '#000' },
     ' .c1': { background_color: 'black' },
-    '.c2': { backgroundColor: 'rgb(0,0,0)' }
+    '.c2': { backgroundColor: 'rgb(0,0,0)' },
   },
   '@media(min-width:200px)': {
     div: { margin: 0, padding: 0 },
-    span: { color: '#000' }
-  }
+    span: { color: '#000' },
+  },
 })
 
 const expected3 = `
@@ -285,10 +272,10 @@ const actual4 = c({
     '.b,.c': {
       margin: 1,
       '.d': {
-        margin: 2
-      }
-    }
-  }
+        margin: 2,
+      },
+    },
+  },
 })
 
 const expected4 = `
@@ -305,9 +292,9 @@ const actual5 = c({
   '.b,.c': {
     margin: 1,
     '.d': {
-      margin: 2
-    }
-  }
+      margin: 2,
+    },
+  },
 })
 
 const expected5 = `
@@ -324,9 +311,9 @@ const actual6 = c({
   '.a,.b': {
     margin: 1,
     '.c,.d': {
-      margin: 2
-    }
-  }
+      margin: 2,
+    },
+  },
 })
 
 const expected6 = `
@@ -377,30 +364,10 @@ yyy",zzz
 expect(csvParse(text)).to.deep.equal([
   ['aaa\n"aaa"\naaa', 'bbb', 'ccc,ccc'],
   ['xxx,xxx', 'yyy\nyyy', 'zzz'],
-  [' 42 ', '42', ' 17']
+  [' 42 ', '42', ' 17'],
 ])
 ```
 
-### escapeValues
-
-```ts
-const escapeValues: (escapeMap: EscapeMap, values: unknown[]) => string[];
-```
-
-Escapes an array of values using the provided escape map.
-
-#### escapeMap
-
-A map where keys are constructors (e.g., `String`, `Number`) and values are escape functions.
-
-#### values
-
-The array of values to escape.
-
-#### Returns
-
-An array of escaped strings.
-
 ### fixPlTypography
 
 ```ts
@@ -421,13 +388,18 @@ except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA
 #### Usage Examples
 
 ```ts
-const p = h('p', 'Pchnąć w tę łódź jeża lub ośm skrzyń fig (zob. https://pl.wikipedia.org/wiki/Pangram).')
+const p = h('p',
+  'Pchnąć w tę łódź jeża lub ośm skrzyń fig (zob. https://pl.wikipedia.org/wiki/Pangram).',
+  ['br'],
+  ['b', 'Zażółć gęślą jaźń.'],
+)
 
 fixPlTypography(p)
 
 expect(p.innerHTML).to.deep.equal(
   'Pchnąć <span style="white-space:nowrap">w </span>tę łódź jeża lub ośm skrzyń fig ' +
-  '(zob. https://\u200Bpl.\u200Bwikipedia.\u200Borg/\u200Bwiki/\u200BPangram).')
+  '(zob. https://\u200Bpl.\u200Bwikipedia.\u200Borg/\u200Bwiki/\u200BPangram).' +
+  '<br><b>Zażółć gęślą jaźń.</b>')
 ```
 
 ### h
@@ -522,6 +494,19 @@ expect(div.key).to.deep.equal({ one: 1 })
 h(div, { $key: { two: 2 } })
 
 expect(div.key).to.deep.equal({ one: 1, two: 2 })
+
+const elemWithClass = h('div', { class: 'test' })
+
+expect(elemWithClass.getAttribute('class')).to.equal('test')
+
+const elemWithText = h('div', 'initial')
+
+h(elemWithText, ' more')
+expect(elemWithText.outerHTML).to.equal('<div>initial more</div>')
+
+const elemWithNested = h('div', ['span', 'hello'], ['b', 'world'])
+
+expect(elemWithNested.outerHTML).to.equal('<div><span>hello</span><b>world</b></div>')
 ```
 
 ### hasOwn
@@ -768,10 +753,10 @@ The parsed value with handler substitutions applied.
 const handlers = {
   $add: (a: number, b: number) => a + b,
   $hello: (name: string) => `Hello ${name}!`,
-  $foo: () => 'bar'
+  $foo: () => 'bar',
 }
 
-const actual = jsOnParse(handlers, `[
+const actual1 = jsOnParse(handlers, `[
   {
     "$add": [1, 2]
   },
@@ -795,23 +780,33 @@ const actual = jsOnParse(handlers, `[
   }
 ]`)
 
-const expected = [
+expect(actual1).to.deep.equal([
   3,
   'Hello World!',
   {
     nested: 'Hello nested World!',
     one: 1,
-    two: 2
+    two: 2,
   },
   'bar',
   {
     $foo: ['The parent object does not have exactly one property!'],
     one: 1,
-    two: 2
-  }
-]
+    two: 2,
+  },
+])
+
+const actual2 = jsOnParse({ $notFunc: 'handler not being a function' } as any, '{"$notFunc": [1, 2]}')
 
-expect(actual).to.deep.equal(expected)
+expect(actual2).to.deep.equal({ $notFunc: [1, 2] })
+
+const actual3 = jsOnParse(handlers, '{"$unknown_handler_key": [1, 2]}')
+
+expect(actual3).to.deep.equal({ $unknown_handler_key: [1, 2] })
+
+const actual4 = jsOnParse(handlers, '{"$add": {"not": "array"}}')
+
+expect(actual4).to.deep.equal({ $add: { not: 'array' } })
 ```
 
 ### monokai
@@ -862,21 +857,21 @@ expect(nanolightTs(codeJs)).to.deep.equal([
   ['span', { class: 'string' }, "'42'"],
   ['span', { class: 'punctuation' }, ']'],
   ' ',
-  ['span', { class: 'comment' }, '/* 42 */']
+  ['span', { class: 'comment' }, '/* 42 */'],
 ])
 ```
 
 ### newEscape
 
 ```ts
-const newEscape: (escapeMap: EscapeMap) => (template: TemplateStringsArray, ...values: unknown[]) => string;
+const newEscape: (escapeFn: (value: any) => string) => (template: TemplateStringsArray, ...values: unknown[]) => string;
 ```
 
 Creates a tag function for escaping interpolated values in template literals.
 
-#### escapeMap
+#### escapeFn
 
-A map where keys are constructors and values are escape functions.
+A function that takes a value and returns its escaped string representation.
 
 #### Returns
 
@@ -885,27 +880,30 @@ A tag function that escapes interpolated values using the provided escape map.
 #### Usage Examples
 
 ```ts
-const escapeMap: EscapeMap = new Map([
-  [null, () => 'NULL'],
-  [undefined, () => 'NULL'],
-  [Array, (values: unknown[]) => escapeValues(escapeMap, values).join(', ')],
-  [Boolean, (value: boolean) => `b'${+value}'`],
-  [Date, (value: Date) => `'${value.toISOString().replace(/^(.+)T(.+)\..*$/, '$1 $2')}'`],
-  [Number, (value: number) => `${value}`],
-  [String, (value: string) => `'${value.replace(/'/g, "''")}'`]
-])
-
-const sql = newEscape(escapeMap)
+const escapeFn = (value: any): string =>
+  isArray(value)
+    ? value.map(escapeFn).join(', ')
+    : value === true || value === false
+      ? `b'${+value}'`
+      : value instanceof Date
+        ? `'${value.toISOString().replace(/^(.+)T(.+)\..*$/, '$1 $2')}'`
+        : isFiniteNumber(value)
+          ? `${value}`
+          : isString(value)
+            ? `'${value.replace(/'/g, "''")}'`
+            : 'NULL'
+
+const sql = newEscape(escapeFn)
 
 const actual = sql`
   SELECT *
   FROM table_name
-  WHERE column_name IN (${[true, null, undefined, 42, '42', "4'2", new Date(323325000000)]})`
+  WHERE column_name IN (${[true, null, undefined, NaN, Infinity, 42, '42', "4'2", /42/, new Date(323325000000)]})`
 
 const expected = `
   SELECT *
   FROM table_name
-  WHERE column_name IN (b'1', NULL, NULL, 42, '42', '4''2', '1980-03-31 04:30:00')`
+  WHERE column_name IN (b'1', NULL, NULL, NULL, NULL, 42, '42', '4''2', NULL, '1980-03-31 04:30:00')`
 
 expect(actual).to.equal(expected)
 ```
@@ -957,6 +955,13 @@ expect(car(0)).to.equal('cars')
 expect(car(1)).to.equal('car')
 expect(car(17)).to.equal('cars')
 expect(car(42)).to.equal('cars')
+
+const empty = newNounForm('en', {})
+
+expect(empty(0)).to.equal('')
+expect(empty(1)).to.equal('')
+expect(empty(17)).to.equal('')
+expect(empty(42)).to.equal('')
 ```
 
 ### newTokenizer
@@ -989,6 +994,99 @@ A tokenizer function that accepts a code string and returns an array of decorate
 2. Among matches at the same position, the longer one wins.
 3. Among matches of the same position and length, the one defined earlier wins.
 
+#### Usage Examples
+
+```ts
+const tokenizer1 = newTokenizer(
+  (chunk, metadata) => ({ chunk, metadata }),
+  ['keyword', /\b(if|else|for)\b/],
+  ['string', /"[^"]*"/],
+)
+const result1 = tokenizer1('if "hello" else "world"')
+
+expect(result1).to.deep.equal([
+  { chunk: 'if', metadata: 'keyword' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: '"hello"', metadata: 'string' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: 'else', metadata: 'keyword' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: '"world"', metadata: 'string' },
+])
+
+const tokenizer2 = newTokenizer(
+  (chunk, metadata) => `${metadata}:${chunk}`,
+  ['tag', 'BEGIN'],
+  ['end', 'END'],
+)
+const result2 = tokenizer2('aBEGINbENDc')
+
+expect(result2).to.deep.equal(['undefined:a', 'tag:BEGIN', 'undefined:b', 'end:END', 'undefined:c'])
+
+const tokenizer3 = newTokenizer(
+  (chunk) => chunk,
+  ['test', /test/],
+)
+const result3 = tokenizer3('')
+
+expect(result3).to.deep.equal([])
+
+const tokenizer4 = newTokenizer(
+  (chunk, metadata) => ({ chunk, metadata }),
+  ['start', /^test/],
+)
+const result4 = tokenizer4('test here')
+
+expect(result4).to.deep.equal([
+  { chunk: 'test', metadata: 'start' },
+  { chunk: ' here', metadata: undefined },
+])
+
+const tokenizer5 = newTokenizer(
+  (chunk, metadata) => metadata,
+  ['later', /x/],
+  ['earlier', /y/],
+)
+const result5 = tokenizer5('yx')
+
+expect(result5).to.deep.equal(['earlier', 'later'])
+
+const tokenizer6 = newTokenizer(
+  (chunk) => chunk,
+  ['short', 'a'],
+  ['long', 'abc'],
+)
+const result6 = tokenizer6('abc')
+
+expect(result6).to.deep.equal(['abc'])
+
+const tokenizer7 = newTokenizer(
+  (chunk) => chunk,
+  ['empty', ''],
+  ['word', /\w+/],
+)
+const result7 = tokenizer7('hello')
+
+expect(result7).to.deep.equal(['hello'])
+
+const tokenizer8 = newTokenizer(
+  (chunk) => chunk,
+  ['test', /xyz/],
+)
+const result8 = tokenizer8('abc')
+
+expect(result8).to.deep.equal(['abc'])
+
+const tokenizer9 = newTokenizer(
+  (chunk, metadata) => metadata,
+  ['a', 'a'],
+  ['b', 'b'],
+)
+const result9 = tokenizer9('aabb')
+
+expect(result9).to.deep.equal(['a', 'a', 'b', 'b'])
+```
+
 ### omit
 
 ```ts
@@ -1085,45 +1183,45 @@ An array of breakpoint specifications, each a tuple of:
 ```ts
 const style: CRoot = {
   body: {
-    margin: 0
+    margin: 0,
   },
   '.r6': {
     border: 'solid red 1px',
     '.no-border': {
-      border: 'none'
-    }
-  }
+      border: 'none',
+    },
+  },
 }
 
 rwd(style, '.r6', 200, 50, [6], [3], [1, 1, 2])
 
 expect(style).to.deep.equal({
   body: {
-    margin: 0
+    margin: 0,
   },
   '.r6': {
     border: 'solid red 1px',
     '.no-border': {
-      border: 'none'
+      border: 'none',
     },
     boxSizing: 'border-box',
     display: 'block',
     float: 'left',
     width: '100%',
-    height: '100px'
+    height: '100px',
   },
   '@media(min-width:600px)': {
     '.r6': {
       width: 'calc(100% / 3)',
-      height: '50px'
-    }
+      height: '50px',
+    },
   },
   '@media(min-width:1200px)': {
     '.r6': {
       width: 'calc(50% / 3)',
-      height: '50px'
-    }
-  }
+      height: '50px',
+    },
+  },
 })
 ```
 
@@ -1158,6 +1256,30 @@ Additional arguments processed as follows:
 
 The created or modified `SVGElement`.
 
+#### Usage Examples
+
+```ts
+const svg = s('svg')
+
+s(svg, { 'xlink:href': true })
+expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).to.equal('')
+
+const svg2 = s('svg')
+
+s(svg2, { 'xlink:href': false })
+expect(svg2.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).to.be.null
+
+const svg3 = s('svg')
+
+s(svg3, { 'xlink:href': 'http://example.com' })
+expect(svg3.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).to.equal('http://example.com')
+
+const svg4 = s('svg')
+
+s(svg4, { 'xlink:title': 42 })
+expect(svg4.getAttributeNS('http://www.w3.org/1999/xlink', 'title')).to.equal('42')
+```
+
 ### svgUse
 
 ```ts
@@ -1180,6 +1302,49 @@ Additional arguments passed to the outer `<svg>` element.
 
 An `SVGSVGElement` containing a `<use>` element.
 
+#### Usage Examples
+
+```ts
+const XLINK_NS = 'http://www.w3.org/1999/xlink'
+
+const svg = svgUse('icon-home')
+
+expect(svg.tagName).to.equal('SVG')
+expect(svg.children.length).to.equal(1)
+
+const useElement = svg.children[0]
+
+expect(useElement.tagName).to.equal('USE')
+expect(useElement.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-home')
+
+const svgWithViewBox = svgUse('icon-star', { viewBox: '0 0 24 24' })
+
+expect(svgWithViewBox.getAttribute('viewBox')).to.equal('0 0 24 24')
+
+const useViewBox = svgWithViewBox.children[0]
+
+expect(useViewBox.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-star')
+
+const svgWithClass = svgUse('icon-menu', { class: 'icon-btn' })
+
+expect(svgWithClass.getAttribute('class')).to.equal('icon-btn')
+expect(svgWithClass.children.length).to.equal(1)
+
+const useClass = svgWithClass.children[0]
+
+expect(useClass.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-menu')
+
+const svgWithMultipleAttrs = svgUse('icon-settings', { width: 24, height: 24, class: 'icon' })
+
+expect(svgWithMultipleAttrs.getAttribute('width')).to.equal('24')
+expect(svgWithMultipleAttrs.getAttribute('height')).to.equal('24')
+expect(svgWithMultipleAttrs.getAttribute('class')).to.equal('icon')
+
+const useMultiple = svgWithMultipleAttrs.children[0]
+
+expect(useMultiple.getAttributeNS(XLINK_NS, 'href')).to.equal('#icon-settings')
+```
+
 ### uuidV1
 
 ```ts
@@ -1282,40 +1447,40 @@ vivify(ref).one.two[3][4]
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, []]
-  }
+    two: [undefined, undefined, undefined, []],
+  },
 })
 
 vivify(ref).one.two[3][4] = 5
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, [undefined, undefined, undefined, undefined, 5]]
-  }
+    two: [undefined, undefined, undefined, [undefined, undefined, undefined, undefined, 5]],
+  },
 })
 
 vivify(ref).one.two[3].length = 1
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, [undefined]]
-  }
+    two: [undefined, undefined, undefined, [undefined]],
+  },
 })
 
 vivify(ref).one.two[3] = 4
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, 4]
-  }
+    two: [undefined, undefined, undefined, 4],
+  },
 })
 
 expect(vivify(ref).one.two.length).to.equal(4)
 
 expect(ref).to.deep.equal({
   one: {
-    two: [undefined, undefined, undefined, 4]
-  }
+    two: [undefined, undefined, undefined, 4],
+  },
 })
 
 vivify(ref).one.two = 3