@oscarpalmer/atoms 0.193.0 → 0.194.0

package/src/promise/index.ts

@@ -1,300 +0,0 @@
-import type {Result} from '../result/models';
-import {getPromiseOptions, getPromisesOptions, getResultsFromPromises} from './helpers';
-import {handleResult, settlePromise} from './misc';
-import {
-	PROMISE_ABORT_OPTIONS,
-	PROMISE_ABORT_EVENT,
-	PROMISE_MESSAGE_EXPECTATION_ATTEMPT,
-	PROMISE_STRATEGY_DEFAULT,
-	PROMISE_TYPE_FULFILLED,
-	PROMISE_TYPE_REJECTED,
-	type PromiseData,
-	type PromiseHandlers,
-	type PromiseOptions,
-	type PromisesItems,
-	type PromisesOptions,
-	type PromisesResult,
-	type PromisesValue,
-	type PromisesValues,
-	type PromisesUnwrapped,
-} from './models';
-import {getTimedPromise} from './timed';
-
-// #region Functions
-
-/**
- * Wrap a _Promise_ with safety handlers, with optional abort capabilities and timeout
- *
- * @param promise _Promise_ to wrap
- * @param options Options for the _Promise_
- * @returns Wrapped _Promise_
- */
-export async function attemptPromise<Value>(
-	promise: Promise<Value>,
-	options?: PromiseOptions | AbortSignal | number,
-): Promise<Value>;
-
-/**
- * Wrap a _Promise_-returning callback with safety handlers, with optional abort capabilities and timeout
- *
- * @param callback Callback to wrap
- * @param options Options for the _Promise_
- * @returns _Promise_-wrapped callback
- */
-export async function attemptPromise<Value>(
-	callback: () => Promise<Value>,
-	options?: PromiseOptions | AbortSignal | number,
-): Promise<Value>;
-
-/**
- * Wrap a callback with a _Promise_ and safety handlers, with optional abort capabilities and timeout
- *
- * @param callback Callback to wrap
- * @param options Options for the _Promise_
- * @returns _Promise_-wrapped callback
- */
-export async function attemptPromise<Value>(
-	callback: () => Value,
-	options?: PromiseOptions | AbortSignal | number,
-): Promise<Value>;
-
-export async function attemptPromise<Value>(
-	value: (() => Value) | Promise<Value>,
-	options?: PromiseOptions | AbortSignal | number,
-): Promise<Value> {
-	const isFunction = typeof value === 'function';
-
-	if (!isFunction && !(value instanceof Promise)) {
-		return Promise.reject(new TypeError(PROMISE_MESSAGE_EXPECTATION_ATTEMPT));
-	}
-
-	const {signal, time} = getPromiseOptions(options);
-
-	if (signal?.aborted ?? false) {
-		return Promise.reject(signal!.reason);
-	}
-
-	function abort(): void {
-		rejector(signal!.reason);
-	}
-
-	async function handler(
-		resolve: (value: Value) => void,
-		reject: (reason: unknown) => void,
-	): Promise<void> {
-		try {
-			let result = isFunction ? value() : await value;
-
-			if (result instanceof Promise) {
-				result = await result;
-			}
-
-			settlePromise(abort, resolve, result, signal);
-		} catch (error) {
-			settlePromise(abort, reject, error, signal);
-		}
-	}
-
-	let rejector: (reason: unknown) => void;
-
-	signal?.addEventListener(PROMISE_ABORT_EVENT, abort, PROMISE_ABORT_OPTIONS);
-
-	const promise = new Promise<Value>((resolve, reject) => {
-		rejector = reject;
-
-		void handler(resolve, reject);
-	});
-
-	return time > 0 ? getTimedPromise(promise, time, signal) : promise;
-}
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array
- *
- * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
- *
- * @param items List of _Promises_
- * @param options Options for handling the _Promises_
- * @returns List of results
- */
-export async function promises<Items extends unknown[], Options extends PromisesOptions>(
-	items: [...Items],
-	options?: Options,
-): Promise<
-	Options['strategy'] extends 'first'
-		? PromisesUnwrapped<Items>
-		: PromisesValues<PromisesItems<Items>>
->;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array
- *
- * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
- *
- * @param items List of _Promises_
- * @param options Options for handling the _Promises_
- * @returns List of results
- */
-export async function promises<Value, Options extends PromisesOptions>(
-	items: Promise<Value>[],
-	options?: Options,
-): Promise<Options['strategy'] extends 'first' ? Value[] : PromisesValue<Value>[]>;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array
- *
- * If any _Promise_ in the list is rejected, the whole function will reject
- *
- * @param items List of _Promises_
- * @param strategy Strategy for handling the _Promises_; rejects on the first error encountered
- * @returns List of results
- */
-export async function promises<Items extends unknown[]>(
-	items: [...Items],
-	strategy: 'first',
-): Promise<PromisesUnwrapped<Items>>;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array
- *
- * If any _Promise_ in the list is rejected, the whole function will reject
- *
- * @param items List of _Promises_
- * @param strategy Strategy for handling the _Promises_; rejects on the first error encountered
- * @returns List of results
- */
-export async function promises<Value>(items: Promise<Value>[], strategy: 'first'): Promise<Value[]>;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array of rejected and resolved results
- *
- * @param items List of _Promises_
- * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
- * @returns List of results
- */
-export async function promises<Items extends unknown[]>(
-	items: [...Items],
-	signal?: AbortSignal,
-): Promise<PromisesValues<PromisesItems<Items>>>;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array of rejected and resolved results
- *
- * @param items List of _Promises_
- * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
- * @returns List of results
- */
-export async function promises<Value>(
-	items: Array<Promise<Value> | (() => Promise<Value>)>,
-	signal?: AbortSignal,
-): Promise<PromisesValue<Value>[]>;
-
-export async function promises(items: unknown[], options?: unknown): Promise<unknown[]> {
-	const {signal, strategy} = getPromisesOptions(options);
-
-	if (signal?.aborted ?? false) {
-		return Promise.reject(signal!.reason);
-	}
-
-	if (!Array.isArray(items)) {
-		return Promise.resolve([]);
-	}
-
-	const actual = items
-		.map(item => (typeof item === 'function' ? item() : item))
-		.filter(item => item instanceof Promise);
-
-	const {length} = actual;
-
-	if (length === 0) {
-		return Promise.resolve([]);
-	}
-
-	const complete = strategy === PROMISE_STRATEGY_DEFAULT;
-
-	function abort(): void {
-		handlers.reject(signal!.reason);
-	}
-
-	signal?.addEventListener(PROMISE_ABORT_EVENT, abort, PROMISE_ABORT_OPTIONS);
-
-	const data: PromiseData = {
-		last: length - 1,
-		result: [] as unknown[],
-	};
-
-	let handlers: PromiseHandlers;
-
-	return new Promise((resolve, reject) => {
-		handlers = {reject, resolve};
-
-		for (let index = 0; index < length; index += 1) {
-			void actual[index]
-				.then(value =>
-					handleResult(PROMISE_TYPE_FULFILLED, {
-						abort,
-						complete,
-						data,
-						handlers,
-						index,
-						signal,
-						value,
-					}),
-				)
-				.catch(reason =>
-					handleResult(PROMISE_TYPE_REJECTED, {
-						abort,
-						complete,
-						data,
-						handlers,
-						index,
-						signal,
-						value: reason,
-					}),
-				);
-		}
-	});
-}
-
-promises.result = resultPromises;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array of results _({@link Result})_
- *
- * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
- *
- * _Available as `resultPromises` and `promises.result`_
- *
- * @param items List of _Promises_
- * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
- * @returns List of results
- */
-export async function resultPromises<Items extends unknown[]>(
-	items: [...Items],
-	signal?: AbortSignal,
-): Promise<PromisesResult<PromisesItems<Items>>>;
-
-/**
- * Handle a list of _Promises_, returning their results in an ordered array of results _({@link Result})_
- *
- * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
- *
- * _Available as `resultPromises` and `promises.result`_
- *
- * @param items List of _Promises_
- * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
- * @returns List of results
- */
-export async function resultPromises<Value>(
-	items: Promise<Value>[],
-	signal?: AbortSignal,
-): Promise<Result<Awaited<Value>>[]>;
-
-export async function resultPromises(
-	items: Promise<unknown>[],
-	signal?: AbortSignal,
-): Promise<Result<unknown>[]> {
-	return promises(items, signal).then(getResultsFromPromises);
-}
-
-// #endregion

package/src/promise/misc.ts

@@ -1,96 +0,0 @@
-import {error, ok} from '../result/misc';
-import type {Result} from '../result/models';
-import {
-	CancelablePromise,
-	PROMISE_ABORT_EVENT,
-	PROMISE_MESSAGE_EXPECTATION_RESULT,
-	PROMISE_TYPE_FULFILLED,
-	PROMISE_TYPE_REJECTED,
-	type PromiseParameters,
-} from './models';
-
-// #region Functions
-
-/**
- * Create a cancelable _Promise_
- *
- * @param executor Executor function for the _Promise_
- * @returns Cancelable _Promise_
- */
-export function cancelable<Value>(
-	executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void,
-): CancelablePromise<Value> {
-	return new CancelablePromise(executor);
-}
-
-export function handleResult(status: string, parameters: PromiseParameters): void {
-	const {abort, complete, data, handlers, index, signal, value} = parameters;
-
-	if (signal?.aborted ?? false) {
-		return;
-	}
-
-	if (!complete && status === PROMISE_TYPE_REJECTED) {
-		settlePromise(abort, handlers.reject, value, signal);
-
-		return;
-	}
-
-	(data.result as unknown[])[index] = !complete
-		? value
-		: status === PROMISE_TYPE_FULFILLED
-			? {status, value}
-			: {status, reason: value};
-
-	if (index === data.last) {
-		settlePromise(abort, handlers.resolve, data.result, signal);
-	}
-}
-
-export function settlePromise(
-	aborter: () => void,
-	settler: (value: any) => void,
-	value: unknown,
-	signal?: AbortSignal,
-): void {
-	signal?.removeEventListener(PROMISE_ABORT_EVENT, aborter);
-
-	settler(value);
-}
-
-/**
- * Converts a _Promise_ to a promised result
- *
- * @param callback _Promise_ callback
- * @returns Promised result
- */
-export async function toResult<Value>(callback: () => Promise<Value>): Promise<Result<Value>>;
-
-/**
- * Converts a _Promise_ to a promised result
- *
- * @param promise _Promise_ to convert
- * @returns Promised result
- */
-export async function toResult<Value>(promise: Promise<Value>): Promise<Result<Value>>;
-
-export async function toResult<Value>(
-	value: Promise<Value> | (() => Promise<Value>),
-): Promise<Result<Value>> {
-	const actual = typeof value === 'function' ? value() : value;
-
-	if (!(actual instanceof Promise)) {
-		return Promise.reject(new TypeError(PROMISE_MESSAGE_EXPECTATION_RESULT));
-	}
-
-	return actual.then(result => ok(result)).catch(reason => error(reason));
-}
-
-// #endregion
-
-// #region Exports
-
-export {toPromise as fromResult} from '../result/misc';
-export {isFulfilled, isRejected} from './helpers';
-
-// #endregion

package/src/promise/models.ts

@@ -1,195 +0,0 @@
-import type {GenericCallback} from '../models';
-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;
-
-	constructor(
-		executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void,
-	) {
-		let rejector: (reason: unknown) => void;
-
-		super((resolve, reject) => {
-			rejector = reject;
-
-			executor(resolve, reject);
-		});
-
-		this.#rejector = rejector!;
-	}
-
-	/**
-	 * Cancel the _Promise_, rejecting it with an optional reason
-	 *
-	 * @param reason Optional reason for canceling the _Promise_
-	 */
-	cancel(reason?: unknown): void {
-		this.#rejector(reason);
-	}
-}
-
-/**
- * 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>;
-};
-
-export type PromiseData = {
-	last: number;
-	result: unknown[];
-};
-
-export type PromiseHandlers = {
-	resolve: (value: unknown[]) => void;
-	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
-	 */
-	signal?: AbortSignal;
-	/**
-	 * How long to wait for _(in milliseconds; defaults to `0`)_
-	 */
-	time?: number;
-};
-
-export type PromiseParameters = {
-	abort: () => void;
-	complete: boolean;
-	data: PromiseData;
-	handlers: PromiseHandlers;
-	index: number;
-	signal?: AbortSignal;
-	value?: unknown;
-};
-
-/**
- * _Promise_ handling strategy
- *
- * - `complete`: wait for all _Promises_ to settle, then return the results, as an array of fulfilled and/or rejected results
- * - `first`: rejects on the first rejected _Promise_, and returns an array of values
- */
-export type PromiseStrategy = 'complete' | 'first';
-
-/**
- * An error thrown when a promise times out
- */
-export class PromiseTimeoutError extends Error {
-	constructor() {
-		super(PROMISE_MESSAGE_TIMEOUT);
-
-		this.name = PROMISE_ERROR_NAME;
-	}
-}
-
-export type PromisesItems<Items extends unknown[]> = {
-	[ItemsKey in keyof Items]: Items[ItemsKey] extends GenericCallback
-		? ReturnType<Items[ItemsKey]> extends Promise<infer Value>
-			? Promise<Value>
-			: never
-		: Items[ItemsKey] extends Promise<infer Value>
-			? Promise<Value>
-			: 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;
-};
-
-export type PromisesResult<Items extends unknown[]> = {
-	[ItemsKey in keyof Items]: Items[ItemsKey] extends Promise<infer Value>
-		? Result<Awaited<Value>>
-		: never;
-};
-
-export type PromisesUnwrapped<Items extends unknown[]> = {
-	[ItemsKey in keyof Items]: Items[ItemsKey] extends GenericCallback
-		? ReturnType<Items[ItemsKey]> extends Promise<infer Value>
-			? Awaited<Value>
-			: never
-		: Items[ItemsKey] extends Promise<infer Value>
-			? Awaited<Value>
-			: never;
-};
-
-export type PromisesValue<Value> = FulfilledPromise<Value> | RejectedPromise;
-
-export type PromisesValues<Items extends unknown[]> = {
-	[ItemsKey in keyof Items]: Items[ItemsKey] extends GenericCallback
-		? ReturnType<Items[ItemsKey]> extends Promise<infer Value>
-			? PromisesValue<Awaited<Value>>
-			: never
-		: Items[ItemsKey] extends Promise<infer Value>
-			? PromisesValue<Awaited<Value>>
-			: never;
-};
-
-/**
- * A _Promise_ that was rejected
- */
-export type RejectedPromise = {
-	/**
-	 * Status of the _Promise_
-	 */
-	status: typeof PROMISE_TYPE_REJECTED;
-	/**
-	 * Reason for the rejection
-	 */
-	reason: unknown;
-};
-
-// #endregion
-
-// #region Variables
-
-export const PROMISE_ABORT_EVENT = 'abort';
-
-export const PROMISE_ABORT_OPTIONS = {once: true};
-
-export const PROMISE_ERROR_NAME = 'PromiseTimeoutError';
-
-export const PROMISE_MESSAGE_EXPECTATION_ATTEMPT = 'Attempt expected a function or a promise';
-
-export const PROMISE_MESSAGE_EXPECTATION_RESULT = 'toResult expected a Promise';
-
-export const PROMISE_MESSAGE_EXPECTATION_TIMED = 'Timed function expected a Promise';
-
-export const PROMISE_MESSAGE_TIMEOUT = 'Promise timed out';
-
-export const PROMISE_STRATEGY_ALL = new Set<PromiseStrategy>(['complete', 'first']);
-
-export const PROMISE_STRATEGY_DEFAULT: PromiseStrategy = 'complete';
-
-export const PROMISE_TYPE_FULFILLED = 'fulfilled';
-
-export const PROMISE_TYPE_REJECTED = 'rejected';
-
-// #endregion

package/src/promise/timed.ts

@@ -1,91 +0,0 @@
-import {getTimer, TIMER_WAIT} from '../internal/function/timer';
-import type {RequiredKeys} from '../models';
-import {getPromiseOptions} from './helpers';
-import {settlePromise} from './misc';
-import {
-	PROMISE_ABORT_OPTIONS,
-	PROMISE_ABORT_EVENT,
-	PROMISE_MESSAGE_EXPECTATION_TIMED,
-	PromiseTimeoutError,
-	type PromiseOptions,
-} from './models';
-
-// #region Functions
-
-export async function getTimedPromise<Value>(
-	promise: Promise<Value>,
-	time: number,
-	signal?: AbortSignal,
-): Promise<Value> {
-	function abort(): void {
-		timer.cancel();
-
-		rejector(signal!.reason);
-	}
-
-	signal?.addEventListener(PROMISE_ABORT_EVENT, abort, PROMISE_ABORT_OPTIONS);
-
-	const timer = getTimer(
-		TIMER_WAIT,
-		() => {
-			settlePromise(abort, rejector, new PromiseTimeoutError(), signal);
-		},
-		time,
-	);
-
-	let rejector: (reason: unknown) => void;
-
-	return Promise.race<Value>([
-		promise,
-		new Promise((_, reject) => {
-			rejector = reject;
-
-			timer();
-		}),
-	]).then(value => {
-		timer.cancel();
-
-		rejector(undefined);
-
-		signal?.removeEventListener(PROMISE_ABORT_EVENT, abort);
-
-		return value;
-	});
-}
-
-/**
- * Create a _Promise_ that should be settled within a certain amount of time
- *
- * @param promise _Promise_ to settle
- * @param options Timed options
- * @returns Timed _Promise_
- */
-export async function timed<Value>(
-	promise: Promise<Value>,
-	options: RequiredKeys<PromiseOptions, 'time'>,
-): Promise<Value>;
-
-/**
- * Create a _Promise_ that should be settled within a certain amount of time
- *
- * @param promise _Promise_ to settle
- * @param time How long to wait for _(in milliseconds; defaults to `0`)_
- * @returns Timed _Promise_
- */
-export async function timed<Value>(promise: Promise<Value>, time: number): Promise<Value>;
-
-export async function timed<Value>(promise: Promise<Value>, options: unknown): Promise<Value> {
-	if (!(promise instanceof Promise)) {
-		return Promise.reject(new TypeError(PROMISE_MESSAGE_EXPECTATION_TIMED));
-	}
-
-	const {signal, time} = getPromiseOptions(options);
-
-	if (signal?.aborted ?? false) {
-		return Promise.reject(signal!.reason);
-	}
-
-	return time > 0 ? getTimedPromise(promise, time, signal) : promise;
-}
-
-// #endregion