@oscarpalmer/atoms 0.141.2 → 0.143.0

package/dist/is.js

@@ -3,8 +3,8 @@ import { getArray } from "./array/get.js";
 import { getString } from "./internal/string.js";
 /**
 * 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`
 */
 function isEmpty(value) {
 	if (value == null) return true;
@@ -15,6 +15,14 @@ function isEmpty(value) {
 	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`
+*/
+function isNonNullable(value) {
+	return value != null;
+}
+/**
 * Is the value `undefined` or `null`?
 * @param value Value to check
 * @returns `true` if the value is `undefined` or `null`, otherwise `false`
@@ -64,4 +72,4 @@ function isPrimitive(value) {
 }
 var EXPRESSION_PRIMITIVE = /^(bigint|boolean|number|string|symbol)$/;
 var EXPRESSION_WHITESPACE = /^\s*$/;
-export { isArrayOrPlainObject, isConstructor, isEmpty, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive, isTypedArray };
+export { isArrayOrPlainObject, isConstructor, isEmpty, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive, isTypedArray };

package/dist/math.js

@@ -1,4 +1,5 @@
-import { aggregate, getAggregated, max } from "./internal/math/aggregate.js";
+import { isNumber } from "./internal/is.js";
+import { aggregate, getAggregateCallback, getAggregated, max } from "./internal/math/aggregate.js";
 function average(array, key) {
 	const aggregated = aggregate("average", array, key);
 	return aggregated.count > 0 ? aggregated.value / aggregated.count : NaN;
@@ -6,9 +7,8 @@ function average(array, key) {
 function count(array, key, value) {
 	if (!Array.isArray(array)) return NaN;
 	const { length } = array;
-	if (key == null) return length;
-	if (typeof key !== "string" && typeof key !== "function") return NaN;
-	const callback = typeof key === "function" ? key : (item) => item[key];
+	const callback = getAggregateCallback(key);
+	if (callback == null) return length;
 	let counted = 0;
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
@@ -16,6 +16,22 @@ function count(array, key, value) {
 	}
 	return counted;
 }
+function median(array, key) {
+	let length = Array.isArray(array) ? array.length : 0;
+	if (!Array.isArray(array) || length === 0) return NaN;
+	if (length === 1) return isNumber(array[0]) ? array[0] : NaN;
+	let values = array;
+	const callback = getAggregateCallback(key);
+	if (callback != null) values = array.map((item, index) => callback(item, 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)];
+}
 function min(array, key) {
 	return getAggregated("min", array, key);
 }
@@ -34,4 +50,4 @@ function round(value, decimals) {
 function sum(array, key) {
 	return getAggregated("sum", array, key);
 }
-export { average, count, max, min, round, sum };
+export { average, count, max, median, min, round, sum };

package/dist/promise.js

@@ -1,9 +1,35 @@
+var CancelablePromise = class extends Promise {
+	#rejector;
+	constructor(executor) {
+		let rejector;
+		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) {
+		this.#rejector(reason);
+	}
+};
 var PromiseTimeoutError = class extends Error {
 	constructor() {
 		super(MESSAGE_TIMEOUT);
 		this.name = ERROR_NAME;
 	}
 };
+/**
+* Create a cancelable promise
+* @param executor Executor function for the promise
+* @returns Cancelable promise
+*/
+function cancelable(executor) {
+	return new CancelablePromise(executor);
+}
 function delay(options) {
 	const { signal, time } = getPromiseOptions(options);
 	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
@@ -11,25 +37,25 @@ function delay(options) {
 		clearTimeout(timeout);
 		rejector(signal.reason);
 	}
-	signal?.addEventListener("abort", abort, abortOptions);
+	signal?.addEventListener("abort", abort, ABORT_OPTIONS);
 	let rejector;
 	let timeout;
 	return new Promise((resolve, reject) => {
 		rejector = reject;
 		timeout = setTimeout(() => {
-			signal?.removeEventListener("abort", abort);
-			resolve();
+			settlePromise(abort, resolve, void 0, signal);
 		}, time);
 	});
 }
-function getBooleanOrDefault(value, defaultValue) {
-	return typeof value === "boolean" ? value : defaultValue;
-}
 function getNumberOrDefault(value) {
 	return typeof value === "number" && value > 0 ? value : 0;
 }
 function getPromiseOptions(input) {
 	if (typeof input === "number") return { time: getNumberOrDefault(input) };
+	if (input instanceof AbortSignal) return {
+		signal: input,
+		time: 0
+	};
 	const options = typeof input === "object" && input !== null ? input : {};
 	return {
 		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
@@ -37,32 +63,54 @@ function getPromiseOptions(input) {
 	};
 }
 function getPromisesOptions(input) {
-	if (typeof input === "boolean") return { eager: input };
+	if (typeof input === "string") return { strategy: getStrategyOrDefault(input) };
 	if (input instanceof AbortSignal) return {
-		eager: false,
-		signal: input
+		signal: input,
+		strategy: DEFAULT_STRATEGY
 	};
 	const options = typeof input === "object" && input !== null ? input : {};
 	return {
-		eager: getBooleanOrDefault(options.eager, false),
-		signal: options.signal instanceof AbortSignal ? options.signal : void 0
+		signal: options.signal instanceof AbortSignal ? options.signal : void 0,
+		strategy: getStrategyOrDefault(options.strategy)
 	};
 }
+function getStrategyOrDefault(value) {
+	return strategies.has(value) ? value : DEFAULT_STRATEGY;
+}
+async function getTimed(promise, time, signal) {
+	function abort() {
+		clearTimeout(timeout);
+		rejector(signal.reason);
+	}
+	signal?.addEventListener(EVENT_NAME, abort, ABORT_OPTIONS);
+	let rejector;
+	let timeout;
+	return Promise.race([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(status, parameters) {
-	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[index] = eager ? value : status === TYPE_FULFILLED ? {
+	data.result[index] = !complete ? value : status === TYPE_FULFILLED ? {
 		status,
 		value
 	} : {
 		status,
 		reason: value
 	};
-	if (index === data.last) handlers.resolve(data.result);
+	if (index === data.last) settlePromise(abort, handlers.resolve, data.result, signal);
 }
 /**
 * Is the value a fulfilled promise result?
@@ -84,15 +132,17 @@ function isType(value, type) {
 	return typeof value === "object" && value !== null && value.status === type;
 }
 async function promises(items, 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;
-	const { eager, signal } = getPromisesOptions(options);
-	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
 	if (length === 0) return actual;
+	const complete = strategy === DEFAULT_STRATEGY;
 	function abort() {
 		handlers.reject(signal.reason);
 	}
-	signal?.addEventListener("abort", abort, abortOptions);
+	signal?.addEventListener("abort", abort, ABORT_OPTIONS);
 	const data = {
 		last: length - 1,
 		result: []
@@ -104,15 +154,17 @@ async function promises(items, options) {
 			resolve
 		};
 		for (let index = 0; index < length; index += 1) actual[index].then((value) => handleResult(TYPE_FULFILLED, {
+			abort,
+			complete,
 			data,
-			eager,
 			handlers,
 			index,
 			signal,
 			value
 		})).catch((reason) => handleResult(TYPE_REJECTED, {
+			abort,
+			complete,
 			data,
-			eager,
 			handlers,
 			index,
 			signal,
@@ -120,31 +172,50 @@ async function promises(items, options) {
 		}));
 	});
 }
-function timed(promise, options) {
-	if (!(promise instanceof Promise)) throw new TypeError(MESSAGE_EXPECTATION);
+function settlePromise(aborter, settler, value, signal) {
+	signal?.removeEventListener(EVENT_NAME, aborter);
+	settler(value);
+}
+async function timed(promise, options) {
+	if (!(promise instanceof Promise)) return Promise.reject(new TypeError(MESSAGE_EXPECTATION_TIMED));
+	const { signal, time } = getPromiseOptions(options);
+	if (signal?.aborted ?? false) return Promise.reject(signal.reason);
+	return time > 0 ? getTimed(promise, time, signal) : promise;
+}
+async function attemptPromise(value, options) {
+	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);
-	if (time <= 0) return promise;
 	function abort() {
-		clearTimeout(timeout);
 		rejector(signal.reason);
 	}
-	signal?.addEventListener(EVENT_NAME, abort, abortOptions);
+	async function handler(resolve, reject) {
+		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;
-	let timeout;
-	return Promise.race([promise, new Promise((_, reject) => {
+	signal?.addEventListener(EVENT_NAME, abort, ABORT_OPTIONS);
+	const promise = new Promise((resolve, reject) => {
 		rejector = reject;
-		timeout = setTimeout(() => {
-			signal?.removeEventListener(EVENT_NAME, abort);
-			reject(new PromiseTimeoutError());
-		}, time);
-	})]);
+		handler(resolve, reject);
+	});
+	return time > 0 ? getTimed(promise, time, signal) : promise;
 }
-var abortOptions = { once: true };
+var ABORT_OPTIONS = { once: true };
+var DEFAULT_STRATEGY = "complete";
 var ERROR_NAME = "PromiseTimeoutError";
 var EVENT_NAME = "abort";
-var MESSAGE_EXPECTATION = "Timed function expected a Promise";
+var MESSAGE_EXPECTATION_ATTEMPT = "Attempt expected a function or a promise";
+var MESSAGE_EXPECTATION_PROMISES = "Promises expected an array of promises";
+var MESSAGE_EXPECTATION_TIMED = "Timed function expected a Promise";
 var MESSAGE_TIMEOUT = "Promise timed out";
+var strategies = new Set(["complete", "first"]);
 var TYPE_FULFILLED = "fulfilled";
 var TYPE_REJECTED = "rejected";
-export { PromiseTimeoutError, delay, isFulfilled, isRejected, promises, timed };
+export { CancelablePromise, PromiseTimeoutError, attemptPromise, cancelable, delay, isFulfilled, isRejected, promises, timed };

package/dist/result.js

@@ -1,4 +1,5 @@
 import { isPlainObject } from "./internal/is.js";
+import { attemptPromise } from "./promise.js";
 function _isResult(value, okValue) {
 	if (!isPlainObject(value)) return false;
 	return value.ok === okValue && (okValue ? "value" : "error") in value;
@@ -44,17 +45,18 @@ function ok(value) {
 		value
 	};
 }
-function result(callback, err) {
+function attempt(callback, err) {
 	try {
 		return ok(callback());
 	} catch (thrown) {
 		return getError(err ?? thrown, err == null ? void 0 : thrown);
 	}
 }
-result.async = asyncResult;
-async function asyncResult(callback, err) {
+attempt.async = asyncAttempt;
+attempt.promise = attemptPromise;
+async function asyncAttempt(value, err) {
 	try {
-		return ok(await callback());
+		return ok(await (typeof value === "function" ? value() : value));
 	} catch (thrown) {
 		return getError(err ?? thrown, err == null ? void 0 : thrown);
 	}
@@ -62,4 +64,4 @@ async function asyncResult(callback, err) {
 function unwrap(value, defaultValue) {
 	return isOk(value) ? value.value : defaultValue;
 }
-export { error, isError, isOk, isResult, ok, result, unwrap };
+export { attempt, error, isError, isOk, isResult, ok, unwrap };

package/dist/sized/map.js

@@ -2,7 +2,7 @@ import { getSizedMaximum } from "../internal/sized.js";
 /**
 * A Map with a maximum size
 *
-* Behaviour is similar to a _LRU_-cache, where the least recently used entries are removed
+* Behavior is similar to a _LRU_-cache, where the least recently used entries are removed
 */
 var SizedMap = class extends Map {
 	/**

package/dist/sized/set.js

@@ -1,7 +1,7 @@
 import { getSizedMaximum } from "../internal/sized.js";
 /**
 * - A Set with a maximum size
-* - Behaviour is similar to a _LRU_-cache, where the oldest values are removed
+* - Behavior is similar to a _LRU_-cache, where the oldest values are removed
 */
 var SizedSet = class extends Set {
 	/**
@@ -39,7 +39,7 @@ var SizedSet = class extends Set {
 	* Get a value from the SizedSet, if it exists _(and move it to the end)_
 	* @param value Value to get from the SizedSet
 	* @param update Update the value's position in the SizedSet? _(defaults to `false`)_
-	* @returns The value if it exists, otherwise `undefined`
+	* @returns Found value if it exists, otherwise `undefined`
 	*/
 	get(value, update) {
 		if (this.has(value)) {

package/dist/value/misc.js

@@ -1,4 +1,5 @@
-import { partial } from "./partial.js";
+import { omit } from "./omit.js";
+import { pick } from "./pick.js";
 import { smush } from "./smush.js";
 import { unsmush } from "./unsmush.js";
-export { partial, smush, unsmush };
+export { omit, pick, smush, unsmush };

package/dist/value/omit.js

@@ -0,0 +1,11 @@
+import { partial } from "../internal/value/partial.js";
+/**
+* Create a new object without the specified keys
+* @param value Original object
+* @param keys Keys to omit
+* @returns Partial object without the specified keys
+*/
+function omit(value, keys) {
+	return partial(value, keys, true);
+}
+export { omit };

package/dist/value/pick.js

@@ -0,0 +1,11 @@
+import { partial } from "../internal/value/partial.js";
+/**
+* Create a new object with only the specified keys
+* @param value Original object
+* @param keys Keys to use
+* @returns Partial object with only the specified keys
+*/
+function pick(value, keys) {
+	return partial(value, keys, false);
+}
+export { pick };

package/package.json

@@ -8,12 +8,12 @@
 		"@types/node": "^25.3",
 		"@vitest/coverage-istanbul": "^4",
 		"jsdom": "^28.1",
-		"oxfmt": "^0.34",
-		"oxlint": "^1.49",
-		"rolldown": "1.0.0-rc.5",
+		"oxfmt": "^0.35",
+		"oxlint": "^1.50",
+		"rolldown": "1.0.0-rc.6",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
-		"vite": "8.0.0-beta.15",
+		"vite": "8.0.0-beta.16",
 		"vitest": "^4"
 	},
 	"exports": {
@@ -236,5 +236,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.141.2"
+	"version": "0.143.0"
 }

package/src/color/misc/is.ts

@@ -34,7 +34,7 @@ function isBytey(value: unknown): value is number {
 
 /**
  * Is the value a Color?
- * @param value The value to check
+ * @param value Value to check
  * @returns `true` if the value is a Color, otherwise `false`
  */
 export function isColor(value: unknown): value is Color {
@@ -75,7 +75,7 @@ function isDegree(value: unknown): value is number {
 
 /**
  * Is the value a hex color?
- * @param value The value to check
+ * @param value Value to check
  * @param alpha Allow alpha channel? _(defaults to `true`)_
  * @returns `true` if the value is a hex color, otherwise `false`
  */
@@ -97,7 +97,7 @@ export function isHexColor(value: unknown, alpha?: boolean): value is string {
 
 /**
  * Is the value an HSLA color?
- * @param value The value to check
+ * @param value Value to check
  * @returns `true` if the value is an HSLA color, otherwise `false`
  */
 export function isHslaColor(value: unknown): value is HSLAColor {
@@ -106,7 +106,7 @@ export function isHslaColor(value: unknown): value is HSLAColor {
 
 /**
  * Is the value an HSL color?
- * @param value The value to check
+ * @param value Value to check
  * @returns `true` if the value is an HSL color, otherwise `false`
  */
 export function isHslColor(value: unknown): value is HSLColor {
@@ -119,7 +119,7 @@ export function isHslLike(value: unknown): value is Record<keyof HSLColor, unkno
 
 /**
  * Is the value an RGBA color?
- * @param value The value to check
+ * @param value Value to check
  * @returns `true` if the value is an RGBA color, otherwise `false`
  */
 export function isRgbaColor(value: unknown): value is RGBAColor {
@@ -128,7 +128,7 @@ export function isRgbaColor(value: unknown): value is RGBAColor {
 
 /**
  * Is the value an RGB color?
- * @param value The value to check
+ * @param value Value to check
  * @returns `true` if the value is an RGB color, otherwise `false`
  */
 export function isRgbColor(value: unknown): value is RGBColor {

package/src/function/debounce.ts

@@ -1,5 +1,5 @@
 import {getLimiter} from '../internal/function/limiter';
-import type {CancellableCallback, GenericCallback} from '../models';
+import type {CancelableCallback, GenericCallback} from '../models';
 
 // #region Functions
 
@@ -14,7 +14,7 @@ import type {CancellableCallback, GenericCallback} from '../models';
 export function debounce<Callback extends GenericCallback>(
 	callback: Callback,
 	time?: number,
-): CancellableCallback<Callback> {
+): CancelableCallback<Callback> {
 	return getLimiter(callback, false, time);
 }
 

package/src/function/memoize.ts

@@ -73,7 +73,7 @@ class Memoized<Callback extends GenericCallback> {
 	/**
 	 * Get a result from the cache
 	 * @param key Key to get
-	 * @returns The cached result or `undefined` if it does not exist
+	 * @returns Cached result or `undefined` if it does not exist
 	 */
 	get(key: unknown): ReturnType<Callback> | undefined {
 		return this.#state.cache?.get(key);

package/src/function/throttle.ts

@@ -1,5 +1,5 @@
 import {getLimiter} from '../internal/function/limiter';
-import type {CancellableCallback, GenericCallback} from '../models';
+import type {CancelableCallback, GenericCallback} from '../models';
 
 // #region Functions
 
@@ -12,7 +12,7 @@ import type {CancellableCallback, GenericCallback} from '../models';
 export function throttle<Callback extends GenericCallback>(
 	callback: Callback,
 	time?: number,
-): CancellableCallback<Callback> {
+): CancelableCallback<Callback> {
 	return getLimiter(callback, true, time);
 }
 

package/src/index.ts

@@ -38,7 +38,8 @@ export * from './string/template';
 export * from './value/clone';
 export * from './value/diff';
 export * from './value/merge';
-export * from './value/partial';
+export * from './value/omit';
+export * from './value/pick';
 export * from './value/smush';
 export * from './value/unsmush';
 

package/src/internal/function/limiter.ts

@@ -1,4 +1,4 @@
-import type {CancellableCallback} from '../../models';
+import type {CancelableCallback} from '../../models';
 import type {GenericCallback} from '../../models';
 import FRAME_RATE_MS from '../frame-rate';
 
@@ -8,7 +8,7 @@ export function getLimiter<Callback extends GenericCallback>(
 	callback: Callback,
 	throttler: boolean,
 	time?: number,
-): CancellableCallback<Callback> {
+): CancelableCallback<Callback> {
 	const interval = typeof time === 'number' && time >= FRAME_RATE_MS ? time : FRAME_RATE_MS;
 
 	function step(now: DOMHighResTimeStamp, parameters: Parameters<Callback>): void {
@@ -46,7 +46,7 @@ export function getLimiter<Callback extends GenericCallback>(
 		}
 	};
 
-	return limiter as CancellableCallback<Callback>;
+	return limiter as CancelableCallback<Callback>;
 }
 
 // #endregion

package/src/internal/math/aggregate.ts

@@ -1,4 +1,5 @@
-import type {GenericCallback, NumericalValues, PlainObject} from '../../models';
+import type {NumericalValues, PlainObject} from '../../models';
+import {isNumber} from '../is';
 
 // #region Types
 
@@ -26,7 +27,7 @@ export function aggregate(type: AggregationType, array: unknown[], key: unknown)
 	}
 
 	const aggregator = aggregators[type];
-	const isCallback = typeof key === 'function';
+	const callback = getAggregateCallback(key);
 
 	let counted = 0;
 	let aggregated = Number.NaN;
@@ -35,16 +36,16 @@ export function aggregate(type: AggregationType, array: unknown[], key: unknown)
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
 
-		const value = isCallback
-			? (key as GenericCallback)(item, index, array)
-			: ((item as PlainObject)[key as never] ?? item);
+		const value = callback == null ? item : callback(item as never, index, array);
 
-		if (typeof value === 'number' && !Number.isNaN(value)) {
-			aggregated = aggregator(aggregated, value, notNumber);
-
-			counted += 1;
-			notNumber = false;
+		if (!isNumber(value)) {
+			continue;
 		}
+
+		aggregated = aggregator(aggregated, value, notNumber);
+
+		counted += 1;
+		notNumber = false;
 	}
 
 	return {
@@ -53,6 +54,14 @@ export function aggregate(type: AggregationType, array: unknown[], key: unknown)
 	};
 }
 
+export function getAggregateCallback(key: unknown): Function | undefined {
+	if (key == null) {
+		return;
+	}
+
+	return typeof key === 'function' ? key : (item: PlainObject): unknown => item[key as never];
+}
+
 /**
  * Get the maximum value from a list of items
  * @param items List of items

package/src/internal/number.ts

@@ -49,7 +49,7 @@ export function clamp(value: number, minimum: number, maximum: number, loop?: bo
 /**
  * Get the number value from an unknown value _(based on Lodash)_
  * @param value Original value
- * @returns The value as a number, or `NaN` if the value is unable to be parsed
+ * @returns Original value as a number, or `NaN` if the value is unable to be parsed
  */
 export function getNumber(value: unknown): number {
 	if (typeof value === 'number') {