Optional

Optional: object

Defined in: Core/Optional.ts:28

Utilities for reading, overwriting, and transforming values along nullable or indexed paths via composable optionals.

Type Declaration

andThen

andThen: <A, B>(inner) => <S>(outer) => Optional<S, B>

Composes two optionals sequentially, yielding None if either segment is absent.

Type Parameters

A

A

B

B

Parameters

inner

Optional<A, B>

Returns

<S>(outer) => Optional<S, B>

See

Optional.andThenLens to compose an Optional with a Lens.

Example

type Address = { landmark?: string };
type Account = { address?: Address };

const landmarkOptional = pipe(
  Optional.from.property<Account>()("address"),
  Optional.andThen(Optional.from.property<Address>()("landmark")),
);

andThenLens

andThenLens: <A, B>(inner) => <S>(outer) => Optional<S, B>

Composes an Optional with a Lens, producing an Optional. The Lens focuses within the value found by the Optional.

Type Parameters

A

A

B

B

Parameters

inner

Lens<A, B>

Returns

<S>(outer) => Optional<S, B>

See

• Optional.andThen to compose two Optional paths.
• Lens.andThenOptional to compose a Lens with an Optional path.

Example

type Address = { city: string };
type Account = { address?: Address };

const cityOptional = pipe(
  Optional.from.property<Account>()("address"),
  Optional.andThenLens(Lens.from.property<Address>()("city")),
);

from

from: object

Constructors for creating Optional instances from accessors, property keys, or array indices.

from.accessors

accessors: <S, A>(get, set) => Optional<S, A> = makeAccessors

Constructs an Optional from a getter (returning Maybe) and a setter function.

Type Parameters

S

S

A

A

Parameters

get

(structure) => Maybe<A>

set

(value) => (structure) => S

Returns

Optional<S, A>

See

• Optional.from.property to create an Optional focused on an object property.
• Optional.from.index to focus on an array element by index.

Example

const firstChar = Optional.from.accessors(
  (text: string) => text.length > 0 ? Maybe.make.some(text[0]) : Maybe.make.none(),
  (char) => (text) => text.length > 0 ? char + text.slice(1) : text,
);

from.index

index: <A>(index) => Optional<readonly A[], A> = makeIndex

Creates an Optional that focuses on an element at a given index in an array. Returns None when the index is out of bounds; set is a no-op when out of bounds.

Type Parameters

A

A

Parameters

index

number

Returns

Optional<readonly A[], A>

See

• Optional.from.property to focus on an object property.
• Optional.from.accessors to construct an Optional from custom getter and setter functions.

Example

const firstItem = Optional.from.index<string>(0);

pipe(["ready", "running"], Optional.get(firstItem)); // Some("ready")
pipe([], Optional.get(firstItem));                   // None

from.property

property: <S>() => <K>(key) => Optional<S, NonNullable<S[K]>> = makeProperty

Creates an Optional that focuses on an optional or nullable property of an object. Call with the structure type first, then the key.

Type Parameters

S

S

Returns

<K>(key) => Optional<S, NonNullable<S[K]>>

See

• Optional.from.accessors to construct an Optional from custom getter and setter functions.
• Optional.from.index to focus on an element of an array by index.

Example

type Profile = { username: string; bio?: string };
const bioOptional = Optional.from.property<Profile>()("bio");

get

get: <S, A>(opt) => (structure) => Maybe<A>

Reads the focused value from a structure, returning Maybe.

Type Parameters

S

S

A

A

Parameters

opt

Optional<S, A>

Returns

(structure) => Maybe<A>

See

• Optional.set to overwrite the focused value if present.
• Optional.modify to transform the focused value if present.
• Optional.getOrElse to extract the value with a fallback default.
• Optional.match to pattern match on present and absent states.

Example

type UserProfile = { bio?: string };
const bioOptional = Optional.from.property<UserProfile>()("bio");
const profile: UserProfile = { bio: "Platform engineer" };

pipe(profile, Optional.get(bioOptional)); // Some("Platform engineer")

getOrElse

getOrElse: <S, A>(opt) => <B>(fallback) => (structure) => A | B

Returns the focused value or a fallback default when the focus is absent.

Type Parameters

S

S

A

A

Parameters

opt

Optional<S, A>

Returns

<B>(fallback) => (structure) => A | B

See

• Optional.get to extract the value as a Maybe.
• Optional.match to pattern match on presence with custom handlers.

Example

type UserProfile = { bio?: string };
const bioOptional = Optional.from.property<UserProfile>()("bio");
const profile: UserProfile = {};

pipe(profile, Optional.getOrElse(bioOptional)(() => "No bio provided"));
// "No bio provided"

match

match: <S, A>(opt) => <B>(cases) => (structure) => B

Pattern matches on an Optional focus using a named-case object.

Type Parameters

S

S

A

A

Parameters

opt

Optional<S, A>

Returns

<B>(cases) => (structure) => B

See

• Optional.get to extract the value as a Maybe.
• Optional.getOrElse to extract the value with a default fallback.

Example

type UserProfile = { bio?: string };
const bioOptional = Optional.from.property<UserProfile>()("bio");
const profile: UserProfile = { bio: "Staff engineer" };

pipe(
  profile,
  Optional.match(bioOptional)({
    none: () => "Empty profile",
    some: (bio) => `Bio: ${bio}`,
  }),
); // "Bio: Staff engineer"

modify

modify: <S, A>(opt) => (transform) => (structure) => S

Applies a function to the focused value if it is present; returns the structure unchanged if the focus is absent.

Type Parameters

S

S

A

A

Parameters

opt

Optional<S, A>

Returns

(transform) => (structure) => S

See

• Optional.get to extract the focused value as a Maybe.
• Optional.set to overwrite the focused value directly.

Example

type UserProfile = { bio?: string };
const bioOptional = Optional.from.property<UserProfile>()("bio");
const profile: UserProfile = { bio: "platform engineer" };

pipe(profile, Optional.modify(bioOptional)((bio) => bio.toUpperCase()));
// { bio: "PLATFORM ENGINEER" }

set

set: <S, A>(opt) => (value) => (structure) => S

Replaces the focused value within a structure. For indexed focuses, this is a no-op when the index is out of bounds.

Type Parameters

S

S

A

A

Parameters

opt

Optional<S, A>

Returns

(value) => (structure) => S

See

• Optional.get to extract the focused value as a Maybe.
• Optional.modify to transform the focused value if present.

Example

type UserProfile = { bio?: string };
const bioOptional = Optional.from.property<UserProfile>()("bio");
const profile: UserProfile = { bio: "Platform engineer" };

pipe(profile, Optional.set(bioOptional)("Staff engineer"));
// { bio: "Staff engineer" }