@wezom/toolkit-array

Useful tools for working with Arrays

| Statements | Branches | Functions | Lines | | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | | | | |

Table of Content:

1. Tools
   1. arrayAddUnique()
   2. arrayClone()
   3. arrayFilterNullable()
   4. arrayFilterUnique()
   5. arrayGetFirstNotNullableItem()
   6. arrayRemoveByIndex()
   7. arrayRemoveItems()
   8. arraySimpleRandomFn()
   9. arrayToggleItem()
2. Contributing
3. License

Tools

arrayAddUnique()

Clones an array and puts only unique elements there

Parameters:

| Name | Data type | Argument | Default value | Description | | --------- | --------- | ---------- | ------------- | ----------- | | array | T[] | | | | items | T[] | | | | predicate | `` | optional | ... |

Returns: T[]

▲ Go Top | ▲ Table of Content

arrayClone()

Clones array for immutable tasks

Parameters:

| Name | Data type | Argument | Default value | Description | | ----- | --------- | -------- | ------------- | ----------- | | array | T[] | | |

Returns: T[]

▲ Go Top | ▲ Table of Content

arrayFilterNullable()

Filter null and undefined array items

Parameters:

| Name | Data type | Argument | Default value | Description | | --------- | --------------------------------- | ---------- | ------------- | ----------- | | data | (T │ null │ undefined)[] │ null | optional | | | predicate | `` | optional | ... |

Returns: R[]

Examples:

arrayFilterNullable([1, null, 2, undefined, 3, false, 0]); // => [1, 2, 3, false, 0]
arrayFilterNullable(null); // => []
arrayFilterNullable(); // => []

// Custom predicate. Use case example #1
interface A {
	x: string;
}
interface B {
	x: string;
	y: string;
}
const data: (A | B | null)[] | null = [{ x: '1' }, { x: '2' }, null, { x: '3', y: '4' }];
const result = arrayFilterNullable(
	data,
	(item): item is B => item != null && 'y' in item
);

// Custom predicate. Use case example #3
interface D {
	x: number;
	y: string;
}
type E = Partial<D>;
const data: (C | D | null)[] | null = [{ y: 1, x: '2' }, null, { x: '2' }, { y: 4 }];
const result = arrayFilterNullable(
	data,
	(item): item is D => item != null && item.y != null && item.x !== null
);

▲ Go Top | ▲ Table of Content

arrayFilterUnique()

Returns new array without duplicates

Parameters:

| Name | Data type | Argument | Default value | Description | | --------- | --------- | ---------- | ------------- | ----------- | | array | T[] | | | | predicate | `` | optional | ... |

Returns: T[]

Examples:

arrayFilterUnique([
	'🚗',
	'🛸',
	'🚐',
	'🚁',
	'🚁',
	'🚐',
	'🚐',
	'🛵',
	'🚁',
	'🛵',
	'🛸',
	'🚗'
]); // => ['🚗','🛸','🚐','🚁','🛵']
arrayFilterUnique([
	{ icon: '🚗' },
	{ icon: '🚐' },
	{ icon: '🚐' },
	{ icon: '🚗' },
	{ icon: '🚁' },
	{ icon: '🛵' },
	{ icon: '🚁' },
	{ icon: '🚁' },
	{ icon: '🛸' },
	{ icon: '🛵' },
	{ icon: '🛵' },
	{ icon: '🛵' },
	{ icon: '🚁' }
]); // => [{icon: '🚗'},{icon: '🚐'},{icon: '🚁'},{icon: '🛵'},{icon: '🛸'}]

▲ Go Top | ▲ Table of Content

arrayGetFirstNotNullableItem()

Getting first not nullable item from given array data

Parameters:

| Name | Data type | Argument | Default value | Description | | --------------- | --------------------- | ---------- | ------------- | ----------- | | data | (T │ null)[] │ null | optional | | | strictZeroIndex | boolean | optional | | | predicate | `` | optional | ... |

Returns: R │ undefined

Examples:

arrayGetFirstNotNullableItem([1, null, 2, undefined, 3, false, 0]); // => 1
arrayGetFirstNotNullableItem([null, null, undefined, 3, false, 0]); // => 3

// StrictZeroIndex example
arrayGetFirstNotNullableItem([1, null, 2, undefined, 3, false, 0], true); // => 1
arrayGetFirstNotNullableItem([null, null, undefined, 3, false, 0], true); // => undefined

// Nullable data example
arrayGetFirstNotNullableItem(null); // => undefined
arrayGetFirstNotNullableItem([null, undefined, null]); // => undefined

// -------------------

// Custom predicate
interface A {
	x: string;
	y: string;
}
type B = Partial<A>;

// must find on 2 index                ✕     ✕           ✔︎                   ✕
const data: (A | B | null)[] | null = [null, { x: '1' }, { x: '3', y: '4' }, { y: '2' }];
const result = arrayGetFirstNotNullableItem(
	data,
	false,
	(item): item is A => item != null && 'y' in item
);

// strict: check only 0 index          ✕           ✕      ✔︎                   ✕
const data: (A | B | null)[] | null = [{ x: '1' }, null, { x: '3', y: '4' }, { y: '2' }];
const result = arrayGetFirstNotNullableItem(
	data,
	true,
	(item): item is A => item != null && 'y' in item
);

▲ Go Top | ▲ Table of Content

arrayRemoveByIndex()

Clones an array and removes items by index

Parameters:

| Name | Data type | Argument | Default value | Description | | ----------- | --------- | ---------- | ------------- | ----------- | | array | T[] | | | | index | number | | | | deleteCount | number | optional | 1 |

Returns: T[]

Examples:

arrayRemoveByIndex(['A', 'B', 'C'], 1); // >>> ['A', 'C'];
arrayRemoveByIndex(['A', 'B', 'C', 'D', 'E'], 1, 3); // >>> ['A', 'E'];

▲ Go Top | ▲ Table of Content

arrayRemoveItems()

Clones an array and removes items

Parameters:

| Name | Data type | Argument | Default value | Description | | --------- | --------- | ---------- | ------------- | ----------- | | array | T[] | | | | items | T[] | | | | predicate | `` | optional | ... |

Returns: T[]

▲ Go Top | ▲ Table of Content

arraySimpleRandomFn()

Function for simple sorting of array elements in random order

Returns: number

▲ Go Top | ▲ Table of Content

arrayToggleItem()

Adds an element to an array or removes if the array already has such an element

Parameters:

| Name | Data type | Argument | Default value | Description | | --------- | --------- | ---------- | ------------- | ----------- | | array | T[] | | | | item | T | | | | predicate | `` | optional | ... |

Returns: T[]

Examples:

arrayToggleItem([1, 2, 3], 9); // => [1, 2, 3, 9]
arrayToggleItem([1, 2, 3, 9], 2); // => [1, 3, 9]
arrayToggleItem([{ x: 1 }, { x: 2 }, { x: 3 }], { x: 2 }, (array, item) =>
	array.findIndex((el) => el.x === item.x)
); // => [{ x: 1 }, { x: 3 }]

▲ Go Top | ▲ Table of Content

Contributing

Please fill free to create issues or send PR

Licence

BSD-3-Clause License