@effect/data

What is @effect/data?

@effect/data is a functional programming library for JavaScript and TypeScript that provides a collection of data structures and utilities to work with immutable data, functional effects, and more. It aims to help developers write more predictable and maintainable code by leveraging functional programming principles.

What are @effect/data's main functionalities?

Immutable Data Structures

Provides immutable data structures like List, Map, and Set. These structures help in maintaining immutability in your code, making it easier to reason about state changes.

const { List } = require('@effect/data');

const list = List.of(1, 2, 3);
const newList = list.append(4);
console.log(newList.toArray()); // [1, 2, 3, 4]

Functional Effects

Allows you to work with functional effects, which are computations that can produce side effects. This helps in managing side effects in a controlled manner.

const { Effect } = require('@effect/data');

const effect = Effect.of(() => console.log('Hello, World!'));
effect.run();

Option and Either

Provides Option and Either types for handling optional values and computations that can fail, respectively. These types help in avoiding null or undefined values and managing errors more effectively.

const { Option, Either } = require('@effect/data');

const someValue = Option.some(42);
const noneValue = Option.none();

const rightValue = Either.right('Success');
const leftValue = Either.left('Error');

console.log(someValue.isSome()); // true
console.log(noneValue.isNone()); // true
console.log(rightValue.isRight()); // true
console.log(leftValue.isLeft()); // true

Pattern Matching

Supports pattern matching, which allows you to match values against patterns and execute code based on the matched pattern. This can make your code more expressive and concise.

const { match } = require('@effect/data');

const value = 2;
const result = match(value)
  .case(1, () => 'one')
  .case(2, () => 'two')
  .case(3, () => 'three')
  .default(() => 'unknown');

console.log(result); // 'two'

Other packages similar to @effect/data

immutable

The 'immutable' package provides persistent immutable data structures for JavaScript, such as List, Map, and Set. It is similar to @effect/data in terms of offering immutable data structures but does not include functional effects or pattern matching.

folktale

Folktale is a suite of libraries for generic functional programming in JavaScript. It includes data structures like Maybe and Either, similar to Option and Either in @effect/data. However, Folktale also provides utilities for asynchronous programming and algebraic data types.

ramda

Ramda is a practical functional library for JavaScript programmers. It focuses on providing utility functions for functional programming, such as currying, composition, and immutability. While it does not provide data structures like @effect/data, it complements it by offering a wide range of functional utilities.

README

Installation

To install the alpha version:

npm install @effect/data

Warning. This package is primarily published to receive early feedback and for contributors, during this development phase we cannot guarantee the stability of the APIs, consider each release to contain breaking changes.

Requirements

• TypeScript 5.0 or newer
• The strict flag enabled in your tsconfig.json file

{
  // ...
  "compilerOptions": {
    // ...
    "strict": true,
  }
}

Documentation (WIP)

• API Reference

License

The MIT License (MIT)

Contributing Guidelines

Thank you for considering contributing to our project! Here are some guidelines to help you get started:

Reporting Bugs

If you have found a bug, please open an issue on our issue tracker and provide as much detail as possible. This should include:

• A clear and concise description of the problem
• Steps to reproduce the problem
• The expected behavior
• The actual behavior
• Any relevant error messages or logs

Suggesting Enhancements

If you have an idea for an enhancement or a new feature, please open an issue on our issue tracker and provide as much detail as possible. This should include:

• A clear and concise description of the enhancement or feature
• Any potential benefits or use cases
• Any potential drawbacks or trade-offs

Pull Requests

We welcome contributions via pull requests! Here are some guidelines to help you get started:

1. Fork the repository and clone it to your local machine.
2. Create a new branch for your changes: git checkout -b my-new-feature
3. Install dependencies: pnpm install (pnpm@8.x)
4. Make your changes and add tests if applicable.
5. Run the tests: pnpm test
6. Create a changeset for your changes: before committing your changes, create a changeset to document the modifications. This helps in tracking and communicating the changes effectively. To create a changeset, run the following command: pnpm changeset.
7. Commit your changes: after creating the changeset, commit your changes with a descriptive commit message: git commit -am 'Add some feature'.
8. Push your changes to your fork: git push origin my-new-feature.
9. Open a pull request against our main branch.

Pull Request Guidelines

• Please make sure your changes are consistent with the project's existing style and conventions.
• Please write clear commit messages and include a summary of your changes in the pull request description.
• Please make sure all tests pass and add new tests as necessary.
• If your change requires documentation, please update the relevant documentation.
• Please be patient! We will do our best to review your pull request as soon as possible.

License

By contributing to this project, you agree that your contributions will be licensed under the project's MIT License.

Changelog

0.18.5

Patch Changes

• #485 d96a5a4 Thanks @fubhy! - Add Uint8Array predicate

• #490 c2c34a1 Thanks @gcanti! - Equal: remove redundant code from equivalence instance implementation

• #493 acbd896 Thanks @gcanti! - refactor toJSON / toString, closes #492