@oscarpalmer/atoms 0.184.2 → 0.185.0

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/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);
 }

package/src/internal/value/equal.ts

@@ -22,6 +22,11 @@ export type EqualOptions = {
 	relaxedNullish?: boolean;
 };
 
+/**
+ * An equalizer function for comparing values for equality, with predefined options
+ *
+ * Can be used to compare values, and register or deregister equality comparison handlers for specific classes
+ */
 type Equalizer = {
 	/**
 	 * Are two strings equal?

package/src/internal/value/get.ts

@@ -1,4 +1,4 @@
-import type {NestedKeys, NestedValue, PlainObject, ToString} from '../../models';
+import type {NestedKeys, NestedValue, PlainObject} from '../../models';
 import type {Ok} from '../../result/models';
 import {getNestedValue} from './misc';
 
@@ -13,7 +13,7 @@ import {getNestedValue} from './misc';
 export function getValue<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
 	path: Path,
-): NestedValue<Data, ToString<Path>>;
+): NestedValue<Data, Path>;
 
 /**
  * Get the value from an object using an unknown path

package/src/internal/value/has.ts

@@ -43,11 +43,11 @@ hasValue.get = hasValueResult;
  * @param ignoreCase If `true`, the path matching is case-insensitive
  * @return Result object
  */
-function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>(
+export function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>(
 	data: Data,
 	path: Path,
 	ignoreCase?: boolean,
-): Result<NestedValue<Data, ToString<Path>>, undefined>;
+): Result<NestedValue<Data, ToString<Path>>, string>;
 
 /**
  * Check if a nested property is defined in an object, and get its value if it is
@@ -58,17 +58,17 @@ function hasValueResult<Data extends PlainObject, Path extends NestedKeys<Data>>
  * @param ignoreCase If `true`, the path matching is case-insensitive
  * @return Result object
  */
-function hasValueResult<Data extends PlainObject>(
+export function hasValueResult<Data extends PlainObject>(
 	data: Data,
 	path: string,
 	ignoreCase?: boolean,
-): Result<unknown, undefined>;
+): Result<unknown, string>;
 
-function hasValueResult(
+export function hasValueResult(
 	data: PlainObject,
 	path: string,
 	ignoreCase?: boolean,
-): Result<unknown, undefined> {
+): Result<unknown, string> {
 	return getNestedValue(data, path, ignoreCase === true);
 }
 

package/src/internal/value/misc.ts

@@ -17,14 +17,13 @@ export function getNestedValue(
 	data: object,
 	path: string,
 	ignoreCase: boolean,
-): Result<unknown, undefined> {
-	if (
-		typeof data !== 'object' ||
-		data === null ||
-		typeof path !== 'string' ||
-		path.trim().length === 0
-	) {
-		return error(undefined);
+): Result<unknown, string> {
+	if (typeof data !== 'object' || data === null) {
+		return error(NESTED_MESSAGE_INPUT);
+	}
+
+	if (typeof path !== 'string' || path.trim().length === 0) {
+		return error(NESTED_MESSAGE_PATH);
 	}
 
 	const shouldIgnoreCase = ignoreCase === true;
@@ -69,7 +68,7 @@ export function handleValue(
 	value: unknown,
 	get: true,
 	ignoreCase: boolean,
-): Result<unknown, undefined>;
+): Result<unknown, string>;
 
 export function handleValue(
 	data: object,
@@ -85,19 +84,23 @@ export function handleValue(
 	value: unknown,
 	get: boolean,
 	ignoreCase: boolean,
-): Result<unknown, undefined> | void {
-	if (typeof data === 'object' && data !== null && !ignoreKey(path)) {
+): Result<unknown, string> | void {
+	if (typeof data === 'object' && data !== null) {
+		if (ignoreKey(path)) {
+			return error(NESTED_MESSAGE_UNSAFE);
+		}
+
 		const key = ignoreCase ? findKey(path, data) : path;
 
 		if (get) {
-			return key in data ? ok(data[key as never]) : error(undefined);
+			return key in data ? ok(data[key as never]) : error(NESTED_MESSAGE_MISSING);
 		}
 
 		(data as PlainObject)[key] = typeof value === 'function' ? value(data[key as never]) : value;
 	}
 
 	if (get) {
-		return error(undefined);
+		return error(NESTED_MESSAGE_MISSING);
 	}
 }
 
@@ -111,4 +114,12 @@ const EXPRESSION_DOTS = /^\.|\.$/g;
 
 const EXPRESSION_NESTED = /\.|\[\w+\]/;
 
+const NESTED_MESSAGE_INPUT = 'Expected data to be an object';
+
+const NESTED_MESSAGE_MISSING = 'Expected property to exist in object';
+
+const NESTED_MESSAGE_PATH = 'Expected path to be a string';
+
+const NESTED_MESSAGE_UNSAFE = 'Access to this property is not allowed';
+
 // #endregion

package/src/logger.ts

@@ -2,6 +2,11 @@ import {noop} from './internal/function/misc';
 
 // #region Types
 
+/**
+ * A logger that can be used to log messages to the console
+ *
+ * _(Logging can be enabled or disabled by setting the `enabled` property)_
+ */
 class Logger {
 	/**
 	 * Log any number of values at the "debug" log level
@@ -83,12 +88,18 @@ class Logger {
 	}
 }
 
+/**
+ * A named timer that can be used to log durations to the console
+ */
 class Time {
 	#logger: typeof console.timeLog | undefined;
 	#stopper: typeof console.timeEnd | undefined;
 
 	readonly #state: TimeState;
 
+	/**
+	 * Is the timer active? _(i.e. has it been started and not stopped, and is logging enabled?)_
+	 */
 	get active(): boolean {
 		return this.#state.started && !this.#state.stopped && enabled;
 	}

package/src/promise/index.ts

@@ -24,8 +24,6 @@ import {getTimedPromise} from './timed';
 
 /**
  * Wrap a promise with safety handlers, with optional abort capabilities and timeout
- *
- * Available as `attemptPromise` and `attempt.promise`
  * @param promise Promise to wrap
  * @param options Options for the promise
  * @returns Wrapped promise
@@ -37,8 +35,6 @@ export async function attemptPromise<Value>(
 
 /**
  * Wrap a promise-returning callback with safety handlers, with optional abort capabilities and timeout
- *
- * Available as `attemptPromise` and `attempt.promise`
  * @param callback Callback to wrap
  * @param options Options for the promise
  * @returns Promise-wrapped callback
@@ -50,8 +46,6 @@ export async function attemptPromise<Value>(
 
 /**
  * Wrap a callback with a promise and safety handlers, with optional abort capabilities and timeout
- *
- * Available as `attemptPromise` and `attempt.promise`
  * @param callback Callback to wrap
  * @param options Options for the promise
  * @returns Promise-wrapped callback

package/src/promise/models.ts

@@ -3,6 +3,9 @@ import type {Result} from '../result/models';
 
 // #region Types
 
+/**
+ * A promise that can be canceled
+ */
 export class CancelablePromise<Value = void> extends Promise<Value> {
 	#rejector!: (reason: unknown) => void;
 
@@ -29,8 +32,17 @@ export class CancelablePromise<Value = void> extends Promise<Value> {
 	}
 }
 
+/**
+ * A promise that was fulfilled
+ */
 export type FulfilledPromise<Value> = {
+	/**
+	 * Status of the promise
+	 */
 	status: typeof PROMISE_TYPE_FULFILLED;
+	/**
+	 * Value of the promise
+	 */
 	value: Awaited<Value>;
 };
 
@@ -44,6 +56,9 @@ export type PromiseHandlers = {
 	reject: (reason: unknown) => void;
 };
 
+/**
+ * Options for a promise-handling function
+ */
 export type PromiseOptions = {
 	/**
 	 * AbortSignal for aborting the promise; when aborted, the promise will reject with the reason of the signal
@@ -75,6 +90,9 @@ export type PromiseParameters = {
  */
 export type PromiseStrategy = 'complete' | 'first';
 
+/**
+ * An error thrown when a promise times out
+ */
 export class PromiseTimeoutError extends Error {
 	constructor() {
 		super(PROMISE_MESSAGE_TIMEOUT);
@@ -93,8 +111,17 @@ export type PromisesItems<Items extends unknown[]> = {
 			: Promise<Items[ItemsKey]>;
 };
 
+/**
+ * Options for handling multiple promises
+ */
 export type PromisesOptions = {
+	/**
+	 * AbortSignal for aborting the promises; when aborted, the promises will reject with the reason of the signal
+	 */
 	signal?: AbortSignal;
+	/**
+	 * Strategy for handling the promises; defaults to `complete`
+	 */
 	strategy?: PromiseStrategy;
 };
 
@@ -126,8 +153,17 @@ export type PromisesValues<Items extends unknown[]> = {
 			: never;
 };
 
+/**
+ * A promise that was rejected
+ */
 export type RejectedPromise = {
+	/**
+	 * Status of the promise
+	 */
 	status: typeof PROMISE_TYPE_REJECTED;
+	/**
+	 * Reason for the rejection
+	 */
 	reason: unknown;
 };
 

package/src/queue.ts

@@ -5,6 +5,9 @@ import type {GenericAsyncCallback, GenericCallback} from './models';
 
 type HandleType = 'clear' | 'pause' | 'resume';
 
+/**
+ * A queue that can be used to manage (a)synchronous tasks with a specific key
+ */
 class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
 	readonly #callback: GenericAsyncCallback;
 
@@ -240,6 +243,9 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 	}
 }
 
+/**
+ * A queue that can be used to manage (a)synchronous tasks
+ */
 class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
 	readonly #callback: GenericAsyncCallback;
 
@@ -487,6 +493,9 @@ class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, Callbac
 	}
 }
 
+/**
+ * An error thrown by the Queue when an operation fails
+ */
 class QueueError extends Error {
 	constructor(message: string) {
 		super(message);
@@ -510,9 +519,12 @@ type QueueOptions = {
 	maximum?: number;
 };
 
+/**
+ * A queued item
+ */
 type Queued<Value> = {
 	/**
-	 * ID of the queued promise _(can be used to remove it from the queue)_
+	 * ID of the queued item _(can be used to remove it from the queue)_
 	 */
 	readonly id: number;
 	/**

package/src/result/index.ts

@@ -1,9 +1,5 @@
-import {attemptPromise} from '../promise';
-import {matchResult} from './match';
 import {getError, ok} from './misc';
 import type {ExtendedErr, ExtendedResult, Result} from './models';
-import {attemptFlow} from './work/flow';
-import {attemptPipe} from './work/pipe';
 
 // #region Functions
 
@@ -99,9 +95,5 @@ export function attempt<Value, E>(
 }
 
 attempt.async = asyncAttempt;
-attempt.flow = attemptFlow;
-attempt.match = matchResult;
-attempt.pipe = attemptPipe;
-attempt.promise = attemptPromise;
 
 // #endregion

package/src/result/match.ts

@@ -5,6 +5,8 @@ import type {AnyResult, ExtendedErr, ResultMatch} from './models';
 
 /**
  * Handles a result with match callbacks
+ *
+ * Available as `asyncMatchResult` and `matchResult.async`
  * @param result Result to handle
  * @param handler Match callbacks
  */
@@ -15,6 +17,8 @@ export async function asyncMatchResult<Value, Returned, E = Error>(
 
 /**
  * Handles a result with match callbacks
+ *
+ * Available as `asyncMatchResult` and `matchResult.async`
  * @param result Result to handle
  * @param ok Ok callback
  * @param error Error callback
@@ -58,8 +62,6 @@ export async function asyncMatchResult<Value, Returned, E = Error>(
 
 /**
  * Handles a result with match callbacks
- *
- * Available as `matchResult` and `attempt.match`
  * @param result Result to handle
  * @param handler Match callbacks
  */
@@ -70,8 +72,6 @@ export function matchResult<Value, Returned, E = Error>(
 
 /**
  * Handles a result with match callbacks
- *
- * Available as `matchResult` and `attempt.match`
  * @param result Result to handle
  * @param ok Ok callback
  * @param error Error callback