API / Core / Nullable

Nullable

Functions for handling nullable values.

Primarily useful when interoping with JavaScript when you don't know whether you'll get a value, null or undefined.

t

RESCRIPT
type t<'a> = Js.Nullable.t<'a> = | Value('a) | Null | Undefined

Type representing a nullable value. A nullable value can be the value 'a, null or undefined.

null

RESCRIPT
let null: t<'a>

The value null.

See null on MDN.

Examples

RESCRIPT
Console.log(Nullable.null) // Logs `null` to the console.

undefined

RESCRIPT
let undefined: t<'a>

The value undefined.

See undefined on MDN.

Examples

RESCRIPT
Console.log(undefined) // Logs `undefined` to the console.

make

RESCRIPT
let make: 'a => t<'a>

Creates a new nullable value from the provided value. This means the compiler will enforce null checks for the new value.

Examples

RESCRIPT
let myStr = "Hello" let asNullable = myStr->Nullable.make // Can't do the below because we're now forced to check for nullability // myStr == asNullable // Need to do this switch asNullable->Nullable.toOption { | Some(value) if value == myStr => Console.log("Yay, values matched!") | _ => Console.log("Values did not match.") }

equal

RESCRIPT
let equal: (t<'a>, t<'b>, ('a, 'b) => bool) => bool

compare

RESCRIPT
let compare: ( t<'a>, t<'b>, ('a, 'b) => Core__Ordering.t, ) => Core__Ordering.t

toOption

RESCRIPT
let toOption: t<'a> => option<'a>

Converts a nullable value into an option, so it can be pattern matched on. Will convert both null and undefined to None, and a present value to Some(value).

Examples

RESCRIPT
let nullableString = Nullable.make("Hello") switch nullableString->Nullable.toOption { | Some(str) => Console.log2("Got string:", str) | None => Console.log("Didn't have a value.") }

fromOption

RESCRIPT
let fromOption: option<'a> => t<'a>

Turns an option into a Nullable.t.

Examples

RESCRIPT
let optString = Some("Hello") let asNullable = optString->Nullable.fromOption // Nullable.t<string>

getOr

RESCRIPT
let getOr: (t<'a>, 'a) => 'a

getOr(value, default) returns value if not null or undefined, otherwise return default.

Examples

RESCRIPT
Nullable.getOr(Nullable.null, "Banana") // Banana Nullable.getOr(Nullable.make("Apple"), "Banana") // Apple let greet = (firstName: option<string>) => "Greetings " ++ firstName->Option.getOr("Anonymous") Nullable.make("Jane")->Nullable.toOption->greet // "Greetings Jane" Nullable.null->Nullable.toOption->greet // "Greetings Anonymous"

getWithDefault

Deprecated

Use getOr instead

RESCRIPT
let getWithDefault: (t<'a>, 'a) => 'a

getExn

RESCRIPT
let getExn: t<'a> => 'a

getExn(value) raises an exception if null or undefined, otherwise returns the value.

RESCRIPT
Nullable.getExn(Nullable.make(3)) // 3 Nullable.getExn(Nullable.null) /* Raises an Error */

Exceptions

  • Raises Invalid_argument if value is null or undefined

getUnsafe

RESCRIPT
let getUnsafe: t<'a> => 'a

getUnsafe(value) returns value.

Examples

RESCRIPT
Nullable.getUnsafe(Nullable.make(3)) == 3 Nullable.getUnsafe(Nullable.null) // Raises an error

Important

  • This is an unsafe operation, it assumes value is not null or undefined.

forEach

RESCRIPT
let forEach: (t<'a>, 'a => unit) => unit

forEach(value, f) call f on value. if value is not null or undefined, then if calls f, otherwise returns unit.

Examples

RESCRIPT
Nullable.forEach(Nullable.make("thing"), x => Console.log(x)) // logs "thing" Nullable.forEach(Nullable.null, x => Console.log(x)) // returns () Nullable.forEach(undefined, x => Console.log(x)) // returns ()

map

RESCRIPT
let map: (t<'a>, 'a => 'b) => t<'b>

map(value, f) returns f(value) if value is not null or undefined, otherwise returns value unchanged.

Examples

RESCRIPT
Nullable.map(Nullable.make(3), x => x * x) // Nullable.make(9) Nullable.map(undefined, x => x * x) // undefined

mapOr

RESCRIPT
let mapOr: (t<'a>, 'b, 'a => 'b) => 'b

mapOr(value, default, f) returns f(value) if value is not null or undefined, otherwise returns default.

Examples

RESCRIPT
let someValue = Nullable.make(3) someValue->Nullable.mapOr(0, x => x + 5) // 8 let noneValue = Nullable.null noneValue->Nullable.mapOr(0, x => x + 5) // 0

mapWithDefault

Deprecated

Use mapOr instead

RESCRIPT
let mapWithDefault: (t<'a>, 'b, 'a => 'b) => 'b

flatMap

RESCRIPT
let flatMap: (t<'a>, 'a => t<'b>) => t<'b>

flatMap(value, f) returns f(value) if value is not null or undefined, otherwise returns value unchanged.

Examples

RESCRIPT
let addIfAboveOne = value => if (value > 1) { Nullable.make(value + 1) } else { Nullable.null } Nullable.flatMap(Nullable.make(2), addIfAboveOne) // Nullable.make(3) Nullable.flatMap(Nullable.make(-4), addIfAboveOne) // undefined Nullable.flatMap(Nullable.null, addIfAboveOne) // undefined