documentation, some basic testing

pkg/async.ts

@@ -1,4 +1,4 @@
-export async function promiseAllSafe<T>(tasks: Promise<T>[]) {
+export async function promiseAllOptimistic<T>(tasks: Promise<T>[]) {
     return await Promise.allSettled(tasks)
         .then(res => {
             const fulfilled: NonNullable<T>[] = [];

pkg/csv.ts

@@ -1,6 +1,15 @@
 import { Options, parse, Parser } from "csv-parse";
 import { z } from "zod";
 
+/**
+ * Converts raw CSV data into a validated array of entries of a given type,
+ * specified by a Zod validator provided in the function parameters.
+ *
+ * @param text a raw CSV text entry containing the data you wish to read
+ * @param validator a Zod schema representing the type of the target object
+ * @param options optional configuration options for the CSV parser
+ * @returns an array of validated
+ */
 export async function readCSVToType<
     TData extends Record<string, unknown>
 >(
@@ -18,10 +27,13 @@ export async function readCSVToType<
     const parser = parse(text, options);
     const records: TData[] = [];
 
+    // the type of the iterable is irrelevant, as it will be asserted by the Zod schema
     for await (const record of parser as (Parser & AsyncIterable<never>)) {
-        records.push(
-            validator.parse(record)
-        )
+        try {
+            records.push(validator.parse(record))
+        } catch (e) {
+            console.error(e);
+        }
     }
 
     return records;

pkg/dom.ts

@@ -1,10 +1,32 @@
 import React from 'react';
 
+/**
+ * Given an JSX element type `TElement`, returns a subset of its props
+ * specified in the union `TProps`.
+ */
 export type PickElementProps<
   TElement extends keyof React.JSX.IntrinsicElements,
   TProps extends keyof React.ComponentProps<TElement>
 > = Pick<React.ComponentProps<TElement>, TProps>;
 
+/**
+ * Given an JSX element type `TElement`, returns its full set of props,
+ * excluding members of the union `TProps`.
+ */
+export type ExcludeElementProps<
+  TElement extends keyof React.JSX.IntrinsicElements,
+  TProps extends keyof React.ComponentProps<TElement>
+> = Exclude<keyof React.ComponentProps<TElement>, TProps>;
+
+export type ElementProps<TElement extends keyof React.JSX.IntrinsicElements> = React.ComponentProps<TElement>;
+
+/**
+ * Mounts a virtual <a> tag and virtually clicks it, intiating a download
+ * on the client's device.
+ *
+ * @param url the URL location of the desired resource
+ * @param filename the name to assign to the download once completed
+ */
 export function clickVirtualDownloadLink(
     url: string,
     filename: string,

pkg/validators.ts

@@ -1,7 +1,14 @@
-export function must<T = unknown>(
-    evaluation: T,
-    errorMessage = "Failed to fulfill requirements for function"
-): NonNullable<T> | never {
-    if (!evaluation) throw new Error(errorMessage);
+/**
+ * Assert that a given value, @param evaluation, is truthy. @returns the evaluation, asserted as non-nullable.
+ */
+
+import { Callable } from "./types";
+
+export function must<T = unknown>(evaluation: T, callback?: Callable<never>): NonNullable<T> | never {
+    if (!evaluation) {
+        if (!callback) throw new Error("Assertion failed: value is falsy");
+        return callback();
+    }
+
     return evaluation;
 }