@jackens/nnn 2023.9.18 → 2023.9.23

package/nnn.js

@@ -1,5 +1,27 @@
+/* eslint-disable no-console */
+
+export const _test = {}
+export const _version = '2023.9.23'
+
+/**
+ * ```ts
+ * export type EscapeMap = Map<any, (value?: any) => string>;
+ * ```
+ */
+
 /**
  * @typedef {Map<any, (value?: any) => string>} EscapeMap
+ *
+ * The type of arguments of the `escapeValues` and `escape` helpers.
+ */
+
+/**
+ * ```ts
+ * export type HArgs = [
+ *   string | Node,
+ *   ...(Record<string, any> | null | undefined | Node | string | number | HArgs)[]
+ * ];
+ * ```
  */
 
 /**
@@ -7,21 +29,84 @@
  *   string | Node,
  *   ...(Record<string, any> | null | undefined | Node | string | number | HArgs)[]
  * ]} HArgs
+ *
+ * The type of arguments of the `h` and `s` helpers.
+ */
+
+/**
+ * ```ts
+ * export type JcssNode = {
+ *   [attributeOrSelector: string]: string | number | JcssNode;
+ * };
+ * ```
  */
 
 /**
  * @typedef {{
  *   [attributeOrSelector: string]: string | number | JcssNode;
  * }} JcssNode
+ *
+ * The type of arguments of the `jcss` helper.
+ */
+
+/**
+ * ```ts
+ * export type JcssRoot = Record<string, JcssNode>;
+ * ```
  */
 
 /**
  * @typedef {Record<string, JcssNode>} JcssRoot
+ *
+ * The type of arguments of the `jcss` helper.
  */
 
 const _COLORS = ['#e22', '#e73', '#fc3', '#ad4', '#4d9', '#3be', '#45d', '#c3e']
 
 /**
+ * ```ts
+ * export function chartable(options?: {
+ *   bottom?: number;
+ *   gapX?: number;
+ *   gapY?: number;
+ *   headerColumn?: boolean;
+ *   headerRow?: boolean;
+ *   id?: string;
+ *   left?: number;
+ *   maxY?: number;
+ *   right?: number;
+ *   singleScale?: boolean;
+ *   table?: HTMLTableElement;
+ *   title?: string;
+ *   top?: number;
+ *   xLabels?: string[];
+ *   zLabels?: string[];
+ *   zxY?: number[][];
+ * }): SVGSVGElement;
+ * ```
+ */
+
+/**
+ * A helper for creating a chart based on a table (conf. <https://jackens.github.io/nnn/chartable/>).
+ *
+ * Options:
+ * - `bottom`: bottom padding (for X axis labels)
+ * - `gapX`: X axis spacing
+ * - `gapY`: Y axis spacing
+ * - `headerColumn`: flag indicating that `table` has a header column (with X axis labels)
+ * - `headerRow`: flag indicating that `table` has a header row (with data series labels)
+ * - `id`: chart id
+ * - `left`: left padding (for data series labels)
+ * - `maxY`: number of Y axis lines
+ * - `right`: right padding (for data series labels)
+ * - `singleScale`: flag to force single scale
+ * - `table`: `HTMLTableElement` to extract data, data series labels and X axis labels
+ * - `title`: chart title
+ * - `top`: top padding (for the title)
+ * - `xLabels`: X axis labels
+ * - `zLabels`: data series labels
+ * - `zxY`: chart data
+ *
  * @param {{
  *   bottom?: number;
  *   gapX?: number;
@@ -211,6 +296,15 @@ export const chartable = ({
   )
 }
 
+/**
+ * ```ts
+ * export function eq(x: any, y: any): boolean;
+ * ```
+ */
+
+/**
+ * A helper that checks equality of the given arguments.
+ */
 export const eq = /** @returns {boolean} */ (/** @type {any} */ x, /** @type {any} */ y) => {
   if (x === y) {
     return true
@@ -253,12 +347,93 @@ export const eq = /** @returns {boolean} */ (/** @type {any} */ x, /** @type {an
   return false
 }
 
+_test.eq = () => {
+  console.assert(eq(true, true))
+  console.assert(eq(NaN, NaN))
+  console.assert(!eq(null, undefined))
+  console.assert(eq(42, 42))
+  // eslint-disable-next-line no-new-wrappers
+  console.assert(eq(42, new Number(42)))
+  console.assert(eq(42, Number(42)))
+  // eslint-disable-next-line no-new-wrappers
+  console.assert(eq(new Number(42), Number(42)))
+  console.assert(!eq(42, '42'))
+  console.assert(eq('42', '42'))
+  // eslint-disable-next-line no-new-wrappers
+  console.assert(eq('42', new String('42')))
+  console.assert(eq('42', String('42')))
+  // eslint-disable-next-line no-new-wrappers
+  console.assert(eq(String('42'), new String('42')))
+  console.assert(eq(/42/, /42/))
+  console.assert(!eq(/42/, /42/g))
+  console.assert(eq(new Date(42), new Date(42)))
+  console.assert(!eq(new Date(), new Date(42)))
+  console.assert(eq({ j: '42', c: 42 }, { c: 42, j: '42' }))
+  console.assert(eq([42, '42'], [42, '42']))
+  console.assert(eq(new Set(['42', 42]), new Set([42, '42'])))
+  console.assert(!eq(new Set(['42', 42]), new Set([42])))
+  console.assert(!eq(new Set([42, undefined]), new Set([42])))
+  console.assert(eq(
+    new Map([[{ j: 42 }, { J: '42' }], [{ c: 42 }, { C: '42' }]]),
+    new Map([[{ c: 42 }, { C: '42' }], [{ j: 42 }, { J: '42' }]])
+  ))
+  console.assert(!eq(
+    new Map([[{ j: 42 }, { J: '42' }], [{ c: 42 }, { C: '42' }]]),
+    new Map([[{ j: '42' }, { J: 42 }], [{ c: '42' }, { C: 42 }]])
+  ))
+}
+
+/**
+ * ```ts
+ * export function escape(escapeMap: EscapeMap, template: TemplateStringsArray, ...values: any[]): string;
+ * ```
+ */
+
+/**
+ * A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
+ */
 export const escape = (
   /** @type {EscapeMap}            */ escapeMap,
   /** @type {TemplateStringsArray} */ template,
   /** @type {any[]}                */ ...values
 ) => String.raw(template, ...escapeValues(escapeMap, values))
 
+_test.escape = () => {
+  // @ts-expect-error
+  const /** @type {EscapeMap} */ escapeMap = new Map([
+    [undefined, () => 'NULL'],
+    [Array, (/** @type {any[]} */ values) => escapeValues(escapeMap, values).join(', ')],
+    [Boolean, (/** @type {boolean} */ value) => `b'${+value}'`],
+    [Date, (/** @type {Date} */ value) => `'${value.toISOString().replace(/^(.+)T(.+)\..*$/, '$1 $2')}'`],
+    [Number, (/** @type {number} */ value) => `${value}`],
+    [String, (/** @type {string} */ value) => `'${value.replace(/'/g, "''")}'`]
+  ])
+
+  // @ts-expect-error
+  const sql = escape.bind(null, escapeMap)
+
+  const actual = sql`
+    SELECT *
+    FROM table_name
+    WHERE column_name IN (${[true, null, undefined, 42, '42', "4'2", /42/, new Date(323325e6)]})`
+
+  const expected = `
+    SELECT *
+    FROM table_name
+    WHERE column_name IN (b'1', NULL, NULL, 42, '42', '4''2', NULL, '1980-03-31 04:30:00')`
+
+  console.assert(actual === expected)
+}
+
+/**
+ * ```ts
+ * export function escapeValues(escapeMap: EscapeMap, values: any[]): string[];
+ * ```
+ */
+
+/**
+ * A generic helper for escaping `values` by given `escapeMap`.
+ */
 export const escapeValues = (
   /** @type {EscapeMap} */ escapeMap,
   /** @type {any[]}     */ values
@@ -266,6 +441,15 @@ export const escapeValues = (
 
 const _TAGS_TO_SKIP = { IFRAME: 1, NOSCRIPT: 1, PRE: 1, SCRIPT: 1, STYLE: 1, TEXTAREA: 1 }
 
+/**
+ * ```ts
+ * export function fixTypography(node: Node): void;
+ * ```
+ */
+
+/**
+ * A helper that implements typographic corrections specific to Polish typography.
+ */
 export const fixTypography = (/** @type {Node} */ node) => {
   const /** @type {Node[]} */ queue = [node]
 
@@ -306,6 +490,25 @@ export const fixTypography = (/** @type {Node} */ node) => {
   }
 }
 
+_test.fixTypography = () => {
+  const p = h('p', 'Pchnąć w tę łódź jeża lub ośm skrzyń fig (zob. https://pl.wikipedia.org/wiki/Pangram).')
+
+  fixTypography(p)
+
+  console.assert(p.innerHTML ===
+    'Pchnąć <span style="white-space:nowrap">w </span>tę łódź jeża lub ośm skrzyń fig ' +
+    '(zob. https://\u200Bpl.\u200Bwikipedia.\u200Borg/\u200Bwiki/\u200BPangram).')
+}
+
+/**
+ * ```ts
+ * export function get(defaultValue: any, ref: any, ...keys: (string | number | symbol)[]): any;
+ * ```
+ */
+
+/**
+ * A convenient helper for getting values of nested objects.
+ */
 export const get = (
   /** @type {any} */ defaultValue,
   /** @type {any} */ ref,
@@ -322,6 +525,23 @@ export const get = (
   return ref
 }
 
+_test.get = () => {
+  const ref = { one: { two: { 3: 'value' } } }
+
+  console.assert(get('default', ref, 'one', 'two', 3) === 'value')
+
+  // @ts-expect-error
+  ref.one.two[3] = undefined
+
+  console.assert(get('default', ref, 'one', 'two', 3) === undefined)
+
+  // @ts-expect-error
+  ref.one.two = {}
+
+  console.assert(get('default', ref, 'one', 'two', 3) === 'default')
+  console.assert(get('default', ref) === ref)
+}
+
 const /** @type {Record<string, string>} */ _NS = {
   xlink: 'http://www.w3.org/1999/xlink'
 }
@@ -416,12 +636,158 @@ const _h = (/** @type {string?=} */ namespaceURI) => {
   return h
 }
 
+/**
+ * ```ts
+ * export function h<T extends keyof HTMLElementTagNameMap>(tag: T, ...args: HArgs[1][]): HTMLElementTagNameMap[T];
+ * export function h<N extends Node>(node: N, ...args: HArgs[1][]): N;
+ * export function h(...args: HArgs): Node;
+ * ```
+ */
+
+/**
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
+ *
+ * - The first argument of type `string` specifies the tag of the element to be created.
+ * - The first argument of type `Node` specifies the element to be modified.
+ * - All other arguments of type `Record<string, any>` are mappings of attributes and properties.
+ *   Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified.
+ *   (Note that `$` is not a valid attribute name character.)
+ *   All other keys specify *attributes* to be set by `setAttribute`.
+ *   An attribute equal to `false` causes the attribute to be removed by `removeAttribute`.
+ * - All other arguments of type `null` or `undefined` are simply ignored.
+ * - All other arguments of type `Node` are appended to the element being created or modified.
+ * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
+ * - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
+ */
 export const h = _h()
 
+_test.h = () => {
+  const b = h('b')
+
+  console.assert(b.outerHTML === '<b></b>')
+
+  const i = h('i', 'text')
+
+  h(b, i)
+
+  console.assert(i.outerHTML === '<i>text</i>')
+  console.assert(b.outerHTML === '<b><i>text</i></b>')
+
+  h(i, { $className: 'some class' })
+
+  console.assert(i.outerHTML === '<i class="some class">text</i>')
+  console.assert(b.outerHTML === '<b><i class="some class">text</i></b>')
+}
+
+_test['h: innerText vs items'] = () => {
+  console.assert(h('span', 'text').outerHTML === '<span>text</span>')
+  console.assert(h('span', { $innerText: 'text' }).outerHTML === '<span>text</span>')
+}
+
+_test['h: style'] = () => {
+  console.assert(h('div', { style: 'margin:0;padding:0' }).outerHTML ===
+    '<div style="margin:0;padding:0"></div>')
+  console.assert(h('div', { $style: 'margin:0;padding:0' }).outerHTML ===
+    '<div style="margin: 0px; padding: 0px;"></div>')
+  console.assert(h('div', { $style: { margin: 0, padding: 0 } }).outerHTML ===
+    '<div style="margin: 0px; padding: 0px;"></div>')
+}
+
+_test['h: attributes vs properties'] = () => {
+  const input1 = h('input', { value: 42 })
+  const input2 = h('input', { $value: '42' })
+
+  console.assert(input1.value === '42')
+  console.assert(input2.value === '42')
+
+  console.assert(input1.outerHTML === '<input value="42">')
+  console.assert(input2.outerHTML === '<input>')
+
+  const checkbox1 = h('input', { type: 'checkbox', checked: true })
+  const checkbox2 = h('input', { type: 'checkbox', $checked: true })
+
+  console.assert(checkbox1.checked === true)
+  console.assert(checkbox2.checked === true)
+
+  console.assert(checkbox1.outerHTML === '<input type="checkbox" checked="">')
+  console.assert(checkbox2.outerHTML === '<input type="checkbox">')
+}
+
+_test['h: nested properties'] = () => {
+  const div = h('div')
+
+  // @ts-expect-error
+  console.assert(div.key === undefined)
+
+  h(div, { $key: { one: 1 } })
+
+  // @ts-expect-error
+  console.assert(eq(div.key, { one: 1 }))
+
+  h(div, { $key: { two: 2 } })
+
+  // @ts-expect-error
+  console.assert(eq(div.key, { one: 1, two: 2 }))
+}
+
+/**
+ * ```ts
+ * export function has(key: any, ref: any): boolean;
+ * ```
+ */
+
+/**
+ * A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
+ */
 export const has = (/** @type {any} */ key, /** @type {any} */ ref) =>
   (is(String, key) || is(Number, key) || is(Symbol, key)) && Object.hasOwnProperty.call(ref ?? Object, key)
 
+_test.has = () => {
+  const obj = { key: 'K', null: 'N' }
+
+  console.assert('key' in obj)
+  console.assert(has('key', obj))
+
+  console.assert('null' in obj)
+  console.assert(has('null', obj))
+
+  // @ts-expect-error
+  console.assert(null in obj)
+  console.assert(!has(null, obj))
+
+  console.assert('toString' in obj)
+  console.assert(!has('toString', obj))
+}
+
+_test['has: null'] = () => {
+  let typeError
+
+  try {
+    // @ts-expect-error
+    console.assert('key' in null)
+  } catch (error) {
+    typeError = error
+  }
+
+  console.assert(typeError instanceof TypeError) // Cannot use 'in' operator to search for 'key' in null
+  console.assert(!has('key', null))
+}
+
 /**
+ * ```ts
+ * export function is(type: BigIntConstructor, arg: any): arg is bigint;
+ * export function is(type: BooleanConstructor, arg: any): arg is boolean;
+ * export function is(type: NumberConstructor, arg: any): arg is number;
+ * export function is(type: StringConstructor, arg: any): arg is string;
+ * export function is(type: SymbolConstructor, arg: any): arg is symbol;
+ * export function is(type: undefined, arg: any): arg is null | undefined;
+ * export function is<T extends abstract new (...args: any[]) => any>(type: T, arg: any): arg is InstanceType<T>;
+ * ```
+ */
+
+/**
+ * A helper that checks if the given argument is of a certain type.
+ *
  * @template {abstract new (...args: any[]) => any} T
  *
  * @type {{
@@ -438,6 +804,39 @@ export const has = (/** @type {any} */ key, /** @type {any} */ ref) =>
  */
 export const is = (/** @type {T} */ type, /** @type {any} */ arg) => arg?.constructor === type
 
+_test.is = () => {
+  console.assert(is(Number, 42))
+  console.assert(is(Number, Number(42)))
+  // eslint-disable-next-line no-new-wrappers
+  console.assert(is(Number, new Number(42)))
+  console.assert(is(Number, NaN))
+  console.assert(is(String, '42'))
+  console.assert(is(String, String('42')))
+  // eslint-disable-next-line no-new-wrappers
+  console.assert(is(String, new String('42')))
+  console.assert(is(Symbol, Symbol('42')))
+  console.assert(is(Symbol, Object(Symbol('42'))))
+  console.assert(is(undefined, undefined))
+  console.assert(is(undefined, null))
+  console.assert(is(Object, {}))
+  console.assert(is(Array, []))
+  console.assert(is(RegExp, /42/))
+  console.assert(is(Date, new Date(42)))
+  console.assert(is(Set, new Set(['42', 42])))
+  console.assert(is(Map, new Map([[{ j: 42 }, { J: '42' }], [{ c: 42 }, { C: '42' }]])))
+}
+
+_test['is vs ‘toString.call’'] = () => {
+  class FooBar { }
+
+  console.assert(is(FooBar, new FooBar()))
+
+  const fakeFooBar = { [Symbol.toStringTag]: 'FooBar' }
+
+  console.assert(({}).toString.call(new FooBar()) === '[object Object]')
+  console.assert(({}).toString.call(fakeFooBar) === '[object FooBar]')
+}
+
 const _jcss = (
   /** @type {JcssNode} */ node,
   /** @type {string}   */ prefix,
@@ -492,6 +891,23 @@ const _jcss = (
   }
 }
 
+/**
+ * ```ts
+ * export function jcss(root: JcssRoot, splitter?: string): string;
+ * ```
+ */
+
+/**
+ * A simple CSS-in-JS helper.
+ *
+ * The `root` parameter provides a hierarchical description of CSS rules.
+ *
+ * - Keys of sub-objects whose values are NOT objects are treated as CSS attribute, and values are treated as values of those CSS attributes; the concatenation of keys of all parent objects is a CSS rule.
+ * - All keys ignore the part starting with a splitter (default: `$$`) sign until the end of the key (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
+ * - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`).
+ * - Commas in keys that makes a CSS rule cause it to “split” and create separate rules for each part (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
+ * - Top-level keys that begin with `@` are not concatenated with sub-object keys.
+ */
 export const jcss = (/** @type {JcssRoot} */ root, splitter = '$$') => {
   const split = (/** @type {string} */ text) => text.split(splitter)[0]
   const /** @type {string[]} */ result = []
@@ -511,6 +927,221 @@ export const jcss = (/** @type {JcssRoot} */ root, splitter = '$$') => {
   return result.join('')
 }
 
+_test['jcss: #1'] = () => {
+  const actual = jcss({
+    a: {
+      color: 'red',
+      margin: 1,
+      '.c': { margin: 2, padding: 2 },
+      padding: 1
+    }
+  })
+
+  const expected = `
+    a{
+      color:red;
+      margin:1
+    }
+    a.c{
+      margin:2;
+      padding:2
+    }
+    a{
+      padding:1
+    }`.replace(/\n\s*/g, '')
+
+  console.assert(actual === expected)
+}
+
+_test['jcss: #2'] = () => {
+  const actual = jcss({
+    a: {
+      '.b': {
+        color: 'red',
+        margin: 1,
+        '.c': { margin: 2, padding: 2 },
+        padding: 1
+      }
+    }
+  })
+
+  const expected = `
+    a.b{
+      color:red;
+      margin:1
+    }
+    a.b.c{
+      margin:2;
+      padding:2
+    }
+    a.b{
+      padding:1
+    }`.replace(/\n\s*/g, '')
+
+  console.assert(actual === expected)
+}
+
+_test['jcss: #3'] = () => {
+  const actual = jcss({
+    '@font-face$$1': {
+      fontFamily: 'Jackens',
+      src$$1: 'url(otf/jackens.otf)',
+      src$$2: "url(otf/jackens.otf) format('opentype')," +
+        "url(svg/jackens.svg) format('svg')",
+      fontWeight: 'normal',
+      fontStyle: 'normal'
+    },
+    '@font-face$$2': {
+      fontFamily: 'C64',
+      src: 'url(fonts/C64_Pro_Mono-STYLE.woff)'
+    },
+    '@keyframes spin': {
+      '0%': { transform: 'rotate(0deg)' },
+      '100%': { transform: 'rotate(360deg)' }
+    },
+    div: {
+      border: 'solid red 1px',
+      '.c1': { 'background-color': '#000' },
+      ' .c1': { backgroundColor: 'black' },
+      '.c2': { backgroundColor: 'rgb(0,0,0)' }
+    },
+    '@media(min-width:200px)': {
+      div: { margin: 0, padding: 0 },
+      span: { color: '#000' }
+    }
+  })
+
+  const expected = `
+    @font-face{
+      font-family:Jackens;
+      src:url(otf/jackens.otf);
+      src:url(otf/jackens.otf) format('opentype'),url(svg/jackens.svg) format('svg');
+      font-weight:normal;
+      font-style:normal
+    }
+    @font-face{
+      font-family:C64;
+      src:url(fonts/C64_Pro_Mono-STYLE.woff)
+    }
+    @keyframes spin{
+      0%{
+        transform:rotate(0deg)
+      }
+      100%{
+        transform:rotate(360deg)
+      }
+    }
+    div{
+      border:solid red 1px
+    }
+    div.c1{
+      background-color:#000
+    }
+    div .c1{
+      background-color:black
+    }
+    div.c2{
+      background-color:rgb(0,0,0)
+    }
+    @media(min-width:200px){
+      div{
+        margin:0;
+        padding:0
+      }
+      span{
+        color:#000
+      }
+    }`.replace(/\n\s*/g, '')
+
+  console.assert(actual === expected)
+}
+
+_test['jcss: #4'] = () => {
+  const actual = jcss({
+    a: {
+      '.b,.c': {
+        margin: 1,
+        '.d': {
+          margin: 2
+        }
+      }
+    }
+  })
+
+  const expected = `
+    a.b,a.c{
+      margin:1
+    }
+    a.b.d,a.c.d{
+      margin:2
+    }`.replace(/\n\s*/g, '')
+
+  console.assert(actual === expected)
+}
+
+_test['jcss: #5'] = () => {
+  const actual = jcss({
+    '.b,.c': {
+      margin: 1,
+      '.d': {
+        margin: 2
+      }
+    }
+  })
+
+  const expected = `
+    .b,.c{
+      margin:1
+    }
+    .b.d,.c.d{
+      margin:2
+    }`.replace(/\n\s*/g, '')
+
+  console.assert(actual === expected)
+}
+
+_test['jcss: #6'] = () => {
+  const actual = jcss({
+    '.a,.b': {
+      margin: 1,
+      '.c,.d': {
+        margin: 2
+      }
+    }
+  })
+
+  const expected = `
+    .a,.b{
+      margin:1
+    }
+    .a.c,.a.d,.b.c,.b.d{
+      margin:2
+    }`.replace(/\n\s*/g, '')
+
+  console.assert(actual === expected)
+}
+
+/**
+ * ```ts
+ * export function jsOnParse(handlers: Record<string, Function>, text: string): any;
+ * ```
+ */
+
+/**
+ * `JSON.parse` with “JavaScript turned on”.
+ *
+ * Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
+ *
+ * ```js
+ * { "«handlerName»": [«params»] }
+ * ```
+ *
+ * are replaced by the result of call
+ *
+ * ```js
+ * handlers['«handlerName»'](...«params»)
+ * ```
+ */
 export const jsOnParse = (
   /** @type {Record<string, Function>} */ handlers,
   /** @type {string}                   */ text
@@ -533,6 +1164,49 @@ export const jsOnParse = (
   return value
 })
 
+_test.jsOnParse = () => {
+  const handlers = {
+    $hello: (/** @type {string} */ name) => `Hello ${name}!`,
+    $foo: () => 'bar'
+  }
+  const actual = jsOnParse(handlers, `
+  [
+    {
+      "$hello": ["World"]
+    },
+    {
+      "nested": {
+        "$hello": ["nested World"]
+      },
+      "one": 1,
+      "two": 2
+    },
+    {
+      "$foo": []
+    },
+    {
+      "$foo": ["The parent object does not have exactly one property!"],
+      "one": 1,
+      "two": 2
+    }
+  ]`)
+  const expected = [
+    'Hello World!',
+    {
+      nested: 'Hello nested World!',
+      one: 1,
+      two: 2
+    },
+    'bar',
+    {
+      $foo: ['The parent object does not have exactly one property!'],
+      one: 1,
+      two: 2
+    }]
+
+  console.assert(eq(actual, expected))
+}
+
 const _locale = (
   /** @type {Record<string, Record<string, string | Record<string, string>>>} */ locales,
   /** @type {string} */ language,
@@ -551,6 +1225,19 @@ const _locale = (
   return is(String, t) ? t : text
 }
 
+/**
+ * ```ts
+ * export function locale(
+ *   locales: Record<string, Record<string, string | Record<string, string>>>,
+ *   defaultLanguage: string,
+ *   languages?: readonly string[]
+ * ): (text?: string, version?: string) => string;
+ * ```
+ */
+
+/**
+ * Language translations helper.
+ */
 export const locale = (
   /** @type {Record<string, Record<string, string | Record<string, string>>>} */ locales,
   /** @type {string} */ defaultLanguage,
@@ -567,6 +1254,42 @@ export const locale = (
   return _locale.bind(0, locales, defaultLanguage)
 }
 
+_test.locale = () => {
+  const locales = {
+    pl: {
+      Password: 'Hasło',
+      button: { Login: 'Zaloguj' }
+    }
+  }
+  const _ = locale(locales, 'pl', [])
+
+  console.assert(_('Login') === 'Login')
+  console.assert(_('Password') === 'Hasło')
+
+  console.assert(_('Undefined text') === 'Undefined text')
+
+  console.assert(_('Login', 'button') === 'Zaloguj')
+
+  console.assert(_('Password', 'undefined_version') === 'Hasło')
+  console.assert(_('Undefined text', 'undefined_version') === 'Undefined text')
+
+  console.assert(_('toString') === 'toString')
+  console.assert(_('toString', 'undefined_version') === 'toString')
+}
+
+/**
+ * ```ts
+ * export function nanolight(
+ *   pattern: RegExp,
+ *   highlighters: ((chunk: string, index: number) => HArgs[1])[],
+ *   code: string
+ * ): HArgs[1][];
+ * ```
+ */
+
+/**
+ * A generic helper for syntax highlighting (see also `nanolightJs`).
+ */
 export const nanolight = (
   /** @type {RegExp} */ pattern,
   /** @type {((chunk: string, index: number) => HArgs[1])[]} */ highlighters,
@@ -584,6 +1307,15 @@ export const nanolight = (
   return result
 }
 
+/**
+ * ```ts
+ * export function nanolightJs(codeJs: string): HArgs[1][];
+ * ```
+ */
+
+/**
+ * A helper for highlighting JavaScript.
+ */
 // @ts-expect-error
 export const nanolightJs = nanolight.bind(0,
   /('.*?'|".*?"|`[\s\S]*?`)|(\/\/.*?\n|\/\*[\s\S]*?\*\/)|(break|case|catch|const|continue|debugger|default|delete|do|else|eval|export\s+type|export|extends|false|finally|for|from|function|goto|if|import|in|instanceof|is|keyof|let|NaN|new|null|package|return|super|switch|this|throw|true|try|typeof|undefined|var|void|while|with|yield)(?!\w)|([<>=.?:&|!~*/%+-])|(0x[\dabcdef]+|0o[01234567]+|0b[01]+|\d+(?:\.[\d_]+)?(?:e[+-]?[\d_]+)?)|([$\w]+)(?=\()|([$\wąćęłńóśżźĄĆĘŁŃÓŚŻŹ]+)/,
@@ -599,6 +1331,22 @@ export const nanolightJs = nanolight.bind(0,
   ]
 )
 
+_test.nanolightJs = () => {
+  const codeJs = 'const answerToLifeTheUniverseAndEverything = 42'
+
+  console.assert(h('pre', ['code', ...nanolightJs(codeJs)]).outerHTML ===
+    '<pre><code><b>const</b> <i>answerToLifeTheUniverseAndEverything</i> <b>=</b> <u>42</u></code></pre>')
+}
+
+/**
+ * ```ts
+ * export function plUral(singular: string, plural2: string, plural5: string, value: number): string;
+ * ```
+ */
+
+/**
+ * A helper for choosing the correct singular and plural.
+ */
 export const plUral = (
   /** @type {string} */ singular,
   /** @type {string} */ plural2,
@@ -617,6 +1365,35 @@ export const plUral = (
         : plural5
 }
 
+_test.plUral = () => {
+  // @ts-expect-error
+  const auto = plUral.bind(null, 'auto', 'auta', 'aut')
+
+  console.assert(auto(0) === 'aut')
+  console.assert(auto(1) === 'auto')
+  console.assert(auto(17) === 'aut')
+  console.assert(auto(42) === 'auta')
+
+  // @ts-expect-error
+  const car = plUral.bind(null, 'car', 'cars', 'cars')
+
+  console.assert(car(0) === 'cars')
+  console.assert(car(1) === 'car')
+  console.assert(car(17) === 'cars')
+  console.assert(car(42) === 'cars')
+}
+
+/**
+ * ```ts
+ * export function refsInfo(...refs: any[]): [string, string, string[]][];
+ * ```
+ */
+
+/**
+ * A helper that provides information about the given `refs`.
+ *
+ * It returns an array of triples: `[«name», «prototype-name», «array-of-own-property-names»]`.
+ */
 export const refsInfo = (/** @type {any[]} */ ...refs) => {
   const /** @type {Set<Function>} */ fns = new Set()
 
@@ -634,8 +1411,72 @@ export const refsInfo = (/** @type {any[]} */ ...refs) => {
   ]).sort((a, b) => -(a[0] < b[0]))
 }
 
+_test.refsInfo = () => {
+  const info = refsInfo(Array, Function)
+
+  console.assert(info.find(([name]) => name === 'Array')?.[2]?.includes?.('length'))
+  console.assert(info.find(([name]) => name === 'Function')?.[2]?.includes?.('length'))
+}
+
+_test['refsInfo: browserFingerprint'] = () => {
+  const browserFingerprint = () => {
+    // @ts-expect-error
+    const refs = Object.getOwnPropertyNames(window).map(name => window[name])
+    const info = refsInfo(...refs)
+    const json = JSON.stringify(info)
+    const hash = Array(32).fill(0)
+    let j = 0
+
+    for (let i = 0; i < json.length; i++) {
+      let charCode = json.charCodeAt(i)
+
+      while (charCode > 0) {
+        hash[j] = hash[j] ^ (charCode & 15)
+        charCode >>= 4
+        j = (j + 1) & 31
+      }
+    }
+
+    return hash.map(x => x.toString(16)).join('')
+  }
+
+  console.log(browserFingerprint())
+}
+
+/**
+ * ```ts
+ * export function s<T extends keyof SVGElementTagNameMap>(tag: T, ...args: HArgs[1][]): SVGElementTagNameMap[T];
+ * export function s<N extends Node>(node: N, ...args: HArgs[1][]): N;
+ * export function s(...args: HArgs): Node;
+ * ```
+ */
+
+/**
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
+ *
+ * - The first argument of type `string` specifies the tag of the element to be created.
+ * - The first argument of type `Node` specifies the element to be modified.
+ * - All other arguments of type `Record<string, any>` are mappings of attributes and properties.
+ *   Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified.
+ *   (Note that `$` is not a valid attribute name character.)
+ *   All other keys specify *attributes* to be set by `setAttributeNS`.
+ *   An attribute equal to `false` causes the attribute to be removed by `removeAttributeNS`.
+ * - All other arguments of type `null` or `undefined` are simply ignored.
+ * - All other arguments of type `Node` are appended to the element being created or modified.
+ * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
+ * - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
+ */
 export const s = _h('http://www.w3.org/2000/svg')
 
+/**
+ * ```ts
+ * export function set(value: any, ref: any, ...keys: (string | number | symbol)[]): void;
+ * ```
+ */
+
+/**
+ * A convenient helper for setting values of nested objects.
+ */
 export const set = (
   /** @type {any} */ value,
   /** @type {any} */ ref,
@@ -660,9 +1501,64 @@ export const set = (
   ref[keys[last]] = value
 }
 
+_test.set = () => {
+  const ref = {}
+
+  set('value', ref, 'one', 'two', 3, 4)
+
+  console.assert(eq(ref, {
+    one: {
+      two: [undefined, undefined, undefined, [
+        undefined, undefined, undefined, undefined, 'value']
+      ]
+    }
+  }))
+
+  set(undefined, ref, 'one', 'two', 3, 4)
+
+  console.assert(eq(ref, {
+    one: {
+      two: [undefined, undefined, undefined, [
+        undefined, undefined, undefined, undefined, undefined]
+      ]
+    }
+  }))
+
+  set({}, ref, 'one', 'two', 3)
+
+  console.assert(eq(ref, {
+    one: {
+      two: [undefined, undefined, undefined, {}]
+    }
+  }))
+
+  set('value', ref)
+
+  console.assert(eq(ref, {
+    one: {
+      two: [undefined, undefined, undefined, {}]
+    }
+  }))
+}
+
 const _ZEROS = '0'.repeat(16)
 let _counter = 0
 
+/**
+ * ```ts
+ * export function uuid1(options?: {
+ *   date?: Date;
+ *   node?: string;
+ * }): string;
+ * ```
+ */
+
+/**
+ * A helper that generates a UUID v1 identifier (with a creation timestamp).
+ *
+ * - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`.
+ *   Its value will be trimmed to last 12 characters and left padded with zeros.
+ */
 export const uuid1 = ({
   date = new Date(),
   node = Math.random().toString(16).slice(2)
@@ -683,3 +1579,26 @@ export const uuid1 = ({
     '-',
     (_ZEROS + node).slice(-12))
 }
+
+_test.uuid1 = () => {
+  for (let counter = 1; counter <= 0x5678; ++counter) {
+    const uuid = uuid1()
+
+    counter === 0x0001 && console.assert(uuid.split('-')[3] === '8001')
+    counter === 0x0fff && console.assert(uuid.split('-')[3] === '8fff')
+    counter === 0x1000 && console.assert(uuid.split('-')[3] === '9000')
+    counter === 0x2345 && console.assert(uuid.split('-')[3] === 'a345')
+    counter === 0x3456 && console.assert(uuid.split('-')[3] === 'b456')
+    counter === 0x4000 && console.assert(uuid.split('-')[3] === '8000')
+    counter === 0x4567 && console.assert(uuid.split('-')[3] === '8567')
+  }
+}
+
+_test['uuid1: node'] = () => {
+  console.assert(uuid1({ node: '000123456789abc' }).split('-')[4] === '123456789abc')
+  console.assert(uuid1({ node: '123456789' }).split('-')[4] === '000123456789')
+}
+
+_test['uuid1: date'] = () => {
+  console.assert(uuid1({ date: new Date(323325e6) }).startsWith('c1399400-9a71-11bd'))
+}

package/package.json

@@ -40,5 +40,5 @@
   "types": "nnn.d.ts",
   "name": "@jackens/nnn",
   "type": "module",
-  "version": "2023.9.18"
+  "version": "2023.9.23"
 }