@oscarpalmer/atoms 0.141.2 → 0.142.0

package/dist/atoms.full.js

@@ -2764,25 +2764,25 @@ function delay(options) {
 		clearTimeout(timeout);
 		rejector(signal.reason);
 	}
-	signal?.addEventListener("abort", abort, abortOptions$1);
+	signal?.addEventListener("abort", abort, ABORT_OPTIONS);
 	let rejector;
 	let timeout;
 	return new Promise((resolve, reject) => {
 		rejector = reject;
 		timeout = setTimeout(() => {
-			signal?.removeEventListener("abort", abort);
-			resolve();
+			settlePromise(abort, resolve, void 0, signal);
 		}, time);
 	});
 }
-function getBooleanOrDefault$1(value, defaultValue) {
-	return typeof value === "boolean" ? value : defaultValue;
-}
 function getNumberOrDefault$1(value) {
 	return typeof value === "number" && value > 0 ? value : 0;
 }
 function getPromiseOptions(input) {
 	if (typeof input === "number") return { time: getNumberOrDefault$1(input) };
+	if (input instanceof AbortSignal) return {
+		signal: input,
+		time: 0
+	};
 	const options = typeof input === "object" && input !== null ? input : {};
 	return {
 		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
@@ -2790,32 +2790,54 @@ function getPromiseOptions(input) {
 	};
 }
 function getPromisesOptions(input) {
-	if (typeof input === "boolean") return { eager: input };
+	if (typeof input === "string") return { strategy: getStrategyOrDefault(input) };
 	if (input instanceof AbortSignal) return {
-		eager: false,
-		signal: input
+		signal: input,
+		strategy: DEFAULT_STRATEGY
 	};
 	const options = typeof input === "object" && input !== null ? input : {};
 	return {
-		eager: getBooleanOrDefault$1(options.eager, false),
-		signal: options.signal instanceof AbortSignal ? options.signal : void 0
+		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
+		strategy: getStrategyOrDefault(options.strategy)
 	};
 }
+function getStrategyOrDefault(value) {
+	return strategies.has(value) ? value : DEFAULT_STRATEGY;
+}
+async function getTimed(promise, time, signal) {
+	function abort() {
+		clearTimeout(timeout);
+		rejector(signal.reason);
+	}
+	signal?.addEventListener(EVENT_NAME$1, abort, ABORT_OPTIONS);
+	let rejector;
+	let timeout;
+	return Promise.race([promise, new Promise((_, reject) => {
+		rejector = reject;
+		timeout = setTimeout(() => {
+			settlePromise(abort, reject, new PromiseTimeoutError(), signal);
+		}, time);
+	})]).then((value) => {
+		clearTimeout(timeout);
+		signal?.removeEventListener(EVENT_NAME$1, abort);
+		return value;
+	});
+}
 function handleResult(status, parameters) {
-	const { data, eager, handlers, index, signal, value } = parameters;
+	const { abort, complete, data, handlers, index, signal, value } = parameters;
 	if (signal?.aborted ?? false) return;
-	if (eager && status === TYPE_REJECTED) {
-		handlers.reject(value);
+	if (!complete && status === TYPE_REJECTED) {
+		settlePromise(abort, handlers.reject, value, signal);
 		return;
 	}
-	data.result[index] = eager ? value : status === TYPE_FULFILLED ? {
+	data.result[index] = !complete ? value : status === TYPE_FULFILLED ? {
 		status,
 		value
 	} : {
 		status,
 		reason: value
 	};
-	if (index === data.last) handlers.resolve(data.result);
+	if (index === data.last) settlePromise(abort, handlers.resolve, data.result, signal);
 }
 /**
 * Is the value a fulfilled promise result?
@@ -2837,15 +2859,17 @@ function isType(value, type) {
 	return typeof value === "object" && value !== null && value.status === type;
 }
 async function promises(items, options) {
+	const { signal, strategy } = getPromisesOptions(options);
+	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
+	if (!Array.isArray(items)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_PROMISES));
 	const actual = items.filter((item) => item instanceof Promise);
 	const { length } = actual;
-	const { eager, signal } = getPromisesOptions(options);
-	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
 	if (length === 0) return actual;
+	const complete = strategy === DEFAULT_STRATEGY;
 	function abort() {
 		handlers.reject(signal.reason);
 	}
-	signal?.addEventListener("abort", abort, abortOptions$1);
+	signal?.addEventListener("abort", abort, ABORT_OPTIONS);
 	const data = {
 		last: length - 1,
 		result: []
@@ -2857,15 +2881,17 @@ async function promises(items, options) {
 			resolve
 		};
 		for (let index = 0; index < length; index += 1) actual[index].then((value) => handleResult(TYPE_FULFILLED, {
+			abort,
+			complete,
 			data,
-			eager,
 			handlers,
 			index,
 			signal,
 			value
 		})).catch((reason) => handleResult(TYPE_REJECTED, {
+			abort,
+			complete,
 			data,
-			eager,
 			handlers,
 			index,
 			signal,
@@ -2873,31 +2899,50 @@ async function promises(items, options) {
 		}));
 	});
 }
-function timed(promise, options) {
-	if (!(promise instanceof Promise)) throw new TypeError(MESSAGE_EXPECTATION);
+function settlePromise(aborter, settler, value, signal) {
+	signal?.removeEventListener(EVENT_NAME$1, aborter);
+	settler(value);
+}
+async function timed(promise, options) {
+	if (!(promise instanceof Promise)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_TIMED));
+	const { signal, time } = getPromiseOptions(options);
+	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
+	return time > 0 ? getTimed(promise, time, signal) : promise;
+}
+async function tryPromise(value, options) {
+	const isFunction = typeof value === "function";
+	if (!isFunction && !(value instanceof Promise)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_TRY));
 	const { signal, time } = getPromiseOptions(options);
 	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
-	if (time <= 0) return promise;
 	function abort() {
-		clearTimeout(timeout);
 		rejector(signal.reason);
 	}
-	signal?.addEventListener(EVENT_NAME$1, abort, abortOptions$1);
+	async function handler(resolve, reject) {
+		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;
-	let timeout;
-	return Promise.race([promise, new Promise((_, reject) => {
+	signal?.addEventListener(EVENT_NAME$1, abort, ABORT_OPTIONS);
+	const promise = new Promise((resolve, reject) => {
 		rejector = reject;
-		timeout = setTimeout(() => {
-			signal?.removeEventListener(EVENT_NAME$1, abort);
-			reject(new PromiseTimeoutError());
-		}, time);
-	})]);
+		handler(resolve, reject);
+	});
+	return time > 0 ? getTimed(promise, time, signal) : promise;
 }
-const abortOptions$1 = { once: true };
+const ABORT_OPTIONS = { once: true };
+const DEFAULT_STRATEGY = "complete";
 const ERROR_NAME$1 = "PromiseTimeoutError";
 const EVENT_NAME$1 = "abort";
-const MESSAGE_EXPECTATION = "Timed function expected a Promise";
+const MESSAGE_EXPECTATION_PROMISES = "Promises expected an array of promises";
+const MESSAGE_EXPECTATION_TIMED = "Timed function expected a Promise";
+const MESSAGE_EXPECTATION_TRY = "TryPromise expected a function or a promise";
 const MESSAGE_TIMEOUT = "Promise timed out";
+const strategies = new Set(["complete", "first"]);
 const TYPE_FULFILLED = "fulfilled";
 const TYPE_REJECTED = "rejected";
 /**
@@ -3342,4 +3387,4 @@ var SizedSet = class extends Set {
 		}
 	}
 };
-export { frame_rate_default as FRAME_RATE_MS, PromiseTimeoutError, QueueError, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, promises, push, queue, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, tryDecode, tryEncode, unique, unsmush, unwrap, upperCase, words };
+export { frame_rate_default as FRAME_RATE_MS, PromiseTimeoutError, QueueError, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, promises, push, queue, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, tryDecode, tryEncode, tryPromise, unique, unsmush, unwrap, upperCase, words };

package/dist/index.js

@@ -51,10 +51,10 @@ import { unsmush } from "./value/unsmush.js";
 import { isEmpty, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumerical, isObject, isPrimitive } from "./is.js";
 import { logger } from "./logger.js";
 import { average, count, min, round, sum } from "./math.js";
-import { PromiseTimeoutError, delay, isFulfilled, isRejected, promises, timed } from "./promise.js";
+import { PromiseTimeoutError, delay, isFulfilled, isRejected, promises, timed, tryPromise } from "./promise.js";
 import { fromQuery, toQuery } from "./query.js";
 import { QueueError, queue } from "./queue.js";
 import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomHex, getRandomItem, getRandomItems } from "./random.js";
 import { error, isError, isOk, isResult, ok, result, unwrap } from "./result.js";
 import { SizedSet } from "./sized/set.js";
-export { frame_rate_default as FRAME_RATE_MS, PromiseTimeoutError, QueueError, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, promises, push, queue, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, tryDecode, tryEncode, unique, unsmush, unwrap, upperCase, words };
+export { frame_rate_default as FRAME_RATE_MS, PromiseTimeoutError, QueueError, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, promises, push, queue, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, tryDecode, tryEncode, tryPromise, unique, unsmush, unwrap, upperCase, words };

package/dist/promise.js

@@ -11,25 +11,25 @@ function delay(options) {
 		clearTimeout(timeout);
 		rejector(signal.reason);
 	}
-	signal?.addEventListener("abort", abort, abortOptions);
+	signal?.addEventListener("abort", abort, ABORT_OPTIONS);
 	let rejector;
 	let timeout;
 	return new Promise((resolve, reject) => {
 		rejector = reject;
 		timeout = setTimeout(() => {
-			signal?.removeEventListener("abort", abort);
-			resolve();
+			settlePromise(abort, resolve, void 0, signal);
 		}, time);
 	});
 }
-function getBooleanOrDefault(value, defaultValue) {
-	return typeof value === "boolean" ? value : defaultValue;
-}
 function getNumberOrDefault(value) {
 	return typeof value === "number" && value > 0 ? value : 0;
 }
 function getPromiseOptions(input) {
 	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 : {};
 	return {
 		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
@@ -37,32 +37,54 @@ function getPromiseOptions(input) {
 	};
 }
 function getPromisesOptions(input) {
-	if (typeof input === "boolean") return { eager: input };
+	if (typeof input === "string") return { strategy: getStrategyOrDefault(input) };
 	if (input instanceof AbortSignal) return {
-		eager: false,
-		signal: input
+		signal: input,
+		strategy: DEFAULT_STRATEGY
 	};
 	const options = typeof input === "object" && input !== null ? input : {};
 	return {
-		eager: getBooleanOrDefault(options.eager, false),
-		signal: options.signal instanceof AbortSignal ? options.signal : void 0
+		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
+		strategy: getStrategyOrDefault(options.strategy)
 	};
 }
+function getStrategyOrDefault(value) {
+	return strategies.has(value) ? value : DEFAULT_STRATEGY;
+}
+async function getTimed(promise, time, signal) {
+	function abort() {
+		clearTimeout(timeout);
+		rejector(signal.reason);
+	}
+	signal?.addEventListener(EVENT_NAME, abort, ABORT_OPTIONS);
+	let rejector;
+	let timeout;
+	return Promise.race([promise, new Promise((_, reject) => {
+		rejector = reject;
+		timeout = setTimeout(() => {
+			settlePromise(abort, reject, new PromiseTimeoutError(), signal);
+		}, time);
+	})]).then((value) => {
+		clearTimeout(timeout);
+		signal?.removeEventListener(EVENT_NAME, abort);
+		return value;
+	});
+}
 function handleResult(status, parameters) {
-	const { data, eager, handlers, index, signal, value } = parameters;
+	const { abort, complete, data, handlers, index, signal, value } = parameters;
 	if (signal?.aborted ?? false) return;
-	if (eager && status === TYPE_REJECTED) {
-		handlers.reject(value);
+	if (!complete && status === TYPE_REJECTED) {
+		settlePromise(abort, handlers.reject, value, signal);
 		return;
 	}
-	data.result[index] = eager ? value : status === TYPE_FULFILLED ? {
+	data.result[index] = !complete ? value : status === TYPE_FULFILLED ? {
 		status,
 		value
 	} : {
 		status,
 		reason: value
 	};
-	if (index === data.last) handlers.resolve(data.result);
+	if (index === data.last) settlePromise(abort, handlers.resolve, data.result, signal);
 }
 /**
 * Is the value a fulfilled promise result?
@@ -84,15 +106,17 @@ function isType(value, type) {
 	return typeof value === "object" && value !== null && value.status === type;
 }
 async function promises(items, options) {
+	const { signal, strategy } = getPromisesOptions(options);
+	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
+	if (!Array.isArray(items)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_PROMISES));
 	const actual = items.filter((item) => item instanceof Promise);
 	const { length } = actual;
-	const { eager, signal } = getPromisesOptions(options);
-	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
 	if (length === 0) return actual;
+	const complete = strategy === DEFAULT_STRATEGY;
 	function abort() {
 		handlers.reject(signal.reason);
 	}
-	signal?.addEventListener("abort", abort, abortOptions);
+	signal?.addEventListener("abort", abort, ABORT_OPTIONS);
 	const data = {
 		last: length - 1,
 		result: []
@@ -104,15 +128,17 @@ async function promises(items, options) {
 			resolve
 		};
 		for (let index = 0; index < length; index += 1) actual[index].then((value) => handleResult(TYPE_FULFILLED, {
+			abort,
+			complete,
 			data,
-			eager,
 			handlers,
 			index,
 			signal,
 			value
 		})).catch((reason) => handleResult(TYPE_REJECTED, {
+			abort,
+			complete,
 			data,
-			eager,
 			handlers,
 			index,
 			signal,
@@ -120,31 +146,50 @@ async function promises(items, options) {
 		}));
 	});
 }
-function timed(promise, options) {
-	if (!(promise instanceof Promise)) throw new TypeError(MESSAGE_EXPECTATION);
+function settlePromise(aborter, settler, value, signal) {
+	signal?.removeEventListener(EVENT_NAME, aborter);
+	settler(value);
+}
+async function timed(promise, options) {
+	if (!(promise instanceof Promise)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_TIMED));
+	const { signal, time } = getPromiseOptions(options);
+	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
+	return time > 0 ? getTimed(promise, time, signal) : promise;
+}
+async function tryPromise(value, options) {
+	const isFunction = typeof value === "function";
+	if (!isFunction && !(value instanceof Promise)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_TRY));
 	const { signal, time } = getPromiseOptions(options);
 	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
-	if (time <= 0) return promise;
 	function abort() {
-		clearTimeout(timeout);
 		rejector(signal.reason);
 	}
-	signal?.addEventListener(EVENT_NAME, abort, abortOptions);
+	async function handler(resolve, reject) {
+		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;
-	let timeout;
-	return Promise.race([promise, new Promise((_, reject) => {
+	signal?.addEventListener(EVENT_NAME, abort, ABORT_OPTIONS);
+	const promise = new Promise((resolve, reject) => {
 		rejector = reject;
-		timeout = setTimeout(() => {
-			signal?.removeEventListener(EVENT_NAME, abort);
-			reject(new PromiseTimeoutError());
-		}, time);
-	})]);
+		handler(resolve, reject);
+	});
+	return time > 0 ? getTimed(promise, time, signal) : promise;
 }
-var abortOptions = { once: true };
+var ABORT_OPTIONS = { once: true };
+var DEFAULT_STRATEGY = "complete";
 var ERROR_NAME = "PromiseTimeoutError";
 var EVENT_NAME = "abort";
-var MESSAGE_EXPECTATION = "Timed function expected a Promise";
+var MESSAGE_EXPECTATION_PROMISES = "Promises expected an array of promises";
+var MESSAGE_EXPECTATION_TIMED = "Timed function expected a Promise";
+var MESSAGE_EXPECTATION_TRY = "TryPromise expected a function or a promise";
 var MESSAGE_TIMEOUT = "Promise timed out";
+var strategies = new Set(["complete", "first"]);
 var TYPE_FULFILLED = "fulfilled";
 var TYPE_REJECTED = "rejected";
-export { PromiseTimeoutError, delay, isFulfilled, isRejected, promises, timed };
+export { PromiseTimeoutError, delay, isFulfilled, isRejected, promises, timed, tryPromise };

package/package.json

@@ -8,12 +8,12 @@
 		"@types/node": "^25.3",
 		"@vitest/coverage-istanbul": "^4",
 		"jsdom": "^28.1",
-		"oxfmt": "^0.34",
-		"oxlint": "^1.49",
-		"rolldown": "1.0.0-rc.5",
+		"oxfmt": "^0.35",
+		"oxlint": "^1.50",
+		"rolldown": "1.0.0-rc.6",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
-		"vite": "8.0.0-beta.15",
+		"vite": "8.0.0-beta.16",
 		"vitest": "^4"
 	},
 	"exports": {
@@ -236,5 +236,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.141.2"
+	"version": "0.142.0"
 }

package/src/promise.ts

@@ -18,8 +18,9 @@ type Handlers<Items extends unknown[]> = {
 };
 
 type Parameters<Items extends unknown[]> = {
+	abort: () => void;
+	complete: boolean;
 	data: Data<Items>;
-	eager: boolean;
 	handlers: Handlers<Items>;
 	index: number;
 	signal?: AbortSignal;
@@ -37,6 +38,11 @@ type PromiseOptions = {
 	time?: number;
 };
 
+/**
+ * Promise handling strategy
+ */
+export type PromiseStrategy = 'complete' | 'first';
+
 export class PromiseTimeoutError extends Error {
 	constructor() {
 		super(MESSAGE_TIMEOUT);
@@ -50,8 +56,8 @@ type Promises<Items extends unknown[]> = {
 };
 
 type PromisesOptions = {
-	eager?: boolean;
 	signal?: AbortSignal;
+	strategy?: PromiseStrategy;
 };
 
 type PromisesResult<Items extends unknown[]> = {
@@ -96,7 +102,7 @@ export function delay(options?: unknown): Promise<void> {
 		rejector(signal!.reason);
 	}
 
-	signal?.addEventListener('abort', abort, abortOptions);
+	signal?.addEventListener('abort', abort, ABORT_OPTIONS);
 
 	let rejector: (reason: unknown) => void;
 	let timeout: ReturnType<typeof setTimeout>;
@@ -105,17 +111,11 @@ export function delay(options?: unknown): Promise<void> {
 		rejector = reject;
 
 		timeout = setTimeout(() => {
-			signal?.removeEventListener('abort', abort);
-
-			resolve();
+			settlePromise(abort, resolve, undefined, signal);
 		}, time);
 	});
 }
 
-function getBooleanOrDefault(value: unknown, defaultValue: boolean): boolean {
-	return typeof value === 'boolean' ? value : defaultValue;
-}
-
 function getNumberOrDefault(value: unknown): number {
 	return typeof value === 'number' && value > 0 ? value : 0;
 }
@@ -127,6 +127,10 @@ function getPromiseOptions(input: unknown): RequiredKeys<PromiseOptions, 'time'>
 		};
 	}
 
+	if (input instanceof AbortSignal) {
+		return {signal: input, time: 0};
+	}
+
 	const options = typeof input === 'object' && input !== null ? (input as PromiseOptions) : {};
 
 	return {
@@ -135,47 +139,87 @@ function getPromiseOptions(input: unknown): RequiredKeys<PromiseOptions, 'time'>
 	};
 }
 
-function getPromisesOptions(input: unknown): RequiredKeys<PromisesOptions, 'eager'> {
-	if (typeof input === 'boolean') {
-		return {eager: input};
+function getPromisesOptions(input: unknown): RequiredKeys<PromisesOptions, 'strategy'> {
+	if (typeof input === 'string') {
+		return {
+			strategy: getStrategyOrDefault(input),
+		};
 	}
 
 	if (input instanceof AbortSignal) {
-		return {eager: false, signal: input};
+		return {signal: input, strategy: DEFAULT_STRATEGY};
 	}
 
 	const options = typeof input === 'object' && input !== null ? (input as PromisesOptions) : {};
 
 	return {
-		eager: getBooleanOrDefault(options.eager, false),
 		signal: options.signal instanceof AbortSignal ? options.signal : undefined,
+		strategy: getStrategyOrDefault(options.strategy),
 	};
 }
 
+function getStrategyOrDefault(value: unknown): PromiseStrategy {
+	return strategies.has(value as PromiseStrategy) ? (value as PromiseStrategy) : DEFAULT_STRATEGY;
+}
+
+async function getTimed<Value>(
+	promise: Promise<Value>,
+	time: number,
+	signal?: AbortSignal,
+): Promise<Value> {
+	function abort(): void {
+		clearTimeout(timeout);
+
+		rejector(signal!.reason);
+	}
+
+	signal?.addEventListener(EVENT_NAME, abort, ABORT_OPTIONS);
+
+	let rejector: (reason: unknown) => void;
+	let timeout: ReturnType<typeof setTimeout>;
+
+	return Promise.race<Value>([
+		promise,
+		new Promise((_, reject) => {
+			rejector = reject;
+
+			timeout = setTimeout(() => {
+				settlePromise(abort, reject, new PromiseTimeoutError(), signal);
+			}, time);
+		}),
+	]).then(value => {
+		clearTimeout(timeout);
+
+		signal?.removeEventListener(EVENT_NAME, abort);
+
+		return value;
+	});
+}
+
 function handleResult<Items extends unknown[]>(
 	status: string,
 	parameters: Parameters<Items>,
 ): void {
-	const {data, eager, handlers, index, signal, value} = parameters;
+	const {abort, complete, data, handlers, index, signal, value} = parameters;
 
 	if (signal?.aborted ?? false) {
 		return;
 	}
 
-	if (eager && status === TYPE_REJECTED) {
-		handlers.reject(value);
+	if (!complete && status === TYPE_REJECTED) {
+		settlePromise(abort, handlers.reject, value, signal);
 
 		return;
 	}
 
-	(data.result as unknown[])[index] = eager
+	(data.result as unknown[])[index] = !complete
 		? value
 		: status === TYPE_FULFILLED
 			? {status, value}
 			: {status, reason: value};
 
 	if (index === data.last) {
-		handlers.resolve(data.result as Items | PromisesResult<Items>);
+		settlePromise(abort, handlers.resolve, data.result, signal);
 	}
 }
 
@@ -206,7 +250,9 @@ function isType(value: unknown, type: string): boolean {
 }
 
 /**
- * ---
+ * 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
  * @return List of results
@@ -214,17 +260,19 @@ function isType(value: unknown, type: string): boolean {
 export async function promises<Items extends unknown[], Options extends PromisesOptions>(
 	items: Promises<Items>,
 	options?: Options,
-): Promise<Options['eager'] extends true ? Items : PromisesResult<Items>>;
+): 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
+ * 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 eager Reject immediately if any promise is rejected
+ * @param strategy Strategy for handling the promises; rejects on the first error encountered
  * @return List of results
  */
 export async function promises<Items extends unknown[]>(
 	items: Promises<Items>,
-	eager: true,
+	strategy: 'first',
 ): Promise<Items>;
 
 /**
@@ -242,24 +290,30 @@ export async function promises<Items extends unknown[]>(
 	items: Promises<Items>,
 	options?: unknown,
 ): Promise<Items | PromisesResult<Items>> {
-	const actual = items.filter(item => item instanceof Promise);
-	const {length} = actual;
-
-	const {eager, signal} = getPromisesOptions(options);
+	const {signal, strategy} = getPromisesOptions(options);
 
 	if (signal?.aborted ?? false) {
 		return Promise.reject(signal!.reason);
 	}
 
+	if (!Array.isArray(items)) {
+		return Promise.reject(new TypeError(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 === DEFAULT_STRATEGY;
+
 	function abort(): void {
 		handlers.reject(signal!.reason);
 	}
 
-	signal?.addEventListener('abort', abort, abortOptions);
+	signal?.addEventListener('abort', abort, ABORT_OPTIONS);
 
 	const data: Data<Items> = {
 		last: length - 1,
@@ -273,21 +327,57 @@ export async function promises<Items extends unknown[]>(
 
 		for (let index = 0; index < length; index += 1) {
 			void actual[index]
-				.then(value => handleResult(TYPE_FULFILLED, {data, eager, handlers, index, signal, value}))
+				.then(value =>
+					handleResult(TYPE_FULFILLED, {abort, complete, data, handlers, index, signal, value}),
+				)
 				.catch(reason =>
-					handleResult(TYPE_REJECTED, {data, eager, handlers, index, signal, value: reason}),
+					handleResult(TYPE_REJECTED, {
+						abort,
+						complete,
+						data,
+						handlers,
+						index,
+						signal,
+						value: reason,
+					}),
 				);
 		}
 	});
 }
 
-export function timed(promise: Promise<unknown>, options: PromiseOptions): Promise<unknown>;
+function settlePromise(
+	aborter: () => void,
+	settler: (value: any) => void,
+	value: unknown,
+	signal?: AbortSignal,
+): void {
+	signal?.removeEventListener(EVENT_NAME, aborter);
+
+	settler(value);
+}
+
+/**
+ * Create a promise that should be settled within a certain amount of time
+ * @param promise Promise to settle
+ * @param options Timed options
+ * @returns A timed promise
+ */
+export async function timed<Value>(
+	promise: Promise<Value>,
+	options: RequiredKeys<PromiseOptions, 'time'>,
+): Promise<Value>;
 
-export function timed(promise: Promise<unknown>, time: number): Promise<unknown>;
+/**
+ * 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 A timed promise
+ */
+export async function timed<Value>(promise: Promise<Value>, time: number): Promise<Value>;
 
-export function timed(promise: Promise<unknown>, options: unknown): Promise<unknown> {
+export async function timed<Value>(promise: Promise<Value>, options: unknown): Promise<Value> {
 	if (!(promise instanceof Promise)) {
-		throw new TypeError(MESSAGE_EXPECTATION);
+		return Promise.reject(new TypeError(MESSAGE_EXPECTATION_TIMED));
 	}
 
 	const {signal, time} = getPromiseOptions(options);
@@ -296,49 +386,114 @@ export function timed(promise: Promise<unknown>, options: unknown): Promise<unkn
 		return Promise.reject(signal!.reason);
 	}
 
-	if (time <= 0) {
-		return promise;
+	return time > 0 ? getTimed(promise, time, signal) : promise;
+}
+
+/**
+ * Wrap a promise with safety handlers, with optional abort capabilities and timeout
+ * @param promise Promise to wrap
+ * @param options Options for the promise
+ * @returns A wrapped promise
+ */
+export async function tryPromise<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 A promise-wrapped callback
+ */
+export async function tryPromise<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 A promise-wrapped callback
+ */
+export async function tryPromise<Value>(
+	callback: () => Value,
+	options?: PromiseOptions | AbortSignal | number,
+): Promise<Value>;
+
+export async function tryPromise<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(MESSAGE_EXPECTATION_TRY));
 	}
 
-	function abort(): void {
-		clearTimeout(timeout);
+	const {signal, time} = getPromiseOptions(options);
 
+	if (signal?.aborted ?? false) {
+		return Promise.reject(signal!.reason);
+	}
+
+	function abort(): void {
 		rejector(signal!.reason);
 	}
 
-	signal?.addEventListener(EVENT_NAME, abort, abortOptions);
+	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;
-	let timeout: ReturnType<typeof setTimeout>;
 
-	return Promise.race([
-		promise,
-		new Promise((_, reject) => {
-			rejector = reject;
+	signal?.addEventListener(EVENT_NAME, abort, ABORT_OPTIONS);
 
-			timeout = setTimeout(() => {
-				signal?.removeEventListener(EVENT_NAME, abort);
+	const promise = new Promise<Value>((resolve, reject) => {
+		rejector = reject;
 
-				reject(new PromiseTimeoutError());
-			}, time);
-		}),
-	]);
+		handler(resolve, reject);
+	});
+
+	return time > 0 ? getTimed(promise, time, signal) : promise;
 }
 
 // #endregion
 
 // #region Variables
 
-const abortOptions = {once: true};
+const ABORT_OPTIONS = {once: true};
+
+const DEFAULT_STRATEGY: PromiseStrategy = 'complete';
 
 const ERROR_NAME = 'PromiseTimeoutError';
 
 const EVENT_NAME = 'abort';
 
-const MESSAGE_EXPECTATION = 'Timed function expected a Promise';
+const MESSAGE_EXPECTATION_PROMISES = 'Promises expected an array of promises';
+
+const MESSAGE_EXPECTATION_TIMED = 'Timed function expected a Promise';
+
+const MESSAGE_EXPECTATION_TRY = 'TryPromise expected a function or a promise';
 
 const MESSAGE_TIMEOUT = 'Promise timed out';
 
+const strategies = new Set<PromiseStrategy>(['complete', 'first']);
+
 const TYPE_FULFILLED = 'fulfilled';
 
 const TYPE_REJECTED = 'rejected';

package/src/value/get-set.ts

@@ -1,2 +1,2 @@
 export {getValue} from '../internal/value/get';
-export {setValue} from '../internal/value/set';
+export {setValue} from '../internal/value/set';

package/src/value/merge.ts

@@ -101,7 +101,7 @@ function initializeMerger(options?: Partial<MergeOptions>): Merger {
 
 	return <Model extends ArrayOrPlainObject>(values: NestedPartial<Model>[]): Model =>
 		handleMerge(values, actual) as Model;
-};
+}
 
 function mergeObjects(
 	values: ArrayOrPlainObject[],

package/types/promise.d.ts

@@ -1,3 +1,4 @@
+import type { RequiredKeys } from './models';
 type FulfilledPromiseResult<Value> = {
     status: typeof TYPE_FULFILLED;
     value: Value;
@@ -12,6 +13,10 @@ type PromiseOptions = {
      */
     time?: number;
 };
+/**
+ * Promise handling strategy
+ */
+export type PromiseStrategy = 'complete' | 'first';
 export declare class PromiseTimeoutError extends Error {
     constructor();
 }
@@ -19,8 +24,8 @@ type Promises<Items extends unknown[]> = {
     [K in keyof Items]: Promise<Items[K]>;
 };
 type PromisesOptions = {
-    eager?: boolean;
     signal?: AbortSignal;
+    strategy?: PromiseStrategy;
 };
 type PromisesResult<Items extends unknown[]> = {
     [K in keyof Items]: PromisesResultItem<Items[K]>;
@@ -55,19 +60,23 @@ export declare function isFulfilled<Value>(value: unknown): value is FulfilledPr
  */
 export declare function isRejected(value: unknown): value is RejectedPromiseResult;
 /**
- * ---
+ * 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
  * @return List of results
  */
-export declare function promises<Items extends unknown[], Options extends PromisesOptions>(items: Promises<Items>, options?: Options): Promise<Options['eager'] extends true ? Items : PromisesResult<Items>>;
+export declare 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
+ * 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 eager Reject immediately if any promise is rejected
+ * @param strategy Strategy for handling the promises; rejects on the first error encountered
  * @return List of results
  */
-export declare function promises<Items extends unknown[]>(items: Promises<Items>, eager: true): Promise<Items>;
+export declare 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
@@ -75,8 +84,41 @@ export declare function promises<Items extends unknown[]>(items: Promises<Items>
  * @return List of results
  */
 export declare function promises<Items extends unknown[]>(items: Promises<Items>, signal?: AbortSignal): Promise<PromisesResult<Items>>;
-export declare function timed(promise: Promise<unknown>, options: PromiseOptions): Promise<unknown>;
-export declare function timed(promise: Promise<unknown>, time: number): Promise<unknown>;
+/**
+ * Create a promise that should be settled within a certain amount of time
+ * @param promise Promise to settle
+ * @param options Timed options
+ * @returns A timed promise
+ */
+export declare 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 A timed promise
+ */
+export declare function timed<Value>(promise: Promise<Value>, time: number): Promise<Value>;
+/**
+ * Wrap a promise with safety handlers, with optional abort capabilities and timeout
+ * @param promise Promise to wrap
+ * @param options Options for the promise
+ * @returns A wrapped promise
+ */
+export declare function tryPromise<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 A promise-wrapped callback
+ */
+export declare function tryPromise<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 A promise-wrapped callback
+ */
+export declare function tryPromise<Value>(callback: () => Value, options?: PromiseOptions | AbortSignal | number): Promise<Value>;
 declare const TYPE_FULFILLED = "fulfilled";
 declare const TYPE_REJECTED = "rejected";
 export {};