Update proposal

* fix typos
* more explanation

Author: cometkim

text/0001-int.md

@@ -7,11 +7,11 @@ ReScript Issue: (leave this empty)
 
 ## Summary
 
-Semantics deifinition of the ReScript's `int` type and integer primitives.
+Semantics definition of the ReScript's `int` type and integer primitives.
 
 ## Motivation
 
-ReScript has three numeric primitive types, `int`, `float` and `bigint`.
+ReScript has three numeric primitive types, `int`, `float`, and `bigint`.
 
 The semantics of `float` and `bigint` completely match JavaScript's ones, but `int` is unique to ReScript and originally came from OCaml's `int` type.
 
@@ -21,49 +21,59 @@ This RFC describes its semantics and chosen trade-offs as precisely as possible.
 
 ## Definition
 
-TBD
+`int` is a built-in type.
 
 ```res
 type int
+```
+
+A numeric literal with only an integer part has type `int`.
 
+```res
 let n = 100
 ```
 
-Using unbounded integer literals may result in compile-time errors with messages such as `"Integer literal exceeds the range of representable integers of type int."`
+The valid range of an integer literal is limited to the range of signed 32-bit integers $[-2^{31} .. 2^{31}-1]$.
+
+Using unbounded numbers in literals may result in compile-time errors with messages such as `"Integer literal exceeds the range of representable integers of type int."`
 
 ## Primitives
 
-Let `max_value` be $2^{31}-1$ and `min_value` be $-2^{31}$.
+Let `min_value` be $-2^{31}$ and `max_value` be $2^{31}-1$
 
-### `fromNumber(x: number)`
+### `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`.
 
-The actions 1 and 2 are intended to reduce confusion when converting from an infinate value. (e.g. https://github.com/rescript-lang/rescript/issues/6737) However, it can be omitted if it is obvious that the `x` is not `Infinity` or `-Infinity`.
+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`.
+
+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 [`ToInt32`] behavior follows the definition in ECMA-262 as is. In action, the ReScript compiler uses `bitwiseOR(number, 0)`. This is what appears in the output as `number | 0`. And this removes all special numbers defined in IEEE-754. `int` never contain the following values:
+`int` never contains the following values:
 
+- `-0`
 - `NaN`
 - `Infinity` and `-Infinity`
-- `-0`
+- $x < $`min_value`
+- $x > $`max_value`
 
 `fromNumber(x)` must be idempotent.
 
-### `add(x: int, y: int)`
+### `add: (x: int, y: int) => int`
 
-1. Let `number` be mathmatically $x + y$.
+1. Let `number` be mathematically $x + y$.
 2. Let `int32` be `fromNumber(number)`, return `int32`.
 
-### `subtract(x, y)`
+### `subtract: (x: int, y: int) => int`
 
-1. Let `number` be mathmatically $x - y$.
+1. Let `number` be mathematically $x - y$.
 2. Let `int32` be `fromNumber(number)`, return `int32`.
 
-### `multiply(x, y)`
+### `multiply: (x: int, y: int) => int`
 
-1. Let `number` be mathmatically $x * y$.
+1. Let `number` be mathematically $x * y$.
 2. Let `int32` be `fromNumber(number)`, return `int32`.
 
 The `multiply(x, y)` must produce the same result as `add(x)` accumulated `y` times.
@@ -81,9 +91,9 @@ let multiply = (x, y) => {
 }
 ```
 
-### `exponentiate(x, y)`
+### `exponentiate: (x: int, y: int) => int`
 
-1. Let `number` be mathmatically $x ^ y$.
+1. Let `number` be mathematically $x ^ y$.
 2. Let `int32` be `fromNumber(number)`, return `int32`.
 
 The `exponentiate(x, y)` must produce the same result as `multiply(x)` accumulated `y` times.
@@ -101,45 +111,54 @@ let exponentiate = (x, y) => {
 }
 ```
 
-### `divide(x, y)`
+### `divide: (x: int, y: int) => int`
 
 1. If `y` equals `0`, raise `Divide_by_zero`.
-2. Let `number` be mathmatically $x / y$.
+2. Let `number` be mathematically $x / y$.
 3. Let `int32` be `fromNumber(number)`, return `int32`.
 
-### `remainder(x, y)`
+### `remainder: (x: int, y: int) => int`
 
 1. If `y` equals `0`, raise `Divide_by_zero`.
+2. Let `number` be mathematically $x / y$.
 
-### `abs(x)`
+### `abs: (x: int) => int`
 
 1. If `x` is `min_value`, raise `Overflow_value`.
 
 ## 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.
+
+### Standard error types
+
 TBD
 
 ## Questions
 
 ### Why do we even use `int`?
 
-The use of `int` is primarily for backward compatibility — not with OCaml, but with all existing ReScript codebases.
+Using `int` is primarily for backward compatibility — not with OCaml, but with all existing ReScript codebases.
 
-Additionally, using `int` is beneficial for JavaScript programs since major JavaScript engines treat integers differently.
+Additionally, using `int` benefits JavaScript programs since major JavaScript engines treat integers differently.
 
-Depending on the implementation, integer values (especially 32-bit integers) may have a distinct memory representation compared to floating-point numbers. For example, V8 (the JavaScript engine in Chromium) employs an internal element kind called "SMI" (Small integers). This provides an efficient memory representation for signed 32-bit integers and enhances runtime performance by avoiding heap allocation.
+Depending on the implementation, integer values (especially 32-bit integers) may have a distinct memory representation compared to floating-point numbers. For example, V8 (the JavaScript engine for Chromium and Node.js) employs an internal element kind called "SMI" (Small integers). This provides an efficient memory representation for signed 32-bit integers and enhances runtime performance by avoiding heap allocation.
 
-At compile time, the compiler ensures that certain operations are restricted to using only `int` types. This increases the likelihood of utilizing the optimized execution paths for SMIs and reduces the potential for runtime de-optimization caused by element kind transitions.
+At compile time, the compiler ensures that certain operations are restricted to using only `int` types. This increases the likelihood of utilizing the optimized execution paths for SMIs and reduces the potential for runtime de-optimization caused by element-kind transitions.
 
 ### Why do we truncate values instead of bounds-checking?
 
-It is also for backward compatibility. Bounds-checking and failure early may be more useful for fast feedback loop, but we don't want to break any programs that (accidentally) worked before.
+It is also for backward compatibility.
+
+Bounds-checking and failure early may be more useful for a fast feedback loop, but we don't want to break any programs that (accidentally) worked before.
 
-The `number | 0` is actually the most concise output form we can consistently use. Introducing any other runtime codes universally would lead to significant code bloat in the output.
+The `number | 0` is the most concise output form we can consistently use. Introducing any other runtime codes universally would lead to significant code bloat in the output.
 
 ### Can we somehow make it match JavaScript's `number`?
 
-Perhaps in the future, we can make our number literals actually match JavaScript's number semantics. We could also rename `int` to `int32` and assign another literal like `0l`, as it was in OCaml syntax.
+Perhaps, we can make our number literals match JavaScript's number semantics. We could also rename `int` to `int32` and assign another literal like `0l`, as it was in OCaml syntax.
 
 However, this is not something that will happen in the near future. It won't occur until we are confident in our migration strategy to avoid breaking existing codebases. If done incorrectly, it could completely break compatibility with existing code.