Guide · Open source
How to use fantasy-land: read the spec and follow its laws
Updated · written with AI from the project's own documentation and checked against our catalogue data
Fantasy Land is an open specification for interoperability of common algebraic structures in JavaScript. It is not a library you install or run, so using it means reading its method names and laws and making your own data types follow them. This guide explains what the spec covers, how to read it, and how to decide whether your code should follow it.
Fantasy Landfantasyland/fantasy-land · ★ 10.2k · MIT Install options & downloads Quick start
- 1Clone the repository. Run the git clone command from the source to get a local copy of the specification.
- 2Read the introduction and diagram. Look at the diagram of algebras to see how Setoid, Functor, Monoid and Monad relate.
- 3Learn the notation. Read the type signature notation section so you can parse :: , ~> and => in the method definitions.
- 4Pick an algebra. Choose the algebra your type needs, such as Functor for map or Monoid for concat and empty.
- 5Implement its dependencies. Check the README for the algebras your chosen one depends on and implement those too.
- 6Check the laws. Test your type against each law listed for the algebra before claiming it follows the spec.
What fantasy-land is and is not
Fantasy Land defines standard method names and laws for algebraic data types in JavaScript, such as Functor, Monoid and Monad. When types follow the same laws, separate libraries can swap values safely.
The project is a specification, not a package. The README describes laws rather than code to install.
Clone the repository and read the README
The source lists a single install-style command to get a local copy of the specification. Once cloned, the README is the main document to read.
The README opens with a diagram of the algebras and how they depend on each other, with links to each section.
git clone https://github.com/fantasyland/fantasy-landLearn the notation and terminology
The spec uses type signature notation borrowed from Sanctuary. The symbol :: means 'is a member of', ~> marks a method type, and => adds constraints on type variables.
Terms such as 'value' and 'equivalent' are defined carefully. Two lists are equivalent when they are equivalent at every index, and two functions are equivalent when they give equivalent outputs for equivalent inputs.
- e :: t reads as 'the expression e is a member of type t'.
- a ~> a -> a describes a method on objects of type a that takes an a and returns an a.
- Semigroup a => constrains type a to satisfy the Semigroup typeclass.
Understand how the algebras depend on each other
Each Fantasy Land algebra is a separate specification. Some algebras depend on others, and those dependencies must also be implemented.
For example, the diagram places Monad below Applicative and Chain, and Alternative below Plus and Applicative. Follow these links when you implement a type.
Make your types follow the laws
If you write functional-style data types, check each algebra you claim to support against its method names and laws. Only claim an algebra once your type satisfies all of its laws.
The README notes that some algebras need a value-level type representative, such as the Identity type, so plan for that in your design.
What people use it for
- Writing a custom data type in JavaScript whose map method behaves like other functional libraries' Functor.
- Checking whether a library's types follow a common interoperability standard before adopting it.
- Learning the vocabulary of functors, monoids and monads from a precise, written source.
- Publishing a library that aims to interoperate with other functional JavaScript libraries.
Frequently asked questions
Is fantasy-land a library I can install with npm?
No. The source describes Fantasy Land as a specification that defines laws rather than code to install. The only command given is to clone the repository from GitHub.
Is fantasy-land free to use?
The project is released under the MIT licence, according to the listing. The MIT licence is a permissive open-source licence.
What do I need to know before reading the fantasy-land spec?
The README assumes familiarity with algebraic concepts such as functors and monads. Beginners without interest in functional programming will find it hard to follow.
What is the difference between fantasy-land and fp-ts?
Fantasy Land is a specification of method names and laws, while fp-ts is a library of functional types. The source lists fp-ts as a comparable project, but it does not describe how the two differ in detail.
Can fantasy-land help with building ordinary web pages?
No. The spec does not provide UI or app tooling, so it is not suited to building ordinary web pages.
Which projects are comparable to fantasy-land?
The source lists Sanctuary, Ramda, Crocks and fp-ts as comparable projects.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Fantasy Land suits JavaScript developers who write functional-style data types or library authors who want their types to interoperate. If you only need to build web pages or want an installable package, pick a functional library such as Sanctuary, Ramda, Crocks or fp-ts instead.
Install options & downloads