@wezom/toolkit-array v6.1.0

@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()

comment: <> (AUTODOC-TOOL-START::add-unique#default)

Clones an array and puts only unique elements there

Parameters:

Returns: T[]

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayClone()

comment: <> (AUTODOC-TOOL-START::clone#default)

Clones array for immutable tasks

Parameters:

Returns: T[]

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayFilterNullable()

comment: <> (AUTODOC-TOOL-START::filter-nullable#default)

Filter null and undefined array items

Parameters:

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
);

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayFilterUnique()

comment: <> (AUTODOC-TOOL-START::filter-unique#default)

Returns new array without duplicates

Parameters:

Returns: T[]

Examples:

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

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayGetFirstNotNullableItem()

comment: <> (AUTODOC-TOOL-START::get-first-not-nullable-item#default)

Getting first not nullable item from given array data

Parameters:

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
);

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayRemoveByIndex()

comment: <> (AUTODOC-TOOL-START::remove-by-index#default)

Clones an array and removes items by index

Parameters:

Returns: T[]

Examples:

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

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayRemoveItems()

comment: <> (AUTODOC-TOOL-START::remove-items#default)

Clones an array and removes items

Parameters:

Returns: T[]

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arraySimpleRandomFn()

comment: <> (AUTODOC-TOOL-START::simple-random-fn#default)

Function for simple sorting of array elements in random order

Returns: number

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

arrayToggleItem()

comment: <> (AUTODOC-TOOL-START::toggle-item#default)

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

Parameters:

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 }]

comment: <> (AUTODOC-TOOL-END)

▲ Go Top | ▲ Table of Content

Contributing

Please fill free to create issues or send PR

Licence

BSD-3-Clause License