@oscarpalmer/atoms 0.192.0 → 0.193.1

package/src/array/filter.ts

@@ -1,182 +0,0 @@
-import {FIND_VALUES_ALL, findValues} from '../internal/array/find';
-import type {PlainObject} from '../models';
-
-// #region Functions
-
-/**
- * Get a filtered array of items that do not match the value
- *
- * _Available as `exclude` and `filter.remove`_
- *
- * @param array Array to search in
- * @param callback Callback to get an item's value for matching
- * @param value Value to match against
- * @returns Filtered array of items that do not match the filter
- *
- * @example
- * ```typescript
- * exclude(
- *   [{id: 1}, {id: 2}, {id: 3}],
- *   item => item.id,
- *   2,
- * ); // => [{id: 1}, {id: 3}]
- * ```
- */
-export function exclude<
-	Item,
-	Callback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
-
-/**
- * Get a filtered array of items that do not match the value
- *
- * _Available as `exclude` and `filter.remove`_
- *
- * @param array Array to search in
- * @param key Key to get an item's value for matching
- * @param value Value to match against
- * @returns Filtered array of items that do not match the filter
- *
- * @example
- * ```typescript
- * exclude(
- *   [{id: 1}, {id: 2}, {id: 3}],
- *   'id',
- *   2,
- * ); // => [{id: 1}, {id: 3}]
- * ```
- */
-export function exclude<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
-): unknown[];
-
-/**
- * Get a filtered array of items that do not match the filter
- *
- * _Available as `exclude` and `filter.remove`_
- *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @returns Filtered array of items that do not match the filter
- *
- * @example
- * ```typescript
- * exclude(
- *   [{id: 1}, {id: 2}, {id: 3}],
- *   item => item.id === 2,
- * ); // => [{id: 1}, {id: 3}]
- * ```
- */
-export function exclude<Item>(
-	array: Item[],
-	filter: (item: Item, index: number, array: Item[]) => boolean,
-): unknown[];
-
-/**
- * Get a filtered array of items that do not match the given item
- *
- * _Available as `exclude` and `filter.remove`_
- *
- * @param array Array to search in
- * @param item Item to match against
- * @returns Filtered array of items that do not match the given item
- *
- * @example
- * ```typescript
- * exclude([1, 2, 3], 2); // => [1, 3]
- * ```
- */
-export function exclude<Item>(array: Item[], item: Item): unknown[];
-
-export function exclude(array: unknown[], ...parameters: unknown[]): unknown[] {
-	return findValues(FIND_VALUES_ALL, array, parameters).notMatched;
-}
-
-/**
- * Get a filtered array of items
- *
- * @param array Array to search in
- * @param callback Callback to get an item's value for matching
- * @param value Value to match against
- * @returns Filtered array of items
- *
- * @example
- * ```typescript
- * filter(
- *   [{id: 1}, {id: 2}, {id: 3}],
- *   item => item.id,
- *   2,
- * ); // => [{id: 2}]
- * ```
- */
-export function filter<
-	Item,
-	Callback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
-
-/**
- * Get a filtered array of items
- *
- * @param array Array to search in
- * @param key Key to get an item's value for matching
- * @param value Value to match against
- * @returns Filtered array of items
- *
- * @example
- * ```typescript
- * filter(
- *   [{id: 1}, {id: 2}, {id: 3}],
- *   'id',
- *   2,
- * ); // => [{id: 2}]
- * ```
- */
-export function filter<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
-): Item[];
-
-/**
- * Get a filtered array of items matching the filter
- *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @returns Filtered array of items
- *
- * @example
- * ```typescript
- * filter(
- *   [{id: 1}, {id: 2}, {id: 3}],
- *   item => item.id === 2,
- * ); // => [{id: 2}]
- * ```
- */
-export function filter<Item>(
-	array: Item[],
-	filter: (item: Item, index: number, array: Item[]) => boolean,
-): Item[];
-
-/**
- * Get a filtered array of items matching the given item
- *
- * @param array Array to search in
- * @param item Item to match against
- * @returns Filtered array of items
- *
- * @example
- * ```typescript
- * filter([1, 2, 3], 2); // => [2]
- * ```
- */
-export function filter<Item>(array: Item[], item: Item): Item[];
-
-export function filter(array: unknown[], ...parameters: unknown[]): unknown[] {
-	return findValues(FIND_VALUES_ALL, array, parameters).matched;
-}
-
-filter.remove = exclude;
-
-// #endregion

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