@jackens/nnn 2024.3.31 → 2024.4.7

package/nnn.d.ts

@@ -1,17 +1,29 @@
+/**
+ * A tiny helper for CSV parsing.
+ *
+ * Options:
+ * - `header`: flag indicating that the parsed CSV has a header row (default: `true`)
+ * - `separator`: field separator (default: `','`)
+ */
+export declare const csvParse: (text: string, { header, separator }?: {
+    header?: boolean | undefined;
+    separator?: string | undefined;
+}) => Partial<Array<Partial<Record<PropertyKey, string>>>> | Partial<Array<Partial<Array<string>>>>;
+
 /**
  * The type of arguments of the `escapeValues` and `escape` helpers.
  */
-export type EscapeMap = Map<any, (value?: any) => string>;
+export type EscapeMap = Map<unknown, (value?: unknown) => string>;
 
 /**
  * A generic helper for escaping `values` by given `escapeMap`.
  */
-export declare const escapeValues: (escapeMap: EscapeMap, values: Partial<Array<any>>) => Partial<Array<string>>;
+export declare const escapeValues: (escapeMap: EscapeMap, values: Partial<Array<unknown>>) => Partial<Array<string>>;
 
 /**
  * A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
  */
-export declare const escape: (escapeMap: EscapeMap, template: TemplateStringsArray, ...values: Partial<Array<any>>) => string;
+export declare const escape: (escapeMap: EscapeMap, template: TemplateStringsArray, ...values: Partial<Array<unknown>>) => string;
 
 /**
  * A helper that implements typographic corrections specific to Polish typography.
@@ -21,7 +33,7 @@ export declare const fixTypography: (node: Node) => void;
 /**
  * The type of arguments of the `h` and `s` helpers.
  */
-export type HArgs1 = Partial<Record<PropertyKey, any>> | null | undefined | Node | string | number | HArgs;
+export type HArgs1 = Partial<Record<PropertyKey, unknown>> | null | undefined | Node | string | number | HArgs;
 
 /**
  * The type of arguments of the `h` and `s` helpers.
@@ -33,7 +45,7 @@ export type HArgs = [string | Node, ...HArgs1[]];
  *
  * - 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 `Partial<Record<PropertyKey, any>>` are mappings of attributes and properties.
+ * - All other arguments of type `Partial<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`.
@@ -54,7 +66,7 @@ export declare const 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 `Partial<Record<PropertyKey, any>>` are mappings of attributes and properties.
+ * - All other arguments of type `Partial<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`.
@@ -78,21 +90,21 @@ export declare const svgUse: (id: string, ...args: Partial<Array<HArgs1>>) => SV
 /**
  * A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
  */
-export declare const has: (key: any, ref: any) => boolean;
+export declare const has: (key: unknown, ref: unknown) => boolean;
 
 /**
  * A helper that checks if the given argument is of a certain type.
  */
 export declare const is: {
-    (type: ArrayConstructor, arg: any): arg is Partial<Array<any>>;
-    (type: BigIntConstructor, arg: any): arg is bigint;
-    (type: BooleanConstructor, arg: any): arg is boolean;
-    (type: NumberConstructor, arg: any): arg is number;
-    (type: ObjectConstructor, arg: any): arg is Partial<Record<PropertyKey, any>>;
-    (type: StringConstructor, arg: any): arg is string;
-    (type: SymbolConstructor, arg: any): arg is symbol;
-    (type: undefined, arg: any): arg is undefined | null;
-    <T extends abstract new (...args: Partial<Array<any>>) => any>(type: T, arg: any): arg is InstanceType<T>;
+    (type: ArrayConstructor, arg: unknown): arg is Partial<Array<unknown>>;
+    (type: BigIntConstructor, arg: unknown): arg is bigint;
+    (type: BooleanConstructor, arg: unknown): arg is boolean;
+    (type: NumberConstructor, arg: unknown): arg is number;
+    (type: ObjectConstructor, arg: unknown): arg is Partial<Record<PropertyKey, unknown>>;
+    (type: StringConstructor, arg: unknown): arg is string;
+    (type: SymbolConstructor, arg: unknown): arg is symbol;
+    (type: undefined, arg: unknown): arg is undefined | null;
+    <T extends abstract new (...args: Partial<Array<any>>) => unknown>(type: T, arg: unknown): arg is InstanceType<T>;
 };
 
 /**
@@ -155,12 +167,12 @@ export declare const nanolightJs: (code: string) => HArgs1[];
 /**
  * A helper that implements TypeScript’s `Pick` utility type.
  */
-export declare const pick: <T extends Partial<Record<PropertyKey, any>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, any>>, keys: Partial<Array<any>>) => Pick<T, K[number]>;
+export declare 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]>;
 
 /**
  * A helper that implements TypeScript’s `Omit` utility type.
  */
-export declare const omit: <T extends Partial<Record<PropertyKey, any>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, any>>, keys: Partial<Array<any>>) => Omit<T, K[number]>;
+export declare 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]>;
 
 /**
  * A helper for choosing the correct singular and plural.
@@ -170,14 +182,14 @@ export declare const plUral: (singular: string, plural2: string, plural5: string
 /**
  * A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
  */
-export declare const pro: (ref: any) => any;
+export declare const pro: (ref: unknown) => any;
 
 /**
  * A helper that provides information about the given `refs`.
  *
  * It returns an array of triples: `[«name», «prototype-name», «array-of-own-property-names»]`.
  */
-export declare const refsInfo: (...refs: Partial<Array<any>>) => [string, string, (string | undefined)[]][];
+export declare const refsInfo: (...refs: Partial<Array<unknown>>) => [string, string, (string | undefined)[]][];
 
 /**
  * A helper that generates a UUID v1 identifier (with a creation timestamp).

package/nnn.js

@@ -1,3 +1,17 @@
+// src/nnn/csvParse.ts
+var csvParse = (text, { header = true, separator = "," } = {}) => {
+  const regExp = new RegExp(`${separator}|(?<!")\\s*"((?:[^"]|"")*)"\\s*(?!")`, "g");
+  const rows = text.replace(/\r/g, "").replace(/\n+$/, "").replace(/\n|(?<!")("(?:[^"]|"")*")(?!")/g, (_, chunk) => chunk ?? "\r").split("\r").map((line) => line.replace(regExp, (_, chunk) => chunk == null ? "\r" : chunk.replace(/""/g, '"')).split("\r"));
+  if (header) {
+    const keys = rows.shift();
+    return rows.map((row) => keys.reduce((record, key, index) => {
+      record[key] = row[index];
+      return record;
+    }, {}));
+  }
+  return rows;
+};
+
 // src/nnn/escape.ts
 var escapeValues = (escapeMap, values) => values.map((value) => (escapeMap.get(value?.constructor) ?? escapeMap.get(undefined))?.(value) ?? "");
 var escape = (escapeMap, template, ...values) => String.raw(template, ...escapeValues(escapeMap, values));
@@ -272,5 +286,6 @@ export {
   h,
   fixTypography,
   escapeValues,
-  escape
+  escape,
+  csvParse
 };

package/package.json

@@ -4,13 +4,11 @@
   "homepage": "https://jackens.github.io/nnn/doc/",
   "keywords": [
     "CSS-in-JS",
-    "deepEqual",
+    "CSV",
+    "csvParse",
     "DOM",
-    "eq",
-    "equal",
     "escape",
     "Gantt",
-    "graph",
     "h",
     "has",
     "highlight",
@@ -40,5 +38,5 @@
   "types": "nnn.d.ts",
   "name": "@jackens/nnn",
   "type": "module",
-  "version": "2024.3.31"
+  "version": "2024.4.7"
 }

package/readme.md

@@ -2,12 +2,12 @@
 
 Jackens’ JavaScript helpers.
 
-<sub>Version: <code class="version">2024.3.31</code></sub>
+<sub>Version: <code class="version">2024.4.7</code></sub>
 
 ## Examples
 
-- [Chessboard Demo](https://jackens.github.io/nnn/chessboard/)
 - [Documentation](https://jackens.github.io/nnn/doc/)
+- [Chessboard Demo](https://jackens.github.io/nnn/chessboard/)
 - [Gant Chart Demo](https://jackens.github.io/nnn/gantt/)
 - [Responsive Web Design Demo](https://jackens.github.io/nnn/rwd/)
 
@@ -44,6 +44,7 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
 - `HArgs1`: The type of arguments of the `h` and `s` helpers.
 - `JcNode`: The type of arguments of the `jc` helper.
 - `JcRoot`: The type of arguments of the `jc` helper.
+- `csvParse`: A tiny helper for CSV parsing.
 - `escape`: A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
 - `escapeValues`: A generic helper for escaping `values` by given `escapeMap`.
 - `fixTypography`: A helper that implements typographic corrections specific to Polish typography.
@@ -67,7 +68,7 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
 ### EscapeMap
 
 ```ts
-type EscapeMap = Map<any, (value?: any) => string>;
+type EscapeMap = Map<unknown, (value?: unknown) => string>;
 ```
 
 The type of arguments of the `escapeValues` and `escape` helpers.
@@ -83,7 +84,7 @@ The type of arguments of the `h` and `s` helpers.
 ### HArgs1
 
 ```ts
-type HArgs1 = Partial<Record<PropertyKey, any>> | null | undefined | Node | string | number | HArgs;
+type HArgs1 = Partial<Record<PropertyKey, unknown>> | null | undefined | Node | string | number | HArgs;
 ```
 
 The type of arguments of the `h` and `s` helpers.
@@ -106,10 +107,53 @@ type JcRoot = Partial<Record<PropertyKey, JcNode>>;
 
 The type of arguments of the `jc` helper.
 
+### csvParse
+
+```ts
+const csvParse: (text: string, { header, separator }?: {
+    header?: boolean | undefined;
+    separator?: string | undefined;
+}) => Partial<Array<Partial<Record<PropertyKey, string>>>> | Partial<Array<Partial<Array<string>>>>;
+```
+
+A tiny helper for CSV parsing.
+
+Options:
+- `header`: flag indicating that the parsed CSV has a header row (default: `true`)
+- `separator`: field separator (default: `','`)
+
+#### Usage Examples
+
+```js
+const text = `"aaa
+""aaa""
+aaa",bbb, "ccc,ccc"
+"xxx,xxx", "yyy
+yyy",zzz
+42,"42"  , 17
+
+`
+expect(csvParse(text, { header: false })).toStrictEqual([
+  ['aaa\n"aaa"\naaa', 'bbb', 'ccc,ccc'],
+  ['xxx,xxx', 'yyy\nyyy', 'zzz'],
+  ['42', '42', ' 17']
+])
+
+expect(csvParse(text)).toStrictEqual([{
+  'aaa\n"aaa"\naaa': 'xxx,xxx',
+  bbb: 'yyy\nyyy',
+  'ccc,ccc': 'zzz'
+}, {
+  'aaa\n"aaa"\naaa': '42',
+  bbb: '42',
+  'ccc,ccc': ' 17'
+}])
+```
+
 ### escape
 
 ```ts
-const escape: (escapeMap: EscapeMap, template: TemplateStringsArray, ...values: Partial<Array<any>>) => string;
+const escape: (escapeMap: EscapeMap, template: TemplateStringsArray, ...values: Partial<Array<unknown>>) => string;
 ```
 
 A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
@@ -119,7 +163,7 @@ A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings
 ```js
 const escapeMap: EscapeMap = new Map([
   [undefined, () => 'NULL'],
-  [Array, (values: Partial<Array<any>>) => escapeValues(escapeMap, values).join(', ')],
+  [Array, (values: Partial<Array<unknown>>) => escapeValues(escapeMap, values).join(', ')],
   [Boolean, (value: boolean) => `b'${+value}'`],
   [Date, (value: Date) => `'${value.toISOString().replace(/^(.+)T(.+)\..*$/, '$1 $2')}'`],
   [Number, (value: number) => `${value}`],
@@ -144,7 +188,7 @@ expect(actual).toStrictEqual(expected)
 ### escapeValues
 
 ```ts
-const escapeValues: (escapeMap: EscapeMap, values: Partial<Array<any>>) => Partial<Array<string>>;
+const escapeValues: (escapeMap: EscapeMap, values: Partial<Array<unknown>>) => Partial<Array<string>>;
 ```
 
 A generic helper for escaping `values` by given `escapeMap`.
@@ -183,7 +227,7 @@ A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style help
 
 - 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 `Partial<Record<PropertyKey, any>>` are mappings of attributes and properties.
+- All other arguments of type `Partial<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`.
@@ -264,7 +308,7 @@ expect(div.key).toStrictEqual({ one: 1, two: 2 })
 ### has
 
 ```ts
-const has: (key: any, ref: any) => boolean;
+const has: (key: unknown, ref: unknown) => boolean;
 ```
 
 A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
@@ -304,15 +348,15 @@ expect(has('key', null)).toBeFalse()
 
 ```ts
 const is: {
-    (type: ArrayConstructor, arg: any): arg is Partial<Array<any>>;
-    (type: BigIntConstructor, arg: any): arg is bigint;
-    (type: BooleanConstructor, arg: any): arg is boolean;
-    (type: NumberConstructor, arg: any): arg is number;
-    (type: ObjectConstructor, arg: any): arg is Partial<Record<PropertyKey, any>>;
-    (type: StringConstructor, arg: any): arg is string;
-    (type: SymbolConstructor, arg: any): arg is symbol;
-    (type: undefined, arg: any): arg is undefined | null;
-    <T extends abstract new (...args: Partial<Array<any>>) => any>(type: T, arg: any): arg is InstanceType<T>;
+    (type: ArrayConstructor, arg: unknown): arg is Partial<Array<unknown>>;
+    (type: BigIntConstructor, arg: unknown): arg is bigint;
+    (type: BooleanConstructor, arg: unknown): arg is boolean;
+    (type: NumberConstructor, arg: unknown): arg is number;
+    (type: ObjectConstructor, arg: unknown): arg is Partial<Record<PropertyKey, unknown>>;
+    (type: StringConstructor, arg: unknown): arg is string;
+    (type: SymbolConstructor, arg: unknown): arg is symbol;
+    (type: undefined, arg: unknown): arg is undefined | null;
+    <T extends abstract new (...args: Partial<Array<any>>) => unknown>(type: T, arg: unknown): arg is InstanceType<T>;
 };
 ```
 
@@ -341,7 +385,7 @@ expect(is(Map, new Map([[{ j: 42 }, { J: '42' }], [{ c: 42 }, { C: '42' }]]))).t
 ```
 
 ```js
-const iz = (type: any, arg: any) => ({}).toString.call(arg).slice(8, -1) === type?.name
+const iz = (type: unknown, arg: unknown) => ({}).toString.call(arg).slice(8, -1) === type?.name
 
 class FooBar { }
 
@@ -719,7 +763,7 @@ expect(nanolightJs(codeJs)).toStrictEqual([
 ### omit
 
 ```ts
-const omit: <T extends Partial<Record<PropertyKey, any>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, any>>, keys: Partial<Array<any>>) => Omit<T, K[number]>;
+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]>;
 ```
 
 A helper that implements TypeScript’s `Omit` utility type.
@@ -735,7 +779,7 @@ expect(omit(obj, ['c'])).toStrictEqual({ a: 42, b: '42' })
 ### pick
 
 ```ts
-const pick: <T extends Partial<Record<PropertyKey, any>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, any>>, keys: Partial<Array<any>>) => Pick<T, K[number]>;
+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]>;
 ```
 
 A helper that implements TypeScript’s `Pick` utility type.
@@ -777,7 +821,7 @@ expect(car(42)).toStrictEqual('cars')
 ### pro
 
 ```ts
-const pro: (ref: any) => any;
+const pro: (ref: unknown) => any;
 ```
 
 A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
@@ -815,7 +859,7 @@ expect(ref).toStrictEqual({ one: { two: { three: { four: 1234 } } } })
 ### refsInfo
 
 ```ts
-const refsInfo: (...refs: Partial<Array<any>>) => [string, string, (string | undefined)[]][];
+const refsInfo: (...refs: Partial<Array<unknown>>) => [string, string, (string | undefined)[]][];
 ```
 
 A helper that provides information about the given `refs`.
@@ -869,7 +913,7 @@ A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style help
 
 - 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 `Partial<Record<PropertyKey, any>>` are mappings of attributes and properties.
+- All other arguments of type `Partial<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`.