@oscarpalmer/atoms 0.186.2 → 0.187.0

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

@@ -2,14 +2,14 @@ import { Key, PlainObject } from "../models.mjs";
 
 //#region src/array/to-map.d.ts
 /**
- * Create a Map from an array of items using callbacks
+ * Create a _Map_ from an array of items using callbacks
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -22,14 +22,14 @@ import { Key, PlainObject } from "../models.mjs";
  */
 declare function toMap<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): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>>;
 /**
- * Create a Map from an array of items using a callback and value
+ * Create a _Map_ from an array of items using a callback and value
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -42,14 +42,14 @@ declare function toMap<Item, KeyCallback extends (item: Item, index: number, arr
  */
 declare function toMap<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Map<ReturnType<KeyCallback>, Item[ItemValue]>;
 /**
- * Create a Map from an array of items using a key and callback
+ * Create a _Map_ from an array of items using a key and callback
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -62,14 +62,14 @@ declare function toMap<Item extends PlainObject, KeyCallback extends (item: Item
  */
 declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Map<Item[ItemKey], ReturnType<ValueCallback>>;
 /**
- * Create a Map from an array of items using a key and value
+ * Create a _Map_ from an array of items using a key and value
  *
  * If multiple items have the same key, the latest item's value will be used
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Key to use for value
- * @returns Map of keyed values
+ * @returns _Map_ of keyed values
  *
  * @example
  * ```typescript
@@ -82,13 +82,13 @@ declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, Val
  */
 declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue]>;
 /**
- * Create a Map from an array of items using a callback
+ * Create a _Map_ from an array of items using a callback
  *
  * If multiple items have the same key, the latest item will be used
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
- * @returns Map of keyed items
+ * @returns _Map_ of keyed items
  *
  * @example
  * ```typescript
@@ -100,13 +100,13 @@ declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, Ite
  */
 declare function toMap<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Map<ReturnType<Callback>, Item>;
 /**
- * Create a Map from an array of items using a key
+ * Create a _Map_ from an array of items using a key
  *
  * If multiple items have the same key, the latest item will be used
  *
  * @param array Array to convert
  * @param key Key to use for grouping
- * @returns Map of keyed items
+ * @returns _Map_ of keyed items
  *
  * @example
  * ```typescript
@@ -118,10 +118,10 @@ declare function toMap<Item, Callback extends (item: Item, index: number, array:
  */
 declare function toMap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Map<Item[ItemKey], Item>;
 /**
- * Create a Map from an array of items _(using indices as keys)_
+ * Create a _Map_ from an array of items _(using indices as keys)_
  *
  * @param array Array to convert
- * @returns Map of indiced items
+ * @returns _Map_ of indiced items
  *
  * @example
  * ```typescript
@@ -135,14 +135,14 @@ declare namespace toMap {
   var arrays: typeof toMapArrays;
 }
 /**
- * Create a Map from an array of items using callbacks, grouping values into arrays
+ * Create a _Map_ from an array of items using callbacks, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -155,14 +155,14 @@ declare namespace toMap {
  */
 declare function toMapArrays<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): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>[]>;
 /**
- * Create a Map from an array of items using a callback and value, grouping values into arrays
+ * Create a _Map_ from an array of items using a callback and value, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -175,14 +175,14 @@ declare function toMapArrays<Item, KeyCallback extends (item: Item, index: numbe
  */
 declare function toMapArrays<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Map<ReturnType<KeyCallback>, Item[ItemValue][]>;
 /**
- * Create a Map from an array of items using a key and callback, grouping values into arrays
+ * Create a _Map_ from an array of items using a key and callback, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -195,14 +195,14 @@ declare function toMapArrays<Item extends PlainObject, KeyCallback extends (item
  */
 declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Map<Item[ItemKey], ReturnType<ValueCallback>[]>;
 /**
- * Create a Map from an array of items using a key and value, grouping values into arrays
+ * Create a _Map_ from an array of items using a key and value, grouping values into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Key to use for value
- * @returns Map of keyed arrays of values
+ * @returns _Map_ of keyed arrays of values
  *
  * @example
  * ```typescript
@@ -215,13 +215,13 @@ declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Ite
  */
 declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue][]>;
 /**
- * Create a Map from an array of items using a callback, grouping items into arrays
+ * Create a _Map_ from an array of items using a callback, grouping items into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
- * @returns Map of keyed arrays of items
+ * @returns _Map_ of keyed arrays of items
  *
  * @example
  * ```typescript
@@ -233,13 +233,13 @@ declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Ite
  */
 declare function toMapArrays<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Map<ReturnType<Callback>, Item[]>;
 /**
- * Create a Map from an array of items using a key, grouping items into arrays
+ * Create a _Map_ from an array of items using a key, grouping items into arrays
  *
- * Available as `toMapArrays` and `toMap.arrays`
+ * _Available as `toMapArrays` and `toMap.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
- * @returns Map of keyed arrays of items
+ * @returns _Map_ of keyed arrays of items
  *
  * @example
  * ```typescript

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

@@ -137,7 +137,7 @@ declare namespace toRecord {
 /**
  * Create a record from an array of items using callbacks, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
@@ -157,7 +157,7 @@ declare function toRecordArrays<Item, KeyCallback extends (item: Item, index: nu
 /**
  * Create a record from an array of items using a callback and value, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
@@ -177,7 +177,7 @@ declare function toRecordArrays<Item extends PlainObject, Callback extends (item
 /**
  * Create a record from an array of items using a key and callback, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
@@ -197,7 +197,7 @@ declare function toRecordArrays<Item extends PlainObject, ItemKey extends keyof
 /**
  * Create a record from an array of items using a key and value, grouping values into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping
@@ -217,7 +217,7 @@ declare function toRecordArrays<Item extends PlainObject, ItemKey extends keyof
 /**
  * Create a record from an array of items using a callback, grouping items into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
@@ -235,7 +235,7 @@ declare function toRecordArrays<Item, Callback extends (item: Item, index: numbe
 /**
  * Create a record from an array of items using a key, grouping items into arrays
  *
- * Available as `toRecordArrays` and `toRecord.arrays`
+ * _Available as `toRecordArrays` and `toRecord.arrays`_
  *
  * @param array Array to convert
  * @param key Key to use for grouping

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

@@ -2,11 +2,11 @@ import { PlainObject } from "../models.mjs";
 
 //#region src/array/to-set.d.ts
 /**
- * Create a Set from an array of items using a callback
+ * 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
+ * @returns _Set_ of values
  *
  * @example
  * ```typescript
@@ -18,11 +18,11 @@ import { PlainObject } from "../models.mjs";
  */
 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
+ * 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
+ * @returns _Set_ of values
  *
  * @example
  * ```typescript
@@ -34,10 +34,10 @@ declare function toSet<Item, Callback extends (item: Item, index: number, array:
  */
 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
+ * Create a _Set_ from an array of items
  *
  * @param array Array to convert
- * @returns Set of items
+ * @returns _Set_ of items
  *
  * @example
  * ```typescript

package/dist/beacon.d.mts

@@ -23,12 +23,14 @@ declare class Beacon<Value> {
   destroy(): void;
   /**
    * Emit a new value
+   *
    * @param value Value to set and emit
    * @param finish Finish the beacon after emitting? _(defaults to `false`)_
    */
   emit(value: Value, finish?: boolean): void;
   /**
    * Emit an error
+   *
    * @param value Error to emit
    * @param finish Finish the beacon after emitting? _(defaults to `false`)_
    */
@@ -44,6 +46,7 @@ declare class Beacon<Value> {
 type BeaconOptions<Value> = {
   /**
    * Method for comparing values for equality
+   *
    * @param first First value
    * @param second Second value
    * @returns `true` if the values are equal, otherwise `false`
@@ -63,6 +66,7 @@ declare class Observable<Value> {
   destroy(): void;
   /**
    * Subscribe to value changes
+   *
    * @param onNext Callback for when the observable receives a new value
    * @param onError Callback for when the observable receives an error
    * @param onComplete Callback for when the observable is completed
@@ -71,6 +75,7 @@ declare class Observable<Value> {
   subscribe(onNext: (value: Value) => void, onError?: (error: Error) => void, onComplete?: () => void): Subscription<Value>;
   /**
    * Subscribe to value changes
+   *
    * @param observer Observer for changes
    * @returns Subscription to the observable
    */
@@ -119,6 +124,7 @@ declare class Subscription<Value> {
 }
 /**
  * Create a new beacon
+ *
  * @param value Initial value
  * @param options Beacon options
  * @returns Beacon instance

package/dist/beacon.mjs

@@ -44,6 +44,7 @@ var Beacon = class {
 	}
 	/**
 	* Emit a new value
+	*
 	* @param value Value to set and emit
 	* @param finish Finish the beacon after emitting? _(defaults to `false`)_
 	*/
@@ -52,6 +53,7 @@ var Beacon = class {
 	}
 	/**
 	* Emit an error
+	*
 	* @param value Error to emit
 	* @param finish Finish the beacon after emitting? _(defaults to `false`)_
 	*/
@@ -136,6 +138,7 @@ var Subscription = class {
 };
 /**
 * Create a new beacon
+*
 * @param value Initial value
 * @param options Beacon options
 * @returns Beacon instance

package/dist/color/index.d.mts

@@ -8,9 +8,13 @@ import { rgbToHex, rgbToHsl, rgbToHsla } from "./space/rgb.mjs";
 
 //#region src/color/index.d.ts
 /**
- * Get a Color from any kind of value
+ * Get a _Color_ from any kind of value
+ *
+ * - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+ * - If the value is unable to be parsed, a black _Color_ will be returned
+ *
  * @param value Original value
- * @returns Color instance
+ * @returns _Color_ instance
  */
 declare function getColor(value: unknown): Color;
 //#endregion

package/dist/color/index.mjs

@@ -6,9 +6,13 @@ import { hslToHex, hslToRgb, hslToRgba } from "./space/hsl.mjs";
 import { Color } from "./instance.mjs";
 //#region src/color/index.ts
 /**
-* Get a Color from any kind of value
+* Get a _Color_ from any kind of value
+*
+* - Values that can be parsed are: hex(a) color strings, _HSL(A)_ color objects, and _RGB(A)_ color objects
+* - If the value is unable to be parsed, a black _Color_ will be returned
+*
 * @param value Original value
-* @returns Color instance
+* @returns _Color_ instance
 */
 function getColor(value) {
 	return isColor(value) ? value : new Color(value);

package/dist/color/instance.d.mts

@@ -13,65 +13,129 @@ declare class Color {
    */
   private readonly $color;
   /**
-   * Get the alpha channel
+   * Get the alpha channel _(opacity)_ of the color
+   *
+   * @returns Current alpha channel value between `0` and `1`
    */
   get alpha(): number;
   /**
-   * Set the alpha channel
+   * Set the alpha channel _(opacity)_ of the color, as:
+   *
+   * - A number between `0` and `1`, where `0` is fully transparent and `1` is fully opaque
+   * - A number between `0` and `100`, where `0` is fully transparent and `100` is fully opaque
+   *
+   * @param value New alpha channel value
    */
   set alpha(value: number);
   /**
-   * Get the color as a hex color
+   * Get the color as a hex color string
+   *
+   * _Hex color string is returned with no `#`-prefix or alpha channel (opacity)_
+   *
+   * @returns Current color as a hex color string
    */
   get hex(): string;
   /**
-   * Set colors from a hex color
+   * Set the color from a hex color string
+   *
+   * - `#`-prefix is optional
+   * - Alpha channel _(opacity)_ will be ignored
+   *
+   * @param value New hex color string
    */
   set hex(value: string);
   /**
-   * Get the color as a hex color with an alpha channel
+   * Get the color as a hex color with an alpha channel _(opacity)_
+   *
+   * _Hex color string is returned with alpha channel (opacity), but without `#`-prefix_
+   *
+   * @returns Current color as a hex color string
    */
   get hexa(): string;
   /**
-   * Set colors and alpha from a hex color with an alpha channel
+   * Set the color from a hex color string with an alpha channel _(opacity)_
+   *
+   * - `#`-prefix is optional
+   * - Alpha channel _(opacity)_ will be respected
+   *
+   * @param value New hex color string
    */
   set hexa(value: string);
   /**
-   * Get the color as an HSL color
+   * Get the color as an _HSL_ color
+   *
+   * @returns Current color as an _HSL_ color
    */
   get hsl(): HSLColor;
   /**
-   * Set colors from an HSL color
+   * Set colors from an _HSL_ color
+   *
+   * @param value New _HSL_ color
    */
   set hsl(value: HSLColor);
   /**
-   * Get the color as an HSLA color
+   * Get the color as an _HSLA_ color
+   *
+   * @returns Current color as an _HSLA_ color
    */
   get hsla(): HSLAColor;
   /**
-   * Set colors and alpha from an HSLA color
+   * Set colors and alpha from an _HSLA_ color
+   *
+   * @param value New _HSLA_ color
    */
   set hsla(value: HSLAColor);
   /**
-   * Get the color as an RGB color
+   * Get the color as an _RGB_ color
+   *
+   * @returns Current color as an _RGB_ color
    */
   get rgb(): RGBColor;
   /**
-   * Set colors from an RGB color
+   * Set colors from an _RGB_ color
+   *
+   * @param value New _RGB_ color
    */
   set rgb(value: RGBColor);
   /**
-   * Get the color as an RGBA color
+   * Get the color as an _RGBA_ color
+   *
+   * @returns Current color as an _RGBA_ color
    */
   get rgba(): RGBAColor;
   /**
-   * Set colors and alpha from an RGBA color
+   * Set colors and alpha from an _RGBA_ color
+   *
+   * @param value New _RGBA_ color
    */
   set rgba(value: RGBAColor);
   constructor(value: unknown);
+  /**
+   * Get the color as a hex string
+   *
+   * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+   * @returns Hex color string
+   */
   toHexString(alpha?: boolean): string;
+  /**
+   * Get the color as an _HSL(A)_ string
+   *
+   * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+   * @returns _HSL(A)_ color string
+   */
   toHslString(alpha?: boolean): string;
+  /**
+   * Get the color as an _RGB(A)_ string
+   *
+   * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+   * @returns _RGB(A)_ color string
+   */
   toRgbString(alpha?: boolean): string;
+  /**
+   * Get the color as a hex color string
+   *
+   * @returns Hex color string
+   */
   toString(): string;
 }
 //#endregion