@oscarpalmer/atoms 0.156.0 → 0.158.0

package/dist/function/index.js

@@ -1,6 +1,7 @@
 import { noop } from "../internal/function/misc.js";
 import { TIMER_DEBOUNCE, TIMER_THROTTLE, getTimer } from "../internal/function/timer.js";
 import { memoize } from "./memoize.js";
+import { once } from "./once.js";
 /**
 * Debounce a function, ensuring it is only called after `time` milliseconds have passed
 *
@@ -21,4 +22,4 @@ function debounce(callback, time) {
 function throttle(callback, time) {
 	return getTimer(TIMER_THROTTLE, callback, time);
 }
-export { debounce, memoize, noop, throttle };
+export { debounce, memoize, noop, once, throttle };

package/dist/function/once.js

@@ -0,0 +1,97 @@
+import { assert } from "./assert.js";
+/**
+* Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+* @param callback Callback to use once
+* @returns Once callback
+*/
+function asyncOnce(callback) {
+	assert(() => typeof callback === "function", MESSAGE_EXPECTATION);
+	const state = {
+		called: false,
+		cleared: false,
+		error: false,
+		finished: false,
+		items: [],
+		value: void 0
+	};
+	const fn = (...parameters) => {
+		if (state.cleared) return Promise.reject(new Error(MESSAGE_CLEARED));
+		if (state.finished) return state.error ? Promise.reject(state.value) : Promise.resolve(state.value);
+		if (state.called) return new Promise((resolve, reject) => {
+			state.items.push({
+				reject,
+				resolve
+			});
+		});
+		state.called = true;
+		return new Promise((resolve, reject) => {
+			state.items.push({
+				reject,
+				resolve
+			});
+			callback(...parameters).then((value) => {
+				handleResult(state, value, false);
+			}).catch((error) => {
+				handleResult(state, error, true);
+			});
+		});
+	};
+	Object.defineProperties(fn, {
+		called: { get: () => state.called },
+		cleared: { get: () => state.cleared },
+		error: { get: () => state.error },
+		finished: { get: () => state.finished }
+	});
+	fn.clear = () => {
+		if (!state.called || !state.finished || state.cleared) return;
+		state.cleared = true;
+		state.value = void 0;
+	};
+	return fn;
+}
+function handleResult(state, value, error) {
+	state.error = error;
+	state.finished = true;
+	state.value = value;
+	const items = state.items.splice(0);
+	const { length } = items;
+	for (let index = 0; index < length; index += 1) {
+		const { reject, resolve } = items[index];
+		if (error) reject(value);
+		else resolve(value);
+	}
+}
+/**
+* Create a function that can only be called once, returning the same value on subsequent calls
+* @param callback Callback to use once
+* @returns Once callback
+*/
+function once(callback) {
+	assert(() => typeof callback === "function", MESSAGE_EXPECTATION);
+	const state = {
+		called: false,
+		cleared: false,
+		value: void 0
+	};
+	const fn = (...parameters) => {
+		if (state.cleared) throw new Error(MESSAGE_CLEARED);
+		if (state.called) return state.value;
+		state.called = true;
+		state.value = callback(...parameters);
+		return state.value;
+	};
+	Object.defineProperties(fn, {
+		called: { get: () => state.called },
+		cleared: { get: () => state.cleared }
+	});
+	fn.clear = () => {
+		if (!state.called || state.cleared) return;
+		state.cleared = true;
+		state.value = void 0;
+	};
+	return fn;
+}
+once.async = asyncOnce;
+var MESSAGE_CLEARED = "Once has been cleared";
+var MESSAGE_EXPECTATION = "Once expected a function";
+export { once };

package/dist/index.js

@@ -17,6 +17,7 @@ import { intersection } from "./array/intersection.js";
 import { partition } from "./array/partition.js";
 import { push } from "./array/push.js";
 import { select } from "./array/select.js";
+import { drop, slice, take } from "./array/slice.js";
 import { max } from "./internal/math/aggregate.js";
 import { getString, ignoreKey, join, tryDecode, tryEncode, words } from "./internal/string.js";
 import { compare } from "./internal/value/compare.js";
@@ -41,6 +42,7 @@ import { hslToHex, hslToRgb, hslToRgba } from "./color/space/hsl.js";
 import { getColor } from "./color/index.js";
 import { SizedMap } from "./sized/map.js";
 import { memoize } from "./function/memoize.js";
+import { once } from "./function/once.js";
 import { debounce, throttle } from "./function/index.js";
 import { RetryError, retry } from "./function/retry.js";
 import { isError, isOk, isResult } from "./internal/result.js";
@@ -75,4 +77,4 @@ import { QueueError, queue } from "./queue.js";
 import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomHex, getRandomItem, getRandomItems } from "./random.js";
 import { attempt } from "./result/index.js";
 import { SizedSet } from "./sized/set.js";
-export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, sum, take, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/package.json

@@ -10,7 +10,7 @@
 		"jsdom": "^28.1",
 		"oxfmt": "^0.36",
 		"oxlint": "^1.51",
-		"rolldown": "1.0.0-rc.6",
+		"rolldown": "1.0.0-rc.7",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
 		"vite": "8.0.0-beta.16",
@@ -184,5 +184,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.156.0"
-}
+	"version": "0.158.0"
+}

package/src/array/index.ts

@@ -15,6 +15,7 @@ export * from './intersection';
 export * from './partition';
 export * from './push';
 export * from './select';
+export * from './slice';
 export * from './sort';
 export * from './splice';
 export * from './to-set';

package/src/array/slice.ts

@@ -0,0 +1,245 @@
+import {getArrayCallbacks} from '../internal/array/callbacks';
+import type {PlainObject} from '../models';
+
+// #region Types
+
+type ExtractType = 'drop' | 'take';
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Drop items from the start of an array until they match a value
+ * @param array Original array
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns New array with items dropped
+ */
+export function drop<Item extends PlainObject, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): Item[];
+
+/**
+ * Drop items from the start of an array until they match a value
+ * @param array Original array
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @return New array with items dropped
+ */
+export function drop<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
+	array: Item[],
+	callback: Callback,
+	value: ReturnType<Callback>,
+): Item[];
+
+/**
+ * Drop items from the start of an array while they match a filter
+ * @param array Original array
+ * @param callback Filter callback to match items
+ * @return New array with items dropped
+ */
+export function drop<Item extends PlainObject>(
+	array: Item[],
+	callback: (item: Item, index: number, array: Item[]) => boolean,
+): Item[];
+
+/**
+ * Drop a specified number of items, from the start if `>= 0`, or from the end if `< 0`
+ * @param array Original array
+ * @param count Number of items to drop
+ * @returns New array with items dropped
+ */
+export function drop(array: unknown[], count: number): unknown[];
+
+export function drop(array: unknown[], first?: unknown, second?: unknown): unknown[] {
+	return extract(EXTRACT_DROP, array, first, second);
+}
+
+function extract(
+	type: ExtractType,
+	array: unknown[],
+	first?: unknown,
+	second?: unknown,
+): unknown[] {
+	if (!Array.isArray(array)) {
+		return [];
+	}
+
+	const {length} = array;
+
+	if (length === 0) {
+		return [];
+	}
+
+	const isTake = type === EXTRACT_TAKE;
+
+	if (typeof first === 'number') {
+		if (Math.abs(first) >= length) {
+			return isTake ? array.slice() : [];
+		}
+
+		if (first === 0) {
+			return isTake ? [] : array.slice();
+		}
+
+		if (isTake) {
+			return first >= 0 ? array.slice(0, first) : array.slice(array.length + first);
+		}
+
+		return first >= 0 ? array.slice(first) : array.slice(0, array.length + first);
+	}
+
+	const callbacks =
+		second == null ? getArrayCallbacks(first) : getArrayCallbacks(undefined, undefined, first);
+
+	const isBoolean = callbacks?.bool != null;
+
+	if (callbacks?.bool == null && callbacks?.value == null) {
+		return isTake ? array.slice() : [];
+	}
+
+	const extracted: unknown[] = [];
+
+	let push = false;
+
+	for (let index = 0; index < length; index += 1) {
+		const item = array[index];
+
+		const matches = isBoolean
+			? callbacks.bool!(item, index, array)
+			: Object.is(callbacks!.value!(item, index, array), second);
+
+		if (isTake) {
+			if (isBoolean ? !matches : matches) {
+				break;
+			}
+
+			extracted.push(item);
+
+			continue;
+		}
+
+		if (push) {
+			extracted.push(item);
+		} else if (isBoolean ? !matches : matches) {
+			push = true;
+
+			if (isBoolean) {
+				extracted.push(item);
+			}
+		}
+	}
+
+	return extracted;
+}
+
+/**
+ * Slice an array, returning a new array with a specified range of items
+ * @param array Original array
+ * @param start Start index _(inclusive)_
+ * @param end End index _(exclusive)_
+ * @return New array with sliced items
+ */
+export function slice<Item>(array: Item[], start: number, end: number): Item[];
+
+/**
+ * Slice an array, returning a new array with a specified number of items
+ * @param array Original array
+ * @param count Maximum sixe of the new array
+ * @return New array with sliced items
+ */
+export function slice<Item>(array: Item[], count: number): Item[];
+
+/**
+ * Slice an array
+ * @param array Array to slice
+ * @returns Sliced array
+ */
+export function slice<Item>(array: Item[]): Item[];
+
+export function slice(array: unknown[], first?: number, second?: number): unknown[] {
+	if (!Array.isArray(array) || array.length === 0) {
+		return [];
+	}
+
+	const firstIsNumber = typeof first === 'number';
+	const secondIsNumber = typeof second === 'number';
+
+	if (!firstIsNumber && !secondIsNumber) {
+		return array.slice();
+	}
+
+	if (!secondIsNumber) {
+		return first! >= 0 ? array.slice(0, first) : array.slice(array.length + first!);
+	}
+
+	if (!firstIsNumber) {
+		return array.slice();
+	}
+
+	return first! >= 0
+		? array.slice(first!, second!)
+		: array.slice(array.length + first!, array.length + second!);
+}
+
+/**
+ * Take items from the start of an array until they match a value
+ * @param array Original array
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns New array with taken items
+ */
+export function take<Item extends PlainObject, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): Item[];
+
+/**
+ * Take items from the start of an array until they match a value
+ * @param array Original array
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @return New array with taken items
+ */
+export function take<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
+	array: Item[],
+	callback: Callback,
+	value: ReturnType<Callback>,
+): Item[];
+
+/**
+ * Take items from the start of an array while they match a filter
+ * @param array Original array
+ * @param callback Filter callback to match items
+ * @return New array with taken items
+ */
+export function take<Item extends PlainObject>(
+	array: Item[],
+	callback: (item: Item, index: number, array: Item[]) => boolean,
+): Item[];
+
+/**
+ * Take a specified number of items, from the start if `>= 0`, or from the end if `< 0`
+ * @param array Original array
+ * @param count Number of items to take
+ * @returns New array with taken items
+ */
+export function take(array: unknown[], count: number): unknown[];
+
+export function take(array: unknown[], first?: unknown, second?: unknown): unknown[] {
+	return extract(EXTRACT_TAKE, array, first, second);
+}
+
+// #endregion
+
+// #region Variables
+
+const EXTRACT_DROP: ExtractType = 'drop';
+
+const EXTRACT_TAKE: ExtractType = 'take';
+
+// #endregion

package/src/function/index.ts

@@ -37,5 +37,6 @@ export function throttle<Callback extends GenericCallback>(
 
 export {noop} from '../internal/function/misc';
 export {memoize, type Memoized, type MemoizedOptions} from './memoize';
+export {once} from './once';
 
 // #endregion

package/src/function/once.ts

@@ -0,0 +1,188 @@
+import type {
+	GenericAsyncCallback,
+	GenericCallback,
+	OnceAsyncCallback,
+	OnceCallback,
+} from '../models';
+import {assert} from './assert';
+
+// #region Types
+
+type OnceAsyncItem<Value> = {
+	reject: (reason?: unknown) => void;
+	resolve: (value: Value) => void;
+};
+
+type OnceAsyncState<Value> = {
+	error: boolean;
+	finished: boolean;
+	items: OnceAsyncItem<Value>[];
+} & OnceState<Value>;
+
+type OnceState<Value> = {
+	called: boolean;
+	cleared: boolean;
+	value: Value;
+};
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+ * @param callback Callback to use once
+ * @returns Once callback
+ */
+function asyncOnce<Callback extends GenericAsyncCallback>(
+	callback: Callback,
+): OnceAsyncCallback<Callback> {
+	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);
+
+	const state: OnceAsyncState<Awaited<ReturnType<Callback>>> = {
+		called: false,
+		cleared: false,
+		error: false,
+		finished: false,
+		items: [],
+		value: undefined as never,
+	};
+
+	const fn = (...parameters: Parameters<Callback>): Promise<Awaited<ReturnType<Callback>>> => {
+		if (state.cleared) {
+			return Promise.reject(new Error(MESSAGE_CLEARED));
+		}
+
+		if (state.finished) {
+			return state.error ? Promise.reject(state.value) : Promise.resolve(state.value);
+		}
+
+		if (state.called) {
+			return new Promise<Awaited<ReturnType<Callback>>>((resolve, reject) => {
+				state.items.push({reject, resolve});
+			});
+		}
+
+		state.called = true;
+
+		return new Promise<Awaited<ReturnType<Callback>>>((resolve, reject) => {
+			state.items.push({reject, resolve});
+
+			void callback(...parameters)
+				.then(value => {
+					handleResult(state, value, false);
+				})
+				.catch(error => {
+					handleResult(state, error, true);
+				});
+		});
+	};
+
+	Object.defineProperties(fn, {
+		called: {
+			get: (): boolean => state.called,
+		},
+		cleared: {
+			get: (): boolean => state.cleared,
+		},
+		error: {
+			get: (): boolean => state.error,
+		},
+		finished: {
+			get: (): boolean => state.finished,
+		},
+	});
+
+	fn.clear = (): void => {
+		if (!state.called || !state.finished || state.cleared) {
+			return;
+		}
+
+		state.cleared = true;
+		state.value = undefined as never;
+	};
+
+	return fn as OnceAsyncCallback<Callback>;
+}
+
+function handleResult<Value>(state: OnceAsyncState<Value>, value: unknown, error: boolean): void {
+	state.error = error;
+	state.finished = true;
+	state.value = value as Value;
+
+	const items = state.items.splice(0);
+	const {length} = items;
+
+	for (let index = 0; index < length; index += 1) {
+		const {reject, resolve} = items[index];
+
+		if (error) {
+			reject(value);
+		} else {
+			resolve(value as Value);
+		}
+	}
+}
+
+/**
+ * Create a function that can only be called once, returning the same value on subsequent calls
+ * @param callback Callback to use once
+ * @returns Once callback
+ */
+export function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback> {
+	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);
+
+	const state: OnceState<ReturnType<Callback>> = {
+		called: false,
+		cleared: false,
+		value: undefined as never,
+	};
+
+	const fn = (...parameters: Parameters<Callback>): ReturnType<Callback> => {
+		if (state.cleared) {
+			throw new Error(MESSAGE_CLEARED);
+		}
+
+		if (state.called) {
+			return state.value;
+		}
+
+		state.called = true;
+
+		state.value = callback(...parameters);
+
+		return state.value;
+	};
+
+	Object.defineProperties(fn, {
+		called: {
+			get: (): boolean => state.called,
+		},
+		cleared: {
+			get: (): boolean => state.cleared,
+		},
+	});
+
+	fn.clear = (): void => {
+		if (!state.called || state.cleared) {
+			return;
+		}
+
+		state.cleared = true;
+		state.value = undefined as never;
+	};
+
+	return fn as OnceCallback<Callback>;
+}
+
+once.async = asyncOnce;
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE_CLEARED = 'Once has been cleared';
+
+const MESSAGE_EXPECTATION = 'Once expected a function';
+
+// #endregion

package/src/models.ts

@@ -140,6 +140,41 @@ export type NumericalValues<Item extends PlainObject> = {
 	[Key in keyof Item as Item[Key] extends number ? Key : never]: Item[Key];
 };
 
+/**
+ * An asynchronous function that can only be called once, returning the same value on subsequent calls
+ */
+export type OnceAsyncCallback<Callback extends GenericAsyncCallback> = {
+	/**
+	 * Did the callback's promise reject?
+	 */
+	readonly error: boolean;
+	/**
+	 * Has the callback finished?
+	 */
+	readonly finished: boolean;
+} & Callback &
+	OnceCallbackProperties;
+
+/**
+ * A callback function that can only be called once, returning the same value on subsequent calls
+ */
+export type OnceCallback<Callback extends GenericCallback> = Callback & OnceCallbackProperties;
+
+type OnceCallbackProperties = {
+	/**
+	 * Has the callback been called?
+	 */
+	readonly called: boolean;
+	/**
+	 * Has the callback's value been cleared?
+	 */
+	readonly cleared: boolean;
+	/**
+	 * Clear the callback's cached value
+	 */
+	clear: () => void;
+};
+
 /**
  * A generic object
  */

package/types/array/index.d.ts

@@ -14,6 +14,7 @@ export * from './intersection';
 export * from './partition';
 export * from './push';
 export * from './select';
+export * from './slice';
 export * from './sort';
 export * from './splice';
 export * from './to-set';