# Option overview

The Option namespace contains utilities to improve the handling of optional values. The Option type is expressed as following:

type Option<A> = A | undefined

Note: In other libraries, the Option type is often either Some value, or None / Nothing.

# Summary

Summary
Types
- Option
Functions

# Types

# Option

type Option<A> = A | undefined

# Functions

# Option.isSome

# Description

Check if an optional value is not undefined

<A>(value: Option<A>) => value is A

# Option.isNone

# Description

Check if an optional value is undefined

<A>(value: Option<A>) => value is undefined

# Option.map

# Description

Map over an optional value, without worrying about the value being undefined

<A, B>(fn: (value: A) => Option<B>) => (value: Option<A>) => Option<B>

# Example

const a: Option<number> = undefined
const b = pipe(
  a,
  Option.map(nb => nb * 2)
)

expect(b).toBe(undefined)

# Option.filter

# Description

If the predicate is false, the value becomes undefined

<A, B extends A>(fn: Refinement<A, B>): (value: Option<A>) => Option<B>
<A>(fn: Predicate<A>): (value: Option<A>) => Option<A>

# Example

const result = pipe(
  NaN,
  Option.filter(nb => !isNaN(nb))
)

expect(result).toBe(undefined)

# References

Option.reject

# Option.reject

# Description

If the predicate is true, the value becomes undefined

<A, B extends A>(fn: Refinement<A, B>): (value: Option<A>) => Option<B>
<A>(fn: Predicate<A>): (value: Option<A>) => Option<A>

# Example

const result = pipe(
  NaN,
  Option.reject(nb => isNaN(nb))
)

expect(result).toBe(undefined)

#### References
- `Option.filter`

### Option.get

#### Description

For a given `Option<A>`, returns either:
- The value `A`
- The given default value if the optional value is `undefined`

```ts
(onNone: () => never): <A>(value: Option<A>) => never
(onNone: () => Array<never>): <A extends Array<any>>(value: Option<A>) => Some<A>
(defaultValue: Array<never>): <A extends Array<any>>(value: Option<A>) => Some<A>
<B>(onNone: () => B): <A>(value: Option<A>) => B | Some<A>
<B>(defaultValue: B): <A>(value: Option<A>) => B | Some<A>

# Example

const a: Option<number> = undefined
const b: number = pipe(
  nb,
  Option.get(0)
)

expect(b).toBe(0)

# References

Option.throwError

# Option.throwError

# Description

For a given Option<A>, either:

Return the value A
Throw the given error if the optional value is undefined

<A>(onNone: () => Error): (value: Option<A>) => A
<A>(err: Error): (value: Option<A>) => A

# Example

const a: Option<number> = undefined
const b: number = pipe(
  nb,
  Option.get(0)
)

expect(b).toBe(0)

# References

Option.get

# Option.fromNullable

# Description

Returns an optional value from a nullable value

<T>(value: T | null) => Option<T>

# Example

const a: number | null = null
const b: Option<number> = Option.fromNullable(a)

expect(b).toBe(undefined)

# Option.fromFalsy

# Description

Returns an optional value from a falsy value

Note: In Javascript, a falsy value may be undefined, null, 0, false and ""

<T>(value: T | Falsy) => Option<T>

# Example

const a: number = 0
const b: Option<number> = Option.fromFalsy(a)

expect(b).toBe(undefined)

# Option.fromString

# Description

Returns an optional value from an empty string

<T>(value: string | T) => Option<string | T>

# Example

const a: string = ""
const b: Option<string> = Option.fromString(a)

expect(b).toBe(undefined)

# Option.fromNumber

# Description

Returns an optional value from a number

(value: number) => Option<number>

# Example

const a: number = NaN
const b: Option<number> = Option.fromNumber(a)

expect(b).toBe(undefined)

# Option.fromDate

# Description

Returns an optional value from a Date object

(value: Date) => Option<Date>

# Example

const a: Date = new Date("invalid")
const b: Option<Date> = Option.fromDate(a)

expect(b).toBe(undefined)

← String Enum →