functional is a set of utility modules in the vein of Ramda and fp-ts. It uses a lightweight higher kinded type encoding to implement type classes such as Functor, Monad, and Traversable. Originally, it followed the static-land specification for these modules, but has since diverged and settled on a curried form of those same module definitions. It contains many common algebraic types such as Option, Either, and other tools such as Lenses and Schemables.
The primary goals of functional are to be:
- Pragmatic: The API surface of functional should favor ease-of-use and consistency over cleverness or purity. This project is ultimately for getting work done.
- Understandable: The HKT and Type Class implementations are meant to be as simple as possible so their logic can be easily audited.
- Performant: Once the first two goals are satisfied, the long term changes within functional are likely going to be beneath the API surface and aimed at speeding things up where possible.
Some non-goals of functional are:
- To be an exact port of fp-ts. Many changes have been implemented throughout functional that diverge sharply from fp-ts, this is often on purpose.
functional started as an exploratory project in late 2020 to learn more about higher kinded type implementations in TypeScript and to assess how much effort it would take to port fp-ts to a Deno-native format. Through that process it became clear that the things I had learned could serve as both a useful tool and as a learning resource in and of itself. At various times functional has used multiple hkt encodings, type class definitions, and implementation methods. Some of the key history moments of functional are in the hkts history. Specifically, the hkts implementation in the initial commit and the last major type system rewrite might be interesting. Now, however, the API for version 1.0.0 is set and will only change between major versions (which should be extremely rare).
This project is incredibly indebted to gcanti, pelotom, and the TypeScript community at large. There is nothing new in this project, it's all a reimaginings of ideas that already existed.
For anyone getting started with functional programming I highly recommend writing your own implementation of an ADT such as Option or Either. From Functor to IndexedTraversable with everything inbetween, there is a lot to learn about the mechanics of programming in general by taking these small pieces apart and putting them back together.
Deno comes with a documentation generator. The
documentation generation doesn't handle
re-exports or types on consts that are functions, as that work progresses the
documentation for functional will improve. The current documentation for any
module at the HEAD of the main branch can be found here:
- Affect
- Array
- Const
- Datum
- Derivations
- Either
- Functions
- HKT
- Identity
- IO
- IOEither
- Map
- Monoid
- Nilable
- Option
- Ord
- Reader
- ReaderEither
- Record
- Semigroup
- Sequence
- Set
- Setoid
- State
- Task
- TaskEither
- These
- Tree
- Type Classes
- Types
- At
- Index
- Iso
- Lens
- Optional
- Prism
- Traversal
- Decoder
- Guard
- Schemable
In general, you can take any specific module url and put it into https://doc.deno.land/ to get a decent rendering of the documentation. (Note: Currently the deno_doc crate, which is what doc.deno.land uses, does not handle re-exports or const arrow function exports well. Eventually, the documentation will get better even if this libraries maintainers have to write those patches themselves).
| Version | Deno Release | TypeScript Version |
|---|---|---|
| 1.0.0 | 1.9.2 | 4.2.2 |
Contributions are welcome! Currently, the only maintainer for functional is baetheus. If you want to add to functional or change something, open an issue and ask away. The guidelines for contribution are:
- We use conventional commit messages
- We use semantic versioning
- We don't break APIs
- We keep test coverage at 100%