PR #5

This document is a preview of merging PR #5 as commit 1aee1516b9e06edc0d0a8e474d84235f5c084f84.

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 / February 6, 2026

TypedArray.prototype.search / searchLast / contains

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 NaN, throw a RangeError exception.
  4. If truncate(ℝ(value)) is not ℝ(value), throw a RangeError exception.
  5. Return ℝ(value).

1.1.1.2 SequenceSameValueZeroEqual ( a, b )

The abstract operation SequenceSameValueZeroEqual takes arguments a (either a List of Numbers or a List of BigInts) and b (either a List of Numbers or a List of BigInts) and returns a Boolean. It determines whether two sequences have the same length and element-wise equal values according to the SameValueZero algorithm. It performs the following steps when called:

  1. Let aLength be the number of elements in a.
  2. Let bLength be the number of elements in b.
  3. If aLength is not bLength, return false.
  4. Let i be 0.
  5. Repeat, while i < aLength,
    1. If SameValueZero(a[i], b[i]) is false, return false.
    2. Set i to i + 1.
  6. Return true.

1.1.1.3 ToCompatibleTypedArrayElementList ( O, needle )

The abstract operation ToCompatibleTypedArrayElementList takes arguments O (a TypedArray) and needle (an ECMAScript language value) 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 compatible with O from needle. If needle is an iterable Object, its elements are collected and validated against the element type of O. If any element is not the expected type, not-found is returned. Non-Object values (including Strings, which would otherwise be boxed into iterable String objects) and non-iterable Objects throw a TypeError. It performs the following steps when called:

  1. If needle is not an Object, throw a TypeError exception.
  2. Let iteratorMethod be ? GetMethod(needle, @@iterator).
  3. If iteratorMethod is undefined, throw a TypeError exception.
  4. Let values be ? IteratorToList(? GetIteratorFromMethod(needle, iteratorMethod)).
  5. Let elementType be TypedArrayElementType(O).
  6. Let result be a new empty List.
  7. For each element v of values, do
    1. If IsBigIntElementType(elementType) is true, then
      1. If v is not a BigInt, return not-found.
    2. Else,
      1. If v is not a Number, return not-found.
    3. Append v to result.
  8. Return result.
 Note

All TypedArray needles (whether same-type or different-type) are iterated via their @@iterator method. This ensures that the resulting List is a snapshot of the needle's elements at the time of the call, which is necessary for correctness when the needle is backed by a SharedArrayBuffer (see issue #8).

If the iterable yields values of the wrong type (e.g., BigInts when the haystack is a non-BigInt TypedArray, or Numbers when it is a BigInt TypedArray), not-found is returned rather than throwing. Such values can never SameValueZero-match any element of the haystack, so returning not-found (which callers interpret as -1𝔽) is the correct result without the cost of performing the search. Alternatively we could throw a TypeError in these cases.

 Editor's Note

The acceptance of iterable objects as needles is intended to improve ergonomics (see issue #1). String primitives are not Objects and so fall through to the TypeError in the first step. Non-iterable objects and non-String primitives also throw to avoid silent misuse (see issue #7).

1.1.1.4 TypedArraySearchSubsequence ( O, haystackLength, needle, direction, position )

The abstract operation TypedArraySearchSubsequence takes arguments O (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 O, 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. Return the smallest integer k such that k ≥ position and SequenceSameValueZeroEqual(the List of elements of O from index k to k + needleLength - 1, needle) is true, or -1𝔽 if no such k exists.
  4. Else,
    1. If needleLength > haystackLength, return -1𝔽.
    2. Return the largest integer k such that k ≤ position and k + needleLength ≤ haystackLength and SequenceSameValueZeroEqual(the List of elements of O from index k to k + needleLength - 1, needle) is true, or -1𝔽 if no such k exists.
 Note

The needle is produced by ToCompatibleTypedArrayElementList, which validates that element values are the correct type for O and are a snapshot that cannot be modified during the search. The elements of O (the haystack) are not snapshotted, consistent with how %TypedArray%.prototype.indexOf and %TypedArray%.prototype.lastIndexOf scan the haystack directly. When O is backed by a SharedArrayBuffer, another agent may modify elements of O during the search.

Implementations may use any technique to search for the subsequence, such as naive search, Boyer-Moore, or other matching algorithms, provided the observable result is correct.

1.1.2 Properties of the %TypedArray% Prototype Object

1.1.2.1 %TypedArray%.prototype.search ( 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 O be the this value.
  2. Let taRecord be ? ValidateTypedArray(O, seq-cst).
  3. Let needleList be ? ToCompatibleTypedArrayElementList(O, needle).
  4. If needleList is not-found, return -1𝔽.
  5. Let haystackLength be TypedArrayLength(taRecord).
  6. Let n be ? ValidateIntegralNumber(position, 0).
  7. Let startFrom be the result of clamping n between 0 and haystackLength.
  8. Return TypedArraySearchSubsequence(O, haystackLength, needleList, first, startFrom).

1.1.2.2 %TypedArray%.prototype.searchLast ( 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 O be the this value.
  2. Let taRecord be ? ValidateTypedArray(O, seq-cst).
  3. Let needleList be ? ToCompatibleTypedArrayElementList(O, needle).
  4. If needleList is not-found, return -1𝔽.
  5. Let haystackLength be TypedArrayLength(taRecord).
  6. Let n be ? ValidateIntegralNumber(position, haystackLength - 1).
  7. Let startFrom be the result of clamping n between 0 and haystackLength - 1.
  8. Return TypedArraySearchSubsequence(O, haystackLength, needleList, last, startFrom).

1.1.2.3 %TypedArray%.prototype.contains ( needle [ , position ] )

This method determines whether the subsequence needle exists within this TypedArray, starting the search at index position. It performs the following steps when called:

  1. Let O be the this value.
  2. Let taRecord be ? ValidateTypedArray(O, seq-cst).
  3. Let needleList be ? ToCompatibleTypedArrayElementList(O, needle).
  4. If needleList is not-found, return false.
  5. Let haystackLength be TypedArrayLength(taRecord).
  6. Let n be ? ValidateIntegralNumber(position, 0).
  7. Let startFrom be the result of clamping n between 0 and haystackLength.
  8. Let index be TypedArraySearchSubsequence(O, haystackLength, needleList, first, startFrom).
  9. If index is -1𝔽, return false.
  10. Return true.
 Editor's Note

Whether contains should exist as a separate method or whether users should simply use search(_needle_) !== -1 is an open question. See issue #6 for discussion.

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.