@oscarpalmer/atoms 0.141.2 → 0.143.0

package/src/internal/value/partial.ts

@@ -0,0 +1,46 @@
+import type {PlainObject} from '../../models';
+
+export function partial<Value extends object, Key extends keyof Value>(
+	value: unknown,
+	keys: Key[],
+	omit: true,
+): Omit<Value, Key>;
+
+export function partial<Value extends object, Key extends keyof Value>(
+	value: unknown,
+	keys: Key[],
+	omit: false,
+): Pick<Value, Key>;
+
+export function partial<Value extends object, Key extends keyof Value>(
+	value: unknown,
+	providedKeys: Key[],
+	omit: boolean,
+): Partial<Value> {
+	if (typeof value !== 'object' || value === null) {
+		return {} as Partial<Value>;
+	}
+
+	const keys = omit ? Object.keys(value) : Array.isArray(providedKeys) ? providedKeys : [];
+	const {length} = keys;
+
+	if (length === 0) {
+		return omit ? (value as Partial<Value>) : ({} as Partial<Value>);
+	}
+
+	const partials: Partial<Value> = {};
+
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+
+		if (!(key in value)) {
+			continue;
+		}
+
+		if (omit ? !providedKeys.includes(key as Key) : true) {
+			(partials as PlainObject)[key] = (value as PlainObject)[key];
+		}
+	}
+
+	return partials;
+}

package/src/is.ts

@@ -7,8 +7,8 @@ import type {Primitive} from './models';
 
 /**
  * Is the value empty, or only containing `null` or `undefined` values?
- * @param value Object to check
- * @returns `true` if the object is considered empty, otherwise `false`
+ * @param value Value to check
+ * @returns `true` if the value is considered empty, otherwise `false`
  */
 export function isEmpty(value: unknown): boolean {
 	if (value == null) {
@@ -31,6 +31,15 @@ export function isEmpty(value: unknown): boolean {
 	return true;
 }
 
+/**
+ * Is the value not `undefined` or `null`?
+ * @param value Value to check
+ * @returns `true` if the value is not `undefined` or `null`, otherwise `false`
+ */
+export function isNonNullable(value: unknown): value is Exclude<unknown, undefined | null> {
+	return value != null;
+}
+
 /**
  * Is the value `undefined` or `null`?
  * @param value Value to check

package/src/math.ts

@@ -1,4 +1,5 @@
-import {aggregate, getAggregated} from './internal/math/aggregate';
+import {isNumber} from './internal/is';
+import {aggregate, getAggregateCallback, getAggregated} from './internal/math/aggregate';
 import type {NumericalValues, PlainObject} from './models';
 
 // #region Functions
@@ -78,17 +79,12 @@ export function count(array: unknown[], key?: unknown, value?: unknown): number
 
 	const {length} = array;
 
-	if (key == null) {
-		return length;
-	}
+	const callback = getAggregateCallback(key);
 
-	if (typeof key !== 'string' && typeof key !== 'function') {
-		return Number.NaN;
+	if (callback == null) {
+		return length;
 	}
 
-	const callback =
-		typeof key === 'function' ? key : (item: PlainObject): unknown => item[key as never];
-
 	let counted = 0;
 
 	for (let index = 0; index < length; index += 1) {
@@ -102,6 +98,68 @@ export function count(array: unknown[], key?: unknown, value?: unknown): number
 	return counted;
 }
 
+/**
+ * Get the median value from a list of items
+ * @param array List of items
+ * @param callback Callback to get an item's value
+ * @returns Median value, or `NaN` if no median can be calculated
+ */
+export function median<Item>(
+	array: Item[],
+	callback: (item: Item, index: number, array: Item[]) => number,
+): number;
+
+/**
+ * Get the median value from a list of items
+ * @param array List of items
+ * @param key Key to use for value
+ * @returns Median value, or `NaN` if no median can be calculated
+ */
+export function median<Item extends PlainObject>(
+	array: Item[],
+	key: keyof NumericalValues<Item>,
+): number;
+
+/**
+ * Get the median value from a list of numbers
+ * @param array List of numbers
+ * @returns Median value, or `NaN` if no median can be calculated
+ */
+export function median(array: number[]): number;
+
+export function median(array: unknown[], key?: unknown): number {
+	let length = Array.isArray(array) ? array.length : 0;
+
+	if (!Array.isArray(array) || length === 0) {
+		return Number.NaN;
+	}
+
+	if (length === 1) {
+		return isNumber(array[0]) ? array[0] : Number.NaN;
+	}
+
+	let values: unknown[] = array;
+
+	const callback = getAggregateCallback(key);
+
+	if (callback != null) {
+		values = array.map((item, index) => callback(item as never, index, array));
+	}
+
+	const numbers = values.filter(isNumber).sort((first, second) => first - second);
+
+	length = numbers.length;
+
+	if (length % 2 === 0) {
+		const first = length / 2 - 1;
+		const second = length / 2;
+
+		return (numbers[first] + numbers[second]) / 2;
+	}
+
+	return numbers[Math.floor(length / 2)];
+}
+
 /**
  * Get the minimum value from a list of items
  * @param items List of items

package/src/models.ts

@@ -13,9 +13,9 @@ export type ArrayOrPlainObject = unknown[] | Record<PropertyKey, unknown>;
 export type BuiltIns = void | Date | Primitive | RegExp;
 
 /**
- * An extend callback that can be cancelled
+ * An extend callback that can be canceled
  */
-export type CancellableCallback<Callback extends GenericCallback> = Callback & {
+export type CancelableCallback<Callback extends GenericCallback> = Callback & {
 	/**
 	 * Cancel the callback
 	 */

package/src/promise.ts

@@ -2,6 +2,32 @@
 
 import type {RequiredKeys} from './models';
 
+export class CancelablePromise<Value = void> extends Promise<Value> {
+	#rejector!: (reason: unknown) => void;
+
+	constructor(
+		executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void,
+	) {
+		let rejector: (reason: unknown) => void;
+
+		super((resolve, reject) => {
+			rejector = reject;
+
+			executor(resolve, reject);
+		});
+
+		this.#rejector = rejector!;
+	}
+
+	/**
+	 * Cancel the promise, rejecting it with an optional reason
+	 * @param reason Optional reason for canceling the promise
+	 */
+	cancel(reason?: unknown): void {
+		this.#rejector(reason);
+	}
+}
+
 type Data<Items extends unknown[]> = {
 	last: number;
 	result: Items | PromisesResult<Items>;
@@ -18,8 +44,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 +64,11 @@ type PromiseOptions = {
 	time?: number;
 };
 
+/**
+ * Promise handling strategy
+ */
+export type PromiseStrategy = 'complete' | 'first';
+
 export class PromiseTimeoutError extends Error {
 	constructor() {
 		super(MESSAGE_TIMEOUT);
@@ -50,12 +82,12 @@ type Promises<Items extends unknown[]> = {
 };
 
 type PromisesOptions = {
-	eager?: boolean;
 	signal?: AbortSignal;
+	strategy?: PromiseStrategy;
 };
 
 type PromisesResult<Items extends unknown[]> = {
-	[K in keyof Items]: PromisesResultItem<Items[K]>;
+	[K in keyof Items]: Items[K] extends Promise<infer Value> ? PromisesResultItem<Value> : never;
 };
 
 type PromisesResultItem<Value> = FulfilledPromiseResult<Value> | RejectedPromiseResult;
@@ -69,17 +101,28 @@ type RejectedPromiseResult = {
 
 // #region Functions
 
+/**
+ * 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,
+): CancelablePromise<Value> {
+	return new CancelablePromise(executor);
+}
+
 /**
  * Create a delayed promise that resolves after a certain amount of time, or rejects if aborted
  * @param options Options for the delay
- * @returns A delayed promise
+ * @returns Delayed promise
  */
 export function delay(options?: PromiseOptions): Promise<void>;
 
 /**
  * Create a delayed promise that resolves after a certain amount of time
  * @param time How long to wait for _(in milliseconds; defaults to `0`)_
- * @returns A delayed promise
+ * @returns Delayed promise
  */
 export function delay(time?: number): Promise<void>;
 
@@ -96,7 +139,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 +148,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 +164,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 +176,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 +287,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 +297,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 +327,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 +364,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);
 
-export function timed(promise: Promise<unknown>, time: number): Promise<unknown>;
+	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 Timed promise
+ */
+export async function timed<Value>(
+	promise: Promise<Value>,
+	options: RequiredKeys<PromiseOptions, 'time'>,
+): Promise<Value>;
 
-export function timed(promise: Promise<unknown>, options: unknown): 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 Timed promise
+ */
+export async function timed<Value>(promise: Promise<Value>, time: number): Promise<Value>;
+
+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 +423,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 Wrapped promise
+ */
+export async function attemptPromise<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 Promise-wrapped callback
+ */
+export async function attemptPromise<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 Promise-wrapped callback
+ */
+export async function attemptPromise<Value>(
+	callback: () => Value,
+	options?: PromiseOptions | AbortSignal | number,
+): Promise<Value>;
+
+export async function attemptPromise<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_ATTEMPT));
+	}
+
+	const {signal, time} = getPromiseOptions(options);
+
+	if (signal?.aborted ?? false) {
+		return Promise.reject(signal!.reason);
 	}
 
 	function abort(): void {
-		clearTimeout(timeout);
-
 		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_ATTEMPT = 'Attempt expected a function or a promise';
+
+const MESSAGE_EXPECTATION_PROMISES = 'Promises expected an array of promises';
+
+const MESSAGE_EXPECTATION_TIMED = 'Timed function expected 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/random.ts

@@ -73,9 +73,9 @@ export function getRandomItem<Value>(array: Value[]): Value | undefined {
 export function getRandomItems<Value>(array: Value[], amount: number): Value[];
 
 /**
- * Get an shuffled array
+ * Get a shuffled array
  * @param array Array to get random items from
- * @returns A shuffled version of the original array
+ * @returns Shuffled version of the original array
  */
 export function getRandomItems<Value>(array: Value[]): Value[];