@oscarpalmer/atoms 0.184.2 → 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

package/dist/beacon.d.mts

@@ -1,4 +1,7 @@
 //#region src/beacon.d.ts
+/**
+ * A beacon is a lighthouse, holding an observable value that can be subscribed to and emitted from
+ */
 declare class Beacon<Value> {
   #private;
   /**
@@ -48,6 +51,9 @@ type BeaconOptions<Value> = {
    */
   equal?: (first: Value, second: Value) => boolean;
 };
+/**
+ * An observable holds a value and allows observers to subscribe to changes in that value
+ */
 declare class Observable<Value> {
   #private;
   constructor(instance: Beacon<Value>, observers: Map<Subscription<Value>, Observer<Value>>);
@@ -75,6 +81,9 @@ type ObservableState<Value> = {
   closed: boolean;
   observers: Map<Subscription<Value>, Observer<Value>>;
 };
+/**
+ * An observer receives notifications from an observable
+ */
 type Observer<Value> = {
   /**
    * Callback for when the observable is completed
@@ -89,6 +98,9 @@ type Observer<Value> = {
    */
   next?: (value: Value) => void;
 };
+/**
+ * A subscription represents an active subscription to an observable, holding its state and allowing it to be destroyed or unsubscribed from
+ */
 declare class Subscription<Value> {
   #private;
   constructor(state: ObservableState<Value>);

package/dist/beacon.mjs

@@ -1,6 +1,9 @@
 import { noop } from "./internal/function/misc.mjs";
 import { isPlainObject } from "./internal/is.mjs";
 //#region src/beacon.ts
+/**
+* A beacon is a lighthouse, holding an observable value that can be subscribed to and emitted from
+*/
 var Beacon = class {
 	#options;
 	#state;
@@ -71,6 +74,9 @@ var Beacon = class {
 		if (finish === true) finishBeacon(this.#state, true);
 	}
 };
+/**
+* An observable holds a value and allows observers to subscribe to changes in that value
+*/
 var Observable = class {
 	#state;
 	constructor(instance, observers) {
@@ -95,6 +101,9 @@ var Observable = class {
 		return instance;
 	}
 };
+/**
+* A subscription represents an active subscription to an observable, holding its state and allowing it to be destroyed or unsubscribed from
+*/
 var Subscription = class {
 	#state;
 	constructor(state) {

package/dist/color/instance.d.mts

@@ -1,8 +1,16 @@
 import { HSLAColor, HSLColor, RGBAColor, RGBColor } from "./models.mjs";
 
 //#region src/color/instance.d.ts
+/**
+ * A color that is represented in multiple color formats
+ */
 declare class Color {
   #private;
+  /**
+   * A property to identify this as a Color instance, used for type checking
+   *
+   * @internal
+   */
   private readonly $color;
   /**
    * Get the alpha channel

package/dist/color/instance.mjs

@@ -3,6 +3,9 @@ import { formatColor } from "./misc/index.mjs";
 import { getAlpha } from "./misc/alpha.mjs";
 import { getColorState, setHSLColor, setHexColor, setRGBColor } from "./misc/state.mjs";
 //#region src/color/instance.ts
+/**
+* A color that is represented in multiple color formats
+*/
 var Color = class {
 	#state;
 	/**

package/dist/color/models.d.mts

@@ -6,16 +6,46 @@ type Alpha = {
 type ColorWithAlpha = {
   alpha: number;
 };
+/**
+ * An _HSL_-color with an alpha channel
+ */
 type HSLAColor = HSLColor & ColorWithAlpha;
+/**
+ * An _HSL_-color
+ */
 type HSLColor = {
+  /**
+   * Hue of the color _(in degrees; 0-360)_
+   */
   hue: number;
+  /**
+   * Lightness of the color _(in percentage; 0-100)_
+   */
   lightness: number;
+  /**
+   * Saturation of the color _(in percentage; 0-100)_
+   */
   saturation: number;
 };
+/**
+ * An _RGB_-color with an alpha channel
+ */
 type RGBAColor = RGBColor & ColorWithAlpha;
+/**
+ * An _RGB_-color
+ */
 type RGBColor = {
+  /**
+   * Blue channel of the color _(in hexadecimal; 0-255)_
+   */
   blue: number;
+  /**
+   * Green channel of the color _(in hexadecimal; 0-255)_
+   */
   green: number;
+  /**
+   * Red channel of the color _(in hexadecimal; 0-255)_
+   */
   red: number;
 };
 type ColorProperty = 'alpha' | 'blue' | 'green' | 'hue' | 'lightness' | 'red' | 'saturation';

package/dist/function/assert.d.mts

@@ -1,12 +1,20 @@
-import { Constructor } from "../models.mjs";
+import { Constructor, NestedKeys, NestedValue, PlainObject } from "../models.mjs";
 
 //#region src/function/assert.d.ts
+/**
+ * Asserter for a nested property of a value
+ */
+type AssertProperty<Value extends PlainObject, Path extends NestedKeys<Value>, Asserted extends NestedPick<Value, Path> = NestedPick<Value, Path>> = Asserter<Asserted>;
+/**
+ * A function that asserts a value is of a specific type, throwing an error if it is not
+ */
 type Asserter<Value> = (value: unknown) => asserts value is Value;
+type NestedPick<Value, Path extends string> = Value extends PlainObject ? Path extends `${infer Head}.${infer Rest}` ? Head extends keyof Value ? { [Key in Head]: NestedPick<Value[Key], Rest> } : never : Path extends keyof Value ? { [Key in Path]: Value[Key] } : never : never;
 /**
  * Asserts that a condition is true, throwing an error if it is not
  * @param condition Condition to assert
  * @param message Error message
- * @param error Error constructor
+ * @param error Error constructor _(defaults to `Error`)_
  */
 declare function assert<Condition extends () => boolean>(condition: Condition, message: string, error?: ErrorConstructor): asserts condition;
 declare namespace assert {
@@ -14,6 +22,7 @@ declare namespace assert {
   var defined: typeof assertDefined;
   var instanceOf: typeof assertInstanceOf;
   var is: typeof assertIs;
+  var property: typeof assertProperty;
 }
 /**
  * Creates an asserter that asserts a condition is true, throwing an error if it is not
@@ -21,25 +30,26 @@ declare namespace assert {
  * Available as `assertCondition` and `assert.condition`
  * @param condition Condition to assert
  * @param message Error message
- * @param error Error constructor
+ * @param error Error constructor _(defaults to `Error`)_
  * @returns Asserter
  */
 declare function assertCondition<Value>(condition: (value: unknown) => boolean, message: string, error?: ErrorConstructor): Asserter<Value>;
 /**
- * Asserts that a value is defined throwing an error if it is not
+ * Asserts that a value is defined, throwing an error if it is not
  *
  * Available as `assertDefined` and `assert.defined`
  * @param value Value to assert
  * @param message Error message
+ * @param error Error constructor _(defaults to `Error`)_
  */
-declare function assertDefined<Value>(value: unknown, message?: string): asserts value is Exclude<Value, null | undefined>;
+declare function assertDefined<Value>(value: unknown, message?: string, error?: ErrorConstructor): asserts value is Exclude<Value, null | undefined>;
 /**
  * Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
  *
  * Available as `assertInstanceOf` and `assert.instanceOf`
  * @param constructor Constructor to check against
  * @param message Error message
- * @param error Error constructor
+ * @param error Error constructor _(defaults to `Error`)_
  * @returns Asserter
  */
 declare function assertInstanceOf<Value>(constructor: Constructor<Value>, message: string, error?: ErrorConstructor): Asserter<Value>;
@@ -49,9 +59,20 @@ declare function assertInstanceOf<Value>(constructor: Constructor<Value>, messag
  * Available as `assertIs` and `assert.is`
  * @param condition Type guard function to check the value
  * @param message Error message
- * @param error Error constructor
+ * @param error Error constructor _(defaults to `Error`)_
  * @returns Asserter
  */
 declare function assertIs<Value>(condition: (value: unknown) => value is Value, message: string, error?: ErrorConstructor): Asserter<Value>;
+/**
+ * Creates an asserter that asserts a property of a value exists and satisfies a condition, throwing an error if it does not
+ *
+ * Available as `assertProperty` and `assert.property`
+ * @param path Path to the property to check, e.g., `foo.bar.baz` for a nested property
+ * @param condition Condition to assert for the property
+ * @param message Error message
+ * @param error Error constructor _(defaults to `Error`)_
+ * @returns Asserter
+ */
+declare function assertProperty<Value extends PlainObject, Path extends NestedKeys<Value>, Asserted = NestedPick<Value, Path>>(path: Path, condition: (value: NestedValue<Value, Path>) => boolean, message: string, error?: ErrorConstructor): Asserter<Asserted>;
 //#endregion
-export { Asserter, assert, assertCondition, assertDefined, assertInstanceOf, assertIs };
+export { AssertProperty, Asserter, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assertProperty };

package/dist/function/assert.mjs

@@ -1,9 +1,10 @@
+import { hasValueResult } from "../internal/value/has.mjs";
 //#region src/function/assert.ts
 /**
 * Asserts that a condition is true, throwing an error if it is not
 * @param condition Condition to assert
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 */
 function assert(condition, message, error) {
 	if (!condition()) throw new (error ?? Error)(message);
@@ -12,13 +13,14 @@ assert.condition = assertCondition;
 assert.defined = assertDefined;
 assert.instanceOf = assertInstanceOf;
 assert.is = assertIs;
+assert.property = assertProperty;
 /**
 * Creates an asserter that asserts a condition is true, throwing an error if it is not
 *
 * Available as `assertCondition` and `assert.condition`
 * @param condition Condition to assert
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 * @returns Asserter
 */
 function assertCondition(condition, message, error) {
@@ -27,14 +29,15 @@ function assertCondition(condition, message, error) {
 	};
 }
 /**
-* Asserts that a value is defined throwing an error if it is not
+* Asserts that a value is defined, throwing an error if it is not
 *
 * Available as `assertDefined` and `assert.defined`
 * @param value Value to assert
 * @param message Error message
+* @param error Error constructor _(defaults to `Error`)_
 */
-function assertDefined(value, message) {
-	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED);
+function assertDefined(value, message, error) {
+	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED, error);
 }
 /**
 * Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
@@ -42,7 +45,7 @@ function assertDefined(value, message) {
 * Available as `assertInstanceOf` and `assert.instanceOf`
 * @param constructor Constructor to check against
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 * @returns Asserter
 */
 function assertInstanceOf(constructor, message, error) {
@@ -56,7 +59,7 @@ function assertInstanceOf(constructor, message, error) {
 * Available as `assertIs` and `assert.is`
 * @param condition Type guard function to check the value
 * @param message Error message
-* @param error Error constructor
+* @param error Error constructor _(defaults to `Error`)_
 * @returns Asserter
 */
 function assertIs(condition, message, error) {
@@ -64,6 +67,24 @@ function assertIs(condition, message, error) {
 		assert(() => condition(value), message, error);
 	};
 }
+/**
+* Creates an asserter that asserts a property of a value exists and satisfies a condition, throwing an error if it does not
+*
+* Available as `assertProperty` and `assert.property`
+* @param path Path to the property to check, e.g., `foo.bar.baz` for a nested property
+* @param condition Condition to assert for the property
+* @param message Error message
+* @param error Error constructor _(defaults to `Error`)_
+* @returns Asserter
+*/
+function assertProperty(path, condition, message, error) {
+	return (value) => {
+		assert(() => {
+			const result = hasValueResult(value, path, false);
+			return result.ok && condition(result.value);
+		}, message, error);
+	};
+}
 const MESSAGE_VALUE_DEFINED = "Expected value to be defined";
 //#endregion
-export { assert, assertCondition, assertDefined, assertInstanceOf, assertIs };
+export { assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assertProperty };

package/dist/function/memoize.d.mts

@@ -1,6 +1,9 @@
 import { GenericCallback } from "../models.mjs";
 
 //#region src/function/memoize.d.ts
+/**
+ * A memoized function, caching and retrieving results based on the its parameters _(or a custom cache key)_
+ */
 declare class Memoized<Callback extends GenericCallback> {
   #private;
   /**

package/dist/function/memoize.mjs

@@ -2,6 +2,9 @@ import { isPlainObject } from "../internal/is.mjs";
 import { getString, join } from "../internal/string.mjs";
 import { SizedMap } from "../sized/map.mjs";
 //#region src/function/memoize.ts
+/**
+* A memoized function, caching and retrieving results based on the its parameters _(or a custom cache key)_
+*/
 var Memoized = class {
 	#state;
 	/**

package/dist/function/retry.d.mts

@@ -1,6 +1,9 @@
 import { GenericAsyncCallback, GenericCallback } from "../models.mjs";
 
 //#region src/function/retry.d.ts
+/**
+ * An error thrown when a retry fails
+ */
 declare class RetryError extends Error {
   readonly original: unknown;
   constructor(message: string, original: unknown);

package/dist/function/retry.mjs

@@ -1,6 +1,9 @@
 import { isPlainObject } from "../internal/is.mjs";
 import { TIMER_WAIT, getTimer } from "../internal/function/timer.mjs";
 //#region src/function/retry.ts
+/**
+* An error thrown when a retry fails
+*/
 var RetryError = class extends Error {
 	constructor(message, original) {
 		super(message);

package/dist/function/work.mjs

@@ -1,5 +1,5 @@
-import { assert } from "./assert.mjs";
 import { isError, isOk } from "../internal/result.mjs";
+import { assert } from "./assert.mjs";
 //#region src/function/work.ts
 function asyncFlow(...fns) {
 	assertFlowFunctions(fns);