@jackens/nnn 2024.4.7 → 2024.4.14

package/nnn.d.ts

@@ -157,7 +157,7 @@ export declare const locale: (map: Partial<Record<PropertyKey, Partial<Record<Pr
 /**
  * A generic helper for syntax highlighting (see also `nanolightJs`).
  */
-export declare const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => HArgs1)[], code: string) => HArgs1[];
+export declare const nanolight: (pattern: RegExp, highlighters: Partial<Array<(chunk: string, index: number) => HArgs1>>, code: string) => HArgs1[];
 
 /**
  * A helper for highlighting JavaScript.
@@ -189,7 +189,7 @@ export declare const pro: (ref: unknown) => any;
  *
  * It returns an array of triples: `[«name», «prototype-name», «array-of-own-property-names»]`.
  */
-export declare const refsInfo: (...refs: Partial<Array<unknown>>) => [string, string, (string | undefined)[]][];
+export declare const refsInfo: (...refs: Partial<Array<unknown>>) => Partial<Array<[string, string, Partial<Array<string>>]>>;
 
 /**
  * A helper that generates a UUID v1 identifier (with a creation timestamp).

package/package.json

@@ -38,5 +38,5 @@
   "types": "nnn.d.ts",
   "name": "@jackens/nnn",
   "type": "module",
-  "version": "2024.4.7"
+  "version": "2024.4.14"
 }

package/readme.md

@@ -2,7 +2,7 @@
 
 Jackens’ JavaScript helpers.
 
-<sub>Version: <code class="version">2024.4.7</code></sub>
+<sub>Version: <code class="version">2024.4.14</code></sub>
 
 ## Examples
 
@@ -87,6 +87,8 @@ The type of arguments of the `h` and `s` helpers.
 type HArgs1 = Partial<Record<PropertyKey, unknown>> | null | undefined | Node | string | number | HArgs;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Record>` instead of `Record`.
+
 The type of arguments of the `h` and `s` helpers.
 
 ### JcNode
@@ -105,6 +107,8 @@ The type of arguments of the `jc` helper.
 type JcRoot = Partial<Record<PropertyKey, JcNode>>;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Record>` instead of `Record`.
+
 The type of arguments of the `jc` helper.
 
 ### csvParse
@@ -116,6 +120,8 @@ const csvParse: (text: string, { header, separator }?: {
 }) => Partial<Array<Partial<Record<PropertyKey, string>>>> | Partial<Array<Partial<Array<string>>>>;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>`/`Partial<Record>` instead of `Array`/`Record`.
+
 A tiny helper for CSV parsing.
 
 Options:
@@ -130,13 +136,13 @@ const text = `"aaa
 aaa",bbb, "ccc,ccc"
 "xxx,xxx", "yyy
 yyy",zzz
-42,"42"  , 17
+ 42 , "42" , 17
 
 `
 expect(csvParse(text, { header: false })).toStrictEqual([
   ['aaa\n"aaa"\naaa', 'bbb', 'ccc,ccc'],
   ['xxx,xxx', 'yyy\nyyy', 'zzz'],
-  ['42', '42', ' 17']
+  [' 42 ', '42', ' 17']
 ])
 
 expect(csvParse(text)).toStrictEqual([{
@@ -144,7 +150,7 @@ expect(csvParse(text)).toStrictEqual([{
   bbb: 'yyy\nyyy',
   'ccc,ccc': 'zzz'
 }, {
-  'aaa\n"aaa"\naaa': '42',
+  'aaa\n"aaa"\naaa': ' 42 ',
   bbb: '42',
   'ccc,ccc': ' 17'
 }])
@@ -156,6 +162,8 @@ expect(csvParse(text)).toStrictEqual([{
 const escape: (escapeMap: EscapeMap, template: TemplateStringsArray, ...values: Partial<Array<unknown>>) => string;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
 
 #### Usage Examples
@@ -191,6 +199,8 @@ expect(actual).toStrictEqual(expected)
 const escapeValues: (escapeMap: EscapeMap, values: Partial<Array<unknown>>) => Partial<Array<string>>;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 A generic helper for escaping `values` by given `escapeMap`.
 
 ### fixTypography
@@ -223,6 +233,8 @@ const h: {
 };
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 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.
@@ -360,6 +372,8 @@ const is: {
 };
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>`/`Partial<Record>` instead of `Array`/`Record`.
+
 A helper that checks if the given argument is of a certain type.
 
 #### Usage Examples
@@ -637,6 +651,8 @@ expect(actual).toStrictEqual(expected)
 const jsOnParse: (handlers: Partial<Record<PropertyKey, Function>>, text: string) => any;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Record>` instead of `Record`.
+
 `JSON.parse` with “JavaScript turned on”.
 
 Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
@@ -704,6 +720,8 @@ expect(actual).toStrictEqual(expected)
 const locale: (map: Partial<Record<PropertyKey, Partial<Record<PropertyKey, string>>>>, defaultVersion: string) => (text: string, version?: string) => string;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Record>` instead of `Record`.
+
 Language translations helper.
 
 #### Usage Examples
@@ -731,9 +749,11 @@ expect(_('toString', 'undefined_version')).toStrictEqual('toString')
 ### nanolight
 
 ```ts
-const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => HArgs1)[], code: string) => HArgs1[];
+const nanolight: (pattern: RegExp, highlighters: Partial<Array<(chunk: string, index: number) => HArgs1>>, code: string) => HArgs1[];
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 A generic helper for syntax highlighting (see also `nanolightJs`).
 
 ### nanolightJs
@@ -766,6 +786,8 @@ expect(nanolightJs(codeJs)).toStrictEqual([
 const omit: <T extends Partial<Record<PropertyKey, unknown>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, unknown>>, keys: Partial<Array<unknown>>) => Omit<T, K[number]>;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>`/`Partial<Record>` instead of `Array`/`Record`.
+
 A helper that implements TypeScript’s `Omit` utility type.
 
 #### Usage Examples
@@ -782,6 +804,8 @@ expect(omit(obj, ['c'])).toStrictEqual({ a: 42, b: '42' })
 const pick: <T extends Partial<Record<PropertyKey, unknown>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, unknown>>, keys: Partial<Array<unknown>>) => Pick<T, K[number]>;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>`/`Partial<Record>` instead of `Array`/`Record`.
+
 A helper that implements TypeScript’s `Pick` utility type.
 
 #### Usage Examples
@@ -859,9 +883,11 @@ expect(ref).toStrictEqual({ one: { two: { three: { four: 1234 } } } })
 ### refsInfo
 
 ```ts
-const refsInfo: (...refs: Partial<Array<unknown>>) => [string, string, (string | undefined)[]][];
+const refsInfo: (...refs: Partial<Array<unknown>>) => Partial<Array<[string, string, Partial<Array<string>>]>>;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 A helper that provides information about the given `refs`.
 
 It returns an array of triples: `[«name», «prototype-name», «array-of-own-property-names»]`.
@@ -871,8 +897,8 @@ It returns an array of triples: `[«name», «prototype-name», «array-of-own-p
 ```js
 const info = refsInfo(Array, Function)
 
-expect(info.find(([name]) => name === 'Array')?.[2]?.includes('length')).toBeTrue()
-expect(info.find(([name]) => name === 'Function')?.[2]?.includes('length')).toBeTrue()
+expect(info.find(item => item?.[0] === 'Array')?.[2]?.includes('length')).toBeTrue()
+expect(info.find(item => item?.[0] === 'Function')?.[2]?.includes('length')).toBeTrue()
 ```
 
 ```js
@@ -909,6 +935,8 @@ const s: {
 };
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 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.
@@ -929,6 +957,8 @@ A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style help
 const svgUse: (id: string, ...args: Partial<Array<HArgs1>>) => SVGSVGElement;
 ```
 
+> See [here](https://jackens.github.io/nnn/doc/#Why-Partial-Array-and-Partial-Record) for an explanation of why `Partial<Array>` instead of `Array`.
+
 A convenient shortcut for `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
 
 ### uuid1
@@ -970,6 +1000,52 @@ expect(uuid1({ node: '123456789' }).split('-')[4]).toStrictEqual('000123456789')
 expect(uuid1({ date: new Date(323325000000) }).startsWith('c1399400-9a71-11bd')).toBeTrue()
 ```
 
+## Why Partial\<Array\> and Partial\<Record\>
+
+Consider the following code snippet:
+
+```ts
+const arr = ['one', 'two', 'three'] // type: string[]
+const arrAt42 = arr[42] // type: string
+
+arrAt42.toUpperCase() // 👎 allowed by TypeScript
+```
+
+TypeScript allows `arrAt42.toUpperCase()`,
+which causes a <code class="log">TypeError: undefined is not an object</code>.
+The variable `arr` should be of type `Partial<Array<string>>`:
+
+```ts
+const arr: Partial<Array<string>> = ['one', 'two', 'three']
+const arrAt42 = arr[42] // type: string | undefined
+
+arrAt42.toUpperCase()  // 👍 forbidden by TypeScript
+```
+
+Now `arrAt42.toUpperCase()` is forbidden by TypeScript (<code class="log">'arrAt42' is possibly undefined</code>).
+
+Similarly for the type `Record`:
+
+```ts
+const rec = Object.fromEntries(['one', 'two', 'three'].map((k, i) => [k, i])) // type: Record<string, number>
+const { tree } = rec // type: number
+
+tree.toFixed() // 👎 allowed by TypeScript
+```
+
+TypeScript allows `tree.toFixed()`, which causes a <code class="log">TypeError: undefined is not an object</code>.
+The variable `rec` should be of type `Partial<Record<PropertyKey, number>>`:
+
+```ts
+const rec: Partial<Record<PropertyKey, number>> =
+  Object.fromEntries(['one', 'two', 'three'].map((k, i) => [k, i]))
+const { tree } = rec // type: number | undefined
+
+tree.toFixed() // 👍 forbidden by TypeScript
+```
+
+Now `tree.toFixed()` is forbidden by TypeScript (<code class="log">'tree' is possibly undefined</code>).
+
 ## License
 
 The MIT License (MIT)