TypeSafeArray

TypeSafeArray API Documentation

TypeSafeArray is a type-safe utility library for array manipulation in TypeScript. This document describes the main methods of TypeSafeArray.

Table of Contents

map

static map<Container extends ReadonlyOrNot<any[]>, ReturnType>(
  container: Container,
  callbackfn: (value: ElementOf<Container>, index: number, array: Container) => ReturnType
): Map<Container, ReturnType>

Creates a new array with the results of calling a provided function on every element in this array.

Parameters:

  • container: The source array
  • callbackfn: A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.

Return value: A new array with each element being the result of the callback function.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const doubled = TypeSafeArray.map(numbers, x => x * 2);
// Result: [2, 4, 6, 8, 10]

forEach

static forEach<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  callbackfn: (value: ElementOf<Container>, index: number, array: Container) => void
): void

Executes a provided function once for each array element.

Parameters:

  • container: The array to iterate over
  • callbackfn: A function to execute for each element in the array

Return value: undefined

Example:

const numbers = [1, 2, 3, 4, 5] as const;
TypeSafeArray.forEach(numbers, x => console.log(x));
// Logs 1, 2, 3, 4, 5 to the console in order

filter

static filter<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  predicate: (value: ElementOf<Container>, index: number, array: Container) => boolean
): ElementOf<Container>[]

Creates a new array with all elements that pass the test implemented by the provided function.

Parameters:

  • container: The source array
  • predicate: A function that accepts up to three arguments. The filter method calls the predicate function one time for each element in the array.

Return value: A new array with the elements that pass the test.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const evenNumbers = TypeSafeArray.filter(numbers, x => x % 2 === 0);
// Result: [2, 4]

reduce

static reduce<Container extends ReadonlyOrNot<any[]>, ReturnType>(
  container: Container,
  callbackfn: (
    previousValue: ReturnType,
    currentValue: ElementOf<Container>,
    currentIndex: number,
    array: Container
  ) => ReturnType,
  initialValue: ReturnType
): ReturnType

Applies a function against an accumulator and each element in the array (from left to right) to reduce it to a single value.

Parameters:

  • container: The array to reduce
  • callbackfn: A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the array.
  • initialValue: A value to use as the first argument to the first call of the callbackfn.

Return value: The value that results from the reduction.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const sum = TypeSafeArray.reduce(numbers, (acc, curr) => acc + curr, 0);
// Result: 15

find

static find<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  predicate: (value: ElementOf<Container>, index: number, obj: Container) => boolean
): ElementOf<Container> | undefined

Returns the value of the first element in the array that satisfies the provided testing function.

Parameters:

  • container: The array to search
  • predicate: A function to execute on each value in the array until the function returns true, indicating that the satisfying element was found.

Return value: The first element in the array that satisfies the provided testing function. Otherwise, undefined is returned.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const firstEven = TypeSafeArray.find(numbers, x => x % 2 === 0);
// Result: 2

findIndex

static findIndex<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  predicate: (value: ElementOf<Container>, index: number, obj: Container) => boolean
): number

Returns the index of the first element in the array that satisfies the provided testing function.

Parameters:

  • container: The array to search
  • predicate: A function to execute on each value in the array until the function returns true, indicating that the satisfying element was found.

Return value: The index of the first element in the array that passes the test. Otherwise, -1.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const indexOfFirstEven = TypeSafeArray.findIndex(numbers, x => x % 2 === 0);
// Result: 1

some

static some<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  predicate: (value: ElementOf<Container>, index: number, array: Container) => boolean
): boolean

Tests whether at least one element in the array passes the test implemented by the provided function.

Parameters:

  • container: The array to test
  • predicate: A function to test for each element.

Return value: true if the callback function returns a truthy value for at least one element in the array. Otherwise, false.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const hasEven = TypeSafeArray.some(numbers, x => x % 2 === 0);
// Result: true

every

static every<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  predicate: (value: ElementOf<Container>, index: number, array: Container) => boolean
): boolean

Tests whether all elements in the array pass the test implemented by the provided function.

Parameters:

  • container: The array to test
  • predicate: A function to test for each element.

Return value: true if the callback function returns a truthy value for every array element. Otherwise, false.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const allPositive = TypeSafeArray.every(numbers, x => x > 0);
// Result: true

includes

static includes<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  searchElement: ElementOf<Container>,
  fromIndex?: number
): boolean

Determines whether an array includes a certain value among its entries.

Parameters:

  • container: The array to search
  • searchElement: The value to search for
  • fromIndex: The position in this array at which to begin searching for searchElement.

Return value: true if the searchElement is found in the array, false otherwise.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const includesThree = TypeSafeArray.includes(numbers, 3);
// Result: true

indexOf

static indexOf<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  searchElement: ElementOf<Container>,
  fromIndex?: number
): number

Returns the first index at which a given element can be found in the array.

Parameters:

  • container: The array to search
  • searchElement: Element to locate in the array
  • fromIndex: The index to start the search at.

Return value: The first index of the element in the array; -1 if not found.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const indexOfThree = TypeSafeArray.indexOf(numbers, 3);
// Result: 2

join

static join<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  separator?: string
): string

Joins all elements of an array into a string.

Parameters:

  • container: The array to join
  • separator: A string used to separate one element of the array from the next in the resulting string. If omitted, the array elements are separated with a comma.

Return value: A string with all array elements joined.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const joined = TypeSafeArray.join(numbers, '-');
// Result: "1-2-3-4-5"

slice

static slice<Container extends ReadonlyOrNot<any[]>>(
  container: Container,
  start?: number,
  end?: number
): ElementOf<Container>[]

Returns a shallow copy of a portion of an array into a new array object.

Parameters:

  • container: The array to slice
  • start: The beginning index of the specified portion of the array.
  • end: The end index of the specified portion of the array. This is exclusive of the element at the index 'end'.

Return value: A new array containing the extracted elements.

Example:

const numbers = [1, 2, 3, 4, 5] as const;
const sliced = TypeSafeArray.slice(numbers, 1, 4);
// Result: [2, 3, 4]

concat

static concat<Container extends ReadonlyOrNot<any[]>, Item>(
  container: Container,
  ...items: (Item | ReadonlyOrNot<Item[]>)[]
): (ElementOf<Container> | Item)[]

Merges two or more arrays.

Parameters:

  • container: The target array
  • items: Additional arrays and/or values to concatenate into the new array.

Return value: A new array instance.

Example:

const numbers1 = [1, 2, 3] as const;
const numbers2 = [4, 5] as const;
const concatenated = TypeSafeArray.concat(numbers1, numbers2, 6);
// Result: [1, 2, 3, 4, 5, 6]