Add Array.push API (#53762)

Summary:

Currently, the size of a jsi `Array` is immutable. Once the `Array` is
created, users can only set the element at an existing index, but not
append to it.

This change adds an `Array::push` API to improve ergonomics.
The default implementation is also provided in `jsi::Runtime`

Changelog: [Internal]

Reviewed By: lavenzg

Differential Revision: D82254334

Author: tsaichien

packages/react-native/ReactCommon/jsi/jsi/decorator.h

@@ -400,6 +400,10 @@ class RuntimeDecorator : public Base, private jsi::Instrumentation {
     plain_.setValueAtIndexImpl(a, i, value);
   }
 
+  size_t push(const Array& a, const Value* elements, size_t count) override {
+    return plain_.push(a, elements, count);
+  }
+
   Function createFunctionFromHostFunction(
       const PropNameID& name,
       unsigned int paramCount,
@@ -969,6 +973,10 @@ class WithRuntimeDecorator : public RuntimeDecorator<Plain, Base> {
     Around around{with_};
     RD::setValueAtIndexImpl(a, i, value);
   }
+  size_t push(const Array& a, const Value* elements, size_t count) override {
+    Around around{with_};
+    return RD::push(a, elements, count);
+  }
 
   Function createFunctionFromHostFunction(
       const PropNameID& name,

packages/react-native/ReactCommon/jsi/jsi/jsi-inl.h

@@ -362,6 +362,22 @@ inline Array Array::createWithElements(IRuntime& runtime, Args&&... args) {
       runtime, {detail::toValue(runtime, std::forward<Args>(args))...});
 }
 
+template <typename... Args>
+inline size_t Array::push(IRuntime& runtime, Args&&... args) {
+  return push(runtime, {detail::toValue(runtime, std::forward<Args>(args))...});
+}
+
+inline size_t Array::push(
+    IRuntime& runtime,
+    std::initializer_list<Value> elements) {
+  return push(runtime, elements.begin(), elements.size());
+}
+
+inline size_t
+Array::push(IRuntime& runtime, const Value* elements, size_t count) {
+  return runtime.push(*this, elements, count);
+}
+
 template <typename... Args>
 inline std::vector<PropNameID> PropNameID::names(
     IRuntime& runtime,

packages/react-native/ReactCommon/jsi/jsi/jsi.cpp

@@ -459,6 +459,16 @@ void Runtime::deleteProperty(const Object& object, const Value& name) {
   }
 }
 
+size_t Runtime::push(const Array& arr, const Value* elements, size_t count) {
+  size_t newSize = size(arr);
+  for (size_t i = 0; i < count; i++) {
+    arr.setProperty(*this, Value((int)newSize), elements[i]);
+    ++newSize;
+  }
+  arr.setProperty(*this, "length", Value((int)newSize));
+  return newSize;
+}
+
 void Runtime::setRuntimeDataImpl(
     const UUID& uuid,
     const void* data,

packages/react-native/ReactCommon/jsi/jsi/jsi.h

@@ -566,6 +566,7 @@ class JSI_EXPORT IRuntime : public ICast {
   virtual Value getValueAtIndex(const Array&, size_t i) = 0;
   virtual void
   setValueAtIndexImpl(const Array&, size_t i, const Value& value) = 0;
+  virtual size_t push(const Array&, const Value*, size_t) = 0;
 
   virtual Function createFunctionFromHostFunction(
       const PropNameID& name,
@@ -710,6 +711,8 @@ class JSI_EXPORT Runtime : public IRuntime {
       void* ctx,
       void (*cb)(void* ctx, bool ascii, const void* data, size_t num)) override;
 
+  size_t push(const Array&, const Value*, size_t) override;
+
  protected:
   friend class Pointer;
   friend class PropNameID;
@@ -1394,8 +1397,18 @@ class JSI_EXPORT Array : public Object {
   template <typename T>
   void setValueAtIndex(IRuntime& runtime, size_t i, T&& value) const;
 
-  /// There is no current API for changing the size of an array once
-  /// created.  We'll probably need that eventually.
+  /// Appends provides values to the end of the Array in the order they appear.
+  /// Returns the new length of the array.
+  template <typename... Args>
+  size_t push(IRuntime& runtime, Args&&... args);
+
+  /// Appends everything in \p elements to the end of the Array in the order
+  /// they appear. Returns the new length of the array.
+  size_t push(IRuntime& runtime, std::initializer_list<Value> elements);
+
+  /// Appends \p count elements at \p elements to the end of the Array in the
+  /// order they appear.
+  size_t push(IRuntime& runtime, const Value* elements, size_t count);
 
   /// Creates a new Array instance from provided values
   template <typename... Args>

packages/react-native/ReactCommon/jsi/jsi/test/testlib.cpp

@@ -2011,6 +2011,116 @@ TEST_P(JSITest, DeleteProperty) {
   EXPECT_TRUE(hasRes);
 }
 
+TEST_P(JSITest, ArrayPush) {
+  // This Runtime Decorator is used to test the default implementation of
+  // Runtime::push
+  class RD : public RuntimeDecorator<Runtime, Runtime> {
+   public:
+    explicit RD(Runtime& rt) : RuntimeDecorator(rt) {}
+
+    size_t push(const Array& arr, const Value* elements, size_t count)
+        override {
+      return Runtime::push(arr, elements, count);
+    }
+  };
+  RD rd = RD(rt);
+
+  // Push to an empty array
+  Array arr(rd, 0);
+  size_t newLength = arr.push(rd, 1, 2, 3);
+  EXPECT_EQ(newLength, 3);
+  EXPECT_EQ(arr.length(rd), 3);
+
+  EXPECT_EQ(arr.getValueAtIndex(rd, 0).getNumber(), 1);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 1).getNumber(), 2);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 2).getNumber(), 3);
+
+  // Push to an array already containing elements
+  arr = Array::createWithElements(rd, 1, true);
+  Object obj(rd);
+  newLength = arr.push(rd, "foobar", obj);
+  EXPECT_EQ(newLength, 4);
+  EXPECT_EQ(arr.length(rd), 4);
+
+  EXPECT_EQ(arr.getValueAtIndex(rd, 0).getNumber(), 1);
+  EXPECT_TRUE(arr.getValueAtIndex(rd, 1).getBool());
+  EXPECT_EQ(arr.getValueAtIndex(rd, 2).getString(rd).utf8(rd), "foobar");
+  EXPECT_TRUE(
+      Object::strictEquals(rd, arr.getValueAtIndex(rd, 3).getObject(rd), obj));
+
+  // Push to a Proxy of a JS Array
+  arr = eval("new Proxy([1], {})").getObject(rd).getArray(rd);
+  EXPECT_EQ(arr.length(rd), 1);
+
+  newLength = arr.push(rd, true, "foobar");
+  EXPECT_EQ(newLength, 3);
+  EXPECT_EQ(arr.length(rd), 3);
+
+  EXPECT_EQ(arr.getValueAtIndex(rd, 0).getNumber(), 1);
+  EXPECT_TRUE(arr.getValueAtIndex(rd, 1).getBool());
+  EXPECT_EQ(arr.getValueAtIndex(rd, 2).getString(rd).utf8(rd), "foobar");
+
+  // Push to a Proxy of a JS Array, where getting the length returns a custom
+  // value
+  arr = eval(
+            "var arr = [1];"
+            "var handler = {"
+            "    get(target, property) {"
+            "        if (property == 'length') {"
+            "            return target.length + 1;"
+            "        }"
+            "        return Reflect.get(target, property);"
+            "    }"
+            "};"
+            "var proxy = new Proxy(arr, handler);"
+            "proxy;")
+            .getObject(rd)
+            .getArray(rd);
+  // The handler returns the underlying array's length plus 1
+  EXPECT_EQ(arr.length(rd), 2);
+
+  // The elements will be adding starting at element 2
+  newLength = arr.push(rd, 3, 4);
+  EXPECT_EQ(newLength, 4);
+
+  EXPECT_EQ(arr.length(rd), 5);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 0).getNumber(), 1);
+  EXPECT_TRUE(arr.getValueAtIndex(rd, 1).isUndefined());
+  EXPECT_EQ(arr.getValueAtIndex(rd, 2).getNumber(), 3);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 3).getNumber(), 4);
+
+  // Push to a Proxy of a JS Array, where setting the 'length' property is
+  // customized
+  arr = eval(
+            "var arr = [1];"
+            "var handler = {"
+            "    set(target, property, value) {"
+            "        if (property == 'length') {"
+            "            return Reflect.set(target, property, value + 1);"
+            "        }"
+            "        return Reflect.set(target, property, value);"
+            "    }"
+            "};"
+            "var proxy = new Proxy(arr, handler);"
+            "proxy;")
+            .getObject(rd)
+            .getArray(rd);
+
+  EXPECT_EQ(arr.length(rd), 1);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 0).getNumber(), 1);
+
+  newLength = arr.push(rd, 2, 3);
+  EXPECT_EQ(newLength, 3);
+
+  // When setting the 'length' property, the handler will actually set it to 3 +
+  // 1
+  EXPECT_EQ(arr.length(rd), 4);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 0).getNumber(), 1);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 1).getNumber(), 2);
+  EXPECT_EQ(arr.getValueAtIndex(rd, 2).getNumber(), 3);
+  EXPECT_TRUE(arr.getValueAtIndex(rd, 3).isUndefined());
+}
+
 INSTANTIATE_TEST_CASE_P(
     Runtimes,
     JSITest,