map(callback: mapFunctionCallback<Value, NextValue>): Optional
An Optional can be in two states: either it has Some associated value or it is Empty.
// An optional can be created from a not null nor undefined value like so
const userNameOptional1 = Optional.of('Francis')
// or an alias for the same thing
const userNameOptional2 = Some('Francis')
// An empty optional can be created with empty but the type has to be added manually
const userNameOptional3 = Optional.empty<string>()
// or an alias for the same thing
const userNameOptional4 = Empty<string>()
// In case you do not know if the value you have is or not undefined or null, you can
// use ofNullable, that wraps that potentially undefined value into either an empty optional or
// a optional with an associated value
const undefinedUserName: string | undefined = undefined
const emptyOptional = Optional.ofNullable(undefinedUserName)
const filledUserName: string | undefined = 'Bernard'
const filledOptional = Optional.ofNullable(filledUserName)One can check the state of an Optional by calling isSome or isEmpty methods.
const filledOptional = Optional.some('a value')
filledOptional.isSome() // true
filledOptional.isEmpty() // false
const emptyOptional = Optional.empty<string>()
emptyOptional.isSome() // false
emptyOptional.isEmpty() // eptyOne can want to get the associated value from inside the Optional. There are three safe way of doing so to match as best possible any workflow, orElse, orElseGet, orElseThrow
const filledOptional = Optional.some('a value')
const emptyOptional = Optional.empty<string>()
// orElse will return the backupValue if the optional is empty,
// or the associated value if not
const backupValue = 'a backup value'
const value1 = filledOptional.orElse(backupValue) // 'a value'
const value2 = emptyOptional.orElse(backupValue) // 'a backup value'
// orElseGet will return a resolved promise with optinal value,
// or the promise returned by the callback if optional was empty
const backupCallback = () => database.getValue() // Promise<'database value'>
const value3 = filledOptional.orElseGet(backupCallback) // Promise<'a value'>
const value4 = emptyOptional.orElseGet(backupCallback) // Promise<'database value'>
// orElseThrow will return the optinal value,
// or throw the error passed as parameter
const error = new Error('the optional was empty')
const value5 = filledOptional.orElseThrow(error) // 'a value'
const value6 = emptyOptional.orElseThrow(error) // Error('the optional was empty')To avoid unwrapping results every line, one can use the .map function.
const filledOptional = Optional.some('a value')
filledOptional.map((value) => { // value > 'a value'
return 'another value'
}) // returns Optional.some('another value')
const emptyOptional = Optional.empty<string>()
emptyOptional.map((value) => { // value > 'a value'
return 'another value'
}) // returns Optional.empty()It is often useful to switch from Optional to Result objects and vice versa.
One can convert an Optional to a Result with the toResult function.
If the Optional is empty then the Result will be a Failure with the error passed as parameter.
If the Optional has an associated value then the Result will be a Success with the associated value.
const filledOptional = Optional.some('a value')
filledOptional.toResult(new Error('a failure')) // returns Result.Success('a value')
const emptyOptional = Optional.empty<string>()
emptyOptional.toResult(new Error('a failure')) // returns Result.Failure(new Error('a failure'))One can convert a Result to an Optional with the toOptional function.
If the Result is a Success then the Optional will be Some with the associated value.
If the Result is a Failure then the Optional will be Empty.
const successResult = Result.fromSuccess('a value')
successResult.toOptional() // returns Optional.some('a value')
const failureResult = Result.fromFailure(new Error('a failure'))
failureResult.toOptional() // returns Optional.empty()On the special cases where the result is a success with an undefined or null value, the optional will be empty.
const successResult = Result.fromSuccess(undefined)
successResult.toOptional() // returns Optional.empty()