@oscarpalmer/atoms 0.186.2 → 0.187.0

package/src/promise/helpers.ts

@@ -68,18 +68,20 @@ export function getStrategyOrDefault(value: unknown): PromiseStrategy {
 }
 
 /**
- * Is the value a fulfilled promise result?
+ * Is the value a fulfilled _Promise_ result?
+ *
  * @param value Value to check
- * @returns `true` if the value is a fulfilled promise result, `false` otherwise
+ * @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?
+ * Is the value a rejected _Promise_ result?
+ *
  * @param value Value to check
- * @returns `true` if the value is a rejected promise result, `false` otherwise
+ * @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);

package/src/promise/index.ts

@@ -23,10 +23,11 @@ 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
+ * 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>,
@@ -34,10 +35,11 @@ export async function attemptPromise<Value>(
 ): Promise<Value>;
 
 /**
- * Wrap a promise-returning callback with safety handlers, with optional abort capabilities and timeout
+ * 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
+ * @param options Options for the _Promise_
+ * @returns _Promise_-wrapped callback
  */
 export async function attemptPromise<Value>(
 	callback: () => Promise<Value>,
@@ -45,10 +47,11 @@ export async function attemptPromise<Value>(
 ): Promise<Value>;
 
 /**
- * Wrap a callback with a promise and safety handlers, with optional abort capabilities and timeout
+ * 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
+ * @param options Options for the _Promise_
+ * @returns _Promise_-wrapped callback
  */
 export async function attemptPromise<Value>(
 	callback: () => Value,
@@ -106,11 +109,12 @@ export async function attemptPromise<Value>(
 }
 
 /**
- * Handle a list of promises, returning their results in an ordered array.
+ * 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
+ *
+ * @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>(
@@ -123,11 +127,12 @@ export async function promises<Items extends unknown[], Options extends Promises
 >;
 
 /**
- * Handle a list of promises, returning their results in an ordered array.
+ * 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
+ *
+ * @param items List of _Promises_
+ * @param options Options for handling the _Promises_
  * @returns List of results
  */
 export async function promises<Value, Options extends PromisesOptions>(
@@ -136,11 +141,12 @@ export async function promises<Value, Options extends PromisesOptions>(
 ): Promise<Options['strategy'] extends 'first' ? Value[] : PromisesValue<Value>[]>;
 
 /**
- * Handle a list of promises, returning their results in an ordered array.
+ * 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
  *
- * 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
+ * @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[]>(
@@ -149,19 +155,21 @@ export async function promises<Items extends unknown[]>(
 ): Promise<PromisesUnwrapped<Items>>;
 
 /**
- * Handle a list of promises, returning their results in an ordered array.
+ * 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
+ * If any _Promise_ in the list is rejected, the whole function will reject
+ *
+ * @param items List of _Promises_
+ * @param strategy Strategy for handling the _Promises_; rejects on the first error encountered
  * @returns List of results
  */
 export async function promises<Value>(items: Promise<Value>[], strategy: 'first'): Promise<Value[]>;
 
 /**
- * Handle a list of promises, returning their results in an ordered array of rejected and resolved results
- * @param items List of promises
- * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * 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[]>(
@@ -170,9 +178,10 @@ export async function promises<Items extends unknown[]>(
 ): Promise<PromisesValues<PromisesItems<Items>>>;
 
 /**
- * Handle a list of promises, returning their results in an ordered array of rejected and resolved results
- * @param items List of promises
- * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * Handle a list of _Promises_, returning their results in an ordered array of rejected and resolved results
+ *
+ * @param items List of _Promises_
+ * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
  * @returns List of results
  */
 export async function promises<Value>(
@@ -250,13 +259,14 @@ export async function promises(items: unknown[], options?: unknown): Promise<unk
 promises.result = resultPromises;
 
 /**
- * Handle a list of promises, returning their results in an ordered array of results _({@link Result})_.
+ * Handle a list of _Promises_, returning their results in an ordered array of results _({@link Result})_
  *
  * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
  *
- * Available as `resultPromises` and `promises.result`
- * @param items List of promises
- * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * _Available as `resultPromises` and `promises.result`_
+ *
+ * @param items List of _Promises_
+ * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
  * @returns List of results
  */
 export async function resultPromises<Items extends unknown[]>(
@@ -265,13 +275,14 @@ export async function resultPromises<Items extends unknown[]>(
 ): Promise<PromisesResult<PromisesItems<Items>>>;
 
 /**
- * Handle a list of promises, returning their results in an ordered array of results _({@link Result})_.
+ * Handle a list of _Promises_, returning their results in an ordered array of results _({@link Result})_
  *
  * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
  *
- * Available as `resultPromises` and `promises.result`
- * @param items List of promises
- * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * _Available as `resultPromises` and `promises.result`_
+ *
+ * @param items List of _Promises_
+ * @param signal AbortSignal for aborting the operation _(when aborted, the _Promise_ will reject with the reason of the signal)_
  * @returns List of results
  */
 export async function resultPromises<Value>(

package/src/promise/misc.ts

@@ -12,9 +12,10 @@ import {
 // #region Functions
 
 /**
- * Create a cancelable promise
- * @param executor Executor function for the promise
- * @returns Cancelable promise
+ * 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,
@@ -58,15 +59,17 @@ export function settlePromise(
 }
 
 /**
- * Converts a promise to a promised result
- * @param callback Promise callback
+ * 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
+ * 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>>;

package/src/promise/models.ts

@@ -4,7 +4,7 @@ import type {Result} from '../result/models';
 // #region Types
 
 /**
- * A promise that can be canceled
+ * A _Promise_ that can be canceled
  */
 export class CancelablePromise<Value = void> extends Promise<Value> {
 	#rejector!: (reason: unknown) => void;
@@ -24,8 +24,9 @@ export class CancelablePromise<Value = void> extends Promise<Value> {
 	}
 
 	/**
-	 * Cancel the promise, rejecting it with an optional reason
-	 * @param reason Optional reason for canceling the promise
+	 * Cancel the _Promise_, rejecting it with an optional reason
+	 *
+	 * @param reason Optional reason for canceling the _Promise_
 	 */
 	cancel(reason?: unknown): void {
 		this.#rejector(reason);
@@ -33,15 +34,15 @@ export class CancelablePromise<Value = void> extends Promise<Value> {
 }
 
 /**
- * A promise that was fulfilled
+ * A _Promise_ that was fulfilled
  */
 export type FulfilledPromise<Value> = {
 	/**
-	 * Status of the promise
+	 * Status of the _Promise_
 	 */
 	status: typeof PROMISE_TYPE_FULFILLED;
 	/**
-	 * Value of the promise
+	 * Value of the _Promise_
 	 */
 	value: Awaited<Value>;
 };
@@ -57,15 +58,15 @@ export type PromiseHandlers = {
 };
 
 /**
- * Options for a promise-handling function
+ * Options for a _Promise_-handling function
  */
 export type PromiseOptions = {
 	/**
-	 * AbortSignal for aborting the promise; when aborted, the promise will reject with the reason of the signal
+	 * AbortSignal for aborting the _Promise_; when aborted, the _Promise_ will reject with the reason of the signal
 	 */
 	signal?: AbortSignal;
 	/**
-	 * How long to wait for (in milliseconds; defaults to `0`)
+	 * How long to wait for _(in milliseconds; defaults to `0`)_
 	 */
 	time?: number;
 };
@@ -81,12 +82,10 @@ export type PromiseParameters = {
 };
 
 /**
- * Promise handling strategy
+ * _Promise_ handling strategy
  *
- * - `complete`: wait for all promises to settle, then return the results
- * 	- Returns an array of fulfilled and/or rejected results
- * - `first`: rejects on the first rejected promise
- * 	- Returns an array of values
+ * - `complete`: wait for all _Promises_ to settle, then return the results, as an array of fulfilled and/or rejected results
+ * - `first`: rejects on the first rejected _Promise_, and returns an array of values
  */
 export type PromiseStrategy = 'complete' | 'first';
 
@@ -112,15 +111,15 @@ export type PromisesItems<Items extends unknown[]> = {
 };
 
 /**
- * Options for handling multiple promises
+ * Options for handling multiple _Promises_
  */
 export type PromisesOptions = {
 	/**
-	 * AbortSignal for aborting the promises; when aborted, the promises will reject with the reason of the signal
+	 * AbortSignal for aborting the _Promises_; when aborted, the _Promises_ will reject with the reason of the signal
 	 */
 	signal?: AbortSignal;
 	/**
-	 * Strategy for handling the promises; defaults to `complete`
+	 * Strategy for handling the _Promises_; defaults to `complete`
 	 */
 	strategy?: PromiseStrategy;
 };
@@ -154,11 +153,11 @@ export type PromisesValues<Items extends unknown[]> = {
 };
 
 /**
- * A promise that was rejected
+ * A _Promise_ that was rejected
  */
 export type RejectedPromise = {
 	/**
-	 * Status of the promise
+	 * Status of the _Promise_
 	 */
 	status: typeof PROMISE_TYPE_REJECTED;
 	/**

package/src/promise/timed.ts

@@ -54,10 +54,11 @@ export async function getTimedPromise<Value>(
 }
 
 /**
- * Create a promise that should be settled within a certain amount of time
- * @param promise Promise to settle
+ * Create a _Promise_ that should be settled within a certain amount of time
+ *
+ * @param promise _Promise_ to settle
  * @param options Timed options
- * @returns Timed promise
+ * @returns Timed _Promise_
  */
 export async function timed<Value>(
 	promise: Promise<Value>,
@@ -65,10 +66,11 @@ export async function timed<Value>(
 ): Promise<Value>;
 
 /**
- * Create a promise that should be settled within a certain amount of time
- * @param promise Promise to settle
+ * Create a _Promise_ that should be settled within a certain amount of time
+ *
+ * @param promise _Promise_ to settle
  * @param time How long to wait for _(in milliseconds; defaults to `0`)_
- * @returns Timed promise
+ * @returns Timed _Promise_
  */
 export async function timed<Value>(promise: Promise<Value>, time: number): Promise<Value>;
 

package/src/query.ts

@@ -8,6 +8,7 @@ import type {ArrayOrPlainObject, PlainObject} from './models';
 
 /**
  * Convert a query string to a plain _(nested)_ object
+ *
  * @param query Query string to convert
  * @returns Plain object representation of the query string
  */
@@ -103,6 +104,7 @@ function setQueryValue(parameters: PlainObject, key: string, value: string): voi
 
 /**
  * Convert a plain _(nested)_ object to a query string
+ *
  * @param parameters Plain object to convert
  * @returns Query string representation of the object
  */

package/src/queue.ts

@@ -16,7 +16,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 	readonly #queues: Map<string, Queue<Tail<CallbackParameters>, CallbackResult>> = new Map();
 
 	/**
-	 * Is any queue active?
+	 * Get keys of all active queues
 	 */
 	get active(): string[] {
 		return this.#getStatus(STATUS_ACTIVE);
@@ -37,14 +37,14 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 	}
 
 	/**
-	 * Are all queues empty?
+	 * Get keys of all empty queues
 	 */
 	get empty(): string[] {
 		return this.#getStatus(STATUS_EMPTY);
 	}
 
 	/**
-	 * Are all queues full?
+	 * Get keys of all full queues
 	 */
 	get full(): string[] {
 		return this.#getStatus(STATUS_FULL);
@@ -100,6 +100,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 
 	/**
 	 * Queue an item for a specific key
+	 *
 	 * @param key Key to queue the item for
 	 * @param parameters Parameters to use when item runs
 	 * @param signal Optional signal to abort the item
@@ -115,6 +116,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 
 	/**
 	 * Clear all items for a specific key _(or all items for all keys, if no key is provided)_
+	 *
 	 * @param key Optional key to clear the queue for
 	 */
 	clear(key?: string): void {
@@ -123,6 +125,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 
 	/**
 	 * Get the queue for a specific key
+	 *
 	 * @param key Key to get the queue for
 	 * @returns Queue for the key, or `undefined` if it doesn't exist
 	 */
@@ -132,6 +135,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 
 	/**
 	 * Pause the queue for a specific key _(or all queues, if no key is provided)_
+	 *
 	 * @param key Optional key to pause the queue for
 	 */
 	pause(key?: string): void {
@@ -140,6 +144,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 
 	/**
 	 * Remove a specific item for a specific key
+	 *
 	 * @param key Key to remove the item for
 	 * @param id ID of the item to remove
 	 */
@@ -149,6 +154,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 	 * Remove a queue and its items for a specific key
 	 *
 	 * _(To remove all items for a specific key, use `clear()` instead)_
+	 *
 	 * @param key Key to remove the queue for
 	 */
 	remove(key: string): void;
@@ -186,6 +192,7 @@ class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, Ca
 
 	/**
 	 * Resume the queue for a specific key _(or all queues, if no key is provided)_
+	 *
 	 * @param key Optional key to resume the queue for
 	 */
 	resume(key?: string): void {
@@ -329,6 +336,7 @@ class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, Callbac
 
 	/**
 	 * Add an item to the queue
+	 *
 	 * @param parameters Parameters to use when item runs
 	 * @param signal Optional signal to abort the item
 	 * @returns Queued item
@@ -404,6 +412,7 @@ class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, Callbac
 
 	/**
 	 * Remove and reject a specific item in the queue
+	 *
 	 * @param id ID of queued item
 	 */
 	remove(id: number): void {
@@ -615,6 +624,7 @@ export function keyedQueue<Callback extends GenericAsyncCallback>(
 
 /**
  * Create a queue for an asynchronous callback function
+ *
  * @param callback Callback function for queued items
  * @param options Queue options
  * @returns Queue instance
@@ -625,7 +635,8 @@ export function queue<Callback extends (key: string, ...parameters: any[]) => Pr
 ): Queue<Parameters<Callback>, Awaited<ReturnType<Callback>>>;
 
 /**
- * Create a queue for an asynchronous callback function
+ * Create a queue for a synchronous callback function
+ *
  * @param callback Callback function for queued items
  * @param options Queue options
  * @returns Queue instance

package/src/random.ts

@@ -6,6 +6,7 @@ import {join} from './internal/string';
 
 /**
  * Get a random boolean
+ *
  * @returns Random boolean
  */
 export function getRandomBoolean(): boolean {
@@ -14,6 +15,7 @@ export function getRandomBoolean(): boolean {
 
 /**
  * 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
@@ -36,6 +38,7 @@ export function getRandomCharacters(length: number, selection?: string): string
 
 /**
  * Get a random hexadecimal color
+ *
  * @param prefix Prefix the color with `#`? _(defaults to `false`)_
  * @returns Random hexadecimal color string in the format `(#)RRGGBB`
  */
@@ -45,6 +48,7 @@ export function getRandomColor(prefix?: boolean): string {
 
 /**
  * Get a random hexadecimal character
+ *
  * @returns Random hexadecimal character from `0-9` and `A-F`
  */
 export function getRandomHex(): string {
@@ -53,6 +57,7 @@ export function getRandomHex(): string {
 
 /**
  * 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
  */
@@ -66,6 +71,7 @@ export function getRandomItem<Value>(array: Value[]): Value | undefined {
 
 /**
  * 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
@@ -74,6 +80,7 @@ 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
  */
@@ -113,6 +120,6 @@ const HEX_MAXIMUM = 15;
 
 // #region Exports
 
-export {getRandomFloat, getRandomInteger} from './internal/random';
+export {getRandomFloatingNumber as getRandomFloat, getRandomInteger} from './internal/random';
 
 // #endregion

package/src/result/index.ts

@@ -4,10 +4,11 @@ import type {ExtendedErr, ExtendedResult, Result} from './models';
 // #region Functions
 
 /**
- * Executes a promise, catching any errors, and returns a result
+ * Executes a _Promise_, catching any errors, and returns a result
  *
- * Available as `asyncAttempt` and `attempt.async`
- * @param promise Promise to execute
+ * _Available as `asyncAttempt` and `attempt.async`_
+ *
+ * @param promise _Promise_ to execute
  * @param error Error value
  * @returns Callback result
  */
@@ -19,7 +20,8 @@ export async function asyncAttempt<Value, E>(
 /**
  * Executes a callback asynchronously, catching any errors, and returns a result
  *
- * Available as `asyncAttempt` and `attempt.async`
+ * _Available as `asyncAttempt` and `attempt.async`_
+ *
  * @param callback Callback to execute
  * @param error Error value
  * @returns Callback result
@@ -30,10 +32,11 @@ export async function asyncAttempt<Value, E>(
 ): Promise<ExtendedResult<Awaited<Value>, E>>;
 
 /**
- * Executes a promise, catching any errors, and returns a result
+ * Executes a _Promise_, catching any errors, and returns a result
+ *
+ * _Available as `asyncAttempt` and `attempt.async`_
  *
- * Available as `asyncAttempt` and `attempt.async`
- * @param promise Promise to execute
+ * @param promise _Promise_ to execute
  * @returns Callback result
  */
 export async function asyncAttempt<Value>(promise: Promise<Value>): Promise<Result<Awaited<Value>>>;
@@ -41,7 +44,8 @@ export async function asyncAttempt<Value>(promise: Promise<Value>): Promise<Resu
 /**
  * Executes a callback asynchronously, catching any errors, and returns a result
  *
- * Available as `asyncAttempt` and `attempt.async`
+ * _Available as `asyncAttempt` and `attempt.async`_
+ *
  * @param callback Callback to execute
  * @returns Callback result
  */
@@ -68,6 +72,7 @@ export async function asyncAttempt<Value, E>(
 
 /**
  * Executes a callback, catching any errors, and returns a result
+ *
  * @param callback Callback to execute
  * @param error Error value
  * @returns Callback result
@@ -76,6 +81,7 @@ export function attempt<Value, E>(callback: () => Value, error: E): ExtendedResu
 
 /**
  * Executes a callback, catching any errors, and returns a result
+ *
  * @param callback Callback to execute
  * @returns Callback result
  */