@oscarpalmer/atoms 0.184.1 → 0.185.0

package/src/array/{position.ts → match.ts}

@@ -1,9 +1,12 @@
-// #region Types
-
 import {getArrayCallback} from '../internal/array/callbacks';
 import type {PlainObject} from '../models';
 
-export type ArrayPosition = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
+// #region Types
+
+/**
+ * Comparison of an array within another array
+ */
+export type ArrayComparison = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
 
 // #endregion
 
@@ -54,11 +57,11 @@ export function endsWithArray(haystack: unknown[], needle: unknown[], key?: unkn
  * @param key Key to get an item's value for matching
  * @returns Position of the needle within the haystack
  */
-export function getArrayPosition<Item extends PlainObject>(
+export function getArrayComparison<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
 	key: keyof Item,
-): ArrayPosition;
+): ArrayComparison;
 
 /**
  * Get the position of an array within another array
@@ -67,11 +70,11 @@ export function getArrayPosition<Item extends PlainObject>(
  * @param callback Callback to get an item's value for matching
  * @returns Position of the needle within the haystack
  */
-export function getArrayPosition<Item>(
+export function getArrayComparison<Item>(
 	haystack: Item[],
 	needle: Item[],
 	callback: (item: Item, index: number, array: Item[]) => unknown,
-): ArrayPosition;
+): ArrayComparison;
 
 /**
  * Get the position of an array within another array
@@ -79,29 +82,29 @@ export function getArrayPosition<Item>(
  * @param needle Needle array
  * @returns Position of the needle within the haystack
  */
-export function getArrayPosition<Item>(haystack: Item[], needle: Item[]): ArrayPosition;
+export function getArrayComparison<Item>(haystack: Item[], needle: Item[]): ArrayComparison;
 
-export function getArrayPosition(
+export function getArrayComparison(
 	haystack: unknown[],
 	needle: unknown[],
 	key?: unknown,
-): ArrayPosition {
+): ArrayComparison {
 	return getPosition(haystack, needle, key)[1];
 }
 
-function getName(start: number, haystack: number, needle: number): ArrayPosition {
+function getName(start: number, haystack: number, needle: number): ArrayComparison {
 	if (start === 0) {
-		return haystack === needle ? POSITION_SAME : POSITION_START;
+		return haystack === needle ? COMPARISON_SAME : COMPARISON_START;
 	}
 
-	return start + needle === haystack ? POSITION_END : POSITION_INSIDE;
+	return start + needle === haystack ? COMPARISON_END : COMPARISON_INSIDE;
 }
 
 function getPosition(
 	haystack: unknown[],
 	needle: unknown[],
 	key?: unknown,
-): readonly [number, ArrayPosition] {
+): readonly [number, ArrayComparison] {
 	if (!Array.isArray(haystack) || !Array.isArray(needle)) {
 		return invalid;
 	}
@@ -278,26 +281,26 @@ export function startsWithArray(haystack: unknown[], needle: unknown[], key?: un
 
 // #region Variables
 
-const POSITION_END: ArrayPosition = 'end';
+const COMPARISON_END: ArrayComparison = 'end';
 
-const POSITION_INSIDE: ArrayPosition = 'inside';
+const COMPARISON_INSIDE: ArrayComparison = 'inside';
 
-const POSITION_INVALID: ArrayPosition = 'invalid';
+const COMPARISON_INVALID: ArrayComparison = 'invalid';
 
-const POSITION_OUTSIDE: ArrayPosition = 'outside';
+const COMPARISON_OUTSIDE: ArrayComparison = 'outside';
 
-const POSITION_SAME: ArrayPosition = 'same';
+const COMPARISON_SAME: ArrayComparison = 'same';
 
-const POSITION_START: ArrayPosition = 'start';
+const COMPARISON_START: ArrayComparison = 'start';
 
-const endings = new Set<ArrayPosition>([POSITION_END, POSITION_SAME]);
+const endings = new Set<ArrayComparison>([COMPARISON_END, COMPARISON_SAME]);
 
-const invalid = [-1, POSITION_INVALID] as const;
+const invalid = [-1, COMPARISON_INVALID] as const;
 
-const outside = [-1, POSITION_OUTSIDE] as const;
+const outside = [-1, COMPARISON_OUTSIDE] as const;
 
-const outsides = new Set<ArrayPosition>([POSITION_INVALID, POSITION_OUTSIDE]);
+const outsides = new Set<ArrayComparison>([COMPARISON_INVALID, COMPARISON_OUTSIDE]);
 
-const starts = new Set<ArrayPosition>([POSITION_START, POSITION_SAME]);
+const starts = new Set<ArrayComparison>([COMPARISON_START, COMPARISON_SAME]);
 
 // #endregion

package/src/array/move.ts

@@ -1,6 +1,8 @@
 import {arraysOverlap} from '../internal/array/overlap';
 import type {PlainObject} from '../models';
-import {indexOfArray} from './position';
+import {indexOfArray} from './match';
+
+// #region Functions
 
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
@@ -239,3 +241,5 @@ export function moveToIndex(
 
 	return array;
 }
+
+// #endregion

package/src/array/reverse.ts

@@ -1,3 +1,5 @@
+// #region Functions
+
 /**
  * Reverse the order of items in an array
  * @param array Array to reverse
@@ -26,3 +28,5 @@ export function reverse<Item>(array: Item[]): Item[] {
 
 	return array;
 }
+
+// #endregion Functions

package/src/array/select.ts

@@ -1,6 +1,8 @@
 import {FIND_VALUES_ALL, findValues} from '../internal/array/find';
 import type {PlainObject} from '../models';
 
+// #region Functions
+
 /**
  * Get a filtered and mapped array of items
  * @param array Array to search in

package/src/array/single.ts

@@ -49,7 +49,7 @@ export function single(array: unknown[], ...parameters: unknown[]): unknown {
 	const {matched} = findValues(FIND_VALUES_ALL, array, parameters);
 
 	if (matched.length > 1) {
-		throw new Error(MESSAGE);
+		throw new Error(SINGLE_MESSAGE);
 	}
 
 	return matched[0];
@@ -59,6 +59,6 @@ export function single(array: unknown[], ...parameters: unknown[]): unknown {
 
 // #region Variables
 
-const MESSAGE = 'Multiple items were found';
+const SINGLE_MESSAGE = 'Multiple items were found';
 
 // #endregion

package/src/array/sort.ts

@@ -104,6 +104,11 @@ type InternalSorterCompare = {
  */
 export type SortDirection = 'ascending' | 'descending';
 
+/**
+ * Sorter for an array with predefined sorters
+ *
+ * Can be used to sort an array, get the predicted index for an item, and check if an array is sorted
+ */
 export type Sorter<Item> = {
 	/**
 	 * Sort an array of items
@@ -245,7 +250,7 @@ function getObjectSorter(obj: PlainObject, modifier: number): InternalSorter | u
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.index`
+ * Available as `getSortedIndex` and `sort.getIndex`
  * @param array Array to get the index from
  * @param item Item to get the index for
  * @param sorters Sorters to use to determine sorting
@@ -264,7 +269,7 @@ export function getSortedIndex<Item>(
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.index`
+ * Available as `getSortedIndex` and `sort.getIndex`
  * @param array Array to get the index from
  * @param item Item to get the index for
  * @param sorter Sorter to use to determine sorting
@@ -283,7 +288,7 @@ export function getSortedIndex<Item>(
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.index`
+ * Available as `getSortedIndex` and `sort.getIndex`
  * @param array Array to get the index from
  * @param item Item to get the index for
  * @param descending Sorted in descending order? _(defaults to `false`)_
@@ -458,9 +463,9 @@ function isSortedArray(array: unknown[], sorters: InternalSorter[]): boolean {
 
 	let offset = 0;
 
-	if (length >= ARRAY_THRESHOLD) {
-		offset = Math.round(length / ARRAY_PEEK_PERCENTAGE);
-		offset = offset > ARRAY_THRESHOLD ? ARRAY_THRESHOLD : offset;
+	if (length >= SORT_THRESHOLD) {
+		offset = Math.round(length / SORT_PEEK_PERCENTAGE);
+		offset = offset > SORT_THRESHOLD ? SORT_THRESHOLD : offset;
 
 		for (let index = 0; index < offset; index += 1) {
 			const [firstItem, firstOffset] = [array[index], array[index + 1]];
@@ -552,7 +557,7 @@ function sortArray(array: unknown[], sorters: InternalSorter[]): unknown[] {
 		: array;
 }
 
-sort.index = getSortedIndex;
+sort.getIndex = getSortedIndex;
 sort.initialize = initializeSorter;
 sort.is = isSorted;
 
@@ -560,9 +565,9 @@ sort.is = isSorted;
 
 // #region Variables
 
-const ARRAY_PEEK_PERCENTAGE = 10;
+const SORT_PEEK_PERCENTAGE = 10;
 
-const ARRAY_THRESHOLD = 100;
+const SORT_THRESHOLD = 100;
 
 export const SORT_DIRECTION_ASCENDING: SortDirection = 'ascending';
 

package/src/array/swap.ts

@@ -2,7 +2,9 @@ import {getArrayCallback} from '../internal/array/callbacks';
 import {indexOf} from '../internal/array/index-of';
 import {arraysOverlap} from '../internal/array/overlap';
 import type {PlainObject} from '../models';
-import {indexOfArray} from './position';
+import {indexOfArray} from './match';
+
+// #region Functions
 
 /**
  * Swap two smaller arrays within a larger array
@@ -211,3 +213,5 @@ function swapValues(array: unknown[], from: unknown, to: unknown, key?: unknown)
 
 	return swapIndices(array, first, second);
 }
+
+// #endregion

package/src/array/toggle.ts

@@ -1,6 +1,8 @@
 import {updateInArray} from '../internal/array/update';
 import type {PlainObject} from '../models';
 
+// #region Functions
+
 /**
  * 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
@@ -38,3 +40,5 @@ export function toggle<Item>(destination: Item[], toggled: Item[]): Item[];
 export function toggle(array: unknown[], values: unknown[], key?: unknown): unknown[] {
 	return updateInArray(array, values, key, false);
 }
+
+// #endregion

package/src/array/union.ts

@@ -1,5 +1,7 @@
 import {COMPARE_SETS_UNION, compareSets} from '../internal/array/sets';
 
+// #region Functions
+
 /**
  * Get the combined, unique values from two arrays
  * @param first First array
@@ -37,3 +39,5 @@ export function union<First, Second>(first: First[], second: Second[]): (First |
 export function union(first: unknown[], second: unknown[], key?: unknown): unknown[] {
 	return compareSets(COMPARE_SETS_UNION, first, second, key);
 }
+
+// #endregion

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

@@ -1,12 +1,20 @@
 import {SPACE_HSL, SPACE_RGB} from './constants';
 import {formatColor} from './misc';
 import {getAlpha} from './misc/alpha';
-import {getState, setHexColor, setHSLColor, setRGBColor} from './misc/state';
+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;
@@ -118,7 +126,7 @@ export class Color {
 	}
 
 	constructor(value: unknown) {
-		this.#state = getState(value);
+		this.#state = getColorState(value);
 
 		Object.defineProperty(this, '$color', {
 			value: true,

package/src/color/misc/get.ts

@@ -17,7 +17,7 @@ import {
 } from '../constants';
 import {Color} from '../instance';
 import type {HSLAColor, HSLColor, RGBAColor, RGBColor} from '../models';
-import {getState} from './state';
+import {getColorState} from './state';
 
 // #region Functions
 
@@ -31,7 +31,7 @@ function getClampedValue(value: unknown, minimum: number, maximum: number): numb
  * @returns Foreground color
  */
 export function getForegroundColor(value: unknown): Color {
-	const state = getState(value);
+	const state = getColorState(value);
 	const {blue, green, red} = state.rgb;
 
 	const values = [blue / MAX_HEX, green / MAX_HEX, red / MAX_HEX];
@@ -63,7 +63,7 @@ export function getForegroundColor(value: unknown): Color {
  * @returns Hex color
  */
 export function getHexaColor(value: unknown): string {
-	const {alpha, hex} = getState(value);
+	const {alpha, hex} = getColorState(value);
 
 	return `${hex}${alpha.hex}`;
 }
@@ -74,7 +74,7 @@ export function getHexaColor(value: unknown): string {
  * @returns Hex color
  */
 export function getHexColor(value: unknown): string {
-	return getState(value).hex;
+	return getColorState(value).hex;
 }
 
 export function getHexValue(value: unknown): number {
@@ -91,7 +91,7 @@ export function getDegrees(value: unknown): number {
  * @returns HSLA color
  */
 export function getHslaColor(value: unknown): HSLAColor {
-	const {alpha, hsl} = getState(value);
+	const {alpha, hsl} = getColorState(value);
 
 	return {
 		...hsl,
@@ -105,7 +105,7 @@ export function getHslaColor(value: unknown): HSLAColor {
  * @returns HSL color
  */
 export function getHslColor(value: unknown): HSLColor {
-	return getState(value).hsl;
+	return getColorState(value).hsl;
 }
 
 export function getPercentage(value: unknown): number {
@@ -118,7 +118,7 @@ export function getPercentage(value: unknown): number {
  * @returns RGBA color
  */
 export function getRgbaColor(value: unknown): RGBAColor {
-	const {alpha, rgb} = getState(value);
+	const {alpha, rgb} = getColorState(value);
 
 	return {
 		...rgb,
@@ -132,7 +132,7 @@ export function getRgbaColor(value: unknown): RGBAColor {
  * @returns RGB color
  */
 export function getRgbColor(value: unknown): RGBColor {
-	return getState(value).rgb;
+	return getColorState(value).rgb;
 }
 
 // #endregion

package/src/color/misc/state.ts

@@ -17,7 +17,7 @@ import {isColor, isHexColor, isHslLike, isRgbLike} from './is';
 
 // #region Functions
 
-export function getState(value: unknown): ColorState {
+export function getColorState(value: unknown): ColorState {
 	if (typeof value === 'string') {
 		const normalized = getNormalizedHex(value, true);
 		const hex = normalized.slice(0, LENGTH_LONG);

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>;