@dev-crew-berlin/enter-js-utils 0.98.9 → 0.98.11

package/dist/api-client/api-base.js

@@ -5,15 +5,22 @@ const BACKOFF_INITIAL_MS = 1_000;
 const BACKOFF_MAX_MS = 30_000;
 const BACKOFF_RESET_AFTER_MS = 10_000;
 const WATCHDOG_TIMEOUT_MS = 45_000;
-function sleep(ms, signal) {
+function sleep(ms, ...signals) {
   return new Promise(resolve => {
     const timer = setTimeout(resolve, ms);
-    signal.addEventListener('abort', () => {
+    const cleanup = () => {
       clearTimeout(timer);
       resolve();
-    }, {
-      once: true
-    });
+    };
+    for (const signal of signals) {
+      if (signal.aborted) {
+        cleanup();
+        return;
+      }
+      signal.addEventListener('abort', cleanup, {
+        once: true
+      });
+    }
   });
 }
 export default class APIBase {
@@ -182,11 +189,38 @@ export default class APIBase {
     let lastEventId = options.initialLastEventId ?? null;
     let backoffMs = BACKOFF_INITIAL_MS;
     let isFirstConnect = true;
+
+    // iOS standalone PWAs are frozen when backgrounded; the heartbeat watchdog
+    // cannot fire while JS is suspended. When the user returns to the app the
+    // foreground events fire immediately, so we use them as a hard-reconnect
+    // trigger instead of waiting for the watchdog.
+    let currentWakeController = null;
+    const onForegroundResume = () => {
+      backoffMs = BACKOFF_INITIAL_MS;
+      currentWakeController?.abort();
+    };
+    const onVisibilityChange = () => {
+      if (document.visibilityState === 'visible') onForegroundResume();
+    };
+    const hasDocument = typeof document !== 'undefined';
+    if (hasDocument) {
+      document.addEventListener('visibilitychange', onVisibilityChange);
+      document.addEventListener('pageshow', onForegroundResume);
+    }
     try {
       while (!outerAbort.signal.aborted) {
         // Fresh abort controller per attempt so the watchdog or a read error
         // on one attempt cannot bleed into the next.
         const attemptAbort = new AbortController();
+        // wakeController is aborted by foreground events to immediately skip
+        // the backoff sleep and break out of a wedged reader.read() race.
+        const wakeController = new AbortController();
+        currentWakeController = wakeController;
+        // Propagate a foreground wake to the in-flight fetch so it is
+        // cancelled and we open a fresh connection right away.
+        wakeController.signal.addEventListener('abort', () => attemptAbort.abort(), {
+          once: true
+        });
         const propagateAbort = () => attemptAbort.abort();
         outerAbort.signal.addEventListener('abort', propagateAbort);
         const hadCursor = lastEventId !== null;
@@ -223,7 +257,7 @@ export default class APIBase {
             for await (const {
               data,
               id
-            } of this.readSseEvents(res.data.body, attemptAbort, onReset)) {
+            } of this.readSseEvents(res.data.body, attemptAbort, onReset, wakeController.signal)) {
               if (id) lastEventId = id;
               yield data;
             }
@@ -242,13 +276,17 @@ export default class APIBase {
         const lived = connectedAt > 0 ? Date.now() - connectedAt : 0;
         if (lived >= BACKOFF_RESET_AFTER_MS) backoffMs = BACKOFF_INITIAL_MS;
         onConnectionChange?.('reconnecting');
-        await sleep(backoffMs, outerAbort.signal);
+        await sleep(backoffMs, outerAbort.signal, wakeController.signal);
         backoffMs = Math.min(backoffMs * 2, BACKOFF_MAX_MS) * (0.5 + Math.random());
       }
     } finally {
       // Aborting here also unblocks any in-progress sleep() call.
       outerAbort.abort();
       externalSignal?.removeEventListener('abort', onExternalAbort);
+      if (hasDocument) {
+        document.removeEventListener('visibilitychange', onVisibilityChange);
+        document.removeEventListener('pageshow', onForegroundResume);
+      }
     }
   }
 
@@ -257,7 +295,7 @@ export default class APIBase {
   // if no message arrives within WATCHDOG_TIMEOUT_MS the connection is
   // considered half-open (common on mobile networks) and is aborted so the
   // outer loop can reconnect.
-  async *readSseEvents(body, attemptAbort, onReset) {
+  async *readSseEvents(body, attemptAbort, onReset, wakeSignal) {
     const reader = body.pipeThrough(new TextDecoderStream()).pipeThrough(new EventSourceParserStream()).getReader();
     let watchdogTimer = null;
     const resetWatchdog = () => {
@@ -265,12 +303,27 @@ export default class APIBase {
       watchdogTimer = setTimeout(() => attemptAbort.abort(), WATCHDOG_TIMEOUT_MS);
     };
     resetWatchdog();
+
+    // Resolves to a sentinel when a foreground-resume event fires. Racing
+    // reader.read() against this promise means the loop can advance to a
+    // fresh connection even if the old read is permanently wedged (iOS).
+    const reconnect = new Promise(resolve => {
+      if (wakeSignal.aborted) {
+        resolve('reconnect');
+        return;
+      }
+      wakeSignal.addEventListener('abort', () => resolve('reconnect'), {
+        once: true
+      });
+    });
     try {
       while (true) {
+        const result = await Promise.race([reader.read(), reconnect]);
+        if (result === 'reconnect') break;
         const {
           done,
           value: event
-        } = await reader.read();
+        } = result;
         if (done) break;
 
         // Any message — including heartbeats — proves the connection is alive.

package/dist/api-client/api-client.test.js

@@ -645,6 +645,196 @@ describe('resilientStream', () => {
     await pending;
   });
 });
+
+// Minimal document stub for foreground-event tests (test env is node, no DOM).
+// visibilityState and dispatch() let tests simulate visibilitychange / pageshow.
+function makeMockDocument() {
+  const listeners = new Map();
+  return {
+    visibilityState: 'visible',
+    addEventListener(type, fn) {
+      if (!listeners.has(type)) listeners.set(type, new Set());
+      listeners.get(type).add(fn);
+    },
+    removeEventListener(type, fn) {
+      listeners.get(type)?.delete(fn);
+    },
+    dispatch(type) {
+      for (const fn of listeners.get(type) ?? []) fn(new Event(type));
+    },
+    listenerCount(type) {
+      return listeners.get(type)?.size ?? 0;
+    }
+  };
+}
+
+// A stream that delivers initialChunks immediately but never closes and never
+// errors, so reader.read() hangs forever once the chunks are consumed.
+function makeWedgedStream(initialChunks = []) {
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of initialChunks) controller.enqueue(chunk);
+      // deliberately never closed or errored
+    }
+  });
+}
+describe('foreground reconnect (visibilitychange / pageshow)', () => {
+  let mockDoc;
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockDoc = makeMockDocument();
+    vi.stubGlobal('document', mockDoc);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  // ─── immediate reconnect on visibilitychange ──────────────────────────────
+
+  it('reconnects immediately on visibilitychange without waiting for backoff', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      // All connections return a silent stream (never delivers events)
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+
+    // Simulate returning to foreground — should trigger immediate reconnect
+    mockDoc.visibilityState = 'visible';
+    mockDoc.dispatch('visibilitychange');
+    await flushMicrotasks();
+
+    // New connection opened without advancing fake timers at all
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+  it('reconnects immediately on pageshow without waiting for backoff', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+    mockDoc.dispatch('pageshow');
+    await flushMicrotasks();
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── Last-Event-ID carried on foreground reconnect ────────────────────────
+
+  it('foreground reconnect carries Last-Event-ID from last received event', async () => {
+    const capturedInits = [];
+    vi.stubGlobal('fetch', (_url, init) => {
+      capturedInits.push(init);
+      if (capturedInits.length === 1) {
+        // First connection: delivers one event with cursor, then hangs
+        return Promise.resolve(okResponse(makeWedgedStream([sseChunk([{
+          id: 'cursor-42',
+          data: '{"n":1}'
+        }])])));
+      }
+      // Second+ connections: abort-responsive so the test can clean up
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+
+    // Consume the first event; generator is now suspended at 'yield data'
+    const response1 = await gen.next();
+    expect(response1.value).toEqual({
+      n: 1
+    });
+
+    // Drive the generator forward so it re-enters readSseEvents's Promise.race.
+    // Without this call the generator stays frozen at 'yield data' and the
+    // foreground event cannot be picked up until the consumer drives it.
+    const nextPromise = gen.next();
+    await flushMicrotasks();
+
+    // Foreground event fires while reader.read() is wedged on the first stream
+    mockDoc.visibilityState = 'visible';
+    mockDoc.dispatch('visibilitychange');
+    await flushMicrotasks();
+    expect(capturedInits.length).toBeGreaterThanOrEqual(2);
+    const secondHeaders = capturedInits[1]?.headers;
+    expect(secondHeaders?.['Last-Event-ID']).toBe('cursor-42');
+    abortController.abort();
+    await nextPromise;
+  });
+
+  // ─── wedged read — recovery without stream closing ────────────────────────
+
+  it('recovers even when the prior response body never closes', async () => {
+    let connectionCount = 0;
+    vi.stubGlobal('fetch', (_url, init) => {
+      connectionCount++;
+      if (connectionCount === 1) {
+        // First connection is truly wedged — reader.read() hangs forever and
+        // the stream ignores the abort signal, simulating iOS zombie streams.
+        return Promise.resolve(okResponse(makeWedgedStream()));
+      }
+      // Subsequent connections are abort-responsive so the test can clean up.
+      return Promise.resolve(okResponse(makeSilentStream(init.signal)));
+    });
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const gen = api.subscribe('/test', {
+      signal: abortController.signal
+    });
+    gen.next();
+    await flushMicrotasks();
+    expect(connectionCount).toBe(1);
+
+    // Foreground event — must open new connection even though the first
+    // stream body is completely wedged and reader.read() never resolves.
+    mockDoc.visibilityState = 'visible';
+    mockDoc.dispatch('visibilitychange');
+    await flushMicrotasks();
+    expect(connectionCount).toBeGreaterThanOrEqual(2);
+    abortController.abort();
+    await gen.return(undefined);
+  });
+
+  // ─── no listener / timer leaks ────────────────────────────────────────────
+
+  it('removes visibilitychange and pageshow listeners after consumer aborts', async () => {
+    vi.stubGlobal('fetch', (_url, init) => Promise.resolve(okResponse(makeSilentStream(init.signal))));
+    const abortController = new AbortController();
+    const api = makeAPI();
+    const pending = api.subscribe('/test', {
+      signal: abortController.signal
+    }).next();
+    await flushMicrotasks();
+    expect(mockDoc.listenerCount('visibilitychange')).toBe(1);
+    expect(mockDoc.listenerCount('pageshow')).toBe(1);
+    abortController.abort();
+    await pending;
+    expect(mockDoc.listenerCount('visibilitychange')).toBe(0);
+    expect(mockDoc.listenerCount('pageshow')).toBe(0);
+  });
+});
 function makeFullAPI() {
   return new API({
     credentials: {
@@ -693,4 +883,56 @@ describe('getAttendeeList', () => {
     if (!result.success) return;
     expect(result.data.eventCursor).toBe('abc123');
   });
+});
+describe('createEvents', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  it('returns created and eventCursors populated from response body', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify({
+      created: 2,
+      event_cursors: {
+        'uuid-1': 'cursor-abc',
+        'uuid-2': 'cursor-def'
+      }
+    }), {
+      status: 201
+    })));
+    const api = makeFullAPI();
+    const result = await api.createEvents([]);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.created).toBe(2);
+    expect(result.data.eventCursors).toEqual({
+      'uuid-1': 'cursor-abc',
+      'uuid-2': 'cursor-def'
+    });
+  });
+  it('returns empty eventCursors when field is absent', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify({
+      created: 1
+    }), {
+      status: 201
+    })));
+    const api = makeFullAPI();
+    const result = await api.createEvents([]);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.created).toBe(1);
+    expect(result.data.eventCursors).toEqual({});
+  });
+  it('returns empty eventCursors when field is empty', async () => {
+    vi.stubGlobal('fetch', () => Promise.resolve(new Response(JSON.stringify({
+      created: 0,
+      event_cursors: {}
+    }), {
+      status: 201
+    })));
+    const api = makeFullAPI();
+    const result = await api.createEvents([]);
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.data.created).toBe(0);
+    expect(result.data.eventCursors).toEqual({});
+  });
 });

package/dist/api-client/index.d.ts

@@ -163,7 +163,10 @@ declare class API extends APIBase {
     /**
      * @category Events
      */
-    createEvents(args: EventInput[], options?: FetchOptions): Promise<APIResult<null>>;
+    createEvents(args: EventInput[], options?: FetchOptions): Promise<APIResult<{
+        created: number;
+        eventCursors: Record<string, string>;
+    }>>;
     /**
      * Subscribe to the SSE event stream. Yields events as they arrive.
      * Use `for await` to consume events, and `break` or `return` to unsubscribe.

package/dist/api-client/index.js

@@ -228,7 +228,18 @@ class API extends APIBase {
    * @category Events
    */
   async createEvents(args, options = {}) {
-    return this.post(`/events`, args, options);
+    const result = await this.fetchResponse(`/events`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(args),
+      ...options
+    });
+    if (!result.success) return result;
+    const json = await result.data.json();
+    return success({
+      created: json.created,
+      eventCursors: json.event_cursors ?? {}
+    });
   }
 
   /**