@oscarpalmer/atoms 0.185.0 → 0.186.0

package/dist/array/to-set.d.mts

@@ -3,22 +3,46 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/to-set.d.ts
 /**
  * Create a Set from an array of items using a callback
+ *
  * @param array Array to convert
  * @param callback Callback to get an item's value
  * @returns Set of values
+ *
+ * @example
+ * ```typescript
+ * toSet(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ * ); // => Set { 1, 2, 3 }
+ * ```
  */
 declare function toSet<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback): Set<ReturnType<Callback>>;
 /**
  * Create a Set from an array of items using a key
+ *
  * @param array Array to convert
  * @param key Key to use for value
  * @returns Set of values
+ *
+ * @example
+ * ```typescript
+ * toSet(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ * ); // => Set { 1, 2, 3 }
+ * ```
  */
 declare function toSet<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Set<Item[ItemKey]>;
 /**
  * Create a Set from an array of items
+ *
  * @param array Array to convert
  * @returns Set of items
+ *
+ * @example
+ * ```typescript
+ * toSet([1, 2, 3]); // => Set { 1, 2, 3 }
+ * ```
  */
 declare function toSet<Item>(array: Item[]): Set<Item>;
 //#endregion

package/dist/array/toggle.d.mts

@@ -2,26 +2,61 @@ import { PlainObject } from "../models.mjs";
 
 //#region src/array/toggle.d.ts
 /**
- * Toggle an item in an array: if the item exists, it will be removed; if it doesn't, it will be added
+ * Toggle an item in an array
+ *
+ * If the item exists, it will be removed; if it doesn't, it will be added
+ *
  * @param destination Array to toggle within
  * @param toggled Toggled items
  * @param callback Callback to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * toggle(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 3}, {id: 4}]
+ * ```
  */
 declare function toggle<Item>(destination: Item[], toggled: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
- * Toggle an item in an array: if the item exists, it will be removed; if it doesn't, it will be added
+ * Toggle an item in an array
+ *
+ * If the item exists, it will be removed; if it doesn't, it will be added
+ *
  * @param destination Array to toggle within
  * @param toggled Toggled items
  * @param key Key to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * toggle(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 3}, {id: 4}]
+ * ```
  */
 declare function toggle<Item extends PlainObject, ItemKey extends keyof Item>(destination: Item[], toggled: Item[], key: ItemKey): Item[];
 /**
- * Toggle an item in an array: if the item exists, it will be removed; if it doesn't, it will be added
+ * Toggle an item in an array
+ *
+ * If the item exists, it will be removed; if it doesn't, it will be added
+ *
  * @param destination Array to toggle within
  * @param toggled Toggled items
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * toggle(
+ *   [1, 2, 3],
+ *   [2, 4],
+ * ); // => [1, 3, 4]
+ * ```
  */
 declare function toggle<Item>(destination: Item[], toggled: Item[]): Item[];
 //#endregion

package/dist/array/union.d.mts

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

package/dist/array/unique.d.mts

@@ -3,22 +3,46 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/unique.d.ts
 /**
  * Get an array of unique items
+ *
  * @param array Original array
  * @param callback Callback to get an item's value
  * @returns Array of unique items
+ *
+ * @example
+ * ```typescript
+ * unique(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 declare function unique<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
  * Get an array of unique items
+ *
  * @param array Original array
  * @param key Key to use for unique value
  * @returns Array of unique items
+ *
+ * @example
+ * ```typescript
+ * unique(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 declare function unique<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Item[];
 /**
  * Get an array of unique items
+ *
  * @param array Original array
  * @returns Array of unique items
+ *
+ * @example
+ * ```typescript
+ * unique([1, 2, 3, 2]); // => [1, 2, 3]
+ * ```
  */
 declare function unique<Item>(array: Item[]): Item[];
 //#endregion

package/dist/array/update.d.mts

@@ -2,26 +2,61 @@ import { PlainObject } from "../models.mjs";
 
 //#region src/array/update.d.ts
 /**
- * Update an item in an array: if the item exists, it will be updated; if it doesn't, it will be added
+ * Update an item in an array
+ *
+ * If the item exists, it will be updated; if it doesn't, it will be added
+ *
  * @param destination Array to update within
  * @param updated Updated items
  * @param callback Callback to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * update(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2, name: 'Updated'}, {id: 4, name: 'New'}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 2, name: 'Updated'}, {id: 3}, {id: 4, name: 'New'}]
+ * ```
  */
 declare function update<Item>(destination: Item[], updated: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
- * Update an item in an array: if the item exists, it will be updated; if it doesn't, it will be added
+ * Update an item in an array
+ *
+ * If the item exists, it will be updated; if it doesn't, it will be added
+ *
  * @param destination Array to update within
  * @param updated Updated items
  * @param key Key to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * update(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2, name: 'Updated'}, {id: 4, name: 'New'}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 2, name: 'Updated'}, {id: 3}, {id: 4, name: 'New'}]
+ * ```
  */
 declare function update<Item extends PlainObject, ItemKey extends keyof Item>(destination: Item[], updated: Item[], key: ItemKey): Item[];
 /**
- * Update an item in an array: if the item exists, it will be updated; if it doesn't, it will be added
+ * Update an item in an array
+ *
+ * If the item exists, it will be updated; if it doesn't, it will be added
+ *
  * @param destination Array to update within
  * @param updated Updated items
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * update(
+ *   [1, 2, 3],
+ *   [2, 4],
+ * ); // => [1, 2, 3, 4]
+ * ```
  */
 declare function update<Item>(destination: Item[], updated: Item[]): Item[];
 //#endregion