@oscarpalmer/atoms 0.217.0 → 0.219.0

package/dist/array/filter.d.mts

@@ -19,7 +19,7 @@ import { PlainObject } from "../models/index.mjs";
  * ); // => [{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
  *
@@ -39,7 +39,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
  *
@@ -57,7 +75,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
  *
@@ -72,7 +90,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
  *
@@ -109,6 +127,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
  *

package/dist/array/find.d.mts

@@ -36,6 +36,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
  *
@@ -105,6 +121,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
  *

package/dist/array/first.d.mts

@@ -36,6 +36,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
  *
@@ -69,7 +85,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
@@ -91,7 +107,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
@@ -110,10 +126,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
@@ -133,7 +169,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

package/dist/array/insert.mjs

@@ -2,7 +2,7 @@ import { ARRAY_INSERT_TYPE_INSERT } from "../models/array/array.misc.model.mjs";
 import { insertValues } from "../internal/array/insert.mjs";
 //#region src/array/insert.ts
 function insert(array, indexOrItems, items) {
-	return insertValues(ARRAY_INSERT_TYPE_INSERT, array, items == null ? indexOrItems : items, typeof indexOrItems === "number" ? indexOrItems : array?.length, 0);
+	return insertValues(ARRAY_INSERT_TYPE_INSERT, array, items ?? indexOrItems, typeof indexOrItems === "number" ? indexOrItems : array?.length, 0);
 }
 //#endregion
 export { insert };

package/dist/array/last.d.mts

@@ -1,7 +1,7 @@
 import { PlainObject } from "../models/index.mjs";
 //#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
@@ -19,7 +19,7 @@ import { PlainObject } from "../models/index.mjs";
  */
 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
@@ -36,6 +36,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
  *
@@ -65,9 +81,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
@@ -87,9 +103,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
@@ -109,9 +125,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
@@ -129,9 +165,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

package/dist/array/partition.d.mts

@@ -6,7 +6,7 @@ import { PlainObject } from "../models/index.mjs";
  * @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
@@ -17,14 +17,14 @@ import { PlainObject } from "../models/index.mjs";
  * ); // => [[{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
@@ -35,13 +35,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
@@ -51,18 +67,18 @@ 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

package/dist/array/reverse.d.mts

@@ -4,6 +4,12 @@
  *
  * @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

package/dist/array/reverse.mjs

@@ -5,6 +5,12 @@ import { floor } from "../internal/math/misc.mjs";
 *
 * @param array Array to reverse
 * @returns Reversed array
+*
+* @example
+* ```typescript
+* reverse([1, 2, 3]);       // => [3, 2, 1]
+* reverse(['a', 'b', 'c']); // => ['c', 'b', 'a']
+* ```
 */
 function reverse(array) {
 	if (!Array.isArray(array)) return [];