@welshman/lib 0.0.32 → 0.0.33

package/build/src/Tools.d.ts

@@ -1,136 +1,577 @@
+/** Type representing null or undefined */
 export type Nil = null | undefined;
+/** Checks if a value is null or undefined */
 export declare const isNil: (x: any) => boolean;
+/** Type representing an optional value */
 export type Maybe<T> = T | undefined;
+/**
+ * Executes a function if the value is defined
+ * @param x - The value to check
+ * @param f - Function to execute if x is defined
+ * @returns Result of f(x) if x is defined, undefined otherwise
+ */
 export declare const ifLet: <T>(x: T | undefined, f: (x: T) => void) => void;
+/** Function that does nothing and returns undefined */
 export declare const noop: (...args: unknown[]) => undefined;
+/**
+ * Returns the first element of an array
+ * @param xs - The array
+ * @returns First element or undefined
+ */
 export declare const first: <T>(xs: T[], ...args: unknown[]) => T;
+/**
+ * Returns the first element of the first array in a nested array
+ * @param xs - Array of arrays
+ * @returns First element of first array or undefined
+ */
 export declare const ffirst: <T>(xs: T[][], ...args: unknown[]) => T;
+/**
+ * Returns the last element of an array
+ * @param xs - The array
+ * @returns Last element or undefined
+ */
 export declare const last: <T>(xs: T[], ...args: unknown[]) => T;
+/**
+ * Returns the input value unchanged
+ * @param x - Any value
+ * @returns The same value
+ */
 export declare const identity: <T>(x: T, ...args: unknown[]) => T;
+/**
+ * Creates a function that always returns the same value
+ * @param x - Value to return
+ * @returns Function that returns x
+ */
 export declare const always: <T>(x: T, ...args: unknown[]) => () => T;
+/**
+ * Returns the logical NOT of a value
+ * @param x - Value to negate
+ * @returns !x
+ */
 export declare const not: (x: any, ...args: unknown[]) => boolean;
+/** Converts a Maybe<number> to a number, defaulting to 0 */
 export declare const num: (x: Maybe<number>) => number;
+/** Adds two numbers, handling undefined values */
 export declare const add: (x: Maybe<number>, y: Maybe<number>) => number;
+/** Subtracts two numbers, handling undefined values */
 export declare const sub: (x: Maybe<number>, y: Maybe<number>) => number;
+/** Multiplies two numbers, handling undefined values */
 export declare const mul: (x: Maybe<number>, y: Maybe<number>) => number;
+/** Divides two numbers, handling undefined values */
 export declare const div: (x: Maybe<number>, y: number) => number;
+/** Increments a number by 1, handling undefined values */
 export declare const inc: (x: Maybe<number>) => number;
+/** Decrements a number by 1, handling undefined values */
 export declare const dec: (x: Maybe<number>) => number;
+/** Less than comparison, handling undefined values */
 export declare const lt: (x: Maybe<number>, y: Maybe<number>) => boolean;
+/** Less than or equal comparison, handling undefined values */
 export declare const lte: (x: Maybe<number>, y: Maybe<number>) => boolean;
+/** Greater than comparison, handling undefined values */
 export declare const gt: (x: Maybe<number>, y: Maybe<number>) => boolean;
+/** Greater than or equal comparison, handling undefined values */
 export declare const gte: (x: Maybe<number>, y: Maybe<number>) => boolean;
+/** Returns maximum value in array, handling undefined values */
 export declare const max: (xs: Maybe<number>[]) => number;
+/** Returns minimum value in array, handling undefined values */
 export declare const min: (xs: Maybe<number>[]) => number;
+/** Returns sum of array values, handling undefined values */
 export declare const sum: (xs: Maybe<number>[]) => number;
+/** Returns average of array values, handling undefined values */
 export declare const avg: (xs: Maybe<number>[]) => number;
+/**
+ * Returns array with first n elements removed
+ * @param n - Number of elements to drop
+ * @param xs - Input array
+ * @returns Array with first n elements removed
+ */
 export declare const drop: <T>(n: number, xs: T[]) => T[];
+/**
+ * Returns first n elements of array
+ * @param n - Number of elements to take
+ * @param xs - Input array
+ * @returns Array of first n elements
+ */
 export declare const take: <T>(n: number, xs: T[]) => T[];
+/**
+ * Creates new object with specified keys removed
+ * @param ks - Keys to remove
+ * @param x - Source object
+ * @returns New object without specified keys
+ */
 export declare const omit: <T extends Record<string, any>>(ks: string[], x: T) => T;
+/**
+ * Creates new object excluding entries with specified values
+ * @param xs - Values to exclude
+ * @param x - Source object
+ * @returns New object without entries containing specified values
+ */
 export declare const omitVals: <T extends Record<string, any>>(xs: any[], x: T) => T;
+/**
+ * Creates new object with only specified keys
+ * @param ks - Keys to keep
+ * @param x - Source object
+ * @returns New object with only specified keys
+ */
 export declare const pick: <T extends Record<string, any>>(ks: string[], x: T) => T;
+/**
+ * Generates sequence of numbers from a to b
+ * @param a - Start number (inclusive)
+ * @param b - End number (exclusive)
+ * @param step - Increment between numbers
+ * @yields Numbers in sequence
+ */
 export declare function range(a: number, b: number, step?: number): Generator<number, void, unknown>;
+/**
+ * Creates new object with transformed keys
+ * @param f - Function to transform keys
+ * @param x - Source object
+ * @returns Object with transformed keys
+ */
 export declare const mapKeys: <T extends Record<string, any>>(f: (v: string) => string, x: T) => T;
+/**
+ * Creates new object with transformed values
+ * @param f - Function to transform values
+ * @param x - Source object
+ * @returns Object with transformed values
+ */
 export declare const mapVals: <V, U>(f: (v: V) => U, x: Record<string, V>) => Record<string, U>;
+/**
+ * Merges two objects, with left object taking precedence
+ * @param a - Left object
+ * @param b - Right object
+ * @returns Merged object with a's properties overriding b's
+ */
 export declare const mergeLeft: <T extends Record<string, any>>(a: T, b: T) => T;
+/**
+ * Merges two objects, with right object taking precedence
+ * @param a - Left object
+ * @param b - Right object
+ * @returns Merged object with b's properties overriding a's
+ */
 export declare const mergeRight: <T extends Record<string, any>>(a: T, b: T) => T;
+/**
+ * Checks if a number is between two values (exclusive)
+ * @param bounds - Lower and upper bounds
+ * @param n - Number to check
+ * @returns True if n is between low and high
+ */
 export declare const between: ([low, high]: [number, number], n: number) => boolean;
+/**
+ * Checks if a number is between two values (inclusive)
+ * @param bounds - Lower and upper bounds
+ * @param n - Number to check
+ * @returns True if n is between low and high
+ */
+export declare const within: ([low, high]: [number, number], n: number) => boolean;
+/**
+ * Generates random integer between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Random integer
+ */
 export declare const randomInt: (min?: number, max?: number) => number;
+/**
+ * Generates random string ID
+ * @returns Random string suitable for use as an ID
+ */
 export declare const randomId: () => string;
+/**
+ * Removes protocol (http://, https://, etc) from URL
+ * @param url - URL to process
+ * @returns URL without protocol
+ */
 export declare const stripProtocol: (url: string) => string;
+/**
+ * Formats URL for display by removing protocol, www, and trailing slash
+ * @param url - URL to format
+ * @returns Formatted URL
+ */
 export declare const displayUrl: (url: string) => string;
+/**
+ * Extracts and formats domain from URL
+ * @param url - URL to process
+ * @returns Formatted domain name
+ */
 export declare const displayDomain: (url: string) => string;
+/**
+ * Creates a promise that resolves after specified time
+ * @param t - Time in milliseconds
+ * @returns Promise that resolves after t milliseconds
+ */
 export declare const sleep: (t: number) => Promise<unknown>;
+/**
+ * Concatenates multiple arrays, filtering out null/undefined
+ * @param xs - Arrays to concatenate
+ * @returns Combined array
+ */
 export declare const concat: <T>(...xs: T[][]) => T[];
+/**
+ * Appends element to array
+ * @param x - Element to append
+ * @param xs - Array to append to
+ * @returns New array with element appended
+ */
 export declare const append: <T>(x: T, xs: T[]) => T[];
+/**
+ * Creates union of two arrays
+ * @param a - First array
+ * @param b - Second array
+ * @returns Array containing unique elements from both arrays
+ */
 export declare const union: <T>(a: T[], b: T[]) => T[];
+/**
+ * Returns elements common to both arrays
+ * @param a - First array
+ * @param b - Second array
+ * @returns Array of elements present in both inputs
+ */
 export declare const intersection: <T>(a: T[], b: T[]) => T[];
+/**
+ * Returns elements in first array not present in second
+ * @param a - Source array
+ * @param b - Array of elements to exclude
+ * @returns Array containing elements unique to first array
+ */
 export declare const difference: <T>(a: T[], b: T[]) => T[];
+/**
+ * Removes all instances of an element from array
+ * @param a - Element to remove
+ * @param xs - Source array
+ * @returns New array with element removed
+ */
 export declare const remove: <T>(a: T, xs: T[]) => T[];
+/**
+ * Returns elements from second array not present in first
+ * @param a - Array of elements to exclude
+ * @param b - Source array
+ * @returns Filtered array
+ */
 export declare const without: <T>(a: T[], b: T[]) => T[];
+/**
+ * Toggles presence of element in array
+ * @param x - Element to toggle
+ * @param xs - Source array
+ * @returns New array with element added or removed
+ */
 export declare const toggle: <T>(x: T, xs: T[]) => T[];
+/**
+ * Constrains number between min and max values
+ * @param bounds - Minimum and maximum allowed values
+ * @param n - Number to clamp
+ * @returns Clamped value
+ */
 export declare const clamp: ([min, max]: [number, number], n: number) => number;
+/**
+ * Safely parses JSON string
+ * @param json - JSON string to parse
+ * @returns Parsed object or null if invalid
+ */
 export declare const parseJson: (json: string | Nil) => any;
+/**
+ * Gets and parses JSON from localStorage
+ * @param k - Storage key
+ * @returns Parsed value or undefined if invalid/missing
+ */
 export declare const getJson: (k: string) => any;
+/**
+ * Stringifies and stores value in localStorage
+ * @param k - Storage key
+ * @param v - Value to store
+ */
 export declare const setJson: (k: string, v: any) => void;
+/**
+ * Safely executes function and handles errors
+ * @param f - Function to execute
+ * @param onError - Optional error handler
+ * @returns Function result or undefined if error
+ */
 export declare const tryCatch: <T>(f: () => T, onError?: ((e: Error) => void) | undefined) => T | undefined;
+/**
+ * Truncates string to length, breaking at word boundaries
+ * @param s - String to truncate
+ * @param l - Maximum length
+ * @param suffix - String to append if truncated
+ * @returns Truncated string
+ */
 export declare const ellipsize: (s: string, l: number, suffix?: string) => string;
+/**
+ * Checks if value is a plain object
+ * @param obj - Value to check
+ * @returns True if value is a plain object
+ */
 export declare const isPojo: (obj: any) => boolean;
+/**
+ * Deep equality comparison
+ * @param a - First value
+ * @param b - Second value
+ * @returns True if values are deeply equal
+ */
 export declare const equals: (a: any, b: any) => boolean;
+/** Returns a function that gets the nth element of an array */
 export declare const nth: (i: number) => <T>(xs: T[], ...args: unknown[]) => T;
+/** Returns a function that checks if nth element equals value */
 export declare const nthEq: (i: number, v: any) => (xs: any[], ...args: unknown[]) => boolean;
+/** Returns a function that checks if nth element does not equal value */
 export declare const nthNe: (i: number, v: any) => (xs: any[], ...args: unknown[]) => boolean;
+/** Returns a function that checks equality with value */
 export declare const eq: <T>(v: T) => (x: T) => boolean;
+/** Returns a function that checks inequality with value */
 export declare const ne: <T>(v: T) => (x: T) => boolean;
+/** Returns a function that gets property value from object */
 export declare const prop: (k: string) => <T>(x: Record<string, T>) => T;
+/** Returns a function that adds/updates property on object */
 export declare const assoc: <K extends string, T, U>(k: K, v: T) => (o: U) => U & Record<K, T>;
+/** Generates a hash string from input string */
 export declare const hash: (s: string) => string;
+/** Splits array into two parts at index */
 export declare const splitAt: <T>(n: number, xs: T[]) => T[][];
+/** Inserts element into array at index */
 export declare const insert: <T>(n: number, x: T, xs: T[]) => T[];
+/** Returns random element from array */
 export declare const choice: <T>(xs: T[]) => T;
+/** Returns shuffled copy of iterable */
 export declare const shuffle: <T>(xs: Iterable<T>) => T[];
+/** Returns n random elements from array */
 export declare const sample: <T>(n: number, xs: T[]) => T[];
+/** Checks if value is iterable */
 export declare const isIterable: (x: any) => boolean;
+/** Ensures value is iterable by wrapping in array if needed */
 export declare const toIterable: (x: any) => any;
+/** Ensures value is array by wrapping if needed */
 export declare const ensurePlural: <T>(x: T | T[]) => T[];
+/** Converts string or number to number */
 export declare const ensureNumber: (x: number | string) => number;
+/**
+ * Creates object from array of key-value pairs
+ * @param pairs - Array of [key, value] tuples
+ * @returns Object with keys and values from pairs
+ */
 export declare const fromPairs: <T>(pairs: [k?: string | undefined, v?: T | undefined, ...args: unknown[]][]) => Record<string, T>;
+/**
+ * Flattens array of arrays into single array
+ * @param xs - Array of arrays to flatten
+ * @returns Flattened array
+ */
 export declare const flatten: <T>(xs: T[][]) => T[];
+/**
+ * Splits array into two arrays based on predicate
+ * @param f - Function to test elements
+ * @param xs - Array to partition
+ * @returns Tuple of [matching, non-matching] arrays
+ */
 export declare const partition: <T>(f: (x: T) => boolean, xs: T[]) => T[][];
+/**
+ * Returns array with duplicate elements removed
+ * @param xs - Array with possible duplicates
+ * @returns Array with unique elements
+ */
 export declare const uniq: <T>(xs: T[]) => T[];
+/**
+ * Returns array with elements unique by key function
+ * @param f - Function to generate key for each element
+ * @param xs - Input array
+ * @returns Array with elements unique by key
+ */
 export declare const uniqBy: <T>(f: (x: T) => any, xs: T[]) => T[];
+/**
+ * Returns sorted copy of array
+ * @param xs - Array to sort
+ * @returns New sorted array
+ */
 export declare const sort: <T>(xs: T[]) => T[];
+/**
+ * Returns array sorted by key function
+ * @param f - Function to generate sort key
+ * @param xs - Array to sort
+ * @returns Sorted array
+ */
 export declare const sortBy: <T>(f: (x: T) => any, xs: T[]) => T[];
+/**
+ * Groups array elements by key function
+ * @param f - Function to generate group key
+ * @param xs - Array to group
+ * @returns Map of groups
+ */
 export declare const groupBy: <T, K>(f: (x: T) => K, xs: T[]) => Map<K, T[]>;
+/**
+ * Creates map from array using key function
+ * @param f - Function to generate key
+ * @param xs - Array to index
+ * @returns Map of values by key
+ */
 export declare const indexBy: <T, K>(f: (x: T) => K, xs: T[]) => Map<K, T>;
+/**
+ * Creates array of specified length using generator function
+ * @param n - Length of array
+ * @param f - Function to generate each element
+ * @returns Generated array
+ */
 export declare const initArray: <T>(n: number, f: () => T) => T[];
+/**
+ * Splits array into chunks of specified length
+ * @param chunkLength - Maximum length of each chunk
+ * @param xs - Array to split
+ * @returns Array of chunks
+ */
 export declare const chunk: <T>(chunkLength: number, xs: T[]) => T[][];
+/**
+ * Splits array into specified number of chunks
+ * @param n - Number of chunks
+ * @param xs - Array to split
+ * @returns Array of n chunks
+ */
 export declare const chunks: <T>(n: number, xs: T[]) => T[][];
+/**
+ * Creates function that only executes once
+ * @param f - Function to wrap
+ * @returns Function that executes f only on first call
+ */
 export declare const once: (f: (...args: any) => void) => (...args: any) => void;
+/**
+ * Memoizes function results based on arguments
+ * @param f - Function to memoize
+ * @returns Memoized function
+ */
 export declare const memoize: <T>(f: (...args: any[]) => T) => (...args: any[]) => T;
+/**
+ * Creates throttled version of function
+ * @param ms - Minimum time between calls
+ * @param f - Function to throttle
+ * @returns Throttled function
+ */
 export declare const throttle: <F extends (...args: any[]) => any>(ms: number, f: F) => F | ((...thisArgs: Parameters<F>) => void);
+/**
+ * Creates throttled function that returns cached value
+ * @param ms - Minimum time between updates
+ * @param f - Function to throttle
+ * @returns Function returning latest value
+ */
 export declare const throttleWithValue: <T>(ms: number, f: () => T) => () => T;
+/**
+ * Creates batching function that collects items
+ * @param t - Time window for batching
+ * @param f - Function to process batch
+ * @returns Function that adds items to batch
+ */
 export declare const batch: <T>(t: number, f: (xs: T[]) => void) => (x: T) => void;
+/**
+ * Creates batching function that returns results
+ * @param t - Time window for batching
+ * @param execute - Function to process batch
+ * @returns Function that returns promise of result
+ */
 export declare const batcher: <T, U>(t: number, execute: (request: T[]) => U[] | Promise<U[]>) => (request: T) => Promise<U>;
+/**
+ * Adds value to Set at key in object
+ * @param m - Object mapping keys to Sets
+ * @param k - Key to add to
+ * @param v - Value to add
+ */
 export declare const addToKey: <T>(m: Record<string, Set<T>>, k: string, v: T) => void;
+/**
+ * Pushes value to array at key in object
+ * @param m - Object mapping keys to arrays
+ * @param k - Key to push to
+ * @param v - Value to push
+ */
 export declare const pushToKey: <T>(m: Record<string, T[]>, k: string, v: T) => void;
+/**
+ * Adds value to Set at key in Map
+ * @param m - Map of Sets
+ * @param k - Key to add to
+ * @param v - Value to add
+ */
 export declare const addToMapKey: <K, T>(m: Map<K, Set<T>>, k: K, v: T) => void;
+/**
+ * Pushes value to array at key in Map
+ * @param m - Map of arrays
+ * @param k - Key to push to
+ * @param v - Value to push
+ */
 export declare const pushToMapKey: <K, T>(m: Map<K, T[]>, k: K, v: T) => void;
+/**
+ * Switches on key in object, with default fallback
+ * @param k - Key to look up
+ * @param m - Object with values and optional default
+ * @returns Value at key or default value
+ */
 export declare const switcher: <T>(k: string, m: Record<string, T>) => T;
+/** One minute in seconds */
 export declare const MINUTE = 60;
+/** One hour in seconds */
 export declare const HOUR: number;
+/** One day in seconds */
 export declare const DAY: number;
+/** One week in seconds */
 export declare const WEEK: number;
+/** One month in seconds (approximate) */
 export declare const MONTH: number;
+/** One quarter in seconds (approximate) */
 export declare const QUARTER: number;
+/** One year in seconds (approximate) */
 export declare const YEAR: number;
+/**
+ * Multiplies time unit by count
+ * @param unit - Time unit in seconds
+ * @param count - Number of units
+ * @returns Total seconds
+ */
 export declare const int: (unit: number, count?: number) => number;
+/** Returns current Unix timestamp in seconds */
 export declare const now: () => number;
+/**
+ * Returns Unix timestamp from specified time ago
+ * @param unit - Time unit in seconds
+ * @param count - Number of units
+ * @returns Timestamp in seconds
+ */
 export declare const ago: (unit: number, count?: number) => number;
+/**
+ * Converts seconds to milliseconds
+ * @param seconds - Time in seconds
+ * @returns Time in milliseconds
+ */
 export declare const ms: (seconds: number) => number;
+/** Options for fetch requests */
 type FetchOpts = {
     method?: string;
     headers?: Record<string, string | boolean>;
     body?: string | FormData;
 };
+/**
+ * Fetches JSON from URL with options
+ * @param url - URL to fetch from
+ * @param opts - Fetch options
+ * @returns Promise of parsed JSON response
+ */
 export declare const fetchJson: (url: string, opts?: FetchOpts) => Promise<any>;
+/**
+ * Posts JSON data to URL
+ * @param url - URL to post to
+ * @param data - Data to send
+ * @param opts - Additional fetch options
+ * @returns Promise of parsed JSON response
+ */
 export declare const postJson: <T>(url: string, data: T, opts?: FetchOpts) => Promise<any>;
-export declare const uploadFile: (url: string, fileObj: File) => Promise<any>;
-export declare const hexToBech32: (prefix: string, url: string) => `${Lowercase<string>}1${string}`;
+/**
+ * Uploads file to URL
+ * @param url - Upload URL
+ * @param file - File to upload
+ * @returns Promise of parsed JSON response
+ */
+export declare const uploadFile: (url: string, file: File) => Promise<any>;
+/**
+ * Converts hex string to bech32 format
+ * @param prefix - Bech32 prefix
+ * @param hex - Hex string to convert
+ * @returns Bech32 encoded string
+ */
+export declare const hexToBech32: (prefix: string, hex: string) => `${Lowercase<string>}1${string}`;
+/**
+ * Converts bech32 string to hex format
+ * @param b32 - Bech32 string to convert
+ * @returns Hex encoded string
+ */
 export declare const bech32ToHex: (b32: string) => string;
-export type OmitStatics<T, S extends string> = T extends {
-    new (...args: infer A): infer R;
-} ? {
-    new (...args: A): R;
-} & Omit<T, S> : Omit<T, S>;
-export type OmitAllStatics<T extends {
-    new (...args: any[]): any;
-    prototype: any;
-}> = T extends {
-    new (...args: infer A): infer R;
-    prototype: infer P;
-} ? {
-    new (...args: A): R;
-    prototype: P;
-} : never;
 export {};