Null additions (#73)

* feat(null): add getWithDefault, getExn, getUnsafe, map, mapWithDefault, flatMap

* docs(null): Null.null -> null

* docs(nullable): Nullable.undefined -> undefined

* docs(changelog): add changelog entry for Null additions

Author: glennsl

CHANGELOG.md

@@ -18,6 +18,7 @@
 - Change `Float.fromString` signature. Now accepts only string. https://github.com/rescript-association/rescript-core/pull/54
 - Change `Float.parseFloat` signature. Now accepts only string. https://github.com/rescript-association/rescript-core/pull/54
 - Add `getExn`, `getUnsafe`, `getWithDefault`, `map`, `mapWithDefault` and `flatMap` to `Nullable`. https://github.com/rescript-association/rescript-core/pull/67
+- Add `getExn`, `getUnsafe`, `getWithDefault`, `map`, `mapWithDefault` and `flatMap` to `Null`. https://github.com/rescript-association/rescript-core/pull/73
 
 ### Documentation
 

src/Core__Null.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Curry from "rescript/lib/es6/curry.js";
 import * as Caml_option from "rescript/lib/es6/caml_option.js";
 
 function fromOption(option) {
@@ -10,7 +11,55 @@ function fromOption(option) {
   }
 }
 
+function getWithDefault(value, $$default) {
+  if (value !== null) {
+    return value;
+  } else {
+    return $$default;
+  }
+}
+
+function getExn(value) {
+  if (value !== null) {
+    return value;
+  }
+  throw {
+        RE_EXN_ID: "Invalid_argument",
+        _1: "Null.getExn: value is null",
+        Error: new Error()
+      };
+}
+
+function map(value, f) {
+  if (value !== null) {
+    return Curry._1(f, value);
+  } else {
+    return null;
+  }
+}
+
+function mapWithDefault(value, $$default, f) {
+  if (value !== null) {
+    return Curry._1(f, value);
+  } else {
+    return $$default;
+  }
+}
+
+function flatMap(value, f) {
+  if (value !== null) {
+    return Curry._1(f, value);
+  } else {
+    return null;
+  }
+}
+
 export {
   fromOption ,
+  getWithDefault ,
+  getExn ,
+  map ,
+  mapWithDefault ,
+  flatMap ,
 }
 /* No side effect */

src/Core__Null.res

@@ -13,3 +13,35 @@ let fromOption: option<'a> => t<'a> = option =>
   | Some(x) => make(x)
   | None => null
   }
+
+let getWithDefault = (value, default) =>
+  switch value->toOption {
+  | Some(x) => x
+  | None => default
+  }
+
+let getExn: t<'a> => 'a = value =>
+  switch value->toOption {
+  | Some(x) => x
+  | None => raise(Invalid_argument("Null.getExn: value is null"))
+  }
+
+external getUnsafe: t<'a> => 'a = "%identity"
+
+let map = (value, f) =>
+  switch value->toOption {
+  | Some(x) => make(f(x))
+  | None => null
+  }
+
+let mapWithDefault = (value, default, f) =>
+  switch value->toOption {
+  | Some(x) => f(x)
+  | None => default
+  }
+
+let flatMap = (value, f) =>
+  switch value->toOption {
+  | Some(x) => f(x)
+  | None => null
+  }

src/Core__Null.resi

@@ -27,7 +27,7 @@ See [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/O
 
 ## Examples
 ```rescript
-Console.log(Null.null) // Logs `null` to the console.
+Console.log(null) // Logs `null` to the console.
 ```
 */
 external null: t<'a> = "#null"
@@ -67,7 +67,106 @@ Turns an `option` into a `Null.t`. `None` will be converted to `null`.
 ```rescript
 let optString: option<string> = None
 let asNull = optString->Null.fromOption // Null.t<string>
-Console.log(asNull == Null.null) // Logs `true` to the console.
+Console.log(asNull == null) // Logs `true` to the console.
 ```
 */
 let fromOption: option<'a> => t<'a>
+
+/**
+`getWithDefault(value, default)` returns `value` if not `null`, otherwise return
+`default`.
+
+## Examples
+
+```rescript
+Null.getWithDefault(null, "Banana") // Banana
+Null.getWithDefault(Nulalble.make("Apple"), "Banana") // Apple
+
+let greet = (firstName: option<string>) =>
+  "Greetings " ++ firstName->Null.getWithDefault("Anonymous")
+
+Null.make("Jane")->greet // "Greetings Jane"
+null->greet // "Greetings Anonymous"
+```
+*/
+let getWithDefault: (t<'a>, 'a) => 'a
+
+/**
+`getExn(value)` raises an exception if `null`, otherwise returns the value.
+
+```rescript
+Null.getExn(Null.make(3)) // 3
+Null.getExn(null) /* Raises an Error */
+```
+
+## Exceptions
+
+- Raises `Invalid_argument` if `value` is `null`,
+*/
+let getExn: t<'a> => 'a
+
+/**
+`getUnsafe(value)` returns `value`.
+
+## Examples
+
+```rescript
+Null.getUnsafe(Null.make(3)) == 3
+Null.getUnsafe(null) // Raises an error
+```
+
+## Important
+
+- This is an unsafe operation, it assumes `value` is not `null`.
+*/
+external getUnsafe: t<'a> => 'a = "%identity"
+
+/**
+`map(value, f)` returns `f(value)` if `value` is not `null`, otherwise returns
+`value` unchanged.
+
+## Examples
+
+```rescript
+Null.map(Null.make(3), x => x * x) // Null.make(9)
+Null.map(null, x => x * x) // null
+```
+*/
+let map: (t<'a>, 'a => 'b) => t<'b>
+
+/**
+`mapWithDefault(value, default, f)` returns `f(value)` if `value` is not `null`,
+otherwise returns `default`.
+
+## Examples
+
+```rescript
+let someValue = Null.make(3)
+someValue->Null.mapWithDefault(0, x => x + 5) // 8
+
+let noneValue = null
+noneValue->Null.mapWithDefault(0, x => x + 5) // 0
+```
+*/
+let mapWithDefault: (t<'a>, 'b, 'a => 'b) => 'b
+
+/**
+`flatMap(value, f)` returns `f(value)` if `value` is not `null`, otherwise
+returns `value` unchanged.
+
+## Examples
+
+```rescript
+let addIfAboveOne = value =>
+  if (value > 1) {
+    Null.make(value + 1)
+  } else {
+    null
+  }
+
+Null.flatMap(Null.make(2), addIfAboveOne) // Null.make(3)
+Null.flatMap(Null.make(-4), addIfAboveOne) // null
+Null.flatMap(null, addIfAboveOne) // null
+```
+*/
+let flatMap: (t<'a>, 'a => t<'b>) => t<'b>

src/Core__Nullable.resi

@@ -29,7 +29,7 @@ See [`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refere
 
 ## Examples
 ```rescript
-Console.log(Nullable.undefined) // Logs `undefined` to the console.
+Console.log(undefined) // Logs `undefined` to the console.
 ```
 */
 external undefined: t<'a> = "#undefined"
@@ -139,7 +139,7 @@ otherwise returns `value` unchanged.
 
 ```rescript
 Nullable.map(Nullable.make(3), x => x * x) // Nullable.make(9)
-Nullable.map(Nullable.undefined, x => x * x) // Nullable.undefined
+Nullable.map(undefined, x => x * x) // undefined
 ```
 */
 let map: (t<'a>, 'a => 'b) => t<'b>
@@ -175,8 +175,8 @@ let addIfAboveOne = value =>
   }
 
 Nullable.flatMap(Nullable.make(2), addIfAboveOne) // Nullable.make(3)
-Nullable.flatMap(Nullable.make(-4), addIfAboveOne) // Nullable.undefined
-Nullable.flatMap(Nullable.null, addIfAboveOne) // Nullable.undefined
+Nullable.flatMap(Nullable.make(-4), addIfAboveOne) // undefined
+Nullable.flatMap(Nullable.null, addIfAboveOne) // undefined
 ```
 */
 let flatMap: (t<'a>, 'a => t<'b>) => t<'b>