Skip to main content

Module: @sapphire/utilities

Interfaces

References

filterNullAndUndefined

Renames and re-exports filterNullish


filterNullAndUndefinedAndEmpty

Renames and re-exports filterNullishOrEmpty


filterNullAndUndefinedAndZero

Renames and re-exports filterNullishOrZero


isNullOrUndefined

Renames and re-exports isNullish


isNullOrUndefinedOrEmpty

Renames and re-exports isNullishOrEmpty


isNullOrUndefinedOrZero

Renames and re-exports isNullishOrZero

Type aliases

AbstractConstructor

Ζ¬ AbstractConstructor<T>: (...args: any[]) => T

Type parameters

Name
T

Type declaration

β€’ (...args)

A generic abstract constructor without parameters

Parameters
NameType
...argsany[]

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:64


AbstractCtor

Ζ¬ AbstractCtor<A, R>: (...args: A) => R

Type parameters

NameType
Aextends Arr = readonly any[]
Rany

Type declaration

β€’ (...args)

A generic abstract constructor with parameters

Parameters
NameType
...argsA

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:54


ArgumentTypes

Ζ¬ ArgumentTypes<F>: F extends (...args: infer A) => any ? A : never

Type parameters

NameType
Fextends (...args: any[]) => unknown

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:38


Arr

Ζ¬ Private Arr: readonly any[]

A readonly array of any values.

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:44


ArrayElementType

Ζ¬ ArrayElementType<T>: T extends infer K[] ? K : T extends readonly infer RK[] ? RK : T

Gets a union type of all the keys that are in an array.

example

const sample = [1, 2, '3', true];

type arrayUnion = ArrayElementType<typeof sample>;
// Expected: string | number | boolean

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:175


Awaitable

Ζ¬ Awaitable<T>: PromiseLike<T> | T

ReturnType for a function that can return either a value or a Promise with that value

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:79


Builtin

Ζ¬ Builtin: Primitive | Function | Date | Error | RegExp

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:4


Constructor

Ζ¬ Constructor<T>: (...args: any[]) => T

Type parameters

Name
T

Type declaration

β€’ (...args)

A generic constructor without parameters

Parameters
NameType
...argsany[]

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:59


Ctor

Ζ¬ Ctor<A, R>: (...args: A) => R

Type parameters

NameType
Aextends Arr = readonly any[]
Rany

Type declaration

β€’ (...args)

A generic constructor with parameters

Parameters
NameType
...argsA

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:49


DeepPartial

Ζ¬ DeepPartial<T>: { [P in keyof T]?: T[P] extends infer U[] ? DeepPartial<U>[] : T[P] extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : DeepPartial<T[P]> }

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:30


DeepRequired

Ζ¬ DeepRequired<T>: T extends Builtin ? NonNullable<T> : T extends Map<infer K, infer V> ? Map<DeepRequired<K>, DeepRequired<V>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<DeepRequired<K>, DeepRequired<V>> : T extends WeakMap<infer K, infer V> ? WeakMap<DeepRequired<K>, DeepRequired<V>> : T extends Set<infer U> ? Set<DeepRequired<U>> : T extends ReadonlySet<infer U> ? ReadonlySet<DeepRequired<U>> : T extends WeakSet<infer U> ? WeakSet<DeepRequired<U>> : T extends Promise<infer U> ? Promise<DeepRequired<U>> : T extends {} ? { [K in keyof T]-?: DeepRequired<T[K]> } : NonNullable<T>

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:6


FirstArgument

Ζ¬ FirstArgument<T>: T extends (arg1: infer U, ...args: unknown[]) => unknown ? U : unknown

Gets the first argument of any given function

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:69


Mutable

Ζ¬ Mutable<T>: { -readonly [P in keyof T]: T[P] extends unknown[] | NonNullObject ? Mutable<T[P]> : T[P] }

Transforms a readonly type to be mutable

example

interface Sample {
id: string;
hobbies: readonly string[];
}

type BB = Mutable<Sample>;
// Expected:
// {
// id: string;
// hobbies: string[];
// }

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:138


NonNullableProperties

Ζ¬ NonNullableProperties<T>: { [P in keyof T]: NonNullable<T[P]> }

Similar to the built in {@link NonNullable}, but properly removes null from all keys in the class or interface This does not recurse deeply, for that use DeepRequired

Type parameters

NameType
Tunknown

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:90


Nullish

Ζ¬ Nullish: null | undefined

Type union for the full 2 billion dollar mistake in the JavaScript ecosystem

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:84


PartialRequired

Ζ¬ PartialRequired<T, K>: Partial<Omit<T, K>> & Required<Pick<T, K>>

Type parameters

NameType
TT
Kextends keyof T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:28


PickByValue

Ζ¬ PickByValue<T, V>: { [P in keyof T]: T[P] extends V ? P : never }[keyof T] & keyof T

Gets all the keys (as a string union) from a type T that match value V

example

interface Sample {
id: string;
name: string | null;
middleName?: string;
lastName: string;
hobbies: readonly string[];
}

type BB = PickByValue<Sample, string>;
// Expected:
// "id" | "lastName"

Type parameters

Name
T
V

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:116


Primitive

Ζ¬ Primitive: string | number | boolean | bigint | symbol | undefined | null

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:1


RequiredExcept

Ζ¬ RequiredExcept<T, K>: Partial<Pick<T, K>> & Required<Omit<T, K>>

Type parameters

NameType
TT
Kextends keyof T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:26


SecondArgument

Ζ¬ SecondArgument<T>: T extends (arg1: unknown, arg2: infer U, ...args: unknown[]) => unknown ? U : unknown

Gets the second argument of any given function

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:74


StrictRequired

Ζ¬ StrictRequired<T>: { [P in keyof T]-?: NonNullable<T[P]> }

Transforms every key in an object to be strictly required, essentially removing undefined and null from the type.

example

interface Sample {
id: string;
name: string | null;
middleName?: string;
}

type BB = StrictRequired<Sample>;
// Expected:
// {
// id: string;
// name: string;
// middleName: string;
// }

Type parameters

Name
T

Defined in

projects/utilities/packages/utilities/src/lib/utilityTypes.ts:161

Functions

arrayStrictEquals

β–Έ arrayStrictEquals<T>(arr1, arr2): boolean

Compare if both arrays are strictly equal

Type parameters

NameType
Textends readonly unknown[]

Parameters

NameTypeDescription
arr1TThe array to compare to
arr2TThe array to compare with

Returns

boolean

Defined in

projects/utilities/packages/utilities/src/lib/arrayStrictEquals.ts:6


chunk

β–Έ chunk<T>(array, chunkSize): T[][]

Splits up an array into chunks

Type parameters

Name
T

Parameters

NameTypeDescription
arrayreadonly T[]The array to chunk up
chunkSizenumberThe size of each individual chunk

Returns

T[][]

Defined in

projects/utilities/packages/utilities/src/lib/chunk.ts:6


classExtends

β–Έ classExtends<T>(value, base): value is T

Checks whether or not the value class extends the base class.

Type parameters

NameType
Textends Ctor<readonly any[], any>

Parameters

NameTypeDescription
valueCtor<readonly any[], any>The constructor to be checked against.
baseTThe base constructor.

Returns

value is T

Defined in

projects/utilities/packages/utilities/src/lib/classExtends.ts:8


codeBlock

β–Έ codeBlock<T>(language, expression): string

Wraps text in a markdown codeblock with optionally a language indicator for syntax highlighting

Type parameters

Name
T

Parameters

NameTypeDescription
languagestringThe codeblock language
expressionTThe expression to be wrapped in the codeblock

Returns

string

Defined in

projects/utilities/packages/utilities/src/lib/codeBlock.ts:8


cutText

β–Έ cutText(str, length): string

Split a text by its latest space character in a range from the character 0 to the selected one.

copyright 2019 Antonio RomΓ‘n

license Apache-2.0

Parameters

NameTypeDescription
strstringThe text to split.
lengthnumberThe length of the desired string.

Returns

string

Defined in

projects/utilities/packages/utilities/src/lib/cutText.ts:10


debounce

β–Έ debounce<FnArgumentsType, FnReturnType>(func, options?): DebouncedFunc<FnArgumentsType, FnReturnType>

Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked. The debounced function comes with a cancel method to cancel delayed invocations and a flush method to immediately invoke them. Provide an options object to indicate that func should be invoked on the leading and/or trailing edge of the wait timeout. Subsequent calls to the debounced function return the result of the last func invocation.

Note: If leading and trailing options are true, func is invoked on the trailing edge of the timeout only if the the debounced function is invoked more than once during the wait timeout.

See David Corbacho’s article for details over the differences between .debounce and .throttle.

Type parameters

NameType
FnArgumentsTypeextends any[]
FnReturnTypeFnReturnType

Parameters

NameTypeDescription
func(...args: FnArgumentsType) => FnReturnTypeThe function to debounce.
optionsDebounceSettingsThe options object.

Returns

DebouncedFunc<FnArgumentsType, FnReturnType>

Returns the new debounced function.

Defined in

projects/utilities/packages/utilities/src/lib/debounce/index.ts:68


deepClone

β–Έ deepClone<T>(source): T

Deep clone an object

Type parameters

Name
T

Parameters

NameTypeDescription
sourceTThe object to clone

Returns

T

Defined in

projects/utilities/packages/utilities/src/lib/deepClone.ts:7


filterNullish

β–Έ filterNullish<TValue>(value): value is TValue

Checks whether a value is not null nor undefined. This can be used in {@link Array.filter} to remove null and undefined from the array type

example

// TypeScript Type: (string | undefined | null)[]
const someArray = ['one', 'two', undefined, null, 'five'];

// TypeScript Type: string[]
const filteredArray = someArray.filter(filterNullAndUndefined);
// Result: ['one', 'two', 'five']

Type parameters

Name
TValue

Parameters

NameTypeDescription
valueTValue | NullishThe value to verify that is neither null nor undefined

Returns

value is TValue

A boolean that is true if the value is neither null nor undefined, false otherwise.

Defined in

projects/utilities/packages/utilities/src/lib/filterNullAndUndefined.ts:19


filterNullishOrEmpty

β–Έ filterNullishOrEmpty<TValue>(value): value is TValue

Checks whether a value is not null nor undefined nor '' (empty string). This can be used in {@link Array.filter} to remove null, undefined from the array type

example

// TypeScript Type: (string | undefined | null)[]
const someArray = ['one', 'two', undefined, null, ''];

// TypeScript Type: string[]
const filteredArray = someArray.filter(filterNullAndUndefinedAndEmpty);
// Result: ['one', 'two']

Type parameters

Name
TValue

Parameters

NameTypeDescription
value"" | Nullish | TValueThe value to verify that is neither null, undefined nor '' (empty string)

Returns

value is TValue

A boolean that is true if the value is neither null, undefined nor '' (empty string), false otherwise.

Defined in

projects/utilities/packages/utilities/src/lib/filterNullAndUndefinedAndEmpty.ts:19


filterNullishOrZero

β–Έ filterNullishOrZero<TValue>(value): value is TValue

Checks whether a value is not null nor undefined nor 0. This can be used in {@link Array.filter} to remove null, undefined from the array type

example

// TypeScript Type: (string | number | undefined | null)[]
const someArray = ['one', 'two', undefined, null, 0, 1];

// TypeScript Type: (string | number)[]
const filteredArray = someArray.filter(filterNullAndUndefinedAndZero);
// Result: ['one', 'two', 1]

Type parameters

Name
TValue

Parameters

NameTypeDescription
value0 | Nullish | TValueThe value to verify that is neither null, undefined nor 0

Returns

value is TValue

A boolean that is true if the value is neither null, undefined nor 0, false otherwise.

Defined in

projects/utilities/packages/utilities/src/lib/filterNullAndUndefinedAndZero.ts:19


hasAtLeastOneKeyInMap

β–Έ hasAtLeastOneKeyInMap<T>(map, keys): boolean

Checks whether any of the keys are in the {@link map}

Type parameters

Name
T

Parameters

NameTypeDescription
mapReadonlyMap<T, any>The map to check
keysreadonly T[]The keys to find in the map

Returns

boolean

true if at least one of the keys is in the {@link map}, false otherwise.

Defined in

projects/utilities/packages/utilities/src/lib/hasAtLeastOneKeyInMap.ts:7


inlineCodeBlock

β–Έ inlineCodeBlock(input): string

Wraps text in a markdown inline codeblock

Parameters

NameType
inputstring

Returns

string

Defined in

projects/utilities/packages/utilities/src/lib/inlineCodeBlock.ts:7


isClass

β–Έ isClass(input): input is Ctor<readonly any[], any>

Verify if the input is a class constructor.

Parameters

NameTypeDescription
inputunknownThe function to verify

Returns

input is Ctor<readonly any[], any>

Defined in

projects/utilities/packages/utilities/src/lib/isClass.ts:7


isFunction

β–Έ isFunction(input): input is Function

Verify if the input is a function.

Parameters

NameTypeDescription
inputunknownThe function to verify

Returns

input is Function

Defined in

projects/utilities/packages/utilities/src/lib/isFunction.ts:6


isNullish

β–Έ isNullish(value): value is Nullish

Checks whether or not a value is null or undefined

Parameters

NameTypeDescription
valueunknownThe value to check

Returns

value is Nullish

Defined in

projects/utilities/packages/utilities/src/lib/isNullOrUndefined.ts:7


isNullishOrEmpty

β–Έ isNullishOrEmpty(value): value is "" | Nullish

Checks whether or not a value is null, undefined or '', []

Parameters

NameTypeDescription
valueunknownThe value to check

Returns

value is "" | Nullish

Defined in

projects/utilities/packages/utilities/src/lib/isNullOrUndefinedOrEmpty.ts:8


isNullishOrZero

β–Έ isNullishOrZero(value): value is 0 | Nullish

Checks whether or not a value is null, undefined or 0

Parameters

NameTypeDescription
valueunknownThe value to check

Returns

value is 0 | Nullish

Defined in

projects/utilities/packages/utilities/src/lib/isNullOrUndefinedOrZero.ts:8


isNumber

β–Έ isNumber(input): input is number

Verify if a number is a finite number.

Parameters

NameTypeDescription
inputunknownThe number to verify

Returns

input is number

Defined in

projects/utilities/packages/utilities/src/lib/isNumber.ts:5


isObject

β–Έ isObject(input): input is object | Record<PropertyKey, unknown>

Verify if the input is an object literal (or class).

Parameters

NameTypeDescription
inputunknownThe object to verify

Returns

input is object | Record<PropertyKey, unknown>

Defined in

projects/utilities/packages/utilities/src/lib/isObject.ts:6


isPrimitive

β–Έ isPrimitive(input): input is string | number | bigint | boolean

Check whether a value is a primitive

Parameters

NameTypeDescription
inputunknownThe input to check

Returns

input is string | number | bigint | boolean

Defined in

projects/utilities/packages/utilities/src/lib/isPrimitive.ts:7


isThenable

β–Έ isThenable(input): input is Thenable

Verify if an object is a promise.

Parameters

NameTypeDescription
inputunknownThe promise to verify

Returns

input is Thenable

Defined in

projects/utilities/packages/utilities/src/lib/isThenable.ts:21


makeObject

β–Έ makeObject(path, value, obj?): Record<string, unknown>

Turn a dotted path into a json object.

Parameters

NameTypeDescription
pathstringThe dotted path
valueunknownThe value
objRecord<string, unknown>The object to edit

Returns

Record<string, unknown>

Defined in

projects/utilities/packages/utilities/src/lib/makeObject.ts:7


mergeDefault

β–Έ mergeDefault<A, B>(base, overwrites?): DeepRequired<A & B>

Deep merges 2 objects. Properties from the second parameter are applied to the first.

remark overwrites is also mutated!

remark If the value of a key in overwrites is undefined then the value of that same key in base is used instead!

remark This is essentially { ...base, ...overwrites } but recursively

example

const base = { a: 0, b: 1 };
const overwrites = {}; // will be { a: 0, b: 1 } after merge
mergeDefault(base, overwrites) // { a: 0, b: 1 }

example

const base = { a: 0, b: 1 };
const overwrites = { a: 2, i: 3 };
mergeDefault(base, overwrites) // { a: 2, i: 3, b: 1 };

example

const base = { a: 0, b: 1 };
const overwrites = { a: null };
mergeDefault(base, overwrites) // { a: null, b: 1 };

example

const base = { a: 0, b: 1 };
const overwrites = { a: undefined };
mergeDefault(base, overwrites) // { a: 0, b: 1 };

example

const base = { a: null };
const overwrites = { a: { b: 5 } };
mergeDefault(base, overwrites) // { a: { b: 5 } };

Type parameters

NameType
Aextends NonNullObject
Bextends Partial<A>

Parameters

NameTypeDescription
baseABase object
overwrites?BOverwrites to apply

Returns

DeepRequired<A & B>

Defined in

projects/utilities/packages/utilities/src/lib/mergeDefault.ts:43


mergeObjects

β–Έ mergeObjects<A, B>(objTarget, objSource): A & B

Merges two objects

Type parameters

NameType
Aextends object
Bextends object

Parameters

NameTypeDescription
objTargetAThe object to be merged
objSourceReadonly<B>The object to merge

Returns

A & B

Defined in

projects/utilities/packages/utilities/src/lib/mergeObjects.ts:9


noop

β–Έ noop(): void

Returns

void

Defined in

projects/utilities/packages/utilities/src/lib/noop.ts:2


objectToTuples

β–Έ objectToTuples(original, prefix?): [string, unknown][]

Convert an object to a tuple

Parameters

NameTypeDefault valueDescription
originalRecord<string, unknown>undefined-
prefixstring''The prefix for the key

Returns

[string, unknown][]

Defined in

projects/utilities/packages/utilities/src/lib/objectToTuples.ts:8


parseURL

β–Έ parseURL(url): URL | null

Parses an URL, returns null if invalid.

Parameters

NameTypeDescription
urlstringThe url to parse

Returns

URL | null

Defined in

projects/utilities/packages/utilities/src/lib/parseUrl.ts:7


partition

β–Έ partition<T>(array, predicate): T[][]

Partitions array into a tuple of two arrays, where one array contains all elements that satisfies predicate, and the other contains all elements that do not satisfy predicate.

Type parameters

Name
T

Parameters

NameTypeDescription
arrayT[]The array to partition. This array is not mutated.
predicate(value: T, index: number) => booleanThe predicate function to determine in which partition the item should be placed. The function should return true for items that should be placed in the first partition, and false for those that should be placed in the second partition.

Returns

T[][]

A tuple of two arrays.

Defined in

projects/utilities/packages/utilities/src/lib/partition.ts:12


range

β–Έ range(min, max, step): number[]

Get an array of numbers with the selected range

Parameters

NameTypeDescription
minnumberThe minimum value
maxnumberThe maximum value
stepnumberThe step value

Returns

number[]

Defined in

projects/utilities/packages/utilities/src/lib/range.ts:7


regExpEsc

β–Έ regExpEsc(str): string

Cleans a string from regex injection

Parameters

NameTypeDescription
strstringThe string to clean

Returns

string

Defined in

projects/utilities/packages/utilities/src/lib/regExpEsc.ts:8


roundNumber

β–Έ roundNumber(num, scale?): number

Properly rounds up or down a number. Also supports strings using an exponent to indicate large or small numbers.

Parameters

NameTypeDefault valueDescription
numstring | numberundefinedThe number to round off
scalenumber0The amount of decimals to retain

Returns

number

Defined in

projects/utilities/packages/utilities/src/lib/roundNumber.ts:7


splitText

β–Έ splitText(str, length, char?): string

Split a string by its latest space character in a range from the character 0 to the selected one.

copyright 2019 Antonio RomΓ‘n

license Apache-2.0

Parameters

NameTypeDefault valueDescription
strstringundefinedThe text to split.
lengthnumberundefinedThe length of the desired string.
charstring' 'The character to split with

Returns

string

Defined in

projects/utilities/packages/utilities/src/lib/splitText.ts:9


toTitleCase

β–Έ toTitleCase(str): string

Converts a string to Title Case

description This is designed to also ensure common Discord PascalCased strings are put in their TitleCase titleCaseVariants. See below for the full list.

terms This table lists how certain terms are converted, these are case insensitive. Any terms not included are converted to regular Titlecase.

 | Term            |    Converted To |
|-----------------|-----------------|
| textchannel | TextChannel |
| voicechannel | VoiceChannel |
| categorychannel | CategoryChannel |
| guildmember | GuildMember |

Parameters

NameTypeDescription
strstringThe string to title case

Returns

string

Defined in

projects/utilities/packages/utilities/src/lib/toTitleCase.ts:26


tryParse

β–Έ tryParse(value): object | string

Try parse a stringified JSON string.

Parameters

NameTypeDescription
valuestringThe value to parse

Returns

object | string

Defined in

projects/utilities/packages/utilities/src/lib/tryParse.ts:6