From d5c3af89ab8076bcf4107859c1ba6b47a7815142 Mon Sep 17 00:00:00 2001 From: Akshay Nair Date: Sun, 15 Jan 2023 00:13:04 +0530 Subject: chore: some more documentation --- docs/README.md | 44 ++++++++++++++++++++++++----------- docs/interfaces/effect.Bind.md | 11 +++++---- docs/interfaces/effect.BindTo.md | 14 +++++++---- docs/interfaces/effect.Do.md | 9 ++++--- docs/interfaces/effect.Kind1.md | 4 ++-- docs/interfaces/effect.Label.md | 9 ++++--- docs/interfaces/effect.Noop.md | 4 ++-- docs/interfaces/effect.Pure.md | 6 ++--- docs/interfaces/effect.Seq.md | 9 ++++--- docs/interfaces/test.AssertEqualsK.md | 28 +++++++++++----------- docs/interfaces/test.Test.md | 16 +++++++++---- docs/interfaces/util.ConstK.md | 4 ++-- docs/interfaces/util.IdK.md | 4 ++-- docs/modules/effect.md | 2 +- docs/modules/nat.md | 28 +++++++++++----------- docs/modules/ref.md | 2 +- docs/modules/stdio.md | 2 +- docs/modules/test.md | 21 ++++++++++++++++- docs/modules/util.md | 12 +++++----- 19 files changed, 143 insertions(+), 86 deletions(-) (limited to 'docs') diff --git a/docs/README.md b/docs/README.md index c38000c..c52b415 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,35 +1,51 @@ ts-types-lang / [Modules](modules.md) -# TS Types lang [WIP] -A runtime for typescript's **type system** that turns it into a **general purpose**, **purely functional** programming language! +# TS Types lang +A runtime for typescript's **type system** that turns it into a **general purpose**, **purely functional** programming language with effects! -Take a look at the [./examples](./examples) directory for examples on how to write a program in typescript types +### Documentation +- [stdlib reference](./docs/modules.md) +- [examples](./examples/) ### Example +Take a look at the [./examples](./examples) directory for more examples on how to write a program in typescript types + ```typescript -import { Bind, Kind1, Do } from 'ts-types-lang/stdlib/effect' +import { Bind } from 'ts-types-lang/stdlib/effect' import { PutString, PutStringLn, ReadLine } from 'ts-types-lang/stdlib/stdio' -// :: string -> Effect () -interface GreetK extends Kind1 { - return: PutString<`Hello, ${this['input']}`>, -} - -// main :: [Effect ()] | Effect () export type main = [ PutString<"Your name? ">, - Bind, + // Read a line from stdin and then greet + Bind() => + PutStringLn<`Hello, ${name}`>>, ] ``` -To run it - +### Run a types-lang module + +Install it - +```bash +npm i --save ts-types-lang +# OR +yarn add ts-types-lang +``` + +Or just run it - ```bash npx tsr run ./examples/guess-number.ts -// OR +# OR yarn exec tsr run ./examples/guess-number.ts ``` -### Why? +### FAQ + +#### Why? +I dunno + +#### How? +I dunno +#### What? I dunno diff --git a/docs/interfaces/effect.Bind.md b/docs/interfaces/effect.Bind.md index 334bd5f..bc42d06 100644 --- a/docs/interfaces/effect.Bind.md +++ b/docs/interfaces/effect.Bind.md @@ -4,20 +4,23 @@ [effect](../modules/effect.md).Bind -Generic interface for declaring effects +Monadic bind an effect to a function (Equivalent to haskell's >>= operator) **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Bind< + ReadFile<"./file.txt">, + () => Print +> ``` ## Type parameters | Name | Type | Description | | :------ | :------ | :------ | -| `_Eff` | extends [`Effect`](effect.Effect.md) | The output generated by the effect (defaults to `unknown`) | -| `_Fn` | extends [`Func`](../modules/effect.md#func) | - | +| `_Eff` | extends [`Effect`](effect.Effect.md) | Effect to evaluate first | +| `_Fn` | extends [`Func`](../modules/effect.md#func) | Function to call with the result of _Eff | ## Hierarchy diff --git a/docs/interfaces/effect.BindTo.md b/docs/interfaces/effect.BindTo.md index c333393..0775364 100644 --- a/docs/interfaces/effect.BindTo.md +++ b/docs/interfaces/effect.BindTo.md @@ -4,20 +4,26 @@ [effect](../modules/effect.md).BindTo -Generic interface for declaring effects +Bind result of evaluating an effect to a label (Equivalent to haskell's <- syntax) + +Note: labels are scoped to outermost Do, Bind, Try, etc scopes **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Do<[ + // contents <- readFile "./file.txt" + BindTo<"contents", ReadFile<"./file.txt">>, + Bind, () => Print> +]> ``` ## Type parameters | Name | Type | Description | | :------ | :------ | :------ | -| `_Name` | extends `string` | The output generated by the effect (defaults to `unknown`) | -| `_Eff` | extends [`Effect`](effect.Effect.md) | - | +| `_Name` | extends `string` | The name of label | +| `_Eff` | extends [`Effect`](effect.Effect.md) | Effect to evaluate | ## Hierarchy diff --git a/docs/interfaces/effect.Do.md b/docs/interfaces/effect.Do.md index 504f9c0..1039bc7 100644 --- a/docs/interfaces/effect.Do.md +++ b/docs/interfaces/effect.Do.md @@ -4,19 +4,22 @@ [effect](../modules/effect.md).Do -Generic interface for declaring effects +Evaluate a sequence of effects in series and get the result of the last effect (Equivalent to haskell's do syntax) **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Bind< + Do<[ Pure<1>, ReadFile<"./foobar.txt"> ]>, + () => Print +> ``` ## Type parameters | Name | Type | Description | | :------ | :------ | :------ | -| `_Effs` | extends [`Effect`](effect.Effect.md)[] | The output generated by the effect (defaults to `unknown`) | +| `_Effs` | extends [`Effect`](effect.Effect.md)[] | List of effects | ## Hierarchy diff --git a/docs/interfaces/effect.Kind1.md b/docs/interfaces/effect.Kind1.md index 0c8600f..dc0ed2f 100644 --- a/docs/interfaces/effect.Kind1.md +++ b/docs/interfaces/effect.Kind1.md @@ -52,7 +52,7 @@ type result = ApplyK #### Defined in -[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/effect.ts#L35) +[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/effect.ts#L35) ___ @@ -62,4 +62,4 @@ ___ #### Defined in -[effect.ts:36](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/effect.ts#L36) +[effect.ts:36](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/effect.ts#L36) diff --git a/docs/interfaces/effect.Label.md b/docs/interfaces/effect.Label.md index f4d9c2c..d007d64 100644 --- a/docs/interfaces/effect.Label.md +++ b/docs/interfaces/effect.Label.md @@ -4,19 +4,22 @@ [effect](../modules/effect.md).Label -Generic interface for declaring effects +Access a label defined with [BindTo](effect.BindTo.md) **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Do<[ + BindTo<"contents", ReadFile<"./file.txt">>, + Bind, () => Print> +]> ``` ## Type parameters | Name | Type | Description | | :------ | :------ | :------ | -| `_Name` | extends `string` | The output generated by the effect (defaults to `unknown`) | +| `_Name` | extends `string` | The name of label | ## Hierarchy diff --git a/docs/interfaces/effect.Noop.md b/docs/interfaces/effect.Noop.md index 79cd0d7..9666460 100644 --- a/docs/interfaces/effect.Noop.md +++ b/docs/interfaces/effect.Noop.md @@ -4,12 +4,12 @@ [effect](../modules/effect.md).Noop -Generic interface for declaring effects +Noop effect that does nothing (returns undefined) **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Bind() => Print> ``` ## Hierarchy diff --git a/docs/interfaces/effect.Pure.md b/docs/interfaces/effect.Pure.md index 69fd304..5e179f3 100644 --- a/docs/interfaces/effect.Pure.md +++ b/docs/interfaces/effect.Pure.md @@ -4,19 +4,19 @@ [effect](../modules/effect.md).Pure -Generic interface for declaring effects +Wrap a value inside an effect (Equivalent to haskell's pure function) **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Bind, () => Print> ``` ## Type parameters | Name | Description | | :------ | :------ | -| `V` | The output generated by the effect (defaults to `unknown`) | +| `V` | Value | ## Hierarchy diff --git a/docs/interfaces/effect.Seq.md b/docs/interfaces/effect.Seq.md index 3604873..6e52a12 100644 --- a/docs/interfaces/effect.Seq.md +++ b/docs/interfaces/effect.Seq.md @@ -4,19 +4,22 @@ [effect](../modules/effect.md).Seq -Generic interface for declaring effects +Evaluate a sequence of effects in series and get the list of results **`Example`** ```ts -interface MyEffect extends Effect {} +type main = Bind< + Seq<[ Pure<1>, ReadFile<"./foobar.txt"> ]>, + () => Print +> ``` ## Type parameters | Name | Type | Description | | :------ | :------ | :------ | -| `_Effs` | extends [`Effect`](effect.Effect.md)[] | The output generated by the effect (defaults to `unknown`) | +| `_Effs` | extends [`Effect`](effect.Effect.md)[] | List of effects | ## Hierarchy diff --git a/docs/interfaces/test.AssertEqualsK.md b/docs/interfaces/test.AssertEqualsK.md index b2c2e81..6390521 100644 --- a/docs/interfaces/test.AssertEqualsK.md +++ b/docs/interfaces/test.AssertEqualsK.md @@ -4,27 +4,25 @@ [test](../modules/test.md).AssertEqualsK -An implementation of `* -> *` higher-kinded type +An alternate point-free api for [AssertEquals](../modules/test.md#assertequals) -**`Example`** +**`Type Param`** -You can define a return property for the function body - and use `this['input']` to access the argument - Uses - [ApplyK](../modules/util.md#applyk) +Right value -```ts -interface SomeFunc extends Kind1 { - return: `Your number is ${this['input']}`, -} +**`Example`** -type result = ApplyK +```ts +type main = [ + Bind, AssertEqualsK<63>> +] ``` ## Type parameters -| Name | Type | Description | -| :------ | :------ | :------ | -| `Right` | extends `unknown` | The input type | +| Name | Type | +| :------ | :------ | +| `Right` | extends `unknown` | ## Hierarchy @@ -51,7 +49,7 @@ type result = ApplyK #### Defined in -[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/effect.ts#L35) +[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/effect.ts#L35) ___ @@ -65,4 +63,4 @@ ___ #### Defined in -[test.ts:34](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/test.ts#L34) +[test.ts:77](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/test.ts#L77) diff --git a/docs/interfaces/test.Test.md b/docs/interfaces/test.Test.md index b503cc0..583569a 100644 --- a/docs/interfaces/test.Test.md +++ b/docs/interfaces/test.Test.md @@ -1,23 +1,29 @@ [ts-types-lang](../README.md) / [Modules](../modules.md) / [test](../modules/test.md) / Test -# Interface: Test<_m, _effs\> +# Interface: Test<_M, _Effs\> [test](../modules/test.md).Test -Generic interface for declaring effects +Create a test block **`Example`** ```ts -interface MyEffect extends Effect {} +type main = [ + Test<"should check if result is 21", [ + Bind, () => AssertEquals>, + // equivalent to... + Bind, AssertEqualsK<21>>, + ]> +] ``` ## Type parameters | Name | Type | Description | | :------ | :------ | :------ | -| `_m` | extends `string` | The output generated by the effect (defaults to `unknown`) | -| `_effs` | extends [`Effect`](effect.Effect.md)[] | - | +| `_M` | extends `string` | description of the test | +| `_Effs` | extends [`Effect`](effect.Effect.md)[] | List of effects to evaluate | ## Hierarchy diff --git a/docs/interfaces/util.ConstK.md b/docs/interfaces/util.ConstK.md index 71db6c3..1b42f9c 100644 --- a/docs/interfaces/util.ConstK.md +++ b/docs/interfaces/util.ConstK.md @@ -51,7 +51,7 @@ type result = ApplyK #### Defined in -[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/effect.ts#L35) +[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/effect.ts#L35) ___ @@ -65,4 +65,4 @@ ___ #### Defined in -[util.ts:13](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L13) +[util.ts:13](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L13) diff --git a/docs/interfaces/util.IdK.md b/docs/interfaces/util.IdK.md index 35bcab6..361cbc0 100644 --- a/docs/interfaces/util.IdK.md +++ b/docs/interfaces/util.IdK.md @@ -45,7 +45,7 @@ type result = ApplyK #### Defined in -[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/effect.ts#L35) +[effect.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/effect.ts#L35) ___ @@ -59,4 +59,4 @@ ___ #### Defined in -[util.ts:9](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L9) +[util.ts:9](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L9) diff --git a/docs/modules/effect.md b/docs/modules/effect.md index 621dede..bfb3341 100644 --- a/docs/modules/effect.md +++ b/docs/modules/effect.md @@ -49,4 +49,4 @@ type main = Bind< #### Defined in -[effect.ts:56](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/effect.ts#L56) +[effect.ts:56](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/effect.ts#L56) diff --git a/docs/modules/nat.md b/docs/modules/nat.md index 40bddf7..0430c20 100644 --- a/docs/modules/nat.md +++ b/docs/modules/nat.md @@ -36,7 +36,7 @@ #### Defined in -[nat.ts:6](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L6) +[nat.ts:6](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L6) ___ @@ -54,7 +54,7 @@ ___ #### Defined in -[nat.ts:14](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L14) +[nat.ts:14](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L14) ___ @@ -64,7 +64,7 @@ ___ #### Defined in -[nat.ts:1](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L1) +[nat.ts:1](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L1) ___ @@ -80,7 +80,7 @@ ___ #### Defined in -[nat.ts:4](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L4) +[nat.ts:4](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L4) ___ @@ -102,7 +102,7 @@ ___ #### Defined in -[nat.ts:3](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L3) +[nat.ts:3](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L3) ___ @@ -119,7 +119,7 @@ ___ #### Defined in -[nat.ts:10](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L10) +[nat.ts:10](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L10) ___ @@ -135,7 +135,7 @@ ___ #### Defined in -[nat.ts:2](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L2) +[nat.ts:2](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L2) ___ @@ -145,7 +145,7 @@ ___ #### Defined in -[nat.ts:20](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L20) +[nat.ts:20](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L20) ___ @@ -155,7 +155,7 @@ ___ #### Defined in -[nat.ts:21](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L21) +[nat.ts:21](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L21) ___ @@ -165,7 +165,7 @@ ___ #### Defined in -[nat.ts:22](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L22) +[nat.ts:22](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L22) ___ @@ -175,7 +175,7 @@ ___ #### Defined in -[nat.ts:23](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L23) +[nat.ts:23](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L23) ___ @@ -185,7 +185,7 @@ ___ #### Defined in -[nat.ts:24](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L24) +[nat.ts:24](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L24) ___ @@ -195,7 +195,7 @@ ___ #### Defined in -[nat.ts:25](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L25) +[nat.ts:25](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L25) ___ @@ -205,4 +205,4 @@ ___ #### Defined in -[nat.ts:26](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/nat.ts#L26) +[nat.ts:26](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/nat.ts#L26) diff --git a/docs/modules/ref.md b/docs/modules/ref.md index d282eaa..aacdb6c 100644 --- a/docs/modules/ref.md +++ b/docs/modules/ref.md @@ -23,4 +23,4 @@ #### Defined in -[ref.ts:6](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/ref.ts#L6) +[ref.ts:6](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/ref.ts#L6) diff --git a/docs/modules/stdio.md b/docs/modules/stdio.md index ba6eb16..21f5f15 100644 --- a/docs/modules/stdio.md +++ b/docs/modules/stdio.md @@ -30,4 +30,4 @@ #### Defined in -[stdio.ts:11](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/stdio.ts#L11) +[stdio.ts:11](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/stdio.ts#L11) diff --git a/docs/modules/test.md b/docs/modules/test.md index dc0ec99..df117e3 100644 --- a/docs/modules/test.md +++ b/docs/modules/test.md @@ -21,6 +21,25 @@ Ƭ **AssertEquals**<`Left`, `Right`\>: [`Try`](../interfaces/exception.Try.md)<[`Assert`](../interfaces/test.Assert.md)<[`Equals`](util.md#equals)<`Left`, `Right`\>\>, () => [`Do`](../interfaces/effect.Do.md)<[[`ShowAssertionError`](../interfaces/test.ShowAssertionError.md)<`Left`, `Right`\>, [`Throw`](../interfaces/exception.Throw.md)<`m`\>]\>\> +Assert if left and right values are equal structurally + +**`Type Param`** + +Left value + +**`Type Param`** + +Right value + +**`Example`** + +```ts +type main = [ + AssertEquals<`Foo ${'bar'}`, 'Foo bar'> + AssertEquals<[2, ...[3, 4]], [2, 3, 4]> +] +``` + #### Type parameters | Name | @@ -30,4 +49,4 @@ #### Defined in -[test.ts:28](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/test.ts#L28) +[test.ts:59](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/test.ts#L59) diff --git a/docs/modules/util.md b/docs/modules/util.md index 753e94b..d9ef12e 100644 --- a/docs/modules/util.md +++ b/docs/modules/util.md @@ -32,7 +32,7 @@ #### Defined in -[util.ts:23](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L23) +[util.ts:23](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L23) ___ @@ -49,7 +49,7 @@ ___ #### Defined in -[util.ts:5](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L5) +[util.ts:5](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L5) ___ @@ -66,7 +66,7 @@ ___ #### Defined in -[util.ts:29](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L29) +[util.ts:29](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L29) ___ @@ -90,7 +90,7 @@ ___ #### Defined in -[util.ts:7](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L7) +[util.ts:7](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L7) ___ @@ -106,7 +106,7 @@ ___ #### Defined in -[util.ts:3](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L3) +[util.ts:3](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L3) ___ @@ -122,4 +122,4 @@ ___ #### Defined in -[util.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/78e384c/stdlib/util.ts#L35) +[util.ts:35](https://github.com/phenax/ts-types-runtime-environment/blob/e75a5a1/stdlib/util.ts#L35) -- cgit v1.3.1