@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

---