Add throw (#7346)

* Add `throw`

Deprecate `raise` and rename references

* remove raise from Pervasives_mini.res

* convert to external and add deprecated attr

* restore tests/gentype_tests/typescript-react-example/package-lock.json

* update analysis output

* update CHANGELOG.md

* move `throw` to Pervasives.res

* Update runtime/Pervasives.res

Co-authored-by: Christoph Knittel <[email protected]>

* Update runtime/Pervasives.res

Co-authored-by: Christoph Knittel <[email protected]>

* Update runtime/Pervasives.res

Co-authored-by: Christoph Knittel <[email protected]>

* Update runtime/Stdlib_Error.resi

Co-authored-by: Christoph Knittel <[email protected]>

* Update runtime/Stdlib_Error.resi

Co-authored-by: Christoph Knittel <[email protected]>

* Update runtime/Stdlib_Error.resi

Co-authored-by: Christoph Knittel <[email protected]>

* update Stdlib_Bool and Stdlib_Char

* remove comment

---------

Co-authored-by: Christoph Knittel <[email protected]>

Author: aspeddro

CHANGELOG.md

@@ -22,6 +22,7 @@
 - Fix Pervasive.max using boolean comparison for floats. https://github.com/rescript-lang/rescript/pull/7333
 - Experimental: Support nested/inline record types - records defined inside of other records, without needing explicit separate type definitions. https://github.com/rescript-lang/rescript/pull/7241
 - Add unified exponentiation (`**`) operator for numeric types using ES7 `**`. https://github.com/rescript-lang/rescript-compiler/pull/7153
+- Rename `raise` to `throw` to align with JavaScript vocabulary. `raise` has been deprecated. https://github.com/rescript-lang/rescript/pull/7346
 
 #### :boom: Breaking Change
 

runtime/Belt_List.res

@@ -88,7 +88,7 @@ let head = x =>
 
 let headExn = x =>
   switch x {
-  | list{} => raise(Not_found)
+  | list{} => throw(Not_found)
   | list{x, ..._} => x
   }
 
@@ -100,7 +100,7 @@ let tail = x =>
 
 let tailExn = x =>
   switch x {
-  | list{} => raise(Not_found)
+  | list{} => throw(Not_found)
   | list{_, ...t} => t
   }
 
@@ -126,7 +126,7 @@ let rec nthAuxAssert = (x, n) =>
     } else {
       nthAuxAssert(t, n - 1)
     }
-  | _ => raise(Not_found)
+  | _ => throw(Not_found)
   }
 
 let get = (x, n) =>
@@ -138,7 +138,7 @@ let get = (x, n) =>
 
 let getExn = (x, n) =>
   if n < 0 {
-    raise(Not_found)
+    throw(Not_found)
   } else {
     nthAuxAssert(x, n)
   }

runtime/Belt_MutableQueue.res

@@ -72,7 +72,7 @@ let peekUndefined = q =>
 
 let peekExn = q =>
   switch q.first {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(v) => v.content
   }
 
@@ -95,7 +95,7 @@ let pop = q =>
 let popExn = q =>
   /* TO fix */
   switch q.first {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(x) =>
     let next = x.next
     if next == None {

runtime/Belt_Option.res

@@ -37,7 +37,7 @@ let forEach = (opt, f) =>
 let getExn = x =>
   switch x {
   | Some(x) => x
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   }
 
 external getUnsafe: option<'a> => 'a = "%identity"

runtime/Belt_Result.res

@@ -29,7 +29,7 @@ type t<'a, 'b> = result<'a, 'b> =
 let getExn = x =>
   switch x {
   | Ok(x) => x
-  | Error(_) => raise(Not_found)
+  | Error(_) => throw(Not_found)
   }
 
 let mapWithDefault = (opt, default, f) =>

runtime/Belt_internalAVLset.res

@@ -590,7 +590,7 @@ let rec getUndefined = (n: t<_>, x, ~cmp) =>
 
 let rec getExn = (n: t<_>, x, ~cmp) =>
   switch n {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(t) /* Node(l, v, r, _) */ =>
     let v = t.value
     let c = Belt_Id.getCmpInternal(cmp)(x, v)

runtime/Belt_internalAVLtree.res

@@ -713,7 +713,7 @@ let rec getUndefined = (n, x, ~cmp) =>
 
 let rec getExn = (n, x, ~cmp) =>
   switch n {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(n) /* Node(l, v, d, r, _) */ =>
     let v = n.key
     let c = Belt_Id.getCmpInternal(cmp)(x, v)

runtime/Belt_internalMapInt.res

@@ -65,7 +65,7 @@ let rec getUndefined = (n, x: key) =>
 
 let rec getExn = (n, x: key) =>
   switch n {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(n) =>
     let v = n.N.key
     if x == v {

runtime/Belt_internalMapString.res

@@ -65,7 +65,7 @@ let rec getUndefined = (n, x: key) =>
 
 let rec getExn = (n, x: key) =>
   switch n {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(n) =>
     let v = n.N.key
     if x == v {

runtime/Belt_internalSetInt.res

@@ -106,7 +106,7 @@ let rec getUndefined = (n: t, x: value) =>
 
 let rec getExn = (n: t, x: value) =>
   switch n {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(t) =>
     let v = t.value
     if x == v {

runtime/Belt_internalSetString.res

@@ -106,7 +106,7 @@ let rec getUndefined = (n: t, x: value) =>
 
 let rec getExn = (n: t, x: value) =>
   switch n {
-  | None => raise(Not_found)
+  | None => throw(Not_found)
   | Some(t) =>
     let v = t.value
     if x == v {

runtime/Pervasives.res

@@ -1,28 +1,39 @@
-/**
-   Since [others] depend on this file, its public mli files **should not
-   export types** introduced here, otherwise it would cause 
-   conflicts here.
-
-   If the type exported here is also exported in modules from others,
-   you will get a type not equivalent.
-*/
 @deprecated("Do not use. This will be removed in v13")
 external /* Internal */
 
 __unsafe_cast: 'a => 'b = "%identity"
 
 /* Exceptions */
-
+@deprecated(
+  "`raise` has been renamed to `throw` to align with JavaScript vocabulary. Please use `throw` instead"
+)
 external raise: exn => 'a = "%raise"
 
 @deprecated("Use custom exception instead")
-let failwith = s => raise(Failure(s))
+let failwith = s => throw(Failure(s))
 
 @deprecated("Use custom exception instead")
-let invalid_arg = s => raise(Invalid_argument(s))
+let invalid_arg = s => throw(Invalid_argument(s))
 
 @deprecated("Use custom exception instead") exception Exit
 
+/**
+Raises the given exception, terminating execution unless caught by a surrounding try/catch block.
+
+## Examples
+
+```rescript
+let error = Error.make("Everything is upside down.")
+
+if 5 > 10 {
+  throw(error)
+} else {
+  Console.log("Phew, sanity still rules.")
+}
+```
+*/
+external throw: Stdlib_Error.t => 'a = "%raise"
+
 /* Composition operators */
 
 external \"|>": ('a, 'a => 'b) => 'b = "%revapply"

runtime/Pervasives_mini.res

@@ -1,5 +1,5 @@
 /* Exceptions */
-external raise: exn => 'a = "%raise"
+external throw: exn => 'a = "%raise"
 
 /* Debugging */
 

runtime/Primitive_array.res

@@ -2,14 +2,14 @@ let length = Primitive_array_extern.length
 
 let get = (xs, index) =>
   if index < 0 || index >= length(xs) {
-    raise(Invalid_argument("index out of bounds"))
+    throw(Invalid_argument("index out of bounds"))
   } else {
     xs->Primitive_array_extern.getUnsafe(index)
   }
 
 let set = (xs, index, newval) =>
   if index < 0 || index >= length(xs) {
-    raise(Invalid_argument("index out of bounds"))
+    throw(Invalid_argument("index out of bounds"))
   } else {
     xs->Primitive_array_extern.setUnsafe(index, newval)
   }

runtime/Primitive_bigint.res

@@ -25,7 +25,7 @@ external div: (bigint, bigint) => bigint = "%divbigint"
 
 let div = (x: bigint, y: bigint) =>
   if y == 0n {
-    raise(Division_by_zero)
+    throw(Division_by_zero)
   } else {
     div(x, y)
   }
@@ -34,7 +34,7 @@ external mod_: (bigint, bigint) => bigint = "%modbigint"
 
 let mod_ = (x: bigint, y: bigint) =>
   if y == 0n {
-    raise(Division_by_zero)
+    throw(Division_by_zero)
   } else {
     mod_(x, y)
   }

runtime/Primitive_int.res

@@ -23,14 +23,14 @@ let max = (x: int, y: int): int =>
 
 let div = (x: int, y: int) =>
   if y == 0 {
-    raise(Division_by_zero)
+    throw(Division_by_zero)
   } else {
     Primitive_int_extern.div(x, y)
   }
 
 let mod_ = (x: int, y: int) =>
   if y == 0 {
-    raise(Division_by_zero)
+    throw(Division_by_zero)
   } else {
     Primitive_int_extern.mod_(x, y)
   }

runtime/Primitive_lazy.res

@@ -50,7 +50,7 @@ exception Undefined
   }
 )
 
-%%private(let raise_undefined = () => raise(Undefined))
+%%private(let raise_undefined = () => throw(Undefined))
 
 /* Assume [blk] is a block with tag lazy */
 %%private(
@@ -59,8 +59,8 @@ exception Undefined
     blk.value = fnToVal(raise_undefined)
     try forward_with_closure(blk, closure) catch {
     | e =>
-      blk.value = fnToVal(() => raise(e))
-      raise(e)
+      blk.value = fnToVal(() => throw(e))
+      throw(e)
     }
   }
 )

runtime/Primitive_module.res

@@ -19,7 +19,7 @@ module type Empty = {}
     in the lambda layer
 */
 let init = (loc: (string, int, int), shape: shape) => {
-  let undef_module = _ => raise(Undefined_recursive_module(loc))
+  let undef_module = _ => throw(Undefined_recursive_module(loc))
   let rec loop = (shape: shape, struct_: Obj.t, idx) =>
     switch shape {
     | Function => Obj.setField(struct_, idx, Obj.magic(undef_module))

runtime/Primitive_object.res

@@ -94,7 +94,7 @@ let rec compare = (a: t, b: t): int =>
     | ("boolean", "boolean") => Pervasives.compare((magic(a): bool), magic(b))
     | ("boolean", _) => 1
     | (_, "boolean") => -1
-    | ("function", "function") => raise(Invalid_argument("compare: functional value"))
+    | ("function", "function") => throw(Invalid_argument("compare: functional value"))
     | ("function", _) => 1
     | (_, "function") => -1
     | ("bigint", "bigint")
@@ -261,7 +261,7 @@ let rec equal = (a: t, b: t): bool =>
     } else {
       let b_type = Js.typeof(b)
       if a_type == "function" || b_type == "function" {
-        raise(Invalid_argument("equal: functional value"))
+        throw(Invalid_argument("equal: functional value"))
       } /* first, check using reference equality */
       else if (
         /* a_type = "object" || "symbol" */

runtime/Primitive_string.res

@@ -23,7 +23,7 @@ let max = (x: string, y: string): string =>
 
 let getChar = (s, i) =>
   if i >= Primitive_string_extern.length(s) || i < 0 {
-    raise(Invalid_argument("index out of bounds"))
+    throw(Invalid_argument("index out of bounds"))
   } else {
     Primitive_string_extern.getChar(s, i)
   }

runtime/Primitive_util.res

@@ -2,7 +2,7 @@ module Js = Primitive_js_extern
 
 let raiseWhenNotFound = x =>
   if Js.testAny(x) {
-    raise(Not_found)
+    throw(Not_found)
   } else {
     x
   }

runtime/Stdlib_Bool.res

@@ -19,7 +19,7 @@ let fromStringExn = param =>
   switch param {
   | "true" => true
   | "false" => false
-  | _ => raise(Invalid_argument(`Bool.fromStringExn: value is neither "true" nor "false"`))
+  | _ => throw(Invalid_argument(`Bool.fromStringExn: value is neither "true" nor "false"`))
   }
 
 external compare: (bool, bool) => Stdlib_Ordering.t = "%compare"

runtime/Stdlib_Char.res

@@ -10,7 +10,7 @@ external fromIntUnsafe: int => t = "%identity"
 
 let fromIntExn = n =>
   if n < 0 || n > 255 {
-    raise(Invalid_argument("`Char.fromIntExn` expects an integer between 0 and 255"))
+    throw(Invalid_argument("`Char.fromIntExn` expects an integer between 0 and 255"))
   } else {
     fromIntUnsafe(n)
   }

runtime/Stdlib_Error.res

@@ -40,6 +40,8 @@ module URIError = {
 
 external raise: t => 'a = "%raise"
 
+external throw: t => 'a = "%raise"
+
 let panic = msg => make(`Panic! ${msg}`)->raise
 
 external ignore: t => unit = "%ignore"

runtime/Stdlib_Error.resi

@@ -155,8 +155,28 @@ if 5 > 10 {
 }
 ```
 */
+@deprecated(
+  "`raise` has been renamed to `throw` to align with JavaScript vocabulary. Please use `throw` instead"
+)
 external raise: t => 'a = "%raise"
 
+/**
+Raises the given exception, terminating execution unless caught by a surrounding try/catch block.
+
+## Examples
+
+```rescript
+let error = Error.make("Everything is upside down.")
+
+if 5 > 10 {
+  Error.throw(error)
+} else {
+  Console.log("Phew, sanity still rules.")
+}
+```
+*/
+external throw: t => 'a = "%raise"
+
 /**
 Raises a panic exception with the given message.