PR #9

This document is a preview of merging PR #9 as commit 3524951ab5df49970a000b8acb7dc3b42ede57da.

Do not reference it as authoritative in any way. Instead, see the living specification at https://github.com/tc39/proposal-typedarray-findwithin.

Stage 1 Draft / March 11, 2026

TypedArray.prototype.indexOfSequence / lastIndexOfSequence

1 TypedArray Objects

1.1 The %TypedArray% Intrinsic Object

1.1.1 Abstract Operations for TypedArray Objects

1.1.1.1 ValidateIntegralNumber ( value, default )

The abstract operation ValidateIntegralNumber takes arguments value (an ECMAScript language value) and default (an integer) and returns either a normal completion containing an integer or a throw completion. It validates that value is either undefined or an integral Number, returning the corresponding mathematical integer. If value is undefined, the default is returned. It performs the following steps when called:

  1. If value is undefined, return default.
  2. If value is not a Number, throw a TypeError exception.
  3. If value is not an integral Number, throw a RangeError exception.
  4. Return ℝ(value).

1.1.1.2 TypedArraySubsequenceFromTypedArray ( haystack, needle )

The abstract operation TypedArraySubsequenceFromTypedArray takes arguments haystack (a TypedArray) and needle (a TypedArray) and returns either a normal completion containing either a List of Numbers, a List of BigInts, or not-found, or a throw completion. It produces a List of element values by reading directly from needle's underlying buffer. If haystack and needle have incompatible content types (Number vs BigInt), not-found is returned. It performs the following steps when called:

  1. Assert: haystack is an Object that has a [[TypedArrayName]] internal slot.
  2. Let needleRecord be MakeTypedArrayWithBufferWitnessRecord(needle, seq-cst).
  3. If IsTypedArrayOutOfBounds(needleRecord) is true, throw a TypeError exception.
  4. Let needleLength be TypedArrayLength(needleRecord).
  5. If haystack.[[ContentType]] is not needle.[[ContentType]], return not-found.
  6. Let needleBuffer be needle.[[ViewedArrayBuffer]].
  7. Let needleType be TypedArrayElementType(needle).
  8. Let needleElementSize be TypedArrayElementSize(needle).
  9. Let needleByteOffset be needle.[[ByteOffset]].
  10. Let result be a new empty List.
  11. Let k be 0.
  12. Repeat, while k < needleLength,
    1. Let byteIndex be (k × needleElementSize) + needleByteOffset.
    2. Let value be GetValueFromBuffer(needleBuffer, byteIndex, needleType, true, unordered).
    3. Append value to result.
    4. Set k to k + 1.
  13. Return result.
 Note 1

This operation reads the needle's elements directly from its underlying buffer without invoking user code. The @@iterator method of needle is not called. This is consistent with how %TypedArray%.prototype.set handles TypedArray sources via SetTypedArrayFromTypedArray.

 Note 2

When needle is backed by a SharedArrayBuffer, another agent may modify the needle's elements during the read. Each element is read individually via GetValueFromBuffer with unordered ordering. Users who need stronger guarantees must synchronize access externally. See issue #8 for discussion.

1.1.1.3 TypedArraySearchSubsequence ( typedArray, haystackLength, needle, direction, position )

The abstract operation TypedArraySearchSubsequence takes arguments typedArray (a TypedArray), haystackLength (a non-negative integer), needle (either a List of Numbers or a List of BigInts), direction (first or last), and position (a non-negative integer) and returns an integral Number. It searches for an occurrence of the subsequence needle within the first haystackLength elements of typedArray, returning the starting index of the match or -1𝔽 if not found. The direction parameter controls whether the first or last match is returned. When direction is first, only matches starting at index position or later are considered. When direction is last, only matches starting at index position or earlier are considered. It performs the following steps when called:

  1. Let needleLength be the number of elements in needle.
  2. If needleLength is 0, return 𝔽(position).
  3. If direction is first, then
    1. If position + needleLength > haystackLength, return -1𝔽.
    2. Let k be position.
    3. Let limit be haystackLength - needleLength.
    4. Repeat, while k ≤ limit,
      1. Let matched be true.
      2. Let j be 0.
      3. Repeat, while j < needleLength and matched is true,
        1. Let Pk be ! ToString(𝔽(k + j)).
        2. Let haystackValue be ! Get(typedArray, Pk).
        3. If SameValueZero(haystackValue, needle[j]) is false, set matched to false.
        4. Set j to j + 1.
      4. If matched is true, return 𝔽(k).
      5. Set k to k + 1.
    5. Return -1𝔽.
  4. Else,
    1. If needleLength > haystackLength, return -1𝔽.
    2. Let k be min(position, haystackLength - needleLength).
    3. Repeat, while k ≥ 0,
      1. Let matched be true.
      2. Let j be 0.
      3. Repeat, while j < needleLength and matched is true,
        1. Let Pk be ! ToString(𝔽(k + j)).
        2. Let haystackValue be ! Get(typedArray, Pk).
        3. If SameValueZero(haystackValue, needle[j]) is false, set matched to false.
        4. Set j to j + 1.
      4. If matched is true, return 𝔽(k).
      5. Set k to k - 1.
    4. Return -1𝔽.
 Note

The elements of typedArray (the haystack) are not snapshotted, consistent with how %TypedArray%.prototype.indexOf and %TypedArray%.prototype.lastIndexOf scan the haystack directly. When typedArray is backed by a SharedArrayBuffer, another agent may modify elements of typedArray during the search.

 Editor's Note

The algorithm above describes a naive linear search for clarity. Implementations may use any technique to search for the subsequence, such as Boyer-Moore, two-way, or other matching algorithms, provided the observable result is equivalent.

1.1.2 Properties of the %TypedArray% Prototype Object

1.1.2.1 %TypedArray%.prototype.indexOfSequence ( needle [ , position ] )

This method searches for the first occurrence of the subsequence needle within this TypedArray, starting the search at index position. It performs the following steps when called:

  1. Let typedArray be the this value.
  2. Let taRecord be ? ValidateTypedArray(typedArray, seq-cst).
  3. If needle is not an Object that has a [[TypedArrayName]] internal slot, throw a TypeError exception.
  4. Let needleList be ? TypedArraySubsequenceFromTypedArray(typedArray, needle).
  5. If needleList is not-found, return -1𝔽.
  6. Let haystackLength be TypedArrayLength(taRecord).
  7. Let start be ? ValidateIntegralNumber(position, 0).
  8. Let startFrom be the result of clamping start between 0 and haystackLength.
  9. Return TypedArraySearchSubsequence(typedArray, haystackLength, needleList, first, startFrom).

This method is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

1.1.2.2 %TypedArray%.prototype.lastIndexOfSequence ( needle [ , position ] )

This method searches for the last occurrence of the subsequence needle within this TypedArray whose starting index is at or before position. It performs the following steps when called:

  1. Let typedArray be the this value.
  2. Let taRecord be ? ValidateTypedArray(typedArray, seq-cst).
  3. If needle is not an Object that has a [[TypedArrayName]] internal slot, throw a TypeError exception.
  4. Let needleList be ? TypedArraySubsequenceFromTypedArray(typedArray, needle).
  5. If needleList is not-found, return -1𝔽.
  6. Let haystackLength be TypedArrayLength(taRecord).
  7. If haystackLength is 0, then
    1. If needleList is not empty, return -1𝔽.
    2. Return +0𝔽.
  8. Let start be ? ValidateIntegralNumber(position, haystackLength - 1).
  9. Let startFrom be the result of clamping start between 0 and haystackLength - 1.
  10. Return TypedArraySearchSubsequence(typedArray, haystackLength, needleList, last, startFrom).

This method is not generic. The this value must be an object with a [[TypedArrayName]] internal slot.

Copyright & Software License

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.