@oscarpalmer/atoms 0.184.1 → 0.185.0

package/src/function/once.ts

@@ -39,7 +39,7 @@ type OnceState<Value> = {
 export function asyncOnce<Callback extends GenericAsyncCallback>(
 	callback: Callback,
 ): OnceAsyncCallback<Callback> {
-	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);
+	assert(() => typeof callback === 'function', ONCE_MESSAGE_EXPECTATION);
 
 	const state: OnceAsyncState<Awaited<ReturnType<Callback>>> = {
 		called: false,
@@ -52,7 +52,7 @@ export function asyncOnce<Callback extends GenericAsyncCallback>(
 
 	const fn = (...parameters: Parameters<Callback>): Promise<Awaited<ReturnType<Callback>>> => {
 		if (state.cleared) {
-			return Promise.reject(new Error(MESSAGE_CLEARED));
+			return Promise.reject(new Error(ONCE_MESSAGE_CLEARED));
 		}
 
 		if (state.finished) {
@@ -72,10 +72,10 @@ export function asyncOnce<Callback extends GenericAsyncCallback>(
 
 			void callback(...parameters)
 				.then(value => {
-					handleResult(state, value, false);
+					handleOnceResult(state, value, false);
 				})
 				.catch(error => {
-					handleResult(state, error, true);
+					handleOnceResult(state, error, true);
 				});
 		});
 	};
@@ -107,7 +107,11 @@ export function asyncOnce<Callback extends GenericAsyncCallback>(
 	return fn as OnceAsyncCallback<Callback>;
 }
 
-function handleResult<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;
@@ -132,7 +136,7 @@ function handleResult<Value>(state: OnceAsyncState<Value>, value: unknown, error
  * @returns Once callback
  */
 export function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback> {
-	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);
+	assert(() => typeof callback === 'function', ONCE_MESSAGE_EXPECTATION);
 
 	const state: OnceState<ReturnType<Callback>> = {
 		called: false,
@@ -142,7 +146,7 @@ export function once<Callback extends GenericCallback>(callback: Callback): Once
 
 	const fn = (...parameters: Parameters<Callback>): ReturnType<Callback> => {
 		if (state.cleared) {
-			throw new Error(MESSAGE_CLEARED);
+			throw new Error(ONCE_MESSAGE_CLEARED);
 		}
 
 		if (state.called) {
@@ -183,8 +187,8 @@ once.async = asyncOnce;
 
 // #region Variables
 
-const MESSAGE_CLEARED = 'Once has been cleared';
+const ONCE_MESSAGE_CLEARED = 'Once has been cleared';
 
-const MESSAGE_EXPECTATION = 'Once expected a function';
+const ONCE_MESSAGE_EXPECTATION = 'Once expected a function';
 
 // #endregion

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,
@@ -11,7 +14,7 @@ export class RetryError extends Error {
 	) {
 		super(message);
 
-		this.name = ERROR_NAME;
+		this.name = RETRY_ERROR_NAME;
 	}
 }
 
@@ -64,7 +67,7 @@ async function asyncRetry<Callback extends GenericCallback>(
 	options?: RetryOptions,
 ): Promise<ReturnType<Callback>> {
 	if (typeof callback !== 'function') {
-		throw new TypeError(MESSAGE_EXPECTATION);
+		throw new TypeError(RETRY_MESSAGE_EXPECTATION);
 	}
 
 	async function handle(): Promise<void> {
@@ -74,7 +77,7 @@ async function asyncRetry<Callback extends GenericCallback>(
 			resolver(result);
 		} catch (error) {
 			if (attempts >= times || !when(error)) {
-				rejector(new RetryError(MESSAGE_FAILED, error));
+				rejector(new RetryError(RETRY_MESSAGE_FAILED, error));
 			} else {
 				attempts += 1;
 
@@ -125,7 +128,7 @@ export function retry<Callback extends GenericCallback>(
 	options?: Omit<RetryOptions, 'delay'>,
 ): ReturnType<Callback> {
 	if (typeof callback !== 'function') {
-		throw new TypeError(MESSAGE_EXPECTATION);
+		throw new TypeError(RETRY_MESSAGE_EXPECTATION);
 	}
 
 	const {times, when} = getRetryOptions(options);
@@ -146,7 +149,7 @@ export function retry<Callback extends GenericCallback>(
 		}
 	}
 
-	throw new RetryError(MESSAGE_FAILED, last);
+	throw new RetryError(RETRY_MESSAGE_FAILED, last);
 }
 
 retry.async = asyncRetry;
@@ -159,10 +162,10 @@ function shouldRetry(): boolean {
 
 // #region Variables
 
-const ERROR_NAME = 'RetryError';
+const RETRY_ERROR_NAME = 'RetryError';
 
-const MESSAGE_EXPECTATION = 'Retry expected a function';
+const RETRY_MESSAGE_EXPECTATION = 'Retry expected a function';
 
-const MESSAGE_FAILED = 'Retry failed';
+const RETRY_MESSAGE_FAILED = 'Retry failed';
 
 // #endregion

package/src/internal/number.ts

@@ -97,6 +97,12 @@ export function getNumber(value: unknown): number {
 	return Number(trimmed);
 }
 
+export function getNumberOrDefault(value: unknown, defaultValue: number, minimum?: number): number {
+	return typeof value === 'number' && !Number.isNaN(value) && value >= (minimum ?? 0)
+		? Math.floor(value)
+		: defaultValue;
+}
+
 // #endregion
 
 // #region Variables

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?
@@ -141,9 +146,9 @@ function equalArray(first: unknown[], second: unknown[], options: Options): bool
 
 	let offset = 0;
 
-	if (length >= ARRAY_THRESHOLD) {
-		offset = Math.round(length / ARRAY_PEEK_PERCENTAGE);
-		offset = offset > ARRAY_THRESHOLD ? ARRAY_THRESHOLD : offset;
+	if (length >= EQUAL_ARRAY_THRESHOLD) {
+		offset = Math.round(length / EQUAL_ARRAY_PEEK_PERCENTAGE);
+		offset = offset > EQUAL_ARRAY_THRESHOLD ? EQUAL_ARRAY_THRESHOLD : offset;
 
 		for (let index = 0; index < offset; index += 1) {
 			if (
@@ -438,9 +443,9 @@ export function registerEqualizer<Instance>(
 
 // #region Variables
 
-const ARRAY_PEEK_PERCENTAGE = 10;
+const EQUAL_ARRAY_PEEK_PERCENTAGE = 10;
 
-const ARRAY_THRESHOLD = 100;
+const EQUAL_ARRAY_THRESHOLD = 100;
 
 const ERROR_PROPERTIES: string[] = ['name', 'message'];
 

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/models.ts

@@ -19,7 +19,7 @@ export type AsyncCancelableCallback<Callback extends GenericAsyncCallback | Gene
 	};
 
 /**
- * For mathicng any `void`, `Date`, primitive, or `RegExp` values
+ * For matching any `void`, `Date`, primitive, or `RegExp` values
  *
  * (Thanks, type-fest!)
  */

package/src/promise/helpers.ts

@@ -1,3 +1,4 @@
+import {getNumberOrDefault} from '../internal/number';
 import type {RequiredKeys} from '../models';
 import {error, ok} from '../result/misc';
 import type {Result} from '../result/models';
@@ -16,14 +17,10 @@ import {
 
 // #region Functions
 
-function getNumberOrDefault(value: unknown): number {
-	return typeof value === 'number' && value > 0 ? value : 0;
-}
-
 export function getPromiseOptions(input: unknown): RequiredKeys<PromiseOptions, 'time'> {
 	if (typeof input === 'number') {
 		return {
-			time: getNumberOrDefault(input),
+			time: getNumberOrDefault(input, 0),
 		};
 	}
 
@@ -35,7 +32,7 @@ export function getPromiseOptions(input: unknown): RequiredKeys<PromiseOptions,
 
 	return {
 		signal: options.signal instanceof AbortSignal ? options.signal : undefined,
-		time: getNumberOrDefault(options.time),
+		time: getNumberOrDefault(options.time, 0),
 	};
 }
 

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

@@ -1,9 +1,13 @@
+import {getNumberOrDefault} from './internal/number';
 import type {GenericAsyncCallback, GenericCallback} from './models';
 
 // #region Types
 
 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;
 
@@ -239,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;
 
@@ -471,13 +478,13 @@ class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, Callbac
 				const paused = item;
 
 				this.#handled.push(() => {
-					handleResult(paused, error, result, this.#items.length === 0);
+					handleQueuedResult(paused, error, result, this.#items.length === 0);
 				});
 
 				break;
 			}
 
-			handleResult(item, error, result, this.#items.length === 0);
+			handleQueuedResult(item, error, result, this.#items.length === 0);
 
 			item = this.#items.shift();
 		}
@@ -486,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);
@@ -509,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;
 	/**
@@ -554,21 +567,20 @@ function getBooleanOrDefault(value: unknown, defaultValue: boolean): boolean {
 	return typeof value === 'boolean' ? value : defaultValue;
 }
 
-function getNumberOrDefault(value: unknown, defaultValue: number): number {
-	return typeof value === 'number' && value > 0 ? Math.floor(value) : defaultValue;
-}
-
 function getOptions(input?: QueueOptions): Required<QueueOptions> {
 	const options = typeof input === 'object' && input != null ? input : {};
 
 	return {
 		autostart: getBooleanOrDefault(options.autostart, true),
-		concurrency: getNumberOrDefault(options.concurrency, 1),
+		concurrency: getNumberOrDefault(options.concurrency, 1, 1),
 		maximum: getNumberOrDefault(options.maximum, 0),
 	};
 }
 
-function handleResult<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult>(
+function handleQueuedResult<
+	CallbackParameters extends Parameters<GenericAsyncCallback>,
+	CallbackResult,
+>(
 	item: QueuedItem<CallbackParameters, CallbackResult>,
 	error: boolean,
 	result: unknown,
@@ -676,11 +688,11 @@ const STATUS_PAUSED: StatusKey = 'paused';
 
 export {
 	type KeyedQueue,
-	type QueueError,
 	type Queue,
 	type Queued,
-	type QueueOptions,
 	type QueuedResult,
+	type QueueError,
+	type QueueOptions,
 };
 
 // #endregion

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