DEV Community: Rich Ramalho

Apresentando holo-fn: uma biblioteca funcional mínima para TypeScript

Rich Ramalho — Sun, 04 May 2025 00:30:00 +0000

The English version of this post is here

Introdução

Você é um desenvolvedor TypeScript que adora programação funcional? Então, eu tenho algo para você: holo-fn – uma biblioteca funcional e leve projetada para lidar com valores opcionais, erros e resultados de uma forma simples, segura em tipos e imutável.

O nome holo-fn é inspirado pelo Holocron do universo Star Wars. Um Holocron é um dispositivo usado para armazenar grandes quantidades de conhecimento, passadas ao longo das gerações. Da mesma forma, o holo-fn serve como um repositório para poderosos construtos de programação funcional (como Maybe, Either e Result), projetados para tornar seu código TypeScript mais limpo, seguro e componível.

🎯 Por que usar o holo-fn?

holo-fn fornece poderosas monads como Maybe, Either e Result. Esses construtos funcionais ajudam você a escrever um código mais seguro, limpo e componível, lidando com casos como valores ausentes, erros e resultados de maneira mais previsível e gerenciável.

Ele foi desenvolvido para funcionar perfeitamente com a função pipe do Rambda para um estilo ainda mais funcional.

It is built to work seamlessly with the pipe function from Rambda for an even more functional style.

Principais Funcionalidades:

Tipos funcionais: Maybe, Either e Result para lidar com valores opcionais, erros e resultados.
Imutabilidade: Tudo é imutável por padrão, tornando seu código mais previsível e seguro.
Segurança de Tipo: Totalmente tipado com TypeScript, para que você possa confiar na análise estática do TypeScript.
Cobertura de Testes 100%: Rigorosamente testado com 100% de cobertura, garantindo estabilidade e confiabilidade.
Sem dependências: Zero dependências, mantendo seu projeto leve.
Compatibilidade com Rambda: Criado para funcionar perfeitamente com a função pipe do Rambda.

📦 Instalação

Você pode instalar facilmente o holo-fn via npm:

npm install holo-fn

🚀 Começando

Aqui está um exemplo rápido de como começar com o holo-fn.

https://richecr.github.io/holo-fn/getting_started/

Maybe

Maybe é usado para lidar com valores que podem ser nulos ou indefinidos. Ele previne erros de null/undefined ao envolver os valores em Just (para valores presentes) ou Nothing (para valores ausentes).

import { fromNullable } from 'holo-fn/maybe'

const name = fromNullable('Rich')
  .map(n => n.toUpperCase())
  .unwrapOr('Anonymous')

console.log(name) // RICH

Você pode ver os métodos que o Maybe suporta nesta página.

Either

Either representa uma computação que pode ter sucesso (Right) ou falhar (Left). Isso é especialmente útil para tratamento de erros, onde o lado esquerdo representa um erro e o lado direito representa um sucesso.

import { Right } from 'holo-fn/either'

const result = new Right(10)
  .map(n => n * 2)
  .unwrapOr(0)

console.log(result); // 20

Você pode ver os métodos que o Either suporta nesta página.

Result

Result é semelhante ao Either, mas especificamente projetado para operações que podem ter sucesso com um valor (Ok) ou falhar com um erro (Err).

import { Ok } from 'holo-fn/result'

const result = new Ok<number, string>(10)
  .map(n => n + 1)
  .unwrapOr(0)

console.log(result) // 11

Você pode ver os métodos que o Result suporta nesta página.

🛠️ Funções Curried

Para um estilo mais funcional, holo-fn também oferece versões curried da maioria dos métodos. Você pode facilmente compondo-os usando o pipe do Rambda.

Exemplos:

import { Err, mapErrR } from 'holo-fn/result';

const result = pipe(
  new Err("Error"),
  mapErrR((e) => `Mapped error: ${e}`),
  (res) => res.unwrapOr("No value")
);

console.log(result); // "No value"

import { Left, mapLeftE } from 'holo-fn/either';

const result = pipe(
  new Left("Error"),
  mapLeftE((e) => `Mapped error: ${e}`),
  (res) => res.unwrapOr("No value") 
);

console.log(result); // "No value"

Temos a documentação para essas funções para cada tipo que você deseja usar:

🧠 Por que escolher o holo-fn?

Imutabilidade: Todos os valores são imutáveis por padrão. Isso reduz erros e torna o código mais fácil de entender.
Composição: Use map, chain, e unwrapOr para fácil composição de pipelines funcionais.
Segurança de Tipo: holo-fn é totalmente tipado com TypeScript, garantindo que seu código seja seguro, sem surpresas.
Leve: Foi projetado para ser leve, com zero dependências.
Compatível com Rambda: Funciona muito bem com o pipe do Rambda, permitindo padrões de programação funcional.

📈 Considerações de Performance

Como o holo-fn foi projetado para ser componível e seguro em tipos, também garante que o desempenho não seja comprometido. Os métodos da biblioteca são otimizados para execução rápida e eficiente, com sobrecarga mínima.

🤝 Contribua

Quer contribuir? Estamos abertos a contribuições! Se você tem familiaridade com TypeScript e programação funcional, fique à vontade para enviar problemas ou pull requests para melhorar a biblioteca.

Você pode começar fazendo um fork do repositório e fazendo suas alterações. Depois disso, basta enviar um pull request!

Aqui temos uma página dedicada para novos contribuidores e fique a vontade para abrir uma issue de dúvida.

🔗 Links

Conclusão

holo-fn é uma biblioteca minimalista, mas poderosa, que torna a programação funcional em TypeScript mais acessível. Com suporte a monads como Maybe, Either e Result, você pode facilmente lidar com casos de borda de forma previsível e limpa. Comece a usá-la em seus projetos TypeScript e aproveite os benefícios da programação funcional!

Introducing holo-fn: A Minimal Functional Library for TypeScript

Rich Ramalho — Sun, 04 May 2025 00:29:25 +0000

Introdution

Are you a TypeScript developer who loves functional programming? Well, I’ve got something for you: holo-fn – a lightweight, functional library designed to handle optional values, errors, and results in a simple, type-safe, and immutable way.

The name holo-fn is inspired by Holocron from the Star Wars universe. A Holocron is a device used to store vast amounts of knowledge, passed down through the ages. Similarly, holo-fn serves as a repository for powerful, functional programming constructs (like Maybe, Either, and Result), designed to make your TypeScript code cleaner, safer, and more composable.

🎯 Why holo-fn?

holo-fn provides powerful monads like Maybe, Either, and Result. These functional constructs help you write safer, cleaner, and more composable code by handling edge cases like missing values, errors, and successful outcomes in a more predictable and manageable way.

It is built to work seamlessly with the pipe function from Rambda for an even more functional style.

Key Features:

Functional types: Maybe, Either, and Result to handle optional values, errors, and results.
Immutability: Everything is immutable by default, making your code more predictable and safer.
Type Safety: Fully typed with TypeScript, so you can rely on the power of TypeScript’s static analysis.
100% Test Coverage: Rigorously tested with 100% coverage, ensuring stability and reliability.
No dependencies: Zero dependencies, keeping your project lightweight.
Rambda compatibility: Built to seamlessly work with pipe from Rambda.

📦 Installation

You can easily install holo-fn via npm:

npm install holo-fn

🚀 Getting Started

Here’s a quick example of how to get started with holo-fn.

https://richecr.github.io/holo-fn/getting_started/

Maybe

Maybe is used to handle values that can be null or undefined. It prevents null/undefined errors by wrapping values in a Just (for present values) or Nothing (for absent values).

import { fromNullable } from 'holo-fn/maybe'

const name = fromNullable('Rich')
  .map(n => n.toUpperCase())
  .unwrapOr('Anonymous')

console.log(name) // RICH

You can see the methods that maybe supports on this page.

Either

Either represents a computation that can either succeed (Right) or fail (Left). This is especially useful for error handling, where the left side represents an error and the right side represents a success.

import { Right } from 'holo-fn/either'

const result = new Right(10)
  .map(n => n * 2)
  .unwrapOr(0)

console.log(result); // 20

You can see the methods that either supports on this page.

Result

Result is similar to Either, but specifically designed for operations that can either succeed with a value (Ok) or fail with an error (Err).

import { Ok } from 'holo-fn/result'

const result = new Ok<number, string>(10)
  .map(n => n + 1)
  .unwrapOr(0)

console.log(result) // 11

You can see the methods that result supports on this page.

🛠️ Curried Functions

For a more functional approach, holo-fn also provides curried versions of most methods. You can easily compose them using pipe from Rambda.

Examples:

import { Err, mapErrR } from 'holo-fn/result';

const result = pipe(
  new Err("Error"),
  mapErrR((e) => `Mapped error: ${e}`),
  (res) => res.unwrapOr("No value")
);

console.log(result); // "No value"

import { Left, mapLeftE } from 'holo-fn/either';

const result = pipe(
  new Left("Error"),
  mapLeftE((e) => `Mapped error: ${e}`),
  (res) => res.unwrapOr("No value") 
);

console.log(result); // "No value"

We have documentation for these functions for each type you want to use:

🧠 Why Choose holo-fn?

Immutability: All values are immutable by default. This reduces bugs and makes code easier to reason about.
Composability: Use map, chain, and unwrapOr for easy composition of functional pipelines.
Type Safety: holo-fn is fully typed with TypeScript, making sure your code is safe, with no surprises.
Lightweight: It’s designed to be lightweight, with zero dependencies.
Rambda-Friendly: Works beautifully with pipe from Rambda, enabling functional programming patterns.

📈 Performance Considerations

Since holo-fn is built for composability and type safety, it also ensures that performance isn’t compromised. The library’s methods are optimized for fast and efficient execution, with minimal overhead.

🤝 Contribute

Want to contribute? We’re open to contributions! If you’re familiar with TypeScript and functional programming, feel free to submit issues or pull requests to improve the library.

You can start by forking the repository and making your changes. Once done, simply submit a pull request!

Here we have a dedicated page for new contributors and feel free to open an issue with any questions.

🔗 Links

Conclusion

holo-fn is a minimal yet powerful library that makes functional programming in TypeScript more approachable. With support for monads like Maybe, Either, and Result, you can easily handle edge cases in a predictable and clean way. Start using it in your TypeScript projects and enjoy the benefits of functional programming!