feat: reconcile abort-signal with type-safety and efficiency refactors

Layers the type-safety helpers from copilot/harden-implementation-type-safety
and the perf cleanup from copilot/improve-code-efficiency on top of
claude/add-abort-signal-support-j2Mmx (now the abort-signal feature commits
already on this branch).

- Use isType from @voxpelli/typed-utils for callback/bufferSize/result guards
- Use guardedArrayIncludes for isPartOfArray (lib/type-checks.js)
- Extract isValueObject helper used by isIterable/isAsyncIterable
- Extract normalizeError helper (lib/misc.js); use it in fillQueue catches
  and the fail-fast / capturedErrors path
- Replace [...subIterators, asyncIterator] spread with yieldArrayWithItem
  generator in fillQueue's unordered branch
- Add bounds check to ordered-insertion while loop in fillQueue
- Add @voxpelli/typed-utils as runtime dependency

Author: claude

index.js

@@ -5,8 +5,9 @@
 // TODO: See "iteratorKind" in https://tc39.es/ecma262/#sec-runtime-semantics-forin-div-ofbodyevaluation-lhs-stmt-iterator-lhskind-labelset – see how it loops and validates the returned values
 // TODO: THERE'S ACTUALLY A "throw" method MENTION IN https://tc39.es/ecma262/#sec-generator-function-definitions-runtime-semantics-evaluation: "NOTE: Exceptions from the inner iterator throw method are propagated. Normal completions from an inner throw method are processed similarly to an inner next." THOUGH NOT SURE HOW TO TRIGGER IT IN PRACTICE, SEE yield.spec.js
 
+import { isType } from '@voxpelli/typed-utils';
 import { findLeastTargeted } from './lib/find-least-targeted.js';
-import { arrayDeleteInPlace, makeIterableAsync } from './lib/misc.js';
+import { arrayDeleteInPlace, makeIterableAsync, normalizeError } from './lib/misc.js';
 import { isAsyncIterable, isIterable, isPartOfArray } from './lib/type-checks.js';
 
 /**
@@ -18,6 +19,17 @@ async function * yieldIterable (item) {
   yield * item;
 }
 
+/**
+ * @template T, U
+ * @param {T[]} array
+ * @param {U} item
+ * @returns {Iterable<T | U>}
+ */
+function * yieldArrayWithItem (array, item) {
+  yield * array;
+  yield item;
+}
+
 /**
  * @template T
  * @param {Array<AsyncIterable<T> | Iterable<T> | T[]>} input
@@ -52,8 +64,8 @@ export function bufferedAsyncMap (input, callback, options) {
 
   if (!input) throw new TypeError('Expected input to be provided');
   if (!isAsyncIterable(asyncIterable)) throw new TypeError('Expected asyncIterable to have a Symbol.asyncIterator function');
-  if (typeof callback !== 'function') throw new TypeError('Expected callback to be a function');
-  if (typeof bufferSize !== 'number') throw new TypeError('Expected bufferSize to be a number');
+  if (!isType(callback, 'function')) throw new TypeError('Expected callback to be a function');
+  if (!isType(bufferSize, 'number')) throw new TypeError('Expected bufferSize to be a number');
   if (externalSignal !== undefined && !(externalSignal instanceof AbortSignal)) throw new TypeError('Expected signal to be an AbortSignal');
   if (errorsMode !== 'fail-eventually' && errorsMode !== 'fail-fast') throw new TypeError("Expected errors to be 'fail-eventually' or 'fail-fast'");
 
@@ -146,8 +158,12 @@ export function bufferedAsyncMap (input, callback, options) {
     if (ordered) {
       currentSubIterator = subIterators[0];
     } else {
+      const targets = mainReturnedDone
+        ? subIterators
+        : yieldArrayWithItem(subIterators, asyncIterator);
+
       const iterator = findLeastTargeted(
-        mainReturnedDone ? subIterators : [...subIterators, asyncIterator],
+        targets,
         bufferedPromises,
         promisesToSourceIteratorMap
       );
@@ -159,10 +175,10 @@ export function bufferedAsyncMap (input, callback, options) {
     const bufferPromise = currentSubIterator
       ? Promise.resolve(currentSubIterator.next())
         .catch(err => ({
-          err: err instanceof Error ? err : new Error('Unknown subiterator error'),
+          err: normalizeError(err, 'Unknown subiterator error'),
         }))
         .then(async result => {
-          if (typeof result !== 'object') {
+          if (!isType(result, 'object')) {
             throw new TypeError('Expected an object value');
           }
           if ('err' in result || result.done) {
@@ -184,10 +200,10 @@ export function bufferedAsyncMap (input, callback, options) {
         })
       : Promise.resolve(asyncIterator.next())
         .catch(err => ({
-          err: err instanceof Error ? err : new Error('Unknown iterator error'),
+          err: normalizeError(err, 'Unknown iterator error'),
         }))
         .then(async result => {
-          if (typeof result !== 'object') {
+          if (!isType(result, 'object')) {
             throw new TypeError('Expected an object value');
           }
           if ('err' in result || result.done) {
@@ -221,7 +237,7 @@ export function bufferedAsyncMap (input, callback, options) {
             promiseValue = {
               bufferPromise,
               done: true,
-              err: err instanceof Error ? err : new Error('Unknown callback error'),
+              err: normalizeError(err, 'Unknown callback error'),
               value: undefined,
             };
           }
@@ -234,7 +250,7 @@ export function bufferedAsyncMap (input, callback, options) {
     if (ordered && currentSubIterator) {
       let i = 0;
 
-      while (promisesToSourceIteratorMap.get(/** @type {BufferPromise} */ (bufferedPromises[i])) === currentSubIterator) {
+      while (i < bufferedPromises.length && promisesToSourceIteratorMap.get(/** @type {BufferPromise} */ (bufferedPromises[i])) === currentSubIterator) {
         i += 1;
       }
 
@@ -319,7 +335,7 @@ export function bufferedAsyncMap (input, callback, options) {
       return { done: true, value: undefined };
     } else if (err || done) {
       if (err) {
-        const normalisedErr = err instanceof Error ? err : new Error('Unknown error');
+        const normalisedErr = normalizeError(err, 'Unknown error');
 
         // In fail-fast mode the first captured error short-circuits iteration:
         // route it through the same abort machinery so the next .next() rejects

lib/misc.js

@@ -22,3 +22,12 @@ export function arrayDeleteInPlace (list, value) {
     list.splice(index, 1);
   }
 }
+
+/**
+ * @param {unknown} err
+ * @param {string} defaultMessage
+ * @returns {Error}
+ */
+export function normalizeError (err, defaultMessage) {
+  return err instanceof Error ? err : new Error(defaultMessage);
+}

lib/type-checks.js

@@ -1,19 +1,27 @@
+import { guardedArrayIncludes } from '@voxpelli/typed-utils';
+
+/**
+ * @param {unknown} value
+ * @returns {value is object}
+ */
+const isValueObject = (value) => Boolean(value && typeof value === 'object');
+
 /**
  * @param {unknown} value
  * @returns {value is Iterable<unknown>}
  */
-export const isIterable = (value) => Boolean(value && typeof value === 'object' && Symbol.iterator in value);
+export const isIterable = (value) => isValueObject(value) && Symbol.iterator in value;
 
 /**
  * @param {unknown} value
  * @returns {value is AsyncIterable<unknown>}
  */
-export const isAsyncIterable = (value) => Boolean(value && typeof value === 'object' && Symbol.asyncIterator in value);
+export const isAsyncIterable = (value) => isValueObject(value) && Symbol.asyncIterator in value;
 
 /**
  * @template Values
  * @param {unknown} value
  * @param {Values[]} list
  * @returns {value is Values}
  */
-export const isPartOfArray = (value, list) => list.includes(/** @type {Values} */ (value));
+export const isPartOfArray = (value, list) => guardedArrayIncludes(list, value);

package.json

@@ -70,5 +70,8 @@
     "type-coverage": "^2.29.1",
     "typescript": "~5.5.3",
     "validate-conventional-commit": "^1.0.4"
+  },
+  "dependencies": {
+    "@voxpelli/typed-utils": "^2.6.0"
   }
 }