array-extend

Array Extend is a library that extends the Array prototype with new methods. It is a collection of methods that are useful for working with arrays and arrays of objects.

import '@pim.sk/utils/array-extend.mjs'

Important: This module extends Array.prototype via getters. You must load import import '@pim.sk/utils/array-extend.mjs' before usage. If not loaded then .sum, .avg, .unique, ... return undefined without throwing errors. Example: [1 2 3].sum -> undefined

Getters - Without changing the original field

.unique

Remove duplicate items from the array.

[1, 2, 3, 2, 4, 5, 5]

const uniqueItems = items.unique

.duplicates

Find duplicate items in the array.

[1, 2, 3, 2, 4, 5, 5]

const duplicatesItems = items.duplicates

.unpaired

Find items that do not have a pair in the array.

a = [1, 2, 3, 4, 5]
b = [1, 2,    4, 5]

const items = a.concat(b)
const unpairedItems = items.unpaired

.sum

Sum the values of the array.

[1, 2, 3, 4, 5]

const sumItems = items.sum

.avg

Average the values of the array.

[1, 2, 3, 4, 5]

const avgItems = items.avg

.numbers

Get the numbers from the array.

[1, "2a", 3, null, 4, 5, "hello"]

const numbersItems = items.numbers

.nonumbers

Get the non-numbers from the array.

[1, "2a", 3, null, 4, 5, "hello"]

const nonumbersItems = items.nonumbers

.shuffle

Shuffle the array.

[1, 2, 3, 4, 5]

const shuffleItems = items.shuffle

Functions

Working with an array of objects based on conditions.

.get( key, value )

Return the first occurrence from the associative array.

[ {a:1,b:"one"}, {a:2,b:"two"}, {a:3,b:"one"} ]

const getItems = items.get("b", "one")

.gets( key, value )

Return all occurrences from an associative array based on a condition.

[ {a:1,b:"one"}, {a:2,b:"two"}, {a:3,b:"one"} ]

const getsItems = items.gets("b", "one")

Functions - Changing the original CONST items

We assume that we are working with an array of objects, where the variable is a constant. Its values always change without direct assignment. For these examples, a constant is used at the input: const items = [ {a:1,b:"one"}, {a:2,b:"two"}, {a:3,b:"one"} ]

.clean()

Clean the array.

items.clean()

.delete( key, value )

Delete the first occurrence from the associative array.

items.delete("b", "one")

.put( key, item ) ~ edit existing item

1/ Search for an element in the array where element[key] === item[key] — i.e. compares the value of the identification key 2/ If found → replaces it with a new item via splice 3/ If not found → adds the item to the end via push

items.put( "a", {a:3,b:"three"} )

.put( key, item ) ~ add new item

items.put( "a", {a:4,b:"four"} )

.puts( items, boolean ) ~ append

Bulk insert items : array of items to insert boolean : true = delete existing array before inserting (replace), false = add to the end (append)

items.puts( [ {a:4,b:"four"}, {a:5,b:"five"} ] )

.puts( items, boolean ) ~ replace

items.puts( [ {a:4,b:"four"}, {a:5,b:"five"} ], true )

.putsBy( key, items )

bulk upsert by key key : name of property that serves as identifier (e.g. "id") items : array of objects to process - if element with given key exists → replace it (update) - if it does not exist → add it to the end (insert)

items.putsBy( "a", [ {a:3,b:"three"}, {a:4,b:"four"} ] )

.uniqueBy( key )

Remove duplicates based on the specified key, keep the LAST occurrence key : name of the property by which duplicates are compared

items.uniqueBy( "b" )

.move( from, to )

Move within array - change index from : from index to : to index * it is more efficient than 2x splice

items.move( 0, 2 )

Utils (@pim.sk/utils)