hkt-toolbelt

hkt-toolbelt

A higher-kinded-type companion to ts-toolbelt.

Installation

npm install hkt-toolbelt

Usage

import { List, Conditional } from "hkt-toolbelt/list";

// Filter a tuple to only numbers
type FilterNumbers = List.Filter<Conditional.SubtypeOf<number>>;

// A :: [1, 2, 3]
type A = $<FilterNumbers, [1, null, 2, 3, "4"]>;

Purpose

This library is a companion to ts-toolbelt that provides higher-kinded-type versions of its functionality. This allows for more complex types to be constructed.

• hkt-toolbelt
  • Installation
  • Usage
  • Purpose
• API
  • Basic Utilities
    • $<F, A>
    • Cast<A, B>
  • Boolean Types
    • Boolean.And<A>
    • Boolean.Not
  • Conditional Types
    • Conditional.Equals<A>
    • Conditional.SubtypeOf<A>
  • Function Types
    • Function
  • Kind Types
    • Kind<F>
    • Kind.Compose<FX>
    • Kind._
  • List Types
    • List.Map<F>
    • List.Find<F>
    • List.Filter<F>
    • List.Append<F>
    • List.Last<T>
    • List.Pair<T>
  • String Types
    • String.StartsWith<S>
    • String.EndsWith<S>
    • String.Includes<S>

API

The curried nature of the functions in this library is intended to be utilized to compose types using point-free style. In this respect, API types will first take in 'operations' and then the data to be operated on.

All type functions (e.g. full Kinds) take in one parameter at a time, to support currying and point-free style.

Basic Utilities

$<F, A>

The $ operator is used to apply a higher-kinded-type function to a type. It is equivalent to the F<A> syntax in TypeScript.

Cast<A, B>

The Cast type is used to cast a type to another type. It is equivalent to the A as B syntax in TypeScript.

Boolean Types

Boolean.And<A>

The And type takes in a boolean and returns a function that takes in another boolean and returns the result of the two booleans being &&'d together.

Boolean.Not

The Not type takes in a boolean and returns the opposite boolean.

Conditional Types

Conditional.Equals<A>

The Equals type is used to check if a type is equal to another type. It is equivalent to the A extends B ? (B extends A ? true : false) : false syntax in TypeScript.

Equals returns a higher-kinded-type function that takes a type and returns a boolean.

Conditional.SubtypeOf<A>

The SubtypeOf type is used to check if a type is a subtype of another type. It is equivalent to the A extends B ? true : false syntax in TypeScript.

SubtypeOf returns a higher-kinded-type function that takes a type and returns a boolean.

Function Types

Function

The Function type is a supertype of all functions, i.e. all functions are a subtype of Function.

Kind Types

Kind<F>

The Kind type denotes a type function that may be applied to a type using $.

The Kind type can optionally be provided a function type to increase the specificity of its internal parameter and return types.

Kind.Compose<FX>

The Compose type takes in a tuple of type functions, and composes them into one type function.

Kind._

The _ type represents the 'placeholder variable' used in type functions before application.

List Types

List.Map<F>

The Map function takes in a type function, and returns a higher kinded type that takes in a tuple type. It applies the given type function over every element in the tuple.

List.Find<F>

The Find function takes in a type function, then a tuple, and returns the first tuple element for which the finder function returns true. If no such element exists, Find returns never.

List.Filter<F>

The Filter function takes in a type function, and a tuple, and returns a tuple in-order of the input tuple, whereby only elements for which the filter function returns true remain in the resultant tuple.

List.Append<F>

The Append function takes in a type, and a tuple, and applies the type such that it is appended to the end of the provided tuple.

List.Last<T>

The Last function takes in a tuple, and returns the last element of the tuple. In the case of tuples with variadic elements, the variadic element is properly handled, even if it's infix.

List.Pair<T>

The Pair function takes in a tuple, and returns a tuple of tuples, where each tuple is a pair of the original tuple's elements, in order. e.g. [1, 2, 3] becomes [[1, 2], [2, 3]].

For variadic tuples, the variadic element is handled via introducing unions to represent the possible combinations of variadic pair elements.

String Types

String.StartsWith<S>

The StartsWith function takes in a string literal and returns whether or not it starts with the given prefix, returning true or false as appropriate.

All strings start with string, so StartsWith<string> will return true for all subsequent string types.

However, string starts with no particular prefix, so $<StartsWith<"f">, string> will result in false. All strings start with the empty string, as well.

String.EndsWith<S>

The EndsWith function takes in a string literal and returns whether or not it ends with the given suffix, returning true or false as appropriate.

@see String.StartsWith

String.Includes<S>

The Includes function takes in a string literal and returns whether or not it is a substring of the given string, returning true or false as appropriate.

@see String.StartsWith

Changelog

[0.1.0]

• First experimental release.
• Introduce Boolean, Cast, Conditional, Function, Kind, List, String, and Test core components.