@koine/utils 2.0.0-beta.131 → 2.0.0-beta.133

package/Defer.d.ts

@@ -1,8 +1,22 @@
+/**
+ * @category async
+ */
 export type Deferred<T> = Promise<T> & {
     resolve: (value: T | PromiseLike<T>) => void;
     reject: (value: T | PromiseLike<T>) => void;
     catch: Promise<T>["catch"];
 };
+/**
+ * @category async
+ * @see https://stackoverflow.com/a/37673534/1938970
+ * @example
+ *
+ * ```ts
+ * const deferred = Defer();
+ * deferred.resolve();
+ * deferred.then(handleSuccess, handleError);
+ * ```
+ */
 export declare function Defer<T>(this: Promise<T> & {
     promise: Promise<T>;
     resolve: (value: T | PromiseLike<T>) => void;

package/Emitter.d.ts

@@ -1,7 +1,27 @@
+/**
+ * Emitter super simple class
+ *
+ * Events will be prefixed with the given `namespace` plus a `.` so:
+ * `{namespace}.myevent`
+ *
+ * Adapted from https://github.com/developit/mitt
+ *
+ * Regarding typescript support see:
+ * - https://stackoverflow.com/q/53299743/1938970
+ * - https://github.com/Microsoft/TypeScript/pull/26349
+ *
+ * @category impl
+ */
 export declare let Emitter: <EventMap extends {
     [key: string]: any;
 }>(namespace: string) => {
+    /**
+     * Register an event handler for the given type.
+     */
     on<EventName extends keyof EventMap>(name: EventName, handler: (data?: EventMap[EventName]) => any): void;
+    /**
+     * Invoke all handlers for the given type.
+     */
     emit<EventName extends keyof EventMap>(name: EventName, data?: EventMap[EventName]): void;
 };
 export default Emitter;

package/accentsSets.d.ts

@@ -1,3 +1,17 @@
+/**
+ * First value is the `to`, second is `from`, from *which* chars do we translates *to*
+ *
+ * @category text
+ */
 export type AccentsSet = [string, string];
+/**
+ * Accent sets
+ *
+ * @category text
+ * @resources
+ * - https://gist.github.com/mathewbyrne/1280286#gistcomment-3498021
+ * - https://gist.github.com/eek/9c4887e80b3ede05c0e39fee4dce3747 for usage
+ * of [normalize](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize)
+ */
 export declare let accentsSets: AccentsSet[];
 export default accentsSets;

package/addOrReplaceAtIdx.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Add or replace an item in the given array, it returns a new array (immutable).
+ * Typescript wise this is meant to keep the same type on the newly returned
+ * array, therefore the `newItem` must match the type of the `list` items.
+ *
+ * @category array
+ */
 export declare let addOrReplaceAtIdx: <T>(list: T[], newItem: T, newIdx?: number) => T[];
 export default addOrReplaceAtIdx;

package/areEqual.d.ts

@@ -1,4 +1,19 @@
 type ComparablePrimitive = string | number | boolean;
 type Comparable = ComparablePrimitive | object | Record<string, ComparablePrimitive> | Array<ComparablePrimitive>;
+/**
+ * A simple and quick deep equal objects utility. This is meant to be used
+ * solely to deduplicate requests payload and perform comparison on JSON ready
+ * objects made of primitives `string`, `number` and `boolean`s.
+ *
+ * It support nested `object`s and `array`s only.
+ *
+ * NB: `undefined` and `null` values do not count in the comparison as they are
+ * usually meant to be ignored in JSON requestBody payloads.
+ *
+ * According to very rudimentary tests this function takes on average between
+ * 0.15 ms and 2ms to compare two averaged sizes requet body payloads.
+ *
+ * @category object
+ */
 export declare let areEqual: (a: Comparable, b?: Comparable) => boolean;
 export default areEqual;

package/arrayFilterFalsy.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Given a list it returns it filtered without any falsy values (`null`,
+ * `undefined`, `false`, `0`, `""`). It "adjusts" the returned type as well.
+ *
+ * @category array
+ */
 export declare let arrayFilterFalsy: <T extends unknown[]>(list?: null | T) => Exclude<NonNullable<T>[number], undefined | false | 0 | "">[];
 export default arrayFilterFalsy;

package/arrayFindLastIndex.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the index of the last element in the array where predicate is true, and -1
+ * otherwise.
+ *
+ * @borrows [SO's answer by Nico Timmerman](https://stackoverflow.com/a/53187807/1938970)
+ *
+ * @category array
+ *
+ * @param array The source array to search in
+ * @param predicate find calls predicate once for each element of the array, in descending
+ * order, until it finds one where predicate returns true. If such an element is found,
+ * findLastIndex immediately returns that element index. Otherwise, findLastIndex returns -1.
+ */
 export declare let arrayFindLastIndex: <T>(array: Array<T>, predicate: (value: T, index: number, obj: T[]) => boolean) => number;
 export default arrayFindLastIndex;

package/arrayOfAll.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Ensure an array contains all desired values
+ *
+ * @category array
+ * @borrows [SO comment by `CertainPerformance`](https://stackoverflow.com/a/60132060/1938970)
+ *
+ * @usage
+ * ```ts
+ * type Fruit = "pear" | "apple" | "orange";
+ *
+ * const arrayOfAllFruits = arrayOfAll<Fruit>();
+ *
+ * const allFruits = arrayOfAllFruits([ "pear", "apple", "orange" ]); // ts compiler ok
+ * const allFruits = arrayOfAllFruits([ "pear", "apple" ]); // ts compiler fails
+ * ```
+ */
 export declare let arrayOfAll: <T>() => <U extends T[]>(array: U & ([T] extends [U[number]] ? unknown : "Invalid")) => U & ([T] extends [U[number]] ? unknown : "Invalid");
+/**
+ * @usage
+ * ```ts
+ * type Check_AreAllListed = AssertTrue<ArrayOfAll<typeof myList, MyUnion>>;
+ * ```
+ */
 export type ArrayOfAll<List extends unknown[], Union> = List[number] extends Union ? Union extends List[number] ? true : "Incomplete" : "Incomplete";
 export default arrayOfAll;

package/arraySum.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Sum array of numbers
+ *
+ * @category array
+ * @category math
+ */
 export declare let arraySum: (numbers: number[]) => number;
 export default arraySum;

package/arrayToLookup.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Maps a simple flat array to a lookup dictionary object
+ *
+ * @category array
+ */
 export declare let arrayToLookup: <T extends string | number | symbol>(array?: T[]) => Record<T, 1>;
 export default arrayToLookup;

package/arrayUniqueByProperties.d.ts

@@ -1,2 +1,10 @@
+/**
+ * @borrows [SO answer](https://stackoverflow.com/a/56757215/1938970)
+ *
+ * @category array
+ * @param array The array to filter
+ * @param keys The keys to compare in each array item
+ * @returns The filtered array
+ */
 export declare let arrayUniqueByProperties: <T extends any[]>(array: T, keys: (keyof T[number])[]) => T;
 export default arrayUniqueByProperties;

package/buildUrlQueryString.d.ts

@@ -1,3 +1,12 @@
 import type { AnyQueryParams } from "./location";
+/**
+ * Get clean query string for URL
+ *
+ * It returns the query string **with** the initial `?`
+ *
+ * TODO: at some point replace with `URLSearchParams`, @see [caniuse](https://caniuse.com/?search=URLSearchParams)
+ *
+ * @category location
+ */
 export declare let buildUrlQueryString: <T extends AnyQueryParams>(params: T) => string;
 export default buildUrlQueryString;

package/capitalize.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Capitalize first letter of the given string.
+ *
+ * @category text
+ * @resources
+ * - https://stackoverflow.com/a/11409944/1938970
+ */
 export declare let capitalize: <T extends string>(string?: null | T) => Capitalize<T>;
 export default capitalize;

package/changeCaseCamel.d.ts

@@ -1,3 +1,10 @@
 import { type PascalCaseOptions } from "./changeCaseHelpers";
+/**
+ * Convert a string to camel case (`fooBar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseCamel: (input: string, options?: PascalCaseOptions) => string;
 export default changeCaseCamel;

package/changeCaseCapital.d.ts

@@ -1,3 +1,10 @@
 import { type Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to sentence case (`Foo Bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseCapital: (input: string, options?: Options) => string;
 export default changeCaseCapital;

package/changeCaseConstant.d.ts

@@ -1,3 +1,10 @@
 import { type Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to constant case (`FOO_BAR`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseConstant: (input: string, options?: Options) => string;
 export default changeCaseConstant;

package/changeCaseDot.d.ts

@@ -1,3 +1,10 @@
 import type { Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to dot case (`foo.bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseDot: (input: string, options?: Options) => string;
 export default changeCaseDot;

package/changeCaseHelpers.d.ts

@@ -1,14 +1,36 @@
+/**
+ * @file
+ *
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
+/**
+ * Supported locale values. Use `false` to ignore locale.
+ * Defaults to `undefined`, which uses the host environment.
+ */
 export type Locale = string[] | string | false | undefined;
+/**
+ * Options used for converting strings to pascal/camel case.
+ */
 export interface PascalCaseOptions extends Options {
     mergeAmbiguousCharacters?: boolean;
 }
+/**
+ * Options used for converting strings to any case.
+ */
 export interface Options {
     locale?: Locale;
     split?: (value: string) => string[];
+    /** @deprecated Pass `split: splitSeparateNumbers` instead. */
     separateNumbers?: boolean;
     delimiter?: string;
     prefixCharacters?: string;
     suffixCharacters?: string;
 }
+/**
+ * Split any cased input strings into an array of words.
+ */
 export declare let split: (value: string) => string[];
+/**
+ * Split the input string into an array of words, separating numbers.
+ */
 export declare let splitSeparateNumbers: (value: string) => string[];

package/changeCaseKebab.d.ts

@@ -1,3 +1,10 @@
 import type { Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to kebab case (`foo.bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseKebab: (input: string, options?: Options) => string;
 export default changeCaseKebab;

package/changeCaseNone.d.ts

@@ -1,3 +1,10 @@
 import { type Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to space separated lower case (`foo bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseNone: (input: string, options?: Options) => string;
 export default changeCaseNone;

package/changeCasePascal.d.ts

@@ -1,3 +1,10 @@
 import { type PascalCaseOptions } from "./changeCaseHelpers";
+/**
+ * Convert a string to camel case (`FooBar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCasePascal: (input: string, options?: PascalCaseOptions) => string;
 export default changeCasePascal;

package/changeCasePascalSnake.d.ts

@@ -1,3 +1,10 @@
 import type { Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to pascal snake case (`Foo_Bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCasePascalSnake: (input: string, options?: Options) => string;
 export default changeCasePascalSnake;

package/changeCasePath.d.ts

@@ -1,3 +1,10 @@
 import type { Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to path case (`foo/bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCasePath: (input: string, options?: Options) => string;
 export default changeCasePath;

package/changeCaseSentence.d.ts

@@ -1,3 +1,10 @@
 import { type Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to sentence case (`Foo bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseSentence: (input: string, options?: Options) => string;
 export default changeCaseSentence;

package/changeCaseSnake.d.ts

@@ -1,3 +1,10 @@
 import type { Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to snake case (`foo_bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseSnake: (input: string, options?: Options) => string;
 export default changeCaseSnake;

package/changeCaseTrain.d.ts

@@ -1,3 +1,10 @@
 import type { Options } from "./changeCaseHelpers";
+/**
+ * Convert a string to train case (`Foo-Bar`).
+ *
+ * @category text
+ * @category case
+ * @borrows [blakeembrey/change-case](https://github.com/blakeembrey/change-case)
+ */
 export declare let changeCaseTrain: (input: string, options?: Options) => string;
 export default changeCaseTrain;

package/chunkByChunks.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @category array
+ * @see https://stackoverflow.com/a/8189268/1938970
+ * @experimental TODO: untested
+ */
 export declare let chunkByChunks: <T>(arr: T[], nrOfChunks: number, balanced?: boolean) => T[][];
 export default chunkByChunks;

package/chunkBySize.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @category array
+ * @see https://stackoverflow.com/a/40682136/1938970
+ */
 export declare let chunkBySize: <T>(arr: T[], size: number) => T[][];
 export default chunkBySize;

package/clamp.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Returns a number whose value is limited to the given range.
+ *
+ * @category math
+ * @see https://stackoverflow.com/a/11409944/1938970
+ */
 export declare let clamp: (num: number, min: number, max: number) => number;
 export default clamp;

package/clsx.d.ts

@@ -2,5 +2,11 @@ type ClassValue = ClassArray | ClassDictionary | string | number | bigint | null
 type ClassDictionary = Record<string, any>;
 type ClassArray = ClassValue[];
 export type ClsxClassValue = ClassValue;
+/**
+ * Class names utility
+ *
+ * @category impl
+ * @borrows [lukeed/clsx](https://github.com/lukeed/clsx)
+ */
 export declare let clsx: (...args: ClassValue[]) => string;
 export default clsx;

package/convertRange.d.ts

@@ -1,2 +1,16 @@
+/**
+ * Convert range of a number
+ *
+ * e.g. converting number 5 in a scale/range from 0 10 to a scale/range from 50
+ * to 100 would return 75
+ * @example
+ *
+ * ```ts
+ * convertRange(5, [0, 10], [50, 100]);
+ * ```
+ *
+ * @category math
+ * @see https://stackoverflow.com/a/14224813
+ */
 export declare let convertRange: (num: number, r1: number[], r2: number[]) => number;
 export default convertRange;

package/cookie.d.ts

@@ -1,15 +1,60 @@
+/**
+ * @module
+ *
+ * @category cookie
+ *
+ * All cookie related code is inspired and adapted from:
+ * - [js-cookie](https://github.com/js-cookie/js-cookie)
+ * - [cookie](https://github.com/jshttp/cookie)
+ */
+/**
+ * @category cookie
+ */
 type CookieAttributes = {
+    /**
+     * Define when the cookie will be removed. Value can be a Number
+     * which will be interpreted as days from time of creation or a
+     * Date instance. If omitted, the cookie becomes a session cookie.
+     */
     expires?: number | Date | undefined;
+    /**
+     * Define the path where the cookie is available. Defaults to '/'
+     *
+     * @default "/"
+     */
     path?: string | undefined;
+    /**
+     * Define the domain where the cookie is available. Defaults to
+     * the domain of the page where the cookie was created.
+     */
     domain?: string | undefined;
+    /**
+     * A Boolean indicating if the cookie transmission requires a
+     * secure protocol (https).
+     *
+     * @default "true"
+     */
     secure?: boolean | undefined;
+    /**
+     * Asserts that a cookie must not be sent with cross-origin requests,
+     * providing some protection against cross-site request forgery
+     * attacks (CSRF)
+     *
+     * @default "strict"
+     */
     sameSite?: "strict" | "Strict" | "lax" | "Lax" | "none" | "None" | undefined;
 };
+/**
+ * @category cookie
+ */
 export type CookieAttributesServer = CookieAttributes & {
     maxAge?: number;
     httpOnly?: boolean;
     encode?: (input: string) => string;
     decode?: (input: string) => string;
 };
+/**
+ * @category cookie
+ */
 export type CookieAttributesClient = CookieAttributes;
 export {};

package/createPalette.d.ts

@@ -6,5 +6,17 @@ type PaletteMapPair<T extends PaletteShade> = {
 type PaletteMap<T extends PaletteShades> = {
     [PS in T[number] as keyof PaletteMapPair<PS>]: PaletteMapPair<PS>[keyof PaletteMapPair<PS>];
 };
+/**
+ * Create palette, this is primarily thought to improve the reuse of a palette
+ * definition between TailwindCSS and straight ES imports
+ *
+ * @category colors
+ * @category tailwind
+ * @category responsive
+ *
+ * @returns An array with: 1) A flat palette map 2) A TailwindCSS ready palette
+ * object 3) A flat array of colors (no special sorting, same order as the `shades`
+ * given as argument)
+ */
 export declare let createPalette: <TName extends string, TShades extends PaletteShades, TColor = TShades[number][1], TMap = PaletteMap<TShades>>(name: TName, shades: TShades) => readonly [TMap, Record<`${TName}-${TShades[number][0]}`, string>, TColor[]];
 export default createPalette;

package/debounce.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Debounce function (with `setTimeout`)
+ *
+ * @category function
+ * @borrows [davidwalsh/debounce](https://davidwalsh.name/javascript-debounce-function)
+ */
 export declare let debounce: <T extends (...args: any[]) => any>(fn: T, wait?: number, immediate?: boolean) => (this: unknown, ...args: Parameters<T>) => void;
 export default debounce;

package/debouncePromise.d.ts

@@ -1,11 +1,28 @@
+/**
+ * Copy pasted from [chodorowicz/ts-debounce](https://github.com/chodorowicz/ts-debounce/blob/master/src/index.ts)
+ *
+ * @module
+ */
+/**
+ * @categroy functionn
+ */
 export type DebounceOptions<Result> = {
     isImmediate?: boolean;
     maxWait?: number;
     callback?: (data: Result) => void;
 };
+/**
+ * @categroy functionn
+ */
 export interface DebouncedFunction<Args extends any[], F extends (...args: Args) => any> {
     (this: ThisParameterType<F>, ...args: Args & Parameters<F>): Promise<ReturnType<F>>;
     cancel: (reason?: any) => void;
 }
+/**
+ * Debounce function (with `Promise`)
+ *
+ * @category function
+ * @borrows [chodorowicz/ts-debounce](https://github.com/chodorowicz/ts-debounce)
+ */
 export declare let debouncePromise: <Args extends any[], F extends (...args: Args) => any>(func: F, waitMilliseconds?: number, options?: DebounceOptions<ReturnType<F>>) => DebouncedFunction<Args, F>;
 export default debouncePromise;

package/debounceRaf.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Debounce function (with `requestAnimationFrame`)
+ *
+ * @category function
+ * @borrows [vanillajstoolkit/debounce by Chris Ferdinandi](https://vanillajstoolkit.com/helpers/debounce/)
+ */
 export declare function debounceRaf<T extends (...args: any[]) => any>(this: unknown, fn: T): (this: unknown, ...args: Parameters<T>) => void;
 export default debounceRaf;

package/decode.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @category security
+ * @see https://stackoverflow.com/a/22405578/9122820
+ */
 export declare let decode: <TReturn extends string>(str: string) => TReturn;
 export default decode;

package/encode.d.ts

@@ -1,2 +1,6 @@
+/**
+ * @category security
+ * @see https://stackoverflow.com/a/22405578/9122820
+ */
 export declare let encode: <TReturn extends string>(str: string) => TReturn;
 export default encode;

package/ensureInt.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Ensure input to be an integer
+ *
+ * @category cast
+ */
 export declare let ensureInt: (input: string | number) => number;
 export default ensureInt;

package/errorToString.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Ensure to transform a JavaScript `Error` into a string (uses its `message`)
+ *
+ * @category error
+ * @category cast
+ */
 export declare let errorToString: (e: unknown) => string;
 export default errorToString;

package/escapeRegExp.d.ts

@@ -1,2 +1,9 @@
+/**
+ * @borrows [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)
+ * @borrows [SO's answer by Mathias Bynens](https://stackoverflow.com/a/9310752/1938970)
+ *
+ * @category escape
+ * @category RegExp
+ */
 export declare let escapeRegExp: (text: string) => string;
 export default escapeRegExp;

package/findDuplicatedIndexes.d.ts

@@ -1,2 +1,5 @@
+/**
+ * @category array
+ */
 export declare let findDuplicatedIndexes: (arr: any[]) => Record<number, true>;
 export default findDuplicatedIndexes;

package/forin.d.ts

@@ -1,2 +1,8 @@
+/**
+ * To easily get typed native `for in`
+ *
+ * @category native
+ * @category object
+ */
 export declare let forin: <T>(object: T, cb: <K extends keyof T>(key: K, value: T[K]) => void) => void;
 export default forin;

package/gbToBytes.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Gigabytes to bytes
+ *
+ * @category format
+ */
 export declare let gbToBytes: (bytes: number) => number;
 export default gbToBytes;