tsu 2.3.0 → 2.4.0

package/README.md

@@ -32,7 +32,7 @@ import { ... } from 'tsu'
 
 ## Documentation
 
-Full documentation is available [here](https://tsu.eb3n.dev).
+Full documentation is available [here](https://tsu-docs.netlify.app/).
 
 ## Credits
 

package/dist/index.d.cts

@@ -0,0 +1,417 @@
+type Arrayable<T> = T | Array<T>;
+type Nullable<T> = T | null | undefined;
+type Fn<T = any> = (...args: any[]) => T;
+type VoidFn = Fn<void>;
+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 equal size.
+ *
+ * @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(array: readonly []): undefined;
+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(array: readonly []): undefined;
+declare function last<T>(array: readonly T[]): T;
+/**
+ * Splits an array into two based on a predicate function.
+ *
+ * @param filter - The predicate function.
+ * @param array - The array.
+ * @returns The tuple of values that satisfy the predicate and those that don't.
+ */
+declare function partition<T, U = T>(filter: (current: T | U, idx: number, array: readonly (T | U)[]) => boolean, array: readonly (T | U)[]): [T[], U[]];
+/**
+ * Generates a range of numbers.
+ *
+ * @param start - The inclusive start value.
+ * @param stop - The exlusive stop value.
+ * @param step - The step to increment by.
+ * @returns The range of numbers.
+ */
+declare function range(stop: number): number[];
+declare function range(start: number, stop: number, step?: number): number[];
+/**
+ * Splits an array into two at a specified index.
+ *
+ * @param i - The position to split at.
+ * @param array - The array.
+ * @returns The tuple of values before and after the split.
+ */
+declare function splitAt<T>(i: number, array: readonly T[]): [T[], T[]];
+/**
+ * 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 in 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[];
+
+interface 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;
+
+/**
+ * Prevents function execution until it hasn't been called for a specified time period.
+ *
+ * @param fn - The function.
+ * @param delay - The time period (in ms).
+ * @returns The debounced function.
+ */
+declare function debounce(fn: VoidFn, 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>;
+/**
+ * Enforces that a function is only callable one time.
+ *
+ * @param fn - The function.
+ * @returns The one-time callable function.
+ */
+declare function once(fn: VoidFn): VoidFn;
+/**
+ * Prevents function execution for a specified time period after it was last called.
+ *
+ * @param fn - The function.
+ * @param limit - The time period.
+ * @returns The throttled function.
+ */
+declare function throttle(fn: VoidFn, 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 a browser.
+ *
+ * @returns If the code is being run in 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 an empty object.
+ *
+ * @param val - The value.
+ * @returns If the value is an empty object.
+ */
+declare function isEmptyObject(val: unknown): val is Record<string, never>;
+/**
+ * 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 null.
+ *
+ * @param val - The value.
+ * @returns If the value is null.
+ */
+declare function isNull(val: unknown): val is null;
+/**
+ * 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;
+
+/**
+ * Rounds a number up to the nearest multiple of the specified factor.
+ *
+ * @param n - The number to round up.
+ * @param factor - The factor used for rounding.
+ * @returns The rounded number.
+ */
+declare function ceil(n: number, factor?: number): number;
+/**
+ * Rounds a number down to the nearest multiple of the specified factor.
+ *
+ * @param n - The number to round down.
+ * @param factor - The factor used for rounding.
+ * @returns The rounded number.
+ */
+declare function floor(n: number, factor?: number): number;
+/**
+ * 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;
+/**
+ * Returns the maximum number of an array.
+ *
+ * @param array - The array of numbers.
+ * @returns The maximum number.
+ */
+declare function max(array: readonly []): undefined;
+declare function max(array: readonly number[]): number;
+/**
+ * Returns the minimum number of an array.
+ *
+ * @param array - The array of numbers.
+ * @returns The minimum number.
+ */
+declare function min(array: readonly []): undefined;
+declare function min(array: readonly 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;
+/**
+ * Generates a random integer between bounds.
+ *
+ * @param min - The inclusive minimum bound.
+ * @param max - The exclusive maximum bound.
+ * @returns The random integer.
+ */
+declare function randomNumber(max: number): number;
+declare function randomNumber(min: number, max: number): number;
+/**
+ * Rounds a number to the nearest multiple of the specified factor.
+ *
+ * @param n - The number to round.
+ * @param factor - The factor used for rounding.
+ * @returns The rounded number.
+ */
+declare function round(n: number, factor?: number): number;
+/**
+ * Returns the sum of a number array.
+ *
+ * @param ns - The number array.
+ * @returns The sum.
+ */
+declare function sum(ns: readonly number[]): number;
+
+/**
+ * Does nothing.
+ *
+ * @returns Nothing.
+ */
+declare function noop(): void;
+/**
+ * Halts thread execution for a specified time period.
+ *
+ * @param duration - The time period (in ms).
+ * @returns The halting promise.
+ */
+declare function sleep(duration: number): Promise<void>;
+/**
+ * Generates a random string of a specified length.
+ *
+ * @param length - The length of the randomly generated string.
+ * @returns The randomly generated string.
+ */
+declare function uuid(length?: number): string;
+
+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]>;
+
+/**
+ * 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.
+ * @param delimiter - The delimiter to split the string by.
+ * @returns The capitalised string.
+ */
+declare function capitalise(str: string, allWords?: boolean, delimiter?: string): 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;
+/**
+ * Splits a string into two at a specified index.
+ *
+ * @param i - The position to split at.
+ * @param str - The string.
+ * @returns The tuple of strings before and after the split.
+ */
+declare function splitStrAt(i: number, str: string): [string, string];
+/**
+ * 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 into the number itself.
+ *
+ * @param str - The string.
+ * @returns The number.
+ */
+declare function toNumber(str: string): number;
+/**
+ * Adds the respective ordinal suffix (-st, -nd, -rd or -th) to a number.
+ *
+ * @param n - The number.
+ * @returns The number with the ordinal suffix appended.
+ */
+declare function toOrdinal(n: number): string;
+/**
+ * Truncates a string to a provided length.
+ *
+ * @param str - The string.
+ * @param length - The length.
+ * @param suffix - The suffix to apply after truncation.
+ * @returns The truncated string.
+ */
+declare function truncate(str: string, length: number, suffix?: string): string;
+
+export { type Arrayable, type Fn, type Nullable, type Obj, type VoidFn, capitalise, ceil, chars, debounce, deepMerge, drop, floor, groupsOf, head, init, isArray, isBlank, isBoolean, isBrowser, isDefined, isEmpty, isEmptyObject, isEven, isFunction, isNull, isNumber, isObject, isOdd, isString, isTouchDevice, isWindow, last, max, memoize, min, noop, once, partition, randomChance, randomNumber, range, round, scroll, sleep, splitAt, splitStrAt, sum, tail, take, throttle, toArray, toCamel, toKebab, toNumber, toOrdinal, truncate, uniq, uuid };

package/dist/index.d.ts

@@ -414,4 +414,4 @@ declare function toOrdinal(n: number): string;
  */
 declare function truncate(str: string, length: number, suffix?: string): string;
 
-export { Arrayable, Fn, Nullable, Obj, VoidFn, capitalise, ceil, chars, debounce, deepMerge, drop, floor, groupsOf, head, init, isArray, isBlank, isBoolean, isBrowser, isDefined, isEmpty, isEmptyObject, isEven, isFunction, isNull, isNumber, isObject, isOdd, isString, isTouchDevice, isWindow, last, max, memoize, min, noop, once, partition, randomChance, randomNumber, range, round, scroll, sleep, splitAt, splitStrAt, sum, tail, take, throttle, toArray, toCamel, toKebab, toNumber, toOrdinal, truncate, uniq, uuid };
+export { type Arrayable, type Fn, type Nullable, type Obj, type VoidFn, capitalise, ceil, chars, debounce, deepMerge, drop, floor, groupsOf, head, init, isArray, isBlank, isBoolean, isBrowser, isDefined, isEmpty, isEmptyObject, isEven, isFunction, isNull, isNumber, isObject, isOdd, isString, isTouchDevice, isWindow, last, max, memoize, min, noop, once, partition, randomChance, randomNumber, range, round, scroll, sleep, splitAt, splitStrAt, sum, tail, take, throttle, toArray, toCamel, toKebab, toNumber, toOrdinal, truncate, uniq, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsu",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "TypeScript utilities",
   "license": "MIT",
@@ -35,17 +35,17 @@
     "prepublishOnly": "nr test; nr build"
   },
   "devDependencies": {
-    "@antfu/ni": "^0.17.2",
-    "@typescript-eslint/eslint-plugin": "^5.33.0",
-    "@typescript-eslint/parser": "^5.33.0",
-    "eslint": "^8.22.0",
-    "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "prettier": "^2.7.1",
-    "tsup": "^6.2.2",
-    "typescript": "^4.7.4",
-    "vite": "^4.3.8",
-    "vitepress": "1.0.0-alpha.35",
-    "vitest": "^0.26.3"
+    "@antfu/ni": "^0.21.12",
+    "@typescript-eslint/eslint-plugin": "^6.16.0",
+    "@typescript-eslint/parser": "^6.16.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.2",
+    "prettier": "^3.1.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.10",
+    "vitepress": "^1.0.0-rc.33",
+    "vitest": "^1.1.0"
   }
 }