npm package: @perfective/array
Description: Functions to work with the Array type
Author: Andrey Mikheychik
Latest version: 0.4.0
Deprecated: @perfective/array@0.4.0 matches @perfective/common@0.7.0 as @perfective/common/array

# Array

The `@perfective/array` package provides functions for the standard JS
[`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) class:

* Unit functions:
    * `array<T>(...elements: T[]): T[]`
    * `arrayFromIterable<T>(elements: Iterable<T>): T[]`
    * `arrayFromArrayLike<T>(elements: ArrayLike<T>): T[]`
    * `copy<T>(array: T[]): T[]`
    — creates a shallow copy of an array
    * `concatenated<T>(initial: T[], ...arrays: T[][]): T[]`
    * `flatten<T>(arrays: T[][]): T[]`
    * `intersection<T>(array1: T[], array2: T[]): T[]`
    * `replicated<T>(value: T, length: number): T[]`
    — creates a new array of the given value replicated the given number of times.
    * `replicated<T>(length: number): Unary<T, T[]>`
    — creates a new function that replicates a given value the given number of times.
    * `reversed<T>(array: T[]): T[]`
    — creates a shallow _reversed_ copy of an array
    * `sorted<T>(array: T[], order?: Compare<T>): T[]`
    — creates a shallow _sorted_ copy of an array
    * `unique<T>(array: T[]): T[]`
    — creates a shallow copy with all duplicate elements removed
    * `wrapped<T>(value: T | T[]): T[]`
    — if value is an array, returns the original array; otherwise returns an array with that value.
* Type guards:
    * `isArray<T, V = unknown>(value: T[] | V): value is T[]`
    * `isNotArray<T, V = unknown>(value: T[] | V): value is V`
* Predicates:
    * `isEmpty<T>(value: T[]): boolean`
    * `isNotEmpty<T>(value: T[]): boolean`
    * `includes<T>(search: T, from?: number): Predicate<T[]>`
    * `includedIn<T>(array: T[], from?: number): Predicate<T>`
    * `every<T>(condition: Predicate<T>): Predicate<T[]>`
    * `some<T>(condition: Predicate<T>): Predicate<T[]>`
* Iterators:
    * `entries<T>(array: T[]): IterableIterator<[number, T]>`
    * `keys<T>(array: T[]): IterableIterator<number>`
    * `values<T>(array: T[]): IterableIterator<T>`
* Map/Reduce:
    * `map<T, V>(lift: Unary<T, V>): Unary<T[], V[]>`
    * `reduce<T, V>(reducer: Reducer<T, V>, initial: V): Unary<T[], V>`
    * `reduceTo<T>(reducer: Reducer<T, T>): Unary<T[], T>`
    * `reduceRight<T, V>(reducer: Reducer<T, V>, initial: V): Unary<T[], V>`
    * `reduceRightTo<T>(reducer: Reducer<T, T>): Unary<T[], T>`
    * `join<T>(separator: string = ','): Unary<T[], string>`
* Immutable element operators:
    * `head<T>(array: T[]): T | undefined`
    — returns the first (head) element of an array;
    * `tail<T>(array: T[]): T[]`
    — returns an array without the first element;
    * `end<T>(array: T[]): T | undefined`
    — returns the last (end) element of an array;
    * `init<T>(array: T[]): T[]`
    — returns an array without the last element;
    * `element<T>(index: number): Unary<T[], T | undefined>`
    — returns the element by its index;
    * `find<T>(condition: Predicate<T>): Unary<T[], T | undefined>`
* Mutable element operators:
    * `pop<T>(array: T[]): T | undefined`
    * `push<T>(...items: T[]): Unary<T[], number>`
    * `shift<T>(array: T[]): T | undefined`
    * `unshift<T>(...items: T[]): Unary<T[], number>`
* Index operators:
    * `findIndex<T>(condition: Predicate<T>): Unary<T[], number | -1>`
    * `indexOf<T>(search: T, from?: number): Unary<T[], number | -1>`
    * `lastIndexOf<T>(search: T, from?: number): Unary<T[], number | -1>`
* Immutable array operators:
    * `first<T>(count: number = 1): Unary<T[], T[]>`
    — returns an array of the first `count` of elements.
    * `last<T>(count: number = 1): Unary<T[], T[]>`
    — returns an array of the last `count` of elements.
    * `append<T>(element: T): Unary<T[], T[]>`
    — returns an array with an element inserted in the end of the original array.
    * `prepend<T>(element: T): Unary<T[], T[]>`
    — returns an array with an element inserted in the beginning of the original array.
    * `insert<T>(index: number, element: T): Unary<T[], T[]>`
    — returns an array with an element inserted into the given `index`.
    * `insertInto<T>(array: T[], index: number): Unary<T, T[]>`
    — returns an array with an element inserted into the given `array`.
    * `replace<T>(index: number, element: T): Unary<T[], T[]>`
    — returns an array with an element replaced in the given `index`.
    * `remove<T>(index: number): Unary<T[], T[]>`
    — returns an array with an element removed from the given `index`.
    * `concat<T>(...items: ConcatArray<T>[]): Unary<T[], T[]>`
    * `filter<T>(condition: Predicate<T>): Unary<T[], T[]>`
    * `slice<T>(start?: number, end?: number): Unary<T[], T[]>`
    * `sorted<T>(order?: Compare<T>): Unary<T[], T[]>`
* Mutable (_in-place_) array operators:
    * `copyWithin<T>(target: number, start: number = 0, end?: number): Unary<T[], T[]>`
    * `fill<T>(value: T, start?: number, end?: number): Unary<T[], T[]>`
    * `reverse<T>(array: T[]): T[]`
    * `sort<T>(order?: Compare<T>): Unary<T[], T[]>`
    * `splice<T>(start: number, deleteCount?: number): Unary<T[], T[]>`
    * `spliceWith<T>(start: number, deleteCount: number, ...items: T[]): Unary<T[], T[]>`
* Procedures:
    * `forEach<T>(procedure: Unary<T, void>): Unary<T[], void>`
* Filters:
    * `Filter<T, S extends T>`
    * `by<T, K extends keyof T>(property: K, condition: Predicate<T[K]>): Filter<T, T>`
    — filters an array keeping elements with the `property` that satisfies the `condition`.
    * `isFirstOccurrence<T>(value: T, index: number, array: T[]): boolean`
    * `isLastOccurrence<T>(value: T, index: number, array: T[]): boolean`
* Mappers:
    * `Map<T, U>`
* Reducers:
    * `Reduce<T, V>`


Read the [full documentation](https://github.com/perfective/js/blob/master/packages/array/README.adoc) 
in the repository.