@oscarpalmer/atoms 0.149.0 → 0.150.0

package/dist/promise/timed.js

@@ -0,0 +1,33 @@
+import { PROMISE_ABORT_OPTIONS, PROMISE_EVENT_NAME, PROMISE_MESSAGE_EXPECTATION_TIMED, PromiseTimeoutError } from "./models.js";
+import { getPromiseOptions } from "./helpers.js";
+import { settlePromise } from "./misc.js";
+async function getTimedPromise(promise, time, signal) {
+	function abort() {
+		cancelAnimationFrame(frame);
+		rejector(signal.reason);
+	}
+	function run(now) {
+		start ??= now;
+		if (time === 0 || now - start >= time - 5) settlePromise(abort, rejector, new PromiseTimeoutError(), signal);
+		else frame = requestAnimationFrame(run);
+	}
+	signal?.addEventListener(PROMISE_EVENT_NAME, abort, PROMISE_ABORT_OPTIONS);
+	let frame;
+	let rejector;
+	let start;
+	return Promise.race([promise, new Promise((_, reject) => {
+		rejector = reject;
+		frame = requestAnimationFrame(run);
+	})]).then((value) => {
+		cancelAnimationFrame(frame);
+		signal?.removeEventListener(PROMISE_EVENT_NAME, abort);
+		return value;
+	});
+}
+async function timed(promise, options) {
+	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;
+}
+export { getTimedPromise, timed };

package/dist/result/index.js

@@ -1,5 +1,7 @@
 import { isError, isOk, isResult } from "../internal/result.js";
-import { attemptPromise } from "../promise.js";
+import { error, getError, ok, toPromise, unwrap } from "./misc.js";
+import { toResult } from "../promise/misc.js";
+import { attemptPromise } from "../promise/index.js";
 import { matchResult } from "./match.js";
 import { attemptFlow } from "./work/flow.js";
 import { attemptPipe } from "./work/pipe.js";
@@ -24,29 +26,4 @@ attempt.flow = attemptFlow;
 attempt.match = matchResult;
 attempt.pipe = attemptPipe;
 attempt.promise = attemptPromise;
-function error(value, original) {
-	return getError(value, original);
-}
-function getError(value, original) {
-	const errorResult = {
-		error: value,
-		ok: false
-	};
-	if (original instanceof Error) errorResult.original = original;
-	return errorResult;
-}
-/**
-* Creates an ok result
-* @param value Value
-* @returns Ok result
-*/
-function ok(value) {
-	return {
-		ok: true,
-		value
-	};
-}
-function unwrap(value, defaultValue) {
-	return isOk(value) ? value.value : defaultValue;
-}
-export { attempt, error, isError, isOk, isResult, ok, unwrap };
+export { attempt, error, toResult as fromPromise, isError, isOk, isResult, ok, toPromise, unwrap };

package/dist/result/misc.js

@@ -0,0 +1,40 @@
+import { isOk, isResult } from "../internal/result.js";
+function error(value, original) {
+	return getError(value, original);
+}
+function getError(value, original) {
+	const errorResult = {
+		error: value,
+		ok: false
+	};
+	if (original instanceof Error) errorResult.original = original;
+	return errorResult;
+}
+/**
+* Creates an ok result
+* @param value Value
+* @returns Ok result
+*/
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* Converts a result to a promise
+*
+* Resolves if ok, rejects for error
+* @param result Result to convert
+* @returns Promised result
+*/
+async function toPromise(result) {
+	const actual = typeof result === "function" ? result() : result;
+	if (!isResult(actual)) return Promise.reject(new Error(MESSAGE_PROMISE_RESULT));
+	return isOk(actual) ? Promise.resolve(actual.value) : Promise.reject(actual.error);
+}
+function unwrap(value, defaultValue) {
+	return isOk(value) ? value.value : defaultValue;
+}
+var MESSAGE_PROMISE_RESULT = "toPromise expected to receive a Result";
+export { error, getError, ok, toPromise, unwrap };

package/package.json

@@ -94,8 +94,8 @@
 			"default": "./dist/number.js"
 		},
 		"./promise": {
-			"types": "./types/promise.d.ts",
-			"default": "./dist/promise.js"
+			"types": "./types/promise/index.d.ts",
+			"default": "./dist/promise/index.js"
 		},
 		"./query": {
 			"types": "./types/query.d.ts",
@@ -192,5 +192,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.149.0"
+	"version": "0.150.0"
 }

package/src/index.ts

@@ -38,7 +38,7 @@ export * from './logger';
 export * from './math';
 export * from './models';
 export * from './number';
-export * from './promise';
+export * from './promise/index';
 export * from './query';
 export * from './queue';
 export * from './random';

package/src/promise/delay.ts

@@ -0,0 +1,63 @@
+import {getPromiseOptions} from './helpers';
+import {settlePromise} from './misc';
+import {PROMISE_ABORT_OPTIONS, type PromiseOptions} from './models';
+
+// #region Functions
+
+/**
+ * Create a delayed promise that resolves after a certain amount of time, or rejects if aborted
+ * @param options Options for the delay
+ * @returns Delayed promise
+ */
+export function delay(options?: PromiseOptions): Promise<void>;
+
+/**
+ * Create a delayed promise that resolves after a certain amount of time
+ * @param time How long to wait for _(in milliseconds; defaults to `0`)_
+ * @returns Delayed promise
+ */
+export function delay(time?: number): Promise<void>;
+
+export function delay(options?: unknown): Promise<void> {
+	const {signal, time} = getPromiseOptions(options);
+
+	if (signal?.aborted ?? false) {
+		return Promise.reject(signal!.reason);
+	}
+
+	function abort(): void {
+		cancelAnimationFrame(frame);
+
+		rejector(signal!.reason);
+	}
+
+	function run(now: DOMHighResTimeStamp): void {
+		start ??= now;
+
+		if (now - start >= time - 5) {
+			settlePromise(abort, resolver, undefined, signal);
+		} else {
+			frame = requestAnimationFrame(run);
+		}
+	}
+
+	signal?.addEventListener('abort', abort, PROMISE_ABORT_OPTIONS);
+
+	let frame: DOMHighResTimeStamp;
+	let rejector: (reason: unknown) => void;
+	let resolver: () => void;
+	let start: DOMHighResTimeStamp;
+
+	return new Promise((resolve, reject) => {
+		rejector = reject;
+		resolver = resolve;
+
+		if (time === 0) {
+			settlePromise(abort, resolve, undefined, signal);
+		} else {
+			frame = requestAnimationFrame(run);
+		}
+	});
+}
+
+// #endregion

package/src/promise/helpers.ts

@@ -0,0 +1,91 @@
+import type {RequiredKeys} from '../models';
+import {
+	PROMISE_STRATEGY_DEFAULT,
+	PROMISE_STRATEGY_ALL,
+	PROMISE_TYPE_FULFILLED,
+	PROMISE_TYPE_REJECTED,
+	type FulfilledPromise,
+	type PromiseOptions,
+	type PromisesOptions,
+	type PromisesResultItem,
+	type PromiseStrategy,
+	type RejectedPromise,
+} from './models';
+
+// #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),
+		};
+	}
+
+	if (input instanceof AbortSignal) {
+		return {signal: input, time: 0};
+	}
+
+	const options = typeof input === 'object' && input !== null ? (input as PromiseOptions) : {};
+
+	return {
+		signal: options.signal instanceof AbortSignal ? options.signal : undefined,
+		time: getNumberOrDefault(options.time),
+	};
+}
+
+export function getPromisesOptions(input: unknown): RequiredKeys<PromisesOptions, 'strategy'> {
+	if (typeof input === 'string') {
+		return {
+			strategy: getStrategyOrDefault(input),
+		};
+	}
+
+	if (input instanceof AbortSignal) {
+		return {signal: input, strategy: PROMISE_STRATEGY_DEFAULT};
+	}
+
+	const options = typeof input === 'object' && input !== null ? (input as PromisesOptions) : {};
+
+	return {
+		signal: options.signal instanceof AbortSignal ? options.signal : undefined,
+		strategy: getStrategyOrDefault(options.strategy),
+	};
+}
+
+export function getStrategyOrDefault(value: unknown): PromiseStrategy {
+	return PROMISE_STRATEGY_ALL.has(value as PromiseStrategy)
+		? (value as PromiseStrategy)
+		: PROMISE_STRATEGY_DEFAULT;
+}
+
+/**
+ * Is the value a fulfilled promise result?
+ * @param value Value to check
+ * @returns `true` if the value is a fulfilled promise result, `false` otherwise
+ */
+export function isFulfilled<Value>(value: unknown): value is FulfilledPromise<Value> {
+	return isType(value, PROMISE_TYPE_FULFILLED);
+}
+
+/**
+ * Is the value a rejected promise result?
+ * @param value Value to check
+ * @returns `true` if the value is a rejected promise result, `false` otherwise
+ */
+export function isRejected(value: unknown): value is RejectedPromise {
+	return isType(value, PROMISE_TYPE_REJECTED);
+}
+
+function isType(value: unknown, type: string): boolean {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		(value as PromisesResultItem<unknown>).status === type
+	);
+}
+
+// #endregion

package/src/promise/index.ts

@@ -0,0 +1,230 @@
+import {getPromiseOptions, getPromisesOptions} from './helpers';
+import {handleResult, settlePromise} from './misc';
+import {
+	PROMISE_ABORT_OPTIONS,
+	PROMISE_EVENT_NAME,
+	PROMISE_MESSAGE_EXPECTATION_ATTEMPT,
+	PROMISE_MESSAGE_EXPECTATION_PROMISES,
+	PROMISE_STRATEGY_DEFAULT,
+	PROMISE_TYPE_FULFILLED,
+	PROMISE_TYPE_REJECTED,
+	type PromiseData,
+	type PromiseHandlers,
+	type PromiseOptions,
+	type Promises,
+	type PromisesOptions,
+	type PromisesResult,
+} 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_EVENT_NAME, abort, PROMISE_ABORT_OPTIONS);
+
+	const promise = new Promise<Value>((resolve, reject) => {
+		rejector = reject;
+
+		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: Promises<Items>,
+	options?: Options,
+): Promise<Options['strategy'] extends 'first' ? Items : PromisesResult<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<Items extends unknown[]>(
+	items: Promises<Items>,
+	strategy: 'first',
+): Promise<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<Items extends unknown[]>(
+	items: Promises<Items>,
+	signal?: AbortSignal,
+): Promise<PromisesResult<Items>>;
+
+export async function promises<Items extends unknown[]>(
+	items: Promises<Items>,
+	options?: unknown,
+): Promise<Items | PromisesResult<Items>> {
+	const {signal, strategy} = getPromisesOptions(options);
+
+	if (signal?.aborted ?? false) {
+		return Promise.reject(signal!.reason);
+	}
+
+	if (!Array.isArray(items)) {
+		return Promise.reject(new TypeError(PROMISE_MESSAGE_EXPECTATION_PROMISES));
+	}
+
+	const actual = items.filter(item => item instanceof Promise);
+	const {length} = actual;
+
+	if (length === 0) {
+		return actual as unknown as Items | PromisesResult<Items>;
+	}
+
+	const complete = strategy === PROMISE_STRATEGY_DEFAULT;
+
+	function abort(): void {
+		handlers.reject(signal!.reason);
+	}
+
+	signal?.addEventListener('abort', abort, PROMISE_ABORT_OPTIONS);
+
+	const data: PromiseData<Items> = {
+		last: length - 1,
+		result: [] as unknown as Items | PromisesResult<Items>,
+	};
+
+	let handlers: PromiseHandlers<Items>;
+
+	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,
+					}),
+				);
+		}
+	});
+}
+
+// #endregion
+
+// #region Exports
+
+export {toPromise as fromResult} from '../result/misc';
+export {delay} from './delay';
+export {isFulfilled, isRejected} from './helpers';
+export {cancelable, toResult} from './misc';
+export {
+	CancelablePromise,
+	PromiseTimeoutError,
+	type FulfilledPromise,
+	type RejectedPromise,
+	type PromiseOptions,
+	type PromiseStrategy,
+	type PromisesOptions,
+	type PromisesResult,
+	type PromisesResultItem,
+} from './models';
+export {timed} from './timed';
+
+// #endregion

package/src/promise/misc.ts

@@ -0,0 +1,89 @@
+import {error, ok} from '../result/misc';
+import type {Result} from '../result/models';
+import {
+	CancelablePromise,
+	PROMISE_EVENT_NAME,
+	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<Items extends unknown[]>(
+	status: string,
+	parameters: PromiseParameters<Items>,
+): 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_EVENT_NAME, 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