docs for Null, Nullable and Undefined (#45)

Author: zth

src/Core__Null.resi

@@ -0,0 +1,73 @@
+/***
+Functions for handling values that could be `null`.
+
+If you also need to cover `undefined`, check out `Nullable` instead.
+*/
+
+/**
+A type representing a value that can be either `'a` or `null`.
+*/
+type t<'a> = Js.Null.t<'a>
+
+/**
+Converts a `Null.t` into a `Nullable.t`.
+
+## Examples
+```rescript
+let nullValue = Null.make("Hello")
+let asNullable = nullValue->Null.asNullable // Nullable.t<string>
+```
+*/
+external asNullable: t<'a> => Core__Nullable.t<'a> = "%identity"
+
+/**
+The value `null`.
+
+See [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null) on MDN.
+
+## Examples
+```rescript
+Console.log(Null.null) // Logs `null` to the console.
+```
+*/
+external null: t<'a> = "#null"
+
+/**
+Creates a new `Null.t` from the provided value. 
+This means the compiler will enforce null checks for the new value.
+
+## Examples
+```rescript
+let myStr = "Hello"
+let asNullValue = myStr->Null.make // The compiler now thinks this can be `string` or `null`.
+```
+*/
+external make: 'a => t<'a> = "%identity"
+
+/**
+Converts a nullable value into an option, so it can be pattern matched on.
+Will convert `null` to `None`, and a present value to `Some(value)`.
+
+## Examples
+```rescript
+let nullStr = Null.make("Hello")
+
+switch nullStr->Null.toOption {
+| Some(str) => Console.log2("Got string:", str)
+| None => Console.log("Didn't have a value.")
+}
+```
+*/
+external toOption: t<'a> => option<'a> = "#null_to_opt"
+
+/**
+Turns an `option` into a `Null.t`. `None` will be converted to `null`.
+
+## Examples
+```rescript
+let optString: option<string> = None
+let asNull = optString->Null.fromOption // Null.t<string>
+Console.log(asNull == Null.null) // Logs `true` to the console.
+```
+*/
+let fromOption: option<'a> => t<'a>

src/Core__Nullable.resi

@@ -0,0 +1,83 @@
+/***
+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`.
+*/
+
+/**
+Type representing a nullable value. 
+A nullable value can be the value `'a`, `null` or `undefined`.
+*/
+type t<'a> = Js.Nullable.t<'a>
+
+/**
+The value `null`.
+
+See [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null) on MDN.
+
+## Examples
+```rescript
+Console.log(Nullable.null) // Logs `null` to the console.
+```
+*/
+external null: t<'a> = "#null"
+
+/**
+The value `undefined`.
+
+See [`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/undefined) on MDN.
+
+## Examples
+```rescript
+Console.log(Nullable.undefined) // Logs `undefined` to the console.
+```
+*/
+external undefined: t<'a> = "#undefined"
+
+/**
+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.")
+}
+```
+*/
+external make: 'a => t<'a> = "%identity"
+
+/**
+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.")
+}
+```
+*/
+external toOption: t<'a> => option<'a> = "#nullable_to_opt"
+
+/**
+Turns an `option` into a `Nullable.t`.
+
+## Examples
+```rescript
+let optString = Some("Hello")
+let asNullable = optString->Nullable.fromOption // Nullable.t<string>
+```
+*/
+let fromOption: option<'a> => t<'a>

src/Core__Undefined.resi

@@ -0,0 +1,75 @@
+/***
+Functions for handling values that could be `undefined`.
+
+Please note that a regular `option` is also represented as `undefined` or the value `'a`. In many cases it makes sense to use `option` directly.
+
+If you also need to cover `null`, check out `Nullable` instead.
+*/
+
+/**
+A type representing a value that can be either `'a` or `undefined`.
+*/
+type t<'a> = Js.Undefined.t<'a>
+
+/**
+Converts a `Undefined.t` into a `Nullable.t`.
+
+## Examples
+```rescript
+let undefinedValue = Undefined.make("Hello")
+let asNullable = undefinedValue->Undefined.asNullable // Nullable.t<string>
+```
+*/
+external asNullable: t<'a> => Core__Nullable.t<'a> = "%identity"
+
+/**
+The value `undefined`.
+
+See [`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/undefined) on MDN.
+
+## Examples
+```rescript
+Console.log(Undefined.undefined) // Logs `undefined` to the console.
+```
+*/
+external undefined: t<'a> = "#undefined"
+
+/**
+Creates a new `Undefined.t` from the provided value. 
+This means the compiler will enforce `undefined` checks for the new value.
+
+## Examples
+```rescript
+let myStr = "Hello"
+let asUndefinedValue = myStr->Undefined.make // The compiler now thinks this can be `string` or `undefined`.
+```
+*/
+external make: 'a => t<'a> = "%identity"
+
+/**
+Converts a potentially undefined value into an option, so it can be pattern matched on.
+Will convert `undefined` to `None`, and a present value to `Some(value)`.
+
+## Examples
+```rescript
+let undefinedStr = Undefined.make("Hello")
+
+switch undefinedStr->Undefined.toOption {
+| Some(str) => Console.log2("Got string:", str)
+| None => Console.log("Didn't have a value.")
+}
+```
+*/
+external toOption: t<'a> => option<'a> = "#undefined_to_opt"
+
+/**
+Turns an `option` into a `Undefined.t`. `None` will be converted to `undefined`.
+
+## Examples
+```rescript
+let optString: option<string> = None
+let asUndefined = optString->Undefined.fromOption // Undefined.t<string>
+Console.log(asUndefined == Undefined.undefined) // Logs `true` to the console.
+```
+*/
+let fromOption: option<'a> => t<'a>