@oscarpalmer/atoms 0.193.0 → 0.194.0

package/src/array/find.ts

@@ -1,183 +0,0 @@
-import {FIND_VALUE_ITEM, findValue} from '../internal/array/find';
-import type {PlainObject} from '../models';
-
-// #region Functions
-
-/**
- * Get the first item matching the given value
- *
- * @param array Array to search in
- * @param callback Callback to get an item's value for matching
- * @param value Value to match against
- * @returns First item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * find(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   10,
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function find<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
-	array: Item[],
-	callback: Callback,
-	value: ReturnType<Callback>,
-): Item | undefined;
-
-/**
- * Get the first item matching the given value by key
- *
- * @param array Array to search in
- * @param key Key to get an item's value for matching
- * @param value Value to match against
- * @returns First item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * find(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   10,
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function find<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
-): Item | undefined;
-
-/**
- * Get the first item matching the filter
- *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @returns First item that matches the filter, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * find(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value === 10,
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function find<Item>(
-	array: Item[],
-	filter: (item: Item, index: number, array: Item[]) => boolean,
-): Item | undefined;
-
-/**
- * Get the first item matching the given value
- *
- * @param array Array to search in
- * @param value Value to match against
- * @returns First item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * find([1, 2, 3, 2, 1], 1); // => 1
- * ```
- */
-export function find<Item>(array: Item[], value: Item): Item | undefined;
-
-export function find(array: unknown[], ...parameters: unknown[]): unknown {
-	return findValue(FIND_VALUE_ITEM, array, parameters, false);
-}
-
-find.last = findLast;
-
-/**
- * Get the last item matching the given value
- *
- * _Available as `findLast` and `find.last`_
- *
- * @param array Array to search in
- * @param callback Callback to get an item's value for matching
- * @param value Value to match against
- * @returns Last item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * findLast(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   10,
- * ); // => {id: 3, value: 10}
- * ```
- */
-export function findLast<
-	Item,
-	Callback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], callback: Callback, value: ReturnType<Callback>): Item | undefined;
-
-/**
- * Get the last item matching the given value by key
- *
- * _Available as `findLast` and `find.last`_
- *
- * @param array Array to search in
- * @param key Key to get an item's value for matching
- * @param value Value to match against
- * @returns Last item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * findLast(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   10,
- * ); // => {id: 3, value: 10}
- * ```
- */
-export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
-): Item | undefined;
-
-/**
- * Get the last item matching the filter
- *
- * _Available as `findLast` and `find.last`_
- *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @returns Last item that matches the filter, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * findLast(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value === 10,
- * ); // => {id: 3, value: 10}
- * ```
- */
-export function findLast<Item>(
-	array: Item[],
-	filter: (item: Item, index: number, array: Item[]) => boolean,
-): Item | undefined;
-
-/**
- * Get the last item matching the given value
- *
- * _Available as `findLast` and `find.last`_
- *
- * @param array Array to search in
- * @param value Value to match against
- * @returns Last item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * findLast([1, 2, 3, 2, 1], 1); // => 1
- * ```
- */
-export function findLast<Item>(array: Item[], value: Item): Item | undefined;
-
-export function findLast(array: unknown[], ...parameters: unknown[]): unknown {
-	return findValue(FIND_VALUE_ITEM, array, parameters, true);
-}
-
-// #endregion

package/src/array/first.ts

@@ -1,196 +0,0 @@
-import {findAbsoluteValueOrDefault} from '../internal/array/find';
-import type {PlainObject} from '../models';
-
-// #region Functions
-
-/**
- * Get the first item matching the given value
- *
- * @param array Array to search in
- * @param callback Callback to get an item's value for matching
- * @param value Value to match against
- * @returns First item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * first(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   10,
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function first<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
-	array: Item[],
-	callback: Callback,
-	value: ReturnType<Callback>,
-): Item | undefined;
-
-/**
- * Get the first item matching the given value by key
- *
- * @param array Array to search in
- * @param key Key to get an item's value for matching
- * @param value Value to match against
- * @returns First item that matches the value, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * first(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   10,
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function first<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
-): Item | undefined;
-
-/**
- * Get the first item matching the filter
- *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @returns First item that matches the filter, or `undefined` if no match is found
- *
- * @example
- * ```typescript
- * first(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value === 10,
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function first<Item>(
-	array: Item[],
-	filter: (item: Item, index: number, array: Item[]) => boolean,
-): Item | undefined;
-
-/**
- * Get the first item from an array
- *
- * @param array Array to get from
- * @returns First item from the array, or `undefined` if the array is empty
- *
- * @example
- * ```typescript
- * first(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- * ); // => {id: 1, value: 10}
- * ```
- */
-export function first<Item>(array: Item[]): Item | undefined;
-
-export function first(array: unknown[], ...parameters: unknown[]): unknown {
-	return findAbsoluteValueOrDefault(array, parameters, undefined, false, false);
-}
-
-first.default = firstOrDefault;
-
-/**
- * Get the first item matching the given value, or a default value if no match is found
- *
- * _Available as `firstOrDefault` and `first.default`_
- *
- * @param array Array to search in
- * @param defaultValue Default value to return if no match is found
- * @param callback Callback to get an item's value for matching
- * @param value Value to match against
- * @returns First item that matches the value, or the default value if no match is found
- *
- * @example
- * ```typescript
- * firstOrDefault(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   {id: -1, value: 30},
- *   item => item.value,
- *   30,
- * ); // => {id: -1, value: 30}
- * ```
- */
-export function firstOrDefault<
-	Item,
-	Callback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], defaultValue: Item, callback: Callback, value: ReturnType<Callback>): Item;
-
-/**
- * Get the first item matching the given value by key, or a default value if no match is found
- *
- * _Available as `firstOrDefault` and `first.default`_
- *
- * @param array Array to search in
- * @param defaultValue Default value to return if no match is found
- * @param key Key to get an item's value for matching
- * @param value Value to match against
- * @returns First item that matches the value, or the default value if no match is found
- *
- * @example
- * ```typescript
- * firstOrDefault(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   {id: -1, value: 30},
- *   'value',
- *   30,
- * ); // => {id: -1, value: 30}
- * ```
- */
-export function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	defaultValue: Item,
-	key: ItemKey,
-	value: Item[ItemKey],
-): Item;
-
-/**
- * Get the first item matching the filter, or a default value if no match is found
- *
- * _Available as `firstOrDefault` and `first.default`_
- *
- * @param array Array to search in
- * @param defaultValue Default value to return if no match is found
- * @param filter Filter callback to match items
- * @returns First item that matches the filter, or the default value if no match is found
- *
- * @example
- * ```typescript
- * firstOrDefault(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   {id: -1, value: 30},
- *   item => item.value === 30,
- * ); // => {id: -1, value: 30}
- * ```
- */
-export function firstOrDefault<Item>(
-	array: Item[],
-	defaultValue: Item,
-	filter: (item: Item, index: number, array: Item[]) => boolean,
-): Item;
-
-/**
- * Get the first item from an array, or a default value if the array is empty
- *
- * _Available as `firstOrDefault` and `first.default`_
- *
- * @param array Array to get from
- * @param defaultValue Default value to return if the array is empty
- * @returns First item from the array, or the default value if the array is empty
- *
- * @example
- * ```typescript
- * firstOrDefault([], {id: -1, value: 30}); // => {id: -1, value: 30}
- * ```
- */
-export function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
-
-export function firstOrDefault(
-	array: unknown[],
-	defaultValue: unknown,
-	...parameters: unknown[]
-): unknown {
-	return findAbsoluteValueOrDefault(array, parameters, defaultValue, true, false);
-}
-
-// #endregion

package/src/array/flatten.ts

@@ -1,20 +0,0 @@
-import type {NestedArray} from '../models';
-
-// #region Functions
-
-/**
- * Flatten an array _(using native `flat` and maximum depth)_
- *
- * @param array Array to flatten
- * @returns Flattened array
- *
- * @example
- * ```typescript
- * flatten([1, [2, [3, 4], 5], 6]); // => [1, 2, 3, 4, 5, 6]
- * ```
- */
-export function flatten<Item>(array: Item[]): NestedArray<Item>[] {
-	return (Array.isArray(array) ? array.flat(Number.POSITIVE_INFINITY) : []) as NestedArray<Item>[];
-}
-
-// #endregion

package/src/array/from.ts

@@ -1,129 +0,0 @@
-// #region Functions
-
-/**
- * Get an array with a specified length, filled with indices
- *
- * @param length Length of the array
- * @returns Array of indices
- *
- * @example
- * ```typescript
- * range(5); // => [0, 1, 2, 3, 4]
- * ```
- */
-export function range(length: number): number[];
-
-/**
- * Get an array of numbers in a specified range
- *
- * @param start Starting number _(inclusive)_
- * @param end Ending number _(exclusive)_
- * @returns Array of numbers in range
- *
- * @example
- * ```typescript
- * range(2, 5); // => [2, 3, 4]
- * ```
- */
-export function range(start: number, end: number): number[];
-
-/**
- * Get an array of numbers in a specified range with a specified step
- *
- * @param start Starting number _(inclusive)_
- * @param end Ending number _(exclusive)_
- * @param step Step between numbers
- * @returns Array of numbers in range
- *
- * @example
- * ```typescript
- * range(0, 10, 2); // => [0, 2, 4, 6, 8]
- * ```
- */
-export function range(start: number, end: number, step: number): number[];
-
-export function range(first: number, second?: number, third?: number): number[] {
-	const start = typeof second === 'number' ? first : 0;
-	const end = typeof second === 'number' ? second : first;
-	const step = typeof third === 'number' ? third : 1;
-
-	const values: number[] = [];
-
-	if (step === 0) {
-		return values;
-	}
-
-	if (step > 0) {
-		for (let i = start; i < end; i += step) {
-			values.push(i);
-		}
-	} else {
-		for (let i = start; i > end; i += step) {
-			values.push(i);
-		}
-	}
-
-	return values;
-}
-
-/**
- * Get an array with a specified length, filled with indices
- *
- * @param length Length of the array
- * @returns Array of indices
- *
- * @example
- * ```typescript
- * times(5); // => [0, 1, 2, 3, 4]
- * ```
- */
-export function times(length: number): number[];
-
-/**
- * Get an array with a specified length, filled by values from a callback
- *
- * @param length Length of the array
- * @param callback Callback function to generate values
- * @returns Array of values generated by the callback
- *
- * @example
- * ```typescript
- * times(5, index => index * 2); // => [0, 2, 4, 6, 8]
- * ```
- */
-export function times<Callback extends (index: number) => unknown>(
-	length: number,
-	callback: Callback,
-): ReturnType<Callback>[];
-
-/**
- * Get an array with a specified length, filled with a specified value
- *
- * @param length Length of the array
- * @param value Value to fill the array with
- * @returns Array filled with the specified value
- *
- * @example
- * ```typescript
- * times(5, 'a'); // => ['a', 'a', 'a', 'a', 'a']
- * ```
- */
-export function times<Value>(length: number, value: Value): Value[];
-
-export function times(length: number, value?: unknown): unknown[] {
-	if (typeof length !== 'number' || length <= 0) {
-		return [];
-	}
-
-	const isFunction = typeof value === 'function';
-
-	const values: unknown[] = [];
-
-	for (let index = 0; index < length; index += 1) {
-		values.push(isFunction ? (value as (index: number) => unknown)(index) : (value ?? index));
-	}
-
-	return values;
-}
-
-// #endregion

package/src/array/get.ts

@@ -1,131 +0,0 @@
-import {isNonPlainObject} from '../internal/is';
-import type {NumericalKeys, PlainObject} from '../models';
-
-// #region Functions
-
-/**
- * Get an array from an object, where only values with numerical keys will be included
- *
- * @param value Object to convert to an array
- * @returns Array holding the values of the object's numerical keys
- *
- * @example
- * ```typescript
- * getArray({0: 'a', 1: 'b', 2: 'c', d: 'd'}, true); // => ['a', 'b', 'c']
- * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}, true); // => []
- * ```
- */
-export function getArray<Value extends PlainObject>(
-	value: Value,
-	indiced: true,
-): Value[NumericalKeys<Value>][];
-
-/**
- * Get an array from a map
- *
- * @param value Map to convert to an array
- * @returns Array holding the entries of the map
- *
- * @example
- * ```typescript
- * getArray(
- *   new Map([['a', 1], ['b', 2], ['c', 3]]),
- * ); // => [['a', 1], ['b', 2], ['c', 3]]
- * ```
- */
-export function getArray<Key, Value>(map: Map<Key, Value>): [Key, Value][];
-
-/**
- * Get an array from an object
- *
- * @param value Object to convert to an array
- * @returns Array holding the values of the object
- *
- * @example
- * ```typescript
- * getArray({0: 'a', 1: 'b', 2: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
- * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
- * ```
- */
-export function getArray<Value extends PlainObject>(
-	value: Value,
-): [keyof Value, Value[keyof Value]][];
-
-/**
- * Get an array from a set
- *
- * @param value Set to convert to an array
- * @returns Array holding the values of the set
- *
- * @example
- * ```typescript
- * getArray(new Set([123, 456, 789])); // => [123, 456, 789]
- * ```
- */
-export function getArray<Value>(set: Set<Value>): Value[];
-
-/**
- * Get an array from a value
- *
- * @param value Original array
- * @returns Original array
- *
- * @example
- * ```typescript
- * getArray([123]); // => [123]
- * ```
- */
-export function getArray<Item>(value: Item[]): Item[];
-
-/**
- * Get an array from an unknown value
- *
- * @param value Value to convert to an array
- * @returns Array of value
- *
- * @example
- * ```typescript
- * getArray(123); // => [123]
- * ```
- */
-export function getArray<Value>(value: Value): Value[];
-
-export function getArray(value: unknown, indiced?: unknown): unknown[] {
-	if (Array.isArray(value)) {
-		return value;
-	}
-
-	if (value instanceof Map) {
-		return [...value.entries()];
-	}
-
-	if (value instanceof Set) {
-		return [...value.values()];
-	}
-
-	if (isNonPlainObject(value)) {
-		return [value];
-	}
-
-	if (indiced !== true) {
-		return Object.entries(value);
-	}
-
-	const keys = Object.keys(value);
-	const {length} = keys;
-
-	const array: unknown[] = [];
-
-	for (let index = 0; index < length; index += 1) {
-		const key = keys[index];
-		const asNumber = Number.parseInt(key, 10);
-
-		if (!Number.isNaN(asNumber)) {
-			array[asNumber] = (value as Record<string, unknown>)[key];
-		}
-	}
-
-	return array;
-}
-
-// #endregion