ts-belt Documentation

ts-belt is a high-performance functional programming library for TypeScript and Flow. It is designed to combine the developer experience of a data-first approach with the performance of highly optimized JavaScript.

Key characteristics include:

• High Performance: Built using ReScript and the Belt standard library, generating highly performant JavaScript code.
• Data-First Approach: Provides a more readable and natural developer experience compared to data-last libraries.
• Type Safety: Leverages Option and Result types to help write safer code, with excellent TypeScript and Flow support.
• Immutability: All functions return immutable data, ensuring no side-effects.
• Modern Tooling: The library is tree-shakeable and fully documented.

Benchmarks conducted on a MacBook Pro (M1 Max, 64 GB, Node v16.13.0) demonstrate that @mobily/ts-belt consistently outperforms other functional programming libraries like remeda, ramda, rambda, lodash/fp, and native implementations across various common operations.

Key performance highlights include:

• map-filter-reduce chains
• deepFlat-uniq-groupBy sequences
• sort (both standalone and within a pipe)
• unzip (both standalone and within a pipe)
• flat (both standalone and within a pipe)
• dropWhile and takeWhile (both standalone and within a pipe)
• difference

In TS Belt, the Option<T> type is used to represent the existence or nonexistence of a value. It is a type alias that wraps a value T and allows it to be undefined or null to represent the absence of a value (often referred to as None).

Mandatory Configuration: To use Option safely and effectively, you must enable noUncheckedIndexedAccess in your tsconfig.json. This ensures that accessing elements in arrays or objects correctly results in undefined rather than a potentially incorrect type, allowing the Option utilities to work as intended.

type Option<T> = T | undefined | null

While both functions perform left-to-right composition, they serve different purposes:

1. pipe(value, fn1, fn2, ...): Operates on a value. It executes the transformations immediately and returns the final result. The first argument must be the data you want to process.
2. flow(fn1, fn2, ...): Operates on functions. It returns a new function that represents the composed pipeline. The first function can take multiple arguments, but all following functions must be unary.

Example of them working together:

// 1. Define a reusable transformation pipeline using flow
const clean = flow(S.removeAll('X'), S.toLowerCase)

// 2. Apply that pipeline to a value using pipe
const value = pipe(
  ['HellXXXo', 'wOrXXXLd'],
  A.map(clean),
  A.join(' ')
)

The Result<A, B> type is used to represent the outcome of an operation without relying on exceptions. It is a union type consisting of either an Ok<A> (representing success with value of type A) or an Error<B> (representing failure with error of type B).

This pattern allows you to chain operations using functional primitives like flatMap and handle errors gracefully using match.

type Result<A, B> = Ok<A> | Error<B>

To run the benchmark suites for ts-belt, you must first clone the repository, build the library, and then set up the benchmarks directory.

Steps to run benchmarks:

1. Clone the repository
2. Install dependencies and build ts-belt using yarn build dist -t.
3. Navigate to the benchmarks directory and install its specific dependencies.
4. Execute the benchmark suite using yarn start to run the tests, or yarn generate to produce a markdown report.

Results are saved in the benchmarks/.results directory.

# 1. Clone the repo
git clone https://github.com/mobily/ts-belt.git

# 2. Install dependencies and build ts-belt
yarn
yarn build dist -t

# 3. Setup benchmarks directory
cd ./benchmarks
yarn

# 4. Run benchmarks
yarn start
# OR generate a markdown file
yarn generate

You can install the @mobily/ts-belt package using either yarn or npm depending on your preferred package manager.

yarn add @mobily/ts-belt

npm install @mobily/ts-belt --save

To get the most benefit from ts-belt's type safety, it is highly recommended to enable strict mode and unchecked indexed access in your tsconfig.json. This ensures that the library's functional patterns and type guarantees are correctly enforced by the compiler.

{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true
  }
}

You can install @mobily/ts-belt using either yarn or npm to add the utility library to your project.

yarn add @mobily/ts-belt

or

npm install @mobily/ts-belt --save

By default, ts-belt uses immutable arrays. If you prefer to use mutable arrays throughout your project, you can change this behavior globally by adding a declaration to a global.d.ts file in your project.

declare namespace Belt {
  type UseMutableArrays = 1
}