@jackens/nnn 2025.9.3 → 2025.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/nnn.d.ts +59 -51
  2. package/package.json +1 -1
  3. package/readme.md +94 -81
package/nnn.d.ts CHANGED
@@ -1,63 +1,66 @@
1
1
  /**
2
- * The type of arguments of the `c` helper.
2
+ * Argument type for the `c` helper.
3
3
  */
4
4
  export type C_Node = {
5
5
  [attribute_or_selector: string]: string | number | C_Node | undefined;
6
6
  };
7
7
  /**
8
- * The type of arguments of the `c` helper.
8
+ * Argument type for the `c` helper.
9
9
  */
10
10
  export type C_Root = Record<PropertyKey, C_Node>;
11
11
  /**
12
- * A simple JS-to-CSS (aka CSS-in-JS) helper.
12
+ * A minimal JS-to-CSS (CSS‑in‑JS) helper.
13
13
  *
14
- * The `root` parameter provides a hierarchical description of CSS rules.
14
+ * The `root` object describes a hierarchy of CSS rules.
15
15
  *
16
- * - 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.
17
- * - 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`).
18
- * - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`), while all `_` characters are replaced by `-` character (e.g. `font_family` → `font-family`).
19
- * - 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}`).
20
- * - Top-level keys that begin with `@` are not concatenated with sub-object keys.
16
+ * - Keys whose values are not objects are treated as CSS property names; their values become property values. The concatenation of parent keys produces a selector.
17
+ * - For every key, the substring starting with the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
18
+ * - In property keys, uppercase letters are converted to lowercase and prefixed with `-` (e.g. `fontFamily` → `font-family`); underscores are converted to `-` (e.g. `font_family` → `font-family`).
19
+ * - Commas inside selector keys cause them to expand into multiple selectors (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
20
+ * - Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
21
21
  */
22
22
  export declare const c: (root: C_Root, splitter?: string) => string;
23
23
  /**
24
- * A tiny helper for parsing CSV.
24
+ * A tiny CSV parsing helper.
25
25
  */
26
26
  export declare const csv_parse: (csv: string, separator?: string) => string[][];
27
27
  /**
28
- * The type of arguments of the `escape_values` and `escape` helpers.
28
+ * Argument type accepted by the `escape_values` and `escape` helpers.
29
29
  */
30
30
  export type Escape_Map = Map<unknown, (value?: unknown) => string>;
31
31
  /**
32
- * A generic helper for escaping `values` by given `escape_map`.
32
+ * Escapes array `values` using the provided `escape_map`.
33
33
  */
34
34
  export declare const escape_values: (escape_map: Escape_Map, values: unknown[]) => string[];
35
35
  /**
36
- * A generic helper for escaping `values` by given `escape_map` (in *TemplateStrings* flavor).
36
+ * Escapes interpolated template `values` using the provided `escape_map`.
37
37
  */
38
38
  export declare const escape: (escape_map: Escape_Map, template: TemplateStringsArray, ...values: unknown[]) => string;
39
39
  /**
40
- * A helper that implements typographic corrections specific to Polish typography.
40
+ * Applies Polish‑specific typographic corrections.
41
41
  */
42
42
  export declare const fix_typography: (node: Node) => void;
43
43
  /**
44
- * The type of arguments of the `h` and `s` helpers.
44
+ * Argument type for the `h` and `s` helpers.
45
45
  */
46
46
  export type H_Args_1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | H_Args;
47
47
  /**
48
- * The type of arguments of the `h` and `s` helpers.
48
+ * Argument type for the `h` and `s` helpers.
49
49
  */
50
50
  export type H_Args = [string | Node, ...H_Args_1[]];
51
51
  /**
52
52
  * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
53
53
  *
54
- * - The first argument of type `string` specifies the tag of the element to be created.
55
- * - The first argument of type `Node` specifies the element to be modified.
56
- * - All other arguments of type `Record<PropertyKey, unknown>` 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`.
57
- * - All other arguments of type `null` or `undefined` are simply ignored.
58
- * - All other arguments of type `Node` are appended to the element being created or modified.
59
- * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
60
- * - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
54
+ * - If the first argument is a `string`, it is treated as the tag name to create.
55
+ * - If the first argument is a `Node`, that node is modified.
56
+ * - Object arguments map attributes/properties:
57
+ * - Keys starting with `$` set element properties (without `$`).
58
+ * - Other keys set attributes via `setAttribute`.
59
+ * - Attributes with value `false` are removed via `removeAttribute`.
60
+ * - `null` / `undefined` are ignored.
61
+ * - `Node` arguments are appended.
62
+ * - `string` / `number` arguments become `Text` nodes.
63
+ * - `H_Args` arrays are processed recursively.
61
64
  */
62
65
  export declare const h: {
63
66
  <T extends keyof HTMLElementTagNameMap>(tag: T, ...args1: H_Args_1[]): HTMLElementTagNameMap[T];
@@ -67,13 +70,16 @@ export declare const h: {
67
70
  /**
68
71
  * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
69
72
  *
70
- * - The first argument of type `string` specifies the tag of the element to be created.
71
- * - The first argument of type `Node` specifies the element to be modified.
72
- * - All other arguments of type `Record<PropertyKey, unknown>` 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`.
73
- * - All other arguments of type `null` or `undefined` are simply ignored.
74
- * - All other arguments of type `Node` are appended to the element being created or modified.
75
- * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
76
- * - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
73
+ * - If the first argument is a `string`, it is treated as the tag name to create.
74
+ * - If the first argument is a `Node`, that node is modified.
75
+ * - Object arguments map attributes/properties:
76
+ * - Keys starting with `$` set element properties (without `$`).
77
+ * - Other keys set attributes via `setAttributeNS`.
78
+ * - Attributes with value `false` are removed via `removeAttributeNS`.
79
+ * - `null` / `undefined` are ignored.
80
+ * - `Node` arguments are appended.
81
+ * - `string` / `number` arguments become `Text` nodes.
82
+ * - `H_Args` arrays are processed recursively.
77
83
  */
78
84
  export declare const s: {
79
85
  <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: H_Args_1[]): SVGElementTagNameMap[T];
@@ -81,48 +87,50 @@ export declare const s: {
81
87
  (tag_or_node: string | Node, ...args1: H_Args_1[]): Node;
82
88
  };
83
89
  /**
84
- * A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
90
+ * Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
85
91
  */
86
92
  export declare const svg_use: (id: string, ...args: H_Args_1[]) => SVGSVGElement;
87
93
  /**
88
- * A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
94
+ * A replacement to the `in` operator (not to be confused with `for-in`).
89
95
  */
90
96
  export declare const has_own: (ref: unknown, key: unknown) => boolean;
91
97
  /**
92
- * A helper that checks if the given argument is of type `any[]`.
98
+ * Checks whether the argument is an array.
93
99
  */
94
- export declare const is_array: (arg: any) => arg is any[];
95
- declare const FINITE_NUMBER: unique symbol;
96
- type Finite_Number = number & {
100
+ export declare const is_array: (arg: unknown) => arg is unknown[];
101
+ /**
102
+ * `number` type excluding `±Infinity` and `NaN`.
103
+ */
104
+ export type Finite_Number = number & {
97
105
  readonly [FINITE_NUMBER]: true;
98
106
  };
99
107
  /**
100
- * A helper that checks if the given argument is of type `number` but not `±Infinity` nor `NaN`.
108
+ * Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
101
109
  */
102
- export declare const is_finite_number: ((arg: unknown) => arg is Finite_Number);
110
+ export declare const is_finite_number: (arg: unknown) => arg is Finite_Number;
103
111
  /**
104
- * A helper that checks if the given argument is of type `number`.
112
+ * Checks whether the argument is a number.
105
113
  */
106
114
  export declare const is_number: (arg: unknown) => arg is number;
107
115
  /**
108
- * A helper that checks if the given argument is of type `Record<PropertyKey, unknown>`.
116
+ * Checks whether the argument is a plain object record.
109
117
  */
110
118
  export declare const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
111
119
  /**
112
- * A helper that checks if the given argument is of type `string`.
120
+ * Checks whether the argument is a string.
113
121
  */
114
122
  export declare const is_string: (arg: unknown) => arg is string;
115
123
  export {};
116
124
  /**
117
125
  * `JSON.parse` with “JavaScript turned on”.
118
126
  *
119
- * Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
127
+ * Objects having *exactly* one property whose name exists in `handlers`, i.e.:
120
128
  *
121
129
  * ```js
122
130
  * { "«handler_name»": [«params»] }
123
131
  * ```
124
132
  *
125
- * are replaced by the result of call
133
+ * are replaced with:
126
134
  *
127
135
  * ```js
128
136
  * handlers['«handler_name»'](...«params»)
@@ -131,32 +139,32 @@ export {};
131
139
  export declare const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => any;
132
140
  import type { H_Args_1 } from './h.js';
133
141
  /**
134
- * A generic helper for syntax highlighting (see also `nanolight_js`).
142
+ * Generic syntax highlighting helper (see also `nanolight_js`).
135
143
  */
136
144
  export declare const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => H_Args_1)[], code: string) => H_Args_1[];
137
145
  /**
138
- * A helper for highlighting JavaScript (see also `nanolight`).
146
+ * JavaScript syntax highlighting helper (built on `nanolight`).
139
147
  */
140
148
  export declare const nanolight_js: (code: string) => H_Args_1[];
141
149
  /**
142
- * A helper that implements TypeScript’s `Pick` utility type (see also `omit`).
150
+ * Runtime implementation of TypeScript’s `Pick` (see also `omit`).
143
151
  */
144
152
  export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
145
153
  /**
146
- * A helper that implements TypeScript’s `Omit` utility type (see also `pick`).
154
+ * Runtime implementation of TypeScript’s `Omit` (see also `pick`).
147
155
  */
148
156
  export declare const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
149
157
  /**
150
- * A helper for choosing the correct singular and plural.
158
+ * Chooses the appropriate Polish noun form based on a numeric value.
151
159
  */
152
160
  export declare const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
153
161
  /**
154
- * A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
162
+ * A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
155
163
  */
156
164
  export declare const pro: (ref: unknown) => any;
157
165
  /**
158
- * A helper that generates a UUID v1 identifier (with a creation timestamp).
166
+ * Generates a UUID v1 (time-based) identifier.
159
167
  *
160
- * - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`. Its value will be trimmed to last 12 characters and left padded with zeros.
168
+ * - Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
161
169
  */
162
170
  export declare const uuid_v1: (date?: Date, node?: string) => string;
package/package.json CHANGED
@@ -36,5 +36,5 @@
36
36
  "name": "@jackens/nnn",
37
37
  "type": "module",
38
38
  "types": "nnn.d.ts",
39
- "version": "2025.9.3"
39
+ "version": "2025.9.5"
40
40
  }
package/readme.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # nnn
2
2
 
3
- Jackens’ JavaScript helpers.
3
+ A collection of Jackens’ JavaScript helper utilities.
4
4
 
5
5
  ## Installation
6
6
 
@@ -28,33 +28,34 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
28
28
 
29
29
  ## Exports
30
30
 
31
- - `C_Node`: The type of arguments of the `c` helper.
32
- - `C_Root`: The type of arguments of the `c` helper.
33
- - `Escape_Map`: The type of arguments of the `escape_values` and `escape` helpers.
34
- - `H_Args`: The type of arguments of the `h` and `s` helpers.
35
- - `H_Args_1`: The type of arguments of the `h` and `s` helpers.
36
- - `c`: A simple JS-to-CSS (aka CSS-in-JS) helper.
37
- - `csv_parse`: A tiny helper for parsing CSV.
38
- - `escape`: A generic helper for escaping `values` by given `escape_map` (in *TemplateStrings* flavor).
39
- - `escape_values`: A generic helper for escaping `values` by given `escape_map`.
40
- - `fix_typography`: A helper that implements typographic corrections specific to Polish typography.
41
- - `h`: A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
42
- - `has_own`: A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
43
- - `is_array`: A helper that checks if the given argument is of type `any[]`.
44
- - `is_finite_number`: A helper that checks if the given argument is of type `number` but not `±Infinity` nor `NaN`.
45
- - `is_number`: A helper that checks if the given argument is of type `number`.
46
- - `is_record`: A helper that checks if the given argument is of type `Record<PropertyKey, unknown>`.
47
- - `is_string`: A helper that checks if the given argument is of type `string`.
48
- - `js_on_parse`: `JSON.parse` with “JavaScript turned on”.
49
- - `nanolight`: A generic helper for syntax highlighting (see also `nanolight_js`).
50
- - `nanolight_js`: A helper for highlighting JavaScript (see also `nanolight`).
51
- - `omit`: A helper that implements TypeScript’s `Omit` utility type (see also `pick`).
52
- - `pick`: A helper that implements TypeScript’s `Pick` utility type (see also `omit`).
53
- - `pl_ural`: A helper for choosing the correct singular and plural.
54
- - `pro`: A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
55
- - `s`: A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
56
- - `svg_use`: A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
57
- - `uuid_v1`: A helper that generates a UUID v1 identifier (with a creation timestamp).
31
+ - [`C_Node`](#C_Node): Argument type for the `c` helper.
32
+ - [`C_Root`](#C_Root): Argument type for the `c` helper.
33
+ - [`Escape_Map`](#Escape_Map): Argument type accepted by the `escape_values` and `escape` helpers.
34
+ - [`Finite_Number`](#Finite_Number): `number` type excluding `±Infinity` and `NaN`.
35
+ - [`H_Args`](#H_Args): Argument type for the `h` and `s` helpers.
36
+ - [`H_Args_1`](#H_Args_1): Argument type for the `h` and `s` helpers.
37
+ - [`c`](#c): A minimal JS-to-CSS (CSS‑in‑JS) helper.
38
+ - [`csv_parse`](#csv_parse): A tiny CSV parsing helper.
39
+ - [`escape`](#escape): Escapes interpolated template `values` using the provided `escape_map`.
40
+ - [`escape_values`](#escape_values): Escapes array `values` using the provided `escape_map`.
41
+ - [`fix_typography`](#fix_typography): Applies Polish‑specific typographic corrections.
42
+ - [`h`](#h): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
43
+ - [`has_own`](#has_own): A replacement to the `in` operator (not to be confused with `for-in`).
44
+ - [`is_array`](#is_array): Checks whether the argument is an array.
45
+ - [`is_finite_number`](#is_finite_number): Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
46
+ - [`is_number`](#is_number): Checks whether the argument is a number.
47
+ - [`is_record`](#is_record): Checks whether the argument is a plain object record.
48
+ - [`is_string`](#is_string): Checks whether the argument is a string.
49
+ - [`js_on_parse`](#js_on_parse): `JSON.parse` with “JavaScript turned on”.
50
+ - [`nanolight`](#nanolight): Generic syntax highlighting helper (see also `nanolight_js`).
51
+ - [`nanolight_js`](#nanolight_js): JavaScript syntax highlighting helper (built on `nanolight`).
52
+ - [`omit`](#omit): Runtime implementation of TypeScript’s `Omit` (see also `pick`).
53
+ - [`pick`](#pick): Runtime implementation of TypeScript’s `Pick` (see also `omit`).
54
+ - [`pl_ural`](#pl_ural): Chooses the appropriate Polish noun form based on a numeric value.
55
+ - [`pro`](#pro): A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
56
+ - [`s`](#s): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
57
+ - [`svg_use`](#svg_use): Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
58
+ - [`uuid_v1`](#uuid_v1): Generates a UUID v1 (time-based) identifier.
58
59
 
59
60
  ### C_Node
60
61
 
@@ -64,7 +65,7 @@ type C_Node = {
64
65
  };
65
66
  ```
66
67
 
67
- The type of arguments of the `c` helper.
68
+ Argument type for the `c` helper.
68
69
 
69
70
  ### C_Root
70
71
 
@@ -72,7 +73,7 @@ The type of arguments of the `c` helper.
72
73
  type C_Root = Record<PropertyKey, C_Node>;
73
74
  ```
74
75
 
75
- The type of arguments of the `c` helper.
76
+ Argument type for the `c` helper.
76
77
 
77
78
  ### Escape_Map
78
79
 
@@ -80,7 +81,17 @@ The type of arguments of the `c` helper.
80
81
  type Escape_Map = Map<unknown, (value?: unknown) => string>;
81
82
  ```
82
83
 
83
- The type of arguments of the `escape_values` and `escape` helpers.
84
+ Argument type accepted by the `escape_values` and `escape` helpers.
85
+
86
+ ### Finite_Number
87
+
88
+ ```ts
89
+ type Finite_Number = number & {
90
+ readonly [FINITE_NUMBER]: true;
91
+ };
92
+ ```
93
+
94
+ `number` type excluding `±Infinity` and `NaN`.
84
95
 
85
96
  ### H_Args
86
97
 
@@ -88,7 +99,7 @@ The type of arguments of the `escape_values` and `escape` helpers.
88
99
  type H_Args = [string | Node, ...H_Args_1[]];
89
100
  ```
90
101
 
91
- The type of arguments of the `h` and `s` helpers.
102
+ Argument type for the `h` and `s` helpers.
92
103
 
93
104
  ### H_Args_1
94
105
 
@@ -96,7 +107,7 @@ The type of arguments of the `h` and `s` helpers.
96
107
  type H_Args_1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | H_Args;
97
108
  ```
98
109
 
99
- The type of arguments of the `h` and `s` helpers.
110
+ Argument type for the `h` and `s` helpers.
100
111
 
101
112
  ### c
102
113
 
@@ -104,15 +115,15 @@ The type of arguments of the `h` and `s` helpers.
104
115
  const c: (root: C_Root, splitter?: string) => string;
105
116
  ```
106
117
 
107
- A simple JS-to-CSS (aka CSS-in-JS) helper.
118
+ A minimal JS-to-CSS (CSS‑in‑JS) helper.
108
119
 
109
- The `root` parameter provides a hierarchical description of CSS rules.
120
+ The `root` object describes a hierarchy of CSS rules.
110
121
 
111
- - 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.
112
- - 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`).
113
- - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`), while all `_` characters are replaced by `-` character (e.g. `font_family` → `font-family`).
114
- - 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}`).
115
- - Top-level keys that begin with `@` are not concatenated with sub-object keys.
122
+ - Keys whose values are not objects are treated as CSS property names; their values become property values. The concatenation of parent keys produces a selector.
123
+ - For every key, the substring starting with the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
124
+ - In property keys, uppercase letters are converted to lowercase and prefixed with `-` (e.g. `fontFamily` → `font-family`); underscores are converted to `-` (e.g. `font_family` → `font-family`).
125
+ - Commas inside selector keys cause them to expand into multiple selectors (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
126
+ - Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
116
127
 
117
128
  #### Usage Examples
118
129
 
@@ -316,7 +327,7 @@ expect(actual).to.deep.equal(expected)
316
327
  const csv_parse: (csv: string, separator?: string) => string[][];
317
328
  ```
318
329
 
319
- A tiny helper for parsing CSV.
330
+ A tiny CSV parsing helper.
320
331
 
321
332
  #### Usage Examples
322
333
 
@@ -342,7 +353,7 @@ expect(csv_parse(text)).to.deep.equal([
342
353
  const escape: (escape_map: Escape_Map, template: TemplateStringsArray, ...values: unknown[]) => string;
343
354
  ```
344
355
 
345
- A generic helper for escaping `values` by given `escape_map` (in *TemplateStrings* flavor).
356
+ Escapes interpolated template `values` using the provided `escape_map`.
346
357
 
347
358
  #### Usage Examples
348
359
 
@@ -377,7 +388,7 @@ expect(actual).to.deep.equal(expected)
377
388
  const escape_values: (escape_map: Escape_Map, values: unknown[]) => string[];
378
389
  ```
379
390
 
380
- A generic helper for escaping `values` by given `escape_map`.
391
+ Escapes array `values` using the provided `escape_map`.
381
392
 
382
393
  ### fix_typography
383
394
 
@@ -385,7 +396,7 @@ A generic helper for escaping `values` by given `escape_map`.
385
396
  const fix_typography: (node: Node) => void;
386
397
  ```
387
398
 
388
- A helper that implements typographic corrections specific to Polish typography.
399
+ Applies Polish‑specific typographic corrections.
389
400
 
390
401
  #### Usage Examples
391
402
 
@@ -411,13 +422,16 @@ const h: {
411
422
 
412
423
  A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
413
424
 
414
- - The first argument of type `string` specifies the tag of the element to be created.
415
- - The first argument of type `Node` specifies the element to be modified.
416
- - All other arguments of type `Record<PropertyKey, unknown>` 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`.
417
- - All other arguments of type `null` or `undefined` are simply ignored.
418
- - All other arguments of type `Node` are appended to the element being created or modified.
419
- - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
420
- - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
425
+ - If the first argument is a `string`, it is treated as the tag name to create.
426
+ - If the first argument is a `Node`, that node is modified.
427
+ - Object arguments map attributes/properties:
428
+ - Keys starting with `$` set element properties (without `$`).
429
+ - Other keys set attributes via `setAttribute`.
430
+ - Attributes with value `false` are removed via `removeAttribute`.
431
+ - `null` / `undefined` are ignored.
432
+ - `Node` arguments are appended.
433
+ - `string` / `number` arguments become `Text` nodes.
434
+ - `H_Args` arrays are processed recursively.
421
435
 
422
436
  #### Usage Examples
423
437
 
@@ -493,7 +507,7 @@ expect(div.key).to.deep.equal({ one: 1, two: 2 })
493
507
  const has_own: (ref: unknown, key: unknown) => boolean;
494
508
  ```
495
509
 
496
- A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
510
+ A replacement to the `in` operator (not to be confused with `for-in`).
497
511
 
498
512
  #### Usage Examples
499
513
 
@@ -531,22 +545,18 @@ expect(has_own(undefined, 'key')).to.be.false
531
545
  ### is_array
532
546
 
533
547
  ```ts
534
- const is_array: (arg: any) => arg is any[];
535
- declare const FINITE_NUMBER: unique symbol;
536
- type Finite_Number = number & {
537
- readonly [FINITE_NUMBER]: true;
538
- };
548
+ const is_array: (arg: unknown) => arg is unknown[];
539
549
  ```
540
550
 
541
- A helper that checks if the given argument is of type `any[]`.
551
+ Checks whether the argument is an array.
542
552
 
543
553
  ### is_finite_number
544
554
 
545
555
  ```ts
546
- const is_finite_number: ((arg: unknown) => arg is Finite_Number);
556
+ const is_finite_number: (arg: unknown) => arg is Finite_Number;
547
557
  ```
548
558
 
549
- A helper that checks if the given argument is of type `number` but not `±Infinity` nor `NaN`.
559
+ Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
550
560
 
551
561
  ### is_number
552
562
 
@@ -554,7 +564,7 @@ A helper that checks if the given argument is of type `number` but not `±Infini
554
564
  const is_number: (arg: unknown) => arg is number;
555
565
  ```
556
566
 
557
- A helper that checks if the given argument is of type `number`.
567
+ Checks whether the argument is a number.
558
568
 
559
569
  ### is_record
560
570
 
@@ -562,7 +572,7 @@ A helper that checks if the given argument is of type `number`.
562
572
  const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
563
573
  ```
564
574
 
565
- A helper that checks if the given argument is of type `Record<PropertyKey, unknown>`.
575
+ Checks whether the argument is a plain object record.
566
576
 
567
577
  ### is_string
568
578
 
@@ -571,7 +581,7 @@ const is_string: (arg: unknown) => arg is string;
571
581
  export {};
572
582
  ```
573
583
 
574
- A helper that checks if the given argument is of type `string`.
584
+ Checks whether the argument is a string.
575
585
 
576
586
  ### js_on_parse
577
587
 
@@ -581,13 +591,13 @@ const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => an
581
591
 
582
592
  `JSON.parse` with “JavaScript turned on”.
583
593
 
584
- Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
594
+ Objects having *exactly* one property whose name exists in `handlers`, i.e.:
585
595
 
586
596
  ```js
587
597
  { "«handler_name»": [«params»] }
588
598
  ```
589
599
 
590
- are replaced by the result of call
600
+ are replaced with:
591
601
 
592
602
  ```js
593
603
  handlers['«handler_name»'](...«params»)
@@ -646,7 +656,7 @@ expect(actual).to.deep.equal(expected)
646
656
  const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => H_Args_1)[], code: string) => H_Args_1[];
647
657
  ```
648
658
 
649
- A generic helper for syntax highlighting (see also `nanolight_js`).
659
+ Generic syntax highlighting helper (see also `nanolight_js`).
650
660
 
651
661
  ### nanolight_js
652
662
 
@@ -654,7 +664,7 @@ A generic helper for syntax highlighting (see also `nanolight_js`).
654
664
  const nanolight_js: (code: string) => H_Args_1[];
655
665
  ```
656
666
 
657
- A helper for highlighting JavaScript (see also `nanolight`).
667
+ JavaScript syntax highlighting helper (built on `nanolight`).
658
668
 
659
669
  #### Usage Examples
660
670
 
@@ -678,7 +688,7 @@ expect(nanolight_js(code_js)).to.deep.equal([
678
688
  const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
679
689
  ```
680
690
 
681
- A helper that implements TypeScript’s `Omit` utility type (see also `pick`).
691
+ Runtime implementation of TypeScript’s `Omit` (see also `pick`).
682
692
 
683
693
  #### Usage Examples
684
694
 
@@ -694,7 +704,7 @@ expect(omit(obj, ['c'])).to.deep.equal({ a: 42, b: '42' })
694
704
  const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
695
705
  ```
696
706
 
697
- A helper that implements TypeScript’s `Pick` utility type (see also `omit`).
707
+ Runtime implementation of TypeScript’s `Pick` (see also `omit`).
698
708
 
699
709
  #### Usage Examples
700
710
 
@@ -710,7 +720,7 @@ expect(pick(obj, ['a', 'b'])).to.deep.equal({ a: 42, b: '42' })
710
720
  const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
711
721
  ```
712
722
 
713
- A helper for choosing the correct singular and plural.
723
+ Chooses the appropriate Polish noun form based on a numeric value.
714
724
 
715
725
  #### Usage Examples
716
726
 
@@ -736,7 +746,7 @@ expect(car(42)).to.deep.equal('cars')
736
746
  const pro: (ref: unknown) => any;
737
747
  ```
738
748
 
739
- A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
749
+ A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
740
750
 
741
751
  #### Usage Examples
742
752
 
@@ -780,13 +790,16 @@ const s: {
780
790
 
781
791
  A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
782
792
 
783
- - The first argument of type `string` specifies the tag of the element to be created.
784
- - The first argument of type `Node` specifies the element to be modified.
785
- - All other arguments of type `Record<PropertyKey, unknown>` 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`.
786
- - All other arguments of type `null` or `undefined` are simply ignored.
787
- - All other arguments of type `Node` are appended to the element being created or modified.
788
- - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
789
- - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
793
+ - If the first argument is a `string`, it is treated as the tag name to create.
794
+ - If the first argument is a `Node`, that node is modified.
795
+ - Object arguments map attributes/properties:
796
+ - Keys starting with `$` set element properties (without `$`).
797
+ - Other keys set attributes via `setAttributeNS`.
798
+ - Attributes with value `false` are removed via `removeAttributeNS`.
799
+ - `null` / `undefined` are ignored.
800
+ - `Node` arguments are appended.
801
+ - `string` / `number` arguments become `Text` nodes.
802
+ - `H_Args` arrays are processed recursively.
790
803
 
791
804
  ### svg_use
792
805
 
@@ -794,7 +807,7 @@ A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style help
794
807
  const svg_use: (id: string, ...args: H_Args_1[]) => SVGSVGElement;
795
808
  ```
796
809
 
797
- A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
810
+ Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
798
811
 
799
812
  ### uuid_v1
800
813
 
@@ -802,9 +815,9 @@ A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args
802
815
  const uuid_v1: (date?: Date, node?: string) => string;
803
816
  ```
804
817
 
805
- A helper that generates a UUID v1 identifier (with a creation timestamp).
818
+ Generates a UUID v1 (time-based) identifier.
806
819
 
807
- - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`. Its value will be trimmed to last 12 characters and left padded with zeros.
820
+ - Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
808
821
 
809
822
  ## License
810
823