@oscarpalmer/atoms 0.218.0 → 0.219.0

package/dist/index.d.mts

@@ -49,7 +49,7 @@ export type KeyOrCallbackValue<Item, Arg extends KeyOrCallback<Item>> = Arg exte
 /**
  * A nested array
  */
-export type NestedArray<Value> = Value extends Array<infer NestedValue> ? NestedArray<NestedValue> : Value;
+export type NestedArray<Value> = Value extends ReadonlyArray<infer NestedValue> ? NestedArray<NestedValue> : Value;
 /**
  * All nested keys of an object as dot notation strings _(up to 5 levels deep)_
  */
@@ -145,7 +145,7 @@ export type Unsubscriber = () => void;
  * ); // => [{id: 1}, {id: 3}]
  * ```
  */
-export declare function exclude<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
+export declare function exclude<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
 /**
  * Get a filtered array of items that do not match the value
  *
@@ -165,7 +165,25 @@ export declare function exclude<Item, Callback extends (item: Item, index: numbe
  * ); // => [{id: 1}, {id: 3}]
  * ```
  */
-export declare function exclude<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): unknown[];
+export declare function exclude<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
+/**
+ * Get a narrowed array of items that do not match the filter
+ *
+ * _Available as `exclude` and `filter.remove`_
+ *
+ * @param array Array to search in
+ * @param filter Type guard to exclude and narrow down the items
+ * @returns Narrowed array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [1, 'a', 2, 'b'],
+ *   (item): item is string => typeof item === 'string',
+ * ); // => [1, 2]
+ * ```
+ */
+export declare function exclude<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Array<Exclude<Item, Narrowed>>;
 /**
  * Get a filtered array of items that do not match the filter
  *
@@ -183,7 +201,7 @@ export declare function exclude<Item extends PlainObject, ItemKey extends keyof
  * ); // => [{id: 1}, {id: 3}]
  * ```
  */
-export declare function exclude<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): unknown[];
+export declare function exclude<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item[];
 /**
  * Get a filtered array of items that do not match the given item
  *
@@ -198,7 +216,7 @@ export declare function exclude<Item>(array: Item[], filter: (item: Item, index:
  * exclude([1, 2, 3], 2); // => [1, 3]
  * ```
  */
-export declare function exclude<Item>(array: Item[], item: Item): unknown[];
+export declare function exclude<Item>(array: Item[], item: Item): Item[];
 /**
  * Get a filtered array of items
  *
@@ -235,6 +253,22 @@ export declare function filter<Item, Callback extends (item: Item, index: number
  * ```
  */
 export declare function filter<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
+/**
+ * Get a narrowed array of items matching the filter
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns Narrowed array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2}, {id: 3, tags: ['c']}],
+ *   (item): item is {id: number; tags: string[]} => item.tags != null,
+ * ); // => [{id: 1, tags: ['a', 'b']}, {id: 3, tags: ['c']}]
+ * ```
+ */
+export declare function filter<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed[];
 /**
  * Get a filtered array of items matching the filter
  *
@@ -305,6 +339,22 @@ export declare function find<Item, Callback extends (item: Item, index: number,
  * ```
  */
 export declare function find<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
+/**
+ * Get the first narrowed item matching the filter
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns First narrowed item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => {id: 2, value: 'a'}
+ * ```
+ */
+export declare function find<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | undefined;
 /**
  * Get the first item matching the filter
  *
@@ -374,6 +424,24 @@ export declare function findLast<Item, Callback extends (item: Item, index: numb
  * ```
  */
 export declare function findLast<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
+/**
+ * Get the last narrowed item matching the filter
+ *
+ * _Available as `findLast` and `find.last`_
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns Last narrowed item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => {id: 3, value: 'b'}
+ * ```
+ */
+export declare function findLast<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | undefined;
 /**
  * Get the last item matching the filter
  *
@@ -448,6 +516,22 @@ export declare function first<Item, Callback extends (item: Item, index: number,
  * ```
  */
 export declare function first<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
+/**
+ * Get the first narrowed item matching the filter
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns First narrowed item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => {id: 2, value: 'a'}
+ * ```
+ */
+export declare function first<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | undefined;
 /**
  * Get the first item matching the filter
  *
@@ -481,7 +565,7 @@ export declare function first<Item>(array: Item[]): Item | undefined;
 /**
  * Get the first item matching the given value, or a default value if no match is found
  *
- * _Available as `firstOrDefault` and `first.default`_
+ * _Available as `firstOrDefault` and `first.defaulted`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -503,7 +587,7 @@ export declare function firstOrDefault<Item, Callback extends (item: Item, index
 /**
  * Get the first item matching the given value by key, or a default value if no match is found
  *
- * _Available as `firstOrDefault` and `first.default`_
+ * _Available as `firstOrDefault` and `first.defaulted`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -522,10 +606,30 @@ export declare function firstOrDefault<Item, Callback extends (item: Item, index
  * ```
  */
 export declare function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], defaultValue: Item, key: ItemKey, value: Item[ItemKey]): Item;
+/**
+ * Get the first narrowed item matching the filter, or a default value if no match is found
+ *
+ * _Available as `firstOrDefault` and `first.defaulted`_
+ *
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param filter Type guard to match and narrow down the items
+ * @returns First narrowed item that matches the filter, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   {id: -1, value: 'c'},
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => {id: 2, value: 'a'}
+ * ```
+ */
+export declare function firstOrDefault<Item, Narrowed extends Item, Default>(array: Item[], defaultValue: Default, filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | Default;
 /**
  * Get the first item matching the filter, or a default value if no match is found
  *
- * _Available as `firstOrDefault` and `first.default`_
+ * _Available as `firstOrDefault` and `first.defaulted`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -545,7 +649,7 @@ export declare function firstOrDefault<Item>(array: Item[], defaultValue: Item,
 /**
  * Get the first item from an array, or a default value if the array is empty
  *
- * _Available as `firstOrDefault` and `first.default`_
+ * _Available as `firstOrDefault` and `first.defaulted`_
  *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
@@ -787,9 +891,7 @@ export declare function getArray<Value>(value: Value): Value[];
  * Comparison of an array within another array
  */
 type ArrayComparison = "end" | "inside" | "invalid" | "outside" | "same" | "start";
-type ArrayMapKeyOrCallback<Item> = ((item: Item, index: number, array: Item[]) => unknown) | (Item extends PlainObject ? keyof Item : never);
-type ArrayMapped<Item, Map extends ArrayMapKeyOrCallback<Item>> = Map extends ((item: Item, index: number, array: Item[]) => unknown) ? ReturnType<Map> : Map extends keyof Item ? Item[Map] : never;
-type ArrayObjectKeysOf<Item> = { [Key in keyof Item]: Item[Key] extends PlainObject ? Key : never; }[keyof Item];
+type ArrayFlattened<Value> = Value extends ReadonlyArray<infer Inner> ? Inner : Value;
 //#endregion
 //#region src/internal/array/match.d.ts
 /**
@@ -1044,6 +1146,11 @@ export declare function startsWithArray<Item>(haystack: Item[], needle: Item[]):
  *
  * @param array Original array
  * @returns Shuffled array
+ *
+ * @example
+ * ```typescript
+ * shuffle([1, 2, 3]); // => [3, 1, 2] (maybe? it's random, you know)
+ * ```
  */
 export declare function shuffle<Item>(array: Item[]): Item[];
 //#endregion
@@ -1355,7 +1462,7 @@ export declare function intersection<First, Second>(first: First[], second: Seco
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
- * @returns Partitioned array of items
+ * @returns Tuple of matching and non-matching items
  *
  * @example
  * ```typescript
@@ -1366,14 +1473,14 @@ export declare function intersection<First, Second>(first: First[], second: Seco
  * ); // => [[{id: 2}], [{id: 1}, {id: 3}]]
  * ```
  */
-export declare function partition<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[][];
+export declare function partition<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): [Item[], Item[]];
 /**
  * Get a partitioned array of items
  *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
- * @returns Partitioned array of items
+ * @returns Tuple of matching and non-matching items
  *
  * @example
  * ```typescript
@@ -1384,13 +1491,29 @@ export declare function partition<Item, Callback extends (item: Item, index: num
  * ); // => [[{id: 2}], [{id: 1}, {id: 3}]]
  * ```
  */
-export declare function partition<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[][];
+export declare function partition<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): [Item[], Item[]];
+/**
+ * Get a partitioned array of items
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns Tuple of matching and non-matching items
+ *
+ * @example
+ * ```typescript
+ * partition(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => [[{id: 2, value: 'a'}, {id: 3, value: 'b'}], [{id: 1, value: 10}]]
+ * ```
+ */
+export declare function partition<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): [Narrowed[], Array<Exclude<Item, Narrowed>>];
 /**
  * Get a partitioned array of items
  *
  * @param array Array to search in
  * @param filter Filter callback to match items
- * @returns Partitioned array of items
+ * @returns Tuple of matching and non-matching items
  *
  * @example
  * ```typescript
@@ -1400,20 +1523,20 @@ export declare function partition<Item extends PlainObject, ItemKey extends keyo
  * ); // => [[{id: 2}], [{id: 1}, {id: 3}]]
  * ```
  */
-export declare function partition<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item[][];
+export declare function partition<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): [Item[], Item[]];
 /**
  * Get a partitioned array of items matching the given item
  *
  * @param array Array to search in
  * @param item Item to match against
- * @returns Partitioned array of items
+ * @returns Tuple of matching and non-matching items
  *
  * @example
  * ```typescript
  * partition([1, 2, 3, 4, 5], 3); // => [[3], [1, 2, 4, 5]]
  * ```
  */
-export declare function partition<Item>(array: Item[], item: Item): Item[][];
+export declare function partition<Item>(array: Item[], item: Item): [Item[], Item[]];
 //#endregion
 //#region src/array/push.d.ts
 /**
@@ -1438,6 +1561,12 @@ export declare function push<Item>(array: Item[], pushed: Item[]): number;
  *
  * @param array Array to reverse
  * @returns Reversed array
+ *
+ * @example
+ * ```typescript
+ * reverse([1, 2, 3]);       // => [3, 2, 1]
+ * reverse(['a', 'b', 'c']); // => ['c', 'b', 'a']
+ * ```
  */
 export declare function reverse<Item>(array: Item[]): Item[];
 //#endregion
@@ -1482,6 +1611,28 @@ export declare function single<Item, Callback extends (item: Item, index: number
  * ```
  */
 export declare function single<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
+/**
+ * Get the _only_ narrowed item matching the filter
+ *
+ * _Throws an error if multiple items match the filter_
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns Only narrowed item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * single(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: number} => typeof item.value === 'number',
+ * ); // => {id: 1, value: 10}
+ * single(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => throws an error as there are two matches
+ * ```
+ */
+export declare function single<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | undefined;
 /**
  * Get the _only_ item matching the filter
  *
@@ -2024,7 +2175,7 @@ export declare function update<Item>(destination: Item[], updated: Item[]): Item
 //#endregion
 //#region src/array/last.d.ts
 /**
- * Get the last items matching the given value
+ * Get the last item matching the given value
  *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
@@ -2042,7 +2193,7 @@ export declare function update<Item>(destination: Item[], updated: Item[]): Item
  */
 export declare function last<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item | undefined;
 /**
- * Get the first item matching the given value by key
+ * Get the last item matching the given value by key
  *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
@@ -2059,6 +2210,22 @@ export declare function last<Item, Callback extends (item: Item, index: number,
  * ```
  */
 export declare function last<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
+/**
+ * Get the last narrowed item matching the filter
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns Last narrowed item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => {id: 3, value: 'b'}
+ * ```
+ */
+export declare function last<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | undefined;
 /**
  * Get the last item matching the filter
  *
@@ -2088,9 +2255,9 @@ export declare function last<Item>(array: Item[], filter: (item: Item, index: nu
  */
 export declare function last<Item>(array: Item[]): Item | undefined;
 /**
- * Get the last item matching the given value
+ * Get the last item matching the given value, or a default value if no match is found
  *
- * _Available as `lastOrDefault` and `last.default`_
+ * _Available as `lastOrDefault` and `last.defaulted`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -2110,9 +2277,9 @@ export declare function last<Item>(array: Item[]): Item | undefined;
  */
 export declare function lastOrDefault<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], defaultValue: Item, callback: Callback, value: ReturnType<Callback>): Item;
 /**
- * Get the last item matching the given value by key
+ * Get the last item matching the given value by key, or a default value if no match is found
  *
- * _Available as `lastOrDefault` and `last.default`_
+ * _Available as `lastOrDefault` and `last.defaulted`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -2132,9 +2299,29 @@ export declare function lastOrDefault<Item, Callback extends (item: Item, index:
  */
 export declare function lastOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], defaultValue: Item, key: ItemKey, value: Item[ItemKey]): Item;
 /**
- * Get the last item matching the filter
+ * Get the last narrowed item matching the filter, or a default value if no match is found
  *
- * _Available as `lastOrDefault` and `last.default`_
+ * _Available as `lastOrDefault` and `last.defaulted`_
+ *
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param filter Type guard to match and narrow down the items
+ * @returns Last narrowed item that matches the filter, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   {id: -1, value: 'c'},
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => {id: 3, value: 'b'}
+ * ```
+ */
+export declare function lastOrDefault<Item, Narrowed extends Item, Default>(array: Item[], defaultValue: Default, filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | Default;
+/**
+ * Get the last item matching the filter, or a default value if no match is found
+ *
+ * _Available as `lastOrDefault` and `last.defaulted`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -2152,9 +2339,9 @@ export declare function lastOrDefault<Item extends PlainObject, ItemKey extends
  */
 export declare function lastOrDefault<Item>(array: Item[], defaultValue: Item, filter: (item: Item, index: number, array: Item[]) => boolean): Item;
 /**
- * Get the last item from an array
+ * Get the last item from an array, or a default value if the array is empty
  *
- * _Available as `lastOrDefault` and `last.default`_
+ * _Available as `lastOrDefault` and `last.defaulted`_
  *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
@@ -2336,190 +2523,172 @@ export declare namespace move {
 //#endregion
 //#region src/array/select.d.ts
 /**
- * Get a filtered and mapped array of items
+ * Get a narrowed, mapped, and flattened array of items
  *
- * @param array Array to search in
- * @param filterCallback Callback to get an item's value for matching
- * @param filterValue Value to match against
- * @param map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
- *
- * @example
- * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id,
- *   2,
- *   item => item.name,
- * ); // => ['Bob']
- * ```
- */
-export declare function filterAndMap<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, map: Map): Array<ArrayMapped<Item, Map>>;
-/**
- * Get a filtered and mapped array of items
+ * _Available as `filterAndFlatMap`, `filterAndMap.flat`, and `select.flat`_
  *
- * @param array Array to search in
- * @param filterKey Key to get an item's value for matching
- * @param filterValue Value to match against
- * @param map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * @param array Array to select from
+ * @param filter Type guard to filter and narrow down the items
+ * @param mapper Callback to map and flatten the narrowed items
+ * @returns Narrowed, mapped, and flattened array of items
  *
  * @example
  * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   'id',
- *   2,
- *   'name',
- * ); // => ['Bob']
+ * filterAndFlatMap(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2}, {id: 3, tags: ['c']}],
+ *   (item): item is {id: number; tags: string[]} => item.tags != null,
+ *   item => item.tags,
+ * ); // => ['a', 'b', 'c']
  * ```
  */
-export declare function filterAndMap<Item extends PlainObject, ItemKey extends keyof Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], map: Map): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndFlatMap<Item, Narrowed extends Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed, mapper: (item: Narrowed, index: number, array: Item[]) => Mapped): Array<ArrayFlattened<Mapped>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a filtered, mapped, and flattened array of items
  *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @param map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * _Available as `filterAndFlatMap`, `filterAndMap.flat`, and `select.flat`_
+ *
+ * @param array Array to select from
+ * @param filter Callback to filter the items
+ * @param mapper Callback to map and flatten the filtered items
+ * @returns Filtered, mapped, and flattened array of items
  *
  * @example
  * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id === 2,
- *   item => item.name,
- * ); // => ['Bob']
+ * filterAndFlatMap(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2, tags: ['c']}, {id: 3, tags: ['d', 'e']}],
+ *   item => item.id !== 2,
+ *   item => item.tags,
+ * ); // => ['a', 'b', 'd', 'e']
  * ```
  */
-export declare function filterAndMap<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: Map): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndFlatMap<Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, mapper: (item: Item, index: number, array: Item[]) => Mapped): Array<ArrayFlattened<Mapped>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a narrowed and mapped array of items
  *
- * @param array Array to search in
- * @param item Item to match against
- * @param map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * _Available as `filterAndMap` and `select`_
+ *
+ * @param array Array to select from
+ * @param filter Type guard to filter and narrow down the items
+ * @param mapper Callback to map the narrowed items
+ * @returns Narrowed and mapped array of items
  *
  * @example
  * ```typescript
- * select(
- *   [1, 2, 3, 2, 1],
- *   3,
- *   value => value ** 2,
- * ); // => [9]
+ * filterAndMap(
+ *   [{id: 1, name: 'Alice'}, {id: 2}, {id: 3, name: 'Charlie'}],
+ *   (item): item is {id: number; name: string} => item.name != null,
+ *   item => item.name.toUpperCase(),
+ * ); // => ['ALICE', 'CHARLIE']
  * ```
  */
-export declare function filterAndMap<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], item: Item, map: Map): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndMap<Item, Narrowed extends Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed, mapper: (item: Narrowed, index: number, array: Item[]) => Mapped): Mapped[];
 /**
- * Get a mapped and filtered array of items
+ * Get a filtered and mapped array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `filterAndMap` and `select`_
  *
- * @param array Array to search in
- * @param map Callback or key to map the items
- * @param filterCallback Callback to get a mapped value's value for matching
- * @param filterValue Value to match against
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param filter Callback to filter the items
+ * @param mapper Callback to map the filtered items
+ * @returns Filtered and mapped array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
+ * filterAndMap(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id === 2,
  *   item => item.name,
- *   value => value.length,
- *   3,
  * ); // => ['Bob']
  * ```
  */
-export declare function mapAndFilter<Item, Map extends ArrayMapKeyOrCallback<Item>, FilterCallback extends (item: ArrayMapped<Item, Map>, index: number, array: Item[]) => unknown>(array: Item[], map: Map, filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndMap<Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, mapper: (item: Item, index: number, array: Item[]) => Mapped): Mapped[];
 /**
- * Get a mapped and filtered array of items
+ * Get a mapped, flattened, and narrowed array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `flatMapAndFilter`, `mapAndFilter.flat`, and `reverseSelect.flat`_
  *
- * @param array Array to search in
- * @param map Callback to map the items
- * @param filterKey Key to get a mapped value's value for matching
- * @param filterValue Value to match against
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param mapper Callback to map and flatten the items
+ * @param filter Type guard to filter and narrow down the flattened items
+ * @returns Mapped, flattened, and narrowed array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => ({label: item.name}),
- *   'label',
- *   'Bob',
- * ); // => [{label: 'Bob'}]
+ * flatMapAndFilter(
+ *   [{id: 1, values: [1, 'a']}, {id: 2, values: ['b', 2]}],
+ *   item => item.values,
+ *   (value): value is number => typeof value === 'number',
+ * ); // => [1, 2]
  * ```
  */
-export declare function mapAndFilter<Item, MapCallback extends (item: Item, index: number, array: Item[]) => PlainObject, ItemKey extends keyof ReturnType<MapCallback>>(array: Item[], map: MapCallback, filterKey: ItemKey, filterValue: ReturnType<MapCallback>[ItemKey]): Array<ReturnType<MapCallback>>;
+export declare function flatMapAndFilter<Item, Mapped, Narrowed extends ArrayFlattened<Mapped>>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: ArrayFlattened<Mapped>, index: number, array: Item[]) => item is Narrowed): Narrowed[];
 /**
- * Get a mapped and filtered array of items
+ * Get a mapped, flattened, and filtered array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `flatMapAndFilter`, `mapAndFilter.flat`, and `reverseSelect.flat`_
  *
- * @param array Array to search in
- * @param map Key to map the items
- * @param filterKey Key to get a mapped value's value for matching
- * @param filterValue Value to match against
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param mapper Callback to map and flatten the items
+ * @param filter Callback to filter the flattened items
+ * @returns Mapped, flattened, and filtered array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [{meta: {tag: 'a'}}, {meta: {tag: 'b'}}],
- *   'meta',
- *   'tag',
- *   'b',
- * ); // => [{tag: 'b'}]
+ * flatMapAndFilter(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2, tags: ['c']}, {id: 3, tags: ['b', 'd']}],
+ *   item => item.tags,
+ *   tag => tag !== 'b',
+ * ); // => ['a', 'c', 'd']
  * ```
  */
-export declare function mapAndFilter<Item, MapKey extends ArrayObjectKeysOf<Item>, ItemKey extends keyof Item[MapKey]>(array: Item[], map: MapKey, filterKey: ItemKey, filterValue: Item[MapKey][ItemKey]): Array<Item[MapKey]>;
+export declare function flatMapAndFilter<Item, Mapped>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: ArrayFlattened<Mapped>, index: number, array: Item[]) => boolean): Array<ArrayFlattened<Mapped>>;
 /**
- * Get a mapped and filtered array of items
+ * Get a mapped and narrowed array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `mapAndFilter`, `reverseSelect`, `filterAndMap.reverse`, and `select.reverse`_
  *
- * @param array Array to search in
- * @param map Callback or key to map the items
- * @param filter Filter callback to match mapped values
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param mapper Callback to map the items
+ * @param filter Type guard to filter and narrow down the mapped items
+ * @returns Mapped and narrowed array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ * mapAndFilter(
+ *   [{id: 1, name: 'Alice'}, {id: 2}, {id: 3, name: 'Charlie'}],
  *   item => item.name,
- *   value => value.startsWith('B'),
- * ); // => ['Bob']
+ *   (name): name is string => name != null,
+ * ); // => ['Alice', 'Charlie']
  * ```
  */
-export declare function mapAndFilter<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], map: Map, filter: (item: ArrayMapped<Item, Map>, index: number, array: Item[]) => boolean): Array<ArrayMapped<Item, Map>>;
+export declare function mapAndFilter<Item, Mapped, Narrowed extends Mapped>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: Mapped, index: number, array: Item[]) => item is Narrowed): Narrowed[];
 /**
  * Get a mapped and filtered array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `mapAndFilter`, `reverseSelect`, `filterAndMap.reverse`, and `select.reverse`_
  *
- * @param array Array to search in
- * @param map Callback or key to map the items
- * @param value Mapped value to match against
+ * @param array Array to select from
+ * @param mapper Callback to map the items
+ * @param filter Callback to filter the mapped items
  * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [1, 2, 3, 2, 1],
- *   value => value ** 2,
- *   4,
- * ); // => [4, 4]
+ * mapAndFilter(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.name,
+ *   name => name.length > 3,
+ * ); // => ['Alice', 'Charlie']
  * ```
  */
-export declare function mapAndFilter<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], map: Map, value: ArrayMapped<Item, Map>): Array<ArrayMapped<Item, Map>>;
+export declare function mapAndFilter<Item, Mapped>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: Mapped, index: number, array: Item[]) => boolean): Mapped[];
 export declare namespace filterAndMap {
+  export var flat: typeof filterAndFlatMap;
   export var reverse: typeof mapAndFilter;
 }
+export declare namespace mapAndFilter {
+  export var flat: typeof flatMapAndFilter;
+}
 //#endregion
 //#region src/models/array/array.sort.model.d.ts
 /**
@@ -2649,6 +2818,11 @@ declare function Sorter(this: any, sorters: SortHandler[]): void;
  * @param sorters Sorters to use to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Index for item
+ *
+ * @example
+ * ```typescript
+ * getSortedIndex([1, 3, 2], 2, [{key: 'value', direction: 'asc'}]); // => 1
+ * ```
  */
 export declare function getSortedIndex<Item>(array: Item[], item: Item, sorters: Array<ArraySorter<Item>>, descending?: boolean): number;
 /**
@@ -2663,6 +2837,11 @@ export declare function getSortedIndex<Item>(array: Item[], item: Item, sorters:
  * @param sorter Sorter to use to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Index for item
+ *
+ * @example
+ * ```typescript
+ * getSortedIndex([1, 3, 2], 2, {key: 'value', direction: 'asc'}); // => 1
+ * ```
  */
 export declare function getSortedIndex<Item>(array: Item[], item: Item, sorter: ArraySorter<Item>, descending?: boolean): number;
 /**
@@ -2676,6 +2855,11 @@ export declare function getSortedIndex<Item>(array: Item[], item: Item, sorter:
  * @param item Item to get the index for
  * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns Index for item
+ *
+ * @example
+ * ```typescript
+ * getSortedIndex([1, 3, 2], 2); // => 1
+ * ```
  */
 export declare function getSortedIndex<Item>(array: Item[], item: Item, descending?: boolean): number;
 /**
@@ -2716,6 +2900,12 @@ export declare function initializeSorter<Item>(descending?: boolean): Sorter<Ite
  * @param sorters Sorters to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns `true` if sorted, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isSorted([1, 2, 3], [{key: 'value', direction: 'asc'}]); // => true
+ * isSorted([3, 2, 1], [{key: 'value', direction: 'asc'}]); // => false
+ * ```
  */
 export declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): boolean;
 /**
@@ -2727,6 +2917,12 @@ export declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter
  * @param sorter Sorter to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns `true` if sorted, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isSorted([1, 2, 3], {key: 'value', direction: 'asc'}); // => true
+ * isSorted([3, 2, 1], {key: 'value', direction: 'asc'}); // => false
+ * ```
  */
 export declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): boolean;
 /**
@@ -2737,6 +2933,12 @@ export declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>,
  * @param array Array to check
  * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns `true` if sorted, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isSorted([1, 2, 3]); // => true
+ * isSorted([3, 2, 1]); // => false
+ * ```
  */
 export declare function isSorted<Item>(array: Item[], descending?: boolean): boolean;
 /**
@@ -2763,6 +2965,14 @@ export declare function sort<Item>(array: Item[], comparator: (first: Item, seco
  * @param sorters Sorters to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort(
+ *   [{id: 3}, {id: 1}, {id: 2}],
+ *   [{key: 'id', direction: 'asc'}],
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 export declare function sort<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): Item[];
 /**
@@ -2772,6 +2982,14 @@ export declare function sort<Item>(array: Item[], sorters: Array<ArraySorter<Ite
  * @param sorter Sorter to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort(
+ *   [{id: 3}, {id: 1}, {id: 2}],
+ *   {key: 'id', direction: 'asc'},
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 export declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): Item[];
 /**
@@ -2780,6 +2998,11 @@ export declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, des
  * @param array Array to sort
  * @param descending Sort in descending order? _(defaults to `false`)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort([3, 1, 2]); // => [1, 2, 3]
+ * ```
  */
 export declare function sort<Item>(array: Item[], descending?: boolean): Item[];
 export declare namespace sort {
@@ -4200,6 +4423,14 @@ export declare namespace pipe {
  *
  * @param value String to convert
  * @returns Camel-cased string
+ *
+ * @example
+ * ```typescript
+ * camelCase('this is camel case'); // => 'thisIsCamelCase'
+ * camelCase('ThisIsCamelCase');    // => 'thisIsCamelCase'
+ * camelCase('this-is-camel-case'); // => 'thisIsCamelCase'
+ * camelCase('this_is_camel_case'); // => 'thisIsCamelCase'
+ * ```
  */
 export declare function camelCase(value: string): string;
 /**
@@ -4207,6 +4438,14 @@ export declare function camelCase(value: string): string;
  *
  * @param value String to capitalize
  * @returns Capitalized string
+ *
+ * @example
+ * ```typescript
+ * capitalize('this is a test'); // => 'This is a test'
+ * capitalize('This Is A Test'); // => 'This is a test'
+ * capitalize('t');              // => 'T'
+ * capitalize('');               // => ''
+ * ```
  */
 export declare function capitalize(value: string): string;
 /**
@@ -4214,6 +4453,14 @@ export declare function capitalize(value: string): string;
  *
  * @param value String to convert
  * @returns Kebab-cased string
+ *
+ * @example
+ * ```typescript
+ * kebabCase('this is kebab case'); // => 'this-is-kebab-case'
+ * kebabCase('ThisIsKebabCase');    // => 'this-is-kebab-case'
+ * kebabCase('this-is-kebab-case'); // => 'this-is-kebab-case'
+ * kebabCase('this_is_kebab_case'); // => 'this-is-kebab-case'
+ * ```
  */
 export declare function kebabCase(value: string): string;
 /**
@@ -4221,6 +4468,13 @@ export declare function kebabCase(value: string): string;
  *
  * @param value String to convert
  * @returns Lower-cased string
+ *
+ * @example
+ * ```typescript
+ * lowerCase('THIS IS A TEST'); // => 'this is a test'
+ * lowerCase('this is a test'); // => 'this is a test'
+ * lowerCase('t');              // => 't'
+ * ```
  */
 export declare function lowerCase(value: string): string;
 /**
@@ -4228,6 +4482,14 @@ export declare function lowerCase(value: string): string;
  *
  * @param value String to convert
  * @returns Pascal-cased string
+ *
+ * @example
+ * ```typescript
+ * pascalCase('this is pascal case'); // => 'ThisIsPascalCase'
+ * pascalCase('ThisIsPascalCase');    // => 'ThisIsPascalCase'
+ * pascalCase('this-is-pascal-case'); // => 'ThisIsPascalCase'
+ * pascalCase('this_is_pascal_case'); // => 'ThisIsPascalCase'
+ * ```
  */
 export declare function pascalCase(value: string): string;
 /**
@@ -4235,6 +4497,14 @@ export declare function pascalCase(value: string): string;
  *
  * @param value String to convert
  * @returns Snake-cased string
+ *
+ * @example
+ * ```typescript
+ * snakeCase('this is snake case'); // => 'this_is_snake_case'
+ * snakeCase('ThisIsSnakeCase');    // => 'this_is_snake_case'
+ * snakeCase('this-is-snake-case'); // => 'this_is_snake_case'
+ * snakeCase('this_is_snake_case'); // => 'this_is_snake_case'
+ * ```
  */
 export declare function snakeCase(value: string): string;
 /**
@@ -4242,6 +4512,14 @@ export declare function snakeCase(value: string): string;
  *
  * @param value String to convert
  * @returns Title-cased string
+ *
+ * @example
+ * ```typescript
+ * titleCase('this is a test'); // => 'This Is A Test'
+ * titleCase('This Is A Test'); // => 'This Is A Test'
+ * titleCase('t');              // => 'T'
+ * titleCase('');               // => ''
+ * ```
  */
 export declare function titleCase(value: string): string;
 /**
@@ -4249,6 +4527,14 @@ export declare function titleCase(value: string): string;
  *
  * @param value String to convert
  * @returns Upper-cased string
+ *
+ * @example
+ * ```typescript
+ * upperCase('this is a test'); // => 'THIS IS A TEST'
+ * upperCase('This Is A Test'); // => 'THIS IS A TEST'
+ * upperCase('t');              // => 'T'
+ * upperCase('');               // => ''
+ * ```
  */
 export declare function upperCase(value: string): string;
 //#endregion
@@ -4271,7 +4557,13 @@ export declare function upperCase(value: string): string;
  * ```
  */
 export declare function getString(value: unknown): string;
+/**
+ * @internal
+ */
 export declare function ignoreKey(key: string): boolean;
+/**
+ * @internal
+ */
 export declare function interpolate(strings: TemplateStringsArray, values: unknown[]): string;
 /**
  * Join an array of values into a string _(while ignoring empty values)_
@@ -4281,9 +4573,23 @@ export declare function interpolate(strings: TemplateStringsArray, values: unkno
  * @param array Array of values
  * @param delimiter Delimiter to use between values
  * @returns Joined string
+ * @example
+ * ```typescript
+ * join(['a', 'b', 'c']);          // => 'abc'
+ * join(['a', 'b', 'c'], ', ');   // => 'a, b, c'
+ * join(['a', '', 'c']);           // => 'ac'
+ * join([null, 'b', undefined]);   // => 'b'
+ * join([]);                       // => ''
+ * ```
  */
 export declare function join(array: unknown[], delimiter?: string): string;
+/**
+ * @internal
+ */
 export declare function tryDecode(value: string): string;
+/**
+ * @internal
+ */
 export declare function tryEncode(value: boolean | number | string): unknown;
 /**
  * Split a string into words _(and other readable parts)_
@@ -5530,7 +5836,13 @@ export declare function isRejected(value: unknown): value is RejectedPromise;
  * @returns Cancelable _Promise_
  */
 export declare function cancelable<Value>(executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void): CancelablePromise<Value>;
+/**
+ * @internal
+ */
 export declare function handleResult(status: string, parameters: PromiseParameters): void;
+/**
+ * @internal
+ */
 export declare function settlePromise(settler: (value: any) => void, value: unknown, aborter?: Aborter): void;
 /**
  * Converts a _Promise_ to a promised result
@@ -5548,6 +5860,9 @@ export declare function toResult<Value>(callback: () => Promise<Value>): Promise
 export declare function toResult<Value>(promise: Promise<Value>): Promise<Result<Value>>;
 //#endregion
 //#region src/promise/timed.d.ts
+/**
+ * @internal
+ */
 export declare function getTimedPromise<Value>(promise: Promise<Value>, time: number, signal?: AbortSignal): Promise<Value>;
 /**
  * Create a _Promise_ that should be settled within a certain amount of time
@@ -6200,7 +6515,7 @@ export declare function getUuid(): string;
  *
  * @param value JSON string to parse
  * @param reviver Reviver function to transform the parsed values
- * @returns Parsed value or `undefined` if parsing fails
+ * @returns Parsed value, or `undefined` if parsing fails
  */
 export declare function parse(value: string, reviver?: (this: unknown, key: string, value: unknown) => unknown): unknown;
 /**
@@ -6208,6 +6523,13 @@ export declare function parse(value: string, reviver?: (this: unknown, key: stri
  *
  * @param value String to trim
  * @returns Trimmed string
+ * @example
+ * ```typescript
+ * trim('  this is a test  '); // => 'this is a test'
+ * trim('this is a test');     // => 'this is a test'
+ * trim('   ');                // => ''
+ * trim('');                   // => ''
+ * ```
  */
 export declare function trim(value: string): string;
 /**
@@ -6217,6 +6539,13 @@ export declare function trim(value: string): string;
  * @param length Maximum length of the string after truncation
  * @param suffix Suffix to append to the truncated string
  * @returns Truncated string
+ * @example
+ * ```typescript
+ * truncate('this is a test', 7);          // => 'this is'
+ * truncate('this is a test', 7, '...');   // => 'this ...'
+ * truncate('this is a test', 20);         // => 'this is a test'
+ * truncate('this is a test', 0);          // => ''
+ * ```
  */
 export declare function truncate(value: string, length: number, suffix?: string): string;
 //#endregion
@@ -6228,6 +6557,14 @@ export declare function truncate(value: string, length: number, suffix?: string)
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
  * @returns `true` if the string ends with the given substring, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * endsWith('this is a test', 'test');          // => true
+ * endsWith('this is a test', 'Test');          // => false
+ * endsWith('this is a test', 'Test', true);    // => true
+ * endsWith('this is a test', 'not');           // => false
+ * ```
  */
 export declare function endsWith(haystack: string, needle: string, ignoreCase?: boolean): boolean;
 /**
@@ -6237,6 +6574,14 @@ export declare function endsWith(haystack: string, needle: string, ignoreCase?:
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
  * @returns `true` if the string includes the given substring, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * includes('this is a test', 'is');          // => true
+ * includes('this is a test', 'Is');          // => false
+ * includes('this is a test', 'Is', true);    // => true
+ * includes('this is a test', 'not');         // => false
+ * ```
  */
 export declare function includes(haystack: string, needle: string, ignoreCase?: boolean): boolean;
 /**
@@ -6246,6 +6591,14 @@ export declare function includes(haystack: string, needle: string, ignoreCase?:
  * @param needle String to look for
  * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
  * @returns `true` if the string starts with the given substring, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * startsWith('this is a test', 'this');          // => true
+ * startsWith('this is a test', 'This');          // => false
+ * startsWith('this is a test', 'This', true);    // => true
+ * startsWith('this is a test', 'not');           // => false
+ * ```
  */
 export declare function startsWith(haystack: string, needle: string, ignoreCase?: boolean): boolean;
 //#endregion
@@ -6391,6 +6744,10 @@ export declare function template(strings: TemplateStringsArray, ...values: unkno
  * @param variables Variables to use
  * @param options Templating options
  * @returns Templated string
+ * @example
+ * ```typescript
+ * template('Hello, {{name}}!', {name: 'World'}); // => 'Hello, World!'
+ * ```
  */
 export declare function template(value: string, variables?: PlainObject, options?: Partial<TemplateOptions>): string;
 export declare namespace template {
@@ -6769,7 +7126,7 @@ type BaseOptions = {
   /**
    * Key _(or key epxressions)_ for values that should be replaced
    *
-   * ```ts
+   * ```typescript
    * merge([{items: [1, 2, 3]}, {items: [99]}]); // => {items: [99]}
    * ```
    */
@@ -6777,7 +7134,7 @@ type BaseOptions = {
   /**
    * Skip nullable values when merging objects?
    *
-   * ```ts
+   * ```typescript
    * merge({a: 1, b: 2}, {b: null, c: 3}, {d: null}); // => {a: 1, b: 2, c: 3}
    * ```
    */
@@ -6785,7 +7142,7 @@ type BaseOptions = {
   /**
    * Skip nullable values when merging arrays?
    *
-   * ```ts
+   * ```typescript
    * merge([1, 2, 3], [null, null, 99]); // => [1, 2, 99]
    * ```
    */
@@ -7676,6 +8033,14 @@ export declare function isRgbColor(value: unknown): value is RGBColor;
  * @param value Value to normalize
  * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
  * @returns Normalized hex color
+ *
+ * @example
+ * ```typescript
+ * getNormalizedHex('#abc'); // => '#aabbcc'
+ * getNormalizedHex('#abc', true); // => '#aabbccff'
+ * getNormalizedHex(123); // => '#000000'
+ * getNormalizedHex(123, true); // => '#000000ff'
+ * ```
  */
 export declare function getNormalizedHex(value: unknown, alpha?: boolean): string;
 /**
@@ -8220,7 +8585,19 @@ type TimeLogger = {
 //#endregion
 //#region src/logger.d.ts
 declare function TimeLogger(this: any, label: string): void;
+/**
+ * Is the value a _Logger_?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a _Logger_, otherwise `false`
+ */
 declare function isLogger(value: unknown): value is Lumberjack;
+/**
+ * Is the value a _TimeLogger_?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a _TimeLogger_, otherwise `false`
+ */
 declare function isTimeLogger(value: unknown): value is TimeLogger;
 /**
  * A logger that can be used to log messages to the console
@@ -8233,6 +8610,11 @@ declare const Logger: Lumberjack;
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param callback Callback to get an item's value
+ * @param first Return only the first item with the maximum value
+ * @returns Item with the maximum value, or `undefined` if no maximum can be found
+ *
  * @example
  * ```typescript
  * max(
@@ -8242,16 +8624,16 @@ declare const Logger: Lumberjack;
  *
  * max([], item => item.value); // => []
  * ```
- *
- * @param items List of items
- * @param callback Callback to get an item's value
- * @param first Return only the first item with the maximum value
- * @returns Item with the maximum value, or `undefined` if no maximum can be found
  */
 export declare function max<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number, first: true): Item | undefined;
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param key Key to use for value
+ * @param first Return only the first item with the maximum value
+ * @returns Item with the maximum value, or `undefined` if no maximum can be found
+ *
  * @example
  * ```typescript
  * max(
@@ -8261,16 +8643,15 @@ export declare function max<Item>(items: Item[], callback: (item: Item, index: n
  *
  * max([], 'value'); // => []
  * ```
- *
- * @param items List of items
- * @param key Key to use for value
- * @param first Return only the first item with the maximum value
- * @returns Item with the maximum value, or `undefined` if no maximum can be found
  */
 export declare function max<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>, first: true): Item | undefined;
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param callback Callback to get an item's value
+ * @returns Items with the maximum value
+ *
  * @example
  * ```typescript
  * max(
@@ -8280,15 +8661,15 @@ export declare function max<Item extends PlainObject>(items: Item[], key: keyof
  *
  * max([], item => item.value); // => []
  * ```
- *
- * @param items List of items
- * @param callback Callback to get an item's value
- * @returns Items with the maximum value
  */
 export declare function max<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): Item[];
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param key Key to use for value
+ * @returns Items with the maximum value
+ *
  * @example
  * ```typescript
  * max(
@@ -8298,23 +8679,19 @@ export declare function max<Item>(items: Item[], callback: (item: Item, index: n
  *
  * max([], 'value'); // => []
  * ```
- *
- * @param items List of items
- * @param key Key to use for value
- * @returns Items with the maximum value
  */
 export declare function max<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): Item[];
 /**
  * Get the maximum value from a list of numbers
  *
+ * @param values List of numbers
+ * @returns Maximum value, or `Number.NaN` if no maximum can be found
+ *
  * @example
  * ```typescript
  * max([10, 20]); // => 20
  * max([]);       // => Number.NaN
  * ```
- *
- * @param values List of numbers
- * @returns Maximum value, or `Number.NaN` if no maximum can be found
  */
 export declare function max(values: number[]): number;
 /**
@@ -8324,6 +8701,17 @@ export declare function max(values: number[]): number;
  * @param callback Callback to get an item's value
  * @param first Return only the first item with the minimum value
  * @returns First item with the minimum value, or `undefined` if no minimum can be found
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   item => item.value,
+ *   true,
+ * ); // => {id: 2, value: 5}
+ *
+ * min([], item => item.value, true); // => undefined
+ * ```
  */
 export declare function min<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number, first: true): Item | undefined;
 /**
@@ -8333,6 +8721,17 @@ export declare function min<Item>(items: Item[], callback: (item: Item, index: n
  * @param key Key to use for value
  * @param first Return only the first item with the minimum value
  * @returns First item with the minimum value, or `undefined` if no minimum can be found
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   'value',
+ *   true,
+ * ); // => {id: 2, value: 5}
+ *
+ * min([], 'value', true); // => undefined
+ * ```
  */
 export declare function min<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>, first: true): Item | undefined;
 /**
@@ -8341,6 +8740,16 @@ export declare function min<Item extends PlainObject>(items: Item[], key: keyof
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Items with the minimum value
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   item => item.value,
+ * ); // => [{id: 2, value: 5}]
+ *
+ * min([], item => item.value); // => []
+ * ```
  */
 export declare function min<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): Item[];
 /**
@@ -8349,6 +8758,16 @@ export declare function min<Item>(items: Item[], callback: (item: Item, index: n
  * @param items List of items
  * @param key Key to use for value
  * @returns Items with the minimum value
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   'value',
+ * ); // => [{id: 2, value: 5}]
+ *
+ * min([], 'value'); // => []
+ * ```
  */
 export declare function min<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): Item[];
 /**
@@ -8356,6 +8775,12 @@ export declare function min<Item extends PlainObject>(items: Item[], key: keyof
  *
  * @param values List of numbers
  * @returns Minimum value, or `Number.NaN` if no minimum can be found
+ *
+ * @example
+ * ```typescript
+ * min([10, 20]); // => 10
+ * min([]);       // => Number.NaN
+ * ```
  */
 export declare function min(values: number[]): number;
 //#endregion
@@ -8366,6 +8791,13 @@ export declare function min(values: number[]): number;
  * @param value Number to round down
  * @param decimals Number of decimal places to round to _(defaults to `0`)_
  * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+ *
+ * @example
+ * ```typescript
+ * floor(10.567, 2); // => 10.56
+ * floor(10.567);    // => 10
+ * floor('abc');       // => Number.NaN
+ * ```
  */
 export declare function floor(value: number, decimals?: number): number;
 /**
@@ -8374,6 +8806,13 @@ export declare function floor(value: number, decimals?: number): number;
  * @param value Number to round
  * @param decimals Number of decimal places to round to _(defaults to `0`)_
  * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+ *
+ * @example
+ * ```typescript
+ * round(10.567, 2); // => 10.57
+ * round(10.567);    // => 11
+ * round('abc');       // => Number.NaN
+ * ```
  */
 export declare function round(value: number, decimals?: number): number;
 //#endregion
@@ -8384,6 +8823,16 @@ export declare function round(value: number, decimals?: number): number;
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([
+ *   {value: 1},
+ *   {value: 2},
+ *   {value: 3},
+ * ], item => item.value); // => 2
+ * average([{value: 1}], item => item.nope); // => Number.NaN
+ * ```
  */
 export declare function average<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -8392,6 +8841,12 @@ export declare function average<Item>(items: Item[], callback: (item: Item, inde
  * @param items List of items
  * @param key Key to use for value
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 2
+ * average([{value: 1}], 'nope'); // => Number.NaN
+ * ```
  */
 export declare function average<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -8399,6 +8854,12 @@ export declare function average<Item extends PlainObject>(items: Item[], key: ke
  *
  * @param numbers List of numbers
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([1, 2, 3, 4, 5]); // => 3
+ * average([]); // => Number.NaN
+ * ```
  */
 export declare function average(numbers: number[]): number;
 /**
@@ -8407,6 +8868,13 @@ export declare function average(numbers: number[]): number;
  * @param value Number to round up
  * @param decimals Number of decimal places to round to _(defaults to `0`)_
  * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+ *
+ * @example
+ * ```typescript
+ * ceil(1.234, 2); // => 1.24
+ * ceil(1.234);    // => 2
+ * ceil('abc');    // => Number.NaN
+ * ```
  */
 export declare function ceil(value: number, decimals?: number): number;
 /**
@@ -8416,6 +8884,14 @@ export declare function ceil(value: number, decimals?: number): number;
  * @param callback Callback to get an item's value
  * @param value Value to match and count
  * @returns Number of items that match the condition, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([1, 2, 3, 2], (item) => item, 2); // => 2
+ * count([{value: 1}, {value: 2}, {value: 3}], 'value', 2); // => 1
+ * count([1, 2, 3], (item) => item, 4); // => 0
+ * count([], (item) => item, 1); // => Number.NaN
+ * ```
  */
 export declare function count<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => unknown, value: unknown): number;
 /**
@@ -8425,6 +8901,12 @@ export declare function count<Item>(array: Item[], callback: (item: Item, index:
  * @param key Key to use for value
  * @param value Value to match and count
  * @returns Number of items with the specified key value, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([{value: 1}, {value: 2}, {value: 3}], 'value', 2); // => 1
+ * count([{value: 1}], 'nope', 1); // => Number.NaN
+ * ```
  */
 export declare function count<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): number;
 /**
@@ -8432,6 +8914,12 @@ export declare function count<Item extends PlainObject, ItemKey extends keyof It
  *
  * @param values Array to count for
  * @returns Number of items, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([1, 2, 3]); // => 3
+ * count([]);        // => Number.NaN
+ * ```
  */
 export declare function count(values: unknown[]): number;
 /**
@@ -8440,6 +8928,13 @@ export declare function count(values: unknown[]): number;
  * @param array List of items
  * @param callback Callback to get an item's value
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([1, 2, 3, 4, 5]); // => 3
+ * median([1, 2, 3, 4]);    // => 2.5
+ * median([]);              // => Number.NaN
+ * ```
  */
 export declare function median<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -8448,6 +8943,13 @@ export declare function median<Item>(array: Item[], callback: (item: Item, index
  * @param array List of items
  * @param key Key to use for value
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 2
+ * median([{value: 1}, {value: 2}, {value: 3}, {value: 4}], 'value'); // => 2.5
+ * median([], 'value'); // => Number.NaN
+ * ```
  */
 export declare function median<Item extends PlainObject>(array: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -8455,6 +8957,13 @@ export declare function median<Item extends PlainObject>(array: Item[], key: key
  *
  * @param array List of numbers
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([1, 2, 3, 4, 5]); // => 3
+ * median([1, 2, 3, 4]);    // => 2.5
+ * median([]);              // => Number.NaN
+ * ```
  */
 export declare function median(array: number[]): number;
 /**
@@ -8463,6 +8972,13 @@ export declare function median(array: number[]): number;
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Sum of the values, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 6
+ * sum([{value: 1}, {value: 2}, {value: 3}], item => item.value); // => 6
+ * sum([]); // => Number.NaN
+ * ```
  */
 export declare function sum<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -8471,6 +8987,13 @@ export declare function sum<Item>(items: Item[], callback: (item: Item, index: n
  * @param items List of items
  * @param key Key to use for value
  * @returns Sum of the values, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 6
+ * sum([{value: 1}, {value: 2}, {value: 3}], item => item.value); // => 6
+ * sum([]); // => Number.NaN
+ * ```
  */
 export declare function sum<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -8478,6 +9001,12 @@ export declare function sum<Item extends PlainObject>(items: Item[], key: keyof
  *
  * @param values List of numbers
  * @returns Sum of the numbers, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([1, 2, 3]); // => 6
+ * sum([]);        // => Number.NaN
+ * ```
  */
 export declare function sum(values: number[]): number;
 //#endregion
@@ -8489,6 +9018,13 @@ export declare function sum(values: number[]): number;
  * @param minimum Minimum value
  * @param maximum Maximum value _(inclusive)_
  * @returns `true` if the value is between the minimum and maximum, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * between(5, 1, 10); // => true
+ * between(0, 1, 10); // => false
+ * between(10, 10, 10); // => true
+ * ```
  */
 export declare function between(value: number, minimum: number, maximum: number): boolean;
 /**
@@ -8514,6 +9050,17 @@ export declare function clamp(value: number, minimum: number, maximum: number, l
  *
  * @param value Original value
  * @returns Original value as a number, or `Number.NaN` if the value is unable to be parsed
+ *
+ * @example
+ * ```typescript
+ * getNumber(null)       // => Number.NaN
+ * getNumber('foo')      // => Number.NaN
+ * getNumber('123')        // => 123
+ * getNumber(true)       // => 1
+ * getNumber([1, 2, 3])  // => Number.NaN
+ * getNumber({a: 1})     // => Number.NaN
+ * getNumber(() => 123)  // => 123
+ * ```
  */
 export declare function getNumber(value: unknown): number;
 //#endregion
@@ -8744,7 +9291,6 @@ export declare function isKeyedQueue(value: unknown): value is KeyedQueue<Generi
  * @returns `true` if the value is a queue, otherwise `false`
  */
 export declare function isQueue(value: unknown): value is Queue<GenericCallback | GenericAsyncCallback>;
-export declare function isQueueInstance<Instance>(name: string, value: unknown): value is Instance;
 /**
  * Create a keyed queue for an asynchronous callback function, where each key has its own queue
  *