perhaps-ts

Maybe Type Library

This library provides a light Maybe type for handling optional values, inspired by functional programming languages. A Maybe can either be Just (containing a value) or Nothing (no value).

Installation

Install via npm:

npm install perhaps-ts

Usage

Creating Maybe Instances

You can create Maybe instances using the Just and Nothing static methods or helper functions.

import { Maybe, Just, Nothing } from "perhaps-ts";

// Using static methods
const maybeValue = Maybe.Just(5);
const noValue = Maybe.Nothing<number>();

// Using helper functions
const anotherMaybeValue = Just(10);
const anotherNoValue = Nothing<string>();

Checking for Values

You can check if a Maybe instance has a value (Just) or not (Nothing).

if (maybeValue.IsJust()) console.log("This is Just:", maybeValue.FromJust());
if (noValue.IsNothing()) console.log("This is Nothing");

Retrieving Values

To retrieve the value of a Just instance, use the FromJust or ToChecked methods. Be cautious as these methods will throw an error if called on a Nothing instance.

try {
  const value = maybeValue.FromJust();
  console.log("Value:", value);
} catch (error) {
  console.error(error.message);
}

try {
  const value = noValue.ToChecked();
} catch (error) {
  console.error(error.message); // Maybe: Attempted to access value of Nothing
}

Default Values

You can provide a default value when dealing with Maybe instances, ensuring you always have a fallback.

const valueOrDefault = noValue.FromMaybe(42);
console.log("Value or Default:", valueOrDefault); // Outputs: 42

Conditional Value Extraction

You can conditionally extract the value into an output object if the instance is Just.

const output = {};
if (maybeValue.To(output)) {
  console.log("Extracted Value:", output.value); // Extracted Value: 5
} else {
  console.log("No value to extract");
}

Or you can use the To method with a custom key.

type Output = { data?: number };
type UserData = { id: number; name: string };

const output: Output = {};
if (maybeValue.To(output, "data")) {
  console.log("Extracted Data:", output.data); // Extracted Data: 5
} else {
  console.log("No data to extract");
}

const user: Maybe<UserData> = Just({ id: 1, name: "Alice" });
const userOutput: Output = {};
if (user.To(userOutput, "data")) {
  console.log("Extracted User:", userOutput.data); // Extracted User: { id: 1, name: 'Alice' }
} else {
  console.log("No user to extract");
}

Equality Comparisons

You can compare Maybe instances for equality.

const maybe1 = Just(5);
const maybe2 = Just(5);
const maybe3 = Nothing<number>();

console.log(maybe1.equals(maybe2)); // true
console.log(maybe1.equals(maybe3)); // false
console.log(maybe1.notEquals(maybe3)); // true

Sure! Here are some examples of how to write functions that return Maybe<T> instead of T | false, along with how to handle and check the returned Maybe<T> values.

Example Function Returning Maybe<T>

Let's write a function that searches for an item in an array and returns a Maybe<T> instead of the item or false.

import { Maybe, Just, Nothing } from "maybe-type";

function findItem<T>(array: T[], predicate: (item: T) => boolean): Maybe<T> {
  for (const item of array) {
    if (predicate(item)) {
      return Just(item);
    }
  }
  return Nothing<T>();
}

// Usage example
const numbers = [1, 2, 3, 4, 5];

const result = findItem(numbers, (n) => n === 3);
if (result.IsJust()) {
  console.log("Found:", result.FromJust()); // Found: 3
} else {
  console.log("Item not found");
}

Handling and Checking Maybe<T> Values

Here are several ways to handle and check Maybe<T> values returned from functions.

Using IsJust and IsNothing

const maybeNumber = findItem(numbers, (n) => n === 6);

if (maybeNumber.IsJust()) {
  console.log("Found:", maybeNumber.FromJust());
} else {
  console.log("Item not found");
}

Using FromMaybe with a Default Value

const valueOrDefault = maybeNumber.FromMaybe(0);
console.log("Value or Default:", valueOrDefault); // Value or Default: 0

Using To for Conditional Extraction

const output = {};
if (maybeNumber.To(output)) {
  console.log("Extracted Value:", output.value);
} else {
  console.log("No value to extract");
}

Another Function Example

Let's create another function that parses an integer from a string and returns Maybe<number>.

function parseIntMaybe(input: string): Maybe<number> {
  const parsed = parseInt(input, 10);
  if (isNaN(parsed)) {
    return Nothing<number>();
  }
  return Just(parsed);
}

// Usage example
const maybeParsed = parseIntMaybe("123");
if (maybeParsed.IsJust()) {
  console.log("Parsed integer:", maybeParsed.FromJust()); // Parsed integer: 123
} else {
  console.log("Failed to parse integer");
}

const maybeFailedParsed = parseIntMaybe("abc");
console.log("Parsed or Default:", maybeFailedParsed.FromMaybe(0)); // Parsed or Default: 0

Returning Maybe<T> from Asynchronous Functions

Here’s an example of how to use Maybe<T> in an asynchronous function:

async function fetchData(url: string): Promise<Maybe<string>> {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      return Nothing<string>();
    }
    const data = await response.text();
    return Just(data);
  } catch (error) {
    return Nothing<string>();
  }
}

// Usage example
fetchData("https://api.example.com/data").then((maybeData) => {
  if (maybeData.IsJust()) {
    console.log("Fetched Data:", maybeData.FromJust());
  } else {
    console.log("Failed to fetch data");
  }
});

These examples demonstrate how to use the Maybe type to handle cases where values might be absent, making your code more expressive and robust.

API Reference

Maybe Class

Static Methods

• Maybe.Just(value: T): Maybe<T>
  • Creates a Just instance containing the provided value.
• Maybe.Nothing<T>(): Maybe<T>
  • Creates a Nothing instance with no value.

Instance Methods

• IsJust(): boolean
  • Returns true if the instance is Just, otherwise false.
• IsNothing(): boolean
  • Returns true if the instance is Nothing, otherwise false.
• FromJust(): T
  • Returns the value if the instance is Just, otherwise throws an error.
• ToChecked(): T
  • Alias for FromJust.
• FromMaybe(defaultValue: T): T
  • Returns the value if the instance is Just, otherwise returns the provided default value.
• To(out: { [key: string]: T }, key?: string): boolean
  • If the instance is Just, sets the value in the provided output object and returns true, otherwise returns false. Optionally, you can specify a custom key, otherwise the default key is "value".
• equals(other: Maybe<T>): boolean
  • Returns true if the other Maybe instance is equal, otherwise false.
• notEquals(other: Maybe<T>): boolean
  • Returns true if the other Maybe instance is not equal, otherwise false.

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

This library simplifies handling optional values in TypeScript, providing a clear and expressive way to manage cases where a value may or may not be present.