@powersync/service-core 1.27.1 → 1.28.0

package/test/src/connection-metrics.test.ts

@@ -0,0 +1,184 @@
+import { ErrorCode, InternalServerError, ServiceError } from '@powersync/lib-services-framework';
+import { APIMetric } from '@powersync/service-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  initializeCoreAPIMetrics,
+  recordSyncConnection,
+  SyncCloseReason,
+  syncConnectionCloseReasonLogText,
+  SyncTransport
+} from '@/index.js';
+import { recordingMetricsEngine } from './recording-metrics.js';
+
+describe('recordSyncConnection', () => {
+  let recorder: ReturnType<typeof recordingMetricsEngine>;
+
+  beforeEach(() => {
+    recorder = recordingMetricsEngine('connection-metrics-test');
+  });
+
+  afterEach(async () => {
+    await recorder.shutdown();
+  });
+
+  function seriesValue(attributes: Record<string, string>): Promise<number | undefined> {
+    return recorder.seriesValue(APIMetric.SYNC_CONNECTIONS, attributes);
+  }
+
+  it.each([
+    [SyncCloseReason.ClientClosed, 'ok', SyncTransport.HttpStream],
+    [SyncCloseReason.ServiceClosed, 'ok', SyncTransport.HttpStream],
+    [SyncCloseReason.ProcessShutdown, 'ok', SyncTransport.HttpStream],
+    [SyncCloseReason.Unknown, 'ok', SyncTransport.HttpStream],
+    [SyncCloseReason.StreamError, 'error', SyncTransport.HttpStream],
+    [SyncCloseReason.ServiceUnavailable, 'rejected', SyncTransport.HttpStream],
+    [SyncCloseReason.NoSyncConfig, 'rejected', SyncTransport.HttpStream],
+    [SyncCloseReason.StorageError, 'rejected', SyncTransport.HttpStream],
+    [SyncCloseReason.SyncConfigError, 'rejected', SyncTransport.HttpStream],
+    [SyncCloseReason.ConcurrencyLimit, 'rejected', SyncTransport.RSocket]
+  ] as const)('classifies %s as %s', async (closeReason, outcome, transport) => {
+    recordSyncConnection(recorder.engine, { transport, closeReason });
+
+    expect(await seriesValue({ close_reason: closeReason, outcome })).toBe(1);
+    expect(await seriesValue({})).toBe(1);
+  });
+
+  it('creates an error-code series on its first failure without resetting it on initialization', async () => {
+    const labels = {
+      outcome: 'error',
+      close_reason: 'stream_error',
+      error_code: ErrorCode.PSYNC_S2403,
+      transport: 'http_stream'
+    };
+    expect(await seriesValue(labels)).toBeUndefined();
+
+    recordSyncConnection(recorder.engine, {
+      transport: SyncTransport.HttpStream,
+      closeReason: SyncCloseReason.StreamError,
+      error: new ServiceError(ErrorCode.PSYNC_S2403, 'Query timed out')
+    });
+
+    expect(await seriesValue(labels)).toBe(1);
+    initializeCoreAPIMetrics(recorder.engine);
+    expect(await seriesValue(labels)).toBe(1);
+  });
+
+  it('does not seed connection series but still initializes the concurrent connection gauge', async () => {
+    expect(await seriesValue({})).toBeUndefined();
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+
+    initializeCoreAPIMetrics(recorder.engine);
+
+    expect(await seriesValue({})).toBeUndefined();
+    expect(await recorder.seriesValue(APIMetric.CONCURRENT_CONNECTIONS, {})).toBe(0);
+  });
+
+  describe('error_code', () => {
+    it('reports other for errors without a recognized PowerSync error code', async () => {
+      for (const error of [
+        new Error('boom'),
+        'not even an error',
+        { is_service_error: true, errorData: { code: 'customer-specific-code' } }
+      ]) {
+        recordSyncConnection(recorder.engine, {
+          transport: SyncTransport.RSocket,
+          closeReason: SyncCloseReason.StreamError,
+          error
+        });
+      }
+
+      expect(await seriesValue({ close_reason: 'stream_error', error_code: 'other' })).toBe(3);
+    });
+
+    it('reports the PowerSync code from a service error', async () => {
+      recordSyncConnection(recorder.engine, {
+        transport: SyncTransport.RSocket,
+        closeReason: SyncCloseReason.StreamError,
+        error: new ServiceError({ status: 500, code: ErrorCode.PSYNC_S2305, description: 'x' })
+      });
+      recordSyncConnection(recorder.engine, {
+        transport: SyncTransport.RSocket,
+        closeReason: SyncCloseReason.StreamError,
+        error: new InternalServerError(new Error('boom'))
+      });
+
+      expect(await seriesValue({ close_reason: 'stream_error', error_code: ErrorCode.PSYNC_S2305 })).toBe(1);
+      expect(await seriesValue({ close_reason: 'stream_error', error_code: ErrorCode.PSYNC_S2001 })).toBe(1);
+    });
+
+    it('reports other when a failure has no error code', async () => {
+      recordSyncConnection(recorder.engine, {
+        transport: SyncTransport.RSocket,
+        closeReason: SyncCloseReason.StreamError
+      });
+
+      expect(await seriesValue({ close_reason: 'stream_error', error_code: 'other' })).toBe(1);
+    });
+
+    it('passes a PowerSync error code through', async () => {
+      recordSyncConnection(recorder.engine, {
+        transport: SyncTransport.RSocket,
+        closeReason: SyncCloseReason.NoSyncConfig,
+        error: new ServiceError({ status: 500, code: ErrorCode.PSYNC_S2302, description: 'x' })
+      });
+
+      expect(
+        await seriesValue({
+          outcome: 'rejected',
+          close_reason: 'no_sync_config',
+          error_code: ErrorCode.PSYNC_S2302,
+          transport: 'rsocket'
+        })
+      ).toBe(1);
+    });
+
+    it.each([
+      SyncCloseReason.ClientClosed,
+      SyncCloseReason.ServiceClosed,
+      SyncCloseReason.ProcessShutdown,
+      SyncCloseReason.Unknown
+    ])('omits error_code and counts %s once even when the handler collected an error', async (closeReason) => {
+      const add = vi.spyOn(recorder.engine.getCounter(APIMetric.SYNC_CONNECTIONS), 'add');
+      recordSyncConnection(recorder.engine, {
+        transport: SyncTransport.RSocket,
+        closeReason,
+        error: new InternalServerError(new Error('ignored'))
+      });
+
+      expect(add).toHaveBeenCalledExactlyOnceWith(1, {
+        outcome: 'ok',
+        close_reason: closeReason,
+        transport: 'rsocket'
+      });
+      expect(await seriesValue({})).toBe(1);
+    });
+  });
+
+  it('accumulates independently for each transport', async () => {
+    for (let i = 0; i < 2; i++) {
+      recordSyncConnection(recorder.engine, {
+        transport: SyncTransport.HttpStream,
+        closeReason: SyncCloseReason.ClientClosed
+      });
+    }
+    recordSyncConnection(recorder.engine, {
+      transport: SyncTransport.RSocket,
+      closeReason: SyncCloseReason.ClientClosed
+    });
+
+    const labels = { outcome: 'ok', close_reason: 'client_closed' };
+    expect(await seriesValue({ ...labels, transport: 'http_stream' })).toBe(2);
+    expect(await seriesValue({ ...labels, transport: 'rsocket' })).toBe(1);
+  });
+});
+
+describe('syncConnectionCloseReasonLogText', () => {
+  it('keeps the pre-existing log wording for handler close reasons', () => {
+    expect(syncConnectionCloseReasonLogText(SyncCloseReason.ClientClosed)).toBe('client closing stream');
+    expect(syncConnectionCloseReasonLogText(SyncCloseReason.ServiceClosed)).toBe('service closing stream');
+    expect(syncConnectionCloseReasonLogText(SyncCloseReason.ProcessShutdown)).toBe('process shutdown');
+    expect(syncConnectionCloseReasonLogText(SyncCloseReason.StreamError)).toBe('stream error');
+    expect(syncConnectionCloseReasonLogText(undefined)).toBe('unknown');
+  });
+});

package/test/src/diagnostics.test.ts

@@ -1,7 +1,7 @@
 import { DiagnosticsOptions, getSyncRulesStatus } from '@/api/diagnostics.js';
 import { RouteAPI, SlotWalBudgetInfo } from '@/api/RouteAPI.js';
 import { ParsedSyncConfigSet, storage } from '@/index.js';
-import { SqlSyncRules } from '@powersync/service-sync-rules';
+import { parseSyncConfig } from '@powersync/service-sync-rules';
 import { describe, expect, test } from 'vitest';
 
 const GB = 1024 * 1024 * 1024;
@@ -40,7 +40,7 @@ function makeSyncRulesContent(overrides?: {
     syncConfigState: status.state,
     version_label: overrides?.version_label,
     parsed(options?: any) {
-      const syncRules = SqlSyncRules.fromYaml(MINIMAL_SYNC_RULES, {
+      const syncRules = parseSyncConfig(MINIMAL_SYNC_RULES, {
         ...options,
         defaultSchema: 'public'
       });
@@ -217,7 +217,7 @@ streams:
 `;
     const content = makeSyncRulesContent();
     content.parsed = (options?: any) => {
-      SqlSyncRules.fromYaml(yaml, { ...options, defaultSchema: 'public', throwOnError: true });
+      parseSyncConfig(yaml, { ...options, defaultSchema: 'public', throwOnError: true });
       throw new Error('Expected parsing to fail');
     };
 

package/test/src/last_value_sink.test.ts

@@ -0,0 +1,34 @@
+import { LastValueSink } from '@/streams/LastValueSink.js';
+import { describe, expect, test } from 'vitest';
+
+describe('LastValueSink cancellation', () => {
+  test.each([
+    { reason: undefined },
+    { reason: new DOMException('Cancelled', 'AbortError') },
+    { reason: new Error('Cancelled') },
+    { reason: 'cancelled' },
+    { reason: 0 },
+    { reason: false },
+    { reason: '' },
+    { reason: null }
+  ])('preserves abort reason $reason before and during a read', async ({ reason }) => {
+    const controller = new AbortController();
+    const sink = new LastValueSink<number>(undefined);
+    const iterator = sink.withSignal(controller.signal)[Symbol.asyncIterator]();
+    const pending = iterator.next();
+    controller.abort(reason);
+    await expect(pending).rejects.toBe(controller.signal.reason);
+
+    const alreadyAborted = new LastValueSink<number>(1).withSignal(controller.signal)[Symbol.asyncIterator]();
+    await expect(alreadyAborted.next()).rejects.toBe(controller.signal.reason);
+  });
+
+  test('uses a DOM AbortError for default cancellation', async () => {
+    const signal = AbortSignal.abort();
+    const iterator = new LastValueSink<number>(undefined).withSignal(signal)[Symbol.asyncIterator]();
+    await expect(iterator.next()).rejects.toBeInstanceOf(DOMException);
+    await expect(new LastValueSink<number>(1).withSignal(signal)[Symbol.asyncIterator]().next()).rejects.toMatchObject({
+      name: 'AbortError'
+    });
+  });
+});

package/test/src/merge_iterable.test.ts

@@ -1,18 +1,14 @@
-import { mergeAsyncIterablesNew, mergeAsyncIterablesOld } from '@/streams/merge.js';
+import { IterableSource } from '@/streams/BroadcastIterable.js';
+import { mergeAsyncIterables } from '@/streams/merge.js';
 import * as timers from 'timers/promises';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 
-type MergeIteratorFunction = <T>(source: AsyncIterable<T>[]) => AsyncIterable<T>;
+// These finite legacy sources do not wait indefinitely. Cancellation-aware sources below test pending reads.
+function mergeSources<T>(sources: AsyncIterable<T>[]): AsyncIterable<T> {
+  return mergeAsyncIterables(sources.map((source) => () => source));
+}
 
 describe('merge iterables', () => {
-  makeTests((source) => mergeAsyncIterablesNew(source));
-});
-
-describe('merge iterables - legacy implementation', () => {
-  makeTests((source) => mergeAsyncIterablesOld(source));
-});
-
-function makeTests(mergeIterables: MergeIteratorFunction) {
   test('iterable should not pre-emptively continue (1)', async () => {
     // Test that the generator stops after the first yield
     let afterYield = false;
@@ -27,7 +23,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a()]);
+    const merged = mergeSources([a()]);
     const iter = merged[Symbol.asyncIterator]();
     const r = await iter.next();
     expect(r).toEqual({ value: 1, done: false });
@@ -51,7 +47,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a()]);
+    const merged = mergeSources([a()]);
 
     for await (let r of merged) {
       expect(r).toEqual(1);
@@ -75,7 +71,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a()]);
+    const merged = mergeSources([a()]);
 
     for await (let r of merged) {
       expect(r).toEqual(1);
@@ -107,7 +103,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a(), b()]);
+    const merged = mergeSources([a(), b()]);
 
     const iter = merged[Symbol.asyncIterator]();
     expect(await iter.next()).toEqual({ value: 'a', done: false });
@@ -151,12 +147,13 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a(), b()]);
+    const merged = mergeSources([a(), b()]);
 
     const iter = merged[Symbol.asyncIterator]();
     expect(await iter.next()).toEqual({ value: 'a', done: false });
     expect(await iter.next()).toEqual({ value: 'b', done: false });
-    await iter.return!();
+    // A previously pending read fails during cleanup. Blocking cleanup must surface that error.
+    await expect(iter.return!()).rejects.toThrow('a');
 
     await timers.setTimeout(2);
 
@@ -193,7 +190,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a(), b()]);
+    const merged = mergeSources([a(), b()]);
 
     const iter = merged[Symbol.asyncIterator]();
     expect(await iter.next()).toEqual({ value: 'a', done: false });
@@ -241,7 +238,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a(), b()]);
+    const merged = mergeSources([a(), b()]);
 
     const iter = merged[Symbol.asyncIterator]();
     expect(await iter.next()).toEqual({ value: 'a', done: false });
@@ -281,7 +278,7 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
       }
     };
 
-    const merged = mergeIterables([a()]);
+    const merged = mergeSources([a()]);
     const iter = merged[Symbol.asyncIterator]();
     const r = await iter.next();
     expect(r).toEqual({ value: 1, done: false });
@@ -297,54 +294,306 @@ function makeTests(mergeIterables: MergeIteratorFunction) {
     expect(aFinally).toEqual(true);
     expect(aError).toEqual(new Error('loop error'));
   });
+});
 
-  test('do not block return', async () => {
-    let aDone = false;
-    let bDone = false;
-    let b2Reached = false;
-    let b2Timedout = false;
-    let b3Reached = false;
+describe('blocking merge cleanup', () => {
+  test.each([
+    { reason: new DOMException('Cancelled', 'AbortError') },
+    { reason: new Error('Cancelled') },
+    { reason: 'cancelled' },
+    { reason: 0 },
+    { reason: false },
+    { reason: null }
+  ])('preserves abort reason $reason before and during iteration', async ({ reason }) => {
+    const preAborted = mergeAsyncIterables([], AbortSignal.abort(reason))[Symbol.asyncIterator]();
+    await expect(preAborted.next()).rejects.toBe(reason);
+
+    const started = Promise.withResolvers<void>();
+    const controller = new AbortController();
+    const source: IterableSource<number> = async function* (signal) {
+      started.resolve();
+      await timers.setTimeout(60_000, undefined, { signal });
+      yield 1;
+    };
+    const iterator = mergeAsyncIterables([source], controller.signal)[Symbol.asyncIterator]();
+    const outcome = expect(iterator.next()).rejects.toBe(reason);
+    await started.promise;
+    controller.abort(reason);
+    await outcome;
+  });
 
-    const a = async function* (): AsyncGenerator<string, void> {
+  test('passes the iteration failure to source cancellation', async () => {
+    const error = new Error('source failed');
+    let sourceSignal: AbortSignal | undefined;
+    const failing: IterableSource<number> = async function* () {
+      throw error;
+    };
+    const other: IterableSource<number> = async function* (signal) {
+      sourceSignal = signal;
+      yield 1;
+    };
+    await expect(mergeAsyncIterables([failing, other])[Symbol.asyncIterator]().next()).rejects.toBe(error);
+    expect(sourceSignal!.reason).toBe(error);
+  });
+
+  test('aborts a pending source read when another source completes', async () => {
+    let closed = false;
+    const waiting: IterableSource<number> = async function* (signal) {
       try {
-        yield 'a';
+        await timers.setTimeout(60_000, undefined, { signal });
+        yield 2;
       } finally {
-        aDone = true;
+        closed = true;
       }
     };
-    const b = async function* (): AsyncGenerator<string, void> {
+    const iter = mergeAsyncIterables([
+      async function* () {
+        yield 1;
+      },
+      waiting
+    ])[Symbol.asyncIterator]();
+
+    expect(await iter.next()).toEqual({ done: false, value: 1 });
+    expect(await iter.next()).toEqual({ done: true, value: undefined });
+    expect(closed).toBe(true);
+  });
+
+  test.each(['return', 'throw', 'abort'] as const)('unblocks an in-flight next() on %s', async (method) => {
+    const started = Promise.withResolvers<void>();
+    const controller = new AbortController();
+    const original = new Error('consumer failed');
+    let closed = false;
+    const source: IterableSource<number> = async function* (signal) {
       try {
-        yield 'b1';
-        // This point should be reached, even if the value is not used
-        b2Reached = true;
-        // The final iter.next() should not wait for this to complete
-        await timers.setTimeout(50);
-        b2Timedout = true;
-        yield 'b2';
-        // This point should not be reached
-        b3Reached = true;
+        started.resolve();
+        await timers.setTimeout(60_000, undefined, { signal });
+        yield 1;
       } finally {
-        bDone = true;
+        closed = true;
       }
     };
+    const iter = mergeAsyncIterables([source], controller.signal)[Symbol.asyncIterator]();
+    const next = iter.next();
+    const outcome = next.then(
+      (value) => value,
+      (error) => error
+    );
+    await started.promise;
+
+    if (method === 'throw') {
+      await expect(iter.throw!(original)).rejects.toBe(original);
+      expect(await outcome).toBe(original);
+    } else if (method === 'abort') {
+      controller.abort();
+      expect(await outcome).toMatchObject({ name: 'AbortError' });
+    } else {
+      await expect(iter.return!()).resolves.toEqual({ done: true, value: undefined });
+      expect(await outcome).toEqual({ done: true, value: undefined });
+    }
+    expect(closed).toBe(true);
+  });
 
-    const merged = mergeIterables([a(), b()]);
+  test('waits for every cleanup and starts cleanups concurrently', async () => {
+    const gates = [Promise.withResolvers<void>(), Promise.withResolvers<void>()];
+    const started = gates.map(() => Promise.withResolvers<void>());
+    const closed: number[] = [];
+    const sources = gates.map(
+      (gate, index): IterableSource<number> =>
+        async function* () {
+          try {
+            yield index;
+          } finally {
+            started[index].resolve();
+            await gate.promise;
+            closed.push(index);
+          }
+        }
+    );
+    const iter = mergeAsyncIterables(sources)[Symbol.asyncIterator]();
+    await iter.next();
+    let finished = false;
+    const cleanup = iter.return!().then(() => {
+      finished = true;
+    });
+    await Promise.all(started.map((item) => item.promise));
+    expect(finished).toBe(false);
+    gates[0].resolve();
+    await timers.setImmediate();
+    expect(closed).toEqual([0]);
+    expect(finished).toBe(false);
+    gates[1].resolve();
+    await cleanup;
+    expect(closed).toEqual([0, 1]);
+  });
 
-    const iter = merged[Symbol.asyncIterator]();
-    expect(await iter.next()).toEqual({ value: 'a', done: false });
-    expect(await iter.next()).toEqual({ value: 'b1', done: false });
-    expect(await iter.next()).toEqual({ value: undefined, done: true });
+  test.each(['return', 'throw'] as const)(
+    'surfaces cleanup failures on %s without hiding the consumer error',
+    async (method) => {
+      const original = new Error('consumer failed');
+      const cleanupError = new Error('cleanup failed');
+      let otherClosed = false;
+      const failing: IterableSource<number> = async function* () {
+        try {
+          yield 1;
+        } finally {
+          throw cleanupError;
+        }
+      };
+      const other: IterableSource<number> = async function* () {
+        try {
+          yield 2;
+        } finally {
+          otherClosed = true;
+        }
+      };
+      const iter = mergeAsyncIterables([failing, other])[Symbol.asyncIterator]();
+      await iter.next();
 
-    expect(aDone).toEqual(true);
-    expect(b2Reached).toEqual(true);
-    expect(b2Reached).toEqual(true);
-    expect(b2Timedout).toEqual(false);
-    expect(bDone).toEqual(false);
+      if (method === 'return') {
+        await expect(iter.return!()).rejects.toBe(cleanupError);
+      } else {
+        await expect(iter.throw!(original)).rejects.toMatchObject({
+          errors: [original, cleanupError],
+          cause: original
+        });
+      }
+      expect(otherClosed).toBe(true);
+    }
+  );
 
-    await timers.setTimeout(60);
+  test('preserves the iteration error when another source fails cleanup', async () => {
+    const original = new Error('source failed');
+    const cleanupError = new Error('cleanup failed');
+    const failing: IterableSource<number> = async function* () {
+      throw original;
+    };
+    const other: IterableSource<number> = async function* () {
+      try {
+        yield 1;
+      } finally {
+        throw cleanupError;
+      }
+    };
+    const iter = mergeAsyncIterables([failing, other])[Symbol.asyncIterator]();
+    await expect(iter.next()).rejects.toMatchObject({ errors: [original, cleanupError], cause: original });
+  });
 
-    expect(b2Timedout).toEqual(true);
-    expect(bDone).toEqual(true);
-    expect(b3Reached).toEqual(false);
+  test('handles a losing read that rejects while the consumer is paused', async () => {
+    const error = new Error('background read failed');
+    const failure = Promise.withResolvers<void>();
+    const source: IterableSource<number> = async function* () {
+      yield 1;
+    };
+    const failing: IterableSource<number> = async function* () {
+      await failure.promise;
+      throw error;
+    };
+    const iter = mergeAsyncIterables([source, failing])[Symbol.asyncIterator]();
+    expect(await iter.next()).toEqual({ done: false, value: 1 });
+    failure.resolve();
+    // No next() consumer is attached during this turn. Vitest detects any unhandled rejection.
+    await timers.setImmediate();
+    await expect(iter.return!()).rejects.toBe(error);
   });
-}
+
+  test('closes a source even if it catches an injected error and yields again', async () => {
+    const original = new Error('consumer failed');
+    let closed = false;
+    const source: IterableSource<number> = async function* () {
+      try {
+        try {
+          yield 1;
+        } catch {
+          yield 2;
+        }
+      } finally {
+        closed = true;
+      }
+    };
+    const iter = mergeAsyncIterables([source])[Symbol.asyncIterator]();
+    await iter.next();
+    await expect(iter.throw!(original)).rejects.toBe(original);
+    expect(closed).toBe(true);
+  });
+
+  test('cleans up initialized sources if a later factory throws', async () => {
+    const error = new Error('factory failed');
+    const close = vi.fn(async () => ({ done: true as const, value: undefined }));
+    const source: IterableSource<number> = () => ({
+      [Symbol.asyncIterator]: () => ({ next: async () => ({ done: false, value: 1 }), return: close })
+    });
+    const iter = mergeAsyncIterables([
+      source,
+      () => {
+        throw error;
+      }
+    ])[Symbol.asyncIterator]();
+    await expect(iter.next()).rejects.toBe(error);
+    expect(close).toHaveBeenCalledOnce();
+  });
+
+  test('does not create sources after cancellation or return before the first read', async () => {
+    const source = vi.fn(async function* () {
+      yield 1;
+    });
+    const controller = new AbortController();
+    controller.abort();
+    await expect(mergeAsyncIterables([source], controller.signal)[Symbol.asyncIterator]().next()).rejects.toMatchObject(
+      { name: 'AbortError' }
+    );
+    await mergeAsyncIterables([source])[Symbol.asyncIterator]().return!();
+    expect(source).not.toHaveBeenCalled();
+  });
+
+  test('completes an empty merge', async () => {
+    await expect(mergeAsyncIterables([])[Symbol.asyncIterator]().next()).resolves.toEqual({
+      done: true,
+      value: undefined
+    });
+  });
+
+  test('collects multiple cleanup errors, including synchronous failures', async () => {
+    const errors = [new Error('first cleanup failed'), new Error('second cleanup failed')];
+    const closed: number[] = [];
+    const sources = errors.map(
+      (error, index): IterableSource<number> =>
+        () => ({
+          [Symbol.asyncIterator]: () => ({
+            next: async () => ({ done: false, value: index }),
+            return: () => {
+              closed.push(index);
+              if (index === 0) throw error;
+              return Promise.reject(error);
+            }
+          })
+        })
+    );
+    const iter = mergeAsyncIterables(sources)[Symbol.asyncIterator]();
+    await iter.next();
+    await expect(iter.return!()).rejects.toMatchObject({ errors, cause: errors[0] });
+    expect(closed).toEqual([0, 1]);
+  });
+
+  test('cleans up on external abort while the consumer is paused and retains cleanup failures', async () => {
+    const controller = new AbortController();
+    const closed = Promise.withResolvers<void>();
+    const error = new Error('cleanup failed');
+    const source: IterableSource<number> = async function* () {
+      try {
+        yield 1;
+      } finally {
+        closed.resolve();
+        throw error;
+      }
+    };
+    const iter = mergeAsyncIterables([source], controller.signal)[Symbol.asyncIterator]();
+    await iter.next();
+    controller.abort();
+    await closed.promise;
+    // No consumer is awaiting cleanup yet. The stored cleanup result must not reject in the background.
+    await timers.setImmediate();
+    await expect(iter.return!()).rejects.toMatchObject({
+      errors: [expect.objectContaining({ name: 'AbortError' }), error]
+    });
+  });
+});