Move bound-checking requirements into API, not in primitives

Author: cometkim

text/0001-int.md

@@ -43,14 +43,13 @@ Let `min_value` be $-2^{31}$ and `max_value` be $2^{31}-1$
 
 ### `fromNumber: (x: number) => int`
 
-1. If `x` is JavaScript's `Infinity`, return `max_value`.
-2. If `x` is JavaScript's `-Infinity`, return `min_value`.
-3. Let `int32` be [`ToInt32`]`(x)`, return `int32`.
-
-Actions 1 and 2 are intended to relax confusion when converting from infinite value directly. (e.g. https://github.com/rescript-lang/rescript/issues/6737) However, it can be omitted if the input is obviously not `Infinity` or `-Infinity`.
+1. Let `int32` be [`ToInt32`]`(x)`, return `int32`.
 
 The [`ToInt32`] behavior follows the definition in ECMA-262 as is. ReScript compiler uses `bitwiseOR(number, 0)` in action. This is what appears in the output as `number | 0`, which truncates all special numbers defined in IEEE-754.
 
+The `fromNumber` shouldn't be directly exposed to the users. Applying the [`ToInt32`] operation to special numeric values, such as `Infinity`, can lead to subtle bugs (see example: [issue #6737](https://github.com/rescript-lang/rescript/issues/6737)).
+Instead, Public APIs should wrap it and perform bounds-checking, if necessary, either emit errors (explained further in the "API Consideration" section below) or notify the user via compiler warning.
+
 `int` never contains the following values:
 
 - `-0`
@@ -61,6 +60,11 @@ The [`ToInt32`] behavior follows the definition in ECMA-262 as is. ReScript comp
 
 `fromNumber(x)` must be idempotent.
 
+### `minus: (x: int) => int`
+
+1. Let `number` be mathematically $-x$.
+2. Let `int32` be `fromNumber(number)`, return `int32`.
+
 ### `add: (x: int, y: int) => int`
 
 1. Let `number` be mathematically $x + y$.
@@ -125,16 +129,50 @@ let exponentiate = (x, y) => {
 ### `abs: (x: int) => int`
 
 1. If `x` is `min_value`, raise `Overflow_value`.
+2. If `x` is less than `0`, return `minus(x)`.
+3. return `x`.
 
 ## API consideration
 
 These primitive operations for `int` often don't work as intended by the user due to the `fromNumber` truncation.
 
-APIs that use this should make it safer by providing appropriate errors with standard types.
+Public APIs should make it safer by providing appropriate bunnds-checking, and errors with standard types.
 
 ### Standard error types
 
-TBD
+```res
+type int_error =
+  /** If the operand represents IEEE-754 `NaN`. */
+  | NaN
+  /** If the operation cannot be performed in the bounds of int32. */
+  | Overflow_value
+  /** If the operation perform devision value (first argument) by `0`. */
+  | Divide_by_zero(int)
+```
+
+`int_error` can be used as error playload in a `result`, and also exception payload.
+
+```res
+exception ConversionError(int_error)
+
+let fromFloatUnsafe = (x: float) => {
+  if x == Primitive_number.NaN {
+    throw ConversionError(NaN)
+  } else if x > Primitive_number.max_int32 || x < Primitive_number.min_int32 {
+    throw ConversionError(Overflow_value)
+  } else {
+    Primitive_int32.fromNumber(x)
+  }
+}
+
+let fromFloat = (x: int) => {
+  switch fromFloatUnsafe(x) {
+  | catch ConversionError(e) => Error(e)
+  | x => Ok(x)
+  }
+}
+```
+
 
 ## Questions