@oscarpalmer/atoms 0.75.0 → 0.76.0

package/types/index.d.cts

@@ -1,91 +1,130 @@
 // Generated by dts-bundle-generator v9.5.1
 
-export declare class Emitter<Value> {
-	private readonly state;
+/**
+ * A Map with a maximum size
+ * - Maximum size defaults to _2^20_; any provided size will be clamped at _2^24_
+ * - Behaviour is similar to a _LRU_-cache, where the least recently used entries are removed
+ */
+export declare class SizedMap<Key = unknown, Value = unknown> extends Map<
+	Key,
+	Value
+> {
+	private readonly maximumSize;
 	/**
-	 * Is the emitter active?
+	 * Is the Map full?
 	 */
-	get active(): boolean;
+	get full(): boolean;
 	/**
-	 * The observable that can be subscribed to
+	 * The maximum size of the Map
 	 */
-	get observable(): Observable<Value>;
+	get maximum(): number;
 	/**
-	 * The current value
+	 * Create a new Map with entries and a maximum size _(2^20)_
 	 */
-	get value(): Value;
-	constructor(value: Value);
+	constructor(entries: Array<[Key, Value]>);
 	/**
-	 * Destroys the emitter
+	 * Create a new Map with a maximum size _(but clamped at 2^24)_
 	 */
-	destroy(): void;
+	constructor(maximum: number);
 	/**
-	 * Emits a new value _(and optionally finishes the emitter)_
+	 * Create a new Map with _(optional)_ entries and a maximum size _(defaults to 2^20; clamped at 2^24)_
 	 */
-	emit(value: Value, finish?: boolean): void;
+	constructor(entries?: Array<[Key, Value]>, maximum?: number);
 	/**
-	 * Emits an error _(and optionally finishes the emitter)_
+	 * @inheritdoc
 	 */
-	error(error: Error, finish?: boolean): void;
+	get(key: Key): Value | undefined;
 	/**
-	 * Finishes the emitter
+	 * @inheritdoc
 	 */
-	finish(): void;
+	set(key: Key, value: Value): this;
 }
-export declare class Observable<Value> {
-	private readonly state;
-	constructor(
-		emitter: Emitter<Value>,
-		observers: Map<Subscription<Value>, Observer<Value>>,
-	);
+/**
+ * A Set with a maximum size
+ * - Maximum size defaults to _2^20_; any provided size will be clamped at _2^24_
+ * - Behaviour is similar to a _LRU_-cache, where the oldest values are removed
+ */
+export declare class SizedSet<Value = unknown> extends Set<Value> {
+	private readonly maximumSize;
 	/**
-	 * Subscribes to value changes
+	 * Is the Set full?
 	 */
-	subscribe(observer: Observer<Value>): Subscription<Value>;
+	get full(): boolean;
 	/**
-	 * Subscribes to value changes
+	 * The maximum size of the Set
 	 */
-	subscribe(
-		onNext: (value: Value) => void,
-		onError?: (error: Error) => void,
-		onComplete?: () => void,
-	): Subscription<Value>;
-}
-export type ObservableState<Value> = {
-	emitter: Emitter<Value>;
-	observers: Map<Subscription<Value>, Observer<Value>>;
-};
-export type Observer<Value> = {
+	get maximum(): number;
 	/**
-	 * Callback for when the observable is complete
+	 * Create a new Set with values and a maximum size _(2^20)_
 	 */
-	complete?: () => void;
+	constructor(values: Value[]);
 	/**
-	 * Callback for when the observable has an error
+	 * Create a new Set with a maximum size _(but clamped at 2^24)_
 	 */
-	error?: (error: Error) => void;
+	constructor(maximum: number);
 	/**
-	 * Callback for when the observable has a new value
+	 * Create a new Set with _(optional)_ values and a maximum size _(defaults to 2^20; clamped at 2^24)_
 	 */
-	next?: (value: Value) => void;
-};
-export declare class Subscription<Value> {
-	private readonly state;
-	constructor(state: ObservableState<Value>);
+	constructor(values?: Value[], maximum?: number);
 	/**
-	 * Is the subscription closed?
+	 * @inheritdoc
 	 */
-	get closed(): boolean;
-	destroy(): void;
+	add(value: Value): this;
 	/**
-	 * Unsubscribes from the observable
+	 * Get a value from an index in the Set, if it exists
+	 * - Negative indices are counted from the end
+	 * - Optionally move the value to the end with `update`
 	 */
-	unsubscribe(): void;
+	at(index: number, update?: boolean): Value | undefined;
+	/**
+	 * Get a value from the Set, if it exists _(and move it to the end)_
+	 */
+	get(value: Value, update?: boolean): Value | undefined;
 }
 /**
- * Creates a new emitter
+ * Get a random boolean
  */
-export declare function emitter<Value>(value: Value): Emitter<Value>;
+export declare function getRandomBoolean(): boolean;
+/**
+ * Get a random string of characters with a specified length
+ * - `selection` defaults to all lowercase letters in the English alphabet
+ */
+export declare function getRandomCharacters(
+	length: number,
+	selection?: string,
+): string;
+/**
+ * Get a random hexadecimal colour
+ */
+export declare function getRandomColour(): string;
+/**
+ * Get a random floating-point number
+ */
+export declare function getRandomFloat(min?: number, max?: number): number;
+/**
+ * Get a random hexadecimal character
+ */
+export declare function getRandomHex(): string;
+/**
+ * Get a random integer
+ */
+export declare function getRandomInteger(min?: number, max?: number): number;
+/**
+ * Get a random item from an array
+ */
+export declare function getRandomItem<Value>(array: Value[]): Value;
+/**
+ * - Get an amount of random items from an array
+ * - If `amount` is not specified, a shuffled array will be returned instead
+ */
+export declare function getRandomItems<Value>(
+	array: Value[],
+	amount?: number,
+): Value[];
+/**
+ * Queue a callback to be executed at the next best time
+ */
+export declare function queue(callback: () => void): void;
 /**
 Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
 
@@ -1485,382 +1524,882 @@ export type EventPosition = {
 	x: number;
 	y: number;
 };
+export type KeyedValue<
+	Item,
+	Key extends keyof Item,
+> = Item[Key] extends PropertyKey ? Item[Key] : never;
 export type NestedArrayType<Value> = Value extends Array<infer NestedValue>
 	? NestedArrayType<NestedValue>
 	: Value;
 export type GenericCallback = (...args: any[]) => any;
-export type GetterSetter<Value> = {
-	get(): Value;
-	set(value: Value): void;
-};
 export type Key = number | string;
 export type PlainObject = UnknownRecord;
 export type UnknownArrayOrRecord = UnknownArray | UnknownRecord;
-export type Debounced<Callback extends GenericCallback> = Callback & {
-	/**
-	 * Cancels the debounce
-	 */
-	cancel: () => void;
-};
-declare class Memoised<Callback extends GenericCallback> {
-	readonly state: MemoisedState<Callback>;
-	constructor(callback: Callback);
-	/**
-	 * Clears the cache
-	 */
-	clear(): void;
-	/**
-	 * Deletes a result from the cache
-	 */
-	delete(key: Parameters<Callback>[0]): boolean;
-	/**
-	 * Destroys the instance, clearing its cache and removing its callback
-	 */
-	destroy(): void;
-	/**
-	 * Retrieves the result from the cache if it exists, or `undefined` otherwise
-	 */
-	get(key: Parameters<Callback>[0]): ReturnType<Callback> | undefined;
-	/**
-	 * Checks if the cache has a result for a given key
-	 */
-	has(key: Parameters<Callback>[0]): boolean;
-	/**
-	 * Retrieves the result from the cache if it exists, otherwise runs the callback, caches the result, and returns it
-	 */
-	run(...parameters: Parameters<Callback>): ReturnType<Callback>;
-}
-export type MemoisedState<Callback extends GenericCallback> = {
-	cache: Map<Parameters<Callback>[0], ReturnType<Callback>>;
-	getter: (...parameters: Parameters<Callback>) => ReturnType<Callback>;
-};
-/**
- * - Debounces a function, ensuring it is only called after `time` milliseconds have passed
- * - On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
- * - Time is clamped between _0_ and _1000_ milliseconds
- * - Returns the callback with an added `cancel`-method for manually cancelling the debounce
- */
-export declare function debounce<Callback extends GenericCallback>(
-	callback: Callback,
-	time?: number,
-): Debounced<Callback>;
-/**
- * Memoises a function, caching and retrieving results based on the first parameter
- */
-export declare function memoise<Callback extends GenericCallback>(
-	callback: Callback,
-): Memoised<Callback>;
-/**
- * A function that does nothing, which can be useful, I guess…
- */
-export declare function noop(): void;
-/**
- * - Throttles a function, ensuring it is only called once every `time` milliseconds
- * - Time is clamped between _0_ and _1000_ milliseconds
- */
-export declare function throttle<Callback extends GenericCallback>(
-	callback: Callback,
-	time?: number,
-): Callback;
-/**
- * Chunks an array into smaller arrays of a specified size
- */
-export declare function chunk<Value>(array: Value[], size?: number): Value[][];
-/**
- * Compacts and returns an array with all falsey values removed
- */
-export declare function compact<Value>(
-	array: Value[],
-	strict: true,
-): Exclude<Value, 0 | '' | false | null | undefined>[];
-/**
- * Compacts and returns an array with all `null` and `undefined` values removed
- */
-export declare function compact<Value>(
-	array: Value[],
-): Exclude<Value, null | undefined>[];
-export type ArrayCallback<Value, Returned> = (
-	value: Value,
-	index: number,
-	array: Value[],
-) => Returned;
-export type BooleanCallback<Value> = ArrayCallback<Value, boolean>;
-export type KeyCallback<Value> = ArrayCallback<Value, Key>;
-export type SortKey<Value> = {
-	direction: 'asc' | 'desc';
-	value: Key | SortKeyCallback<Value>;
-};
-export type SortKeyCallback<Value> = (value: Value) => Key;
-/**
- * Returns the number of items _(count)_ that match the given value
- */
-export declare function count<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-): number;
 /**
- * - Returns the number of items _(count)_ that match the given value
- * - Use `key` to find a comparison value to match with `value`
+ * Convert a query string to a plain _(nested)_ object
  */
-export declare function count<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
-): number;
+export declare function fromQuery(query: string): PlainObject;
 /**
- * Does the value exist in array?
+ * Convert a plain _(nested)_ object to a query string
  */
-export declare function exists<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-): boolean;
+export declare function toQuery(parameters: PlainObject): string;
 /**
- * - Does the value exist in array?
- * - Use `key` to find a comparison value to match with `value`
+ * Is the number between a minimum and maximum value?
  */
-export declare function exists<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
+export declare function between(
+	value: number,
+	min: number,
+	max: number,
 ): boolean;
 /**
- * Returns a filtered array of items matching `value`
- */
-export declare function filter<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-): Model[];
-/**
- * - Returns a filtered array of items
- * - Use `key` to find a comparison value to match with `value`
- */
-export declare function filter<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
-): Model[];
-/**
- * Returns the first item matching `value`, or `undefined` if no match is found
- */
-export declare function find<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-): Model | undefined;
-/**
- * - Returns the first matching item, or `undefined` if no match is found
- * - Use `key` to find a comparison value to match with `value`
- */
-export declare function find<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
-): Model | undefined;
-/**
- * Groups an array of items using a key or callback
+ * - Clamp a number between a minimum and maximum value
+ * - If `loop` is `true`, when the value is less than the minimum, it will be clamped as the maximum, and vice versa
  */
-export declare function groupBy<Value>(
-	array: Value[],
-	key: Key | KeyCallback<Value>,
-): Record<Key, Value[]>;
+export declare function clamp(
+	value: number,
+	min: number,
+	max: number,
+	loop?: boolean,
+): number;
 /**
- * Returns the index for the first item matching `value`, or `-1` if no match is found
+ * - Get the number value from an unknown value
+ * - Returns `NaN` if the value is `undefined`, `null`, or cannot be parsed
+ * - Based on Lodash :-)
  */
-export declare function indexOf<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-): number;
+export declare function getNumber(value: unknown): number;
 /**
- * - Returns the index for the first matching item, or `-1` if no match is found
- * - Use `key` to find a comparison value to match with `value`
+ * Get the average value from a list of numbers
  */
-export declare function indexOf<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
-): number;
+export declare function average(values: number[]): number;
 /**
- * - Inserts values into an array at a specified index
- * - Uses chunking to avoid stack overflow
+ * Get the maximum value from a list of numbers
  */
-export declare function insert<Value>(
-	array: Value[],
-	index: number,
-	values: Value[],
-): void;
+export declare function max(values: number[]): number;
 /**
- * Shuffles an array
+ * Get the minimum value from a list of numbers
  */
-export declare function shuffle<Value>(array: Value[]): Value[];
+export declare function min(values: number[]): number;
 /**
- * Sorts an array of items _(ascending by default)_
+ * Round a number to a specific number of decimal places _(defaults to 0)_
  */
-export declare function sort<Value>(
-	array: Value[],
-	descending?: boolean,
-): Value[];
+export declare function round(value: number, decimals?: number): number;
 /**
- * - Sorts an array of items, using a `key` to sort by a specific value
- * - Ascending by default, but can be changed by setting `descending` to `true`, or using a `SortKey`
+ * Get the sum of a list of numbers
  */
-export declare function sort<Value>(
-	array: Value[],
-	key: Key | SortKey<Value> | SortKeyCallback<Value>,
+export declare function sum(values: number[]): number;
+declare class Logger {
+	/**
+	 * Log any number of values at the "debug" log level
+	 */
+	get debug(): {
+		(...data: any[]): void;
+		(message?: any, ...optionalParams: any[]): void;
+	};
+	/**
+	 * Log the value and shows all its properties
+	 */
+	get dir(): {
+		(item?: any, options?: any): void;
+		(obj: any, options?: import('util').InspectOptions): void;
+	};
+	/**
+	 * Is logging to the console enabled? _(defaults to `true`)_
+	 */
+	get enabled(): boolean;
+	/**
+	 * Enable or disable logging to the console
+	 */
+	set enabled(value: boolean);
+	/**
+	 * Log any number of values at the "error" log level
+	 */
+	get error(): {
+		(...data: any[]): void;
+		(message?: any, ...optionalParams: any[]): void;
+	};
+	/**
+	 * Log any number of values at the "info" log level
+	 */
+	get info(): {
+		(...data: any[]): void;
+		(message?: any, ...optionalParams: any[]): void;
+	};
+	/**
+	 * Log any number of values at the "log" log level
+	 */
+	get log(): {
+		(...data: any[]): void;
+		(message?: any, ...optionalParams: any[]): void;
+	};
+	/**
+	 * Log data as a table, with optional properties to use as columns
+	 */
+	get table(): {
+		(tabularData?: any, properties?: string[]): void;
+		(tabularData: any, properties?: readonly string[]): void;
+	};
+	/**
+	 * Log any number of values together with a trace from where it was called
+	 */
+	get trace(): {
+		(...data: any[]): void;
+		(message?: any, ...optionalParams: any[]): void;
+	};
+	/**
+	 * Log any number of values at the "warn" log level
+	 */
+	get warn(): {
+		(...data: any[]): void;
+		(message?: any, ...optionalParams: any[]): void;
+	};
+	/**
+	 * - Start a logged timer with a label
+	 * - Returns a `Time`-object for logging the current duration of the timer and stopping the timer _(and logging the total duration)_
+	 */
+	time(label: string): Time;
+}
+declare class Time {
+	private readonly state;
+	constructor(label: string);
+	/**
+	 * - Log the current duration of the timer
+	 * - _(Ignored if logging is disabled)_
+	 */
+	log(): void;
+	/**
+	 * - Stop the timer and logs the total duration
+	 * - _(Will always log the total duration, even if logging is disabled)_
+	 */
+	stop(): void;
+}
+export declare const logger: Logger;
+/**
+ * Is the value an array or a record?
+ */
+export declare function isArrayOrPlainObject(
+	value: unknown,
+): value is ArrayOrPlainObject;
+/**
+ * Is the array or object completely empty or only containing `null` or `undefined` values?
+ */
+export declare function isEmpty(value: ArrayOrPlainObject): boolean;
+/**
+ * Is the value a key?
+ */
+export declare function isKey(value: unknown): value is Key;
+/**
+ * Is the value undefined or null?
+ */
+export declare function isNullable(value: unknown): value is undefined | null;
+/**
+ * Is the value undefined, null, or an empty string?
+ */
+export declare function isNullableOrEmpty(
+	value: unknown,
+): value is undefined | null | '';
+/**
+ * Is the value undefined, null, or a whitespace-only string?
+ */
+export declare function isNullableOrWhitespace(
+	value: unknown,
+): value is undefined | null | '';
+/**
+ * Is the value a number?
+ */
+export declare function isNumber(value: unknown): value is number;
+/**
+ * Is the value a number, or a number-like string?
+ */
+export declare function isNumerical(
+	value: unknown,
+): value is number | `${number}`;
+/**
+ * Is the value an object?
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Is the value a plain object?
+ */
+export declare function isPlainObject(value: unknown): value is PlainObject;
+/**
+ * Is the value a primitive value?
+ */
+export declare function isPrimitive(value: unknown): value is Primitive;
+/**
+ * Chunk an array _(into smaller arrays of a specified size)_
+ */
+export declare function chunk<Item>(array: Item[], size?: number): Item[][];
+/**
+ * Compact an array _(removing all `null` and `undefined` values)_
+ */
+export declare function compact<Item>(
+	array: Item[],
+): Exclude<Item, null | undefined>[];
+/**
+ * Compact an array _(removing all falsey values)_
+ */
+export declare function compact<Item>(
+	array: Item[],
+	strict: true,
+): Exclude<Item, 0 | '' | false | null | undefined>[];
+export type ArrayCallback<Item, Value> = (
+	item: Item,
+	index: number,
+	array: Item[],
+) => Value;
+export type BooleanCallback<Item> = ArrayCallback<Item, boolean>;
+export type KeyCallback<Item> = ArrayCallback<Item, Key>;
+export type SortKey<Item> = {
+	direction: 'asc' | 'desc';
+	value: Key | SortKeyCallback<Item>;
+};
+export type SortKeyCallback<Item> = (item: Item) => unknown;
+export type ValueCallback<Item> = ArrayCallback<Item, unknown>;
+/**
+ * Get the number of items _(count)_ that match the given value
+ */
+export declare function count<Item>(array: Item[], value: Item): number;
+/**
+ * Get the number of items _(count)_ that match the given value
+ */
+export declare function count<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
+): number;
+/**
+ * Get the number of items _(count)_ that match the given value
+ */
+export declare function count<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): number;
+/**
+ * Get the number of items _(count)_ that match the given value
+ */
+export declare function count<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	value: ReturnType<Key>,
+): number;
+/**
+ * Does the value exist in array?
+ */
+export declare function exists<Item>(array: Item[], value: Item): boolean;
+/**
+ * Does the value exist in array?
+ */
+export declare function exists<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
+): boolean;
+/**
+ * - Does the value exist in array?
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function exists<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): boolean;
+/**
+ * - Does the value exist in array?
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function exists<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	value: ReturnType<Key>,
+): boolean;
+/**
+ * Get a filtered array of items matching `value`
+ */
+export declare function filter<Item>(array: Item[], value: Item): Item[];
+/**
+ * Get a filtered array of items matching `value`
+ */
+export declare function filter<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
+): Item[];
+/**
+ * - Get a filtered array of items
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function filter<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): Item[];
+/**
+ * - Get a filtered array of items
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function filter<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	value: ReturnType<Key>,
+): Item[];
+/**
+ * Get the first item matching `value` _(or `undefined` if no match is found)_
+ */
+export declare function find<Item>(
+	array: Item[],
+	value: Item,
+): Item | undefined;
+/**
+ * Get the first item matching `value` _(or `undefined` if no match is found)_
+ */
+export declare function find<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
+): Item | undefined;
+/**
+ * - Get the first matching item _(or `undefined` if no match is found)_
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function find<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): Item | undefined;
+/**
+ * - Get the first matching item _(or `undefined` if no match is found)_
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function find<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	value: ReturnType<Key>,
+): Item | undefined;
+/**
+ * Create a record from an array of items using a specific key
+ */
+export declare function groupBy<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Record<KeyedValue<Item, Key>, Item>;
+/**
+ * Create a record from an array of items using a specific key, and grouping them into arrays
+ */
+export declare function groupBy<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Item[]>;
+/**
+ * Create a record from an array of items using a specific key
+ */
+export declare function groupBy<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Record<ReturnType<Key>, Item>;
+/**
+ * Create a record from an array of items using a specific key, and grouping them into arrays
+ */
+export declare function groupBy<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	arrays: true,
+): Record<ReturnType<Key>, Item[]>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function groupBy<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function groupBy<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function groupBy<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, ReturnType<Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function groupBy<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function groupBy<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<ReturnType<Key>, KeyedValue<Item, Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function groupBy<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function groupBy<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<ReturnType<Key>, ReturnType<Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function groupBy<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<ReturnType<Key>, Array<ReturnType<Value>>>;
+/**
+ * Get the index for the first item matching `value` _(or `-1` if no match is found)_
+ */
+export declare function indexOf<Item>(array: Item[], value: Item): number;
+/**
+ * Get the index for the first item matching `value` _(or `-1` if no match is found)_
+ */
+export declare function indexOf<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
+): number;
+/**
+ * - Get the index for the first matching item _(or `-1` if no match is found)_
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function indexOf<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): number;
+/**
+ * - Get the index for the first matching item _(or `-1` if no match is found)_
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export declare function indexOf<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	value: ReturnType<Key>,
+): number;
+/**
+ * - Insert values into an array _(at the end)_
+ * - _(Uses chunking to avoid stack overflow_)
+ */
+export declare function insert<Item>(array: Item[], items: Item[]): void;
+/**
+ * - Insert values into an array at a specified index
+ * - _(Uses chunking to avoid stack overflow_)
+ */
+export declare function insert<Item>(
+	array: Item[],
+	index: number,
+	items: Item[],
+): void;
+/**
+ * Shuffle an array
+ */
+export declare function shuffle<Item>(array: Item[]): Item[];
+/**
+ * Sort an array of items _(defaults to ascending)_
+ */
+export declare function sort<Item>(array: Item[], descending?: boolean): Item[];
+/**
+ * - Sort an array of items, using a `key` to sort by a specific value
+ * - Defaults to ascending, but can be changed by setting `descending` to `true`, or using a `SortKey`
+ */
+export declare function sort<Item>(
+	array: Item[],
+	key: Key | SortKey<Item> | SortKeyCallback<Item>,
 	descending?: boolean,
-): Value[];
+): Item[];
 /**
- * - Sorts an array of items, using multiple `keys` to sort by specific values
- * - Ascending by default, but can be changed by setting `descending` to `true`, or using `SortKey`
+ * - Sort an array of items, using multiple `keys` to sort by specific values
+ * - Defaults to ascending, but can be changed by setting `descending` to `true`, or using `SortKey`
  */
-export declare function sort<Value>(
-	array: Value[],
-	keys: Array<Key | SortKey<Value> | SortKeyCallback<Value>>,
+export declare function sort<Item>(
+	array: Item[],
+	keys: Array<Key | SortKey<Item> | SortKeyCallback<Item>>,
 	descending?: boolean,
-): Value[];
+): Item[];
 /**
  * Removes and returns all items from an array starting from a specific index
  */
-export declare function splice<Value>(array: Value[], start: number): Value[];
+export declare function splice<Item>(array: Item[], start: number): Item[];
 /**
  * Removes and returns _(up to)_ a specific amount of items from an array, starting from a specific index
  */
-export declare function splice<Value>(
-	array: Value[],
+export declare function splice<Item>(
+	array: Item[],
 	start: number,
 	amount: number,
-): Value[];
+): Item[];
 /**
  * - Splices values into an array and returns any removed values
  * - Uses chunking to avoid stack overflow
  */
-export declare function splice<Value>(
-	array: Value[],
+export declare function splice<Item>(
+	array: Item[],
 	start: number,
-	values: Value[],
-): Value[];
+	added: Item[],
+): Item[];
 /**
  * - Splices values into an array and returns any removed values
  * - Uses chunking to avoid stack overflow
  */
-export declare function splice<Value>(
-	array: Value[],
+export declare function splice<Item>(
+	array: Item[],
 	start: number,
 	amount: number,
-	values: Value[],
-): Value[];
+	added: Item[],
+): Item[];
 /**
- * Converts an array into a map, using indices as keys
+ * Create a map from an array of items _(using their indices as keys)_
  */
-export declare function toMap<Value>(array: Value[]): Map<number, Value>;
+export declare function toMap<Item>(array: Item[]): Map<number, Item>;
 /**
- * Converts an array into a map, using indices as keys and grouping values into arrays
+ * Create a map from an array of items using a specific key
  */
-export declare function toMap<Value>(
-	array: Value[],
+export declare function toMap<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Map<KeyedValue<Item, Key>, Item>;
+/**
+ * Create a map from an array of items using a specific key, and grouping them into arrays
+ */
+export declare function toMap<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
 	arrays: true,
-): Map<number, Value[]>;
+): Map<KeyedValue<Item, Key>, Item[]>;
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a map from an array of items using a specific key
  */
-export declare function toMap<Value>(array: Value[], key: Key): Map<Key, Value>;
+export declare function toMap<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Map<ReturnType<Key>, Item>;
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a map from an array of items using a specific key, and grouping them into arrays
  */
-export declare function toMap<Value>(
-	array: Value[],
+export declare function toMap<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
 	key: Key,
 	arrays: true,
-): Map<Key, Value[]>;
+): Map<ReturnType<Key>, Item[]>;
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a map from an array of items using a specific key and value
  */
-export declare function toMap<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
-): Map<Key, Value>;
+export declare function toMap<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
  */
-export declare function toMap<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
+export declare function toMap<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
 	arrays: true,
-): Map<Key, Value[]>;
+): Map<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
 /**
- * Converts an array into a record, using indices as keys
+ * Create a map from an array of items using a specific key and value
  */
-export declare function toRecord<Value>(array: Value[]): Record<number, Value>;
+export declare function toMap<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<KeyedValue<Item, Key>, ReturnType<Value>>;
 /**
- * Converts an array into a record, using indices as keys and grouping values into arrays
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
  */
-export declare function toRecord<Value>(
-	array: Value[],
+export declare function toMap<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
 	arrays: true,
-): Record<number, Value[]>;
+): Map<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a map from an array of items using a specific key and value
  */
-export declare function toRecord<Value>(
-	array: Value[],
+export declare function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
 	key: Key,
-): Record<Key, Value>;
+	value: Value,
+): Map<ReturnType<Key>, KeyedValue<Item, Value>>;
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
  */
-export declare function toRecord<Value>(
-	array: Value[],
+export declare function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Map<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+/**
+ * Create a map from an array of items using a specific key and value
+ */
+export declare function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<ReturnType<Key>, ReturnType<Value>>;
+/**
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
 	key: Key,
+	value: Value,
 	arrays: true,
-): Record<Key, Value[]>;
+): Map<ReturnType<Key>, Array<ReturnType<Value>>>;
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a record from an array of items _(using their indices as keys)_
  */
-export declare function toRecord<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
-): Record<Key, Value>;
+export declare function toRecord<Item>(array: Item[]): Record<number, Item>;
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a record from an array of items using a specific key
  */
-export declare function toRecord<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
+export declare function toRecord<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Record<KeyedValue<Item, Key>, Item>;
+/**
+ * Create a record from an array of items using a specific key, and grouping them into arrays
+ */
+export declare function toRecord<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Item[]>;
+/**
+ * Create a record from an array of items using a specific key
+ */
+export declare function toRecord<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Record<ReturnType<Key>, Item>;
+/**
+ * Create a record from an array of items using a specific key, and grouping them into arrays
+ */
+export declare function toRecord<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	arrays: true,
+): Record<ReturnType<Key>, Item[]>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, ReturnType<Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<ReturnType<Key>, KeyedValue<Item, Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export declare function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<ReturnType<Key>, ReturnType<Value>>;
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export declare function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
 	arrays: true,
-): Record<Key, Value[]>;
+): Record<ReturnType<Key>, Array<ReturnType<Value>>>;
 /**
- * Returns an array of unique items
+ * Get an array of unique items
  */
-export declare function unique<Value>(array: Value[]): Value[];
+export declare function unique<Item>(array: Item[]): Item[];
 /**
- * - Returns an array of unique items
+ * - Get an array of unique items
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function unique<Value>(
-	array: Value[],
-	key: Key | KeyCallback<Value>,
-): Value[];
+export declare function unique<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Item[];
 /**
- * Flattens an array _(using native `flat` and maximum depth)_
+ * - Get an array of unique items
+ * - Use `key` to find a comparison value to match with `value`
  */
-export declare function flatten<Value>(
-	array: Value[],
-): NestedArrayType<Value>[];
+export declare function unique<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Item[];
 /**
- * - Pushes values to the end of an array, returning the new length
- * - Uses chunking to avoid stack overflow
+ * Flatten an array _(using native `flat` and maximum depth)_
+ */
+export declare function flatten<Item>(array: Item[]): NestedArrayType<Item>[];
+/**
+ * - Push values to the end of an array
+ * - Returns the new length
+ * - _(Uses chunking to avoid stack overflow)_
  */
-export declare function push<Value>(array: Value[], values: Value[]): number;
+export declare function push<Item>(array: Item[], pushed: Item[]): number;
 export type HSLColourValue = {
 	hue: number;
 	lightness: number;
@@ -1868,35 +2407,41 @@ export type HSLColourValue = {
 };
 export declare class HSLColour extends Colour<HSLColourValue> {
 	/**
-	 * Gets the current hue
+	 * Get the current hue
 	 */
 	get hue(): number;
 	/**
-	 * Sets the current hue
+	 * Set the current hue
 	 */
 	set hue(value: number);
 	/**
-	 * Gets the current lightness
+	 * Get the current lightness
 	 */
 	get lightness(): number;
 	/**
-	 * Sets the current lightness
+	 * Set the current lightness
 	 */
 	set lightness(value: number);
 	/**
-	 * Gets the current saturation
+	 * Get the current saturation
 	 */
 	get saturation(): number;
 	/**
-	 * Sets the current saturation
+	 * Set the current saturation
 	 */
 	set saturation(value: number);
 	constructor(value: HSLColourValue);
+	/**
+	 * @inheritdoc
+	 */
 	toHex(): HexColour;
 	/**
-	 * Converts the colour to an RGB-colour
+	 * Convert the colour to an RGB-colour
 	 */
 	toRgb(): RGBColour;
+	/**
+	 * @inheritdoc
+	 */
 	toString(): string;
 	/**
 	 * Convert an HSL-colour to an RGB-colour
@@ -1911,11 +2456,11 @@ export declare class HexColour {
 	private readonly $colour;
 	private readonly state;
 	/**
-	 * Gets the value of the colour
+	 * Get the value of the colour
 	 */
 	get value(): string;
 	/**
-	 * Sets the value of the colour
+	 * Set the value of the colour
 	 */
 	set value(value: string);
 	constructor(value: string);
@@ -1944,7 +2489,7 @@ declare abstract class Colour<Model> {
 	private readonly $colour;
 	protected readonly state: ColourState<Model>;
 	/**
-	 * Gets the current value of the colour
+	 * Get the current value of the colour
 	 */
 	get value(): Model;
 	constructor(
@@ -1972,390 +2517,232 @@ export type RGBColourValue = {
 };
 export declare class RGBColour extends Colour<RGBColourValue> {
 	/**
-	 * Gets the current blue value
+	 * Get the current blue value
 	 */
 	get blue(): number;
 	/**
-	 * Sets the current blue value
+	 * Set the current blue value
 	 */
 	set blue(value: number);
 	/**
-	 * Gets the current green value
+	 * Get the current green value
 	 */
 	get green(): number;
 	/**
-	 * Sets the current green value
+	 * Set the current green value
 	 */
 	set green(value: number);
 	/**
-	 * Gets the current red value
+	 * Get the current red value
 	 */
 	get red(): number;
 	/**
-	 * Sets the current red value
+	 * Set the current red value
 	 */
 	set red(value: number);
 	constructor(value: RGBColourValue);
-	toHex(): HexColour;
-	/**
-	 * Convert the colour to an HSL-colour
-	 */
-	toHsl(): HSLColour;
-	toString(): string;
-	/**
-	 * Convert an RGB-colour to a hex-colour
-	 */
-	static toHex(value: RGBColourValue): HexColour;
-	/**
-	 * - Convert an RGB-colour to an HSL-colour
-	 */
-	static toHsl(rgb: RGBColourValue): HSLColour;
-}
-/**
- * Get an RGB-colour from a value-object
- */
-export declare function getRGBColour(value: RGBColourValue): RGBColour;
-/**
- * Is the value a colour?
- */
-export declare function isColour(
-	value: unknown,
-): value is HexColour | HSLColour | RGBColour;
-/**
- * Is the value a hex-colour?
- */
-export declare function isHexColour(value: unknown): value is HexColour;
-/**
- * Is the value an HSL-colour?
- */
-export declare function isHSLColour(value: unknown): value is HSLColour;
-/**
- * Is the value an RGB-colour?
- */
-export declare function isRGBColour(value: unknown): value is RGBColour;
-/**
- * Get a foreground colour _(usually text)_ based on a background colour's luminance
- */
-export declare function getForegroundColour(value: RGBColourValue): string;
-/**
- * Is the value an array or a record?
- */
-export declare function isArrayOrPlainObject(
-	value: unknown,
-): value is ArrayOrPlainObject;
-/**
- * Is the array or object completely empty or only containing `null` or `undefined` values?
- */
-export declare function isEmpty(value: ArrayOrPlainObject): boolean;
-/**
- * Is the value a key?
- */
-export declare function isKey(value: unknown): value is Key;
-/**
- * Is the value undefined or null?
- */
-export declare function isNullable(value: unknown): value is undefined | null;
-/**
- * Is the value undefined, null, or an empty string?
- */
-export declare function isNullableOrEmpty(
-	value: unknown,
-): value is undefined | null | '';
-/**
- * Is the value undefined, null, or a whitespace-only string?
- */
-export declare function isNullableOrWhitespace(
-	value: unknown,
-): value is undefined | null | '';
-/**
- * Is the value a number?
- */
-export declare function isNumber(value: unknown): value is number;
-/**
- * Is the value a number, or a number-like string?
- */
-export declare function isNumerical(
-	value: unknown,
-): value is number | `${number}`;
-/**
- * Is the value an object?
- */
-export declare function isObject(value: unknown): value is object;
-/**
- * Is the value a plain object?
- */
-export declare function isPlainObject(value: unknown): value is PlainObject;
-/**
- * Is the value a primitive value?
- */
-export declare function isPrimitive(value: unknown): value is Primitive;
-declare class Logger {
-	/**
-	 * Logs any number of values at the "debug" log level
-	 */
-	get debug(): {
-		(...data: any[]): void;
-		(message?: any, ...optionalParams: any[]): void;
-	};
-	/**
-	 * Logs the value and shows all its properties
-	 */
-	get dir(): {
-		(item?: any, options?: any): void;
-		(obj: any, options?: import('util').InspectOptions): void;
-	};
-	/**
-	 * Is logging to the console enabled? _(defaults to `true`)_
-	 */
-	get enabled(): boolean;
-	/**
-	 * Enable or disable logging to the console
-	 */
-	set enabled(value: boolean);
-	/**
-	 * Logs any number of values at the "error" log level
-	 */
-	get error(): {
-		(...data: any[]): void;
-		(message?: any, ...optionalParams: any[]): void;
-	};
-	/**
-	 * Logs any number of values at the "info" log level
-	 */
-	get info(): {
-		(...data: any[]): void;
-		(message?: any, ...optionalParams: any[]): void;
-	};
-	/**
-	 * Logs any number of values at the "log" log level
-	 */
-	get log(): {
-		(...data: any[]): void;
-		(message?: any, ...optionalParams: any[]): void;
-	};
-	/**
-	 * Logs data as a table, with optional properties to use as columns
-	 */
-	get table(): {
-		(tabularData?: any, properties?: string[]): void;
-		(tabularData: any, properties?: readonly string[]): void;
-	};
-	/**
-	 * Logs any number of values together with a trace from where it was called
-	 */
-	get trace(): {
-		(...data: any[]): void;
-		(message?: any, ...optionalParams: any[]): void;
-	};
 	/**
-	 * Logs any number of values at the "warn" log level
+	 * @inheritdoc
 	 */
-	get warn(): {
-		(...data: any[]): void;
-		(message?: any, ...optionalParams: any[]): void;
-	};
+	toHex(): HexColour;
 	/**
-	 * - Starts a logged timer with a label
-	 * - Returns a `Time`-object for logging the current duration of the timer and stopping the timer _(and logging the total duration)_
+	 * Convert the colour to an HSL-colour
 	 */
-	time(label: string): Time;
-}
-declare class Time {
-	private readonly state;
-	constructor(label: string);
+	toHsl(): HSLColour;
 	/**
-	 * - Logs the current duration of the timer
-	 * - Ignored if logging is disabled
+	 * @inheritdoc
 	 */
-	log(): void;
+	toString(): string;
 	/**
-	 * - Stops the timer and logs the total duration
-	 * - Will always log the total duration, even if logging is disabled
+	 * Convert an RGB-colour to a hex-colour
 	 */
-	stop(): void;
+	static toHex(value: RGBColourValue): HexColour;
+	/**
+	 * - Convert an RGB-colour to an HSL-colour
+	 */
+	static toHsl(rgb: RGBColourValue): HSLColour;
 }
-export declare const logger: Logger;
-/**
- * Get the average value from a list of numbers
- */
-export declare function average(values: number[]): number;
-/**
- * Get the maximum value from a list of numbers
- */
-export declare function max(values: number[]): number;
-/**
- * Get the minimum value from a list of numbers
- */
-export declare function min(values: number[]): number;
-/**
- * Rounds a number to a specific number of decimal places _(defaults to 0)_
- */
-export declare function round(value: number, decimals?: number): number;
-/**
- * Get the sum of a list of numbers
- */
-export declare function sum(values: number[]): number;
-/**
- * Is the number between a minimum and maximum value?
- */
-export declare function between(
-	value: number,
-	min: number,
-	max: number,
-): boolean;
-/**
- * - Clamps a number between a minimum and maximum value
- * - If `loop` is `true`, when the value is less than the minimum, it will be clamped as the maximum, and vice versa
- */
-export declare function clamp(
-	value: number,
-	min: number,
-	max: number,
-	loop?: boolean,
-): number;
-/**
- * - Gets the number value from an unknown value
- * - Returns `NaN` if the value is `undefined`, `null`, or cannot be parsed
- * - Based on Lodash :-)
- */
-export declare function getNumber(value: unknown): number;
-/**
- * Converts a query string to a plain _(nested)_ object
- */
-export declare function fromQuery(query: string): PlainObject;
-/**
- * Converts a plain _(nested)_ object to a query string
- */
-export declare function toQuery(parameters: PlainObject): string;
-/**
- * Queues a callback to be executed at the next best time
- */
-export declare function queue(callback: () => void): void;
-/**
- * Returns a random boolean
- */
-export declare function getRandomBoolean(): boolean;
-/**
- * Returns a random string of characters with a specified length
- * - `selection` defaults to all lowercase letters in the English alphabet
- */
-export declare function getRandomCharacters(
-	length: number,
-	selection?: string,
-): string;
-/**
- * Returns a random hexadecimal colour
- */
-export declare function getRandomColour(): string;
-/**
- * Returns a random date
- */
-export declare function getRandomDate(earliest?: Date, latest?: Date): Date;
 /**
- * Returns a random floating-point number
+ * Get an RGB-colour from a value-object
  */
-export declare function getRandomFloat(min?: number, max?: number): number;
+export declare function getRGBColour(value: RGBColourValue): RGBColour;
 /**
- * Returns a random hexadecimal character
+ * Is the value a colour?
  */
-export declare function getRandomHex(): string;
+export declare function isColour(
+	value: unknown,
+): value is HexColour | HSLColour | RGBColour;
 /**
- * Returns a random integer
+ * Is the value a hex-colour?
  */
-export declare function getRandomInteger(min?: number, max?: number): number;
+export declare function isHexColour(value: unknown): value is HexColour;
 /**
- * Returns a random item from an array
+ * Is the value an HSL-colour?
  */
-export declare function getRandomItem<Value>(array: Value[]): Value;
+export declare function isHSLColour(value: unknown): value is HSLColour;
 /**
- * - Returns an amount of random items from an array
- * - If `amount` is not specified, a shuffled array will be returned instead
+ * Is the value an RGB-colour?
  */
-export declare function getRandomItems<Value>(
-	array: Value[],
-	amount?: number,
-): Value[];
+export declare function isRGBColour(value: unknown): value is RGBColour;
 /**
- * A Map with a maximum size
- * - Maximum size defaults to _2^20_; any provided size will be clamped at _2^24_
- * - Behaviour is similar to a _LRU_-cache, where the least recently used entries are removed
+ * Get a foreground colour _(usually text)_ based on a background colour's luminance
  */
-export declare class SizedMap<Key = unknown, Value = unknown> extends Map<
-	Key,
-	Value
-> {
-	private readonly maximumSize;
+export declare function getForegroundColour(value: RGBColourValue): string;
+export declare class Emitter<Value> {
+	private readonly state;
 	/**
-	 * Is the Map full?
+	 * Is the emitter active?
 	 */
-	get full(): boolean;
+	get active(): boolean;
 	/**
-	 * The maximum size of the Map
+	 * The observable that can be subscribed to
 	 */
-	get maximum(): number;
+	get observable(): Observable<Value>;
 	/**
-	 * Creates a new Map with entries and a maximum size _(2^20)_
+	 * The current value
 	 */
-	constructor(entries: Array<[Key, Value]>);
+	get value(): Value;
+	constructor(value: Value);
 	/**
-	 * Creates a new Map with a maximum size _(but clamped at 2^24)_
+	 * Destroy the emitter
 	 */
-	constructor(maximum: number);
+	destroy(): void;
 	/**
-	 * Creates a new Map with _(optional)_ entries and a maximum size _(defaults to 2^20; clamped at 2^24)_
+	 * Emit a new value _(and optionally finishes the emitter)_
 	 */
-	constructor(entries?: Array<[Key, Value]>, maximum?: number);
+	emit(value: Value, finish?: boolean): void;
 	/**
-	 * @inheritdoc
+	 * Emit an error _(and optionally finishes the emitter)_
 	 */
-	get(key: Key): Value | undefined;
+	error(error: Error, finish?: boolean): void;
 	/**
-	 * @inheritdoc
+	 * Finish the emitter
 	 */
-	set(key: Key, value: Value): this;
+	finish(): void;
 }
-/**
- * A Set with a maximum size
- * - Maximum size defaults to _2^20_; any provided size will be clamped at _2^24_
- * - Behaviour is similar to a _LRU_-cache, where the oldest values are removed
- */
-export declare class SizedSet<Value = unknown> extends Set<Value> {
-	private readonly maximumSize;
+export declare class Observable<Value> {
+	private readonly state;
+	constructor(
+		emitter: Emitter<Value>,
+		observers: Map<Subscription<Value>, Observer<Value>>,
+	);
 	/**
-	 * Is the Set full?
+	 * Subscribe to value changes
 	 */
-	get full(): boolean;
+	subscribe(observer: Observer<Value>): Subscription<Value>;
 	/**
-	 * The maximum size of the Set
+	 * Subscribe to value changes
 	 */
-	get maximum(): number;
+	subscribe(
+		onNext: (value: Value) => void,
+		onError?: (error: Error) => void,
+		onComplete?: () => void,
+	): Subscription<Value>;
+}
+export type ObservableState<Value> = {
+	emitter: Emitter<Value>;
+	observers: Map<Subscription<Value>, Observer<Value>>;
+};
+export type Observer<Value> = {
 	/**
-	 * Creates a new Set with values and a maximum size _(2^20)_
+	 * Callback for when the observable is complete
 	 */
-	constructor(values: Value[]);
+	complete?: () => void;
 	/**
-	 * Creates a new Set with a maximum size _(but clamped at 2^24)_
+	 * Callback for when the observable has an error
 	 */
-	constructor(maximum: number);
+	error?: (error: Error) => void;
 	/**
-	 * Creates a new Set with _(optional)_ values and a maximum size _(defaults to 2^20; clamped at 2^24)_
+	 * Callback for when the observable has a new value
 	 */
-	constructor(values?: Value[], maximum?: number);
+	next?: (value: Value) => void;
+};
+export declare class Subscription<Value> {
+	private readonly state;
+	constructor(state: ObservableState<Value>);
 	/**
-	 * @inheritdoc
+	 * Is the subscription closed?
 	 */
-	add(value: Value): this;
+	get closed(): boolean;
 	/**
-	 * Get a value from an index in the Set, if it exists
-	 * - Negative indices are counted from the end
-	 * - Optionally move the value to the end with `update`
+	 * Destroy the subscription
 	 */
-	at(index: number, update?: boolean): Value | undefined;
+	destroy(): void;
 	/**
-	 * Get a value from the Set, if it exists _(and move it to the end)_
+	 * Unsubscribe from its observable
 	 */
-	get(value: Value, update?: boolean): Value | undefined;
+	unsubscribe(): void;
+}
+/**
+ * Create a new emitter
+ */
+export declare function emitter<Value>(value: Value): Emitter<Value>;
+export type Debounced<Callback extends GenericCallback> = Callback & {
+	/**
+	 * Cancel the debounce
+	 */
+	cancel: () => void;
+};
+declare class Memoised<Callback extends GenericCallback> {
+	readonly state: MemoisedState<Callback>;
+	constructor(callback: Callback);
+	/**
+	 * Clear the cache
+	 */
+	clear(): void;
+	/**
+	 * Delete a result from the cache
+	 */
+	delete(key: Parameters<Callback>[0]): boolean;
+	/**
+	 * Destroy the instance, clearing its cache and removing its callback
+	 */
+	destroy(): void;
+	/**
+	 * Get a result from the cache if it exists _(or `undefined` otherwise)_
+	 */
+	get(key: Parameters<Callback>[0]): ReturnType<Callback> | undefined;
+	/**
+	 * Does the result exist?
+	 */
+	has(key: Parameters<Callback>[0]): boolean;
+	/**
+	 * Get the result from the cache if it exists; otherwise runs the callback, caches the result, and returns it
+	 */
+	run(...parameters: Parameters<Callback>): ReturnType<Callback>;
 }
+export type MemoisedState<Callback extends GenericCallback> = {
+	cache: Map<Parameters<Callback>[0], ReturnType<Callback>>;
+	getter: (...parameters: Parameters<Callback>) => ReturnType<Callback>;
+};
+/**
+ * - Debounce a function, ensuring it is only called after `time` milliseconds have passed
+ * - On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
+ * - Time is clamped between _0_ and _1000_ milliseconds
+ * - Returns the callback with an added `cancel`-method for manually cancelling the debounce
+ */
+export declare function debounce<Callback extends GenericCallback>(
+	callback: Callback,
+	time?: number,
+): Debounced<Callback>;
+/**
+ * Memoise a function, caching and retrieving results based on the first parameter
+ */
+export declare function memoise<Callback extends GenericCallback>(
+	callback: Callback,
+): Memoised<Callback>;
+/**
+ * A function that does nothing, which can be useful, I guess…
+ */
+export declare function noop(): void;
+/**
+ * - Throttle a function, ensuring it is only called once every `time` milliseconds
+ * - Time is clamped between _0_ and _1000_ milliseconds
+ */
+export declare function throttle<Callback extends GenericCallback>(
+	callback: Callback,
+	time?: number,
+): Callback;
 /**
  * Convert a string to camel case _(thisIsCamelCase)_
  */
@@ -2390,6 +2777,9 @@ export type Options = {
 	 */
 	pattern?: RegExp;
 };
+/**
+ * Render a string from a template with variables
+ */
 export declare function template(
 	value: string,
 	variables: PlainObject,
@@ -2404,18 +2794,18 @@ export declare function createUuid(): string;
  */
 export declare function getString(value: unknown): string;
 /**
- * Joins an array into a string while ignoring empty values _(with an optional delimiter)_
+ * Join an array into a string while ignoring empty values _(with an optional delimiter)_
  */
 export declare function join(value: unknown[], delimiter?: string): string;
 /**
- * Parses a JSON string into its proper value _(or `undefined` if it fails)_
+ * Parse a JSON string into its proper value _(or `undefined` if it fails)_
  */
 export declare function parse(
 	value: string,
 	reviver?: (this: unknown, key: string, value: unknown) => unknown,
 ): unknown;
 /**
- * Truncates a string to a specified length, when possible
+ * Truncate a string to a specified length, when possible
  * - Returned as-is if the string is already short enough
  * - A suffix may be appended to the truncated string, e.g., an ellipsis
  */
@@ -2428,8 +2818,10 @@ export declare function truncate(
  * Split a string into words _(and other readable parts)_
  */
 export declare function words(value: string): string[];
-export declare function clone(fn: (...args: unknown[]) => unknown): null;
-export declare function clone<Value>(value: Value): Value;
+/**
+ * Clone any kind of value _(deeply, if needed)_
+ */
+export declare function clone(value: unknown): {} | null | undefined;
 /**
  * Compare two values _(for sorting purposes)_
  */
@@ -2498,7 +2890,7 @@ export type MergeOptions = {
 	skipNullable?: boolean;
 };
 /**
- * Merges multiple arrays or objects into a single one
+ * Merge multiple arrays or objects into a single one
  */
 export declare function merge<Model extends ArrayOrPlainObject>(
 	values: Model[],
@@ -2531,7 +2923,7 @@ export type Smushed<Value> = Simplify<{
 	[Key in Paths<Value>]: Get<Value, ToString<Key>>;
 }>;
 /**
- * Smushes an object into a flat object with dot notation keys
+ * Smush an object into a flat object that uses dot notation keys
  */
 export declare function smush<Value extends PlainObject>(
 	value: Value,
@@ -2545,13 +2937,13 @@ export type Unsmushed<Value extends PlainObject> = Simplify<
 	>
 >;
 /**
- * Unsmushes a smushed object _(turning dot notation keys into nested keys)_
+ * Unsmush a smushed object _(turning dot notation keys into nested keys)_
  */
 export declare function unsmush<Value extends PlainObject>(
 	value: Value,
 ): Unsmushed<Value>;
 /**
- * Creates a new object with only the specified keys
+ * Create a new object with only the specified keys
  */
 export declare function partial<
 	Value extends PlainObject,