monet.js Documentation

MonetJS provides several specialized monads for different functional programming patterns:

• Maybe: For handling optional values (presence/absence).
• Either: For handling computations that can result in one of two values (typically a success value or an error value).
• Validation: For accumulating errors during validation processes.
• List: For working with collections of items.
• Non Empty List (NEL): A list that is guaranteed to contain at least one element.
• IO: For managing side effects.
• Reader: For dependency injection and accessing shared environment/context.
• Free: For building and interpreting domain-specific languages (DSLs).

The Maybe type is used to represent nothingness (the null type) while eliminating NullPointer issues. It is an abstract type with two concrete subtypes:

1. Some (also known as Just): Represents the presence of a value.
2. None (also known as Nothing): Represents the absence of a value.

Critical Warning: The monet implementation treats null and undefined specially. Any attempt to provide null or undefined to a constructor (except via fromNull, fromFalsy, or fromUndefined) will throw an exception. Similarly, mapping a Maybe to null or undefined will cause errors.

The IO monad is used to isolate side effects to maintain referential transparency in your software. Instead of executing an effect immediately (like reading from a DOM or writing to a database), you create a lazy description of that effect.

Key characteristics:

• Lazy evaluation: The effect is not performed until the .run() (or .perform()) method is explicitly called.
• Referential transparency: By wrapping side-effecting functions in IO, you can treat them as pure values that describe an action rather than the action itself.
• Execution pattern: The standard pattern is to start with an effect (reading data), perform pure transformations on that data, and end with an effect (writing data). The run() method should typically be called only once at the very end of your program.

Either (or the disjunct union) is a type that can hold a value of type A or a value of type B but never both simultaneously. It is primarily used to represent computations that can fail, providing a safer alternative to exception handling.

Either is right-biased, meaning that transformation methods like map and flatMap operate on the Right side (the success side). The Left side is typically used to hold error or failure information.

The IO monad is used to isolate side effects to maintain referential transparency. It allows you to create a description of an effect that is only executed as the final action in your program.

IO is lazy; it will not be evaluated until you call the perform method (which is aliased as run).

The Validation type, represented as Validation[E,A], holds either a success value (A) or a failure value (E, such as an error message).

While it provides monad-like methods, it is not strictly a monad because it does not follow all monad rules. Its primary purpose is to allow for the accumulation of errors.

The Free monad is a tool used to separate instructions from their interpreter. This separation allows you to define a sequence of operations (the instructions) without specifying how they are actually executed.

A common use case is implementing Trampolines, which enables constant stack recursion in environments like JavaScript that do not natively support tail call elimination.

The Either type (or disjunct union) holds either a value of type A or a value of type B, but never both. It is typically used for error handling as a better alternative to exceptions.

Either is right-biased, meaning that map and flatMap (bind) operations are performed on the right side (the success side).

• Right side: Holds the success value.
• Left side: Holds the failure value.