@makerx/graphql-core 3.0.0-beta.7 → 3.0.0-beta.8

package/README.md

@@ -366,6 +366,34 @@ This library includes a `subscriptions` module to provide simple setup using the
 
 1. For authorisation, clients can include a connection parameter named `authorization` or `Authorization` using the HTTP header format `Bearer <token>`. Note: [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer) will include an `Authorization` connection parameter when you specify an HTTP `Authorization` header via the UI.
 
+### wrapSubscriptionIterator
+
+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`.
+
+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:
+
+```ts
+const eventIsFinal = (data: BackgroundJobTopicData) =>
+  [BackgroundJobStatus.Completed, BackgroundJobStatus.Failed].includes(data.event.status)
+
+export const subscribeToBackgroundJobEvents = async (
+  args: SubscriptionBackgroundJobEventArgs,
+): Promise<AsyncIterator<BackgroundJobTopicData> & AsyncIterable<BackgroundJobTopicData>> => {
+  const initialPayload = await getJobFinishedEventFromCache(args.jobId)
+  const iterator = pubsub().asyncIterableIterator<BackgroundJobTopicData>(`${BACKGROUND_JOB_TOPIC}.${args.jobId}`)
+  return wrapSubscriptionIterator({
+    iterator,
+    initialPayload: initialPayload ? [initialPayload] : undefined,
+    eventIsFinal,
+  })
+}
+```
+
+The returned value is both an `AsyncIterator` and `AsyncIterable`, so it can be consumed via `for await` or by manual `next()` calls. `return()` and `throw()` are forwarded to the wrapped iterator when present.
+
 ## Utils
 
 - `isIntrospectionQuery`: indicates whether the query is an introspection query, based on the operation name or query content.

package/package.json

@@ -4,7 +4,7 @@
     "**"
   ],
   "name": "@makerx/graphql-core",
-  "version": "3.0.0-beta.7",
+  "version": "3.0.0-beta.8",
   "private": false,
   "description": "A set of core GraphQL utilities that MakerX uses to build GraphQL APIs",
   "author": "MakerX",

package/subscriptions/index.d.cts

@@ -1,3 +1,4 @@
 export * from './context';
+export { wrapSubscriptionIterator } from './subscription-iterator';
 export * from './server';
 export { extractTokenFromConnectionParams } from './utils';

package/subscriptions/index.d.mts

@@ -1,3 +1,4 @@
 export * from './context.js';
+export { wrapSubscriptionIterator } from './subscription-iterator.js';
 export * from './server.js';
 export { extractTokenFromConnectionParams } from './utils.js';

package/subscriptions/index.d.ts

@@ -1,3 +1,4 @@
 export * from './context';
+export { wrapSubscriptionIterator } from './subscription-iterator';
 export * from './server';
 export { extractTokenFromConnectionParams } from './utils';

package/subscriptions/index.js

@@ -1,12 +1,14 @@
 'use strict';
 
 var context = require('./context.js');
+var subscriptionIterator = require('./subscription-iterator.js');
 var server = require('./server.js');
 var utils = require('./utils.js');
 
 
 
 exports.createSubscriptionContextFactory = context.createSubscriptionContextFactory;
+exports.wrapSubscriptionIterator = subscriptionIterator.wrapSubscriptionIterator;
 exports.useSubscriptionsServer = server.useSubscriptionsServer;
 exports.extractTokenFromConnectionParams = utils.extractTokenFromConnectionParams;
 //# sourceMappingURL=index.js.map

package/subscriptions/index.js.map

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

package/subscriptions/index.mjs

@@ -1,4 +1,5 @@
 export { createSubscriptionContextFactory } from './context.mjs';
+export { wrapSubscriptionIterator } from './subscription-iterator.mjs';
 export { useSubscriptionsServer } from './server.mjs';
 export { extractTokenFromConnectionParams } from './utils.mjs';
 //# sourceMappingURL=index.mjs.map

package/subscriptions/index.mjs.map

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

package/subscriptions/subscription-iterator.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Wraps an async iterator with options for:
+ *  - returning an initial payload (e.g. current state)
+ *  - eagerly ending iteration when a final event is received
+ *
+ * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,
+ *  by providing an initial payload to be immediately returned, before subsequent events stream in.
+ *
+ * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
+ *
+ * @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 eventIsFinal An optional function to determine if an event is final (and iteration should end).
+ *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.
+ * @returns An async iterator for the event data.
+ */
+export declare function wrapSubscriptionIterator<TEventData>({ iterator: wrapped, initialPayload, eventIsFinal, }: {
+    iterator: AsyncIterableIterator<TEventData>;
+    initialPayload?: TEventData | TEventData[];
+    eventIsFinal?: (event: TEventData) => boolean;
+}): AsyncIterator<TEventData> & AsyncIterable<TEventData>;

package/subscriptions/subscription-iterator.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Wraps an async iterator with options for:
+ *  - returning an initial payload (e.g. current state)
+ *  - eagerly ending iteration when a final event is received
+ *
+ * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,
+ *  by providing an initial payload to be immediately returned, before subsequent events stream in.
+ *
+ * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
+ *
+ * @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 eventIsFinal An optional function to determine if an event is final (and iteration should end).
+ *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.
+ * @returns An async iterator for the event data.
+ */
+export declare function wrapSubscriptionIterator<TEventData>({ iterator: wrapped, initialPayload, eventIsFinal, }: {
+    iterator: AsyncIterableIterator<TEventData>;
+    initialPayload?: TEventData | TEventData[];
+    eventIsFinal?: (event: TEventData) => boolean;
+}): AsyncIterator<TEventData> & AsyncIterable<TEventData>;

package/subscriptions/subscription-iterator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Wraps an async iterator with options for:
+ *  - returning an initial payload (e.g. current state)
+ *  - eagerly ending iteration when a final event is received
+ *
+ * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,
+ *  by providing an initial payload to be immediately returned, before subsequent events stream in.
+ *
+ * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
+ *
+ * @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 eventIsFinal An optional function to determine if an event is final (and iteration should end).
+ *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.
+ * @returns An async iterator for the event data.
+ */
+export declare function wrapSubscriptionIterator<TEventData>({ iterator: wrapped, initialPayload, eventIsFinal, }: {
+    iterator: AsyncIterableIterator<TEventData>;
+    initialPayload?: TEventData | TEventData[];
+    eventIsFinal?: (event: TEventData) => boolean;
+}): AsyncIterator<TEventData> & AsyncIterable<TEventData>;

package/subscriptions/subscription-iterator.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Wraps an async iterator with options for:
+ *  - returning an initial payload (e.g. current state)
+ *  - eagerly ending iteration when a final event is received
+ *
+ * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,
+ *  by providing an initial payload to be immediately returned, before subsequent events stream in.
+ *
+ * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
+ *
+ * @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 eventIsFinal An optional function to determine if an event is final (and iteration should end).
+ *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.
+ * @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 iterator = {
+        next: async () => {
+            if (done)
+                return { done: true, value: undefined };
+            if (initialQueue.length > 0) {
+                const value = initialQueue.shift();
+                return { done: false, value };
+            }
+            const next = await wrapped.next();
+            if (!next.done && eventIsFinal && eventIsFinal(next.value)) {
+                done = true;
+                await wrapped.return?.();
+            }
+            return next;
+        },
+        return: async (value) => {
+            done = true;
+            initialQueue.length = 0;
+            if (wrapped.return)
+                return wrapped.return(value);
+            return { done: true, value: value };
+        },
+        throw: async (err) => {
+            done = true;
+            initialQueue.length = 0;
+            if (wrapped.throw)
+                return wrapped.throw(err);
+            throw err;
+        },
+    };
+    return { ...iterator, [Symbol.asyncIterator]: () => iterator };
+}
+
+exports.wrapSubscriptionIterator = wrapSubscriptionIterator;
+//# sourceMappingURL=subscription-iterator.js.map

package/subscriptions/subscription-iterator.js.map

@@ -0,0 +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 *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.\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        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;;;;;;;;;;;;;;;AAeG;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,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;;;;"}

package/subscriptions/subscription-iterator.mjs

@@ -0,0 +1,54 @@
+/**
+ * Wraps an async iterator with options for:
+ *  - returning an initial payload (e.g. current state)
+ *  - eagerly ending iteration when a final event is received
+ *
+ * Providing an initial payload helps avoid race conditions when clients subscribe to events but miss recent state changes,
+ *  by providing an initial payload to be immediately returned, before subsequent events stream in.
+ *
+ * Eagerly ending iteration when a final event ensures subscriptions do not continue unnecessarily.
+ *
+ * @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 eventIsFinal An optional function to determine if an event is final (and iteration should end).
+ *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.
+ * @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 iterator = {
+        next: async () => {
+            if (done)
+                return { done: true, value: undefined };
+            if (initialQueue.length > 0) {
+                const value = initialQueue.shift();
+                return { done: false, value };
+            }
+            const next = await wrapped.next();
+            if (!next.done && eventIsFinal && eventIsFinal(next.value)) {
+                done = true;
+                await wrapped.return?.();
+            }
+            return next;
+        },
+        return: async (value) => {
+            done = true;
+            initialQueue.length = 0;
+            if (wrapped.return)
+                return wrapped.return(value);
+            return { done: true, value: value };
+        },
+        throw: async (err) => {
+            done = true;
+            initialQueue.length = 0;
+            if (wrapped.throw)
+                return wrapped.throw(err);
+            throw err;
+        },
+    };
+    return { ...iterator, [Symbol.asyncIterator]: () => iterator };
+}
+
+export { wrapSubscriptionIterator };
+//# sourceMappingURL=subscription-iterator.mjs.map

package/subscriptions/subscription-iterator.mjs.map

@@ -0,0 +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 *   Note: only applied to events from the wrapped iterator, not to entries in `initialPayload`.\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        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;;;;;;;;;;;;;;;AAeG;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,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;;;;"}