Option

The Option data type represents optional values. An Option<A> can either be Some<A>, containing a value of type A, or None, representing the absence of a value.

You can use Option in scenarios like:

• Using it for initial values
• Returning values from functions that are not defined for all possible inputs (referred to as “partial functions”)
• Managing optional fields in data structures
• Handling optional function arguments

Creating Options

some

Use the Option.some constructor to create an Option that holds a value of type A.

Example (Creating an Option with a Value)

import { Option } from "effect"

// An Option holding the number 1
const value = Option.some(1)

console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }

none

Use the Option.none constructor to create an Option representing the absence of a value.

Example (Creating an Option with No Value)

import { Option } from "effect"

// An Option holding no value
const noValue = Option.none()

console.log(noValue)
// Output: { _id: 'Option', _tag: 'None' }

liftPredicate

You can create an Option based on a predicate, for example, to check if a value is positive.

Example (Using Explicit Option Creation)

Here’s how you can achieve this using Option.none and Option.some:

import { Option } from "effect"

const isPositive = (n: number) => n > 0

const parsePositive = (n: number): Option.Option<number> =>
  isPositive(n) ? Option.some(n) : Option.none()

Example (Using Option.liftPredicate for Conciseness)

Alternatively, you can simplify the above logic with Option.liftPredicate:

import { Option } from "effect"

const isPositive = (n: number) => n > 0

//      ┌─── (b: number) => Option<number>
//      ▼
const parsePositive = Option.liftPredicate(isPositive)

Modeling Optional Properties

Consider a User model where the "email" property is optional and can hold a string value. We use the Option<string> type to represent this optional property:

import { Option } from "effect"

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
}

Property Key Always Present

Optionality only applies to the value of the property. The key "email" will always be present in the object, regardless of whether it has a value or not.

Here are examples of how to create User instances with and without an email:

Example (Creating Users with and without Email)

import { Option } from "effect"

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
}

const withEmail: User = {
  id: 1,
  username: "john_doe",
  email: Option.some("john.doe@example.com")
}

const withoutEmail: User = {
  id: 2,
  username: "jane_doe",
  email: Option.none()
}

Guards

You can check whether an Option is a Some or a None using the Option.isSome and Option.isNone guards.

Example (Using Guards to Check Option Values)

import { Option } from "effect"

const foo = Option.some(1)

console.log(Option.isSome(foo))
// Output: true

if (Option.isNone(foo)) {
  console.log("Option is empty")
} else {
  console.log(`Option has a value: ${foo.value}`)
}
// Output: "Option has a value: 1"

Pattern Matching

Use Option.match to handle both cases of an Option by specifying separate callbacks for None and Some.

Example (Pattern Matching with Option)

import { Option } from "effect"

const foo = Option.some(1)

const message = Option.match(foo, {
  onNone: () => "Option is empty",
  onSome: (value) => `Option has a value: ${value}`
})

console.log(message)
// Output: "Option has a value: 1"

Working with Option

map

The Option.map function lets you transform the value inside an Option without manually unwrapping and re-wrapping it. If the Option holds a value (Some), the transformation function is applied. If the Option is None, the function is ignored, and the Option remains unchanged.

Example (Mapping a Value in Some)

import { Option } from "effect"

// Transform the value inside Some
console.log(Option.map(Option.some(1), (n) => n + 1))
// Output: { _id: 'Option', _tag: 'Some', value: 2 }

When dealing with None, the mapping function is not executed, and the Option remains None:

Example (Mapping over None)

import { Option } from "effect"

// Mapping over None results in None
console.log(Option.map(Option.none(), (n) => n + 1))
// Output: { _id: 'Option', _tag: 'None' }

flatMap

The Option.flatMap function is similar to Option.map, but it is designed to handle cases where the transformation might return another Option. This allows us to chain computations that depend on whether or not a value is present in an Option.

Consider a User model that includes a nested optional Address, which itself contains an optional street property:

import { Option } from "effect"

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
  readonly address: Option.Option<Address>
}

interface Address {
  readonly city: string
  readonly street: Option.Option<string>
}

In this model, the address field is an Option<Address>, and the street field within Address is an Option<string>.

We can use Option.flatMap to extract the street property from address:

Example (Extracting a Nested Optional Property)

import { Option } from "effect"

interface Address {
  readonly city: string
  readonly street: Option.Option<string>
}

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
  readonly address: Option.Option<Address>
}

const user: User = {
  id: 1,
  username: "john_doe",
  email: Option.some("john.doe@example.com"),
  address: Option.some({
    city: "New York",
    street: Option.some("123 Main St")
  })
}

// Use flatMap to extract the street value
const street = user.address.pipe(
  Option.flatMap((address) => address.street)
)

console.log(street)
// Output: { _id: 'Option', _tag: 'Some', value: '123 Main St' }

If user.address is Some, Option.flatMap applies the function (address) => address.street to retrieve the street value.

If user.address is None, the function is not executed, and street remains None.

This approach lets us handle nested optional values concisely, avoiding manual checks and making the code cleaner and easier to read.

filter

The Option.filter function allows you to filter an Option based on a given predicate. If the predicate is not met or if the Option is None, the result will be None.

Example (Filtering an Option Value)

Here’s how you can simplify some code using Option.filter for a more idiomatic approach:

Original Code

import { Option } from "effect"

// Function to remove empty strings from an Option
const removeEmptyString = (input: Option.Option<string>) => {
  if (Option.isSome(input) && input.value === "") {
    return Option.none() // Return None if the value is an empty string
  }
  return input // Otherwise, return the original Option
}

console.log(removeEmptyString(Option.none()))
// Output: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("")))
// Output: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("a")))
// Output: { _id: 'Option', _tag: 'Some', value: 'a' }

Refactored Idiomatic Code

Using Option.filter, we can write the same logic more concisely:

import { Option } from "effect"

const removeEmptyString = (input: Option.Option<string>) =>
  Option.filter(input, (value) => value !== "")

console.log(removeEmptyString(Option.none()))
// Output: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("")))
// Output: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("a")))
// Output: { _id: 'Option', _tag: 'Some', value: 'a' }

Getting the Value from an Option

To retrieve the value stored inside an Option, you can use several helper functions provided by the Option module. Here’s an overview of the available methods:

getOrThrow

This function extracts the value from a Some. If the Option is None, it throws an error.

Example (Retrieving Value or Throwing an Error)

import { Option } from "effect"

console.log(Option.getOrThrow(Option.some(10)))
// Output: 10

console.log(Option.getOrThrow(Option.none()))
// throws: Error: getOrThrow called on a None

getOrNull / getOrUndefined

These functions convert a None to either null or undefined, which is useful when working with non-Option-based code.

Example (Converting None to null or undefined)

import { Option } from "effect"

console.log(Option.getOrNull(Option.some(5)))
// Output: 5

console.log(Option.getOrNull(Option.none()))
// Output: null

console.log(Option.getOrUndefined(Option.some(5)))
// Output: 5

console.log(Option.getOrUndefined(Option.none()))
// Output: undefined

getOrElse

This function allows you to specify a default value to return when the Option is None.

Example (Providing a Default Value When None)

import { Option } from "effect"

console.log(Option.getOrElse(Option.some(5), () => 0))
// Output: 5

console.log(Option.getOrElse(Option.none(), () => 0))
// Output: 0

Fallback

orElse

When a computation returns None, you might want to try an alternative computation that yields an Option. The Option.orElse function is helpful in such cases. It lets you chain multiple computations, moving on to the next if the current one results in None. This approach is often used in retry logic, attempting computations until one succeeds or all possibilities are exhausted.

Example (Attempting Alternative Computations)

import { Option } from "effect"

// Simulating a computation that may or may not produce a result
const computation = (): Option.Option<number> =>
  Math.random() < 0.5 ? Option.some(10) : Option.none()

// Simulates an alternative computation
const alternativeComputation = (): Option.Option<number> =>
  Math.random() < 0.5 ? Option.some(20) : Option.none()

// Attempt the first computation, then try an alternative if needed
const program = computation().pipe(
  Option.orElse(() => alternativeComputation())
)

const result = Option.match(program, {
  onNone: () => "Both computations resulted in None",
  // At least one computation succeeded
  onSome: (value) => `Computed value: ${value}`
})

console.log(result)
// Output: Computed value: 10

firstSomeOf

You can also use Option.firstSomeOf to get the first Some value from an iterable of Option values:

Example (Retrieving the First Some Value)

import { Option } from "effect"

const first = Option.firstSomeOf([
  Option.none(),
  Option.some(2),
  Option.none(),
  Option.some(3)
])

console.log(first)
// Output: { _id: 'Option', _tag: 'Some', value: 2 }

Interop with Nullable Types

When dealing with the Option data type, you may encounter code that uses undefined or null to represent optional values. The Option module provides several APIs to make interaction with these nullable types straightforward.

fromNullable

Option.fromNullable converts a nullable value (null or undefined) into an Option. If the value is null or undefined, it returns Option.none(). Otherwise, it wraps the value in Option.some().

Example (Creating Option from Nullable Values)

import { Option } from "effect"

console.log(Option.fromNullable(null))
// Output: { _id: 'Option', _tag: 'None' }

console.log(Option.fromNullable(undefined))
// Output: { _id: 'Option', _tag: 'None' }

console.log(Option.fromNullable(1))
// Output: { _id: 'Option', _tag: 'Some', value: 1 }

If you need to convert an Option back to a nullable value, there are two helper methods:

• Option.getOrNull: Converts None to null.
• Option.getOrUndefined: Converts None to undefined.

Interop with Effect

The Option type works as a subtype of the Effect type, allowing you to use it with functions from the Effect module. While these functions are built to handle Effect values, they can also manage Option values correctly.

How Option Maps to Effect

Option Variant	Mapped to Effect	Description
None	Effect<never, NoSuchElementException>	Represents the absence of a value
Some<A>	Effect<A>	Represents the presence of a value

Example (Combining Option with Effect)

import { Effect, Option } from "effect"

// Function to get the head of an array, returning Option
const head = <A>(array: ReadonlyArray<A>): Option.Option<A> =>
  array.length > 0 ? Option.some(array[0]) : Option.none()

// Simulated fetch function that returns Effect
const fetchData = (): Effect.Effect<string, string> => {
  const success = Math.random() > 0.5
  return success
    ? Effect.succeed("some data")
    : Effect.fail("Failed to fetch data")
}

// Mixing Either and Effect
const program = Effect.