@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/array/unique.ts

@@ -5,9 +5,18 @@ import type {PlainObject} from '../models';
 
 /**
  * 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}]
+ * ```
  */
 export function unique<Item>(
 	array: Item[],
@@ -16,9 +25,18 @@ export function unique<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}]
+ * ```
  */
 export function unique<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -27,8 +45,14 @@ export function unique<Item extends PlainObject, ItemKey extends keyof 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]
+ * ```
  */
 export function unique<Item>(array: Item[]): Item[];
 

package/src/array/update.ts

@@ -2,11 +2,23 @@ import {updateInArray} from '../internal/array/update';
 import type {PlainObject} from '../models';
 
 /**
- * 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'}]
+ * ```
  */
 export function update<Item>(
 	destination: Item[],
@@ -15,11 +27,23 @@ export function update<Item>(
 ): 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'}]
+ * ```
  */
 export function update<Item extends PlainObject, ItemKey extends keyof Item>(
 	destination: Item[],
@@ -28,10 +52,21 @@ export function update<Item extends PlainObject, ItemKey extends keyof Item>(
 ): 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]
+ * ```
  */
 export function update<Item>(destination: Item[], updated: Item[]): Item[];
 

package/src/beacon.ts

@@ -4,6 +4,9 @@ import type {PlainObject} from './models';
 
 // #region Types
 
+/**
+ * A beacon is a lighthouse, holding an observable value that can be subscribed to and emitted from
+ */
 class Beacon<Value> {
 	readonly #options: Options;
 	readonly #state: BeaconState<Value>;
@@ -122,6 +125,9 @@ type BeaconState<Value> = {
 	value: Value;
 };
 
+/**
+ * An observable holds a value and allows observers to subscribe to changes in that value
+ */
 class Observable<Value> {
 	readonly #state: ObservableState<Value>;
 
@@ -186,6 +192,9 @@ type ObservableState<Value> = {
 	observers: Map<Subscription<Value>, Observer<Value>>;
 };
 
+/**
+ * An observer receives notifications from an observable
+ */
 type Observer<Value> = {
 	/**
 	 * Callback for when the observable is completed
@@ -203,6 +212,9 @@ type Observer<Value> = {
 
 type Options = Required<BeaconOptions<unknown>>;
 
+/**
+ * A subscription represents an active subscription to an observable, holding its state and allowing it to be destroyed or unsubscribed from
+ */
 class Subscription<Value> {
 	readonly #state: SubscriptionState<Value>;
 

package/src/color/index.ts

@@ -39,11 +39,8 @@ export {
 } from './misc/is';
 
 export {getNormalizedHex, hexToHsl, hexToHsla, hexToRgb, hexToRgba} from './space/hex';
-
 export {hslToHex, hslToRgb, hslToRgba} from './space/hsl';
-
 export {rgbToHex, rgbToHsl, rgbToHsla} from './space/rgb';
-
 export type {Color, HSLAColor, HSLColor, RGBAColor, RGBColor};
 
 // #endregion

package/src/color/instance.ts

@@ -4,9 +4,17 @@ import {getAlpha} from './misc/alpha';
 import {getColorState, setHexColor, setHSLColor, setRGBColor} from './misc/state';
 import type {ColorState, HSLAColor, HSLColor, RGBAColor, RGBColor} from './models';
 
-// #region Classes
+// #region Types
 
+/**
+ * A color that is represented in multiple color formats
+ */
 export class Color {
+	/**
+	 * A property to identify this as a Color instance, used for type checking
+	 *
+	 * @internal
+	 */
 	declare private readonly $color: boolean;
 
 	readonly #state: ColorState;

package/src/color/models.ts

@@ -9,19 +9,49 @@ type ColorWithAlpha = {
 	alpha: number;
 };
 
+/**
+ * An _HSL_-color with an alpha channel
+ */
 export type HSLAColor = HSLColor & ColorWithAlpha;
 
+/**
+ * An _HSL_-color
+ */
 export 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
+ */
 export type RGBAColor = RGBColor & ColorWithAlpha;
 
+/**
+ * An _RGB_-color
+ */
 export 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;
 };
 

package/src/function/assert.ts

@@ -1,9 +1,32 @@
-import type {Constructor} from '../models';
+import {hasValueResult} from '../internal/value/has';
+import type {Constructor, NestedKeys, NestedValue, PlainObject} from '../models';
 
 // #region Types
 
+/**
+ * Asserter for a nested property of a value
+ */
+export 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
+ */
 export 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;
+
 // #endregion
 
 // #region Functions
@@ -12,7 +35,7 @@ export type Asserter<Value> = (value: unknown) => asserts value is Value;
  * 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`)_
  */
 export function assert<Condition extends () => boolean>(
 	condition: Condition,
@@ -28,6 +51,7 @@ 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
@@ -35,7 +59,7 @@ assert.is = assertIs;
  * 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
  */
 export function assertCondition<Value>(
@@ -49,17 +73,19 @@ export function assertCondition<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`)_
  */
 export function assertDefined<Value>(
 	value: unknown,
 	message?: string,
+	error?: ErrorConstructor,
 ): asserts value is Exclude<Value, null | undefined> {
-	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED);
+	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED, error);
 }
 
 /**
@@ -68,7 +94,7 @@ export function assertDefined<Value>(
  * 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
  */
 export function assertInstanceOf<Value>(
@@ -87,7 +113,7 @@ export function assertInstanceOf<Value>(
  * 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
  */
 export function assertIs<Value>(
@@ -100,6 +126,39 @@ export function assertIs<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
+ */
+export 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> {
+	return (value: unknown): asserts value is Asserted => {
+		assert(
+			() => {
+				const result = hasValueResult(value as never, path, false);
+
+				return result.ok && condition(result.value as never);
+			},
+			message,
+			error,
+		);
+	};
+}
+
 // #endregion
 
 // #region Variables

package/src/function/memoize.ts

@@ -5,6 +5,9 @@ import {SizedMap} from '../sized/map';
 
 // #region Types
 
+/**
+ * A memoized function, caching and retrieving results based on the its parameters _(or a custom cache key)_
+ */
 class Memoized<Callback extends GenericCallback> {
 	readonly #state: MemoizedState<Callback>;
 

package/src/function/once.ts

@@ -107,7 +107,11 @@ export function asyncOnce<Callback extends GenericAsyncCallback>(
 	return fn as OnceAsyncCallback<Callback>;
 }
 
-function handleOnceResult<Value>(state: OnceAsyncState<Value>, value: unknown, error: boolean): void {
+function handleOnceResult<Value>(
+	state: OnceAsyncState<Value>,
+	value: unknown,
+	error: boolean,
+): void {
 	state.error = error;
 	state.finished = true;
 	state.value = value as Value;

package/src/function/retry.ts

@@ -4,6 +4,9 @@ import type {GenericAsyncCallback, GenericCallback} from '../models';
 
 // #region Types
 
+/**
+ * An error thrown when a retry fails
+ */
 export class RetryError extends Error {
 	constructor(
 		message: string,

package/src/internal/array/chunk.ts

@@ -2,9 +2,15 @@
 
 /**
  * Chunk an array into smaller arrays
+ *
  * @param array Array to chunk
  * @param size Size of each chunk _(minimum is `1`, maximum is `5000`; defaults to `5000`)_
  * @returns Array of arrays
+ *
+ * @example
+ * ```typescript
+ * chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
+ * ```
  */
 export function chunk<Item>(array: Item[], size?: number): Item[][] {
 	if (!Array.isArray(array)) {

package/src/internal/array/compact.ts

@@ -2,9 +2,15 @@
 
 /**
  * Compact an array _(removing all false-y values)_
+ *
  * @param array Array to compact
  * @param strict True to remove all false-y values
  * @returns Compacted array
+ *
+ * @example
+ * ```typescript
+ * compact([0, 1, '', 'hello', false, true, null, undefined]); // => [1, 'hello', true]
+ * ```
  */
 export function compact<Item>(
 	array: Item[],
@@ -13,8 +19,14 @@ export function compact<Item>(
 
 /**
  * Compact an array _(removing all `null` and `undefined` values)_
+ *
  * @param array Array to compact
  * @returns Compacted array
+ *
+ * @example
+ * ```typescript
+ * compact([0, 1, '', 'hello', false, true, null, undefined]); // => [0, 1, '', 'hello', false, true]
+ * ```
  */
 export function compact<Item>(array: Item[]): Exclude<Item, null | undefined>[];
 

package/src/internal/array/index-of.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../../models';
 
 /**
  * Get the index of the first matching item by callback
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value
  * @param value Value to match against
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => 1
+ * ```
  */
 export function indexOf<
 	Item,
@@ -17,10 +27,20 @@ export function indexOf<
 
 /**
  * Get the index of the first matching item by key
+ *
  * @param array Array to search in
  * @param key Key to match items by
  * @param value Value to match against
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => 1
+ * ```
  */
 export function indexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -30,9 +50,18 @@ export function indexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get the index of the first item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => 1
+ * ```
  */
 export function indexOf<Item>(
 	array: Item[],
@@ -41,9 +70,15 @@ export function indexOf<Item>(
 
 /**
  * Get the index of the first item matching the given item
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Index of the first matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * indexOf([1, 2, 3, 4, 5], 3); // => 2
+ * ```
  */
 export function indexOf<Item>(array: Item[], item: Item): number;
 
@@ -57,10 +92,20 @@ indexOf.last = lastIndexOf;
  * Get the index of the last matching item by callback
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value
  * @param value Value to match against
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   item => item.id,
+ *   2,
+ * ); // => 3
+ * ```
  */
 export function lastIndexOf<
 	Item,
@@ -71,10 +116,20 @@ export function lastIndexOf<
  * Get the index of the last matching item by key
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param key Key to match items by
  * @param value Value to match against
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   'id',
+ *   2,
+ * ); // => 3
+ * ```
  */
 export function lastIndexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -86,9 +141,18 @@ export function lastIndexOf<Item extends PlainObject, ItemKey extends keyof Item
  * Get the index of the last item matching the filter
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf(
+ *   [{id: 1}, {id: 2}, {id: 3}, {id: 2}],
+ *   item => item.id === 2,
+ * ); // => 3
+ * ```
  */
 export function lastIndexOf<Item>(
 	array: Item[],
@@ -99,9 +163,15 @@ export function lastIndexOf<Item>(
  * Get the index of the last item matching the given item
  *
  * Available as `lastIndexOf` and `indexOf.last`
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Index of the last matching item, or `-1` if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastIndexOf([1, 2, 3, 2, 1], 2); // => 3
+ * ```
  */
 export function lastIndexOf<Item>(array: Item[], item: Item): number;
 

package/src/internal/math/aggregate.ts

@@ -66,6 +66,17 @@ export function getAggregateCallback(key: unknown): Function | undefined {
 
 /**
  * Get the maximum value from a list of items
+ *
+ * @example
+ * ```typescript
+ * max(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}],
+ *   item => item.value,
+ * ); // 20
+ *
+ * max([], item => item.value); // Number.NaN
+ * ```
+ *
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Maximum value, or `NaN` if no maximum can be found
@@ -77,6 +88,17 @@ export function max<Item>(
 
 /**
  * Get the maximum value from a list of items
+ *
+ * @example
+ * ```typescript
+ * max(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}],
+ *   'value',
+ * ); // 20
+ *
+ * max([], 'value'); // Number.NaN
+ * ```
+ *
  * @param items List of items
  * @param key Key to use for value
  * @returns Maximum value, or `NaN` if no maximum can be found
@@ -88,6 +110,13 @@ export function max<Item extends PlainObject, ItemKey extends keyof NumericalVal
 
 /**
  * Get the maximum value from a list of numbers
+ *
+ * @example
+ * ```typescript
+ * max([10, 20]); // 20
+ * max([]);       // Number.NaN
+ * ```
+ *
  * @param values List of numbers
  * @returns Maximum value, or `NaN` if no maximum can be found
  */

package/src/internal/string.ts

@@ -19,11 +19,9 @@ export function getString(value: unknown): string {
 	}
 
 	if (typeof value !== 'object') {
-		// oxlint-disable-next-line typescript/no-base-to-string: the whole point of this function is to get a string representation of any value, so calling `String` on it is fine
 		return String(value);
 	}
 
-	// oxlint-disable-next-line typescript/no-base-to-string: ditto
 	const asString = String(value.valueOf?.() ?? value);
 
 	return asString.startsWith('[object ') ? JSON.stringify(value) : asString;

package/src/internal/value/compare.ts

@@ -45,6 +45,7 @@ export function compare(first: unknown, second: unknown): number {
 	const firstParts = getComparisonParts(first);
 	const secondParts = getComparisonParts(second);
 	const length = max([firstParts.length, secondParts.length]);
+
 	const lastIndex = length - 1;
 
 	for (let index = 0; index < length; index += 1) {
@@ -147,7 +148,7 @@ function getComparisonParts(value: unknown): unknown[] {
  */
 export function registerComparator<Instance>(
 	constructor: Constructor<Instance>,
-	handler?: string | ((first: Instance, second: Instance) => number),
+	handler?: string | Comparator<Instance>,
 ): void {
 	compare.handlers.register(constructor, handler);
 }