Fix JS-compatible callback arity for Array methods

reference/REFERENCE.md

@@ -203,6 +203,12 @@ Status of built-in methods and properties on GiavaScript runtime types.
 | `values()` | Instance method | Not available |
 | `with()` | Instance method | Not available |
 
+#### Array callback argument behavior
+
+- In array methods that accept callbacks, user-defined callback functions use JavaScript-compatible argument normalization.
+- Extra callback arguments are ignored.
+- Missing callback arguments are passed as `undefined`.
+
 ### Object
 
 | Member | Kind | Status |

reference/Types.md

@@ -97,6 +97,12 @@ Status of built-in methods and properties on GiavaScript runtime types.
 | `values()` | Instance method | Not available |
 | `with()` | Instance method | Not available |
 
+### Array callback argument behavior
+
+- In array methods that accept callbacks, user-defined callback functions use JavaScript-compatible argument normalization.
+- Extra callback arguments are ignored.
+- Missing callback arguments are passed as `undefined`.
+
 ## Object
 
 | Member | Kind | Status |

spec/giavascript_spec.cr

@@ -874,6 +874,14 @@ describe GiavaScript do
     interpreter.eval("numbers.findIndex(function(value, index, array) { return value * 2 == array.length + index + 1; });").should eq(["3"])
   end
 
+  it "uses JS-compatible callback arity for array methods" do
+    interpreter = GiavaScript::Interpreter.new
+    interpreter.eval("var array = [1, 4, 9, 16];").should eq([] of String)
+    interpreter.eval("array.map(function(x) { return x * 2; });").should eq(["[2, 8, 18, 32]"])
+    interpreter.eval("array.map(function(value, index, source, extra) { return extra; });").should eq(["[undefined, undefined, undefined, undefined]"])
+    interpreter.eval("[1, 2, 3].reduce(function(acc, value) { return acc + value; }, 0);").should eq(["6"])
+  end
+
   it "supports Array.reduce with and without an initial value" do
     interpreter = GiavaScript::Interpreter.new
     interpreter.eval("[1, 2, 3].reduce(function(acc, value, index, array) { return acc + value + index + array.length; }, 0);").should eq(["18"])

src/giavascript/runtime_types.cr

@@ -959,7 +959,26 @@ module GiavaScript
         raise ExpressionError.new("Error: #{method_name} callback invoker is not configured")
       end
 
-      invoker.call(callback, args)
+      callback_args = normalize_callback_args(callback, args)
+      invoker.call(callback, callback_args)
+    end
+
+    private def normalize_callback_args(callback : Value, args : Array(Value)) : Array(Value)
+      return args unless callback.is_a?(UserFunction)
+
+      expected_count = callback.parameters.size
+      provided_count = args.size
+      return args if expected_count == provided_count
+
+      normalized = Array(Value).new(expected_count)
+      index = 0
+
+      while index < expected_count
+        normalized << (index < provided_count ? args[index] : UNDEFINED)
+        index += 1
+      end
+
+      normalized
     end
 
     private def string_argument(value : Value, method_name : String) : String