@oscarpalmer/atoms 0.179.0 → 0.180.0

package/src/function/assert.ts

@@ -31,12 +31,14 @@ assert.is = assertIs;
 
 /**
  * Creates an asserter that asserts a condition is true, throwing an error if it is not
+ *
+ * Available as `assertCondition` and `assert.condition`
  * @param condition Condition to assert
  * @param message Error message
  * @param error Error constructor
  * @returns Asserter
  */
-function assertCondition<Value>(
+export function assertCondition<Value>(
 	condition: (value: unknown) => boolean,
 	message: string,
 	error?: ErrorConstructor,
@@ -48,10 +50,12 @@ function assertCondition<Value>(
 
 /**
  * Asserts that a value is defined throwing an error if it is not
+ *
+ * Available as `assertDefined` and `assert.defined`
  * @param value Value to assert
  * @param message Error message
  */
-function assertDefined<Value>(
+export function assertDefined<Value>(
 	value: unknown,
 	message?: string,
 ): asserts value is Exclude<Value, null | undefined> {
@@ -60,12 +64,14 @@ function assertDefined<Value>(
 
 /**
  * Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
+ *
+ * Available as `assertInstanceOf` and `assert.instanceOf`
  * @param constructor Constructor to check against
  * @param message Error message
  * @param error Error constructor
  * @returns Asserter
  */
-function assertInstanceOf<Value>(
+export function assertInstanceOf<Value>(
 	constructor: Constructor<Value>,
 	message: string,
 	error?: ErrorConstructor,
@@ -77,12 +83,14 @@ function assertInstanceOf<Value>(
 
 /**
  * Creates an asserter that asserts a value is of a specific type, throwing an error if it is not
+ *
+ * Available as `assertIs` and `assert.is`
  * @param condition Type guard function to check the value
  * @param message Error message
  * @param error Error constructor
  * @returns Asserter
  */
-function assertIs<Value>(
+export function assertIs<Value>(
 	condition: (value: unknown) => value is Value,
 	message: string,
 	error?: ErrorConstructor,

package/src/function/limit.ts

@@ -14,11 +14,13 @@ import type {
  * When called, successful _(finished)_ results will resolve and errors will reject.
  *
  * On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+ *
+ * Available as `asyncDebounce` and `debounce.async`
  * @param callback Callback to debounce
  * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
  * @returns Debounced callback handler with a `cancel` method
  */
-function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(
+export function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(
 	callback: Callback,
 	time?: number,
 ): AsyncCancelableCallback<Callback> {
@@ -31,11 +33,13 @@ function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(
  * When called, successful _(finished)_ results will resolve and errors will reject.
  *
  * On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+ *
+ * Available as `asyncThrottle` and `throttle.async`
  * @param callback Callback to throttle
  * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
  * @returns Throttled callback handler with a `cancel` method
  */
-function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(
+export function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(
 	callback: Callback,
 	time?: number,
 ): AsyncCancelableCallback<Callback> {

package/src/function/once.ts

@@ -31,10 +31,12 @@ type OnceState<Value> = {
 
 /**
  * Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+ *
+ * Available as `asyncOnce` and `once.async`
  * @param callback Callback to use once
  * @returns Once callback
  */
-function asyncOnce<Callback extends GenericAsyncCallback>(
+export function asyncOnce<Callback extends GenericAsyncCallback>(
 	callback: Callback,
 ): OnceAsyncCallback<Callback> {
 	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);

package/src/function/retry.ts

@@ -27,6 +27,8 @@ export type RetryOptions = {
 
 /**
  * Retry a callback a specified number of times, with a delay between attempts
+ *
+ * Available as `asyncRetry` and `retry.async`
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result
@@ -38,6 +40,8 @@ async function asyncRetry<Callback extends GenericAsyncCallback>(
 
 /**
  * Retry a callback a specified number of times, with a delay between attempts
+ *
+ * Available as `asyncRetry` and `retry.async`
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result
@@ -49,6 +53,8 @@ async function asyncRetry<Callback extends GenericCallback>(
 
 /**
  * Retry a callback a specified number of times, with a delay between attempts
+ *
+ * Available as `asyncRetry` and `retry.async`
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result
@@ -72,7 +78,7 @@ async function asyncRetry<Callback extends GenericCallback>(
 			} else {
 				attempts += 1;
 
-				timer();
+				void timer();
 			}
 		}
 	}
@@ -90,7 +96,7 @@ async function asyncRetry<Callback extends GenericCallback>(
 		rejector = reject;
 		resolver = resolve;
 
-		handle();
+		void handle();
 	});
 }
 

package/src/function/work.ts

@@ -29,24 +29,30 @@ export type FlowPromise<Callback extends GenericCallback, Value> = (
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a function
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<Fn extends GenericCallback>(fn: Fn): FlowPromise<Fn, ReturnType<Fn>>;
+export function asyncFlow<Fn extends GenericCallback>(fn: Fn): FlowPromise<Fn, ReturnType<Fn>>;
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<First extends GenericCallback, Second>(
+export function asyncFlow<First extends GenericCallback, Second>(
 	first: First,
 	second: (value: Awaited<UnwrapValue<ReturnType<First>>>) => Second,
 ): FlowPromise<First, Second>;
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<First extends GenericCallback, Second, Third>(
+export function asyncFlow<First extends GenericCallback, Second, Third>(
 	first: First,
 	second: (value: Awaited<UnwrapValue<ReturnType<First>>>) => Second,
 	third: (value: Awaited<UnwrapValue<Second>>) => Third,
@@ -54,9 +60,11 @@ function asyncFlow<First extends GenericCallback, Second, Third>(
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<First extends GenericCallback, Second, Third, Fourth>(
+export function asyncFlow<First extends GenericCallback, Second, Third, Fourth>(
 	first: First,
 	second: (value: Awaited<UnwrapValue<ReturnType<First>>>) => Second,
 	third: (value: Awaited<UnwrapValue<Second>>) => Third,
@@ -65,9 +73,11 @@ function asyncFlow<First extends GenericCallback, Second, Third, Fourth>(
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth>(
+export function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth>(
 	first: First,
 	second: (value: Awaited<UnwrapValue<ReturnType<First>>>) => Second,
 	third: (value: Awaited<UnwrapValue<Second>>) => Third,
@@ -77,9 +87,11 @@ function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth>(
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth, Sixth>(
+export function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth, Sixth>(
 	first: First,
 	second: (value: Awaited<UnwrapValue<ReturnType<First>>>) => Second,
 	third: (value: Awaited<UnwrapValue<Second>>) => Third,
@@ -90,9 +102,19 @@ function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth,
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth, Sixth, Seventh>(
+export function asyncFlow<
+	First extends GenericCallback,
+	Second,
+	Third,
+	Fourth,
+	Fifth,
+	Sixth,
+	Seventh,
+>(
 	first: First,
 	second: (value: Awaited<UnwrapValue<ReturnType<First>>>) => Second,
 	third: (value: Awaited<UnwrapValue<Second>>) => Third,
@@ -104,9 +126,11 @@ function asyncFlow<First extends GenericCallback, Second, Third, Fourth, Fifth,
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<
+export function asyncFlow<
 	First extends GenericCallback,
 	Second,
 	Third,
@@ -128,9 +152,11 @@ function asyncFlow<
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<
+export function asyncFlow<
 	First extends GenericCallback,
 	Second,
 	Third,
@@ -154,9 +180,11 @@ function asyncFlow<
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<
+export function asyncFlow<
 	First extends GenericCallback,
 	Second,
 	Third,
@@ -182,20 +210,24 @@ function asyncFlow<
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow<Fn extends GenericCallback>(
+export function asyncFlow<Fn extends GenericCallback>(
 	fn: Fn,
 	...fns: Array<(value: Awaited<UnwrapValue<ReturnType<Fn>>>) => unknown>
 ): FlowPromise<Fn, ReturnType<Fn>>;
 
 /**
  * Create an asynchronous Flow, a function that pipes values through a series of functions
+ *
+ * Available as `asyncFlow` and `flow.async`
  * @returns Flow function
  */
-function asyncFlow(...fns: GenericCallback[]): (...args: unknown[]) => Promise<unknown>;
+export function asyncFlow(...fns: GenericCallback[]): (...args: unknown[]) => Promise<unknown>;
 
-function asyncFlow(...fns: GenericCallback[]): (...args: unknown[]) => Promise<unknown> {
+export function asyncFlow(...fns: GenericCallback[]): (...args: unknown[]) => Promise<unknown> {
 	assertFlowFunctions(fns);
 
 	return (...args: unknown[]): Promise<unknown> =>
@@ -413,20 +445,24 @@ flow.async = asyncFlow;
 
 /**
  * Pipe a value through a function
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, Piped>(
+export async function asyncPipe<Initial, Piped>(
 	value: Initial,
 	pipe: (value: UnwrapValue<Initial>) => Piped,
 ): Promise<UnwrapValue<Piped>>;
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second>(
+export async function asyncPipe<Initial, First, Second>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -434,10 +470,12 @@ async function asyncPipe<Initial, First, Second>(
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second, Third>(
+export async function asyncPipe<Initial, First, Second, Third>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -446,10 +484,12 @@ async function asyncPipe<Initial, First, Second, Third>(
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second, Third, Fourth>(
+export async function asyncPipe<Initial, First, Second, Third, Fourth>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -459,10 +499,12 @@ async function asyncPipe<Initial, First, Second, Third, Fourth>(
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth>(
+export async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -473,10 +515,12 @@ async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth>(
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>(
+export async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -488,10 +532,12 @@ async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth>(
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Seventh>(
+export async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Seventh>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -504,10 +550,22 @@ async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Se
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Seventh, Eighth>(
+export async function asyncPipe<
+	Initial,
+	First,
+	Second,
+	Third,
+	Fourth,
+	Fifth,
+	Sixth,
+	Seventh,
+	Eighth,
+>(
 	value: Initial,
 	first: (value: UnwrapValue<Initial>) => First,
 	second: (value: UnwrapValue<First>) => Second,
@@ -521,10 +579,12 @@ async function asyncPipe<Initial, First, Second, Third, Fourth, Fifth, Sixth, Se
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<
+export async function asyncPipe<
 	Initial,
 	First,
 	Second,
@@ -550,10 +610,12 @@ async function asyncPipe<
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<
+export async function asyncPipe<
 	Initial,
 	First,
 	Second,
@@ -581,25 +643,29 @@ async function asyncPipe<
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe<Value>(
+export async function asyncPipe<Value>(
 	value: Value,
 	...pipes: Array<(value: Value) => Value>
 ): Promise<UnwrapValue<Value>>;
 
 /**
  * Pipe a value through a series of functions
+ *
+ * Available as `asyncPipe` and `pipe.async`
  * @param value Initial value
  * @returns Piped result
  */
-async function asyncPipe(
+export async function asyncPipe(
 	value: unknown,
 	...pipes: Array<(value: unknown) => unknown>
 ): Promise<unknown>;
 
-async function asyncPipe(
+export async function asyncPipe(
 	value: unknown,
 	...pipes: Array<(value: unknown) => unknown>
 ): Promise<unknown> {

package/src/internal/array/index-of.ts

@@ -48,7 +48,7 @@ export function indexOf<Item>(
 export function indexOf<Item>(array: Item[], item: Item): number;
 
 export function indexOf(array: unknown[], ...parameters: unknown[]): number {
-	return findValue(FIND_VALUE_INDEX, array, parameters) as number;
+	return findValue(FIND_VALUE_INDEX, array, parameters, false) as number;
 }
 
 // #endregion

package/src/internal/function/timer.ts

@@ -77,9 +77,11 @@ export function getAsyncTimer<Callback extends GenericAsyncCallback | GenericCal
 		last = next;
 
 		if (throttle) {
-			run(next);
+			void run(next);
 		} else {
-			id = startTimer(() => run(next));
+			id = startTimer(() => {
+				void run(next);
+			});
 		}
 
 		return next.promise;

package/src/internal/string.ts

@@ -21,9 +21,11 @@ export function getString(value: unknown): string {
 	}
 
 	if (typeof value !== 'object') {
+		// oxlint-disable-next-line typescript/no-base-to-string: the whole point of this function is to get a string representation of any value, so calling `String` on it is fine
 		return String(value);
 	}
 
+	// oxlint-disable-next-line typescript/no-base-to-string: ditto
 	const asString = String(value.valueOf?.() ?? value);
 
 	return asString.startsWith('[object ') ? JSON.stringify(value) : asString;

package/src/internal/value/compare.ts

@@ -76,10 +76,9 @@ compare.handlers = getCompareHandlers<number>(compare, {
 	method: COMPARE_NAME,
 });
 
+compare.deregister = deregisterComparator;
 compare.register = registerComparator;
 
-compare.unregister = unregisterComparator;
-
 function compareNumbers(first: bigint | number, second: bigint | number): number {
 	if (Object.is(first, second)) {
 		return 0;
@@ -121,6 +120,16 @@ function compareValue(
 	return compare.handlers.handle(first, second, compareStrings);
 }
 
+/**
+ * Deregister a custom comparison handler for a class
+ *
+ * Available as `deregisterComparator` and `compare.deregister`
+ * @param constructor Class constructor
+ */
+export function deregisterComparator<Instance>(constructor: Constructor<Instance>): void {
+	compare.handlers.deregister(constructor);
+}
+
 function getComparisonParts(value: unknown): unknown[] {
 	if (Array.isArray(value)) {
 		return value;
@@ -131,24 +140,18 @@ function getComparisonParts(value: unknown): unknown[] {
 
 /**
  * Register a custom comparison handler for a class
+ *
+ * Available as `registerComparator` and `compare.register`
  * @param constructor Class constructor
  * @param handler Method name or comparison function _(defaults to `compare`)_
  */
-function registerComparator<Instance>(
+export function registerComparator<Instance>(
 	constructor: Constructor<Instance>,
 	handler?: string | ((first: Instance, second: Instance) => number),
 ): void {
 	compare.handlers.register(constructor, handler);
 }
 
-/**
- * Unregister a custom comparison handler for a class
- * @param constructor Class constructor
- */
-function unregisterComparator<Instance>(constructor: Constructor<Instance>): void {
-	compare.handlers.unregister(constructor);
-}
-
 // #endregion
 
 // #region Variables