Remove Int.Ref and the %incr, %decr and %refget builtins

None of these were designed for ReScript. %incr, %decr and %refget arrived
with OCaml's Pervasives in the 2016 initial export and were carried unexamined
through every stdlib reshuffle since. Int.Ref itself was created in April 2025
(#7371) not because anyone wanted it, but as somewhere for the Pervasives.incr
deprecation to point; the primitives it wrapped were removed for v13 two weeks
ago. Outside this repository, GitHub code search finds no user of either the
externals or the API.

What the primitive bought was unboxing: expanding at the call site kept the
field write syntactically visible, so Lam_pass_eliminate_ref could still turn
a local ref into a mutable variable. A call through an ordinary function
cannot - the reference appears as a bare Lvar and the pass gives up. That is
not special to increment. Its body is six nodes against a small_inline_size of
five, and cross-module inlining is off, so the inliner cannot reach it.

Writing the update directly does keep the unboxing, and is shorter than the
call it replaces:

    Int.Ref.increment(v)   ->   v.contents = v.contents + 1

53 call sites across 30 test files change that way, and their generated
JavaScript is byte-identical. Only two outputs move: Stdlib_Int loses an empty
Ref object and its export, and test_incr_ref loses onExpression - added to pin
that the primitive bound its argument before mentioning it twice, which has
nothing left to test now that no expansion happens.

Lambda.offset_ref and the Offset_ref builtin go with them. Nothing in lambda.ml
now builds a term outside the constructors and the traversals.

Int.Ref.t went too. It was a type alias for ref<int> introduced alongside the
two functions, and with them gone the module held nothing else.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W8g8qwBARAcvW9MyuKQq8H

Author: cristianoc

CHANGELOG.md

@@ -22,6 +22,7 @@
 - Correct the structured function details produced by `rescript-tools doc` and exposed by `RescriptTools.Docgen`: parameters now retain labels and optionality, nested functions, tuples, variables, and generic arguments retain their type structure, return types are identified correctly, and non-function values no longer receive fake function details. This changes the published docgen detail schema. https://github.com/rescript-lang/rescript/pull/8576
 - Make object-field mutability part of the type. A property has one type for reading and writing. Assignment requires `@set`, except on an inferred open row, where assignment makes the field settable. Private rows are not inferred open rows, so a field in `type t = private {.."x": int}` is writable only when annotated with `@set`. Coercions never grant or widen write capability. Previously, getter and setter types were tracked independently, allowing a property to be written at a different type than it was read and allowing writes through a value coerced to a type without `@set`. https://github.com/rescript-lang/rescript/pull/8597
 - Remove the undocumented object-field attribute forms `@get` (bare or with a `null`/`undefined`/`nullable` payload) and `@set({no_get: ...})` on object types. Only bare `@set` marks a field settable; nullable getter types are written directly (`null<t>`, `undefined<t>`, `nullable<t>`). https://github.com/rescript-lang/rescript/pull/8597
+- Remove `Int.Ref` and the `%incr`, `%decr` and `%refget` builtins behind it. Write `r.contents = r.contents + 1` instead; an `external` declared with one of the removed names is now rejected. https://github.com/rescript-lang/rescript/pull/8616
 
 #### :eyeglasses: Spec Compliance
 

compiler/ml/lambda.ml

@@ -351,9 +351,6 @@ type builtin =
   | Primitive of primitive
   | Eliminated of eliminated
   | Constant of structured_constant
-  | Offset_ref of int
-      (** [%incr] / [%decr]: an assignment through the reference, expanded here
-          so the caller's own IR carries the form its escape analysis reads. *)
 
 type inline_attribute =
   | Always_inline (* [@inline] or [@inline always] *)
@@ -490,35 +487,6 @@ let lambda_false = Lconst Const_js_false
 
 (* [r := r.contents + delta]. The reference is mentioned twice, so bind it
    unless it is already a variable. *)
-let offset_ref ~delta r loc =
-  let assign r =
-    Lprim
-      {
-        primitive = Psetfield (0, ref_field_set_info);
-        args =
-          [
-            r;
-            Lprim
-              {
-                primitive = Paddint;
-                args =
-                  [
-                    Lprim
-                      {primitive = Pfield (0, ref_field_info); args = [r]; loc};
-                    Lconst (const_int delta);
-                  ];
-                loc;
-              };
-          ];
-        loc;
-      }
-  in
-  match r with
-  | Lvar _ -> assign r
-  | _ ->
-    let id = Ident.create "ref" in
-    Llet (Strict, id, r, assign (Lvar id))
-
 let eq_comparison (p : comparison) (p1 : comparison) = p = p1
 
 let eq_field_dbg_info (x : field_dbg_info) (y : field_dbg_info) = x = y
@@ -1269,10 +1237,6 @@ let mk_builtin b args loc =
     match args with
     | [] -> Lconst c
     | _ -> assert false)
-  | Offset_ref delta -> (
-    match args with
-    | [r] -> offset_ref ~delta r loc
-    | _ -> assert false)
   | Eliminated Identity -> (
     match args with
     | [arg] -> arg

compiler/ml/lambda.mli

@@ -321,9 +321,6 @@ type builtin =
   | Primitive of primitive
   | Eliminated of eliminated
   | Constant of structured_constant
-  | Offset_ref of int
-      (** [%incr] / [%decr]: an assignment through the reference, expanded here
-          so the caller's own IR carries the form its escape analysis reads. *)
 
 type inline_attribute =
   | Always_inline (* [@inline] or [@inline always] *)

compiler/ml/translcore.ml

@@ -252,8 +252,6 @@ let erased_builtins : (string * Lambda.builtin) array =
     ("%identity", Eliminated Identity);
     ("%component_identity", Eliminated Identity);
     ("%ignore", Eliminated Ignore);
-    ("%incr", Offset_ref 1);
-    ("%decr", Offset_ref (-1));
     ("%null", Constant Const_js_null);
     ("%undefined", Constant (Const_js_undefined {is_unit = false}));
     (* FIXME: Core compatibility *)
@@ -268,7 +266,6 @@ let primitive_builtins : (string * Lambda.builtin) array =
       (* BEGIN Triples for  ref data type *)
       ("%makeref", Pmakeblock Lambda.ref_tag_info);
       ("%refset", Psetfield (0, Lambda.ref_field_set_info));
-      ("%refget", Pfield (0, Lambda.ref_field_info));
       (* Finish Triples for  ref data type *)
       ("%field0", Pfield (0, Fld_tuple));
       ("%field1", Pfield (1, Fld_tuple));

packages/@rescript/runtime/Stdlib_Int.res

@@ -127,10 +127,3 @@ module Bitwise = {
 }
 
 external ignore: int => unit = "%ignore"
-
-module Ref = {
-  type t = ref<int>
-
-  external increment: ref<int> => unit = "%incr"
-  external decrement: ref<int> => unit = "%decr"
-}

packages/@rescript/runtime/Stdlib_Int.resi

@@ -520,33 +520,3 @@ module Bitwise: {
   without having to store or process it further.
 */
 external ignore: int => unit = "%ignore"
-
-module Ref: {
-  type t = ref<int>
-
-  /**
-  `increment(intRef)` increments the value of the provided reference by 1.
-
-  ## Examples
-
-  ```rescript
-  let myRef = ref(4)
-  Int.Ref.increment(myRef)
-  myRef.contents == 5
-  ```
-  */
-  external increment: ref<int> => unit = "%incr"
-
-  /**
-  `decrement(intRef)` decrements the value of the provided reference by 1.
-
-  ## Examples
-
-  ```rescript
-  let myRef = ref(4)
-  Int.Ref.decrement(myRef)
-  myRef.contents == 3
-  ```
-  */
-  external decrement: ref<int> => unit = "%decr"
-}

packages/@rescript/runtime/lib/es6/Stdlib_Int.mjs

@@ -75,8 +75,6 @@ let Bitwise = {
   lnot: lnot
 };
 
-let Ref = {};
-
 let Constants = {
   minValue: -2147483648,
   maxValue: 2147483647
@@ -89,6 +87,5 @@ export {
   rangeWithOptions,
   clamp,
   Bitwise,
-  Ref,
 }
 /* No side effect */

packages/@rescript/runtime/lib/js/Stdlib_Int.cjs

@@ -75,8 +75,6 @@ let Bitwise = {
   lnot: lnot
 };
 
-let Ref = {};
-
 let Constants = {
   minValue: -2147483648,
   maxValue: 2147483647
@@ -88,5 +86,4 @@ exports.range = range;
 exports.rangeWithOptions = rangeWithOptions;
 exports.clamp = clamp;
 exports.Bitwise = Bitwise;
-exports.Ref = Ref;
 /* No side effect */

tests/belt_tests/src/bs_queue_test.res

@@ -116,7 +116,7 @@ describe(__MODULE__, () => {
       q,
       j => {
         assert(i.contents == j)
-        Stdlib.Int.Ref.increment(i)
+        i.contents = i.contents + 1
       },
     )
   })

tests/tests/src/ari_regress_test.res

@@ -13,7 +13,7 @@ let gg = (x, y) => {
 
 let g1 = (x, y) => {
   let u = x + y
-  let () = Int.Ref.increment(h)
+  let () = h.contents = h.contents + 1
   (xx, yy) => xx + yy + u
 }
 let x = gg(3, 5)(6)