@koine/utils 2.0.0-beta.10 → 2.0.0-beta.12

package/Emitter.d.ts

@@ -6,9 +6,11 @@
  *
  * Adapted from https://github.com/developit/mitt
  *
- * Regarding typescript support @see:
+ * Regarding typescript support see:
  * - https://stackoverflow.com/q/53299743/1938970
  * - https://github.com/Microsoft/TypeScript/pull/26349
+ *
+ * @category impl
  */
 export declare function Emitter<EventMap extends {
     [key: string]: any;

package/Emitter.mjs

@@ -6,9 +6,11 @@
  *
  * Adapted from https://github.com/developit/mitt
  *
- * Regarding typescript support @see:
+ * Regarding typescript support see:
  * - https://stackoverflow.com/q/53299743/1938970
  * - https://github.com/Microsoft/TypeScript/pull/26349
+ *
+ * @category impl
  */ export function Emitter(namespace) {
     const all = new Map();
     return {

package/accentSets.d.ts

@@ -8,8 +8,9 @@ export type AccentsSet = [string, string];
  * Accent sets
  *
  * @category text
- * @see https://gist.github.com/mathewbyrne/1280286#gistcomment-3498021
- * @see https://gist.github.com/eek/9c4887e80b3ede05c0e39fee4dce3747 for usage
+ * @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 const accentsSets: AccentsSet[];

package/accentSets.mjs

@@ -6,8 +6,9 @@
  * Accent sets
  *
  * @category text
- * @see https://gist.github.com/mathewbyrne/1280286#gistcomment-3498021
- * @see https://gist.github.com/eek/9c4887e80b3ede05c0e39fee4dce3747 for usage
+ * @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 const accentsSets = [
     [

package/addOrReplaceAtIdx.d.ts

@@ -1,4 +1,8 @@
 /**
+ * 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 function addOrReplaceAtIdx<T>(list: T[], newItem: T, newIdx?: number): T[];

package/addOrReplaceAtIdx.mjs

@@ -1,4 +1,8 @@
 /**
+ * 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 function addOrReplaceAtIdx(list, newItem, newIdx) {
     if (list.length === 0) {

package/areEqual.d.ts

@@ -13,7 +13,7 @@ type Comparable = ComparablePrimitive | object | Record<string, ComparablePrimit
  * 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 objects
+ * @category object
  */
 export declare function areEqual(a: Comparable, b?: Comparable): boolean;
 export default areEqual;

package/areEqual.mjs

@@ -40,7 +40,7 @@ function areEqualObjects(a, b) {
  * 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 objects
+ * @category object
  */ export function areEqual(a, b) {
     if (!a && !b) {
         // console.log(`areEqual took ${performance.now() - t0} ms`);

package/arrayOfAll.d.ts

@@ -5,8 +5,7 @@
  * @borrows [SO comment by `CertainPerformance`](https://stackoverflow.com/a/60132060/1938970)
  *
  * @usage
- *
- * ```
+ * ```ts
  * type Fruit = "pear" | "apple" | "orange";
  *
  * const arrayOfAllFruits = arrayOfAll<Fruit>();

package/arrayOfAll.mjs

@@ -5,8 +5,7 @@
  * @borrows [SO comment by `CertainPerformance`](https://stackoverflow.com/a/60132060/1938970)
  *
  * @usage
- *
- * ```
+ * ```ts
  * type Fruit = "pear" | "apple" | "orange";
  *
  * const arrayOfAllFruits = arrayOfAll<Fruit>();

package/arraySum.d.ts

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

package/arraySum.mjs

@@ -1,6 +1,7 @@
 /**
  * Sum array of numbers
  *
- * @category array | math
+ * @category array
+ * @category math
  */ export const arraySum = (numbers)=>numbers.reduce((sum, current)=>sum + current, 0);
 export default arraySum;

package/capitalize.d.ts

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

package/capitalize.mjs

@@ -2,7 +2,8 @@
  * Capitalize first letter of the given string.
  *
  * @category text
- * @see https://stackoverflow.com/a/11409944/1938970
+ * @resources
+ * - https://stackoverflow.com/a/11409944/1938970
  */ export function capitalize(string) {
     const ensuredString = string || "";
     return ensuredString.charAt(0).toUpperCase() + ensuredString.slice(1);

package/chunkByChunks.d.ts

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

package/chunkByChunks.mjs

@@ -1,7 +1,7 @@
 /**
- * TODO: untested
  * @category array
  * @see https://stackoverflow.com/a/8189268/1938970
+ * @experimental TODO: untested
  */ export function chunkByChunks(arr, nrOfChunks, balanced) {
     if (nrOfChunks < 2) return [
         arr

package/clsx.d.ts

@@ -5,8 +5,9 @@ export type ClsxClassValue = ClassValue;
 /**
  * Class names utility
  *
+ * @category impl
  * @borrows [lukeed/clsx](https://github.com/lukeed/clsx)
- * @license [MIT: Luke Edwards](https://github.com/lukeed/clsx/blob/master/license)
+ * @license MIT Luke Edwards https://github.com/lukeed/clsx/blob/master/license
  */
 export declare const clsx: (...args: ClassValue[]) => string;
 export default clsx;

package/clsx.mjs

@@ -29,8 +29,9 @@ function toVal(mix) {
 /**
  * Class names utility
  *
+ * @category impl
  * @borrows [lukeed/clsx](https://github.com/lukeed/clsx)
- * @license [MIT: Luke Edwards](https://github.com/lukeed/clsx/blob/master/license)
+ * @license MIT Luke Edwards https://github.com/lukeed/clsx/blob/master/license
  */ export const clsx = function() {
     let i = 0, tmp, x, str = "";
     while(i < arguments.length){

package/convertRange.d.ts

@@ -3,7 +3,9 @@
  *
  * 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]);
  * ```
  *

package/convertRange.mjs

@@ -3,7 +3,9 @@
  *
  * 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]);
  * ```
  *

package/cookie.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file
+ * @module
  *
  * @category cookie
  *
@@ -7,6 +7,9 @@
  * - [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
@@ -41,13 +44,22 @@ type CookieAttributes = {
      */
     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;
+/**
+ * @category cookie
+ */
 export declare const defaultAttributesClient: {
     path: string;
 };

package/cookie.mjs

@@ -1,11 +1,15 @@
 /**
- * @file
+ * @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
+ */ /**
+ * @category cookie
  */ export const defaultAttributesClient = {
     path: "/"
 };

package/createPalette.d.ts

@@ -10,7 +10,9 @@ type PaletteMap<T extends PaletteShades> = {
  * Create palette, this is primarily thought to improve the reuse of a palette
  * definition between TailwindCSS and straight ES imports
  *
- * @category styling|tailwind|colours
+ * @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`

package/createPalette.mjs

@@ -2,7 +2,9 @@
  * Create palette, this is primarily thought to improve the reuse of a palette
  * definition between TailwindCSS and straight ES imports
  *
- * @category styling|tailwind|colours
+ * @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`

package/debouncePromise.d.ts

@@ -1,11 +1,19 @@
 /**
- * @file Copy pasted from https://github.com/chodorowicz/ts-debounce/blob/master/src/index.ts
+ * 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;
@@ -15,7 +23,7 @@ export interface DebouncedFunction<Args extends any[], F extends (...args: Args)
  *
  * @category function
  * @borrows [chodorowicz/ts-debounce](https://github.com/chodorowicz/ts-debounce)
- * @license [MIT: Jakub Chodorowicz](Jakub Chodorowicz)
+ * @license MIT: Jakub Chodorowicz
  */
 export declare function debouncePromise<Args extends any[], F extends (...args: Args) => any>(func: F, waitMilliseconds?: number, options?: DebounceOptions<ReturnType<F>>): DebouncedFunction<Args, F>;
 export default debouncePromise;

package/debouncePromise.mjs

@@ -10,13 +10,17 @@
 // export const debouncePromise = tsDebounce;
 // export default debouncePromise;
 /**
- * @file Copy pasted from https://github.com/chodorowicz/ts-debounce/blob/master/src/index.ts
+ * Copy pasted from [chodorowicz/ts-debounce](https://github.com/chodorowicz/ts-debounce/blob/master/src/index.ts)
+ *
+ * @module
+ */ /**
+ * @categroy functionn
  */ /**
  * Debounce function (with `Promise`)
  *
  * @category function
  * @borrows [chodorowicz/ts-debounce](https://github.com/chodorowicz/ts-debounce)
- * @license [MIT: Jakub Chodorowicz](Jakub Chodorowicz)
+ * @license MIT: Jakub Chodorowicz
  */ export function debouncePromise(func, waitMilliseconds = 50, options = {}) {
     let timeoutId;
     const isImmediate = options.isImmediate ?? false;

package/debounceRaf.d.ts

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

package/debounceRaf.mjs

@@ -1,9 +1,9 @@
 /**
  * Debounce function (with `requestAnimationFrame`)
  *
- * (c) 2021 Chris Ferdinandi, MIT License, https://gomakethings.com
  * @category function
  * @borrows [vanillajstoolkit/debounce](https://vanillajstoolkit.com/helpers/debounce/)
+ * @license (c) 2021 Chris Ferdinandi, MIT License, https://gomakethings.com
  */ export function debounceRaf(fn) {
     let timeout;
     return function(...args) {

package/errorToString.d.ts

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

package/errorToString.mjs

@@ -2,6 +2,7 @@ import isString from "./isString";
 /**
  * Ensure to transform a JavaScript `Error` into a string (uses its `message`)
  *
- * @category Error
+ * @category error
+ * @category cast
  */ export const errorToString = (e)=>e instanceof Error ? e.message : isString(e) ? e : "";
 export default errorToString;

package/forin.d.ts

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

package/forin.mjs

@@ -1,7 +1,8 @@
 /**
  * To easily get typed native `for in`
  *
- * @category objects
+ * @category native
+ * @category object
  */ export function forin(object, cb) {
     for(const key in object){
         cb(key, object[key]);

package/getEmptyArray.d.ts

@@ -1,5 +1,4 @@
 /**
- *
  * Returns an array of undefined values of the desired length, useful to build
  * skeleton UIs.
  *

package/getEmptyArray.mjs

@@ -1,6 +1,5 @@
 import isNumber from "./isNumber";
 /**
- *
  * Returns an array of undefined values of the desired length, useful to build
  * skeleton UIs.
  *

package/getKeys.d.ts

@@ -2,7 +2,8 @@
  * Type safe replacement for `Object.keys(myObject)` to iterate over a record
  * without loosing the key's types in simple `string`s.
  *
- * @category objects
+ * @category native
+ * @category object
  * @see https://stackoverflow.com/a/59459000/1938970
  */
 export declare const getKeys: <T extends object>(obj: T) => (keyof T)[];

package/getKeys.mjs

@@ -2,7 +2,8 @@
  * Type safe replacement for `Object.keys(myObject)` to iterate over a record
  * without loosing the key's types in simple `string`s.
  *
- * @category objects
+ * @category native
+ * @category object
  * @see https://stackoverflow.com/a/59459000/1938970
  */ export const getKeys = Object.keys;
 export default getKeys;

package/getMediaQueryWidthResolvers.d.ts

@@ -1,4 +1,10 @@
+/**
+ * @category responsive
+ */
 export type GetMediaQueryWidthResolversBreakpoints = Record<string, number>;
+/**
+ * @category responsive
+ */
 export declare function getMediaQueryWidthResolvers<TBreakpointsConfig extends GetMediaQueryWidthResolversBreakpoints>(customBreakpoints: TBreakpointsConfig): {
     max: (br: Extract<keyof TBreakpointsConfig, string>) => string;
     min: (br: Extract<keyof TBreakpointsConfig, string>) => string;

package/getMediaQueryWidthResolvers.mjs

@@ -1,4 +1,8 @@
-export function getMediaQueryWidthResolvers(customBreakpoints) {
+/**
+ * @category responsive
+ */ /**
+ * @category responsive
+ */ export function getMediaQueryWidthResolvers(customBreakpoints) {
     const breakpoints = {
         xs: 0,
         ...customBreakpoints

package/getMediaQueryWidthTailwindScreens.d.ts

@@ -1,4 +1,8 @@
 import { type GetMediaQueryWidthResolversBreakpoints } from "./getMediaQueryWidthResolvers";
+/**
+ * @category responsive
+ * @category tailwind
+ */
 export declare function getMediaQueryWidthTailwindScreens(breakpoints: GetMediaQueryWidthResolversBreakpoints): Record<string, {
     raw: string;
 }>;

package/getMediaQueryWidthTailwindScreens.mjs

@@ -1,5 +1,8 @@
 import { getMediaQueryWidthResolvers } from "./getMediaQueryWidthResolvers";
-export function getMediaQueryWidthTailwindScreens(breakpoints) {
+/**
+ * @category responsive
+ * @category tailwind
+ */ export function getMediaQueryWidthTailwindScreens(breakpoints) {
     const mqWidthResolvers = getMediaQueryWidthResolvers(breakpoints);
     // Object.keys(breakpoints).reduce((screens, br) => {
     const screens = Object.keys(breakpoints).reduce((output, br, idx)=>{

package/getParamAmong.d.ts

@@ -5,8 +5,9 @@
  *
  * @category location
  *
- * @param {string} [raw] - The _raw_ query parameter
- * @param {string[]} [allowedValues=[]] - The list of values (as strings) that the parameter can have, if not one of them `null` is returned
+ * @param raw The _raw_ query parameter
+ * @param allowedValues The list of values (as strings) that the parameter can
+ * have, if not one of them `null` is returned
  */
 export declare function getParamAmong<T extends string[]>(raw?: string | string[], allowedValues?: T): T[number] | null;
 export default getParamAmong;

package/getParamAmong.mjs

@@ -6,8 +6,9 @@ import getParamAsString from "./getParamAsString";
  *
  * @category location
  *
- * @param {string} [raw] - The _raw_ query parameter
- * @param {string[]} [allowedValues=[]] - The list of values (as strings) that the parameter can have, if not one of them `null` is returned
+ * @param raw The _raw_ query parameter
+ * @param allowedValues The list of values (as strings) that the parameter can
+ * have, if not one of them `null` is returned
  */ export function getParamAmong(raw, allowedValues = []) {
     const string = getParamAsString(raw);
     return allowedValues.includes(string) ? string : null;

package/getParamAsInt.d.ts

@@ -5,8 +5,8 @@
  *
  * @category location
  *
- * @param {string} [raw] - The _raw_ query parameter
- * @param {number} [fallback] - Fallback number, we return `null` if not provided
+ * @param raw The _raw_ query parameter
+ * @param fallback Fallback number, we return `null` if not provided
  */
 export declare function getParamAsInt<TFallback extends number | null | undefined>(raw?: string | string[], fallback?: TFallback): number | TFallback;
 export default getParamAsInt;

package/getParamAsInt.mjs

@@ -6,8 +6,8 @@ import getParamAsString from "./getParamAsString";
  *
  * @category location
  *
- * @param {string} [raw] - The _raw_ query parameter
- * @param {number} [fallback] - Fallback number, we return `null` if not provided
+ * @param raw The _raw_ query parameter
+ * @param fallback Fallback number, we return `null` if not provided
  */ export function getParamAsInt(raw, fallback = null) {
     const string = getParamAsString(raw);
     if (string) {

package/getParamAsString.d.ts

@@ -5,7 +5,7 @@
  *
  * @category location
  *
- * @param {string} [raw] - The _raw_ query parameter
+ * @param raw The _raw_ query parameter
  */
 export declare function getParamAsString(raw?: string | string[]): string;
 export default getParamAsString;

package/getParamAsString.mjs

@@ -6,7 +6,7 @@ import isArray from "./isArray";
  *
  * @category location
  *
- * @param {string} [raw] - The _raw_ query parameter
+ * @param raw The _raw_ query parameter
  */ export function getParamAsString(raw) {
     return (isArray(raw) ? raw[0] : raw) || "";
 }

package/getType.d.ts

@@ -14,9 +14,6 @@ export type PlainObject = Record<string | number | symbol, any>;
 export type TypeGuard<A, B extends A> = (payload: A) => payload is B;
 /**
  * Returns the object type of the given payload
- *
- * @param {*} payload
- * @returns {string}
  */
 export declare function getType(payload: any): string;
 export default getType;

package/getType.mjs

@@ -8,9 +8,6 @@
  * - `isFloat`
  */ /**
  * Returns the object type of the given payload
- *
- * @param {*} payload
- * @returns {string}
  */ export function getType(payload) {
     return Object.prototype.toString.call(payload).slice(8, -1);
 }

package/getUrlQueryParams.d.ts

@@ -4,10 +4,9 @@ import { type AnyQueryParams } from "./location";
  *
  * @category location
  * @param url A URL which contains a  `?`, e.g. `?myparam=x` or `https://a.com?myparams=x`.
- *                    If not provided it defaults reading the current URL query string with
- *                    `location.search`. Through this argument you can use this
- *                    same function to parse, for instance, the query params of
- *                    the `href` of a `<a href="...">` HTML tag.
+ * If not provided it defaults reading the current URL query string with
+ * `location.search`. Through this argument you can use this same function to
+ * parse, for instance, the query params of the `href` of a `<a href="...">` HTML tag.
  *
  */
 export declare function getUrlQueryParams<T extends NonNullable<AnyQueryParams>>(url?: string): T;

package/getUrlQueryParams.mjs

@@ -4,10 +4,9 @@ import isBrowser from "./isBrowser";
  *
  * @category location
  * @param url A URL which contains a  `?`, e.g. `?myparam=x` or `https://a.com?myparams=x`.
- *                    If not provided it defaults reading the current URL query string with
- *                    `location.search`. Through this argument you can use this
- *                    same function to parse, for instance, the query params of
- *                    the `href` of a `<a href="...">` HTML tag.
+ * If not provided it defaults reading the current URL query string with
+ * `location.search`. Through this argument you can use this same function to
+ * parse, for instance, the query params of the `href` of a `<a href="...">` HTML tag.
  *
  */ export function getUrlQueryParams(url) {
     let params = {};