@oscarpalmer/atoms 0.185.0 → 0.186.1

package/dist/array/get.d.mts

@@ -3,32 +3,52 @@ import { NumericalKeys, PlainObject } from "../models.mjs";
 //#region src/array/get.d.ts
 /**
  * Get an array from an object, where only values with numerical keys will be included
+ *
  * @param value Object to convert to an array
  * @returns Array holding the values of the object's numerical keys
+ *
+ * @example
+ * ```typescript
+ * getArray({0: 'a', 1: 'b', 2: 'c', d: 'd'}, true); // => ['a', 'b', 'c']
+ * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}, true); // => []
+ * ```
  */
 declare function getArray<Value extends PlainObject>(value: Value, indiced: true): Value[NumericalKeys<Value>][];
 /**
  * Get an array from an object
+ *
  * @param value Object to convert to an array
  * @returns Array holding the values of the object
+ *
+ * @example
+ * ```typescript
+ * getArray({0: 'a', 1: 'b', 2: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
+ * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
+ * ```
  */
 declare function getArray<Value extends PlainObject>(value: Value): Value[keyof Value][];
 /**
- * Get an array
+ * Get an array from a value
+ *
  * @param value Original array
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * getArray(123); // => [123]
+ * ```
  */
 declare function getArray<Item>(value: Item[]): Item[];
-/**
- * Get an array from a value
- * @param value Value to convert to an array
- * @returns Array holding the value
- */
-declare function getArray<Item>(value: Item): Item[];
 /**
  * Get an array from an unknown value
+ *
  * @param value Value to convert to an array
  * @returns Array of value
+ *
+ * @example
+ * ```typescript
+ * getArray(123); // => [123]
+ * ```
  */
 declare function getArray(value: unknown): unknown[];
 //#endregion

package/dist/array/group-by.d.mts

@@ -5,64 +5,130 @@ import { Key, KeyedValue, PlainObject, Simplify } from "../models.mjs";
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   item => item,
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 declare function groupBy<Item, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: KeyCallback, value: ValueCallback): Simplify<Record<ReturnType<KeyCallback>, ReturnType<ValueCallback>>>;
 /**
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   'id'
+ * ); // => {10: 3, 20: 2}
+ * ```
  */
 declare function groupBy<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Record<ReturnType<KeyCallback>, Item[ItemValue]>;
 /**
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   item => item,
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Simplify<Record<KeyedValue<Item, ItemKey>, ReturnType<ValueCallback>>>;
 /**
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   'id'
+ * ); // => {10: 3, 20: 2}
+ * ```
  */
 declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Simplify<Record<KeyedValue<Item, ItemKey>, Item[ItemValue]>>;
 /**
  * Create a record from an array of items using a specific key
  *
  * If multiple items have the same key, the latest item will be used
+ *
  * @param array Array to group
  * @param callback Callback to get an item's grouping key
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 declare function groupBy<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Record<ReturnType<Callback>, Item>;
 /**
  * Create a record from an array of items using a specific key
  *
  * If multiple items have the same key, the latest item will be used
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Simplify<Record<KeyedValue<Item, ItemKey>, Item>>;
 /**
  * Create a record from an array of items _(using indices as keys)_
+ *
  * @param array Array to group
  * @returns Record of indiced items
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ * ); // => {0: {id: 1, value: 10}, 1: {id: 2, value: 20}, 2: {id: 3, value: 10}}
+ * ```
  */
 declare function groupBy<Item>(array: Item[]): Record<number, Item>;
 declare namespace groupBy {
@@ -72,58 +138,134 @@ declare namespace groupBy {
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   item => item,
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 declare function groupArraysBy<Item, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: KeyCallback, value: ValueCallback): Record<ReturnType<KeyCallback>, ReturnType<ValueCallback>[]>;
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   'id',
+ * ); // => {
+ *    //   10: [1, 3],
+ *    //   20: [2],
+ *    // }
+ * ```
  */
 declare function groupArraysBy<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Record<ReturnType<KeyCallback>, Item[ItemValue][]>;
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   item => item,
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Simplify<Record<KeyedValue<Item, ItemKey>, ReturnType<ValueCallback>[]>>;
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   'id',
+ * ); // => {
+ *    //   10: [1, 3],
+ *    //   20: [2],
+ *    // }
+ * ```
  */
 declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Simplify<Record<KeyedValue<Item, ItemKey>, Item[ItemValue][]>>;
 /**
  * Create a record from an array of items using a specific key, grouping items into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param callback Callback to get an item's grouping key
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 declare function groupArraysBy<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Record<ReturnType<Callback>, Item[]>;
 /**
  * Create a record from an array of items using a specific key, grouping items into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Simplify<Record<KeyedValue<Item, ItemKey>, Item[]>>;
 //#endregion

package/dist/array/insert.d.mts

@@ -1,17 +1,33 @@
 //#region src/array/insert.d.ts
 /**
  * Insert items into an array at a specified index
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param index Index to insert at
  * @param items Inserted items
  * @returns Updated array
+ *
+ * @example
+ * ```typescript
+ * insert([1, 2, 3], 1, [4, 5]); // => [1, 4, 5, 2, 3]
+ * ```
  */
 declare function insert<Item>(array: Item[], index: number, items: Item[]): Item[];
 /**
  * Insert items into an array _(at the end)_
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param items Inserted items
  * @returns Updated array
+ *
+ * @example
+ * ```typescript
+ * insert([1, 2, 3], [4, 5]); // => [1, 2, 3, 4, 5]
+ * ```
  */
 declare function insert<Item>(array: Item[], items: Item[]): Item[];
 //#endregion

package/dist/array/intersection.d.mts

@@ -1,25 +1,54 @@
 //#region src/array/intersection.d.ts
 /**
  * Get the common values between two arrays
+ *
  * @param first First array
  * @param second Second array
  * @param callback Callback to get an item's value for comparison
  * @returns Common values from both arrays
+ *
+ * @example
+ * ```typescript
+ * intersection(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}, {id: 4}],
+ *   item => item.id,
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
 declare function intersection<First, Second>(first: First[], second: Second[], callback: (item: First | Second) => unknown): First[];
 /**
  * Get the common values between two arrays
+ *
  * @param first First array
  * @param second Second array
  * @param key Key to get an item's value for comparison
  * @returns Common values from both arrays
+ *
+ * @example
+ * ```typescript
+ * intersection(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}, {id: 4}],
+ *   'id',
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
 declare function intersection<First extends Record<string, unknown>, Second extends Record<string, unknown>, SharedKey extends keyof First & keyof Second>(first: First[], second: Second[], key: SharedKey): First[];
 /**
  * Get the common values between two arrays
+ *
  * @param first First array
  * @param second Second array
  * @returns Common values from both arrays
+ *
+ * @example
+ * ```typescript
+ * intersection(
+ *   [1, 2, 3],
+ *   [2, 3, 4],
+ * ); // => [2, 3]
+ * ```
  */
 declare function intersection<First, Second>(first: First[], second: Second[]): First[];
 //#endregion

package/dist/array/last.d.mts

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