@makerx/graphql-core 3.0.1 → 3.2.0

package/README.md

@@ -370,8 +370,26 @@ This library includes a `subscriptions` module to provide simple setup using the
 
 Wraps an `AsyncIterableIterator` (e.g. one returned by a pubsub `asyncIterableIterator(...)` call) with two optional behaviours:
 
-- `initialPayload` — a single event or array of events yielded before the wrapped iterator's events. Useful when a client subscribes after a state change has already happened, so they don't miss the current state while waiting for the next event.
-- `eventIsFinal` — a predicate that ends iteration eagerly when it returns `true` for an event. The final event is still yielded, then `wrapped.return()` is called to release resources. Only applied to events from the wrapped iterator, not to entries in `initialPayload`.
+- `initialPayload` — a single event, an array of events, or a **factory** (`() => event | event[] | undefined | Promise<…>`) yielded before the wrapped iterator's events. Useful when a client subscribes after a state change has already happened, so they don't miss the current state while waiting for the next event. A factory may return `undefined` (e.g. a `findOne` that yields nothing) to mean "no snapshot", in which case iteration proceeds straight to the wrapped stream.
+- `eventIsFinal` — a predicate that ends iteration eagerly when it returns `true` for an event. The triggering event is still yielded, then `wrapped.return()` is called to release resources. It is checked against every event from the wrapped iterator **and** against the _final_ entry of `initialPayload` (earlier entries are always yielded); if that final entry is terminal, iteration ends after the payload drains — in the value form without ever pulling the wrapped iterator.
+
+#### Prefer the factory form for "snapshot then stream"
+
+pubsub iterators (e.g. `graphql-subscriptions` / `graphql-redis-subscriptions`) subscribe to their channel **lazily, on the first `next()`**. If you read your snapshot (the initial payload) _before_ the iterator is pulled, the channel isn't live yet — any event published between the snapshot read and the subscription going live is **lost** _and_ missing from the snapshot, so the client can be left showing stale state until a manual refetch.
+
+Passing `initialPayload` as a **factory** closes that window: the helper eagerly pulls the wrapped iterator once (establishing the subscription) _before_ invoking the factory to read the snapshot. Events fired during the snapshot read are then buffered by the wrapped iterator and delivered immediately after the snapshot, instead of being dropped.
+
+```ts
+return wrapSubscriptionIterator({
+  iterator: pubsub().asyncIterableIterator(`topic.${id}`),
+  // factory runs AFTER the subscription is kicked, so an event fired during the read isn't lost
+  initialPayload: () => repo.find({ where: { id } }),
+})
+```
+
+> The plain value form (a single event or array) is unchanged and still subscribes lazily — fine when there is no read between subscribe and snapshot (e.g. a cached value already in hand, as below).
+>
+> Detection is via `typeof initialPayload === 'function'`. If your event type is itself callable, wrap a value-form payload in an array (`[value]`) to disambiguate it from a factory.
 
 Typical use is in a subscription resolver that needs to bridge a "current state" (cache or other persisted state lookup) with a live event stream, and close the subscription once a terminal event arrives:
 
@@ -405,6 +423,104 @@ The returned value is both an `AsyncIterator` and `AsyncIterable`, so it can be
   extractAnonymousOperationName('subscription { onUpdate { id } }') // 'subscription onUpdate'
   ```
 
+## GraphQL test helpers
+
+The `@makerx/graphql-core/testing` submodule provides helpers for running GraphQL operations directly against a schema, without spinning up an HTTP or websocket server.
+
+Bypassing the transport layer supports complete control over JWT payloads and other operation context inputs required to set up complex test scenarios.
+
+This complements the `@makerx/graphql-apollo-server/testing` module, which exports `buildExecuteOperation` for running queries and mutations directly against an `ApolloServer` instance. Subscriptions normally flow over websockets via [graphql-ws](https://the-guild.dev/graphql/ws), so they need their own helper that calls `graphql.subscribe` directly against the schema.
+
+### buildSubscribeOperation
+
+`buildSubscribeOperation` accepts a `GraphQLSchema` (or async schema factory) and a context creation function and returns a `subscribeOperation` function which:
+
+- is strongly typed to the GraphQL context
+- accepts `TypedDocumentNode` subscriptions to provide strong operation typing
+- forwards any additional arguments to the supplied context creation function
+- returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls
+- throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors
+
+The shape of the context creation function — and the JWT/user factories used to drive it — depends on your GraphQL implementation, so the example below illustrates one common pattern using [Vitest test contexts](https://vitest.dev/guide/test-context), matching the [`buildExecuteOperation`](https://github.com/MakerXStudio/graphql-apollo-server#apollo-server-test-helpers) examples for queries and mutations.
+
+#### Vitest GraphQL context example
+
+Note: extend auth context (e.g. `buildJwt`, `buildUserJwt`) and other context as required — see the [graphql-apollo-server test helper docs](https://github.com/MakerXStudio/graphql-apollo-server#vitest-auth-context-example) for a complete auth fixture example.
+
+`test/graphql.ts`
+
+```ts
+import { buildSubscribeOperation } from '@makerx/graphql-core/testing'
+import { test as baseTest } from './auth'
+
+const createContext = async (jwtPayload?: JwtPayload): Promise<GraphQLContext> => {
+  const user = await findUpdateOrCreateUser(jwtPayload, randomUUID())
+  const baseContext: BaseContext = { user, logger, requestInfo, started: Date.now() }
+  const extraContext = await augmentContext(baseContext)
+  return { ...baseContext, ...extraContext }
+}
+
+export const test = baseTest
+  .extend('schema', { scope: 'worker' }, async ({}) => createSchema())
+  .extend('backgroundJobs', { scope: 'worker' }, backgroundJobsFixture)
+  .extend('executeOperation', { scope: 'worker' }, async ({ schema }, { onCleanup }) => {
+    const server = new ApolloServer<GraphQLContext>({ schema })
+    onCleanup(() => server.stop())
+    return buildExecuteOperation(server, createContext)
+  })
+  .extend('subscribeOperation', { scope: 'worker' }, async ({ schema }) => {
+    return buildSubscribeOperation(schema, createContext)
+  })
+```
+
+#### job-status.subscription.test.ts
+
+The test below uses the `graphql` template-literal tag from [GraphQL-Codegen](https://the-guild.dev/graphql/codegen/docs/getting-started) to produce strongly typed operations.
+
+```ts
+import { describe, expect } from 'vitest'
+import { graphql } from './gql'
+import { test } from '../../../test/graphql'
+
+const jobStatusSubscription = graphql(`
+  subscription JobStatus($jobId: ID!) {
+    jobStatus(jobId: $jobId) {
+      jobId
+      status
+    }
+  }
+`)
+
+describe('jobStatus subscription operation', () => {
+  test('anonymous subscribes fail', async ({ subscribeOperation }) => {
+    await expect(subscribeOperation({ subscription: jobStatusSubscription, variables: { jobId: 'job-1' } })).rejects.toThrow(
+      /Not authenticated/,
+    )
+  })
+
+  test('authenticated subscribers receive events until terminal status', async ({ subscribeOperation, buildUserJwt }) => {
+    const jwt = buildUserJwt()
+    const jobId = randomUUID()
+
+    const iterator = await subscribeOperation({ subscription: jobStatusSubscription, variables: { jobId } }, jwt)
+
+    // app-specific: trigger the events your subscription resolves over
+    // await addJob('demo', { demoPayload: 'subscription-test' }, { jobId })
+
+    const events: JobStatusSubscription[] = []
+    for await (const result of iterator) {
+      if (result.data) events.push(result.data)
+    }
+
+    expect(events.at(-1)?.jobStatus.status).toBe('Completed')
+  })
+})
+```
+
+The first argument is a `TypedSubscribeRequest` (`subscription`, `variables`, `operationName`); any further arguments are forwarded verbatim to the context creation function — in the example above, the optional `JwtPayload` produced by `buildUserJwt()`.
+
+When pairing this helper with [`wrapSubscriptionIterator`](#wrapsubscriptioniterator), `eventIsFinal` will close the subscription once a terminal event arrives, ending the `for await` loop above without manual cleanup.
+
 ## \*Express peer dependency
 
 ApolloServer v3 standardises on the Express request representation.

package/package.json

@@ -4,7 +4,7 @@
     "**"
   ],
   "name": "@makerx/graphql-core",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "private": false,
   "description": "A set of core GraphQL utilities that MakerX uses to build GraphQL APIs",
   "author": "MakerX",
@@ -21,6 +21,7 @@
     "url": "git+https://github.com/MakerXStudio/graphql-core.git"
   },
   "peerDependencies": {
+    "@graphql-typed-document-node/core": ">=3.2.0",
     "@makerx/node-common": ">=1",
     "es-toolkit": ">=1",
     "express": ">=4",
@@ -40,6 +41,9 @@
       "optional": true
     }
   },
+  "overrides": {
+    "esbuild": "^0.28.1"
+  },
   "main": "./index.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -74,6 +78,16 @@
         "types": "./subscriptions/index.d.cts",
         "default": "./subscriptions/index.js"
       }
+    },
+    "./testing": {
+      "import": {
+        "types": "./testing/index.d.mts",
+        "default": "./testing/index.mjs"
+      },
+      "require": {
+        "types": "./testing/index.d.cts",
+        "default": "./testing/index.js"
+      }
     }
   }
 }

package/subscriptions/subscription-iterator.d.cts

@@ -1,3 +1,21 @@
+/**
+ * A function that lazily produces an initial payload. Provided in place of a plain value when the
+ * caller needs the wrapped iterator's subscription to be established *before* the payload is read.
+ *
+ * May return `undefined` (or a promise of it) to indicate "no snapshot" — e.g. a repository
+ * `findOne` that yields nothing — in which case iteration proceeds straight to the wrapped stream.
+ */
+export type InitialPayloadFactory<TEventData> = () => TEventData | TEventData[] | undefined | Promise<TEventData | TEventData[] | undefined>;
+/**
+ * An initial payload: a single event, an array of events, or a factory that produces either (or
+ * `undefined` for "no snapshot").
+ *
+ * Note: the factory form is detected via `typeof initialPayload === 'function'`. If `TEventData` is
+ * itself a callable type, a value-form payload would be misclassified as a factory — wrap such a value
+ * in an array (`[value]`) to disambiguate. GraphQL event payloads are objects, so this is not a concern
+ * in practice.
+ */
+export type InitialPayload<TEventData> = TEventData | TEventData[] | InitialPayloadFactory<TEventData>;
 /**
  * Wraps an async iterator with options for:
  *  - returning an initial payload (e.g. current state)
@@ -8,16 +26,29 @@
  *
  * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
  *
+ * ### Avoiding the subscribe-before-snapshot race
+ *
+ * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the
+ * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the
+ * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that
+ * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this
+ * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory
+ * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead
+ * of dropped, and are delivered immediately after the snapshot.
+ *
  * @param iterator The async iterator to wrap.
- * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.
+ * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an
+ *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the
+ *   "snapshot then stream" pattern so the subscription is established before the snapshot is read.
  * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).
  *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which
- *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event
- *   is checked.
+ *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in
+ *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events
+ *   from the wrapped iterator, every event is checked.
  * @returns An async iterator for the event data.
  */
 export declare function wrapSubscriptionIterator<TEventData>({ iterator: wrapped, initialPayload, eventIsFinal, }: {
     iterator: AsyncIterableIterator<TEventData>;
-    initialPayload?: TEventData | TEventData[];
+    initialPayload?: InitialPayload<TEventData>;
     eventIsFinal?: (event: TEventData) => boolean;
 }): AsyncIterator<TEventData> & AsyncIterable<TEventData>;

package/subscriptions/subscription-iterator.d.mts

@@ -1,3 +1,21 @@
+/**
+ * A function that lazily produces an initial payload. Provided in place of a plain value when the
+ * caller needs the wrapped iterator's subscription to be established *before* the payload is read.
+ *
+ * May return `undefined` (or a promise of it) to indicate "no snapshot" — e.g. a repository
+ * `findOne` that yields nothing — in which case iteration proceeds straight to the wrapped stream.
+ */
+export type InitialPayloadFactory<TEventData> = () => TEventData | TEventData[] | undefined | Promise<TEventData | TEventData[] | undefined>;
+/**
+ * An initial payload: a single event, an array of events, or a factory that produces either (or
+ * `undefined` for "no snapshot").
+ *
+ * Note: the factory form is detected via `typeof initialPayload === 'function'`. If `TEventData` is
+ * itself a callable type, a value-form payload would be misclassified as a factory — wrap such a value
+ * in an array (`[value]`) to disambiguate. GraphQL event payloads are objects, so this is not a concern
+ * in practice.
+ */
+export type InitialPayload<TEventData> = TEventData | TEventData[] | InitialPayloadFactory<TEventData>;
 /**
  * Wraps an async iterator with options for:
  *  - returning an initial payload (e.g. current state)
@@ -8,16 +26,29 @@
  *
  * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
  *
+ * ### Avoiding the subscribe-before-snapshot race
+ *
+ * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the
+ * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the
+ * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that
+ * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this
+ * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory
+ * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead
+ * of dropped, and are delivered immediately after the snapshot.
+ *
  * @param iterator The async iterator to wrap.
- * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.
+ * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an
+ *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the
+ *   "snapshot then stream" pattern so the subscription is established before the snapshot is read.
  * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).
  *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which
- *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event
- *   is checked.
+ *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in
+ *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events
+ *   from the wrapped iterator, every event is checked.
  * @returns An async iterator for the event data.
  */
 export declare function wrapSubscriptionIterator<TEventData>({ iterator: wrapped, initialPayload, eventIsFinal, }: {
     iterator: AsyncIterableIterator<TEventData>;
-    initialPayload?: TEventData | TEventData[];
+    initialPayload?: InitialPayload<TEventData>;
     eventIsFinal?: (event: TEventData) => boolean;
 }): AsyncIterator<TEventData> & AsyncIterable<TEventData>;

package/subscriptions/subscription-iterator.d.ts

@@ -1,3 +1,21 @@
+/**
+ * A function that lazily produces an initial payload. Provided in place of a plain value when the
+ * caller needs the wrapped iterator's subscription to be established *before* the payload is read.
+ *
+ * May return `undefined` (or a promise of it) to indicate "no snapshot" — e.g. a repository
+ * `findOne` that yields nothing — in which case iteration proceeds straight to the wrapped stream.
+ */
+export type InitialPayloadFactory<TEventData> = () => TEventData | TEventData[] | undefined | Promise<TEventData | TEventData[] | undefined>;
+/**
+ * An initial payload: a single event, an array of events, or a factory that produces either (or
+ * `undefined` for "no snapshot").
+ *
+ * Note: the factory form is detected via `typeof initialPayload === 'function'`. If `TEventData` is
+ * itself a callable type, a value-form payload would be misclassified as a factory — wrap such a value
+ * in an array (`[value]`) to disambiguate. GraphQL event payloads are objects, so this is not a concern
+ * in practice.
+ */
+export type InitialPayload<TEventData> = TEventData | TEventData[] | InitialPayloadFactory<TEventData>;
 /**
  * Wraps an async iterator with options for:
  *  - returning an initial payload (e.g. current state)
@@ -8,16 +26,29 @@
  *
  * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
  *
+ * ### Avoiding the subscribe-before-snapshot race
+ *
+ * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the
+ * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the
+ * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that
+ * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this
+ * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory
+ * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead
+ * of dropped, and are delivered immediately after the snapshot.
+ *
  * @param iterator The async iterator to wrap.
- * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.
+ * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an
+ *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the
+ *   "snapshot then stream" pattern so the subscription is established before the snapshot is read.
  * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).
  *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which
- *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event
- *   is checked.
+ *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in
+ *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events
+ *   from the wrapped iterator, every event is checked.
  * @returns An async iterator for the event data.
  */
 export declare function wrapSubscriptionIterator<TEventData>({ iterator: wrapped, initialPayload, eventIsFinal, }: {
     iterator: AsyncIterableIterator<TEventData>;
-    initialPayload?: TEventData | TEventData[];
+    initialPayload?: InitialPayload<TEventData>;
     eventIsFinal?: (event: TEventData) => boolean;
 }): AsyncIterator<TEventData> & AsyncIterable<TEventData>;

package/subscriptions/subscription-iterator.js

@@ -10,30 +10,74 @@
  *
  * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
  *
+ * ### Avoiding the subscribe-before-snapshot race
+ *
+ * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the
+ * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the
+ * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that
+ * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this
+ * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory
+ * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead
+ * of dropped, and are delivered immediately after the snapshot.
+ *
  * @param iterator The async iterator to wrap.
- * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.
+ * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an
+ *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the
+ *   "snapshot then stream" pattern so the subscription is established before the snapshot is read.
  * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).
  *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which
- *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event
- *   is checked.
+ *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in
+ *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events
+ *   from the wrapped iterator, every event is checked.
  * @returns An async iterator for the event data.
  */
 function wrapSubscriptionIterator({ iterator: wrapped, initialPayload, eventIsFinal, }) {
     let done = false;
-    const initialQueue = initialPayload === undefined ? [] : Array.isArray(initialPayload) ? [...initialPayload] : [initialPayload];
+    const toQueue = (payload) => payload === undefined ? [] : Array.isArray(payload) ? [...payload] : [payload];
+    // Factory form: the caller wants the channel subscription established BEFORE the initial payload
+    // (typically a DB snapshot) is read. The wrapped iterator subscribes on its first `next()`, so pull it
+    // eagerly *now*. The resulting event is buffered and delivered after the initial payload drains; the
+    // factory (and therefore the snapshot read) runs lazily on the first consumer `next()`, after the
+    // subscription is already kicked.
+    const isFactory = typeof initialPayload === 'function';
+    let eagerPull = isFactory ? wrapped.next() : undefined;
+    // Value form: build the queue eagerly, exactly as before. Factory form: resolved lazily on first next().
+    let initialQueue = isFactory ? undefined : toQueue(initialPayload);
+    // Hand back the eagerly-pulled (= already-subscribed) event the first time, then defer to wrapped.next().
+    const consumeWrapped = () => {
+        if (eagerPull) {
+            const pull = eagerPull;
+            eagerPull = undefined;
+            return pull;
+        }
+        return wrapped.next();
+    };
+    // Abandon the eager pull without leaking an unhandled rejection. Only reached via early teardown
+    // (return/throw before the buffered event is consumed) or the eventIsFinal short-circuit on the
+    // snapshot — neither consumes the buffered event, and wrapped.return() tears down the kicked subscription.
+    const discardEagerPull = () => {
+        if (eagerPull) {
+            eagerPull.catch(() => { });
+            eagerPull = undefined;
+        }
+    };
     const iterator = {
         next: async () => {
             if (done)
                 return { done: true, value: undefined };
+            if (initialQueue === undefined) {
+                initialQueue = toQueue(await initialPayload());
+            }
             if (initialQueue.length > 0) {
                 const value = initialQueue.shift();
                 if (initialQueue.length === 0 && eventIsFinal && eventIsFinal(value)) {
                     done = true;
+                    discardEagerPull(); // tear down the redundant eager subscription, if any
                     await wrapped.return?.();
                 }
                 return { done: false, value };
             }
-            const next = await wrapped.next();
+            const next = await consumeWrapped();
             if (!next.done && eventIsFinal && eventIsFinal(next.value)) {
                 done = true;
                 await wrapped.return?.();
@@ -42,14 +86,18 @@ function wrapSubscriptionIterator({ iterator: wrapped, initialPayload, eventIsFi
         },
         return: async (value) => {
             done = true;
-            initialQueue.length = 0;
+            if (initialQueue)
+                initialQueue.length = 0;
+            discardEagerPull();
             if (wrapped.return)
                 return wrapped.return(value);
             return { done: true, value: value };
         },
         throw: async (err) => {
             done = true;
-            initialQueue.length = 0;
+            if (initialQueue)
+                initialQueue.length = 0;
+            discardEagerPull();
             if (wrapped.throw)
                 return wrapped.throw(err);
             throw err;

package/subscriptions/subscription-iterator.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscription-iterator.js","sources":["../../src/subscriptions/subscription-iterator.ts"],"sourcesContent":["/**\n * Wraps an async iterator with options for:\n *  - returning an initial payload (e.g. current state)\n *  - eagerly ending iteration when a final event is received\n *\n * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,\n *  by providing an initial payload to be immediately returned, before subsequent events stream in.\n *\n * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.\n *\n * @param iterator The async iterator to wrap.\n * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.\n * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).\n *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which\n *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event\n *   is checked.\n * @returns An async iterator for the event data.\n */\nexport function wrapSubscriptionIterator<TEventData>({\n  iterator: wrapped,\n  initialPayload,\n  eventIsFinal,\n}: {\n  iterator: AsyncIterableIterator<TEventData>\n  initialPayload?: TEventData | TEventData[]\n  eventIsFinal?: (event: TEventData) => boolean\n}): AsyncIterator<TEventData> & AsyncIterable<TEventData> {\n  let done = false\n  const initialQueue: TEventData[] =\n    initialPayload === undefined ? [] : Array.isArray(initialPayload) ? [...initialPayload] : [initialPayload]\n\n  const iterator: AsyncIterator<TEventData> = {\n    next: async () => {\n      if (done) return { done: true, value: undefined }\n\n      if (initialQueue.length > 0) {\n        const value = initialQueue.shift() as TEventData\n        if (initialQueue.length === 0 && eventIsFinal && eventIsFinal(value)) {\n          done = true\n          await wrapped.return?.()\n        }\n        return { done: false, value }\n      }\n\n      const next = await wrapped.next()\n      if (!next.done && eventIsFinal && eventIsFinal(next.value)) {\n        done = true\n        await wrapped.return?.()\n      }\n      return next\n    },\n    return: async (value) => {\n      done = true\n      initialQueue.length = 0\n      if (wrapped.return) return wrapped.return(value)\n      return { done: true, value: value as TEventData }\n    },\n    throw: async (err) => {\n      done = true\n      initialQueue.length = 0\n      if (wrapped.throw) return wrapped.throw(err)\n      throw err\n    },\n  }\n\n  return { ...iterator, [Symbol.asyncIterator]: () => iterator }\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;AAiBG;AACG,SAAU,wBAAwB,CAAa,EACnD,QAAQ,EAAE,OAAO,EACjB,cAAc,EACd,YAAY,GAKb,EAAA;IACC,IAAI,IAAI,GAAG,KAAK;AAChB,IAAA,MAAM,YAAY,GAChB,cAAc,KAAK,SAAS,GAAG,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC;AAE5G,IAAA,MAAM,QAAQ,GAA8B;QAC1C,IAAI,EAAE,YAAW;AACf,YAAA,IAAI,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;AAEjD,YAAA,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE;AAC3B,gBAAA,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAgB;AAChD,gBAAA,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE;oBACpE,IAAI,GAAG,IAAI;AACX,oBAAA,MAAM,OAAO,CAAC,MAAM,IAAI;gBAC1B;AACA,gBAAA,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE;YAC/B;AAEA,YAAA,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE;AACjC,YAAA,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;gBAC1D,IAAI,GAAG,IAAI;AACX,gBAAA,MAAM,OAAO,CAAC,MAAM,IAAI;YAC1B;AACA,YAAA,OAAO,IAAI;QACb,CAAC;AACD,QAAA,MAAM,EAAE,OAAO,KAAK,KAAI;YACtB,IAAI,GAAG,IAAI;AACX,YAAA,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,IAAI,OAAO,CAAC,MAAM;AAAE,gBAAA,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;YAChD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAmB,EAAE;QACnD,CAAC;AACD,QAAA,KAAK,EAAE,OAAO,GAAG,KAAI;YACnB,IAAI,GAAG,IAAI;AACX,YAAA,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,IAAI,OAAO,CAAC,KAAK;AAAE,gBAAA,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;AAC5C,YAAA,MAAM,GAAG;QACX,CAAC;KACF;AAED,IAAA,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC,MAAM,CAAC,aAAa,GAAG,MAAM,QAAQ,EAAE;AAChE;;;;"}
+{"version":3,"file":"subscription-iterator.js","sources":["../../src/subscriptions/subscription-iterator.ts"],"sourcesContent":["/**\n * A function that lazily produces an initial payload. Provided in place of a plain value when the\n * caller needs the wrapped iterator's subscription to be established *before* the payload is read.\n *\n * May return `undefined` (or a promise of it) to indicate \"no snapshot\" — e.g. a repository\n * `findOne` that yields nothing — in which case iteration proceeds straight to the wrapped stream.\n */\nexport type InitialPayloadFactory<TEventData> = () => TEventData | TEventData[] | undefined | Promise<TEventData | TEventData[] | undefined>\n\n/**\n * An initial payload: a single event, an array of events, or a factory that produces either (or\n * `undefined` for \"no snapshot\").\n *\n * Note: the factory form is detected via `typeof initialPayload === 'function'`. If `TEventData` is\n * itself a callable type, a value-form payload would be misclassified as a factory — wrap such a value\n * in an array (`[value]`) to disambiguate. GraphQL event payloads are objects, so this is not a concern\n * in practice.\n */\nexport type InitialPayload<TEventData> = TEventData | TEventData[] | InitialPayloadFactory<TEventData>\n\n/**\n * Wraps an async iterator with options for:\n *  - returning an initial payload (e.g. current state)\n *  - eagerly ending iteration when a final event is received\n *\n * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,\n *  by providing an initial payload to be immediately returned, before subsequent events stream in.\n *\n * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.\n *\n * ### Avoiding the subscribe-before-snapshot race\n *\n * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the\n * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the\n * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that\n * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this\n * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory\n * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead\n * of dropped, and are delivered immediately after the snapshot.\n *\n * @param iterator The async iterator to wrap.\n * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an\n *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the\n *   \"snapshot then stream\" pattern so the subscription is established before the snapshot is read.\n * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).\n *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which\n *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in\n *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events\n *   from the wrapped iterator, every event is checked.\n * @returns An async iterator for the event data.\n */\nexport function wrapSubscriptionIterator<TEventData>({\n  iterator: wrapped,\n  initialPayload,\n  eventIsFinal,\n}: {\n  iterator: AsyncIterableIterator<TEventData>\n  initialPayload?: InitialPayload<TEventData>\n  eventIsFinal?: (event: TEventData) => boolean\n}): AsyncIterator<TEventData> & AsyncIterable<TEventData> {\n  let done = false\n\n  const toQueue = (payload: TEventData | TEventData[] | undefined): TEventData[] =>\n    payload === undefined ? [] : Array.isArray(payload) ? [...payload] : [payload]\n\n  // Factory form: the caller wants the channel subscription established BEFORE the initial payload\n  // (typically a DB snapshot) is read. The wrapped iterator subscribes on its first `next()`, so pull it\n  // eagerly *now*. The resulting event is buffered and delivered after the initial payload drains; the\n  // factory (and therefore the snapshot read) runs lazily on the first consumer `next()`, after the\n  // subscription is already kicked.\n  const isFactory = typeof initialPayload === 'function'\n  let eagerPull: Promise<IteratorResult<TEventData>> | undefined = isFactory ? wrapped.next() : undefined\n\n  // Value form: build the queue eagerly, exactly as before. Factory form: resolved lazily on first next().\n  let initialQueue: TEventData[] | undefined = isFactory ? undefined : toQueue(initialPayload as TEventData | TEventData[] | undefined)\n\n  // Hand back the eagerly-pulled (= already-subscribed) event the first time, then defer to wrapped.next().\n  const consumeWrapped = (): Promise<IteratorResult<TEventData>> => {\n    if (eagerPull) {\n      const pull = eagerPull\n      eagerPull = undefined\n      return pull\n    }\n    return wrapped.next()\n  }\n\n  // Abandon the eager pull without leaking an unhandled rejection. Only reached via early teardown\n  // (return/throw before the buffered event is consumed) or the eventIsFinal short-circuit on the\n  // snapshot — neither consumes the buffered event, and wrapped.return() tears down the kicked subscription.\n  const discardEagerPull = () => {\n    if (eagerPull) {\n      eagerPull.catch(() => {})\n      eagerPull = undefined\n    }\n  }\n\n  const iterator: AsyncIterator<TEventData> = {\n    next: async () => {\n      if (done) return { done: true, value: undefined }\n\n      if (initialQueue === undefined) {\n        initialQueue = toQueue(await (initialPayload as InitialPayloadFactory<TEventData>)())\n      }\n\n      if (initialQueue.length > 0) {\n        const value = initialQueue.shift() as TEventData\n        if (initialQueue.length === 0 && eventIsFinal && eventIsFinal(value)) {\n          done = true\n          discardEagerPull() // tear down the redundant eager subscription, if any\n          await wrapped.return?.()\n        }\n        return { done: false, value }\n      }\n\n      const next = await consumeWrapped()\n      if (!next.done && eventIsFinal && eventIsFinal(next.value)) {\n        done = true\n        await wrapped.return?.()\n      }\n      return next\n    },\n    return: async (value) => {\n      done = true\n      if (initialQueue) initialQueue.length = 0\n      discardEagerPull()\n      if (wrapped.return) return wrapped.return(value)\n      return { done: true, value: value as TEventData }\n    },\n    throw: async (err) => {\n      done = true\n      if (initialQueue) initialQueue.length = 0\n      discardEagerPull()\n      if (wrapped.throw) return wrapped.throw(err)\n      throw err\n    },\n  }\n\n  return { ...iterator, [Symbol.asyncIterator]: () => iterator }\n}\n"],"names":[],"mappings":"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"}

package/subscriptions/subscription-iterator.mjs

@@ -8,30 +8,74 @@
  *
  * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
  *
+ * ### Avoiding the subscribe-before-snapshot race
+ *
+ * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the
+ * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the
+ * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that
+ * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this
+ * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory
+ * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead
+ * of dropped, and are delivered immediately after the snapshot.
+ *
  * @param iterator The async iterator to wrap.
- * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.
+ * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an
+ *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the
+ *   "snapshot then stream" pattern so the subscription is established before the snapshot is read.
  * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).
  *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which
- *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event
- *   is checked.
+ *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in
+ *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events
+ *   from the wrapped iterator, every event is checked.
  * @returns An async iterator for the event data.
  */
 function wrapSubscriptionIterator({ iterator: wrapped, initialPayload, eventIsFinal, }) {
     let done = false;
-    const initialQueue = initialPayload === undefined ? [] : Array.isArray(initialPayload) ? [...initialPayload] : [initialPayload];
+    const toQueue = (payload) => payload === undefined ? [] : Array.isArray(payload) ? [...payload] : [payload];
+    // Factory form: the caller wants the channel subscription established BEFORE the initial payload
+    // (typically a DB snapshot) is read. The wrapped iterator subscribes on its first `next()`, so pull it
+    // eagerly *now*. The resulting event is buffered and delivered after the initial payload drains; the
+    // factory (and therefore the snapshot read) runs lazily on the first consumer `next()`, after the
+    // subscription is already kicked.
+    const isFactory = typeof initialPayload === 'function';
+    let eagerPull = isFactory ? wrapped.next() : undefined;
+    // Value form: build the queue eagerly, exactly as before. Factory form: resolved lazily on first next().
+    let initialQueue = isFactory ? undefined : toQueue(initialPayload);
+    // Hand back the eagerly-pulled (= already-subscribed) event the first time, then defer to wrapped.next().
+    const consumeWrapped = () => {
+        if (eagerPull) {
+            const pull = eagerPull;
+            eagerPull = undefined;
+            return pull;
+        }
+        return wrapped.next();
+    };
+    // Abandon the eager pull without leaking an unhandled rejection. Only reached via early teardown
+    // (return/throw before the buffered event is consumed) or the eventIsFinal short-circuit on the
+    // snapshot — neither consumes the buffered event, and wrapped.return() tears down the kicked subscription.
+    const discardEagerPull = () => {
+        if (eagerPull) {
+            eagerPull.catch(() => { });
+            eagerPull = undefined;
+        }
+    };
     const iterator = {
         next: async () => {
             if (done)
                 return { done: true, value: undefined };
+            if (initialQueue === undefined) {
+                initialQueue = toQueue(await initialPayload());
+            }
             if (initialQueue.length > 0) {
                 const value = initialQueue.shift();
                 if (initialQueue.length === 0 && eventIsFinal && eventIsFinal(value)) {
                     done = true;
+                    discardEagerPull(); // tear down the redundant eager subscription, if any
                     await wrapped.return?.();
                 }
                 return { done: false, value };
             }
-            const next = await wrapped.next();
+            const next = await consumeWrapped();
             if (!next.done && eventIsFinal && eventIsFinal(next.value)) {
                 done = true;
                 await wrapped.return?.();
@@ -40,14 +84,18 @@ function wrapSubscriptionIterator({ iterator: wrapped, initialPayload, eventIsFi
         },
         return: async (value) => {
             done = true;
-            initialQueue.length = 0;
+            if (initialQueue)
+                initialQueue.length = 0;
+            discardEagerPull();
             if (wrapped.return)
                 return wrapped.return(value);
             return { done: true, value: value };
         },
         throw: async (err) => {
             done = true;
-            initialQueue.length = 0;
+            if (initialQueue)
+                initialQueue.length = 0;
+            discardEagerPull();
             if (wrapped.throw)
                 return wrapped.throw(err);
             throw err;

package/subscriptions/subscription-iterator.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"subscription-iterator.mjs","sources":["../../src/subscriptions/subscription-iterator.ts"],"sourcesContent":["/**\n * Wraps an async iterator with options for:\n *  - returning an initial payload (e.g. current state)\n *  - eagerly ending iteration when a final event is received\n *\n * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,\n *  by providing an initial payload to be immediately returned, before subsequent events stream in.\n *\n * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.\n *\n * @param iterator The async iterator to wrap.\n * @param initialPayload An optional initial payload to return on the first iteration. May be a single event or an array.\n * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).\n *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which\n *   the wrapped iterator is closed without ever being pulled from. For events from the wrapped iterator, every event\n *   is checked.\n * @returns An async iterator for the event data.\n */\nexport function wrapSubscriptionIterator<TEventData>({\n  iterator: wrapped,\n  initialPayload,\n  eventIsFinal,\n}: {\n  iterator: AsyncIterableIterator<TEventData>\n  initialPayload?: TEventData | TEventData[]\n  eventIsFinal?: (event: TEventData) => boolean\n}): AsyncIterator<TEventData> & AsyncIterable<TEventData> {\n  let done = false\n  const initialQueue: TEventData[] =\n    initialPayload === undefined ? [] : Array.isArray(initialPayload) ? [...initialPayload] : [initialPayload]\n\n  const iterator: AsyncIterator<TEventData> = {\n    next: async () => {\n      if (done) return { done: true, value: undefined }\n\n      if (initialQueue.length > 0) {\n        const value = initialQueue.shift() as TEventData\n        if (initialQueue.length === 0 && eventIsFinal && eventIsFinal(value)) {\n          done = true\n          await wrapped.return?.()\n        }\n        return { done: false, value }\n      }\n\n      const next = await wrapped.next()\n      if (!next.done && eventIsFinal && eventIsFinal(next.value)) {\n        done = true\n        await wrapped.return?.()\n      }\n      return next\n    },\n    return: async (value) => {\n      done = true\n      initialQueue.length = 0\n      if (wrapped.return) return wrapped.return(value)\n      return { done: true, value: value as TEventData }\n    },\n    throw: async (err) => {\n      done = true\n      initialQueue.length = 0\n      if (wrapped.throw) return wrapped.throw(err)\n      throw err\n    },\n  }\n\n  return { ...iterator, [Symbol.asyncIterator]: () => iterator }\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;AAiBG;AACG,SAAU,wBAAwB,CAAa,EACnD,QAAQ,EAAE,OAAO,EACjB,cAAc,EACd,YAAY,GAKb,EAAA;IACC,IAAI,IAAI,GAAG,KAAK;AAChB,IAAA,MAAM,YAAY,GAChB,cAAc,KAAK,SAAS,GAAG,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC;AAE5G,IAAA,MAAM,QAAQ,GAA8B;QAC1C,IAAI,EAAE,YAAW;AACf,YAAA,IAAI,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE;AAEjD,YAAA,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE;AAC3B,gBAAA,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAgB;AAChD,gBAAA,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE;oBACpE,IAAI,GAAG,IAAI;AACX,oBAAA,MAAM,OAAO,CAAC,MAAM,IAAI;gBAC1B;AACA,gBAAA,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE;YAC/B;AAEA,YAAA,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE;AACjC,YAAA,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,YAAY,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;gBAC1D,IAAI,GAAG,IAAI;AACX,gBAAA,MAAM,OAAO,CAAC,MAAM,IAAI;YAC1B;AACA,YAAA,OAAO,IAAI;QACb,CAAC;AACD,QAAA,MAAM,EAAE,OAAO,KAAK,KAAI;YACtB,IAAI,GAAG,IAAI;AACX,YAAA,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,IAAI,OAAO,CAAC,MAAM;AAAE,gBAAA,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;YAChD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAmB,EAAE;QACnD,CAAC;AACD,QAAA,KAAK,EAAE,OAAO,GAAG,KAAI;YACnB,IAAI,GAAG,IAAI;AACX,YAAA,YAAY,CAAC,MAAM,GAAG,CAAC;YACvB,IAAI,OAAO,CAAC,KAAK;AAAE,gBAAA,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;AAC5C,YAAA,MAAM,GAAG;QACX,CAAC;KACF;AAED,IAAA,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC,MAAM,CAAC,aAAa,GAAG,MAAM,QAAQ,EAAE;AAChE;;;;"}
+{"version":3,"file":"subscription-iterator.mjs","sources":["../../src/subscriptions/subscription-iterator.ts"],"sourcesContent":["/**\n * A function that lazily produces an initial payload. Provided in place of a plain value when the\n * caller needs the wrapped iterator's subscription to be established *before* the payload is read.\n *\n * May return `undefined` (or a promise of it) to indicate \"no snapshot\" — e.g. a repository\n * `findOne` that yields nothing — in which case iteration proceeds straight to the wrapped stream.\n */\nexport type InitialPayloadFactory<TEventData> = () => TEventData | TEventData[] | undefined | Promise<TEventData | TEventData[] | undefined>\n\n/**\n * An initial payload: a single event, an array of events, or a factory that produces either (or\n * `undefined` for \"no snapshot\").\n *\n * Note: the factory form is detected via `typeof initialPayload === 'function'`. If `TEventData` is\n * itself a callable type, a value-form payload would be misclassified as a factory — wrap such a value\n * in an array (`[value]`) to disambiguate. GraphQL event payloads are objects, so this is not a concern\n * in practice.\n */\nexport type InitialPayload<TEventData> = TEventData | TEventData[] | InitialPayloadFactory<TEventData>\n\n/**\n * Wraps an async iterator with options for:\n *  - returning an initial payload (e.g. current state)\n *  - eagerly ending iteration when a final event is received\n *\n * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,\n *  by providing an initial payload to be immediately returned, before subsequent events stream in.\n *\n * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.\n *\n * ### Avoiding the subscribe-before-snapshot race\n *\n * `graphql-subscriptions`' iterator subscribes to its channel lazily, on its first `next()`. If you read the\n * snapshot (the initial payload) *before* constructing/pulling the iterator, any event published between the\n * snapshot read and the subscription going live is lost — and missing from the snapshot too. To close that\n * window, pass `initialPayload` as a **factory** (`() => ... | Promise<...>`). When a factory is supplied this\n * helper eagerly pulls the wrapped iterator once (establishing the subscription) *before* invoking the factory\n * to read the snapshot; events fired during the snapshot read are then buffered by the wrapped iterator instead\n * of dropped, and are delivered immediately after the snapshot.\n *\n * @param iterator The async iterator to wrap.\n * @param initialPayload An optional initial payload to return on the first iteration. May be a single event, an\n *   array, or a factory (`() => event | event[] | Promise<event | event[]>`). Prefer the factory form for the\n *   \"snapshot then stream\" pattern so the subscription is established before the snapshot is read.\n * @param eventIsFinal An optional function to determine if an event is final (and iteration should end).\n *   The full `initialPayload` is always yielded; `eventIsFinal` is only checked against its final entry, after which\n *   the wrapped iterator is closed (`wrapped.return()`). In the value form it is closed without ever being pulled; in\n *   the factory form the single eager pull used to establish the subscription is discarded on teardown. For events\n *   from the wrapped iterator, every event is checked.\n * @returns An async iterator for the event data.\n */\nexport function wrapSubscriptionIterator<TEventData>({\n  iterator: wrapped,\n  initialPayload,\n  eventIsFinal,\n}: {\n  iterator: AsyncIterableIterator<TEventData>\n  initialPayload?: InitialPayload<TEventData>\n  eventIsFinal?: (event: TEventData) => boolean\n}): AsyncIterator<TEventData> & AsyncIterable<TEventData> {\n  let done = false\n\n  const toQueue = (payload: TEventData | TEventData[] | undefined): TEventData[] =>\n    payload === undefined ? [] : Array.isArray(payload) ? [...payload] : [payload]\n\n  // Factory form: the caller wants the channel subscription established BEFORE the initial payload\n  // (typically a DB snapshot) is read. The wrapped iterator subscribes on its first `next()`, so pull it\n  // eagerly *now*. The resulting event is buffered and delivered after the initial payload drains; the\n  // factory (and therefore the snapshot read) runs lazily on the first consumer `next()`, after the\n  // subscription is already kicked.\n  const isFactory = typeof initialPayload === 'function'\n  let eagerPull: Promise<IteratorResult<TEventData>> | undefined = isFactory ? wrapped.next() : undefined\n\n  // Value form: build the queue eagerly, exactly as before. Factory form: resolved lazily on first next().\n  let initialQueue: TEventData[] | undefined = isFactory ? undefined : toQueue(initialPayload as TEventData | TEventData[] | undefined)\n\n  // Hand back the eagerly-pulled (= already-subscribed) event the first time, then defer to wrapped.next().\n  const consumeWrapped = (): Promise<IteratorResult<TEventData>> => {\n    if (eagerPull) {\n      const pull = eagerPull\n      eagerPull = undefined\n      return pull\n    }\n    return wrapped.next()\n  }\n\n  // Abandon the eager pull without leaking an unhandled rejection. Only reached via early teardown\n  // (return/throw before the buffered event is consumed) or the eventIsFinal short-circuit on the\n  // snapshot — neither consumes the buffered event, and wrapped.return() tears down the kicked subscription.\n  const discardEagerPull = () => {\n    if (eagerPull) {\n      eagerPull.catch(() => {})\n      eagerPull = undefined\n    }\n  }\n\n  const iterator: AsyncIterator<TEventData> = {\n    next: async () => {\n      if (done) return { done: true, value: undefined }\n\n      if (initialQueue === undefined) {\n        initialQueue = toQueue(await (initialPayload as InitialPayloadFactory<TEventData>)())\n      }\n\n      if (initialQueue.length > 0) {\n        const value = initialQueue.shift() as TEventData\n        if (initialQueue.length === 0 && eventIsFinal && eventIsFinal(value)) {\n          done = true\n          discardEagerPull() // tear down the redundant eager subscription, if any\n          await wrapped.return?.()\n        }\n        return { done: false, value }\n      }\n\n      const next = await consumeWrapped()\n      if (!next.done && eventIsFinal && eventIsFinal(next.value)) {\n        done = true\n        await wrapped.return?.()\n      }\n      return next\n    },\n    return: async (value) => {\n      done = true\n      if (initialQueue) initialQueue.length = 0\n      discardEagerPull()\n      if (wrapped.return) return wrapped.return(value)\n      return { done: true, value: value as TEventData }\n    },\n    throw: async (err) => {\n      done = true\n      if (initialQueue) initialQueue.length = 0\n      discardEagerPull()\n      if (wrapped.throw) return wrapped.throw(err)\n      throw err\n    },\n  }\n\n  return { ...iterator, [Symbol.asyncIterator]: () => iterator }\n}\n"],"names":[],"mappings":"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"}

package/testing/index.d.cts

@@ -0,0 +1 @@
+export * from './subscribe-operation';

package/testing/index.d.mts

@@ -0,0 +1 @@
+export * from './subscribe-operation.mjs';

package/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './subscribe-operation';

package/testing/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+var subscribeOperation = require('./subscribe-operation.js');
+
+
+
+exports.buildSubscribeOperation = subscribeOperation.buildSubscribeOperation;
+//# sourceMappingURL=index.js.map

package/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/testing/index.mjs

@@ -0,0 +1,2 @@
+export { buildSubscribeOperation } from './subscribe-operation.mjs';
+//# sourceMappingURL=index.mjs.map

package/testing/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/testing/subscribe-operation.d.cts

@@ -0,0 +1,31 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type DocumentNode, type ExecutionResult, type GraphQLSchema } from 'graphql';
+import type { AnyGraphqlContext } from '../context';
+export type VariableValues = {
+    [key: string]: any;
+};
+export type TypedSubscribeRequest<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues> = {
+    subscription: string | DocumentNode | TypedDocumentNode<TData, TVariables>;
+    variables?: TVariables;
+    operationName?: string;
+};
+/**
+ * Returns a `subscribeOperation` test helper for the provided schema and context creation function.
+ *
+ * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,
+ * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads
+ * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in
+ * `@makerx/graphql-apollo-server/testing`.
+ *
+ * The returned function:
+ * - is strongly typed to the GraphQL context
+ * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing
+ * - forwards any additional arguments to the supplied context creation function
+ * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls
+ * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors
+ *
+ * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).
+ * @param createContext A context creation function. Any args supplied after the request are forwarded to it,
+ *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).
+ */
+export declare function buildSubscribeOperation<TContext extends AnyGraphqlContext, TContextFunction extends (...args: any) => Promise<TContext>>(schema: GraphQLSchema | (() => Promise<GraphQLSchema>), createContext: TContextFunction): <TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues>({ subscription, variables, operationName }: TypedSubscribeRequest<TData, TVariables>, ...createContextArgs: Parameters<TContextFunction>) => Promise<AsyncIterableIterator<ExecutionResult<TData>>>;

package/testing/subscribe-operation.d.mts

@@ -0,0 +1,31 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type DocumentNode, type ExecutionResult, type GraphQLSchema } from 'graphql';
+import type { AnyGraphqlContext } from '../context.mjs';
+export type VariableValues = {
+    [key: string]: any;
+};
+export type TypedSubscribeRequest<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues> = {
+    subscription: string | DocumentNode | TypedDocumentNode<TData, TVariables>;
+    variables?: TVariables;
+    operationName?: string;
+};
+/**
+ * Returns a `subscribeOperation` test helper for the provided schema and context creation function.
+ *
+ * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,
+ * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads
+ * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in
+ * `@makerx/graphql-apollo-server/testing`.
+ *
+ * The returned function:
+ * - is strongly typed to the GraphQL context
+ * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing
+ * - forwards any additional arguments to the supplied context creation function
+ * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls
+ * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors
+ *
+ * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).
+ * @param createContext A context creation function. Any args supplied after the request are forwarded to it,
+ *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).
+ */
+export declare function buildSubscribeOperation<TContext extends AnyGraphqlContext, TContextFunction extends (...args: any) => Promise<TContext>>(schema: GraphQLSchema | (() => Promise<GraphQLSchema>), createContext: TContextFunction): <TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues>({ subscription, variables, operationName }: TypedSubscribeRequest<TData, TVariables>, ...createContextArgs: Parameters<TContextFunction>) => Promise<AsyncIterableIterator<ExecutionResult<TData>>>;

package/testing/subscribe-operation.d.ts

@@ -0,0 +1,31 @@
+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
+import { type DocumentNode, type ExecutionResult, type GraphQLSchema } from 'graphql';
+import type { AnyGraphqlContext } from '../context';
+export type VariableValues = {
+    [key: string]: any;
+};
+export type TypedSubscribeRequest<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues> = {
+    subscription: string | DocumentNode | TypedDocumentNode<TData, TVariables>;
+    variables?: TVariables;
+    operationName?: string;
+};
+/**
+ * Returns a `subscribeOperation` test helper for the provided schema and context creation function.
+ *
+ * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,
+ * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads
+ * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in
+ * `@makerx/graphql-apollo-server/testing`.
+ *
+ * The returned function:
+ * - is strongly typed to the GraphQL context
+ * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing
+ * - forwards any additional arguments to the supplied context creation function
+ * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls
+ * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors
+ *
+ * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).
+ * @param createContext A context creation function. Any args supplied after the request are forwarded to it,
+ *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).
+ */
+export declare function buildSubscribeOperation<TContext extends AnyGraphqlContext, TContextFunction extends (...args: any) => Promise<TContext>>(schema: GraphQLSchema | (() => Promise<GraphQLSchema>), createContext: TContextFunction): <TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues>({ subscription, variables, operationName }: TypedSubscribeRequest<TData, TVariables>, ...createContextArgs: Parameters<TContextFunction>) => Promise<AsyncIterableIterator<ExecutionResult<TData>>>;

package/testing/subscribe-operation.js

@@ -0,0 +1,43 @@
+'use strict';
+
+var graphql = require('graphql');
+
+/**
+ * Returns a `subscribeOperation` test helper for the provided schema and context creation function.
+ *
+ * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,
+ * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads
+ * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in
+ * `@makerx/graphql-apollo-server/testing`.
+ *
+ * The returned function:
+ * - is strongly typed to the GraphQL context
+ * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing
+ * - forwards any additional arguments to the supplied context creation function
+ * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls
+ * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors
+ *
+ * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).
+ * @param createContext A context creation function. Any args supplied after the request are forwarded to it,
+ *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).
+ */
+function buildSubscribeOperation(schema, createContext) {
+    return async function subscribeOperation({ subscription, variables, operationName }, ...createContextArgs) {
+        const resolvedSchema = typeof schema === 'function' ? await schema() : schema;
+        const document = typeof subscription === 'string' ? graphql.parse(subscription) : subscription;
+        const contextValue = await createContext(...createContextArgs);
+        const result = await graphql.subscribe({
+            schema: resolvedSchema,
+            document,
+            contextValue,
+            variableValues: variables,
+            operationName,
+        });
+        if (Symbol.asyncIterator in result)
+            return result;
+        throw new Error(`Subscription did not produce an iterator: ${JSON.stringify(result.errors)}`);
+    };
+}
+
+exports.buildSubscribeOperation = buildSubscribeOperation;
+//# sourceMappingURL=subscribe-operation.js.map

package/testing/subscribe-operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe-operation.js","sources":["../../src/testing/subscribe-operation.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@graphql-typed-document-node/core'\nimport { parse, subscribe, type DocumentNode, type ExecutionResult, type GraphQLSchema } from 'graphql'\nimport type { AnyGraphqlContext } from '../context'\n\nexport type VariableValues = { [key: string]: any }\n\nexport type TypedSubscribeRequest<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues> = {\n  subscription: string | DocumentNode | TypedDocumentNode<TData, TVariables>\n  variables?: TVariables\n  operationName?: string\n}\n\n/**\n * Returns a `subscribeOperation` test helper for the provided schema and context creation function.\n *\n * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,\n * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads\n * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in\n * `@makerx/graphql-apollo-server/testing`.\n *\n * The returned function:\n * - is strongly typed to the GraphQL context\n * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing\n * - forwards any additional arguments to the supplied context creation function\n * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls\n * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors\n *\n * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).\n * @param createContext A context creation function. Any args supplied after the request are forwarded to it,\n *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).\n */\nexport function buildSubscribeOperation<TContext extends AnyGraphqlContext, TContextFunction extends (...args: any) => Promise<TContext>>(\n  schema: GraphQLSchema | (() => Promise<GraphQLSchema>),\n  createContext: TContextFunction,\n) {\n  return async function subscribeOperation<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues>(\n    { subscription, variables, operationName }: TypedSubscribeRequest<TData, TVariables>,\n    ...createContextArgs: Parameters<TContextFunction>\n  ): Promise<AsyncIterableIterator<ExecutionResult<TData>>> {\n    const resolvedSchema = typeof schema === 'function' ? await schema() : schema\n    const document = typeof subscription === 'string' ? parse(subscription) : subscription\n    const contextValue = await createContext(...createContextArgs)\n    const result = await subscribe({\n      schema: resolvedSchema,\n      document,\n      contextValue,\n      variableValues: variables as VariableValues | undefined,\n      operationName,\n    })\n    if (Symbol.asyncIterator in result) return result as AsyncIterableIterator<ExecutionResult<TData>>\n    throw new Error(`Subscription did not produce an iterator: ${JSON.stringify((result as ExecutionResult).errors)}`)\n  }\n}\n"],"names":["parse","subscribe"],"mappings":";;;;AAYA;;;;;;;;;;;;;;;;;;AAkBG;AACG,SAAU,uBAAuB,CACrC,MAAsD,EACtD,aAA+B,EAAA;AAE/B,IAAA,OAAO,eAAe,kBAAkB,CACtC,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAA4C,EACpF,GAAG,iBAA+C,EAAA;AAElD,QAAA,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,GAAG,MAAM,MAAM,EAAE,GAAG,MAAM;AAC7E,QAAA,MAAM,QAAQ,GAAG,OAAO,YAAY,KAAK,QAAQ,GAAGA,aAAK,CAAC,YAAY,CAAC,GAAG,YAAY;QACtF,MAAM,YAAY,GAAG,MAAM,aAAa,CAAC,GAAG,iBAAiB,CAAC;AAC9D,QAAA,MAAM,MAAM,GAAG,MAAMC,iBAAS,CAAC;AAC7B,YAAA,MAAM,EAAE,cAAc;YACtB,QAAQ;YACR,YAAY;AACZ,YAAA,cAAc,EAAE,SAAuC;YACvD,aAAa;AACd,SAAA,CAAC;AACF,QAAA,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM;AAAE,YAAA,OAAO,MAAuD;AAClG,QAAA,MAAM,IAAI,KAAK,CAAC,CAAA,0CAAA,EAA6C,IAAI,CAAC,SAAS,CAAE,MAA0B,CAAC,MAAM,CAAC,CAAA,CAAE,CAAC;AACpH,IAAA,CAAC;AACH;;;;"}

package/testing/subscribe-operation.mjs

@@ -0,0 +1,41 @@
+import { parse, subscribe } from 'graphql';
+
+/**
+ * Returns a `subscribeOperation` test helper for the provided schema and context creation function.
+ *
+ * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,
+ * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads
+ * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in
+ * `@makerx/graphql-apollo-server/testing`.
+ *
+ * The returned function:
+ * - is strongly typed to the GraphQL context
+ * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing
+ * - forwards any additional arguments to the supplied context creation function
+ * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls
+ * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors
+ *
+ * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).
+ * @param createContext A context creation function. Any args supplied after the request are forwarded to it,
+ *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).
+ */
+function buildSubscribeOperation(schema, createContext) {
+    return async function subscribeOperation({ subscription, variables, operationName }, ...createContextArgs) {
+        const resolvedSchema = typeof schema === 'function' ? await schema() : schema;
+        const document = typeof subscription === 'string' ? parse(subscription) : subscription;
+        const contextValue = await createContext(...createContextArgs);
+        const result = await subscribe({
+            schema: resolvedSchema,
+            document,
+            contextValue,
+            variableValues: variables,
+            operationName,
+        });
+        if (Symbol.asyncIterator in result)
+            return result;
+        throw new Error(`Subscription did not produce an iterator: ${JSON.stringify(result.errors)}`);
+    };
+}
+
+export { buildSubscribeOperation };
+//# sourceMappingURL=subscribe-operation.mjs.map

package/testing/subscribe-operation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribe-operation.mjs","sources":["../../src/testing/subscribe-operation.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@graphql-typed-document-node/core'\nimport { parse, subscribe, type DocumentNode, type ExecutionResult, type GraphQLSchema } from 'graphql'\nimport type { AnyGraphqlContext } from '../context'\n\nexport type VariableValues = { [key: string]: any }\n\nexport type TypedSubscribeRequest<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues> = {\n  subscription: string | DocumentNode | TypedDocumentNode<TData, TVariables>\n  variables?: TVariables\n  operationName?: string\n}\n\n/**\n * Returns a `subscribeOperation` test helper for the provided schema and context creation function.\n *\n * The returned function runs a subscription operation directly against the schema using `graphql.subscribe`,\n * bypassing the websocket / `graphql-ws` transport. This gives tests complete control over JWT payloads\n * and other context inputs, the same way `buildExecuteOperation` does for queries and mutations in\n * `@makerx/graphql-apollo-server/testing`.\n *\n * The returned function:\n * - is strongly typed to the GraphQL context\n * - accepts `TypedDocumentNode` subscriptions to provide strong operation typing\n * - forwards any additional arguments to the supplied context creation function\n * - returns the subscription's `AsyncIterableIterator<ExecutionResult<TData>>` so tests can consume events via `for await` or manual `next()` calls\n * - throws if the subscription fails to produce an iterator (e.g. a validation error), surfacing the underlying errors\n *\n * @param schema The executable `GraphQLSchema`, or a factory that resolves one (useful when schema construction is async).\n * @param createContext A context creation function. Any args supplied after the request are forwarded to it,\n *   so test fixtures can drive auth/user state per-call (e.g. `(jwtPayload?) => Promise<GraphQLContext>`).\n */\nexport function buildSubscribeOperation<TContext extends AnyGraphqlContext, TContextFunction extends (...args: any) => Promise<TContext>>(\n  schema: GraphQLSchema | (() => Promise<GraphQLSchema>),\n  createContext: TContextFunction,\n) {\n  return async function subscribeOperation<TData = Record<string, unknown>, TVariables extends VariableValues = VariableValues>(\n    { subscription, variables, operationName }: TypedSubscribeRequest<TData, TVariables>,\n    ...createContextArgs: Parameters<TContextFunction>\n  ): Promise<AsyncIterableIterator<ExecutionResult<TData>>> {\n    const resolvedSchema = typeof schema === 'function' ? await schema() : schema\n    const document = typeof subscription === 'string' ? parse(subscription) : subscription\n    const contextValue = await createContext(...createContextArgs)\n    const result = await subscribe({\n      schema: resolvedSchema,\n      document,\n      contextValue,\n      variableValues: variables as VariableValues | undefined,\n      operationName,\n    })\n    if (Symbol.asyncIterator in result) return result as AsyncIterableIterator<ExecutionResult<TData>>\n    throw new Error(`Subscription did not produce an iterator: ${JSON.stringify((result as ExecutionResult).errors)}`)\n  }\n}\n"],"names":[],"mappings":";;AAYA;;;;;;;;;;;;;;;;;;AAkBG;AACG,SAAU,uBAAuB,CACrC,MAAsD,EACtD,aAA+B,EAAA;AAE/B,IAAA,OAAO,eAAe,kBAAkB,CACtC,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,EAA4C,EACpF,GAAG,iBAA+C,EAAA;AAElD,QAAA,MAAM,cAAc,GAAG,OAAO,MAAM,KAAK,UAAU,GAAG,MAAM,MAAM,EAAE,GAAG,MAAM;AAC7E,QAAA,MAAM,QAAQ,GAAG,OAAO,YAAY,KAAK,QAAQ,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,YAAY;QACtF,MAAM,YAAY,GAAG,MAAM,aAAa,CAAC,GAAG,iBAAiB,CAAC;AAC9D,QAAA,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC;AAC7B,YAAA,MAAM,EAAE,cAAc;YACtB,QAAQ;YACR,YAAY;AACZ,YAAA,cAAc,EAAE,SAAuC;YACvD,aAAa;AACd,SAAA,CAAC;AACF,QAAA,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM;AAAE,YAAA,OAAO,MAAuD;AAClG,QAAA,MAAM,IAAI,KAAK,CAAC,CAAA,0CAAA,EAA6C,IAAI,CAAC,SAAS,CAAE,MAA0B,CAAC,MAAM,CAAC,CAAA,CAAE,CAAC;AACpH,IAAA,CAAC;AACH;;;;"}