Repository files navigation

Functional is a no dependency utility library for TypeScript and JavaScript thatincludes a full suite of functional programming tools. Recent versions havemoved away from the jargon ofCategory Theory to a moreintuitive naming scheme unique to functional. However, for those that do haveexisting experience with functional programming or category theory, functionalincludes many algebraic data types (including implementations of algebraicstructures for native javascript structures), type classes, TypeScript-basedhigher kinded type substitutions, data-last utility combinators, and concretetype utilities.

The primary goals of functional are to be:

• Pragmatic: The API surface of functional should favor ease-of-use andconsistency over cleverness or purity. This project is ultimately for gettingwork done, even it if means a data structure or tools is not mathematicallysound in all use cases.
• Understandable: The higher kinded type and algebraic structureimplementations are meant to be as simple as possible so their logic can beeasily audited. We have also chosen descriptive names for TypeClassimplementations instead of ones pulled from Category Theory.
• Performant: Once the first two goals are satisfied, the long term changeswithin functional are likely going to be beneath the API surface and aimed atspeeding things up where possible.

Some non-goals of functional are:

• To be an exact port of fp-ts. Many changes have been implemented throughoutfunctional that diverge sharply from fp-ts, this is often on purpose.

This library is a collection of smaller tools. This means that each one shouldbe imported separately. There is no barrel export, instead one should pull inthe modules they need individually. Following is an example importing from jsrusing the deno runtime.

import*asAfrom"jsr:@baetheus/fun/array";import{pipe}from"jsr:@baetheus/fun/fn";pipe(A.range(5),// get 5 numbers 0-4A.map((n)=>n*n),// square themconsole.log,// [ 0, 1, 4, 9, 16 ]);

Documentation is generated for each github tagged release. The latestdocumentation can be foundhere. Following is alist of thealgebraic data types andalgebraic structures/type classesthat are implemented in fun. Note that some of these types are both datastructures and more general algebraic structures.

In the fashion of semantic versioning function makes an effort to not break APIson minor or patch releases. Occasionally, candidate tags (eg. 2.0.0-alpha.1)will be used to indicate a commit is ready for inspection by other developers offun. The main branch of fun is for bleeding edge developement and is notconsidered to be a production ready import.

functional started as an exploratory project in late 2020 to learn more abouthigher kinded type implementations in TypeScript and to assess how much effortit would take to port fp-ts to a Deno-native format. Through that process itbecame clear that the things I had learned could serve as both useful tools andas a learning resource in and of itself. At various times functional has usedmultiple hkt encodings, type class definitions, and implementation methods. Someof the key history moments of functional are in the hkts history. Specifically,thehkts implementationin the initial commit and the lastmajor type system rewritemight be interesting. Now, however, the API for version 1.0.0 is set and willonly change between major versions (which should be extremely rare).

This project is incredibly indebted togcanti,pelotom, and the TypeScript community at large.There is nothing new in this project, it's all a reimaginings of ideas thatalready existed.

For anyone getting started with functional programming I highly recommendwriting your own implementation of an ADT such as Option or Either. From Functorto IndexedTraversable with everything inbetween, there is a lot to learn aboutthe mechanics of programming in general by taking these small pieces apart andputting them back together.

Contributions are welcome! Currently, the only maintainer for functional isbaetheus. If you want to add to functional orchange something, open an issue and ask away. The guidelines for contributionare:

1. We are kind to others
2. We useconventional commit messages
3. We usesemantic versioning
4. We try to keep test coverage at 100%
5. We try not to break APIs between major releases

Since there is little churn in this library releases are infrequent. If you wishto contribute I would prefer that you start with documentation. It is one of mylong term goals to have a few sentences of description and an example for everyexport. After that, if I'm behind on test coverage that is a great place tostart. Last, if you wish to add a feature it's good to start a discussion aboutthe feature with a few concrete use cases before submitting a PR. This willallow for others to chime in without crowding the issues section.

Thanks for you interest!