Funcio 🚀

Funcio is a powerful and versatile library designed to bring the elegance of functional programming to the TypeScript ecosystem. With Funcio, seamlessly integrate functional programming principles and techniques into your codebase, unlocking a universe of possibilities. It empowers you to create clean and expressive code using functional programming paradigms. 🧙‍♂️

Note: This library is currently under construction and not yet ready for production use.

Table of Contents

• Funcio 🚀
  • Table of Contents
  • Installation 📦
  • Getting Started 🏁
  • Usage 🚀
    • _Either
      • _Either.right(value)
      • _Either.left(value)
      • _Either.isRight(either)
      • _Either.isLeft(either)
      • _Either._try.sync(fn)
      • _Either._try.async(fn)
      • _Either.unwrap()
    • _Object
      • _Object.makeImmutable
      • _Object.chainify
      • _Object.setByPath(keysToFollow, value, obj)
      • _Object.getPathValue(keysToFollow, obj)
    • _Maybe
      • _Maybe.get()
      • _Maybe.getOrElse(defaultValue)
      • _Maybe.map(function)
    • _Maybe.unwrap()
    • _pipe
    • _curry
    • _match
  • Contributions 🤝
  • License 📜

Installation 📦

To integrate Funcio into your project, let the npm package manager work its magic. Simply run the following command in your terminal:

npm install funcio

If you prefer yarn, it's got you covered too:

yarn add funcio

Getting Started 🏁

Embark on your Funcio journey by importing it into your TypeScript code:

import Funcio from 'funcio';

Usage 🚀

_Either

_Either is a module in the Funcio library that enables you to handle two distinct scenarios: the "Right" case and the "Left" case. It excels in situations where you need to decide between two possible outcomes. The "Right" case typically represents success, while the "Left" case conveys errors or alternative values.

_Either.right(value)

The _Either.right(value) method creates an Either instance, cradling a specific value in the "Right" case.

import { Funcio } from 'funcio';

const rightResult = Funcio._Either.right(42);

_Either.left(value)

The _Either.left(value) method crafts an Either instance with the "Left" case containing a specific value.

import { Funcio } from 'funcio';

const leftResult = Funcio._Either.left("Error: Something went wrong");

_Either.isRight(either)

The _Either.isRight(either) method assesses if the provided Either instance resides in the "Right" case and returns true for a match or false if it's in the "Left" case.

import { Funcio } from 'funcio';

const result = Funcio._Either.right(42);
const isRight = result.isRight();

// Result: true

_Either.isLeft(either)

The _Either.isLeft(either) method verifies if the provided Either instance dwells in the "Left" case and returns true for an affirmative or false if it inhabits the "Right" case.

import { Funcio } from 'funcio';

const result = Funcio._Either.left("Error: Something went wrong");
const isLeft = result.isLeft();  // Result: true

_Either._try.sync(fn)

The _Either._try.sync(fn) function is a powerful tool for encapsulating synchronous functions that can throw exceptions in a safe context. It allows you to execute a function fn and return the result in the "Right" case if the function is successful, or the exception in the "Left" case if the function fails.

import { Funcio } from 'funcio';

function divide(a: number, b: number) {
  if (b === 0) {
    throw new Error("Division by zero");
  }
  return a / b;
}

const result1 = Funcio._Either._try.sync(() => divide(6, 2)); // Result: Right(3)
const result2 = Funcio._Either._try.sync(() => divide(6, 0)); // Result: Left(Error: Division by zero)

_Either._try.async(fn)

The _Either._try.async(fn) function is a powerful tool for encapsulating asynchronous functions that can throw exceptions in a safe context. It allows you to execute an asynchronous function fn and return the result in the "Right" case if the function is successful or the exception in the "Left" case if the function fails.

import { Funcio } from 'funcio';

const jsonString = '{"name": "John", "age": 30}';
const validJson = await Funcio._Either._try.async<object>(() => JSON.parse(jsonString));

const invalidJsonString = '{"name": "John", "age": 30,}';
const invalidJson = await Funcio._Either._try.async<object>(() => JSON.parse(invalidJsonString));

_Either.unwrap()

The _Either.unwrap() method, when called on an Either instance, extracts the value contained within the Either structure. This method proves to be instrumental in scenarios where you need to handle both success and failure cases, as it allows you to access the wrapped value regardless of the outcome.

import { Funcio } from 'funcio';

const eitherValue = Funcio._Either.right(42);
const unwrappedValue = eitherValue.unwrap();

// Result: 42

_Object

_Object is a module in the Funcio library that offers a treasure trove of utilities for manipulating objects.

_Object.makeImmutable

The _Object.makeImmutable function is a versatile tool provided by the _Object module in our library. It enables you to create an immutable incarnation of an object, ensuring that its properties remain impervious to change once set.

import { Funcio } from 'funcio';

const user =  {
  "name": "Alice",
  "age": 25,
  "address": { "city": "Wonderland" },
  "hobbies": ["reading", "painting"]
}

const immutableUser = Funcio._Object.makeImmutable(user);
immutableUser.address.city = "Avalora"; // ❌ Error: TypeError: Cannot assign to read-only property 'city' of object '#<Object>'.

_Object.chainify

_Object.chainify is a versatile utility in the Funcio library that allows you to create a fluent interface for method chaining, providing a seamless and expressive way to apply multiple operations on an object.

import { Funcio } from 'funcio';

class ExampleClass {
  private value: number;

  constructor(value: number) {
    this.value = value;
  }

  setValue(newValue: number): this {
    this.value = newValue;
    return this;
  }

  multiplyBy(factor: number): this {
    this.value *= factor;
    return this;
  }

  getValue(): number {
    return this.value;
  }
}

// Using _chainify with ExampleClass
const result = Funcio._Object.chainify(new ExampleClass(5))
  .setValue(10)
  .multiplyBy(3)
  .getValue();

// Result: 30

_Object.setByPath(keysToFollow, value, obj)

The _Object.setByPath(keysToFollow, value, obj) method allows you to set a value at a specific path within an object. It takes an array keysToFollow representing the path to the desired value and the object obj where the value will be set. For example:

import { Funcio } from 'funcio';

const person = {
  name: "John Doe",
  age: 30,
  address: {
    street: "123 Main St",
    city: "New York",
    state: "NY",
    country: "USA",
  },
}

const streetValue = Funcio._Object.setByPath(['address', 'street'], '124 Main St', person);

// Result: "124 Main St" for streetValue

_Object.getPathValue(keysToFollow, obj)

The _Object.getPathValue(keysToFollow, obj) function retrieves the value

at the specified path within an object. It takes an array of keys (keysToFollow) representing the path to follow and the target object (obj). The function returns the value found at the specified path or undefined if the path is not valid.

import { Funcio } from 'funcio';

const person = {
  name: "John Doe",
  age: 30,
  address: {
    street: "123 Main St",
    city: "New York",
    state: "NY",
    country: "USA",
  },
}

const streetValue = Funcio._Object.getPathValue(['address', 'street'], person);
const nonExistingValue = Funcio._Object.getPathValue(['address', 'null'], person);

// Result: "123 Main St" for streetValue
// Result: undefined for nonExistingValue

_Maybe

_Maybe is a module in the Funcio library that empowers you to handle optional values with finesse, in line with functional programming principles. The concept of "Maybe" is your guardian angel for situations where a value may or may not be present, safeguarding against null reference errors and enabling the creation of safer code.

_Maybe.get()

The _Maybe.get() method is a foundational function bequeathed by the _Maybe module within the Funcio library. It allows you to securely fetch the value ensconced within a Maybe object.

When you invoke _Maybe.get() on a Maybe instance, it will yield the value if it's present, or it will raise an error or yield a default value if the Maybe is empty.

_Maybe.getOrElse(defaultValue)

The _Maybe.getOrElse(defaultValue) method is another invaluable tool within the _Maybe module in Funcio. It permits you to procure the value from a Maybe object while specifying a default value to deploy in case the Maybe is empty.

import { Funcio } from 'funcio';

const maybeValue = Funcio._Maybe.of(42) // Create a Maybe with a present value
const maybeEmpty = Funcio._Maybe.of(null); // Create an empty Maybe

const retrievedValue = maybeValue.get(); // Retrieve the present value
const defaultValue = maybeEmpty.getOrElse(0); // Retrieve a default value if the Maybe is empty

// Result: 42
// Result: 0

_Maybe.map(function)

The _Maybe.map(function) method is a potent tool presented by the _Maybe module within the Funcio library. It allows you to apply a function to the value contained within a Maybe object, but only if the Maybe isn't empty. This method is your trusty companion for transforming the value within a Maybe while preserving safety and gracefully handling optional values.

import { Funcio } from 'funcio';

// Create a Maybe with a value
const maybeValue = Funcio._Maybe.of(5);

// Define a function to double the value
const doubleValue = (x) => x * 2;

// Utilize map to wield the function on the Maybe's value
const doubledMaybe = maybeValue.map(doubleValue);

// Create a Maybe with no value (empty)
const maybeEmpty = Funcio._Maybe.of(null);

// Endeavor to employ the same function on the empty Maybe
const doubledEmptyMaybe = maybeEmpty.map(doubleValue);

// Retrieve the outcomes
const result1 = doubledMaybe.getOrElse("Value is empty");
const result2 = doubledEmptyMaybe.getOrElse("Value is empty");

result1 // Output: 10
result2 // Output: "Value is empty"

_Maybe.unwrap()

The _Maybe.unwrap() method, when called on a Maybe instance, retrieves the encapsulated value if it exists. If the Maybe is empty, an error or a default value can be specified to handle this scenario, ensuring robust error handling and smooth execution flow.

 import { Funcio } from 'funcio';

const maybeValue = Funcio._Maybe.of(42);
const unwrappedValue = maybeValue.unwrap();

// Result: 42

_pipe

The _pipe function in the Funcio library is a formidable utility for composing multiple functions into a single, higher-order function. It empowers you to craft a pipeline of functions where the output of one function becomes the input for the next.

import { Funcio } from 'funcio';

const addTwo = (x: number) => x + 2;
const square = (x: number) => x * x;
const subtractTen = (x: number) => x - 10;

const transform = Funcio._pipe(
  2,
  addTwo,
  square,
  subtractTen
);

// Result: 16

_curry

The _Curry function in the Funcio library is a powerful tool for enabling currying, a fundamental concept in functional programming. Currying allows you to transform a function that takes multiple arguments into a series of functions, each accepting a single argument. This technique enhances code readability, reusability, and composability.

The _curry(fn) method transforms a regular function into a curried function. Once curried, you can partially apply arguments one at a time, creating new functions along the way.

import { Funcio } from 'funcio';

// Regular function
const add = (a: number, b: number, c: number) => a + b + c;

// Curry the function
const curriedAdd = Funcio._curry(add);

// Partially apply arguments
const addFive = curriedAdd(5);
const addTen = addFive(10);

// Usage
const result = addTen(7); // Result: 22

_match

The _match function in the Funcio library is a powerful pattern-matching tool for executing different code blocks based on the matched values. It allows you to define patterns and corresponding actions, providing a concise and expressive way to handle multiple cases.

import { Funcio } from 'funcio';

const response = Funcio._match<number, number>(2)
  .with(1, (v) => v * 2)
  .with(2, (v) => v * v)
  ._(() => -1)
  .exec();

result // 4

Contributions 🤝

We extend a warm welcome to contributions from the open-source community. If you have ideas or a desire to contribute to Funcio, please explore our GitHub repository and submit a pull request.

License 📜

Funcio is released under the MIT License.

Embark on a thrilling journey into the realm of functional programming with Funcio! 🌟