@oscarpalmer/atoms 0.152.1 → 0.154.0

package/dist/atoms.full.js

@@ -937,6 +937,82 @@ function debounce(callback, time) {
 function throttle(callback, time) {
 	return getTimer(TIMER_THROTTLE, callback, time);
 }
+var RetryError = class extends Error {
+	constructor(message, original) {
+		super(message);
+		this.original = original;
+		this.name = ERROR_NAME$1;
+	}
+};
+/**
+* Retry a callback a specified number of times, with a delay between attempts
+* @param callback Callback to retry
+* @param options Retry options
+* @returns Callback result
+*/
+async function asyncRetry(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_EXPECTATION);
+	async function handle() {
+		try {
+			const result = await callback();
+			resolver(result);
+		} catch (error) {
+			if (attempts >= times || !when(error)) rejector(new RetryError(MESSAGE_FAILED, error));
+			else {
+				attempts += 1;
+				timer();
+			}
+		}
+	}
+	const { delay, times, when } = getRetryOptions(options);
+	const timer = getTimer(TIMER_WAIT, handle, delay);
+	let attempts = 0;
+	let rejector;
+	let resolver;
+	return new Promise((resolve, reject) => {
+		rejector = reject;
+		resolver = resolve;
+		handle();
+	});
+}
+function getRetryNumber(value) {
+	return typeof value === "number" && value > 0 ? value : 0;
+}
+function getRetryOptions(input) {
+	const options = isPlainObject(input) ? input : {};
+	return {
+		delay: getRetryNumber(options.delay),
+		times: getRetryNumber(options.times),
+		when: typeof options.when === "function" ? options.when : shouldRetry
+	};
+}
+/**
+* Retry a callback a specified number of times
+* @param callback Callback to retry
+* @param options Retry options
+* @returns Callback result
+*/
+function retry(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_EXPECTATION);
+	const { times, when } = getRetryOptions(options);
+	let last;
+	for (let index = 0; index <= times; index += 1) try {
+		return callback();
+	} catch (error) {
+		if (index >= times || !when(error)) {
+			last = error;
+			break;
+		}
+	}
+	throw new RetryError(MESSAGE_FAILED, last);
+}
+retry.async = asyncRetry;
+function shouldRetry() {
+	return true;
+}
+const ERROR_NAME$1 = "RetryError";
+const MESSAGE_EXPECTATION = "Retry expected a function";
+const MESSAGE_FAILED = "Retry failed";
 function _isResult(value, okValue) {
 	if (!isPlainObject(value)) return false;
 	return value.ok === okValue && (okValue ? "value" : "error") in value;
@@ -3696,4 +3772,4 @@ var SizedSet = class extends Set {
 		}
 	}
 };
-export { CancelablePromise, PromiseTimeoutError, QueueError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, toResult, fromQuery, toPromise as fromResult, toPromise, 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, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toSet, toggle, trim, truncate, tryDecode, tryEncode, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, toResult, fromQuery, toPromise as fromResult, toPromise, 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, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toSet, toggle, trim, truncate, tryDecode, tryEncode, unique, unsmush, unwrap, update, upperCase, words };

package/dist/function/retry.js

@@ -0,0 +1,79 @@
+import { isPlainObject } from "../internal/is.js";
+import { TIMER_WAIT, getTimer } from "../internal/function/timer.js";
+var RetryError = class extends Error {
+	constructor(message, original) {
+		super(message);
+		this.original = original;
+		this.name = ERROR_NAME;
+	}
+};
+/**
+* Retry a callback a specified number of times, with a delay between attempts
+* @param callback Callback to retry
+* @param options Retry options
+* @returns Callback result
+*/
+async function asyncRetry(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_EXPECTATION);
+	async function handle() {
+		try {
+			const result = await callback();
+			resolver(result);
+		} catch (error) {
+			if (attempts >= times || !when(error)) rejector(new RetryError(MESSAGE_FAILED, error));
+			else {
+				attempts += 1;
+				timer();
+			}
+		}
+	}
+	const { delay, times, when } = getRetryOptions(options);
+	const timer = getTimer(TIMER_WAIT, handle, delay);
+	let attempts = 0;
+	let rejector;
+	let resolver;
+	return new Promise((resolve, reject) => {
+		rejector = reject;
+		resolver = resolve;
+		handle();
+	});
+}
+function getRetryNumber(value) {
+	return typeof value === "number" && value > 0 ? value : 0;
+}
+function getRetryOptions(input) {
+	const options = isPlainObject(input) ? input : {};
+	return {
+		delay: getRetryNumber(options.delay),
+		times: getRetryNumber(options.times),
+		when: typeof options.when === "function" ? options.when : shouldRetry
+	};
+}
+/**
+* Retry a callback a specified number of times
+* @param callback Callback to retry
+* @param options Retry options
+* @returns Callback result
+*/
+function retry(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_EXPECTATION);
+	const { times, when } = getRetryOptions(options);
+	let last;
+	for (let index = 0; index <= times; index += 1) try {
+		return callback();
+	} catch (error) {
+		if (index >= times || !when(error)) {
+			last = error;
+			break;
+		}
+	}
+	throw new RetryError(MESSAGE_FAILED, last);
+}
+retry.async = asyncRetry;
+function shouldRetry() {
+	return true;
+}
+var ERROR_NAME = "RetryError";
+var MESSAGE_EXPECTATION = "Retry expected a function";
+var MESSAGE_FAILED = "Retry failed";
+export { RetryError, retry };

package/dist/index.js

@@ -39,6 +39,7 @@ import { getColor } from "./color/index.js";
 import { SizedMap } from "./sized/map.js";
 import { memoize } from "./function/memoize.js";
 import { debounce, throttle } from "./function/index.js";
+import { RetryError, retry } from "./function/retry.js";
 import { isError, isOk, isResult } from "./internal/result.js";
 import { flow, pipe } from "./function/work.js";
 import { equal } from "./internal/value/equal.js";
@@ -70,4 +71,4 @@ import { QueueError, queue } from "./queue.js";
 import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomHex, getRandomItem, getRandomItems } from "./random.js";
 import { attempt } from "./result/index.js";
 import { SizedSet } from "./sized/set.js";
-export { CancelablePromise, PromiseTimeoutError, QueueError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, 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, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, 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, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, unique, unsmush, unwrap, update, upperCase, words };

package/package.json

@@ -54,6 +54,14 @@
 			"types": "./types/function/index.d.ts",
 			"default": "./dist/function/index.js"
 		},
+		"./function/assert": {
+			"types": "./types/function/assert.d.ts",
+			"default": "./dist/function/assert.js"
+		},
+		"./function/retry": {
+			"types": "./types/function/retry.d.ts",
+			"default": "./dist/function/retry.js"
+		},
 		"./function/work": {
 			"types": "./types/function/work.d.ts",
 			"default": "./dist/function/work.js"
@@ -176,5 +184,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.152.1"
-}
+	"version": "0.154.0"
+}

package/src/function/assert.ts

@@ -1,7 +1,19 @@
 import type {Constructor} from '../models';
 
+// #region Types
+
 export type Asserter<Value> = (value: unknown) => asserts value is Value;
 
+// #endregion
+
+// #region Functions
+
+/**
+ * Asserts that a condition is true, throwing an error if it is not
+ * @param condition Condition to assert
+ * @param message Error message
+ * @param error Error constructor
+ */
 export function assert<Condition extends () => boolean>(
 	condition: Condition,
 	message: string,
@@ -12,32 +24,78 @@ export function assert<Condition extends () => boolean>(
 	}
 }
 
-assert.condition = <Value>(
+assert.condition = assertCondition;
+assert.defined = assertDefined;
+assert.instanceOf = assertInstanceOf;
+assert.is = assertIs;
+
+/**
+ * Creates an asserter that asserts a condition is true, throwing an error if it is not
+ * @param condition Condition to assert
+ * @param message Error message
+ * @param error Error constructor
+ * @returns Asserter
+ */
+function assertCondition<Value>(
 	condition: (value: unknown) => boolean,
 	message: string,
 	error?: ErrorConstructor,
-): Asserter<Value> => {
+): Asserter<Value> {
 	return value => {
 		assert(() => condition(value), message, error);
 	};
-};
+}
+
+/**
+ * Asserts that a value is defined _(not `null` or `undefined`)_, throwing an error if it is not
+ * @param value Value to assert
+ * @param message Error message
+ */
+function assertDefined<Value>(
+	value: unknown,
+	message?: string,
+): asserts value is Exclude<Value, null | undefined> {
+	assert(() => value != null, message ?? MESSAGE_DEFINED);
+}
 
-assert.instanceOf = <Value>(
+/**
+ * Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
+ * @param constructor Constructor to check against
+ * @param message Error message
+ * @param error Error constructor
+ * @returns Asserter
+ */
+function assertInstanceOf<Value>(
 	constructor: Constructor<Value>,
 	message: string,
 	error?: ErrorConstructor,
-): Asserter<Value> => {
+): Asserter<Value> {
 	return value => {
 		assert(() => value instanceof constructor, message, error);
 	};
-};
+}
 
-assert.is = <Value>(
+/**
+ * Creates an asserter that asserts a value is of a specific type, throwing an error if it is not
+ * @param condition Type guard function to check the value
+ * @param message Error message
+ * @param error Error constructor
+ * @returns Asserter
+ */
+function assertIs<Value>(
 	condition: (value: unknown) => value is Value,
 	message: string,
 	error?: ErrorConstructor,
-): Asserter<Value> => {
+): Asserter<Value> {
 	return value => {
 		assert(() => condition(value), message, error);
 	};
-};
+}
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE_DEFINED = 'Expected value to be defined';
+
+// #endregion

package/src/function/retry.ts

@@ -0,0 +1,162 @@
+import {getTimer, TIMER_WAIT} from '../internal/function/timer';
+import {isPlainObject} from '../internal/is';
+import type {GenericAsyncCallback, GenericCallback} from '../models';
+
+// #region Types
+
+export class RetryError extends Error {
+	constructor(
+		message: string,
+		readonly original: unknown,
+	) {
+		super(message);
+
+		this.name = ERROR_NAME;
+	}
+}
+
+export type RetryOptions = {
+	delay?: number;
+	times?: number;
+	when?: (error: unknown) => boolean;
+};
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Retry a callback a specified number of times, with a delay between attempts
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+async function asyncRetry<Callback extends GenericAsyncCallback>(
+	callback: Callback,
+	options?: RetryOptions,
+): Promise<Awaited<ReturnType<Callback>>>;
+
+/**
+ * Retry a callback a specified number of times, with a delay between attempts
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+async function asyncRetry<Callback extends GenericCallback>(
+	callback: Callback,
+	options?: RetryOptions,
+): Promise<ReturnType<Callback>>;
+
+/**
+ * Retry a callback a specified number of times, with a delay between attempts
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+async function asyncRetry<Callback extends GenericCallback>(
+	callback: Callback,
+	options?: RetryOptions,
+): Promise<ReturnType<Callback>> {
+	if (typeof callback !== 'function') {
+		throw new TypeError(MESSAGE_EXPECTATION);
+	}
+
+	async function handle(): Promise<void> {
+		try {
+			const result = await callback();
+
+			resolver(result);
+		} catch (error) {
+			if (attempts >= times || !when(error)) {
+				rejector(new RetryError(MESSAGE_FAILED, error));
+			} else {
+				attempts += 1;
+
+				timer();
+			}
+		}
+	}
+
+	const {delay, times, when} = getRetryOptions(options);
+
+	const timer = getTimer(TIMER_WAIT, handle, delay);
+
+	let attempts = 0;
+
+	let rejector: (reason?: unknown) => void;
+	let resolver: (value: Awaited<ReturnType<Callback>>) => void;
+
+	return new Promise<Awaited<ReturnType<Callback>>>((resolve, reject) => {
+		rejector = reject;
+		resolver = resolve;
+
+		handle();
+	});
+}
+
+function getRetryNumber(value?: unknown): number {
+	return typeof value === 'number' && value > 0 ? value : 0;
+}
+
+function getRetryOptions(input?: RetryOptions): Required<RetryOptions> {
+	const options = isPlainObject(input) ? input : {};
+
+	return {
+		delay: getRetryNumber(options.delay),
+		times: getRetryNumber(options.times),
+		when: typeof options.when === 'function' ? options.when : shouldRetry,
+	};
+}
+
+/**
+ * Retry a callback a specified number of times
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+export function retry<Callback extends GenericCallback>(
+	callback: Callback,
+	options?: Omit<RetryOptions, 'delay'>,
+): ReturnType<Callback> {
+	if (typeof callback !== 'function') {
+		throw new TypeError(MESSAGE_EXPECTATION);
+	}
+
+	const {times, when} = getRetryOptions(options);
+
+	let last: unknown;
+
+	for (let index = 0; index <= times; index += 1) {
+		try {
+			const result = callback();
+
+			return result;
+		} catch (error) {
+			if (index >= times || !when(error)) {
+				last = error;
+
+				break;
+			}
+		}
+	}
+
+	throw new RetryError(MESSAGE_FAILED, last);
+}
+
+retry.async = asyncRetry;
+
+function shouldRetry(): boolean {
+	return true;
+}
+
+// #endregion
+
+// #region Variables
+
+const ERROR_NAME = 'RetryError';
+
+const MESSAGE_EXPECTATION = 'Retry expected a function';
+
+const MESSAGE_FAILED = 'Retry failed';
+
+// #endregion

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './array/to-record';
 export * from './array/unique';
 
 export * from './function/index';
+export * from './function/retry';
 export * from './function/work';
 
 export * from './internal/function/misc';

package/src/math.ts

@@ -154,10 +154,6 @@ export function median(array: unknown[], key?: unknown): number {
 		return Number.NaN;
 	}
 
-	if (length === 1) {
-		return isNumber(array[0]) ? array[0] : Number.NaN;
-	}
-
 	let values: unknown[] = array;
 
 	const callback = getAggregateCallback(key);
@@ -170,6 +166,10 @@ export function median(array: unknown[], key?: unknown): number {
 
 	length = numbers.length;
 
+	if (length === 1) {
+		return numbers[0];
+	}
+
 	if (length % 2 === 0) {
 		const first = length / 2 - 1;
 		const second = length / 2;

package/types/function/retry.d.ts

@@ -0,0 +1,35 @@
+import type { GenericAsyncCallback, GenericCallback } from '../models';
+export declare class RetryError extends Error {
+    readonly original: unknown;
+    constructor(message: string, original: unknown);
+}
+export type RetryOptions = {
+    delay?: number;
+    times?: number;
+    when?: (error: unknown) => boolean;
+};
+/**
+ * Retry a callback a specified number of times, with a delay between attempts
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+declare function asyncRetry<Callback extends GenericAsyncCallback>(callback: Callback, options?: RetryOptions): Promise<Awaited<ReturnType<Callback>>>;
+/**
+ * Retry a callback a specified number of times, with a delay between attempts
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+declare function asyncRetry<Callback extends GenericCallback>(callback: Callback, options?: RetryOptions): Promise<ReturnType<Callback>>;
+/**
+ * Retry a callback a specified number of times
+ * @param callback Callback to retry
+ * @param options Retry options
+ * @returns Callback result
+ */
+export declare function retry<Callback extends GenericCallback>(callback: Callback, options?: Omit<RetryOptions, 'delay'>): ReturnType<Callback>;
+export declare namespace retry {
+    var async: typeof asyncRetry;
+}
+export {};

package/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './array/to-map';
 export * from './array/to-record';
 export * from './array/unique';
 export * from './function/index';
+export * from './function/retry';
 export * from './function/work';
 export * from './internal/function/misc';
 export * from './internal/string';