Add documentation

[nadameu]

@nadameu Sorry for off-topic, just wanted to say I'm amazed at the work you've done here and this deserves many many stars. Unfortunately I can only give one, but I hope it helps! I'm itching to make use of this in some way, but as I noticed an absence of docs, I'm guessing it's not at a stage where it can really be generally used? I've got this on my github watching list now, and I'm really excited to see any future updates you might have for this, but I can understand how enormous the task of porting over all of this so far must have been. Really, this is rather incredible stuff. Anyway, sorry again for the off-topic comment. Wishing you a wonderful new year!

Originally posted by @MiracleBlue in #3 (comment)

[nadameu]

@MiracleBlue Thank you very much for your kind words.

I started this project to be able to use some of PureScript's concepts in TypeScript.

I am not a professional programmer, most of my experience is with userscripts to be run in the browser, with tools such as Greasemonkey and Tampermonkey, and Firefox Extensions.

Therefore, my programs require a lot of DOM and CSS parsing, validation and manipulation. Having tried out PureScript (and a few other functional compile-to-js languages, like ReasonML), I found that the verbosity of the generated code, and frankly, the peculiarities of PureScript's type system weren't suited for my needs. In some simple examples I found myself unsafely coercing lots of types which I knew were correct in JavaScript but PureScript's type system just couldn't figure out.

Nevertheless, I am passionate about functional programming and have tried to use a functional style in my TypeScript programs ever since I started learning about it. But something was missing. Concepts such as Maybes, Eithers, and all kinds of functors, applicatives and monads had entered my mind and were there to stay. So I had to bring some of that functionality to my workflow. PureScript was the best inspiration, since it is based on Haskell (which I admire but have not had the opportunity to work with), fixing some of its shortcomings and is focused on JavaScript.

This library is in a usable state, I would say, even if some tweaks still need to be made. Unfortunately, after all the time I spent working on this, I discovered that it is not very ergonomic to use in TypeScript. I find myself replacing Maybes with undefined and nullish coalescing operator, Eithers with Promises and so on.

Anyway, if you want to start experimenting with it, it is very well tested and should work ok, please report any bugs you eventually find.

If you use Microsoft VS Code, it should provide code completion for pretty much everything. Although the code is undocumented, most of the function names are the same as PureScript's, so their documentation should suffice to some extent.

The library exposes a function called pipeValue, which I use a lot.

import { pipeValue } from 'adt-ts';

pipeValue('Hello').pipe(
  x => [x],
  x => x.concat('world'),
  xs => xs.join(' '),
);

To avoid name clashes, functions that work with a particular type are grouped under a namespace, which is the name of the type in lowercase (maybe, either, array, and so on). These namespaces are also aliased for brevity (maybe as M and either as E, for instance).

import { pipeValue, Just, Nothing, M } from 'adt-ts';

pipeValue(Just('Hello')).pipe(
  M.map(x => x + ' world'),
  M.bind(x => x.length < 10 ? Nothing : Just(x)),
  M.fromMaybe(''),
);

That should be enough explanation to get you started, since I can't promise to find any time soon to properly document the library.

Don't hesitate to ask questions if something seems strange, or missing, or just plain wrong. I am very happy to see someone take an interest in this.