tsu 1.0.2 → 1.1.2

package/dist/index.d.ts

@@ -1,9 +1,342 @@
-export * from './array';
-export * from './function';
-export * from './is';
-export * from './maths';
-export * from './misc';
-export * from './object';
-export * from './scroll';
-export * from './string';
-export * from './types';
+declare type Arrayable<T> = T | Array<T>;
+declare type Nullable<T> = T | null | undefined;
+declare type Fn<T = any> = (...args: any[]) => T;
+declare type VoidFn = Fn<void>;
+declare type Obj<V = unknown> = Record<string | symbol | number, V>;
+
+/**
+ * Removes the first n items of an array.
+ *
+ * @param n - The number of items to remove.
+ * @param array - The array.
+ * @returns The remaining items.
+ */
+declare function drop<T>(n: number, array: readonly T[]): T[];
+/**
+ * Splits an array into groups of size s.
+ *
+ * @param s - The size of each group.
+ * @param array - The array.
+ * @returns The array split into groups.
+ */
+declare function groupsOf<T>(s: number, array: readonly T[]): T[][];
+/**
+ * Returns the first item of an array.
+ *
+ * @param array - The array.
+ * @returns The first item.
+ */
+declare function head<T>(array: readonly T[]): T;
+/**
+ * Returns all but the last item of an array.
+ *
+ * @param array - The array.
+ * @returns The array without the last item.
+ */
+declare function init<T>(array: readonly T[]): T[];
+/**
+ * Returns the last item of an array.
+ *
+ * @param array - The array.
+ * @returns The last item.
+ */
+declare function last<T>(array: readonly T[]): T;
+/**
+ * Returns the maximum number of an array.
+ *
+ * @param array - The array of numbers.
+ * @returns The maximum number.
+ */
+declare function max(array: readonly number[]): number | undefined;
+/**
+ * Returns the minimum number of an array.
+ *
+ * @param array - The array of numbers.
+ * @returns The minimum number.
+ */
+declare function min(array: readonly number[]): number | undefined;
+/**
+ * Splits an array into two based on a predicate function.
+ *
+ * @param filter - The predicate function.
+ * @param array - The array.
+ * @returns The array split in two.
+ */
+declare function partition<T>(filter: (x: T, idx: number, a: readonly T[]) => boolean, array: readonly T[]): [T[], T[]];
+/**
+ * Splits an array into two at a given index.
+ *
+ * @param i - The position to split at.
+ * @param array - The array.
+ * @returns The array split in two.
+ */
+declare function splitAt<T>(i: number, array: readonly T[]): [T[], T[]];
+/**
+ * Returns the sum of the numbers of an array.
+ *
+ * @param array - The array of numbers.
+ * @returns The sum.
+ */
+declare function sum(array: readonly number[]): number;
+/**
+ * Returns all but the first item of an array.
+ *
+ * @param array - The array.
+ * @returns The array without the first item.
+ */
+declare function tail<T>(array: readonly T[]): T[];
+/**
+ * Returns the first n items of an array.
+ *
+ * @param n - The number of items to return.
+ * @param array - The array.
+ * @returns The first n items.
+ */
+declare function take<T>(n: number, array: readonly T[]): T[];
+/**
+ * Wraps a single value of an array, if not already an array.
+ *
+ * @param maybeArray - The value to wrap, or the existing array.
+ * @returns The item wrapped in an array, or the provided array.
+ */
+declare function toArray<T>(maybeArray: Nullable<Arrayable<T>>): T[];
+/**
+ * Removes duplicate primitive values from an array.
+ *
+ * @param array - The array.
+ * @returns The array without duplicated primitive values.
+ */
+declare function uniq<T>(array: readonly T[]): T[];
+
+/**
+ * Prevents a function from running until it hasn't been called for a certain time period.
+ *
+ * @param fn - The function.
+ * @param delay - The time period (in ms).
+ * @returns The debounced function.
+ */
+declare function debounce(fn: Fn, delay: number): VoidFn;
+/**
+ * Optimises subsequent calls of a function by caching return values.
+ *
+ * @param fn - The function.
+ * @returns The memoized function.
+ */
+declare function memoize<T>(fn: Fn<T>): Fn<T>;
+/**
+ * Prevents a function from running for some time period after it was last called.
+ *
+ * @param fn - The function.
+ * @param limit - The time period.
+ * @returns The throttled function.
+ */
+declare function throttle(fn: Fn, limit: number): VoidFn;
+
+/**
+ * Identifies if a value is an array.
+ *
+ * @param val - The value.
+ * @returns If the value is an array.
+ */
+declare function isArray(val: unknown): val is any[];
+/**
+ * Identifies if a value is a boolean.
+ *
+ * @param val - The value.
+ * @returns If the value is a boolean.
+ */
+declare function isBoolean(val: unknown): val is boolean;
+/**
+ * Identifies if the code is being run in the browser.
+ *
+ * @returns If the code is being run on a browser.
+ */
+declare function isBrowser(): boolean;
+/**
+ * Identifies if a value is defined.
+ *
+ * @param val - The value.
+ * @returns If the value is defined.
+ */
+declare function isDefined<T = unknown>(val?: T): val is T;
+/**
+ * Identifies if a value is a function.
+ *
+ * @param val - The value.
+ * @returns If the value is a function.
+ */
+declare function isFunction<T extends Fn>(val: unknown): val is T;
+/**
+ * Identifies if a value is a number.
+ *
+ * @param val - The value.
+ * @returns If the value is a number.
+ */
+declare function isNumber(val: unknown): val is number;
+/**
+ * Identifies if a value is an object.
+ *
+ * @param val - The value.
+ * @returns If the value is an object.
+ */
+declare function isObject(val: unknown): val is Obj;
+/**
+ * Identifies if a value is a string.
+ *
+ * @param val - The value.
+ * @returns If the value is a string.
+ */
+declare function isString(val: unknown): val is string;
+/**
+ * Identifies if the code is being run on a touch device.
+ *
+ * @returns If the code is being run on a touch device.
+ */
+declare function isTouchDevice(): boolean;
+/**
+ * Identifies if a value is the global window.
+ *
+ * @param val - The value.
+ * @returns If the value is the global window.
+ */
+declare function isWindow(val: unknown): val is Window;
+
+/**
+ * Identifies if a number is even.
+ *
+ * @param n - The number.
+ * @returns If the number is even.
+ */
+declare function isEven(n: number): boolean;
+/**
+ * Identifies if a number is odd.
+ *
+ * @param n - The number.
+ * @returns If the number is odd.
+ */
+declare function isOdd(n: number): boolean;
+/**
+ * Opinionated implementation of modulo (%).
+ *
+ * @param n - The dividend.
+ * @param m - The divisor.
+ * @returns The remainder of dividing n by m.
+ */
+declare function modulo(n: number, m: number): number;
+/**
+ * Generates a random integer between bounds.
+ *
+ * @param max - The exclusive maximum bound.
+ * @param min - The inclusive minimum bound.
+ * @returns The random integer.
+ */
+declare function randomNumber(max: number, min?: number): number;
+/**
+ * Rolls an n-sided die.
+ *
+ * @param n - The number of sides on the die.
+ * @returns If the die roll was 0.
+ */
+declare function randomChance(n: number): boolean;
+
+/**
+ * Does nothing.
+ *
+ * @returns Nothing.
+ */
+declare function noop(): void;
+/**
+ * Halts program execution for a specified time.
+ *
+ * @param duration - The time to wait (in ms).
+ * @returns The halting promise.
+ */
+declare function sleep(duration: number): Promise<void>;
+
+declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Recursively merges multiple objects into one.
+ *
+ * @param objects - The objects to merge.
+ * @returns The merged object.
+ */
+declare function deepMerge<T extends Obj<any>[]>(...objects: T): UnionToIntersection<T[number]>;
+
+declare type ScrollConfig = {
+    to: Element | string | number;
+    offset?: number;
+    duration?: number;
+    container?: Element | string | null;
+};
+/**
+ * Scrolls the page or provided container to a target element or y-coordinate.
+ *
+ * @param config - The scroll config.
+ * @param config.to - The scroll target.
+ * @param config.offset - The offset from the scroll target (in px).
+ * @param config.duration - The scroll duration (in ms).
+ * @param config.container - The container to scroll in.
+ */
+declare function scroll({ to, offset, duration, container }: ScrollConfig): void;
+
+/**
+ * Capitalises the first letter of one word, or all words, in a string.
+ *
+ * @param str - The string.
+ * @param allWords - If all words should be capitalised.
+ * @returns The capitalised string.
+ */
+declare function capitalise(str: string, allWords?: boolean): string;
+/**
+ * Separates a string into an array of characters.
+ *
+ * @param str - The string.
+ * @returns The string's characters.
+ */
+declare function chars(str: string): string[];
+/**
+ * Identifies strings which only contain whitespace.
+ *
+ * @param str - The string.
+ * @returns If the string is blank.
+ */
+declare function isBlank(str: string): boolean;
+/**
+ * Identifies empty strings.
+ *
+ * @param str - The string.
+ * @returns If the string is empty.
+ */
+declare function isEmpty(str: string): boolean;
+/**
+ * Converts a kebab case string to camel case.
+ *
+ * @param str - The kebab case string.
+ * @returns The camel case string.
+ */
+declare function toCamel(str: string): string;
+/**
+ * Converts a camel case string to kebab case.
+ *
+ * @param str - The camel case string.
+ * @returns The kebab case string.
+ */
+declare function toKebab(str: string): string;
+/**
+ * Converts a string which contains a number to the number itself.
+ *
+ * @param str - The string.
+ * @returns The number.
+ */
+declare function toNumber(str: string): number;
+/**
+ * Truncates a string to a provided length.
+ *
+ * @param str - The string.
+ * @param length - The length.
+ * @param truncateStr - The prefix to apply after truncation.
+ * @returns The truncated string.
+ */
+declare function truncate(str: string, length: number, truncateStr?: string): string;
+
+export { Arrayable, Fn, Nullable, Obj, VoidFn, capitalise, chars, debounce, deepMerge, drop, groupsOf, head, init, isArray, isBlank, isBoolean, isBrowser, isDefined, isEmpty, isEven, isFunction, isNumber, isObject, isOdd, isString, isTouchDevice, isWindow, last, max, memoize, min, modulo, noop, partition, randomChance, randomNumber, scroll, sleep, splitAt, sum, tail, take, throttle, toArray, toCamel, toKebab, toNumber, truncate, uniq };