hkt-toolbelt - npm Package Compare versions

Comparing version 0.3.0 to 0.4.0

changelog.md

 # Changelog
 
+## 0.4.0
+
+- Added shorthand `$$` pipe-application operator.
+- Added `Boolean.Or` for `||` HKT-level operator.
+- Added `Combinator.Self` and `Combinator.ApplySelf` combinators.
+- Added `Kind.Pipe` left-to-right composition.
+- Added `List.First`, `List.Some`, `List.Reverse` tuple utilities.
+- Improve `Test.Expect` error messages to use ᛰ for strict type equality.
+
 ## 0.3.0
@@ -4,0 +13,0 @@

dist/index.d.ts

 declare module "src/components/$" {
     import { Kind } from "src/index";
-    export type $<F extends Kind, X extends Kind.Input<F>> = ReturnType<(F & {
+    export type $<F extends Kind, X extends Kind.InputOf<F>> = ReturnType<(F & {
         readonly [Kind._]: X;
@@ -63,16 +63,26 @@ })["f"]>;
             infer Last
-        ] ? _$compose<Cast<Init, Kind[]>, $<Cast<Last, Kind>, Cast<X, Input<Cast<Last, Kind>>>>> : X;
-        type _$composable<F extends Kind, G extends Kind> = Kind.Output<G> extends Kind.Input<F> ? true : false;
-        abstract class Compose<FX extends Kind[]> extends Kind {
-            abstract f: (x: Cast<this[Kind._], FX extends [] ? unknown : Input<List._$last<FX>>>) => _$compose<FX, typeof x>;
+        ] ? _$compose<Cast<Init, Kind[]>, $<Cast<Last, Kind>, Cast<X, InputOf<Cast<Last, Kind>>>>> : X;
+        type _$composablePair<F extends [Kind, Kind]> = Kind.OutputOf<F[1]> extends Kind.InputOf<F[0]> ? true : false;
+        abstract class ComposablePair extends Kind {
+            abstract f: (x: Cast<this[Kind._], [Kind, Kind]>) => _$composablePair<typeof x>;
         }
+        type _$composable<FX extends Kind[]> = List._$every<Kind.ComposablePair, List._$pair<FX>>;
+        abstract class Composable extends Kind {
+            abstract f: (x: Cast<this[Kind._], Kind[]>) => _$composable<typeof x>;
+        }
+        abstract class Compose<FX extends _$composable<FX> extends true ? Kind[] : never> extends Kind {
+            abstract f: (x: Cast<this[Kind._], FX extends [] ? unknown : InputOf<List._$last<FX>>>) => _$compose<FX, typeof x>;
+        }
         abstract class Apply<X> extends Kind {
-            abstract f: (x: Cast<this[Kind._], Kind<(x: X) => unknown>>) => $<typeof x, Cast<X, Input<typeof x>>>;
+            abstract f: (x: Cast<this[Kind._], Kind<(x: X) => unknown>>) => $<typeof x, Cast<X, InputOf<typeof x>>>;
         }
-        type Input<F extends Kind> = F extends {
+        type InputOf<F extends Kind> = F extends {
             f: (x: infer X) => unknown;
         } ? X : unknown;
-        type Output<F extends Kind> = F extends {
+        type OutputOf<F extends Kind> = F extends {
             f: (x: never) => infer X;
         } ? X : unknown;
+        abstract class ApplySelf extends Kind {
+            abstract f: (x: Cast<this[Kind._], Kind>) => $<typeof x, Cast<typeof x, Kind.InputOf<typeof x>>>;
+        }
     }
@@ -90,3 +100,3 @@ const Kind_: typeof Kind;
         type _$map<F extends Kind, X extends unknown[]> = {
-            [key in keyof X]: $<F, Cast<X[key], Kind.Input<F>>>;
+            [key in keyof X]: $<F, Cast<X[key], Kind.InputOf<F>>>;
         };
@@ -99,3 +109,3 @@ abstract class Map<F extends Kind> extends Kind {
             ...infer Tail
-        ] ? $<F, Cast<Head, Kind.Input<F>>> extends true ? Head : _$find<F, Tail> : never;
+        ] ? $<F, Cast<Head, Kind.InputOf<F>>> extends true ? Head : _$find<F, Tail> : never;
         abstract class Find<F extends Kind<(x: never) => boolean>> extends Kind {
@@ -107,3 +117,3 @@ abstract f: (x: Cast<this[Kind._], unknown[]>) => _$find<F, typeof x>;
             ...infer Tail
-        ] ? $<F, Cast<Head, Kind.Input<F>>> extends true ? [Head, ..._$filter<F, Tail>] : _$filter<F, Tail> : [];
+        ] ? $<F, Cast<Head, Kind.InputOf<F>>> extends true ? [Head, ..._$filter<F, Tail>] : _$filter<F, Tail> : [];
         abstract class Filter<F extends Kind<(x: never) => boolean>> extends Kind {
@@ -115,3 +125,3 @@ abstract f: (x: Cast<this[Kind._], unknown[]>) => _$filter<F, typeof x>;
             ...infer Tail
-        ] ? $<F, Cast<Head, Kind.Input<F>>> extends true ? true : _$includes<F, Tail> : false;
+        ] ? $<F, Cast<Head, Kind.InputOf<F>>> extends true ? true : _$includes<F, Tail> : false;
         abstract class Includes<F extends Kind<(x: never) => boolean>> extends Kind {
@@ -140,5 +150,5 @@ abstract f: (x: Cast<this[Kind._], unknown[]>) => _$includes<F, typeof x>;
         }
-        type _$every<F extends Kind<(x: never) => boolean>, T extends unknown[]> = T extends [infer Head, ...infer Rest] ? Boolean._$and<$<F, Cast<Head, Kind.Input<F>>>, _$every<F, Rest>> : true;
+        type _$every<F extends Kind<(x: never) => boolean>, T extends unknown[]> = T extends [infer Head, ...infer Rest] ? Boolean._$and<$<F, Cast<Head, Kind.InputOf<F>>>, _$every<F, Rest>> : true;
         abstract class Every<F extends Kind<(x: never) => boolean>> extends Kind {
-            abstract f: (x: Cast<this[Kind._], Kind.Input<F>[]>) => _$every<F, typeof x>;
+            abstract f: (x: Cast<this[Kind._], Kind.InputOf<F>[]>) => _$every<F, typeof x>;
         }
@@ -163,2 +173,10 @@ }
         }
+        type _$append<Suffix extends string, S extends string> = `${S}${Suffix}`;
+        abstract class Append<Suffix extends string> extends Kind {
+            abstract f: (x: Cast<this[Kind._], string>) => _$append<Suffix, typeof x>;
+        }
+        type _$prepend<Prefix extends string, S extends string> = `${Prefix}${S}`;
+        abstract class Prepend<Prefix extends string> extends Kind {
+            abstract f: (x: Cast<this[Kind._], string>) => _$prepend<Prefix, typeof x>;
+        }
     }
@@ -170,5 +188,8 @@ export default String;
     type IsNever<X> = Conditional._$equals<X, never>;
+    abstract class TypeError<_S extends string> {
+        static readonly _: unique symbol;
+    }
     export namespace Test {
-        type Expect<X extends true> = IsNever<X> extends true ? Expect<X> : X;
-        type ExpectNot<X extends false> = IsNever<X> extends true ? ExpectNot<X> : X;
+        type Expect<X extends Conditional._$equals<X, V> extends true ? V : V & [_: TypeError<"NotEqual">], V = true> = IsNever<X> extends true ? Expect<X, V> : X;
+        type ExpectNot<X extends Conditional._$equals<X, V> extends true ? V : V & [_: TypeError<"Equal">], V = false> = IsNever<X> extends true ? Expect<X, V> : X;
     }
@@ -190,2 +211,16 @@ export default Test;
 }
+declare module "src/components/Combinator" {
+    import $, { Cast, Kind } from "src/index";
+    export namespace Combinator {
+        abstract class Self extends Kind {
+            abstract f: (x: this[Kind._]) => Self;
+        }
+        abstract class SelfApply extends Kind {
+            abstract f: (x: Cast<this[Kind._], Kind>) => $<typeof x, Cast<typeof x, Kind.InputOf<typeof x>>>;
+        }
+        abstract class Omega<T = true> extends Kind {
+            abstract f: (x: this[Kind._]) => $<SelfApply, T extends true ? SelfApply : never>;
+        }
+    }
+}
 declare module "test/components/Boolean.spec" { }
@@ -192,0 +227,0 @@ declare module "test/components/Kind.spec" { }

package.json

 {
   "name": "hkt-toolbelt",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A collection of useful HKT utilities and building blocks",
@@ -5,0 +5,0 @@ "main": "./src/index.ts",

readme.md

@@ -33,7 +33,12 @@ # hkt-toolbelt
   - [Basic Utilities](#basic-utilities)
-    - [$<F, A>](#f-a)
+    - [$<F, X>](#f-x)
+    - [$$<FX, X>](#fx-x)
     - [Cast<A, B>](#casta-b)
   - [Boolean Types](#boolean-types)
-    - [Boolean.And\<A>](#booleananda)
+    - [Boolean.And\<X>](#booleanandx)
+    - [Boolean.Or\<X>](#booleanorx)
     - [Boolean.Not](#booleannot)
+  - [Combinator Types](#combinator-types)
+    - [Combinator.Self](#combinatorself)
+    - [Combinator.ApplySelf](#combinatorapplyself)
   - [Conditional Types](#conditional-types)
@@ -50,2 +55,3 @@ - [Conditional.Equals\<A>](#conditionalequalsa)
     - [Kind.Compose\<FX>](#kindcomposefx)
+    - [Kind.Pipe\<FX>](#kindpipefx)
     - [Kind.\_](#kind_)
@@ -57,2 +63,3 @@ - [List Types](#list-types)
     - [List.Append\<F>](#listappendf)
+    - [List.First\<T>](#listfirstt)
     - [List.Last\<T>](#listlastt)
@@ -64,2 +71,4 @@ - [List.Pair\<T>](#listpairt)
     - [String.Includes\<S>](#stringincludess)
+    - [String.Append\<S>](#stringappends)
+    - [String.Prepend\<S>](#stringprepends)
 
@@ -74,16 +83,60 @@ # API
 
-### $<F, A>
+### $<F, X>
 
 The `$` operator is used to apply a higher-kinded-type function to a type. It is equivalent to the `F<A>` syntax in TypeScript.
 
+```ts
+import $, { String } from "hkt-toolbelt";
+
+type Result = $<String.Append<" world">, "hello">; // "hello world"
+```
+
+### $$<FX, X>
+
+The `$$` operator is used to apply a pipeline of kinds to a designated input type. This is a syntactic sugar for the `$` and `Kind.Compose` operators.
+
+@see `$`
+@see `Kind.Compose`
+
+```ts
+import { $$, Kind, String } from "hkt-toolbelt";
+
+type Result = $$<
+  Kind.Compose<String.Append<" world">, String.Append<"!">>,
+  "hello"
+>; // "hello world!"
+```
+
 ### 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.
+The `Cast` type is used to cast a type to another type. It is equivalent to the `A as B` syntax in TypeScript. For subtle cases.
 
+```ts
+import { Cast } from "hkt-toolbelt";
+
+type Result = Cast<"hello", string>; // "hello"
+```
+
 ## Boolean Types
 
-### Boolean.And\<A>
+### Boolean.And\<X>
 
 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.
 
+```ts
+import $, { Boolean } from "hkt-toolbelt";
+
+type Result = $<Boolean.And<true>, false>; // false
+```
+
+### Boolean.Or\<X>
+
+The `Or` 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.
+
+```ts
+import $, { Boolean } from "hkt-toolbelt";
+
+type Result = $<Boolean.Or<true>, false>; // true
+```
+
 ### Boolean.Not
@@ -93,2 +146,30 @@
 
+```ts
+import $, { Boolean } from "hkt-toolbelt";
+
+type Result = $<Boolean.Not, true>; // false
+```
+
+## Combinator Types
+
+### Combinator.Self
+
+The `Self` kind returns itself. This means it can be applied with $ infinitely.
+
+```ts
+import $, { Combinator } from "hkt-toolbelt";
+
+type Result = $<$<Combinator.Self, "foo">, "foo">; // Combinator.Self
+```
+
+### Combinator.ApplySelf
+
+The `ApplySelf` kind takes in a kind, and applies that kind to itself. This can be used to create syntho-recursive kinds.
+
+```ts
+import $, { Combinator } from "hkt-toolbelt";
+
+type Result = $<Combinator.ApplySelf, Function.Identity>; // Function.Identity
+```
+
 ## Conditional Types
@@ -102,2 +183,8 @@
 
+```ts
+import $, { Conditional } from "hkt-toolbelt";
+
+type Result = $<Conditional.Equals<"foo">, "bar">; // false
+```
+
 ### Conditional.SubtypeOf\<A>
@@ -107,4 +194,12 @@
 
+The first type passed in is the supertype, and the second type passed in is the subtype.
+
 `SubtypeOf` returns a higher-kinded-type function that takes a type and returns a boolean.
 
+```ts
+import $, { Conditional } from "hkt-toolbelt";
+
+type Result = $<Conditional.SubtypeOf<string>, "bar">; // true
+```
+
 ## Function Types
@@ -114,8 +209,14 @@
 
-The `Function` type is a supertype of all functions, i.e. all functions are a subtype of `Function`.
+The `Function` type is a supertype of all functions, i.e. all functions are a subtype of `Function`. It is not a kind and cannot be applied.
 
 ### Function.Constant\<A>
 
-The `Constant` type takes in a type and returns a function that takes in any type and returns the original type.
+The `Constant` type takes in a type and returns a function that takes in any type and returns the original type. It ignores its applied input and always returns the configured type.
 
+```ts
+import $, { Function } from "hkt-toolbelt";
+
+type Result = $<Function.Constant<"foo">, number>; // "foo"
+```
+
 ### Function.Identity
@@ -125,2 +226,8 @@
 
+```ts
+import $, { Function } from "hkt-toolbelt";
+
+type Result = $<Function.Identity, "foo">; // "foo"
+```
+
 ## Kind Types
@@ -132,8 +239,14 @@
 
-The Kind type can optionally be provided a function type to increase the specificity of its internal parameter and return types.
+The Kind type can optionally be provided a function type to increase the specificity of its internal parameter and return types. This is used to create new kinds.
 
 ### Kind.Composable\<FX>
 
-The `Composable` type checks whether a tuple of kinds are composable. A tuple of kinds is composable if the output of kind N is a subtype of the input of kind N-1.
+The `Composable` type checks whether a tuple of kinds are composable. A tuple of kinds is composable if the output of kind $N$ is a subtype of the input of kind $N-1$.
 
+```ts
+import $, { Kind, String } from "hkt-toolbelt";
+
+type Result = $<Kind.Composable, [String.Append<"bar">, String.Append<"foo">]>; // true
+```
+
 ### Kind.Compose\<FX>
@@ -145,5 +258,25 @@
 
+`Compose` executes functions from right to left, i.e. the last function in the tuple is executed first - as is traditional in mathematics.
+
+```ts
+import $, { Kind, String } from "hkt-toolbelt";
+
+type Result = $<Kind.Compose<[String.Append<"bar">, String.Append<"foo">]>, "">; // "foobar"
+```
+
+### Kind.Pipe\<FX>
+
+The `Pipe` type takes in a tuple of type functions, and pipes them into one type function. This operates from left to right, i.e. the first function in the tuple is executed first. This is the opposite order of `Compose`.
+
+`Pipe` is often more intuitive for programmers since it reads in order of execution. This is what `$$` uses internally.
+
+```ts
+import $, { Kind, String } from "hkt-toolbelt";
+
+type Result = $<Kind.Pipe<[String.Append<"foo">, String.Append<"bar">]>, "">; // "foobar"
+```
+
 ### Kind.\_
 
-The `_` type represents the 'placeholder variable' used in type functions before application.
+The `_` type represents the 'unique placeholder type' used in type functions before application. `Kind._` is used by `$` for application.
 
@@ -156,2 +289,8 @@ ## List Types
 
+```ts
+import $, { List, String } from "hkt-toolbelt";
+
+type Result = $<List.Map<String.Append<"bar">>, ["foo", "baz"]>; // ["foobar", "bazbar"]
+```
+
 ### List.Find\<F>
@@ -161,2 +300,8 @@
 
+```ts
+import $, { List, String } from "hkt-toolbelt";
+
+type Result = $<List.Find<String.StartsWith<"foo">>, ["bar", "foobar"]>; // "foobar"
+```
+
 ### List.Filter\<F>
@@ -166,2 +311,8 @@
 
+```ts
+import $, { List, String } from "hkt-toolbelt";
+
+type Result = $<List.Filter<String.StartsWith<"foo">>, ["bar", "foobar"]>; // ["foobar"]
+```
+
 ### List.Append\<F>
@@ -171,2 +322,18 @@
 
+```ts
+import $, { List } from "hkt-toolbelt";
+
+type Result = $<List.Append<"bar">, ["foo", "baz"]>; // ["foo", "baz", "bar"]
+```
+
+### List.First\<T>
+
+The `First` function takes in a tuple, and returns the first element of the tuple.
+
+```ts
+import $, { List } from "hkt-toolbelt";
+
+type Result = $<List.First, ["foo", "bar"]>; // "foo"
+```
+
 ### List.Last\<T>
@@ -176,2 +343,8 @@
 
+```ts
+import $, { List } from "hkt-toolbelt";
+
+type Result = $<List.Last, ["foo", "bar", "baz"]>; // "baz"
+```
+
 ### List.Pair\<T>
@@ -181,2 +354,8 @@
 
+```ts
+import $, { List } from "hkt-toolbelt";
+
+type Result = $<List.Pair, [1, 2, 3]>; // [[1, 2], [2, 3]]
+```
+
 For variadic tuples, the variadic element is handled via introducing unions to represent the possible combinations of variadic pair elements.
@@ -194,2 +373,8 @@
 
+```ts
+import $, { String } from "hkt-toolbelt";
+
+type Result = $<String.StartsWith<"foo">, "foobar">; // true
+```
+
 ### String.EndsWith\<S>
@@ -201,2 +386,8 @@
 
+```ts
+import $, { String } from "hkt-toolbelt";
+
+type Result = $<String.EndsWith<"bar">, "foobar">; // true
+```
+
 ### String.Includes\<S>
@@ -207,1 +398,27 @@
 @see `String.StartsWith`
+
+```ts
+import $, { String } from "hkt-toolbelt";
+
+type Result = $<String.Includes<"foo">, "barfoobar">; // true
+```
+
+### String.Append\<S>
+
+The `Append` function takes in a string literal and returns a higher-kinded-type function that takes in a string and returns the result of appending the string literal to the end of the string.
+
+```ts
+import $, { String } from "hkt-toolbelt";
+
+type Result = $<String.Append<"bar">, "foo">; // "foobar"
+```
+
+### String.Prepend\<S>
+
+The `Prepend` function takes in a string literal and returns a higher-kinded-type function that takes in a string and returns the result of prepending the string literal to the beginning of the string.
+
+```ts
+import $, { String } from "hkt-toolbelt";
+
+type Result = $<String.Prepend<"foo">, "bar">; // "foobar"
+```

src/components/$.ts

@@ -1,2 +0,2 @@
-import { Kind } from "hkt-toolbelt";
+import { Kind, List } from "hkt-toolbelt";
 
@@ -9,2 +9,7 @@ export type $<F extends Kind, X extends Kind.InputOf<F>> = ReturnType<
 
+export type $$<
+  FX extends Kind[],
+  X extends FX extends [] ? unknown : Kind.InputOf<List._$first<FX>>
+> = Kind._$pipe<FX, X>;
+
 export default $;

src/components/Boolean.ts

@@ -15,2 +15,13 @@ import { Cast, Kind } from "hkt-toolbelt";
 
+  export type _$or<T extends boolean, U extends boolean> = [T, U] extends [
+    false,
+    false
+  ]
+    ? false
+    : true;
+
+  export abstract class Or<T extends boolean> extends Kind {
+    abstract f: (x: Cast<this[Kind._], boolean>) => _$or<T, typeof x>;
+  }
+
   export type _$not<T extends boolean> = T extends true ? false : true;
@@ -17,0 +28,0 @@

src/components/Kind.ts

@@ -47,2 +47,12 @@ import $, { Cast, Function, List } from "hkt-toolbelt";
 
+  export type _$pipe<FX extends Kind[], X> = _$compose<List._$reverse<FX>, X>;
+
+  export abstract class Pipe<
+    FX extends _$composable<List._$reverse<FX>> extends true ? Kind[] : never
+  > extends Kind {
+    abstract f: (
+      x: Cast<this[Kind._], FX extends [] ? unknown : InputOf<List._$first<FX>>>
+    ) => _$pipe<FX, typeof x>;
+  }
+
   export abstract class Apply<X> extends Kind {
@@ -49,0 +59,0 @@ abstract f: (

src/components/List.ts

@@ -69,2 +69,8 @@ import $, { Boolean, Kind, Cast } from "hkt-toolbelt";
 
+  export type _$first<T extends unknown[]> = T extends [] ? never : T[0];
+
+  export abstract class First extends Kind {
+    abstract f: (x: Cast<this[Kind._], unknown[]>) => _$first<typeof x>;
+  }
+
   export type _$last<T extends unknown[]> = T extends [infer X]
@@ -110,4 +116,32 @@ ? X
   }
+
+  export type _$some<
+    F extends Kind<(x: never) => boolean>,
+    T extends unknown[]
+  > = T extends [infer Head, ...infer Rest]
+    ? Boolean._$or<$<F, Cast<Head, Kind.InputOf<F>>>, _$some<F, Rest>>
+    : false;
+
+  export abstract class Some<
+    F extends Kind<(x: never) => boolean>
+  > extends Kind {
+    abstract f: (
+      x: Cast<this[Kind._], Kind.InputOf<F>[]>
+    ) => _$some<F, typeof x>;
+  }
+
+  export type _$reverse<T extends unknown[]> = T extends [
+    infer Head,
+    ...infer Tail
+  ]
+    ? [..._$reverse<Tail>, Head]
+    : T extends [...infer Init, infer Last]
+    ? [Last, ..._$reverse<Init>]
+    : T;
+
+  export abstract class Reverse extends Kind {
+    abstract f: (x: Cast<this[Kind._], unknown[]>) => _$reverse<typeof x>;
+  }
 }
 
 export default List;

src/components/Test.ts

@@ -5,4 +5,4 @@ import { Conditional } from "hkt-toolbelt";
 
-declare abstract class TypeError<_S extends string> {
-  static readonly _: unique symbol;
+declare class ᛰ {
+  readonly ᛰ: symbol;
 }
@@ -12,5 +12,3 @@
   export type Expect<
-    X extends Conditional._$equals<X, V> extends true
-      ? V
-      : V & [_: TypeError<"NotEqual">],
+    X extends Conditional._$equals<X, V> extends true ? V : V & ᛰ,
     V = true
@@ -20,5 +18,3 @@ > = IsNever<X> extends true ? Expect<X, V> : X;
   export type ExpectNot<
-    X extends Conditional._$equals<X, V> extends true
-      ? V
-      : V & [_: TypeError<"Equal">],
+    X extends Conditional._$equals<X, V> extends true ? V : V & ᛰ,
     V = false
@@ -25,0 +21,0 @@ > = IsNever<X> extends true ? Expect<X, V> : X;

No alert changes

Improved metrics

Total package byte prevSize

48760

increased by34.01%

Number of package files

17

increased by6.25%

Lines of code

580

increased by18.61%

Number of lines in readme file

404

increased by116.04%

No dependency changes