Package io.karatelabs.js

Class IterUtils

java.lang.Object
io.karatelabs.js.IterUtils
public class IterUtils extends Object
Single seam for ECMAScript iteration protocol consumers (for-of, spread, destructuring, Array.from). Built-ins (JsArray/List/JsString/String) use fast paths that bypass the user-facing iterator object; user-defined objects with an @@iterator method go through the spec dance: call obj[@@iterator]() → repeatedly invoke .next() → unpack {value, done}.

The @@iterator string key stands in for Symbol.iterator until real Symbol support lands; built-in iterables expose their iterator factory under that key so user code (and Map/Set when they arrive) can use the same protocol.

  • Field Details

    • SYMBOL_ITERATOR

      public static final String SYMBOL_ITERATOR
      Stand-in for Symbol.iterator until real Symbol support lands.
      See Also:

    • SYMBOL_ITERATOR_METHOD

      public static final io.karatelabs.js.JsCallable SYMBOL_ITERATOR_METHOD
      Shared @@iterator stand-in installed on built-in iterable prototypes (JsArrayPrototype, JsStringPrototype). Per spec, Symbol.iterator lives on the prototype rather than each instance — installing once means arr.hasOwnProperty('@@iterator') === false (correct: it's inherited) and identity holds across instances.

      Reads this from the call context, resolves it via getIterator(java.lang.Object, io.karatelabs.js.Context), and wraps in the spec iterator-result shape. A non-iterable this surfaces as a TypeError from getIterator — same behavior as spec's Array.prototype[Symbol.iterator] when detached from an iterable receiver.

  • Method Details

    • getIterator

      public static JsIterator getIterator(Object source, Context context)
      GetIterator(source) per spec 7.4.1. Throws JsErrorException (TypeError) if source is null/undefined or otherwise not iterable.

    • tryGetIterator

      public static JsIterator tryGetIterator(Object source, Context context)
      Like getIterator(java.lang.Object, io.karatelabs.js.Context) but returns null instead of throwing — for callers that need to gate behavior on iterability without forcing a TypeError.

    • isIterable

      public static boolean isIterable(Object source, Context context)
      True iff source would yield a non-null iterator from tryGetIterator(java.lang.Object, io.karatelabs.js.Context).

    • iteratorFromCallable

      public static JsIterator iteratorFromCallable(io.karatelabs.js.JsCallable factory, ObjectLike receiver, Context context)
      Spec GetIteratorFromMethod: invoke factory with receiver as this (no args) and walk the returned iterator. Used by Set.prototype.{union/difference/...}'s GetKeysIterator step (call the set-like's keys property).

      Lenient on the call result: spec demands an iterator Object with .next(), but built-ins inside karate-js sometimes return raw Lists / JsArrays (e.g. Array.prototype.values() currently returns the underlying list). When the result lacks a .next member, fall through to getIterator(Object, Context) so those shortcuts still iterate correctly. test262 tests like converts-negative-zero.js construct set-likes that return [-0].values() from keys expecting iteration to work.

    • toIteratorObject

      public static io.karatelabs.js.JsObject toIteratorObject(JsIterator iter)
      Wraps a JsIterator as the user-visible iterator object: a JsObject with a next method returning {value, done}. Used by built-in @@iterator factories (JsArray, JsString) to expose internal iteration in spec-compliant shape.