@oscarpalmer/atoms 0.158.0 → 0.160.0

package/src/array/position.ts

@@ -0,0 +1,303 @@
+// #region Types
+
+import {getArrayCallback} from '../internal/array/callbacks';
+import type {PlainObject} from '../models';
+
+export type ArrayPosition = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Does the needle array end the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return `true` if the haystack ends with the needle, otherwise `false`
+ */
+export function endsWithArray<Item extends PlainObject>(
+	haystack: Item[],
+	needle: Item[],
+	key: keyof Item,
+): boolean;
+
+/**
+ * Does the needle array end the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return `true` if the haystack ends with the needle, otherwise `false`
+ */
+export function endsWithArray<Item>(
+	haystack: Item[],
+	needle: Item[],
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): boolean;
+
+/**
+ * Does the needle array end the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return `true` if the haystack ends with the needle, otherwise `false`
+ */
+export function endsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
+
+export function endsWithArray(haystack: unknown[], needle: unknown[], key?: unknown): boolean {
+	return endings.has(getPosition(haystack, needle, key)[1]);
+}
+
+/**
+ * Get the position of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @returns Position of the needle within the haystack
+ */
+export function getArrayPosition<Item extends PlainObject>(
+	haystack: Item[],
+	needle: Item[],
+	key: keyof Item,
+): ArrayPosition;
+
+/**
+ * Get the position of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @returns Position of the needle within the haystack
+ */
+export function getArrayPosition<Item>(
+	haystack: Item[],
+	needle: Item[],
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): ArrayPosition;
+
+/**
+ * Get the position of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @returns Position of the needle within the haystack
+ */
+export function getArrayPosition<Item>(haystack: Item[], needle: Item[]): ArrayPosition;
+
+export function getArrayPosition(
+	haystack: unknown[],
+	needle: unknown[],
+	key?: unknown,
+): ArrayPosition {
+	return getPosition(haystack, needle, key)[1];
+}
+
+function getName(start: number, haystack: number, needle: number): ArrayPosition {
+	if (start === 0) {
+		return haystack === needle ? POSITION_SAME : POSITION_START;
+	}
+
+	return start + needle === haystack ? POSITION_END : POSITION_INSIDE;
+}
+
+function getPosition(
+	haystack: unknown[],
+	needle: unknown[],
+	key?: unknown,
+): readonly [number, ArrayPosition] {
+	if (!Array.isArray(haystack) || !Array.isArray(needle)) {
+		return invalid;
+	}
+
+	const haystackLength = haystack.length;
+	const needleLength = needle.length;
+
+	if (haystackLength === 0 || needleLength === 0) {
+		return outside;
+	}
+
+	if (needleLength > haystackLength) {
+		return outside;
+	}
+
+	const callback = getArrayCallback(key);
+
+	const limit = haystackLength - needleLength + 1;
+
+	let needleValues = callback == null ? needle : needle.slice();
+
+	if (callback != null) {
+		for (let needleIndex = 0; needleIndex < needleLength; needleIndex += 1) {
+			needleValues[needleIndex] = callback(needle[needleIndex], needleIndex, needle);
+		}
+	}
+
+	for (let haystackIndex = 0; haystackIndex < limit; haystackIndex += 1) {
+		let haystackItem = haystack[haystackIndex];
+		let haystackValue = callback?.(haystackItem, haystackIndex, haystack) ?? haystackItem;
+
+		if (!Object.is(haystackValue, needleValues[0])) {
+			continue;
+		}
+
+		if (needleLength === 1) {
+			return [haystackIndex, getName(haystackIndex, haystackLength, needleLength)];
+		}
+
+		for (let needleIndex = 1; needleIndex < needleLength; needleIndex += 1) {
+			haystackItem = haystack[haystackIndex + needleIndex];
+
+			haystackValue =
+				callback?.(haystackItem, haystackIndex + needleIndex, haystack) ?? haystackItem;
+
+			if (!Object.is(haystackValue, needleValues[needleIndex])) {
+				break;
+			}
+
+			if (needleIndex === needleLength - 1) {
+				return [haystackIndex, getName(haystackIndex, haystackLength, needleLength)];
+			}
+		}
+	}
+
+	return outside;
+}
+
+/**
+ * Does the needle array exist within the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return `true` if the haystack includes the needle, otherwise `false`
+ */
+export function includesArray<Item extends PlainObject>(
+	haystack: Item[],
+	needle: Item[],
+	key: keyof Item,
+): boolean;
+
+/**
+ * Does the needle array exist within the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return `true` if the haystack includes the needle, otherwise `false`
+ */
+export function includesArray<Item>(
+	haystack: Item[],
+	needle: Item[],
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): boolean;
+
+/**
+ * Does the needle array exist within the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return `true` if the haystack includes the needle, otherwise `false`
+ */
+export function includesArray<Item>(haystack: Item[], needle: Item[]): boolean;
+
+export function includesArray(haystack: unknown[], needle: unknown[], key?: unknown): boolean {
+	return !outsides.has(getPosition(haystack, needle, key)[1]);
+}
+
+/**
+ * Get the index of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ */
+export function indexOfArray<Item extends PlainObject>(
+	haystack: Item[],
+	needle: Item[],
+	key: keyof Item,
+): number;
+
+/**
+ * Get the index of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ */
+export function indexOfArray<Item>(
+	haystack: Item[],
+	needle: Item[],
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): number;
+
+/**
+ * Get the index of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ */
+export function indexOfArray<Item>(haystack: Item[], needle: Item[]): number;
+
+export function indexOfArray(haystack: unknown[], needle: unknown[], key?: unknown): number {
+	return getPosition(haystack, needle, key)[0];
+}
+
+/**
+ * Does the needle array start the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return `true` if the haystack starts with the needle, otherwise `false`
+ */
+export function startsWithArray<Item extends PlainObject>(
+	haystack: Item[],
+	needle: Item[],
+	key: keyof Item,
+): boolean;
+
+/**
+ * Does the needle array start the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return `true` if the haystack starts with the needle, otherwise `false`
+ */
+export function startsWithArray<Item>(
+	haystack: Item[],
+	needle: Item[],
+	callback: (item: Item, index: number, array: Item[]) => unknown,
+): boolean;
+
+/**
+ * Does the needle array start the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return `true` if the haystack starts with the needle, otherwise `false`
+ */
+export function startsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
+
+export function startsWithArray(haystack: unknown[], needle: unknown[], key?: unknown): boolean {
+	return starts.has(getPosition(haystack, needle, key)[1]);
+}
+
+// #endregion
+
+// #region Variables
+
+const POSITION_END: ArrayPosition = 'end';
+
+const POSITION_INSIDE: ArrayPosition = 'inside';
+
+const POSITION_INVALID: ArrayPosition = 'invalid';
+
+const POSITION_OUTSIDE: ArrayPosition = 'outside';
+
+const POSITION_SAME: ArrayPosition = 'same';
+
+const POSITION_START: ArrayPosition = 'start';
+
+const endings = new Set<ArrayPosition>([POSITION_END, POSITION_SAME]);
+
+const invalid = [-1, POSITION_INVALID] as const;
+
+const outside = [-1, POSITION_OUTSIDE] as const;
+
+const outsides = new Set<ArrayPosition>([POSITION_INVALID, POSITION_OUTSIDE]);
+
+const starts = new Set<ArrayPosition>([POSITION_START, POSITION_SAME]);
+
+// #endregion

package/src/internal/array/sets.ts

@@ -23,11 +23,11 @@ export function compareSets(
 	const isUnion = type === COMPARE_SETS_UNION;
 
 	if (first.length === 0) {
-		return isDifference ? [...first] : isIntersection ? [] : [...second];
+		return isDifference ? first.slice() : isIntersection ? [] : second.slice();
 	}
 
 	if (!Array.isArray(second) || second.length === 0) {
-		return isIntersection ? [] : [...first];
+		return isIntersection ? [] : first.slice();
 	}
 
 	const callback = getArrayCallback(key);
@@ -47,7 +47,7 @@ export function compareSets(
 
 	length = source.length;
 
-	const result: unknown[] = isUnion ? [...first] : [];
+	const result: unknown[] = isUnion ? first.slice() : [];
 
 	for (let index = 0; index < length; index += 1) {
 		const item = source[index];

package/src/internal/array/shuffle.ts

@@ -12,7 +12,7 @@ export function shuffle<Item>(array: Item[]): Item[] {
 		return [];
 	}
 
-	const shuffled = [...array];
+	const shuffled = array.slice();
 
 	if (shuffled.length < 2) {
 		return shuffled;

package/src/promise/helpers.ts

@@ -1,14 +1,16 @@
 import type {RequiredKeys} from '../models';
+import {error, ok} from '../result';
+import type {Result} from '../result/models';
 import {
-	PROMISE_STRATEGY_DEFAULT,
 	PROMISE_STRATEGY_ALL,
+	PROMISE_STRATEGY_DEFAULT,
 	PROMISE_TYPE_FULFILLED,
 	PROMISE_TYPE_REJECTED,
 	type FulfilledPromise,
 	type PromiseOptions,
 	type PromisesOptions,
-	type PromisesResultItem,
 	type PromiseStrategy,
+	type PromisesValue,
 	type RejectedPromise,
 } from './models';
 
@@ -56,6 +58,14 @@ export function getPromisesOptions(input: unknown): RequiredKeys<PromisesOptions
 	};
 }
 
+export function getResultsFromPromises<Value>(
+	promised: PromisesValue<Value>[],
+): Result<Value>[] {
+	return promised.map(result =>
+		isFulfilled(result) ? ok(result.value) : error(result.reason),
+	) as Result<Value>[];
+}
+
 export function getStrategyOrDefault(value: unknown): PromiseStrategy {
 	return PROMISE_STRATEGY_ALL.has(value as PromiseStrategy)
 		? (value as PromiseStrategy)
@@ -84,7 +94,7 @@ function isType(value: unknown, type: string): boolean {
 	return (
 		typeof value === 'object' &&
 		value !== null &&
-		(value as PromisesResultItem<unknown>).status === type
+		(value as PromisesValue<unknown>).status === type
 	);
 }
 

package/src/promise/index.ts

@@ -1,4 +1,5 @@
-import {getPromiseOptions, getPromisesOptions} from './helpers';
+import type {Result} from '../result/models';
+import {getPromiseOptions, getPromisesOptions, getResultsFromPromises} from './helpers';
 import {handleResult, settlePromise} from './misc';
 import {
 	PROMISE_ABORT_OPTIONS,
@@ -11,9 +12,11 @@ import {
 	type PromiseData,
 	type PromiseHandlers,
 	type PromiseOptions,
-	type Promises,
+	type PromisesItems,
 	type PromisesOptions,
 	type PromisesResult,
+	type PromisesValue,
+	type PromisesValues,
 } from './models';
 import {getTimedPromise} from './timed';
 
@@ -111,9 +114,22 @@ export async function attemptPromise<Value>(
  * @returns List of results
  */
 export async function promises<Items extends unknown[], Options extends PromisesOptions>(
-	items: Promises<Items>,
+	items: [...Items],
 	options?: Options,
-): Promise<Options['strategy'] extends 'first' ? Items : PromisesResult<Items>>;
+): Promise<Options['strategy'] extends 'first' ? Items : PromisesValues<PromisesItems<Items>>>;
+
+/**
+ * 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
+ * @returns List of results
+ */
+export async function promises<Value, Options extends PromisesOptions>(
+	items: Promise<Value>[],
+	options?: Options,
+): Promise<Options['strategy'] extends 'first' ? Value[] : PromisesValue<Value>[]>;
 
 /**
  * Handle a list of promises, returning their results in an ordered array.
@@ -124,9 +140,19 @@ export async function promises<Items extends unknown[], Options extends Promises
  * @returns List of results
  */
 export async function promises<Items extends unknown[]>(
-	items: Promises<Items>,
+	items: [...Items],
 	strategy: 'first',
-): Promise<Items>;
+): Promise<PromisesItems<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
+ * @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
@@ -135,14 +161,22 @@ export async function promises<Items extends unknown[]>(
  * @returns List of results
  */
 export async function promises<Items extends unknown[]>(
-	items: Promises<Items>,
+	items: [...Items],
 	signal?: AbortSignal,
-): Promise<PromisesResult<Items>>;
+): Promise<PromisesValues<PromisesItems<Items>>>;
 
-export async function promises<Items extends unknown[]>(
-	items: Promises<Items>,
-	options?: unknown,
-): Promise<Items | PromisesResult<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)_
+ * @returns List of results
+ */
+export async function promises<Value>(
+	items: Promise<Value>[],
+	signal?: AbortSignal,
+): Promise<PromisesValue<Value>[]>;
+
+export async function promises(items: unknown[], options?: unknown): Promise<unknown[]> {
 	const {signal, strategy} = getPromisesOptions(options);
 
 	if (signal?.aborted ?? false) {
@@ -157,7 +191,7 @@ export async function promises<Items extends unknown[]>(
 	const {length} = actual;
 
 	if (length === 0) {
-		return actual as unknown as Items | PromisesResult<Items>;
+		return Promise.reject(new TypeError(PROMISE_MESSAGE_EXPECTATION_PROMISES));
 	}
 
 	const complete = strategy === PROMISE_STRATEGY_DEFAULT;
@@ -168,12 +202,12 @@ export async function promises<Items extends unknown[]>(
 
 	signal?.addEventListener('abort', abort, PROMISE_ABORT_OPTIONS);
 
-	const data: PromiseData<Items> = {
+	const data: PromiseData = {
 		last: length - 1,
-		result: [] as unknown as Items | PromisesResult<Items>,
+		result: [] as unknown[],
 	};
 
-	let handlers: PromiseHandlers<Items>;
+	let handlers: PromiseHandlers;
 
 	return new Promise((resolve, reject) => {
 		handlers = {reject, resolve};
@@ -206,6 +240,41 @@ export async function promises<Items extends unknown[]>(
 	});
 }
 
+promises.result = resultPromises;
+
+/**
+ * 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
+ * @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
+ */
+async function resultPromises<Items extends unknown[]>(
+	items: [...Items],
+	signal?: AbortSignal,
+): Promise<PromisesResult<PromisesItems<Items>>>;
+
+/**
+ * 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
+ * @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
+ */
+async function resultPromises<Value>(
+	items: Promise<Value>[],
+	signal?: AbortSignal,
+): Promise<Result<Awaited<Value>>[]>;
+
+async function resultPromises(
+	items: Promise<unknown>[],
+	signal?: AbortSignal,
+): Promise<Result<unknown>[]> {
+	return promises(items, signal).then(getResultsFromPromises);
+}
+
 // #endregion
 
 // #region Exports
@@ -218,12 +287,13 @@ export {
 	CancelablePromise,
 	PromiseTimeoutError,
 	type FulfilledPromise,
-	type RejectedPromise,
 	type PromiseOptions,
-	type PromiseStrategy,
 	type PromisesOptions,
 	type PromisesResult,
-	type PromisesResultItem,
+	type PromiseStrategy,
+	type PromisesValues as PromisesValue,
+	type PromisesValue as PromisesValueItem,
+	type RejectedPromise,
 } from './models';
 export {timed} from './timed';
 

package/src/promise/misc.ts

@@ -22,10 +22,7 @@ export function cancelable<Value>(
 	return new CancelablePromise(executor);
 }
 
-export function handleResult<Items extends unknown[]>(
-	status: string,
-	parameters: PromiseParameters<Items>,
-): void {
+export function handleResult(status: string, parameters: PromiseParameters): void {
 	const {abort, complete, data, handlers, index, signal, value} = parameters;
 
 	if (signal?.aborted ?? false) {

package/src/promise/models.ts

@@ -1,3 +1,5 @@
+import type {Result} from '../result/models';
+
 // #region Types
 
 export class CancelablePromise<Value = void> extends Promise<Value> {
@@ -28,16 +30,16 @@ export class CancelablePromise<Value = void> extends Promise<Value> {
 
 export type FulfilledPromise<Value> = {
 	status: typeof PROMISE_TYPE_FULFILLED;
-	value: Value;
+	value: Awaited<Value>;
 };
 
-export type PromiseData<Items extends unknown[]> = {
+export type PromiseData = {
 	last: number;
-	result: Items | PromisesResult<Items>;
+	result: unknown[];
 };
 
-export type PromiseHandlers<Items extends unknown[]> = {
-	resolve: (value: Items | PromisesResult<Items>) => void;
+export type PromiseHandlers = {
+	resolve: (value: unknown[]) => void;
 	reject: (reason: unknown) => void;
 };
 
@@ -52,11 +54,11 @@ export type PromiseOptions = {
 	time?: number;
 };
 
-export type PromiseParameters<Items extends unknown[]> = {
+export type PromiseParameters = {
 	abort: () => void;
 	complete: boolean;
-	data: PromiseData<Items>;
-	handlers: PromiseHandlers<Items>;
+	data: PromiseData;
+	handlers: PromiseHandlers;
 	index: number;
 	signal?: AbortSignal;
 	value?: unknown;
@@ -64,7 +66,7 @@ export type PromiseParameters<Items extends unknown[]> = {
 
 /**
  * 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
@@ -80,7 +82,7 @@ export class PromiseTimeoutError extends Error {
 	}
 }
 
-export type Promises<Items extends unknown[]> = {
+export type PromisesItems<Items extends unknown[]> = {
 	[K in keyof Items]: Promise<Items[K]>;
 };
 
@@ -90,10 +92,14 @@ export type PromisesOptions = {
 };
 
 export type PromisesResult<Items extends unknown[]> = {
-	[K in keyof Items]: Items[K] extends Promise<infer Value> ? PromisesResultItem<Value> : never;
+	[K in keyof Items]: Items[K] extends Promise<infer Value> ? Result<Awaited<Value>> : never;
 };
 
-export type PromisesResultItem<Value> = FulfilledPromise<Value> | RejectedPromise;
+export type PromisesValue<Value> = FulfilledPromise<Value> | RejectedPromise;
+
+export type PromisesValues<Items extends unknown[]> = {
+	[K in keyof Items]: Items[K] extends Promise<infer Value> ? PromisesValue<Awaited<Value>> : never;
+};
 
 export type RejectedPromise = {
 	status: typeof PROMISE_TYPE_REJECTED;

package/src/value/clone.ts

@@ -130,7 +130,7 @@ function clonePlainObject(
 	references: WeakMap<WeakKey, unknown>,
 ): ArrayOrPlainObject {
 	if (depth >= MAX_CLONE_DEPTH) {
-		return Array.isArray(value) ? [...value] : {...value};
+		return Array.isArray(value) ? value.slice() : {...value};
 	}
 
 	const cloned = (Array.isArray(value) ? [] : {}) as PlainObject;

package/src/value/smush.ts

@@ -44,7 +44,7 @@ function flattenObject(
 		if (isArrayOrPlainObject(val)) {
 			const prefixedKey = join([prefix, key], '.');
 
-			flattened[prefixedKey] = Array.isArray(val) ? [...val] : {...val};
+			flattened[prefixedKey] = Array.isArray(val) ? val.slice() : {...val};
 
 			const nested = flattenObject(val, depth + 1, smushed, prefixedKey);
 			const nestedKeys = Object.keys(nested);

package/src/value/unsmush.ts

@@ -77,7 +77,7 @@ export function unsmush<Value extends PlainObject>(value: Value): Unsmushed<Valu
 		let next = val;
 
 		if (isArrayOrPlainObject(val)) {
-			next = Array.isArray(val) ? [...val] : {...val};
+			next = Array.isArray(val) ? val.slice() : {...val};
 		}
 
 		setValue(unsmushed, key, next);

package/types/array/index.d.ts

@@ -12,6 +12,7 @@ export * from './index-of';
 export * from './insert';
 export * from './intersection';
 export * from './partition';
+export * from './position';
 export * from './push';
 export * from './select';
 export * from './slice';