@oscarpalmer/atoms 0.193.0 → 0.194.0

package/src/random.ts

@@ -1,125 +0,0 @@
-import {shuffle} from './internal/array/shuffle';
-import {getRandomInteger} from './internal/random';
-import {join} from './internal/string';
-
-// #region Functions
-
-/**
- * Get a random boolean
- *
- * @returns Random boolean
- */
-export function getRandomBoolean(): boolean {
-	return Math.random() > BOOLEAN_MODIFIER;
-}
-
-/**
- * Get a random string of characters with a specified length
- *
- * @param length Length of random string
- * @param selection String of characters to select from _(defaults to lowercase English alphabet)_
- * @returns Random string of characters
- */
-export function getRandomCharacters(length: number, selection?: string): string {
-	if (typeof length !== 'number' || length <= 0) {
-		return '';
-	}
-
-	const actual = typeof selection === 'string' && selection.length > 0 ? selection : ALPHABET;
-
-	let characters = '';
-
-	for (let index = 0; index < length; index += 1) {
-		characters += actual.charAt(getRandomInteger(0, actual.length - 1));
-	}
-
-	return characters;
-}
-
-/**
- * Get a random hexadecimal color
- *
- * @param prefix Prefix the color with `#`? _(defaults to `false`)_
- * @returns Random hexadecimal color string in the format `(#)RRGGBB`
- */
-export function getRandomColor(prefix?: boolean): string {
-	return `${prefix === true ? '#' : ''}${join(Array.from({length: 6}, getRandomHex))}`;
-}
-
-/**
- * Get a random hexadecimal character
- *
- * @returns Random hexadecimal character from `0-9` and `A-F`
- */
-export function getRandomHex(): string {
-	return HEX_CHARACTERS[getRandomInteger(0, HEX_MAXIMUM)];
-}
-
-/**
- * Get a random item from an array
- *
- * @param array Array to get a random item from
- * @returns Random item from the array, or `undefined` if unable to retrieve one
- */
-export function getRandomItem<Value>(array: Value[]): Value | undefined {
-	if (!Array.isArray(array) || array.length === 0) {
-		return;
-	}
-
-	return array.length === 1 ? array[0] : array[getRandomInteger(0, array.length - 1)];
-}
-
-/**
- * Get an amount of random items from an array
- *
- * @param array Array to get random items from
- * @param amount Amount of items to return
- * @returns Array of random items
- */
-export function getRandomItems<Value>(array: Value[], amount: number): Value[];
-
-/**
- * Get a shuffled array
- *
- * @param array Array to get random items from
- * @returns Shuffled version of the original array
- */
-export function getRandomItems<Value>(array: Value[]): Value[];
-
-export function getRandomItems<Value>(array: Value[], amount?: number): Value[] {
-	if (!Array.isArray(array) || array.length === 0 || amount === 0) {
-		return [];
-	}
-
-	if (array.length < 2) {
-		return array;
-	}
-
-	if (amount === 1) {
-		return [array[getRandomInteger(0, array.length - 1)]];
-	}
-
-	return typeof amount !== 'number' || amount <= 0 || amount >= array.length
-		? shuffle(array)
-		: shuffle(array).slice(0, amount);
-}
-
-// #endregion
-
-// #region Variables
-
-const ALPHABET = 'abcdefghijklmnopqrstuvwxyz';
-
-const BOOLEAN_MODIFIER = 0.5;
-
-const HEX_CHARACTERS = '0123456789ABCDEF';
-
-const HEX_MAXIMUM = 15;
-
-// #endregion
-
-// #region Exports
-
-export {getRandomFloatingNumber as getRandomFloat, getRandomInteger} from './internal/random';
-
-// #endregion

package/src/result/index.ts

@@ -1,105 +0,0 @@
-import {getError, ok} from './misc';
-import type {ExtendedErr, ExtendedResult, Result} from './models';
-
-// #region Functions
-
-/**
- * Executes a _Promise_, catching any errors, and returns a result
- *
- * _Available as `asyncAttempt` and `attempt.async`_
- *
- * @param promise _Promise_ to execute
- * @param error Error value
- * @returns Callback result
- */
-export async function asyncAttempt<Value, E>(
-	promise: Promise<Value>,
-	error: E,
-): Promise<ExtendedResult<Awaited<Value>, E>>;
-
-/**
- * Executes a callback asynchronously, catching any errors, and returns a result
- *
- * _Available as `asyncAttempt` and `attempt.async`_
- *
- * @param callback Callback to execute
- * @param error Error value
- * @returns Callback result
- */
-export async function asyncAttempt<Value, E>(
-	callback: () => Promise<Value>,
-	error: E,
-): Promise<ExtendedResult<Awaited<Value>, E>>;
-
-/**
- * Executes a _Promise_, catching any errors, and returns a result
- *
- * _Available as `asyncAttempt` and `attempt.async`_
- *
- * @param promise _Promise_ to execute
- * @returns Callback result
- */
-export async function asyncAttempt<Value>(promise: Promise<Value>): Promise<Result<Awaited<Value>>>;
-
-/**
- * Executes a callback asynchronously, catching any errors, and returns a result
- *
- * _Available as `asyncAttempt` and `attempt.async`_
- *
- * @param callback Callback to execute
- * @returns Callback result
- */
-export async function asyncAttempt<Value>(
-	callback: () => Promise<Value>,
-): Promise<Result<Awaited<Value>>>;
-
-export async function asyncAttempt<Value, E>(
-	value: Promise<Value> | (() => Promise<Value>),
-	err?: E,
-): Promise<unknown> {
-	try {
-		let result = typeof value === 'function' ? value() : await value;
-
-		if (result instanceof Promise) {
-			result = await result;
-		}
-
-		return ok(result);
-	} catch (thrown) {
-		return getError((err ?? thrown) as E, err == null ? undefined : (thrown as Error));
-	}
-}
-
-/**
- * Executes a callback, catching any errors, and returns a result
- *
- * @param callback Callback to execute
- * @param error Error value
- * @returns Callback result
- */
-export function attempt<Value, E>(callback: () => Value, error: E): ExtendedResult<Value, E>;
-
-/**
- * Executes a callback, catching any errors, and returns a result
- *
- * @param callback Callback to execute
- * @returns Callback result
- */
-export function attempt<Value>(callback: () => Value): Result<Value, Error>;
-
-export function attempt<Value, E>(
-	callback: () => Value,
-	err?: E,
-): ExtendedErr<E> | Result<Value, E> {
-	try {
-		const value = callback();
-
-		return ok(value);
-	} catch (thrown) {
-		return getError((err ?? thrown) as E, err == null ? undefined : (thrown as Error));
-	}
-}
-
-attempt.async = asyncAttempt;
-
-// #endregion

package/src/result/match.ts

@@ -1,124 +0,0 @@
-import {isOk, isResult} from '../internal/result';
-import type {AnyResult, ExtendedErr, ResultMatch} from './models';
-
-// #region Functions
-
-/**
- * Handles a _Result_ with match callbacks
- *
- * _Available as `asyncMatchResult` and `matchResult.async`_
- *
- * @param result _Result_ to handle
- * @param handler Match callbacks
- * @returns Matched value-_Promise_
- */
-export async function asyncMatchResult<Value, Returned, E = Error>(
-	result: AnyResult<Value, E> | Promise<AnyResult<Value, E>> | (() => Promise<AnyResult<Value, E>>),
-	handler: ResultMatch<Value, Returned, E>,
-): Promise<Returned>;
-
-/**
- * Handles a _Result_ with match callbacks
- *
- * _Available as `asyncMatchResult` and `matchResult.async`_
- *
- * @param result _Result_ to handle
- * @param ok Ok callback
- * @param error Error callback
- * @returns Matched value-_Promise_
- */
-export async function asyncMatchResult<Value, Returned, E = Error>(
-	result: AnyResult<Value, E> | Promise<AnyResult<Value, E>> | (() => Promise<AnyResult<Value, E>>),
-	ok: ResultMatch<Value, Returned, E>['ok'],
-	error: ResultMatch<Value, Returned, E>['error'],
-): Promise<Returned>;
-
-export async function asyncMatchResult<Value, Returned, E = Error>(
-	result: AnyResult<Value, E> | Promise<AnyResult<Value, E>> | (() => Promise<AnyResult<Value, E>>),
-	first: ResultMatch<Value, Returned, E> | ResultMatch<Value, Returned, E>['ok'],
-	error?: ResultMatch<Value, Returned, E>['error'],
-): Promise<Returned> {
-	let value: AnyResult<Value, E>;
-
-	if (typeof result === 'function') {
-		value = await result();
-	} else if (result instanceof Promise) {
-		value = await result;
-	} else {
-		value = result;
-	}
-
-	if (!isResult(value)) {
-		throw new Error(MESSAGE_RESULT);
-	}
-
-	const hasObj = typeof first === 'object' && first !== null;
-
-	const okHandler = hasObj ? first.ok : first;
-	const errorHandler = hasObj ? first.error : error;
-
-	if (isOk(value)) {
-		return okHandler(value.value);
-	}
-
-	return errorHandler!(value.error, (value as ExtendedErr<E>).original);
-}
-
-/**
- * Handles a _Result_ with match callbacks
- *
- * @param result _Result_ to handle
- * @param handler Match callbacks
- * @returns Matched value
- */
-export function matchResult<Value, Returned, E = Error>(
-	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
-	handler: ResultMatch<Value, Returned, E>,
-): Returned;
-
-/**
- * Handles a _Result_ with match callbacks
- *
- * @param result _Result_ to handle
- * @param ok Ok callback
- * @param error Error callback
- * @returns Matched value
- */
-export function matchResult<Value, Returned, E = Error>(
-	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
-	ok: ResultMatch<Value, Returned, E>['ok'],
-	error: ResultMatch<Value, Returned, E>['error'],
-): Returned;
-
-export function matchResult<Value, Returned, E = Error>(
-	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
-	first: ResultMatch<Value, Returned, E> | ResultMatch<Value, Returned, E>['ok'],
-	error?: ResultMatch<Value, Returned, E>['error'],
-): Returned {
-	const value = typeof result === 'function' ? result() : result;
-
-	if (!isResult(value)) {
-		throw new Error(MESSAGE_RESULT);
-	}
-
-	const hasObj = typeof first === 'object' && first !== null;
-
-	const okHandler = hasObj ? first.ok : first;
-	const errorHandler = hasObj ? first.error : error;
-
-	if (isOk(value)) {
-		return okHandler(value.value);
-	}
-
-	return errorHandler!(value.error, (value as ExtendedErr<E>).original);
-}
-
-matchResult.async = asyncMatchResult;
-
-// #endregion
-
-// #region Variables
-
-const MESSAGE_RESULT = '`result.match` expected a Result or a function that returns a Result';
-
-// #endregion

package/src/result/misc.ts

@@ -1,129 +0,0 @@
-import {isOk, isResult} from '../internal/result';
-import type {AnyResult, Err, ExtendedErr, Ok, Result} from './models';
-
-// #region Functions
-
-/**
- * Creates an extended error result
- *
- * @param value Error value
- * @param original Original error
- * @returns Error result
- */
-export function error<E>(value: E, original: Error): ExtendedErr<E>;
-
-/**
- * Creates an error result
- *
- * @param value Error value
- * @returns Error result
- */
-export function error<E>(value: E): Err<E>;
-
-export function error<E>(value: E, original?: Error): Err<E> | ExtendedErr<E> {
-	return getError(value, original);
-}
-
-export function getError<E>(value: E, original?: Error): Err<E> | ExtendedErr<E> {
-	const errorResult: Err<E> | ExtendedErr<E> = {
-		error: value,
-		ok: false,
-	};
-
-	if (original instanceof Error) {
-		(errorResult as ExtendedErr<E>).original = original;
-	}
-
-	return errorResult;
-}
-
-/**
- * Creates an ok result
- *
- * @param value Value
- * @returns Ok result
- */
-export function ok<Value>(value: Value): Ok<Value> {
-	return {
-		ok: true,
-		value,
-	};
-}
-
-/**
- * Converts a result to a _Promise_
- *
- * Resolves if ok, rejects for error
- *
- * @param callback Callback to get the result
- * @returns Promised result
- */
-export async function toPromise<Value, E = Error>(
-	callback: () => AnyResult<Value, E>,
-): Promise<Value>;
-
-/**
- * Converts a result to a _Promise_
- *
- * Resolves if ok, rejects for error
- *
- * @param result _Result_ to convert
- * @returns Promised result
- */
-export async function toPromise<Value, E = Error>(result: AnyResult<Value, E>): Promise<Value>;
-
-/**
- * Converts a _Result_ to a _Promise_
- *
- * Resolves if ok, rejects for error
- *
- * @param result _Result_ to convert
- * @returns Promised result
- */
-export async function toPromise<Value, E = Error>(
-	result: AnyResult<Value, E> | (() => AnyResult<Value, E>),
-): Promise<Value> {
-	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);
-}
-
-/**
- * Gets the value of an ok result _(or a default value)_
- *
- * @param value _Result_ to unwrap
- * @param defaultValue Default value
- * @returns Value of the _Result_ _(or the default value)_
- */
-export function unwrap<Value, E = Error>(value: Result<Value, E>, defaultValue: Value): Value;
-
-/**
- * Gets the value of an ok result _(or a default value)_
- *
- * @param value _Result_ to unwrap
- * @param defaultValue Default value
- * @returns Value of the _Result_ _(or the default value)_
- */
-export function unwrap(value: unknown, defaultValue: unknown): unknown;
-
-export function unwrap(value: unknown, defaultValue: unknown): unknown {
-	return isOk(value) ? value.value : defaultValue;
-}
-
-// #endregion
-
-// #region Variables
-
-const MESSAGE_PROMISE_RESULT = 'toPromise expected to receive a Result';
-
-// #endregion
-
-// #region Exports
-
-export {isError, isOk, isResult} from '../internal/result';
-
-// #endregion

package/src/result/models.ts

@@ -1,83 +0,0 @@
-import type {GenericCallback} from '../models';
-
-// #region Types
-
-/**
- * An unknown result
- */
-export type AnyResult<Value, E> = Err<E> | ExtendedErr<E> | Ok<Value>;
-
-/**
- * An error result
- */
-export type Err<Error> = {
-	ok: false;
-	error: Error;
-};
-
-/**
- * An extended error result
- */
-export type ExtendedErr<E> = Err<E> & {
-	original: Error;
-};
-
-/**
- * An extended, unknown result
- */
-export type ExtendedResult<Value, E> = ExtendedErr<E> | Ok<Value>;
-
-/**
- * A successful result
- */
-export type Ok<Value> = {
-	ok: true;
-	value: Value;
-};
-
-/**
- * An unknown result
- */
-export type Result<Value, E = Error> = Err<E> | Ok<Value>;
-
-/**
- * Match callbacks for a result
- */
-export type ResultMatch<Value, Returned, E = Error> = {
-	/**
-	 * Callback for error result
-	 *
-	 * @param error Error value
-	 * @param original Original error, if available
-	 * @returns Value to return
-	 */
-	error: (error: E, original?: Error) => Returned;
-	/**
-	 * Callback for ok result
-	 *
-	 * @param value Ok value
-	 * @returns Value to return
-	 */
-	ok: (value: Value) => Returned;
-};
-
-/**
- * Unwrap a result value
- */
-type UnwrapResult<Original extends Result<unknown, unknown>> =
-	Original extends Ok<infer Value> ? Value : never;
-
-/**
- * Unwrap any value
- */
-export type UnwrapValue<Original> = Original extends GenericCallback
-	? ReturnType<Original> extends Result<unknown, unknown>
-		? UnwrapResult<ReturnType<Original>>
-		: ReturnType<Original>
-	: Original extends Result<unknown, unknown>
-		? UnwrapResult<Original>
-		: Original extends Promise<infer Value>
-			? Awaited<Value>
-			: Original;
-
-// #endregion