folktale

The folktale.core module provides utilities for handling native JavaScript objects using functional programming patterns. It is divided into two primary functional areas:

1. Lambda: Provides tools for manipulating functions, including utilities for combining functions and simplifying abstractions like currying and partial application.
2. Object: Provides functions to treat standard JavaScript objects as functional dictionaries.

The adt/union module is categorized into three main functional areas:

1. Constructing Data Structures: Functions used to create new tagged unions.
2. Extending Unions: Functions that allow you to extend existing Unions and variants with new functionality.
3. Derivation: Functions used as derivations to provide common functionality to Unions.

The folktale.core.object module provides utilities for treating JavaScript objects as dictionaries or records. It is designed for common use cases where objects represent configuration options, HTTP headers, or environment variables.

Important Behavior Note: Most operations in Core.Object focus exclusively on own, enumerable properties. Because all transformations are pure, they return a new object with a new identity. As a result, transformations will cause the object to lose:

• Symbols
• Non-enumerable properties
• The [[Prototype]] field (prototype chain)

For example, a round-trip transformation like toPairs(fromPairs(object)) may not result in an object equivalent to the original due to these property losses.

The folktale.core.lambda module provides tools for transforming and combining functions. It is designed to overcome the limitations of manual function composition in JavaScript by providing standardized ways to manipulate function signatures.

The module is organized into three main categories:

1. Combining: Functions that merge the functionality of different functions into a single function (e.g., function composition).
2. Combinators: Functions that rearrange arguments without adding special behavior (e.g., constant and identity).
3. Currying and Partialisation: Functions that transform how parameters are provided to a function, such as allowing parameters to be provided one at a time (currying) or providing a subset of positional parameters (partialisation).

Folktale provides two primary abstractions for managing asynchronous concurrent operations in JavaScript:

1. Task: Models asynchronous operations with built-in automatic resource management. Use Task when you need more robust control over the lifecycle of an asynchronous operation.
2. Future: A simpler alternative to the native JavaScript Promise. Use Future for straightforward asynchronous values where the advanced resource management of Task is not required.

A Result represents the outcome of a computation that may fail. Instead of throwing exceptions, functions return a Result object, allowing errors to be treated as first-class values.

A Result can be one of two cases:

• Ok(value): Represents a successful computation containing the result value.
• Error(value): Represents an unsuccessful computation containing the error value.

To use the value inside a Result, you must unwrap it using methods for sequencing, transforming, or extracting.

const Result = require('folktale/result');

const divideBy2 = (dividend, divisor) => {
  if (divisor === 0) {
    return Result.Error('Division by zero');
  } else {
    return Result.Ok(dividend / divisor);
  }
}

divideBy2(6, 3); // ==> Result.Ok(2)

A Task is a data structure that models asynchronous computations rather than just asynchronous values. Unlike Promises, Tasks support:

1. Safe Cancellation: Because a Task represents a computation, it can track allocated resources and clean them up when the computation is cancelled.
2. Automatic Resource Handling: Using the resolver.cleanup mechanism, you can ensure resources (like timers or file handles) are released regardless of whether the task succeeds, fails, or is cancelled.
3. Native Composition: Tasks support operations like sequencing and concurrent execution natively, which are often difficult or non-standard with raw callbacks or Promises.

While Promises represent a value that will eventually exist, a Task represents the process of computing that value.

A Result is a data structure used to model the outcome of operations that may fail. It provides a more controllable way to sequence operations and propagate errors compared to standard JavaScript try/catch or manual if/else branching.

A Result can be in one of two states:

• Ok(value): Represents a successful operation containing the resulting value.
• Error(value): Represents a failed operation containing the error value.

The Maybe data structure models the presence or absence of a value, helping to handle computations that might fail without throwing exceptions or returning ambiguous values like null or -1.

A Maybe structure has two cases:

• Just(value): Represents the presence of an answer and contains the value.
• Nothing(): Represents the absence of an answer.

Using Maybe forces the consumer of a function to acknowledge the possibility of failure because the value is wrapped and cannot be used directly.

const Maybe = require('folktale/maybe');

const find = (list, predicate) => {
  for (var i = 0; i < list.length; ++i) {
    const item = list[i];
    if (predicate(item)) {
      return Maybe.Just(item);
    }
  }
  return Maybe.Nothing();
};

find([1, 2, 3], (x) => x > 2); // ==> Maybe.Just(3)
find([1, 2, 3], (x) => x > 3); // ==> Maybe.Nothing()

The Validation data structure is used to model scenarios like form or schema validation where you want to aggregate all failures rather than short-circuiting at the first error.

Unlike the Result type (which is better for short-circuiting on the first error), Validation allows you to collect multiple error messages and present them all at once.

A Validation instance is one of two cases:

• Success(value): Represents a successful validation containing the successful value.
• Failure(value): Represents an unsuccessful validation containing the error(s).