/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_dom_TypedArray_h
#define mozilla_dom_TypedArray_h

#include <string>
#include <type_traits>
#include <utility>

#include "js/ArrayBuffer.h"
#include "js/ArrayBufferMaybeShared.h"
#include "js/Context.h"
#include "js/GCAPI.h"       // JS::AutoCheckCannotGC
#include "js/RootingAPI.h"  // JS::Rooted
#include "js/ScalarType.h"  // JS::Scalar::Type
#include "js/SharedArrayBuffer.h"
#include "js/experimental/TypedData.h"  // js::Unwrap(Ui|I)nt(8|16|32)Array, js::Get(Ui|I)nt(8|16|32)ArrayLengthAndData, js::UnwrapUint8ClampedArray, js::GetUint8ClampedArrayLengthAndData, js::UnwrapFloat(32|64)Array, js::GetFloat(32|64)ArrayLengthAndData, JS_GetArrayBufferViewType
#include "js/friend/ErrorMessages.h"
#include "mozilla/Attributes.h"
#include "mozilla/Buffer.h"
#include "mozilla/ErrorResult.h"
#include "mozilla/Result.h"
#include "mozilla/Vector.h"
#include "mozilla/dom/BindingDeclarations.h"
#include "mozilla/dom/ScriptSettings.h"
#include "mozilla/dom/SpiderMonkeyInterface.h"
#include "nsIGlobalObject.h"
#include "nsWrapperCache.h"
#include "nsWrapperCacheInlines.h"

namespace mozilla::dom {

/*
 * Various typed array classes for argument conversion.  We have a base class
 * that has a way of initializing a TypedArray from an existing typed array, and
 * a subclass of the base class that supports creation of a relevant typed array
 * or array buffer object.
 *
 * Accessing the data of a TypedArray is tricky. The underlying storage is in a
 * JS object, which is subject to the JS GC. The memory for the array can be
 * either inline in the JSObject or stored separately. If the data is stored
 * inline then the exact location in memory of the data buffer can change as a
 * result of a JS GC (which is a moving GC). Running JS code can also mutate the
 * data (including the length). For all these reasons one has to be careful when
 * holding a pointer to the data or keeping a local copy of the length value. On
 * the other hand, most code that takes a TypedArray has to access its data at
 * some point, to process it in some way. The TypedArray class tries to supply a
 * number of helper APIs, so that the most common cases of processing the data
 * can be done safely, without having to check the caller very closely for
 * potential security issues. The main classes of processing TypedArray data
 * are:
 *
 *  1) Appending a copy of the data (or of a subset of the data) to a different
 *     data structure
 *  2) Copying the data (or a subset of the data) into a different data
 *     structure
 *  3) Creating a new data structure with a copy of the data (or of a subset of
 *     the data)
 *  4) Processing the data in some other way
 *
 * The APIs for the first 3 classes all return a boolean and take an optional
 * argument named aCalculator. aCalculator should be a lambda taking a size_t
 * argument which will be passed the total length of the data in the typed
 * array. aCalculator is allowed to return a std::pair<size_t, size_t> or a
 * Maybe<std::pair<size_t, size_t>>. The return value should contain the offset
 * and the length of the subset of the data that should be appended, copied or
 * used for creating a new datastructure. If the calculation can fail then
 * aCalculator should return a Maybe<std::pair<size_t, size_t>>, with Nothing()
 * signaling that the operation should be aborted.
 * The return value of these APIs will be false if appending, copying or
 * creating a structure with the new data failed, or if the optional aCalculator
 * lambda returned Nothing().
 *
 * Here are the different APIs:
 *
 *  1) Appending to a different data structure
 *
 *     There are AppendDataTo helpers for nsCString, nsTArray<T>,
 *     FallibleTArray<T> and Vector<T>. The signatures are:
 *
 *       template <typename... Calculator>
 *       [[nodiscard]] bool AppendDataTo(nsCString& aResult, Calculator&&...
 *                                       aCalculator) const;
 *
 *       template <typename T, typename... Calculator>
 *       [[nodiscard]] bool AppendDataTo(nsTArray<T>& aResult, Calculator&&...
 *                                       aCalculator) const;
 *
 *       template <typename T, typename... Calculator>
 *       [[nodiscard]] bool AppendDataTo(FallibleTArray<T>& aResult,
 *                                       Calculator&&... aCalculator) const;
 *
 *       template <typename T, typename... Calculator>
 *       [[nodiscard]] bool AppendDataTo(Vector<T>& aResult, Calculator&&...
 *                                       aCalculator) const;
 *
 *     The data (or the calculated subset) will be appended to aResult by using
 *     the appropriate fallible API. If the append fails then AppendDataTo will
 *     return false. The aCalculator optional argument is described above.
 *
 *     Examples:
 *
 *       Vector<uint32_t> array;
 *       if (!aUint32Array.AppendDataTo(array)) {
 *         aError.ThrowTypeError("Failed to copy data from typed array");
 *         return;
 *       }
 *
 *       size_t offset, length;
 *       … // Getting offset and length values from somewhere.
 *       FallibleTArray<float> array;
 *       if (!aFloat32Array.AppendDataTo(array, [&](const size_t& aLength) {
 *           size_t dataLength = std::min(aLength - offset, length);
 *           return std::make_pair(offset, dataLength);
 *         }) {
 *         aError.ThrowTypeError("Failed to copy data from typed array");
 *         return;
 *       }
 *
 *       size_t offset, length;
 *       … // Getting offset and length values from somewhere.
 *       FallibleTArray<float> array;
 *       if (!aFloat32Array.AppendDataTo(array, [&](const size_t& aLength) {
 *         if (aLength < offset + length) {
 *           return Maybe<std::pair<size_t, size_t>>();
 *         }
 *         size_t dataLength = std::min(aLength - offset, length);
 *         return Some(std::make_pair(offset, dataLength));
 *       })) {
 *         aError.ThrowTypeError("Failed to copy data from typed array");
 *         return;
 *       }
 *
 *
 *  2) Copying into a different data structure
 *
 *     There is a CopyDataTo helper for a fixed-size buffer. The signature is:
 *
 *       template <typename T, size_t N, typename... Calculator>
 *       [[nodiscard]] bool CopyDataTo(T (&aResult)[N],
 *                                     Calculator&&... aCalculator) const;
 *
 *     The data (or the calculated subset) will be copied to aResult, starting
 *     at aResult[0]. If the length of the data to be copied is bigger than the
 *     size of the fixed-size buffer (N) then nothing will be copied and
 *     CopyDataTo will return false. The aCalculator optional argument is
 *     described above.
 *
 *     Examples:
 *
 *       float data[3];
 *       if (!aFloat32Array.CopyDataTo(data)) {
 *         aError.ThrowTypeError("Typed array doesn't contain the right amount"
 *                               "of data");
 *         return;
 *       }
 *
 *       size_t offset;
 *       … // Getting offset value from somewhere.
 *       uint32_t data[3];
 *       if (!aUint32Array.CopyDataTo(data, [&](const size_t& aLength) {
 *         if (aLength - offset != std::size(data)) {
 *           aError.ThrowTypeError("Typed array doesn't contain the right"
 *                                 " amount of data");
 *           return Maybe<std::pair<size_t, size_t>>();
 *         }
 *         return Some(std::make_pair(offset, std::size(data)));
 *       }) {
 *         return;
 *       }
 *
 *  3) Creating a new data structure with a copy of the data (or a subset of the
 *     data)
 *
 *     There are CreateFromData helper for creating a Vector<element_type>, a
 *     UniquePtr<element_type[]> and a Buffer<element_type>.
 *
 *       template <typename... Calculator>
 *       [[nodiscard]] Maybe<Vector<element_type>>
 *       CreateFromData<Vector<element_type>>(
 *           Calculator&&... aCalculator) const;
 *
 *       template <typename... Calculator>
 *       [[nodiscard]] Maybe<UniquePtr<element_type[]>>
 *       CreateFromData<UniquePtr<element_type[]>>(
 *           Calculator&&... aCalculator) const;
 *
 *       template <typename... Calculator>
 *       [[nodiscard]] Maybe<Buffer<element_type>>
 *       CreateFromData<Buffer<element_type>>(
 *           Calculator&&... aCalculator) const;
 *
 *     A new container will be created, and the data (or the calculated subset)
 *     will be copied to it. The container will be returned inside a Maybe<…>.
 *     If creating the container with the right size fails then Nothing() will
 *     be returned. The aCalculator optional argument is described above.
 *
 *     Examples:
 *
 *       Maybe<Buffer<uint8_t>> buffer =
 *         aUint8Array.CreateFromData<Buffer<uint8_t>>();
 *       if (buffer.isNothing()) {
 *         aError.ThrowTypeError("Failed to create a buffer");
 *         return;
 *       }
 *
 *       size_t offset, length;
 *       … // Getting offset and length values from somewhere.
 *       Maybe<Buffer<uint8_t>> buffer =
 *         aUint8Array.CreateFromData<Buffer<uint8_t>>([&](
 *             const size_t& aLength) {
 *         if (aLength - offset != std::size(data)) {
 *           aError.ThrowTypeError(
 *               "Typed array doesn't contain the right amount" of data");
 *           return Maybe<std::pair<size_t, size_t>>();
 *         }
 *         return Some(std::make_pair(offset, std::size(data)));
 *       });
 *       if (buffer.isNothing()) {
 *         return;
 *       }
 *
 *  4) Processing the data in some other way
 *
 *     This is the API for when none of the APIs above are appropriate for your
 *     usecase. As these are the most dangerous APIs you really should check
 *     first if you can't use one of the safer alternatives above. The reason
 *     these APIs are more dangerous is because they give access to the typed
 *     array's data directly, and the location of that data can be changed by
 *     the JS GC (due to generational and/or compacting collection). There are
 *     two APIs for processing data:
 *
 *       template <typename Processor>
 *       [[nodiscard]] ProcessReturnType<Processor> ProcessData(
 *           Processor&& aProcessor) const;
 *
 *       template <typename Processor>
 *       [[nodiscard]] ProcessReturnType<Processor> ProcessFixedData(
 *           Processor&& aProcessor) const;
 *
 *     ProcessData will call the lambda with as arguments a |const Span<…>&|
 *     wrapping the data pointer and length for the data in the typed array, and
 *     a |JS::AutoCheckCannotGC&&|. The lambda will execute in a context where
 *     GC is not allowed.
 *
 *     ProcessFixedData will call the lambda with as argument |const Span<…>&|.
 *     For small typed arrays where the data is stored inline in the typed
 *     array, and thus could move during GC, then the data will be copied into a
 *     fresh out-of-line allocation before the lambda is called.
 *
 *     The signature of the lambdas for ProcessData and ProcessFixedData differ
 *     in that the ProcessData lambda will additionally be passed a nogc token
 *     to prevent GC from occurring and invalidating the data. If the processing
 *     you need to do in the lambda can't be proven to not GC then you should
 *     probably use ProcessFixedData instead. There are cases where you need to
 *     do something that can cause a GC but you don't actually need to access
 *     the data anymore. A good example would be throwing a JS exception and
 *     return. For those very specific cases you can call nogc.reset() before
 *     doing anything that causes a GC. Be extra careful to not access the data
 *     after you called nogc.reset().
 *
 *     Extra care must be taken to not let the Span<…> or any pointers derived
 *     from it escape the lambda, as the position in memory of the typed array's
 *     data can change again once we leave the lambda (invalidating the
 *     pointers). The lambda passed to ProcessData is not allowed to do anything
 *     that will trigger a GC, and the GC rooting hazard analysis will enforce
 *     that.
 *
 *     Both ProcessData and ProcessFixedData will pin the typed array's length
 *     while calling the lambda, to block any changes to the length of the data.
 *     Note that this means that the lambda itself isn't allowed to change the
 *     length of the typed array's data. Any attempt to change the length will
 *     throw a JS exception.
 *
 *     The return type of ProcessData and ProcessFixedData depends on the return
 *     type of the lambda, as they forward the return value from the lambda to
 *     the caller of ProcessData or ProcessFixedData.
 *
 *     Examples:
 *
 *       aUint32Array.ProcessData([] (const Span<uint32_t>& aData,
 *                                    JS::AutoCheckCannotGC&&) {
 *         for (size_t i = 0; i < aData.Length(); ++i) {
 *           aData[i] = i;
 *         }
 *       });
 *
 *       aUint32Array.ProcessData([&] (const Span<uint32_t>& aData,
 *                                     JS::AutoCheckCannotGC&& nogc) {
 *         for (size_t i = 0; i < aData.Length(); ++i) {
 *           if (!aData[i]) {
 *             nogc.reset();
 *             ThrowJSException("Data shouldn't contain 0");
 *             return;
 *           };
 *           DoSomething(aData[i]);
 *         }
 *       });
 *
 *       uint8_t max = aUint8Array.ProcessData([] (const Span<uint8_t>& aData) {
 *         return std::max_element(aData.cbegin(), aData.cend());
 *       });
 *
 *       aUint8Array.ProcessFixedData([] (const Span<uint8_t>& aData) {
 *         return CallFunctionThatMightGC(aData);
 *       });
 *
 *
 * In addition to the above APIs we provide helpers to call them on the typed
 * array members of WebIDL unions. We have helpers for the 4 different sets of
 * APIs above. The return value of the helpers depends on whether the union can
 * contain a type other than a typed array. If the union can't contain a type
 * other than a typed array then the return type is simply the type returned by
 * the corresponding API above. If the union can contain a type other than a
 * typed array then the return type of the helper is a Maybe<…> wrapping the
 * actual return type, with Nothing() signifying that the union contained a
 * non-typed array value.
 *
 *     template <typename ToType, typename T>
 *     [[nodiscard]] auto AppendTypedArrayDataTo(const T& aUnion,
 *                                               ToType& aResult);
 *
 *     template <typename ToType, typename T>
 *     [[nodiscard]] auto CreateFromTypedArrayData(const T& aUnion);
 *
 *     template <typename T, typename Processor>
 *     [[nodiscard]] auto ProcessTypedArrays(
 *         const T& aUnion, Processor&& aProcessor);
 *
 *     template <typename T, typename Processor>
 *     [[nodiscard]] auto ProcessTypedArraysFixed(const T& aUnion,
 *                                                Processor&& aProcessor);
 *
 */

template <class ArrayT>
struct TypedArray_base : public SpiderMonkeyInterfaceObjectStorage,
                         AllTypedArraysBase {
  using element_type = typename ArrayT::DataType;

  TypedArray_base() = default;
  TypedArray_base(TypedArray_base&& aOther) = default;

 public:
  inline bool Init(JSObject* obj) {
    MOZ_ASSERT(!inited());
    mImplObj = mWrappedObj = ArrayT::unwrap(obj).asObject();
    return inited();
  }

  // About shared memory:
  //
  // Any DOM TypedArray as well as any DOM ArrayBufferView can map the
  // memory of either a JS ArrayBuffer or a JS SharedArrayBuffer.
  //
  // Code that elects to allow views that map shared memory to be used
  // -- ie, code that "opts in to shared memory" -- should generally
  // not access the raw data buffer with standard C++ mechanisms as
  // that creates the possibility of C++ data races, which is
  // undefined behavior.  The JS engine will eventually export (bug
  // 1225033) a suite of methods that avoid undefined behavior.
  //
  // Callers of Obj() that do not opt in to shared memory can produce
  // better diagnostics by checking whether the JSObject in fact maps
  // shared memory and throwing an error if it does.  However, it is
  // safe to use the value of Obj() without such checks.
  //
  // The DOM TypedArray abstraction prevents the underlying buffer object
  // from being accessed directly, but JS_GetArrayBufferViewBuffer(Obj())
  // will obtain the buffer object.  Code that calls that function must
  // not assume the returned buffer is an ArrayBuffer.  That is guarded
  // against by an out parameter on that call that communicates the
  // sharedness of the buffer.
  //
  // Finally, note that the buffer memory of a SharedArrayBuffer is
  // not detachable.

 public:
  /**
   * Helper functions to append a copy of this typed array's data to a
   * container. Returns false if the allocation for copying the data fails.
   *
   * aCalculator is an optional argument to which one can pass a lambda
   * expression that will calculate the offset and length of the data to copy
   * out of the typed array. aCalculator will be called with one argument of
   * type size_t set to the length of the data in the typed array. It is allowed
   * to return a std::pair<size_t, size_t> or a Maybe<std::pair<size_t, size_t>>
   * containing the offset and the length of the subset of the data that we
   * should copy. If the calculation can fail then aCalculator should return a
   * Maybe<std::pair<size_t, size_t>>, if .isNothing() returns true for the
   * return value then AppendDataTo will return false and the data won't be
   * copied.
   */

  template <typename... Calculator>
  [[nodiscard]] bool AppendDataTo(nsCString& aResult,
                                  Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "AppendDataTo takes at most one aCalculator");

    return ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          return aResult.Append(aData, fallible);
        },
        std::forward<Calculator>(aCalculator)...);
  }

  template <typename T, typename... Calculator>
  [[nodiscard]] bool AppendDataTo(nsTArray<T>& aResult,
                                  Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "AppendDataTo takes at most one aCalculator");

    return ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          return aResult.AppendElements(aData, fallible);
        },
        std::forward<Calculator>(aCalculator)...);
  }

  template <typename T, typename... Calculator>
  [[nodiscard]] bool AppendDataTo(FallibleTArray<T>& aResult,
                                  Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "AppendDataTo takes at most one aCalculator");

    return ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          return aResult.AppendElements(aData, fallible);
        },
        std::forward<Calculator>(aCalculator)...);
  }

  template <typename T, typename... Calculator>
  [[nodiscard]] bool AppendDataTo(Vector<T>& aResult,
                                  Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "AppendDataTo takes at most one aCalculator");

    return ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          return aResult.append(aData.Elements(), aData.Length());
        },
        std::forward<Calculator>(aCalculator)...);
  }

  /**
   * Helper functions to copy this typed array's data to a container. This will
   * clear any existing data in the container.
   *
   * See the comments for AppendDataTo for information on the aCalculator
   * argument.
   */

  template <typename T, size_t N, typename... Calculator>
  [[nodiscard]] bool CopyDataTo(T (&aResult)[N],
                                Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "CopyDataTo takes at most one aCalculator");

    return ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          if (aData.Length() != N) {
            return false;
          }
          for (size_t i = 0; i < N; ++i) {
            aResult[i] = aData[i];
          }
          return true;
        },
        std::forward<Calculator>(aCalculator)...);
  }

  template <typename T, size_t N, typename... Calculator>
  [[nodiscard]] bool CopyDataTo(std::array<T, N>* const aResult,
                                Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "CopyDataTo takes at most one aCalculator");

    return ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          if (aData.Length() != N) {
            return false;
          }
          for (size_t i = 0; i < N; ++i) {
            (*aResult).at(i) = aData[i];
          }
          return true;
        },
        std::forward<Calculator>(aCalculator)...);
  }

  /**
   * Helper functions to copy this typed array's data to a newly created
   * container. Returns Nothing() if creating the container with the right size
   * fails.
   *
   * See the comments for AppendDataTo for information on the aCalculator
   * argument.
   */

  template <typename T, typename... Calculator,
            typename IsVector =
                std::enable_if_t<std::is_same_v<Vector<element_type>, T>>>
  [[nodiscard]] Maybe<Vector<element_type>> CreateFromData(
      Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "CreateFromData takes at most one aCalculator");

    return CreateFromDataHelper<T>(
        [&](const Span<const element_type>& aData,
            Vector<element_type>& aResult) {
          if (!aResult.initCapacity(aData.Length())) {
            return false;
          }
          aResult.infallibleAppend(aData.Elements(), aData.Length());
          return true;
        },
        std::forward<Calculator>(aCalculator)...);
  }

  template <typename T, typename... Calculator,
            typename IsUniquePtr =
                std::enable_if_t<std::is_same_v<T, UniquePtr<element_type[]>>>>
  [[nodiscard]] Maybe<UniquePtr<element_type[]>> CreateFromData(
      Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "CreateFromData takes at most one aCalculator");

    return CreateFromDataHelper<T>(
        [&](const Span<const element_type>& aData,
            UniquePtr<element_type[]>& aResult) {
          aResult =
              MakeUniqueForOverwriteFallible<element_type[]>(aData.Length());
          if (!aResult.get()) {
            return false;
          }
          memcpy(aResult.get(), aData.Elements(), aData.LengthBytes());
          return true;
        },
        std::forward<Calculator>(aCalculator)...);
  }

  template <typename T, typename... Calculator,
            typename IsBuffer =
                std::enable_if_t<std::is_same_v<T, Buffer<element_type>>>>
  [[nodiscard]] Maybe<Buffer<element_type>> CreateFromData(
      Calculator&&... aCalculator) const {
    static_assert(sizeof...(aCalculator) <= 1,
                  "CreateFromData takes at most one aCalculator");

    return CreateFromDataHelper<T>(
        [&](const Span<const element_type>& aData,
            Buffer<element_type>& aResult) {
          Maybe<Buffer<element_type>> buffer =
              Buffer<element_type>::CopyFrom(aData);
          if (buffer.isNothing()) {
            return false;
          }
          aResult = buffer.extract();
          return true;
        },
        std::forward<Calculator>(aCalculator)...);
  }

 private:
  template <typename Processor, typename R = decltype(std::declval<Processor>()(
                                    std::declval<Span<element_type>>(),
                                    std::declval<JS::AutoCheckCannotGC>()))>
  using ProcessNoGCReturnType = R;

  template <typename Processor>
  [[nodiscard]] static inline ProcessNoGCReturnType<Processor>
  CallProcessorNoGC(const Span<element_type>& aData, Processor&& aProcessor,
                    JS::AutoCheckCannotGC&& nogc) {
    MOZ_ASSERT(
        aData.IsEmpty() || aData.Elements(),
        "We expect a non-null data pointer for typed arrays that aren't empty");

    return aProcessor(aData, std::move(nogc));
  }

  template <typename Processor, typename R = decltype(std::declval<Processor>()(
                                    std::declval<Span<element_type>>()))>
  using ProcessReturnType = R;

  template <typename Processor>
  [[nodiscard]] static inline ProcessReturnType<Processor> CallProcessor(
      const Span<element_type>& aData, Processor&& aProcessor) {
    MOZ_ASSERT(
        aData.IsEmpty() || aData.Elements(),
        "We expect a non-null data pointer for typed arrays that aren't empty");

    return aProcessor(aData);
  }

  struct MOZ_STACK_CLASS LengthPinner {
    explicit LengthPinner(const TypedArray_base* aTypedArray)
        : mTypedArray(aTypedArray),
          mWasPinned(
              !JS::PinArrayBufferOrViewLength(aTypedArray->Obj(), true)) {}
    ~LengthPinner() {
      if (!mWasPinned) {
        JS::PinArrayBufferOrViewLength(mTypedArray->Obj(), false);
      }
    }

   private:
    const TypedArray_base* mTypedArray;
    bool mWasPinned;
  };

  template <typename Processor, typename Calculator>
  [[nodiscard]] bool ProcessDataHelper(
      Processor&& aProcessor, Calculator&& aCalculateOffsetAndLength) const {
    LengthPinner pinner(this);

    JS::AutoCheckCannotGC nogc;  // `data` is GC-sensitive.
    Span<element_type> data = GetCurrentData();
    const auto& offsetAndLength = aCalculateOffsetAndLength(data.Length());
    size_t offset, length;
    if constexpr (std::is_convertible_v<decltype(offsetAndLength),
                                        std::pair<size_t, size_t>>) {
      std::tie(offset, length) = offsetAndLength;
    } else {
      if (offsetAndLength.isNothing()) {
        return false;
      }
      std::tie(offset, length) = offsetAndLength.value();
    }

    return CallProcessorNoGC(data.Subspan(offset, length),
                             std::forward<Processor>(aProcessor),
                             std::move(nogc));
  }

  template <bool AllowLargeTypedArrays = false, typename Processor>
  [[nodiscard]] ProcessNoGCReturnType<Processor> ProcessDataHelper(
      Processor&& aProcessor) const {
    LengthPinner pinner(this);
    // The data from GetCurrentData() is GC sensitive.
    JS::AutoCheckCannotGC nogc;
    return CallProcessorNoGC(GetCurrentData<AllowLargeTypedArrays>(),
                             std::forward<Processor>(aProcessor),
                             std::move(nogc));
  }

 public:
  template <bool AllowLargeTypedArrays = false, typename Processor>
  [[nodiscard]] ProcessNoGCReturnType<Processor> ProcessData(
      Processor&& aProcessor) const {
    return ProcessDataHelper<AllowLargeTypedArrays>(
        std::forward<Processor>(aProcessor));
  }

  template <typename Processor>
  [[nodiscard]] ProcessReturnType<Processor> ProcessFixedData(
      Processor&& aProcessor) const {
    mozilla::dom::AutoJSAPI jsapi;
    if (!jsapi.Init(mImplObj)) {
#if defined(EARLY_BETA_OR_EARLIER)
      if constexpr (std::is_same_v<ArrayT, JS::ArrayBufferView>) {
        if (!mImplObj) {
          MOZ_CRASH("Null mImplObj");
        }
        if (!xpc::NativeGlobal(mImplObj)) {
          MOZ_CRASH("Null xpc::NativeGlobal(mImplObj)");
        }
        if (!xpc::NativeGlobal(mImplObj)->GetGlobalJSObject()) {
          MOZ_CRASH("Null xpc::NativeGlobal(mImplObj)->GetGlobalJSObject()");
        }
      }
#endif
      MOZ_CRASH("Failed to get JSContext");
    }
#if defined(EARLY_BETA_OR_EARLIER)
    if constexpr (std::is_same_v<ArrayT, JS::ArrayBufferView>) {
      JS::Rooted<JSObject*> view(jsapi.cx(),
                                 js::UnwrapArrayBufferView(mImplObj));
      if (!view) {
        if (JSObject* unwrapped = js::CheckedUnwrapStatic(mImplObj)) {
          if (!js::UnwrapArrayBufferView(unwrapped)) {
            MOZ_CRASH(
                "Null "
                "js::UnwrapArrayBufferView(js::CheckedUnwrapStatic(mImplObj))");
          }
          view = unwrapped;
        } else {
          MOZ_CRASH("Null js::CheckedUnwrapStatic(mImplObj)");
        }
      }
    }
#endif
    JS::AutoBrittleMode abm(jsapi.cx());
    if (!JS::EnsureNonInlineArrayBufferOrView(jsapi.cx(), mImplObj)) {
      MOZ_CRASH("small oom when moving inline data out-of-line");
    }
    LengthPinner pinner(this);

    return CallProcessor(GetCurrentData(), std::forward<Processor>(aProcessor));
  }

 private:
  template <bool AllowLargeTypedArrays = false>
  Span<element_type> GetCurrentData() const {
    MOZ_ASSERT(inited());
    MOZ_RELEASE_ASSERT(
        !ArrayT::fromObject(mImplObj).isResizable(),
        "Bindings must have checked ArrayBuffer{View} is non-resizable");
    MOZ_RELEASE_ASSERT(
        !ArrayT::fromObject(mImplObj).isImmutable(),
        "Bindings must have checked ArrayBuffer{View} is mutable");

    // Intentionally return a pointer and length that escape from a nogc region.
    // Private so it can only be used in very limited situations.
    JS::AutoCheckCannotGC nogc;
    bool shared;
    Span<element_type> span =
        ArrayT::fromObject(mImplObj).getData(&shared, nogc);
    if constexpr (!AllowLargeTypedArrays) {
      MOZ_RELEASE_ASSERT(span.Length() <= INT32_MAX,
                         "Bindings must have checked ArrayBuffer{View} length");
    }
    return span;
  }

  template <typename T, typename F, typename... Calculator>
  [[nodiscard]] Maybe<T> CreateFromDataHelper(
      F&& aCreator, Calculator&&... aCalculator) const {
    Maybe<T> result;
    bool ok = ProcessDataHelper(
        [&](const Span<const element_type>& aData, JS::AutoCheckCannotGC&&) {
          result.emplace();
          return aCreator(aData, *result);
        },
        std::forward<Calculator>(aCalculator)...);

    if (!ok) {
      return Nothing();
    }

    return result;
  }

  TypedArray_base(const TypedArray_base&) = delete;
};

template <class ArrayT>
struct TypedArray : public TypedArray_base<ArrayT> {
  using Base = TypedArray_base<ArrayT>;
  using element_type = typename Base::element_type;

  TypedArray() = default;

  TypedArray(TypedArray&& aOther) = default;

  static inline JSObject* Create(JSContext* cx, nsWrapperCache* creator,
                                 size_t length, ErrorResult& error) {
    return CreateCommon(cx, creator, length, error).asObject();
  }

  static inline JSObject* Create(JSContext* cx, size_t length,
                                 ErrorResult& error) {
    return CreateCommon(cx, length, error).asObject();
  }

  static inline JSObject* Create(JSContext* cx, nsWrapperCache* creator,
                                 Span<const element_type> data,
                                 ErrorResult& error) {
    ArrayT array = CreateCommon(cx, creator, data.Length(), error);
    if (!error.Failed() && !data.IsEmpty()) {
      CopyFrom(cx, data, array);
    }
    return array.asObject();
  }

  static inline JSObject* Create(JSContext* cx, Span<const element_type> data,
                                 ErrorResult& error) {
    ArrayT array = CreateCommon(cx, data.Length(), error);
    if (!error.Failed() && !data.IsEmpty()) {
      CopyFrom(cx, data, array);
    }
    return array.asObject();
  }

 private:
  template <typename>
  friend class TypedArrayCreator;

  static inline ArrayT CreateCommon(JSContext* cx, nsWrapperCache* creator,
                                    size_t length, ErrorResult& error) {
    JS::Rooted<JSObject*> creatorWrapper(cx);
    Maybe<JSAutoRealm> ar;
    if (creator && (creatorWrapper = creator->GetWrapperPreserveColor())) {
      ar.emplace(cx, creatorWrapper);
    }

    return CreateCommon(cx, length, error);
  }
  static inline ArrayT CreateCommon(JSContext* cx, size_t length,
                                    ErrorResult& error) {
    error.MightThrowJSException();
    ArrayT array = CreateCommon(cx, length);
    if (array) {
      return array;
    }
    error.StealExceptionFromJSContext(cx);
    return ArrayT::fromObject(nullptr);
  }
  // NOTE: this leaves any exceptions on the JSContext, and the caller is
  //       required to deal with them.
  static inline ArrayT CreateCommon(JSContext* cx, size_t length) {
    return ArrayT::create(cx, length);
  }
  static inline void CopyFrom(JSContext* cx,
                              const Span<const element_type>& data,
                              ArrayT& dest) {
    JS::AutoCheckCannotGC nogc;
    bool isShared;
    mozilla::Span<element_type> span = dest.getData(&isShared, nogc);
    MOZ_ASSERT(span.size() == data.size(),
               "Didn't create a large enough typed array object?");
    // Data will not be shared, until a construction protocol exists
    // for constructing shared data.
    MOZ_ASSERT(!isShared);
    memcpy(span.Elements(), data.Elements(), data.LengthBytes());
  }

  TypedArray(const TypedArray&) = delete;
};

template <JS::Scalar::Type GetViewType(JSObject*)>
struct ArrayBufferView_base : public TypedArray_base<JS::ArrayBufferView> {
 private:
  using Base = TypedArray_base<JS::ArrayBufferView>;

 public:
  ArrayBufferView_base() : Base(), mType(JS::Scalar::MaxTypedArrayViewType) {}

  ArrayBufferView_base(ArrayBufferView_base&& aOther)
      : Base(std::move(aOther)), mType(aOther.mType) {
    aOther.mType = JS::Scalar::MaxTypedArrayViewType;
  }

 private:
  JS::Scalar::Type mType;

 public:
  inline bool Init(JSObject* obj) {
    if (!Base::Init(obj)) {
      return false;
    }

    mType = GetViewType(this->Obj());
    return true;
  }

  inline JS::Scalar::Type Type() const {
    MOZ_ASSERT(this->inited());
    return mType;
  }
};

using Int8Array = TypedArray<JS::Int8Array>;
using Uint8Array = TypedArray<JS::Uint8Array>;
using Uint8ClampedArray = TypedArray<JS::Uint8ClampedArray>;
using Int16Array = TypedArray<JS::Int16Array>;
using Uint16Array = TypedArray<JS::Uint16Array>;
using Int32Array = TypedArray<JS::Int32Array>;
using Uint32Array = TypedArray<JS::Uint32Array>;
using Float32Array = TypedArray<JS::Float32Array>;
using Float64Array = TypedArray<JS::Float64Array>;
using BigInt64Array = TypedArray<JS::BigInt64Array>;
using BigUint64Array = TypedArray<JS::BigUint64Array>;
using ArrayBufferView = ArrayBufferView_base<JS_GetArrayBufferViewType>;
using ArrayBuffer = TypedArray<JS::ArrayBuffer>;

// A class for converting an nsTArray to a TypedArray
// Note: A TypedArrayCreator must not outlive the nsTArray it was created from.
//       So this is best used to pass from things that understand nsTArray to
//       things that understand TypedArray, as with ToJSValue.
template <typename TypedArrayType>
class MOZ_STACK_CLASS TypedArrayCreator {
  using ValuesType = typename TypedArrayType::element_type;
  using ArrayType = nsTArray<ValuesType>;

 public:
  explicit TypedArrayCreator(const ArrayType& aArray) : mValues(aArray) {}
  explicit TypedArrayCreator(const nsCString& aString) : mValues(aString) {}

  // NOTE: this leaves any exceptions on the JSContext, and the caller is
  //       required to deal with them.
  JSObject* Create(JSContext* aCx) const {
    auto array = TypedArrayType::CreateCommon(aCx, mValues.Length());
    if (array) {
      TypedArrayType::CopyFrom(aCx, mValues, array);
    }
    return array.asObject();
  }

 private:
  Span<const ValuesType> mValues;
};

namespace binding_detail {

template <typename Union, typename UnionMemberType, typename = int>
struct ApplyToTypedArray;

#define APPLY_IMPL(type)                                                       \
  template <typename Union>                                                    \
  struct ApplyToTypedArray<Union, type, decltype((void)&Union::Is##type, 0)> { \
    /* Return type of calling the lambda with a TypedArray 'type'.         */  \
    template <typename F>                                                      \
    using FunReturnType = decltype(std::declval<F>()(std::declval<type>()));   \
                                                                               \
    /* Whether the return type of calling the lambda with a TypedArray     */  \
    /* 'type' is void. */                                                      \
    template <typename F>                                                      \
    static constexpr bool FunReturnsVoid =                                     \
        std::is_same_v<FunReturnType<F>, void>;                                \
                                                                               \
    /* The return type of calling Apply with a union that has 'type' as    */  \
    /* one of its union member types depends on the return type of         */  \
    /* calling the lambda. This return type will be bool if the lambda     */  \
    /* returns void, or it will be a Maybe<…> with the inner type being    */  \
    /* the actual return type of calling the lambda. If the union          */  \
    /* contains a value of the right type, then calling Apply will return  */  \
    /* either 'true', or 'Some(…)' containing the return value of calling  */  \
    /* the lambda. If the union does not contain a value of the right      */  \
    /* type, then calling Apply will return either 'false', or             */  \
    /* 'Nothing()'.                                                        */  \
    template <typename F>                                                      \
    using ApplyReturnType =                                                    \
        std::conditional_t<FunReturnsVoid<F>, bool, Maybe<FunReturnType<F>>>;  \
                                                                               \
   public:                                                                     \
    template <typename F>                                                      \
    static ApplyReturnType<F> Apply(const Union& aUnion, F&& aFun) {           \
      if (!aUnion.Is##type()) {                                                \
        return ApplyReturnType<F>(); /* false or Nothing() */                  \
      }                                                                        \
      if constexpr (FunReturnsVoid<F>) {                                       \
        std::forward<F>(aFun)(aUnion.GetAs##type());                           \
        return true;                                                           \
      } else {                                                                 \
        return Some(std::forward<F>(aFun)(aUnion.GetAs##type()));              \
      }                                                                        \
    }                                                                          \
  };

APPLY_IMPL(Int8Array)
APPLY_IMPL(Uint8Array)
APPLY_IMPL(Uint8ClampedArray)
APPLY_IMPL(Int16Array)
APPLY_IMPL(Uint16Array)
APPLY_IMPL(Int32Array)
APPLY_IMPL(Uint32Array)
APPLY_IMPL(Float32Array)
APPLY_IMPL(Float64Array)
APPLY_IMPL(BigInt64Array)
APPLY_IMPL(BigUint64Array)
APPLY_IMPL(ArrayBufferView)
APPLY_IMPL(ArrayBuffer)

#undef APPLY_IMPL

// The binding code generate creates an alias of this type for every WebIDL
// union that contains a typed array type, with the right value for H (which
// will be true if there are non-typedarray types in the union).
template <typename T, bool H, typename FirstUnionMember,
          typename... UnionMembers>
struct ApplyToTypedArraysHelper {
  static constexpr bool HasNonTypedArrayMembers = H;
  template <typename Fun>
  static auto Apply(const T& aUnion, Fun&& aFun) {
    auto result = ApplyToTypedArray<T, FirstUnionMember>::Apply(
        aUnion, std::forward<Fun>(aFun));
    if constexpr (sizeof...(UnionMembers) == 0) {
      return result;
    } else {
      if (result) {
        return result;
      } else {
        return ApplyToTypedArraysHelper<T, H, UnionMembers...>::template Apply<
            Fun>(aUnion, std::forward<Fun>(aFun));
      }
    }
  }
};

template <typename T, typename Fun>
auto ApplyToTypedArrays(const T& aUnion, Fun&& aFun) {
  using ApplyToTypedArrays = typename T::ApplyToTypedArrays;

  auto result =
      ApplyToTypedArrays::template Apply<Fun>(aUnion, std::forward<Fun>(aFun));
  if constexpr (ApplyToTypedArrays::HasNonTypedArrayMembers) {
    return result;
  } else {
    MOZ_ASSERT(result, "Didn't expect union members other than typed arrays");

    if constexpr (std::is_same_v<std::remove_cv_t<
                                     std::remove_reference_t<decltype(result)>>,
                                 bool>) {
      return;
    } else {
      return result.extract();
    }
  }
}

}  // namespace binding_detail

template <typename T, typename ToType,
          std::enable_if_t<is_dom_union_with_typedarray_members<T>, int> = 0>
[[nodiscard]] auto AppendTypedArrayDataTo(const T& aUnion, ToType& aResult) {
  return binding_detail::ApplyToTypedArrays(
      aUnion, [&](const auto& aTypedArray) {
        return aTypedArray.AppendDataTo(aResult);
      });
}

template <typename ToType, typename T,
          std::enable_if_t<is_dom_union_with_typedarray_members<T>, int> = 0>
[[nodiscard]] auto CreateFromTypedArrayData(const T& aUnion) {
  return binding_detail::ApplyToTypedArrays(
      aUnion, [&](const auto& aTypedArray) {
        return aTypedArray.template CreateFromData<ToType>();
      });
}

template <typename T, typename Processor,
          std::enable_if_t<is_dom_union_with_typedarray_members<T>, int> = 0>
[[nodiscard]] auto ProcessTypedArrays(const T& aUnion, Processor&& aProcessor) {
  return binding_detail::ApplyToTypedArrays(
      aUnion, [&](const auto& aTypedArray) {
        return aTypedArray.ProcessData(std::forward<Processor>(aProcessor));
      });
}

template <typename T, typename Processor,
          std::enable_if_t<is_dom_union_with_typedarray_members<T>, int> = 0>
[[nodiscard]] auto ProcessTypedArraysFixed(const T& aUnion,
                                           Processor&& aProcessor) {
  return binding_detail::ApplyToTypedArrays(
      aUnion, [&](const auto& aTypedArray) {
        return aTypedArray.ProcessFixedData(
            std::forward<Processor>(aProcessor));
      });
}

}  // namespace mozilla::dom

#endif /* mozilla_dom_TypedArray_h */