@oscarpalmer/atoms 0.185.0 → 0.186.0

package/dist/array/difference.d.mts

@@ -3,25 +3,54 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/difference.d.ts
 /**
  * Get the items from the first array that are not in the second array
+ *
  * @param first First array
  * @param second Second array
  * @param callback Callback to get an item's value for comparison
  * @returns Unique values from the first array
+ *
+ * @example
+ * ```typescript
+ * difference(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 declare function difference<First, Second>(first: First[], second: Second[], callback: (item: First | Second) => unknown): First[];
 /**
  * Get the items from the first array that are not in the second array
+ *
  * @param first First array
  * @param second Second array
  * @param key Key to get an item's value for comparison
  * @returns Unique values from the first array
+ *
+ * @example
+ * ```typescript
+ * difference(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 declare function difference<First extends PlainObject, Second extends PlainObject, SharedKey extends keyof First & keyof Second>(first: First[], second: Second[], key: SharedKey): First[];
 /**
  * Get the items from the first array that are not in the second array
+ *
  * @param first First array
  * @param second Second array
  * @returns Unique values from the first array
+ *
+ * @example
+ * ```typescript
+ * difference(
+ *   [1, 2, 3],
+ *   [2, 4],
+ * ); // => [1, 3]
+ * ```
  */
 declare function difference<First, Second>(first: First[], second: Second[]): First[];
 //#endregion

package/dist/array/exists.d.mts

@@ -3,32 +3,67 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/exists.d.ts
 /**
  * Does an item with a specific value exist in the array?
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns `true` if the item exists in the array, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => true
+ * ```
  */
 declare function exists<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): boolean;
 /**
  * Does an item with a specific value exist in the array?
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns `true` if the item exists in the array, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => true
+ * ```
  */
 declare function exists<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): boolean;
 /**
  * Does an item in the array match the filter?
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns `true` if a matching item exists, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => true
+ * ```
  */
 declare function exists<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): boolean;
 /**
  * Does the item exist in the array?
+ *
  * @param array Array to search in
  * @param item Item to search for
  * @returns `true` if the item exists in the array, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * exists([1, 2, 3], 2); // => true
+ * ```
  */
 declare function exists<Item>(array: Item[], item: Item): boolean;
 //#endregion

package/dist/array/filter.d.mts

@@ -2,71 +2,141 @@ import { PlainObject } from "../models.mjs";
 
 //#region src/array/filter.d.ts
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items that do not match the value
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 declare function exclude<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
 /**
- * Get a filtered array of items that do not match the filter
+ * Get a filtered array of items that do not match the value
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 declare function exclude<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): unknown[];
 /**
  * Get a filtered array of items that do not match the filter
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Filtered array of items that do not match the filter
+ *
+ * @example
+ * ```typescript
+ * exclude(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [{id: 1}, {id: 3}]
+ * ```
  */
 declare function exclude<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): unknown[];
 /**
  * Get a filtered array of items that do not match the given item
  *
  * Available as `exclude` and `filter.remove`
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Filtered array of items that do not match the given item
+ *
+ * @example
+ * ```typescript
+ * exclude([1, 2, 3], 2); // => [1, 3]
+ * ```
  */
 declare function exclude<Item>(array: Item[], item: Item): unknown[];
 /**
  * Get a filtered array of items
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [{id: 2}]
+ * ```
  */
 declare function filter<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
 /**
  * Get a filtered 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 Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [{id: 2}]
+ * ```
  */
 declare function filter<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
 /**
  * Get a filtered array of items matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [{id: 2}]
+ * ```
  */
 declare function filter<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item[];
 /**
  * Get a filtered array of items matching the given item
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Filtered array of items
+ *
+ * @example
+ * ```typescript
+ * filter([1, 2, 3], 2); // => [2]
+ * ```
  */
 declare function filter<Item>(array: Item[], item: Item): Item[];
 declare namespace filter {

package/dist/array/find.d.mts

@@ -3,32 +3,67 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/find.d.ts
 /**
  * Get the first item matching the given value
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function find<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
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function find<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
 /**
  * Get the first item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns First item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function find<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item | undefined;
 /**
  * Get the first item matching the given value
+ *
  * @param array Array to search in
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find([1, 2, 3, 2, 1], 1); // => 1
+ * ```
  */
 declare function find<Item>(array: Item[], value: Item): Item | undefined;
 declare namespace find {
@@ -38,38 +73,73 @@ declare namespace find {
  * Get the last item matching the given value
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 declare function findLast<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item | undefined;
 /**
  * Get the last item matching the given value by key
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 declare function findLast<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
 /**
  * Get the last item matching the filter
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Last item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 declare function findLast<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item | undefined;
 /**
  * Get the last item matching the given value
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast([1, 2, 3, 2, 1], 1); // => 1
+ * ```
  */
 declare function findLast<Item>(array: Item[], value: Item): Item | undefined;
 //#endregion

package/dist/array/first.d.mts

@@ -3,31 +3,68 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/first.d.ts
 /**
  * Get the first item matching the given value
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function first<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
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function first<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
 /**
  * Get the first item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns First item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function first<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item | undefined;
 /**
  * Get the first item from an array
+ *
  * @param array Array to get from
- * @return First item from the array, or `undefined` if the array is empty
+ * @returns First item from the array, or `undefined` if the array is empty
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 declare function first<Item>(array: Item[]): Item | undefined;
 declare namespace first {
@@ -38,41 +75,79 @@ declare namespace first {
  * Get the first item matching the given value, or a default value if no match is found
  *
  * Available as `firstOrDefault` and `first.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   item => item.value,
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 declare function firstOrDefault<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], defaultValue: Item, callback: Callback, value: ReturnType<Callback>): Item;
 /**
  * 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`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns First item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   'value',
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 declare function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], defaultValue: Item, key: ItemKey, value: Item[ItemKey]): Item;
 /**
  * Get the first item matching the filter, or a default value if no match is found
  *
  * Available as `firstOrDefault` and `first.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param filter Filter callback to match items
  * @returns First item that matches the filter, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   item => item.value === 30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 declare function firstOrDefault<Item>(array: Item[], defaultValue: Item, filter: (item: Item, index: number, array: Item[]) => boolean): Item;
 /**
  * Get the first item from an array, or a default value if the array is empty
  *
  * Available as `firstOrDefault` and `first.default`
+ *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
- * @return First item from the array, or the default value if the array is empty
+ * @returns First item from the array, or the default value if the array is empty
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault([], {id: -1, value: 30}); // => {id: -1, value: 30}
+ * ```
  */
 declare function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
 //#endregion

package/dist/array/flatten.d.mts

@@ -3,8 +3,14 @@ import { NestedArray } from "../models.mjs";
 //#region src/array/flatten.d.ts
 /**
  * Flatten an array _(using native `flat` and maximum depth)_
+ *
  * @param array Array to flatten
  * @returns Flattened array
+ *
+ * @example
+ * ```typescript
+ * flatten([1, [2, [3, 4], 5], 6]); // => [1, 2, 3, 4, 5, 6]
+ * ```
  */
 declare function flatten<Item>(array: Item[]): NestedArray<Item>[];
 //#endregion

package/dist/array/flatten.mjs

@@ -1,8 +1,14 @@
 //#region src/array/flatten.ts
 /**
 * Flatten an array _(using native `flat` and maximum depth)_
+*
 * @param array Array to flatten
 * @returns Flattened array
+*
+* @example
+* ```typescript
+* flatten([1, [2, [3, 4], 5], 6]); // => [1, 2, 3, 4, 5, 6]
+* ```
 */
 function flatten(array) {
 	return Array.isArray(array) ? array.flat(Number.POSITIVE_INFINITY) : [];

package/dist/array/from.d.mts

@@ -1,43 +1,79 @@
 //#region src/array/from.d.ts
 /**
  * Get an array with a specified length, filled with indices
+ *
  * @param length Length of the array
  * @returns Array of indices
+ *
+ * @example
+ * ```typescript
+ * range(5); // => [0, 1, 2, 3, 4]
+ * ```
  */
 declare function range(length: number): number[];
 /**
  * Get an array of numbers in a specified range
+ *
  * @param start Starting number _(inclusive)_
  * @param end Ending number _(exclusive)_
  * @returns Array of numbers in range
+ *
+ * @example
+ * ```typescript
+ * range(2, 5); // => [2, 3, 4]
+ * ```
  */
 declare function range(start: number, end: number): number[];
 /**
  * Get an array of numbers in a specified range with a specified step
+ *
  * @param start Starting number _(inclusive)_
  * @param end Ending number _(exclusive)_
  * @param step Step between numbers
  * @returns Array of numbers in range
+ *
+ * @example
+ * ```typescript
+ * range(0, 10, 2); // => [0, 2, 4, 6, 8]
+ * ```
  */
 declare function range(start: number, end: number, step: number): number[];
 /**
  * Get an array with a specified length, filled with indices
+ *
  * @param length Length of the array
  * @returns Array of indices
+ *
+ * @example
+ * ```typescript
+ * times(5); // => [0, 1, 2, 3, 4]
+ * ```
  */
 declare function times(length: number): number[];
 /**
  * Get an array with a specified length, filled by values from a callback
+ *
  * @param length Length of the array
  * @param callback Callback function to generate values
  * @returns Array of values generated by the callback
+ *
+ * @example
+ * ```typescript
+ * times(5, index => index * 2); // => [0, 2, 4, 6, 8]
+ * ```
  */
 declare function times<Callback extends (index: number) => unknown>(length: number, callback: Callback): ReturnType<Callback>[];
 /**
  * Get an array with a specified length, filled with a specified value
+ *
  * @param length Length of the array
  * @param value Value to fill the array with
  * @returns Array filled with the specified value
+ *
+ * @example
+ * ```typescript
+ * times(5, 'a'); // => ['a', 'a', 'a', 'a', 'a']
+ * ```
  */
 declare function times<Value>(length: number, value: Value): Value[];
 //#endregion