### Navigate to Benchmarks Directory and Install Dependencies
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/introduction.md
Change the current directory to 'benchmarks' and install its specific dependencies.
```bash
cd ./benchmarks
yarn
```
--------------------------------
### Install Dependencies and Build ts-belt
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/introduction.md
Install all project dependencies and build the ts-belt distribution files.
```bash
yarn
yarn build dist -t
```
--------------------------------
### String Manipulation Example
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/string.mdx
Demonstrates filtering strings that start with '+', joining them with '-', and removing the '+' prefix.
```jsx
function() {
const value = pipe(
['hello', 'world', '+ts', '+belt'],
A.filter(S.startsWith('+')),
A.join('-'),
S.removeAll('+'),
)
return value
}
```
--------------------------------
### Install ts-belt with npm
Source: https://github.com/mobily/ts-belt/blob/master/README.md
Use this command to add the ts-belt library to your project when using npm.
```shell
npm install @mobily/ts-belt --save
```
--------------------------------
### Install ts-belt with Yarn
Source: https://github.com/mobily/ts-belt/blob/master/README.md
Use this command to add the ts-belt library to your project when using Yarn.
```shell
yarn add @mobily/ts-belt
```
--------------------------------
### Live Example: Performing Division with Result
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/result.mdx
Demonstrates using the Result type with pipe and various Result operations (fromNullable, flatMap, match) to handle potential errors like division by zero or null values in a functional manner.
```jsx
function() {
const obj = {
// ⬇️ update the value below to either greater than 0 or `null/undefined` in order to see changes
value: 0,
}
const value = pipe(
R.fromNullable(obj.value, 'value cannot be nullable!'),
R.flatMap(value => {
return value === 0 ? R.Error('never divide by zero!') : R.Ok(100 / value)
}),
R.match(value => `100 / ${obj.value} = ${value}`, err => err),
)
return value
}
```
--------------------------------
### Working with Option Type
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/option.mdx
Demonstrates using Option utility functions like fromNullable, flatMap, map, and getWithDefault to process an array. This example shows how to safely extract and transform values, providing a default if the Option is None.
```jsx
function() {
// ⬇️ remove all elements in the array below in order to see the default value
const xs = ['hello', 'world', 'ts', 'belt']
const value = pipe(
O.fromNullable(xs), // → Some(['hello', 'world', 'ts', 'belt'])
O.flatMap(A.dropExactly(2)), // → Some(['ts', 'belt'])
O.map(A.join('-')), // → Some('ts-belt')
O.getWithDefault('default value'), // returns `default value` if `None`
)
return value
}
```
--------------------------------
### prepend
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Prepends a single element to the start of the given array.
```APIDOC
## prepend
### Description
Prepends a single element to the start of the given array.
### Signature
```ts
function prepend(xs: Array, element: A): Array
function prepend(element: A): (xs: Array) => Array
```
```
--------------------------------
### Example Usage of Pipe and Flow
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/pipe-flow.mdx
Demonstrates how to use pipe and flow together to clean and process an array of strings. The flow function defines a cleaning pipeline, and pipe applies this pipeline to an array, mapping the cleaning function and then joining the results.
```jsx
function() {
const clean = flow(S.removeAll('X'), S.toLowerCase)
const value = pipe(
['HellXXXo', 'wOrXXXLd'],
A.map(clean),
A.join(' ')
)
return value
}
```
--------------------------------
### Run Benchmark Suites
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/introduction.md
Execute the benchmark suites using yarn. Use 'yarn generate' to produce a markdown results file.
```bash
yarn start
# or
yarn generate
```
--------------------------------
### range
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns an inclusive array of numbers from start to finish. Returns an empty array if start is greater than finish.
```APIDOC
## range
### Description
Returns a new inclusive array of numbers from `start` to `finish` (it returns an empty array when `start` > `finish`).
### Signature
```ts
function range(finish: number): (start: number) => Array
function range(start: number, finish: number): Array
```
```
--------------------------------
### Generate Number Range
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Creates an inclusive array of numbers between a start and finish value. Returns an empty array if start is greater than finish.
```typescript
function range(finish: number): (start: number) => Array
function range(start: number, finish: number): Array
```
--------------------------------
### Array Creation and Transformation
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/array.mdx
Demonstrates creating an array with indexed values and applying a series of transformations using pipe, tail, take, and map.
```jsx
function() {
const xs = A.makeWithIndex(5, index => index) // → [0, 1, 2, 3, 4]
const value = pipe(
xs,
A.tailOrEmpty, // → [1, 2, 3, 4]
A.take(2), // → [1, 2]
A.map(value => value * 2), // → [2, 4]
)
return JSON.stringify(value)
}
```
--------------------------------
### Extract Substring by Start and End Index
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Extracts a portion of a string between a specified start and end index. The character at the end index is not included.
```typescript
function slice(str: string, start: number, end: number): string
function slice(start: number, end: number): (str: string) => string
```
--------------------------------
### rangeBy
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns an inclusive array of numbers from start to finish with a specified step. Returns an empty array if the step is zero or negative, or if start is greater than finish.
```APIDOC
## rangeBy
### Description
Returns a new inclusive array of numbers from `start` to `finish` (it returns an empty array when `step` is 0 or negative, it also returns an empty array when `start` > `finish`).
### Signature
```ts
function rangeBy(finish: number, step: number): (start: number) => Array
function rangeBy(start: number, finish: number, step: number): Array
```
```
--------------------------------
### take
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns a new array containing the first n elements of the provided array.
```APIDOC
## take
### Description
Returns a new array including the first `n` elements of the provided array, or an empty array if `n` is either negative or greater than the length of the provided array.
### Signature
```ts
function take(xs: Array, n: number): Array
function take(n: number): (xs: Array) => Array
```
```
--------------------------------
### Generate Number Range with Step
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Creates an inclusive array of numbers between a start and finish value with a specified step. Returns an empty array if the step is zero or negative, or if start is greater than finish.
```typescript
function rangeBy(finish: number, step: number): (start: number) => Array
function rangeBy(start: number, finish: number, step: number): Array
```
--------------------------------
### sliceToEnd
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Extracts a portion of a string from a start index to the end.
```APIDOC
## sliceToEnd
### Description
Returns the substring of `str` starting at character `start` to the end of the string.
### Function Signature
```ts
function sliceToEnd(str: string, start: number): string
function sliceToEnd(start: number): (str: string) => string
```
```
--------------------------------
### Get String Length
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Returns the number of characters in a string.
```typescript
function length(str: string): number
```
```typescript
S.length('hello') // → 5
pipe('ts-belt', S.length) // → 7
```
--------------------------------
### deepFlat-uniq-groupBy Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/windows-10-i7-10700k.md
Compares the performance of deepFlat, uniq, and groupBy operations. @mobily/ts-belt shows the fastest results.
```bash
✔ @mobily/ts-belt 1,457,783.47 ops/sec ±4.12% (87 runs) fastest
✔ remeda 271,365.52 ops/sec ±5.28% (74 runs) -81.39%
✔ ramda 139,708.87 ops/sec ±4.33% (78 runs) -90.42%
✔ rambda 1,085,267.39 ops/sec ±3.43% (81 runs) -25.55%
✔ lodash/fp 287,683.71 ops/sec ±1.86% (86 runs) -80.27%
```
--------------------------------
### slice
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Extracts a portion of a string between specified start and end indices.
```APIDOC
## slice
### Description
Returns the substring of `str` starting at character `start` up to but not including `end`.
### Function Signature
```ts
function slice(str: string, start: number, end: number): string
function slice(start: number, end: number): (str: string) => string
```
```
--------------------------------
### startsWith
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Checks if a string begins with a specified substring.
```APIDOC
## startsWith
### Description
Returns `true` if the given string starts with `substr`.
### Function Signature
```ts
function startsWith(substr: string): (str: string) => boolean
function startsWith(str: string, substr: string): boolean
```
### Usage Example
```ts
startsWith('hello', 'o') // → false
pipe('ts-belt', S.startsWith('ts')) // → true
```
```
--------------------------------
### make
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns a new array of a specified size, populated with a given element.
```APIDOC
## make
### Description
Returns a new array of size `n` populated by `element`, or an empty array if `n` is negative.
### Signature
```ts
function make(n: number, element: A): Array
function make(element: A): (n: number) => Array
```
### Example
```ts
A.make(-1, 'hello') // → []
A.make(3, 1) // → [1, 1, 1]
pipe(2, A.make('hello')) // → ['hello', 'hello']
```
```
--------------------------------
### at
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Alias for `get`. Returns the element at the specified index, or `None` if the index is out of bounds.
```APIDOC
## at
### Description
Alias for `get`. Returns the element at the specified index, or `None` if the index is out of bounds.
### Signature
```ts
function at(xs: Array, index: number): Option
function at(index: number): (xs: Array) => Option
```
```
--------------------------------
### deepFlat-uniq-groupBy Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-air-2020.md
Compares the performance of deepFlat, uniq, and groupBy operations. @mobily/ts-belt is the fastest.
```bash
✔ @mobily/ts-belt 2,232,731.32 ops/sec ±0.12% (101 runs) fastest
✔ remeda 491,977.09 ops/sec ±2.20% (97 runs) -77.97%
✔ ramda 267,914.93 ops/sec ±0.86% (97 runs) -88.00%
✔ rambda 1,713,610.43 ops/sec ±1.02% (97 runs) -23.25%
✔ lodash/fp 521,001.69 ops/sec ±1.24% (97 runs) -76.67%
```
--------------------------------
### Get Array Length
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns the number of elements in an array. Can be used directly or with a pipe.
```typescript
A.length(['hello', 'world']) // → 2
pipe([0, 2, 4], A.length) // → 3
```
--------------------------------
### trimStart
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Removes leading whitespace from a string.
```APIDOC
## trimStart
### Description
Returns a new string with leading whitespace removed from `str`.
### Function Signature
```ts
function trimStart(str: string): string
```
### Usage Example
```ts
trimStart(' text ') // → 'text '
```
```
--------------------------------
### takeExactly
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns a new array with the first n elements, or None if n is out of bounds.
```APIDOC
## takeExactly
### Description
Returns a new array (`Some(xs)`) with the first `n` elements of the provided array, or `None` if `n` is either negative or greater than the length of the provided array.
### Signature
```ts
function takeExactly(xs: Array, n: number): Option>
function takeExactly(n: number): (xs: Array) => Option>
```
```
--------------------------------
### fromPairs Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.7.0/macbook-air-2020.md
Compares the performance of ts-belt's fromPairs function against other libraries when called directly. Results are measured in operations per second.
```bash
✔ @mobily/ts-belt 19,416,008.78 ops/sec ±0.05% (99 runs) fastest
███████████████████████████████████████████████████████████████████████
✔ remeda 17,511,630.07 ops/sec ±1.49% (97 runs) -9.81%
██████████████████████████████████████████████████████████████████████
✔ ramda 8,477,718.23 ops/sec ±1.00% (99 runs) -56.34%
██████████████████████████████████
✔ rambda 16,827,952.34 ops/sec ±1.85% (98 runs) -13.33%
███████████████████████████████████████████████████████████████████
✔ lodash/fp 13,886,757.40 ops/sec ±1.26% (97 runs) -28.48%
████████████████████████████████████████████████████████████████
✔ native 2,758,522.55 ops/sec ±0.44% (101 runs) -85.79%
██████████
```
--------------------------------
### takeWhile
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns a new array containing elements from the start of the array until a condition is no longer met.
```APIDOC
## takeWhile
### Description
Returns a new array, filled with elements from the provided array until an element doesn't pass the provided predicate.
### Signature
```ts
function takeWhile(xs: Array, predicateFn: (_1: A) => boolean): Array
function takeWhile(predicateFn: (_1: A) => boolean): (xs: Array) => Array
```
```
--------------------------------
### fromPairs Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-air-2020.md
Benchmark results for the fromPairs function when called as a standalone operation. Shows performance comparison with other libraries.
```bash
✔ @mobily/ts-belt 19,553,087.09 ops/sec ±0.07% (101 runs) fastest
✔ remeda 17,659,061.64 ops/sec ±1.79% (98 runs) -9.69%
✔ ramda 8,440,932.06 ops/sec ±1.11% (96 runs) -56.83%
✔ rambda 16,986,649.62 ops/sec ±2.27% (91 runs) -13.13%
✔ lodash/fp 14,162,403.18 ops/sec ±1.33% (99 runs) -27.57%
```
--------------------------------
### lastIndexOf
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Returns `Some(index)`, where `index` is the starting position of the last occurrence of `searchValue` within `str`.
```APIDOC
## lastIndexOf
### Description
Returns `Some(index)`, where `index` is the starting position of the last occurrence of `searchValue` within `str`.
### Signature
```ts
function lastIndexOf(searchValue: string): (str: string) => Option
function lastIndexOf(str: string, searchValue: string): Option
```
### Examples
```ts
S.lastIndexOf('ts,rescript', 's') // → Some(5)
S.lastIndexOf('ts,rescript', 'x') // → None
pipe(['hello', 'ts'], A.keepMap(S.lastIndexOf('l'))) // → [3]
```
```
--------------------------------
### deepFlat-uniq-groupBy Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.7.0/macbook-pro-2017.md
Compares the performance of deepFlat-uniq-groupBy operations. @mobily/ts-belt achieves the highest operations per second.
```bash
✔ @mobily/ts-belt 919,915.97 ops/sec ±4.43% (89 runs) fastest
███████████████████████████████████████████████████████████████████
✔ remeda 193,455.13 ops/sec ±5.61% (80 runs) -78.97%
████████████
✔ ramda 116,813.04 ops/sec ±3.86% (89 runs) -87.30%
████████
✔ rambda 757,985.17 ops/sec ±3.80% (93 runs) -17.60%
███████████████████████████████████████████
✔ lodash/fp 202,938.21 ops/sec ±4.33% (87 runs) -77.94%
██████████████
```
--------------------------------
### indexOf
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Returns `Some(index)`, where `index` is the starting position of the first occurrence of `searchValue` within `str`.
```APIDOC
## indexOf
### Description
Returns `Some(index)`, where `index` is the starting position of the first occurrence of `searchValue` within `str`.
### Signature
```ts
function indexOf(searchValue: string): (str: string) => Option
function indexOf(str: string, searchValue: string): Option
```
### Examples
```ts
S.indexOf('hello', 'e') // → Some(1)
pipe(['hello', 'world'], A.keepMap(S.indexOf('o'))) // → [4, 1]
```
```
--------------------------------
### deepFlat-uniq-groupBy Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2021.md
Compares the performance of deepFlat-uniq-groupBy operations using @mobily/ts-belt against other libraries.
```bash
✔ @mobily/ts-belt 2,297,096.07 ops/sec ±0.20% (99 runs) fastest
✔ remeda 494,070.92 ops/sec ±2.33% (98 runs) -78.49%
✔ ramda 281,192.43 ops/sec ±0.97% (93 runs) -87.76%
✔ rambda 1,767,868.03 ops/sec ±1.10% (98 runs) -23.04%
✔ lodash/fp 528,949.75 ops/sec ±1.15% (98 runs) -76.97%
```
--------------------------------
### Get All Dictionary Values
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_dict.mdx
Returns an array containing all values from a dictionary. The order of values is not guaranteed.
```typescript
function values(dict: Record): Array
```
```typescript
D.values({
name: 'Joe',
age: 20,
}) // → ['Joe', 20]
```
```typescript
pipe(
{
name: 'Joe',
age: 20,
},
D.values,
) // → ['Joe', 20]
```
--------------------------------
### Convert Option to Undefined
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_option.mdx
Use `toUndefined` to get the value from a `Some` Option or `undefined` if it's `None`.
```ts
function toUndefined(option: Option): A | undefined
```
```ts
pipe(
O.fromNullable(['hello', 'world']),
O.flatMap(A.takeExactly(2)),
O.toUndefined,
) // → ['hello', 'world']
pipe(O.fromNullable([]), O.flatMap(A.takeExactly(2)), O.toUndefined) // → undefined
```
--------------------------------
### unzip Benchmark (single function call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2021.md
Compares the performance of a single unzip function call using @mobily/ts-belt against other libraries.
```bash
✔ @mobily/ts-belt 49,515,854.12 ops/sec ±0.30% (97 runs) fastest
✔ lodash/fp 2,186,127.29 ops/sec ±1.08% (99 runs) -95.58%
```
--------------------------------
### Convert Option to Nullable
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_option.mdx
Use `toNullable` to get the value from a `Some` Option or `null` if it's `None`.
```ts
function toNullable(option: Option): A | null
```
```ts
pipe(
O.fromNullable(['hello', 'world']),
O.flatMap(A.takeExactly(2)),
O.toNullable,
) // → ['hello', 'world']
pipe(O.fromNullable([]), O.flatMap(A.takeExactly(2)), O.toNullable) // → null
```
--------------------------------
### Using zipWith with pipe and Option
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_option.mdx
Demonstrates how to use zipWith within a pipe to combine two Option values, concatenating them if both are present.
```typescript
pipe(
O.fromNullable('hello'),
O.zipWith(O.fromNullable('world'), S.concat),
) // → Some('helloworld')
```
--------------------------------
### Get Last Character
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Returns the last character of a string as an Option, or None if the string is empty.
```typescript
function last(str: string): Option
```
```typescript
S.last('random-text') // → Some('t')
```
--------------------------------
### Get First Character
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Returns the first character of a string as an Option, or None if the string is empty.
```typescript
function head(str: string): Option
```
```typescript
S.head('random-text') // → Some('r')
```
--------------------------------
### forEach Benchmark (Inside Pipe)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.7.0/macbook-air-2020.md
Compares the performance of forEach when used within a pipe across different libraries.
```bash
✔ @mobily/ts-belt 80,060,371.34 ops/sec ±0.38% (99 runs) fastest
███████████████████████████████████████████████████████████████████████
✔ remeda 2,480,371.88 ops/sec ±0.80% (98 runs) -96.90%
██
✔ ramda 2,497,713.89 ops/sec ±0.25% (101 runs) -96.88%
██
✔ rambda 38,734,852.35 ops/sec ±0.20% (94 runs) -51.62%
██████████████████████████████████
✔ lodash/fp 1,041,207.17 ops/sec ±1.13% (100 runs) -98.70%
✔ native 17,466,000.74 ops/sec ±0.22% (100 runs) -78.18%
█████████████
```
--------------------------------
### Array Intersection Example
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Calculates the common elements between two arrays. Can be used directly or with a pipe.
```typescript
A.intersection([1, 2, 3, 4], [3, 4, 5, 6]) // → [3, 4]
pipe([5, 2, 3, 5, 6], A.intersection([5, 2, 3, 1, 5, 4])) // → [5, 2, 3]
```
--------------------------------
### deepFlat-uniq-groupBy Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2017.md
Compares the performance of deepFlat-uniq-groupBy operations across different libraries.
```bash
✔ @mobily/ts-belt 1,057,091.24 ops/sec ±1.83% (90 runs) fastest
✔ remeda 212,327.21 ops/sec ±3.93% (89 runs) -79.91%
✔ ramda 120,122.01 ops/sec ±3.83% (86 runs) -88.64%
✔ rambda 806,321.94 ops/sec ±2.21% (95 runs) -23.72%
✔ lodash/fp 196,049.03 ops/sec ±2.59% (91 runs) -81.45%
```
--------------------------------
### deepFlat Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-air-2020.md
Benchmark results for deepFlat when called as a single function. Shows performance comparison against other libraries.
```bash
✔ @mobily/ts-belt 16,538,319.46 ops/sec ±0.54% (99 runs) fastest
✔ remeda 1,416,540.10 ops/sec ±1.77% (94 runs) -91.43%
✔ ramda 701,492.07 ops/sec ±0.53% (97 runs) -95.76%
✔ rambda 14,731,465.99 ops/sec ±0.78% (99 runs) -10.93%
✔ lodash/fp 7,094,316.19 ops/sec ±0.59% (99 runs) -57.10%
```
--------------------------------
### reduce
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Applies a reduce function to each element of an array, accumulating a result. The accumulator starts with an initial value.
```APIDOC
## reduce
### Description
Applies `reduceFn` (which has two parameters: an `accumulator` which starts with a value of `initialValue` and the next value from the array) to each element of the provided array, and eventually it returns the final value of the accumulator.
### Signature
```ts
function reduce(xs: Array, initialValue: B, reduceFn: (_1: B, _2: A) => B): B
function reduce(initialValue: B, reduceFn: (_1: B, _2: A) => B): (xs: Array) => B
```
```
--------------------------------
### Get Tail of Array - Array
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns all elements except the first. Returns `None` if the array is empty.
```typescript
A.tail([1, 2, 3]) // → Some([2, 3])
```
```typescript
A.tail([1]) // → Some([])
```
```typescript
A.tail([]) // → None
```
```typescript
pipe([1, 2, 3, 4], A.tail) // → Some([2, 3, 4])
```
--------------------------------
### zip Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/windows-10-i7-10700k.md
Performance comparison of ts-belt's zip function against alternatives when called directly. ts-belt is shown to be the fastest.
```bash
✔ @mobily/ts-belt 16,561,039.31 ops/sec ±1.38% (89 runs) fastest
✔ remeda 1,930,383.26 ops/sec ±0.33% (94 runs) -88.34%
✔ ramda 13,143,191.31 ops/sec ±2.32% (87 runs) -20.64%
✔ rambda 13,555,345.79 ops/sec ±2.19% (92 runs) -18.15%
✔ lodash/fp 2,989,782.14 ops/sec ±1.29% (93 runs) -81.95%
```
--------------------------------
### deepFlat Benchmark (Single Function Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2017.md
Compares the performance of ts-belt's deepFlat function against other libraries when called directly. Results are measured in operations per second.
```bash
✔ @mobily/ts-belt 9,578,337.48 ops/sec ±2.69% (91 runs) fastest
✔ remeda 591,977.18 ops/sec ±4.01% (88 runs) -93.82%
✔ ramda 312,107.56 ops/sec ±2.89% (89 runs) -96.74%
✔ rambda 9,192,197.77 ops/sec ±2.25% (90 runs) -4.03%
✔ lodash/fp 3,880,407.90 ops/sec ±2.74% (92 runs) -59.49%
```
--------------------------------
### get
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Retrieves the element at a specific index in the array. Returns `Some(value)` if the index is valid, otherwise `None`.
```APIDOC
## get
Returns `Some(value)` at the given index, or `None` if the given index is out of range.
```ts
function get(xs: Array, index: number): Option
function get(index: number): (xs: Array) => Option
```
```
--------------------------------
### reduceWithIndex
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Applies a reduce function with index to each element of an array, accumulating a result. The accumulator starts with an initial value.
```APIDOC
## reduceWithIndex
### Description
Applies `reduceFn` (which has three parameters: an `accumulator` which starts with a value of `initialValue`, the next value from the array and its index) to each element of the provided array, and eventually it returns the final value of the accumulator.
### Signature
```ts
function reduceWithIndex(xs: Array, initialValue: B, reduceFn: (_1: B, _2: A, _3: number) => B): B
function reduceWithIndex(initialValue: B, reduceFn: (_1: B, _2: A, _3: number) => B): (xs: Array) => B
```
```
--------------------------------
### unzip Benchmark (single call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-air-2020.md
Compares the performance of the unzip operation when called directly. @mobily/ts-belt is the fastest.
```bash
✔ @mobily/ts-belt 45,331,676.08 ops/sec ±2.52% (95 runs) fastest
✔ lodash/fp 2,100,106.38 ops/sec ±1.45% (95 runs) -95.37%
```
--------------------------------
### Get all keys of an object
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_dict.mdx
Returns an array containing all own enumerable property keys of the provided object. Works with `pipe`.
```typescript
function keys>(dict: T): Array
```
```typescript
D.keys({
name: 'Joe',
age: 20,
}) // → ['name', 'age']
pipe(
{
name: 'Joe',
age: 20,
},
D.keys,
) // → ['name', 'age']
```
--------------------------------
### forEach Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.7.0/macbook-air-2020.md
Compares the performance of forEach when called directly across different libraries.
```bash
✔ @mobily/ts-belt 151,522,502.20 ops/sec ±1.09% (97 runs) -0.93%
███████████████████████████████████████████████████████████████████████
✔ remeda 3,155,520.10 ops/sec ±0.57% (96 runs) -97.94%
█
✔ ramda 150,488,946.35 ops/sec ±0.93% (101 runs) -1.61%
██████████████████████████████████████████████████████████████████████
✔ rambda 152,944,208.48 ops/sec ±0.04% (102 runs) fastest
████████████████████████████████████████████████████████████████████████
✔ lodash/fp 16,238,687.16 ops/sec ±0.58% (100 runs) -89.38%
███████
✔ native 21,061,643.09 ops/sec ±0.14% (102 runs) -86.23%
█████████
```
--------------------------------
### get
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Returns `Some(value)`, where `value` is a string consisting of the character at location `n` in the string, or `None` if the `n` is out of range.
```APIDOC
## get
### Description
Returns `Some(value)`, where `value` is a string consisting of the character at location `n` in the string, or `None` if the `n` is out of range.
### Signature
```ts
function get(str: string, n: number): Option
function get(n: number): (str: string) => Option
```
### Examples
```ts
S.get('hello', 1) // → Some('e')
pipe('ts-belt', S.get(9)) // → None
```
```
--------------------------------
### make
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Converts the given value to a string.
```APIDOC
## make
### Description
Converts the given value to a string.
### Signature
```ts
function make(value: A): string
```
### Examples
```ts
S.make(['hello', 'world']) // → 'hello,world'
S.make(true) // → 'true'
pipe({}, S.make) // → '[object Object]'
pipe(100, S.make) // → '100'
```
```
--------------------------------
### Get Character at Index Unsafely
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Retrieves the character at a specific index in a string, returning undefined for out-of-range indices.
```typescript
function getUnsafe(str: string, n: number): string
function getUnsafe(n: number): (str: string) => string
```
```typescript
S.getUnsafe('hello', 1) // → 'e'
pipe('world', S.getUnsafe(1)) // → 'o'
```
--------------------------------
### deepFlat Benchmark (Inside Pipe)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2017.md
Compares the performance of ts-belt's deepFlat function when used within a pipe, against other libraries. Results are measured in operations per second.
```bash
✔ @mobily/ts-belt 9,321,041.36 ops/sec ±2.81% (90 runs) fastest
✔ remeda 526,670.26 ops/sec ±3.16% (91 runs) -94.35%
✔ ramda 249,516.64 ops/sec ±3.31% (93 runs) -97.32%
✔ rambda 7,040,220.02 ops/sec ±2.79% (92 runs) -24.47%
✔ lodash/fp 2,344,753.07 ops/sec ±3.01% (88 runs) -74.84%
```
--------------------------------
### toPairs Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2017.md
Compares the performance of `toPairs` when called directly against other libraries.
```bash
✔ @mobily/ts-belt 15,759,801.15 ops/sec ±4.81% (85 runs) fastest
✔ remeda 14,281,044.65 ops/sec ±6.23% (78 runs) -9.38%
✔ ramda 4,355,137.41 ops/sec ±3.69% (86 runs) -72.37%
✔ rambda 15,631,702.94 ops/sec ±4.61% (85 runs) -0.81%
✔ lodash/fp 6,709,574.96 ops/sec ±3.56% (91 runs) -57.43%
```
--------------------------------
### Reduce Array
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Applies a reducer function to each element of an array, accumulating a single result. The accumulator starts with an initial value.
```typescript
function reduce(xs: Array, initialValue: B, reduceFn: (_1: B, _2: A) => B): B
function reduce(initialValue: B, reduceFn: (_1: B, _2: A) => B): (xs: Array) => B
```
--------------------------------
### toPairs Benchmark (Inside Pipe)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2017.md
Compares the performance of `toPairs` when used within a `pipe` composition against other libraries.
```bash
✔ @mobily/ts-belt 15,882,321.16 ops/sec ±3.86% (85 runs) fastest
✔ remeda 9,336,455.38 ops/sec ±2.87% (90 runs) -41.21%
✔ ramda 1,028,707.89 ops/sec ±2.58% (91 runs) -93.52%
✔ rambda 4,713,875.23 ops/sec ±33.00% (48 runs) -70.32%
✔ lodash/fp 2,600,464.69 ops/sec ±4.04% (87 runs) -83.63%
```
--------------------------------
### Check if String Starts With Substring
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Determines if a string begins with a specified substring. Returns a boolean value indicating the result.
```typescript
function startsWith(substr: string): (str: string) => boolean
function startsWith(str: string, substr: string): boolean
```
```typescript
S.startsWith('hello', 'o') // → false
pipe('ts-belt', S.startsWith('ts')) // → true
```
--------------------------------
### groupBy Benchmark (Single Call)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/windows-10-i7-10700k.md
Compares the performance of ts-belt's groupBy function against other libraries when called directly. Results show ts-belt as the fastest.
```bash
✔ @mobily/ts-belt 4,198,534.69 ops/sec ±0.81% (90 runs) fastest
✔ remeda 1,145,154.40 ops/sec ±0.33% (96 runs) -72.72%
✔ ramda 1,017,820.38 ops/sec ±0.91% (95 runs) -75.76%
✔ rambda 4,176,668.42 ops/sec ±1.36% (96 runs) -0.52%
✔ lodash/fp 2,024,891.48 ops/sec ±1.30% (94 runs) -51.77%
```
--------------------------------
### Get Character at Index
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Retrieves the character at a specific index in a string, returning an Option. Handles out-of-range indices gracefully.
```typescript
function get(str: string, n: number): Option
function get(n: number): (str: string) => Option
```
```typescript
S.get('hello', 1) // → Some('e')
pipe('ts-belt', S.get(9)) // → None
```
--------------------------------
### Trim Leading Whitespace
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Removes only the leading whitespace characters from the beginning of a string. Useful for cleaning up data where only the start needs trimming.
```typescript
function trimStart(str: string): string
```
```typescript
S.trimStart(' text ') // → 'text '
```
--------------------------------
### groupBy Benchmark (Inside Pipe)
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/windows-10-i7-10700k.md
Compares the performance of ts-belt's groupBy function when used within a pipe, against other libraries. ts-belt demonstrates the fastest performance in this scenario.
```bash
✔ @mobily/ts-belt 3,822,024.67 ops/sec ±1.13% (96 runs) fastest
✔ remeda 1,086,479.19 ops/sec ±0.87% (97 runs) -71.57%
✔ ramda 563,730.96 ops/sec ±0.80% (94 runs) -85.25%
✔ rambda 3,435,938.37 ops/sec ±0.74% (91 runs) -10.10%
✔ lodash/fp 409,581.80 ops/sec ±1.27% (96 runs) -89.28%
```
--------------------------------
### unzip (single function call) Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-pro-2017.md
Compares the performance of a single unzip function call across different libraries.
```bash
✔ @mobily/ts-belt 24,515,360.07 ops/sec ±2.01% (89 runs) fastest
✔ lodash/fp 1,045,603.53 ops/sec ±2.83% (91 runs) -95.73%
```
--------------------------------
### Get object property (deprecated)
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_dict.mdx
Retrieves a property from an object using its key. This function is deprecated and `D.get` or `D.getUnsafe` should be used instead.
```typescript
function prop(dict: T, key: K): T[K]
function prop(key: K): (dict: T) => T[K]
```
--------------------------------
### init
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_array.mdx
Returns a new array containing all elements except the last one. Returns `Some(array)` if the input array is not empty, otherwise `None`.
```APIDOC
## init
Returns a new array (`Some(xs)`) with all elements except the last of the provided array.
```ts
function init(xs: Array): Option>
```
```
--------------------------------
### Safely get a value by key
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_dict.mdx
Returns `Some(value)` if the key exists, otherwise `None`. Useful for safe access in functional pipelines.
```typescript
function get(dict: T, key: K): Option>
function get(key: K): (dict: T) => Option>
```
```typescript
D.get({ name: 'Joe', location: 'Warsaw' }, 'location') // → Some('Warsaw')
pipe({ name: 'Joe', location: 'Warsaw' }, D.get('location')) // → Some('Warsaw')
pipe([{ name: 'Joe' }, { location: 'Warsaw' }], A.map(D.get('name'))) // → [Some('Joe'), None]
```
--------------------------------
### map-filter-reduce Benchmark
Source: https://github.com/mobily/ts-belt/blob/master/docs/benchmarks/v3.0.0/macbook-air-2020.md
Compares the performance of map, filter, and reduce operations. @mobily/ts-belt is the fastest.
```bash
✔ @mobily/ts-belt 249,953.41 ops/sec ±0.13% (101 runs) fastest
✔ remeda 25,063.45 ops/sec ±1.79% (91 runs) -89.97%
✔ ramda 128,775.82 ops/sec ±0.31% (99 runs) -48.48%
✔ rambda 245,417.43 ops/sec ±0.36% (100 runs) -1.81%
✔ lodash/fp 66,199.93 ops/sec ±0.57% (99 runs) -73.52%
```
--------------------------------
### Extract Substring to the End
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_string.mdx
Extracts a portion of a string from a specified start index to the end of the string. Supports both direct and curried function usage.
```typescript
function sliceToEnd(str: string, start: number): string
function sliceToEnd(start: number): (str: string) => string
```
--------------------------------
### Get a value by key (unsafe)
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_dict.mdx
Returns the value if the key exists, otherwise returns `undefined`. Use with caution or when `undefined` is an acceptable outcome.
```typescript
function getUnsafe(dict: T, key: K): T[K]
function getUnsafe(key: K): (dict: T) => T[K]
```
```typescript
D.getUnsafe({ name: 'Joe', location: 'Warsaw' }, 'location') // → 'Warsaw'
pipe({ name: 'Joe', location: 'Warsaw' }, D.getUnsafe('location')) // → 'Warsaw'
pipe(
[{ name: 'Joe' }, { location: 'Warsaw' }],
A.map(D.getUnsafe('name')),
) // → ['Joe', undefined]
```
--------------------------------
### fromExecution
Source: https://github.com/mobily/ts-belt/blob/master/docs/api/generated/_option.mdx
Creates an Option from a function that might throw an error. Returns Some(value) if successful, None otherwise.
```APIDOC
## fromExecution
### Description
Returns `Some(value)` (`value` is the result of `fn`) if `fn` didn't throw an error, otherwise, returns `None`.
### Method Signature
```ts
function fromExecution(fn: () => A): Option>
```
### Example
```ts
type User = { readonly name: string }
const parseJSON = (value: string) => () => JSON.parse(value) as T
const okJSON = `{"name": "John"}`
const badJSON = `{name": John}`
O.fromExecution(parseJSON(okJSON)) // → Some({ name: 'John' })
O.fromExecution(parseJSON(badJSON)) // → None
```
```