@apollo/client 3.8.7 → 3.8.8

package/utilities/observables/Concast.js

@@ -5,18 +5,54 @@ import { fixObservableSubclass } from "./subclassing.js";
 function isPromiseLike(value) {
     return value && typeof value.then === "function";
 }
-var Concast = (function (_super) {
+// A Concast<T> observable concatenates the given sources into a single
+// non-overlapping sequence of Ts, automatically unwrapping any promises,
+// and broadcasts the T elements of that sequence to any number of
+// subscribers, all without creating a bunch of intermediary Observable
+// wrapper objects.
+//
+// Even though any number of observers can subscribe to the Concast, each
+// source observable is guaranteed to receive at most one subscribe call,
+// and the results are multicast to all observers.
+//
+// In addition to broadcasting every next/error message to this.observers,
+// the Concast stores the most recent message using this.latest, so any
+// new observers can immediately receive the latest message, even if it
+// was originally delivered in the past. This behavior means we can assume
+// every active observer in this.observers has received the same most
+// recent message.
+//
+// With the exception of this.latest replay, a Concast is a "hot"
+// observable in the sense that it does not replay past results from the
+// beginning of time for each new observer.
+//
+// Could we have used some existing RxJS class instead? Concast<T> is
+// similar to a BehaviorSubject<T>, because it is multicast and redelivers
+// the latest next/error message to new subscribers. Unlike Subject<T>,
+// Concast<T> does not expose an Observer<T> interface (this.handlers is
+// intentionally private), since Concast<T> gets its inputs from the
+// concatenated sources. If we ever switch to RxJS, there may be some
+// value in reusing their code, but for now we use zen-observable, which
+// does not contain any Subject implementations.
+var Concast = /** @class */ (function (_super) {
     __extends(Concast, _super);
+    // Not only can the individual elements of the iterable be promises, but
+    // also the iterable itself can be wrapped in a promise.
     function Concast(sources) {
         var _this = _super.call(this, function (observer) {
             _this.addObserver(observer);
             return function () { return _this.removeObserver(observer); };
         }) || this;
+        // Active observers receiving broadcast messages. Thanks to this.latest,
+        // we can assume all observers in this Set have received the same most
+        // recent message, though possibly at different times in the past.
         _this.observers = new Set();
         _this.promise = new Promise(function (resolve, reject) {
             _this.resolve = resolve;
             _this.reject = reject;
         });
+        // Bound handler functions that can be reused for every internal
+        // subscription.
         _this.handlers = {
             next: function (result) {
                 if (_this.sub !== null) {
@@ -28,6 +64,9 @@ var Concast = (function (_super) {
             error: function (error) {
                 var sub = _this.sub;
                 if (sub !== null) {
+                    // Delay unsubscribing from the underlying subscription slightly,
+                    // so that immediately subscribing another observer can keep the
+                    // subscription active.
                     if (sub)
                         setTimeout(function () { return sub.unsubscribe(); });
                     _this.sub = null;
@@ -40,6 +79,11 @@ var Concast = (function (_super) {
             complete: function () {
                 var _a = _this, sub = _a.sub, _b = _a.sources, sources = _b === void 0 ? [] : _b;
                 if (sub !== null) {
+                    // If complete is called before concast.start, this.sources may be
+                    // undefined, so we use a default value of [] for sources. That works
+                    // here because it falls into the if (!value) {...} block, which
+                    // appropriately terminates the Concast, even if this.sources might
+                    // eventually have been initialized to a non-empty array.
                     var value = sources.shift();
                     if (!value) {
                         if (sub)
@@ -52,6 +96,12 @@ var Concast = (function (_super) {
                             _this.resolve();
                         }
                         _this.notify("complete");
+                        // We do not store this.latest = ["complete"], because doing so
+                        // discards useful information about the previous next (or
+                        // error) message. Instead, if new observers subscribe after
+                        // this Concast has completed, they will receive the final
+                        // 'next' message (unless there was an error) immediately
+                        // followed by a 'complete' message (see addObserver).
                         iterateObserversSafely(_this.observers, "complete");
                     }
                     else if (isPromiseLike(value)) {
@@ -64,12 +114,19 @@ var Concast = (function (_super) {
             },
         };
         _this.nextResultListeners = new Set();
+        // A public way to abort observation and broadcast.
         _this.cancel = function (reason) {
             _this.reject(reason);
             _this.sources = [];
             _this.handlers.complete();
         };
+        // Suppress rejection warnings for this.promise, since it's perfectly
+        // acceptable to pay no attention to this.promise if you're consuming
+        // the results through the normal observable API.
         _this.promise.catch(function (_) { });
+        // If someone accidentally tries to create a Concast using a subscriber
+        // function, recover by creating an Observable from that subscriber and
+        // using it as the source.
         if (typeof sources === "function") {
             sources = [new Observable(sources)];
         }
@@ -84,7 +141,14 @@ var Concast = (function (_super) {
     Concast.prototype.start = function (sources) {
         if (this.sub !== void 0)
             return;
+        // In practice, sources is most often simply an Array of observables.
+        // TODO Consider using sources[Symbol.iterator]() to take advantage
+        // of the laziness of non-Array iterables.
         this.sources = Array.from(sources);
+        // Calling this.handlers.complete() kicks off consumption of the first
+        // source observable. It's tempting to do this step lazily in
+        // addObserver, but this.promise can be accessed without calling
+        // addObserver, so consumption needs to begin eagerly.
         this.handlers.complete();
     };
     Concast.prototype.deliverLastMessage = function (observer) {
@@ -94,6 +158,9 @@ var Concast = (function (_super) {
             if (method) {
                 method.call(observer, this.latest[1]);
             }
+            // If the subscription is already closed, and the last message was
+            // a 'next' message, simulate delivery of the final 'complete'
+            // message again.
             if (this.sub === null && nextOrError === "next" && observer.complete) {
                 observer.complete();
             }
@@ -101,22 +168,36 @@ var Concast = (function (_super) {
     };
     Concast.prototype.addObserver = function (observer) {
         if (!this.observers.has(observer)) {
+            // Immediately deliver the most recent message, so we can always
+            // be sure all observers have the latest information.
             this.deliverLastMessage(observer);
             this.observers.add(observer);
         }
     };
     Concast.prototype.removeObserver = function (observer) {
         if (this.observers.delete(observer) && this.observers.size < 1) {
+            // In case there are still any listeners in this.nextResultListeners, and
+            // no error or completion has been broadcast yet, make sure those
+            // observers have a chance to run and then remove themselves from
+            // this.observers.
             this.handlers.complete();
         }
     };
     Concast.prototype.notify = function (method, arg) {
         var nextResultListeners = this.nextResultListeners;
         if (nextResultListeners.size) {
+            // Replacing this.nextResultListeners first ensures it does not grow while
+            // we are iterating over it, potentially leading to infinite loops.
             this.nextResultListeners = new Set();
             nextResultListeners.forEach(function (listener) { return listener(method, arg); });
         }
     };
+    // We need a way to run callbacks just *before* the next result (or error or
+    // completion) is delivered by this Concast, so we can be sure any code that
+    // runs as a result of delivering that result/error observes the effects of
+    // running the callback(s). It was tempting to reuse the Observer type instead
+    // of introducing NextResultListener, but that messes with the sizing and
+    // maintenance of this.observers, and ends up being more code overall.
     Concast.prototype.beforeNext = function (callback) {
         var called = false;
         this.nextResultListeners.add(function (method, arg) {
@@ -129,5 +210,7 @@ var Concast = (function (_super) {
     return Concast;
 }(Observable));
 export { Concast };
+// Necessary because the Concast constructor has a different signature
+// than the Observable constructor.
 fixObservableSubclass(Concast);
 //# sourceMappingURL=Concast.js.map

package/utilities/observables/Concast.js.map

@@ -1 +1 @@
-{"version":3,"file":"Concast.js","sourceRoot":"","sources":["../../../src/utilities/observables/Concast.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Observer,\n  ObservableSubscription,\n  Subscriber,\n} from \"./Observable.js\";\nimport { Observable } from \"./Observable.js\";\nimport { iterateObserversSafely } from \"./iteration.js\";\nimport { fixObservableSubclass } from \"./subclassing.js\";\n\ntype MaybeAsync<T> = T | PromiseLike<T>;\n\nfunction isPromiseLike<T>(value: MaybeAsync<T>): value is PromiseLike<T> {\n  return value && typeof (value as any).then === \"function\";\n}\n\n// Any individual Source<T> can be an Observable<T> or a promise for one.\ntype Source<T> = MaybeAsync<Observable<T>>;\n\nexport type ConcastSourcesIterable<T> = Iterable<Source<T>>;\nexport type ConcastSourcesArray<T> = Array<Source<T>>;\n\n// A Concast<T> observable concatenates the given sources into a single\n// non-overlapping sequence of Ts, automatically unwrapping any promises,\n// and broadcasts the T elements of that sequence to any number of\n// subscribers, all without creating a bunch of intermediary Observable\n// wrapper objects.\n//\n// Even though any number of observers can subscribe to the Concast, each\n// source observable is guaranteed to receive at most one subscribe call,\n// and the results are multicast to all observers.\n//\n// In addition to broadcasting every next/error message to this.observers,\n// the Concast stores the most recent message using this.latest, so any\n// new observers can immediately receive the latest message, even if it\n// was originally delivered in the past. This behavior means we can assume\n// every active observer in this.observers has received the same most\n// recent message.\n//\n// With the exception of this.latest replay, a Concast is a \"hot\"\n// observable in the sense that it does not replay past results from the\n// beginning of time for each new observer.\n//\n// Could we have used some existing RxJS class instead? Concast<T> is\n// similar to a BehaviorSubject<T>, because it is multicast and redelivers\n// the latest next/error message to new subscribers. Unlike Subject<T>,\n// Concast<T> does not expose an Observer<T> interface (this.handlers is\n// intentionally private), since Concast<T> gets its inputs from the\n// concatenated sources. If we ever switch to RxJS, there may be some\n// value in reusing their code, but for now we use zen-observable, which\n// does not contain any Subject implementations.\nexport class Concast<T> extends Observable<T> {\n  // Active observers receiving broadcast messages. Thanks to this.latest,\n  // we can assume all observers in this Set have received the same most\n  // recent message, though possibly at different times in the past.\n  private observers = new Set<Observer<T>>();\n\n  // This property starts off undefined to indicate the initial\n  // subscription has not yet begun, then points to each source\n  // subscription in turn, and finally becomes null after the sources have\n  // been exhausted. After that, it stays null.\n  private sub?: ObservableSubscription | null;\n\n  // Not only can the individual elements of the iterable be promises, but\n  // also the iterable itself can be wrapped in a promise.\n  constructor(sources: MaybeAsync<ConcastSourcesIterable<T>> | Subscriber<T>) {\n    super((observer) => {\n      this.addObserver(observer);\n      return () => this.removeObserver(observer);\n    });\n\n    // Suppress rejection warnings for this.promise, since it's perfectly\n    // acceptable to pay no attention to this.promise if you're consuming\n    // the results through the normal observable API.\n    this.promise.catch((_) => {});\n\n    // If someone accidentally tries to create a Concast using a subscriber\n    // function, recover by creating an Observable from that subscriber and\n    // using it as the source.\n    if (typeof sources === \"function\") {\n      sources = [new Observable(sources)];\n    }\n\n    if (isPromiseLike(sources)) {\n      sources.then((iterable) => this.start(iterable), this.handlers.error);\n    } else {\n      this.start(sources);\n    }\n  }\n\n  // A consumable array of source observables, incrementally consumed each time\n  // this.handlers.complete is called. This private field is not initialized\n  // until the concast.start method is called, which can happen asynchronously\n  // if a Promise is passed to the Concast constructor, so undefined is a\n  // possible value for this.sources before concast.start is called.\n  private sources: Source<T>[] | undefined;\n\n  private start(sources: ConcastSourcesIterable<T>) {\n    if (this.sub !== void 0) return;\n\n    // In practice, sources is most often simply an Array of observables.\n    // TODO Consider using sources[Symbol.iterator]() to take advantage\n    // of the laziness of non-Array iterables.\n    this.sources = Array.from(sources);\n\n    // Calling this.handlers.complete() kicks off consumption of the first\n    // source observable. It's tempting to do this step lazily in\n    // addObserver, but this.promise can be accessed without calling\n    // addObserver, so consumption needs to begin eagerly.\n    this.handlers.complete();\n  }\n\n  private deliverLastMessage(observer: Observer<T>) {\n    if (this.latest) {\n      const nextOrError = this.latest[0];\n      const method = observer[nextOrError];\n      if (method) {\n        method.call(observer, this.latest[1]);\n      }\n      // If the subscription is already closed, and the last message was\n      // a 'next' message, simulate delivery of the final 'complete'\n      // message again.\n      if (this.sub === null && nextOrError === \"next\" && observer.complete) {\n        observer.complete();\n      }\n    }\n  }\n\n  public addObserver(observer: Observer<T>) {\n    if (!this.observers.has(observer)) {\n      // Immediately deliver the most recent message, so we can always\n      // be sure all observers have the latest information.\n      this.deliverLastMessage(observer);\n      this.observers.add(observer);\n    }\n  }\n\n  public removeObserver(observer: Observer<T>) {\n    if (this.observers.delete(observer) && this.observers.size < 1) {\n      // In case there are still any listeners in this.nextResultListeners, and\n      // no error or completion has been broadcast yet, make sure those\n      // observers have a chance to run and then remove themselves from\n      // this.observers.\n      this.handlers.complete();\n    }\n  }\n\n  // Any Concast object can be trivially converted to a Promise, without\n  // having to create a new wrapper Observable. This promise provides an\n  // easy way to observe the final state of the Concast.\n  private resolve: (result?: T | PromiseLike<T>) => void;\n  private reject: (reason: any) => void;\n  public readonly promise = new Promise<T>((resolve, reject) => {\n    this.resolve = resolve;\n    this.reject = reject;\n  });\n\n  // Name and argument of the most recently invoked observer method, used\n  // to deliver latest results immediately to new observers.\n  private latest?: [\"next\", T] | [\"error\", any];\n\n  // Bound handler functions that can be reused for every internal\n  // subscription.\n  private handlers = {\n    next: (result: T) => {\n      if (this.sub !== null) {\n        this.latest = [\"next\", result];\n        this.notify(\"next\", result);\n        iterateObserversSafely(this.observers, \"next\", result);\n      }\n    },\n\n    error: (error: any) => {\n      const { sub } = this;\n      if (sub !== null) {\n        // Delay unsubscribing from the underlying subscription slightly,\n        // so that immediately subscribing another observer can keep the\n        // subscription active.\n        if (sub) setTimeout(() => sub.unsubscribe());\n        this.sub = null;\n        this.latest = [\"error\", error];\n        this.reject(error);\n        this.notify(\"error\", error);\n        iterateObserversSafely(this.observers, \"error\", error);\n      }\n    },\n\n    complete: () => {\n      const { sub, sources = [] } = this;\n      if (sub !== null) {\n        // If complete is called before concast.start, this.sources may be\n        // undefined, so we use a default value of [] for sources. That works\n        // here because it falls into the if (!value) {...} block, which\n        // appropriately terminates the Concast, even if this.sources might\n        // eventually have been initialized to a non-empty array.\n        const value = sources.shift();\n        if (!value) {\n          if (sub) setTimeout(() => sub.unsubscribe());\n          this.sub = null;\n          if (this.latest && this.latest[0] === \"next\") {\n            this.resolve(this.latest[1]);\n          } else {\n            this.resolve();\n          }\n          this.notify(\"complete\");\n          // We do not store this.latest = [\"complete\"], because doing so\n          // discards useful information about the previous next (or\n          // error) message. Instead, if new observers subscribe after\n          // this Concast has completed, they will receive the final\n          // 'next' message (unless there was an error) immediately\n          // followed by a 'complete' message (see addObserver).\n          iterateObserversSafely(this.observers, \"complete\");\n        } else if (isPromiseLike(value)) {\n          value.then((obs) => (this.sub = obs.subscribe(this.handlers)));\n        } else {\n          this.sub = value.subscribe(this.handlers);\n        }\n      }\n    },\n  };\n\n  private nextResultListeners = new Set<NextResultListener>();\n\n  private notify(\n    method: Parameters<NextResultListener>[0],\n    arg?: Parameters<NextResultListener>[1]\n  ) {\n    const { nextResultListeners } = this;\n    if (nextResultListeners.size) {\n      // Replacing this.nextResultListeners first ensures it does not grow while\n      // we are iterating over it, potentially leading to infinite loops.\n      this.nextResultListeners = new Set();\n      nextResultListeners.forEach((listener) => listener(method, arg));\n    }\n  }\n\n  // We need a way to run callbacks just *before* the next result (or error or\n  // completion) is delivered by this Concast, so we can be sure any code that\n  // runs as a result of delivering that result/error observes the effects of\n  // running the callback(s). It was tempting to reuse the Observer type instead\n  // of introducing NextResultListener, but that messes with the sizing and\n  // maintenance of this.observers, and ends up being more code overall.\n  beforeNext(callback: NextResultListener) {\n    let called = false;\n    this.nextResultListeners.add((method, arg) => {\n      if (!called) {\n        called = true;\n        callback(method, arg);\n      }\n    });\n  }\n\n  // A public way to abort observation and broadcast.\n  public cancel = (reason: any) => {\n    this.reject(reason);\n    this.sources = [];\n    this.handlers.complete();\n  };\n}\n\ntype NextResultListener = (\n  method: \"next\" | \"error\" | \"complete\",\n  arg?: any\n) => any;\n\n// Necessary because the Concast constructor has a different signature\n// than the Observable constructor.\nfixObservableSubclass(Concast);\n"]}
+{"version":3,"file":"Concast.js","sourceRoot":"","sources":["../../../src/utilities/observables/Concast.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  Observer,\n  ObservableSubscription,\n  Subscriber,\n} from \"./Observable.js\";\nimport { Observable } from \"./Observable.js\";\nimport { iterateObserversSafely } from \"./iteration.js\";\nimport { fixObservableSubclass } from \"./subclassing.js\";\n\ntype MaybeAsync<T> = T | PromiseLike<T>;\n\nfunction isPromiseLike<T>(value: MaybeAsync<T>): value is PromiseLike<T> {\n  return value && typeof (value as any).then === \"function\";\n}\n\n// Any individual Source<T> can be an Observable<T> or a promise for one.\ntype Source<T> = MaybeAsync<Observable<T>>;\n\nexport type ConcastSourcesIterable<T> = Iterable<Source<T>>;\nexport type ConcastSourcesArray<T> = Array<Source<T>>;\n\n// A Concast<T> observable concatenates the given sources into a single\n// non-overlapping sequence of Ts, automatically unwrapping any promises,\n// and broadcasts the T elements of that sequence to any number of\n// subscribers, all without creating a bunch of intermediary Observable\n// wrapper objects.\n//\n// Even though any number of observers can subscribe to the Concast, each\n// source observable is guaranteed to receive at most one subscribe call,\n// and the results are multicast to all observers.\n//\n// In addition to broadcasting every next/error message to this.observers,\n// the Concast stores the most recent message using this.latest, so any\n// new observers can immediately receive the latest message, even if it\n// was originally delivered in the past. This behavior means we can assume\n// every active observer in this.observers has received the same most\n// recent message.\n//\n// With the exception of this.latest replay, a Concast is a \"hot\"\n// observable in the sense that it does not replay past results from the\n// beginning of time for each new observer.\n//\n// Could we have used some existing RxJS class instead? Concast<T> is\n// similar to a BehaviorSubject<T>, because it is multicast and redelivers\n// the latest next/error message to new subscribers. Unlike Subject<T>,\n// Concast<T> does not expose an Observer<T> interface (this.handlers is\n// intentionally private), since Concast<T> gets its inputs from the\n// concatenated sources. If we ever switch to RxJS, there may be some\n// value in reusing their code, but for now we use zen-observable, which\n// does not contain any Subject implementations.\nexport class Concast<T> extends Observable<T> {\n  // Active observers receiving broadcast messages. Thanks to this.latest,\n  // we can assume all observers in this Set have received the same most\n  // recent message, though possibly at different times in the past.\n  private observers = new Set<Observer<T>>();\n\n  // This property starts off undefined to indicate the initial\n  // subscription has not yet begun, then points to each source\n  // subscription in turn, and finally becomes null after the sources have\n  // been exhausted. After that, it stays null.\n  private sub?: ObservableSubscription | null;\n\n  // Not only can the individual elements of the iterable be promises, but\n  // also the iterable itself can be wrapped in a promise.\n  constructor(sources: MaybeAsync<ConcastSourcesIterable<T>> | Subscriber<T>) {\n    super((observer) => {\n      this.addObserver(observer);\n      return () => this.removeObserver(observer);\n    });\n\n    // Suppress rejection warnings for this.promise, since it's perfectly\n    // acceptable to pay no attention to this.promise if you're consuming\n    // the results through the normal observable API.\n    this.promise.catch((_) => {});\n\n    // If someone accidentally tries to create a Concast using a subscriber\n    // function, recover by creating an Observable from that subscriber and\n    // using it as the source.\n    if (typeof sources === \"function\") {\n      sources = [new Observable(sources)];\n    }\n\n    if (isPromiseLike(sources)) {\n      sources.then((iterable) => this.start(iterable), this.handlers.error);\n    } else {\n      this.start(sources);\n    }\n  }\n\n  // A consumable array of source observables, incrementally consumed each time\n  // this.handlers.complete is called. This private field is not initialized\n  // until the concast.start method is called, which can happen asynchronously\n  // if a Promise is passed to the Concast constructor, so undefined is a\n  // possible value for this.sources before concast.start is called.\n  private sources: Source<T>[] | undefined;\n\n  private start(sources: ConcastSourcesIterable<T>) {\n    if (this.sub !== void 0) return;\n\n    // In practice, sources is most often simply an Array of observables.\n    // TODO Consider using sources[Symbol.iterator]() to take advantage\n    // of the laziness of non-Array iterables.\n    this.sources = Array.from(sources);\n\n    // Calling this.handlers.complete() kicks off consumption of the first\n    // source observable. It's tempting to do this step lazily in\n    // addObserver, but this.promise can be accessed without calling\n    // addObserver, so consumption needs to begin eagerly.\n    this.handlers.complete();\n  }\n\n  private deliverLastMessage(observer: Observer<T>) {\n    if (this.latest) {\n      const nextOrError = this.latest[0];\n      const method = observer[nextOrError];\n      if (method) {\n        method.call(observer, this.latest[1]);\n      }\n      // If the subscription is already closed, and the last message was\n      // a 'next' message, simulate delivery of the final 'complete'\n      // message again.\n      if (this.sub === null && nextOrError === \"next\" && observer.complete) {\n        observer.complete();\n      }\n    }\n  }\n\n  public addObserver(observer: Observer<T>) {\n    if (!this.observers.has(observer)) {\n      // Immediately deliver the most recent message, so we can always\n      // be sure all observers have the latest information.\n      this.deliverLastMessage(observer);\n      this.observers.add(observer);\n    }\n  }\n\n  public removeObserver(observer: Observer<T>) {\n    if (this.observers.delete(observer) && this.observers.size < 1) {\n      // In case there are still any listeners in this.nextResultListeners, and\n      // no error or completion has been broadcast yet, make sure those\n      // observers have a chance to run and then remove themselves from\n      // this.observers.\n      this.handlers.complete();\n    }\n  }\n\n  // Any Concast object can be trivially converted to a Promise, without\n  // having to create a new wrapper Observable. This promise provides an\n  // easy way to observe the final state of the Concast.\n  private resolve!: (result?: T | PromiseLike<T>) => void;\n  private reject!: (reason: any) => void;\n  public readonly promise = new Promise<T | undefined>((resolve, reject) => {\n    this.resolve = resolve;\n    this.reject = reject;\n  });\n\n  // Name and argument of the most recently invoked observer method, used\n  // to deliver latest results immediately to new observers.\n  private latest?: [\"next\", T] | [\"error\", any];\n\n  // Bound handler functions that can be reused for every internal\n  // subscription.\n  private handlers = {\n    next: (result: T) => {\n      if (this.sub !== null) {\n        this.latest = [\"next\", result];\n        this.notify(\"next\", result);\n        iterateObserversSafely(this.observers, \"next\", result);\n      }\n    },\n\n    error: (error: any) => {\n      const { sub } = this;\n      if (sub !== null) {\n        // Delay unsubscribing from the underlying subscription slightly,\n        // so that immediately subscribing another observer can keep the\n        // subscription active.\n        if (sub) setTimeout(() => sub.unsubscribe());\n        this.sub = null;\n        this.latest = [\"error\", error];\n        this.reject(error);\n        this.notify(\"error\", error);\n        iterateObserversSafely(this.observers, \"error\", error);\n      }\n    },\n\n    complete: () => {\n      const { sub, sources = [] } = this;\n      if (sub !== null) {\n        // If complete is called before concast.start, this.sources may be\n        // undefined, so we use a default value of [] for sources. That works\n        // here because it falls into the if (!value) {...} block, which\n        // appropriately terminates the Concast, even if this.sources might\n        // eventually have been initialized to a non-empty array.\n        const value = sources.shift();\n        if (!value) {\n          if (sub) setTimeout(() => sub.unsubscribe());\n          this.sub = null;\n          if (this.latest && this.latest[0] === \"next\") {\n            this.resolve(this.latest[1]);\n          } else {\n            this.resolve();\n          }\n          this.notify(\"complete\");\n          // We do not store this.latest = [\"complete\"], because doing so\n          // discards useful information about the previous next (or\n          // error) message. Instead, if new observers subscribe after\n          // this Concast has completed, they will receive the final\n          // 'next' message (unless there was an error) immediately\n          // followed by a 'complete' message (see addObserver).\n          iterateObserversSafely(this.observers, \"complete\");\n        } else if (isPromiseLike(value)) {\n          value.then((obs) => (this.sub = obs.subscribe(this.handlers)));\n        } else {\n          this.sub = value.subscribe(this.handlers);\n        }\n      }\n    },\n  };\n\n  private nextResultListeners = new Set<NextResultListener>();\n\n  private notify(\n    method: Parameters<NextResultListener>[0],\n    arg?: Parameters<NextResultListener>[1]\n  ) {\n    const { nextResultListeners } = this;\n    if (nextResultListeners.size) {\n      // Replacing this.nextResultListeners first ensures it does not grow while\n      // we are iterating over it, potentially leading to infinite loops.\n      this.nextResultListeners = new Set();\n      nextResultListeners.forEach((listener) => listener(method, arg));\n    }\n  }\n\n  // We need a way to run callbacks just *before* the next result (or error or\n  // completion) is delivered by this Concast, so we can be sure any code that\n  // runs as a result of delivering that result/error observes the effects of\n  // running the callback(s). It was tempting to reuse the Observer type instead\n  // of introducing NextResultListener, but that messes with the sizing and\n  // maintenance of this.observers, and ends up being more code overall.\n  beforeNext(callback: NextResultListener) {\n    let called = false;\n    this.nextResultListeners.add((method, arg) => {\n      if (!called) {\n        called = true;\n        callback(method, arg);\n      }\n    });\n  }\n\n  // A public way to abort observation and broadcast.\n  public cancel = (reason: any) => {\n    this.reject(reason);\n    this.sources = [];\n    this.handlers.complete();\n  };\n}\n\ntype NextResultListener = (\n  method: \"next\" | \"error\" | \"complete\",\n  arg?: any\n) => any;\n\n// Necessary because the Concast constructor has a different signature\n// than the Observable constructor.\nfixObservableSubclass(Concast);\n"]}

package/utilities/observables/Observable.js

@@ -1,8 +1,14 @@
 import { Observable } from "zen-observable-ts";
+// This simplified polyfill attempts to follow the ECMAScript Observable
+// proposal (https://github.com/zenparsing/es-observable)
 import "symbol-observable";
+// The zen-observable package defines Observable.prototype[Symbol.observable]
+// when Symbol is supported, but RxJS interop depends on also setting this fake
+// '@@observable' string as a polyfill for Symbol.observable.
 var prototype = Observable.prototype;
 var fakeObsSymbol = "@@observable";
 if (!prototype[fakeObsSymbol]) {
+    // @ts-expect-error
     prototype[fakeObsSymbol] = function () {
         return this;
     };

package/utilities/observables/Observable.js.map

@@ -1 +1 @@
-{"version":3,"file":"Observable.js","sourceRoot":"","sources":["../../../src/utilities/observables/Observable.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C,OAAO,mBAAmB,CAAC;AAOnB,IAAA,SAAS,GAAK,UAAU,UAAf,CAAgB;AACjC,IAAM,aAAa,GAAG,cAAwC,CAAC;AAC/D,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE;IAC7B,SAAS,CAAC,aAAa,CAAC,GAAG;QACzB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;CACH;AAED,OAAO,EAAE,UAAU,EAAE,CAAC","sourcesContent":["import type {\n  Observer,\n  Subscription as ObservableSubscription,\n  Subscriber,\n} from \"zen-observable-ts\";\nimport { Observable } from \"zen-observable-ts\";\n\n// This simplified polyfill attempts to follow the ECMAScript Observable\n// proposal (https://github.com/zenparsing/es-observable)\nimport \"symbol-observable\";\n\nexport type { Observer, ObservableSubscription, Subscriber };\n\n// The zen-observable package defines Observable.prototype[Symbol.observable]\n// when Symbol is supported, but RxJS interop depends on also setting this fake\n// '@@observable' string as a polyfill for Symbol.observable.\nconst { prototype } = Observable;\nconst fakeObsSymbol = \"@@observable\" as keyof typeof prototype;\nif (!prototype[fakeObsSymbol]) {\n  prototype[fakeObsSymbol] = function () {\n    return this;\n  };\n}\n\nexport { Observable };\n"]}
+{"version":3,"file":"Observable.js","sourceRoot":"","sources":["../../../src/utilities/observables/Observable.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,wEAAwE;AACxE,yDAAyD;AACzD,OAAO,mBAAmB,CAAC;AAI3B,6EAA6E;AAC7E,+EAA+E;AAC/E,6DAA6D;AACrD,IAAA,SAAS,GAAK,UAAU,UAAf,CAAgB;AACjC,IAAM,aAAa,GAAG,cAAwC,CAAC;AAC/D,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE,CAAC;IAC9B,mBAAmB;IACnB,SAAS,CAAC,aAAa,CAAC,GAAG;QACzB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,CAAC","sourcesContent":["import type {\n  Observer,\n  Subscription as ObservableSubscription,\n  Subscriber,\n} from \"zen-observable-ts\";\nimport { Observable } from \"zen-observable-ts\";\n\n// This simplified polyfill attempts to follow the ECMAScript Observable\n// proposal (https://github.com/zenparsing/es-observable)\nimport \"symbol-observable\";\n\nexport type { Observer, ObservableSubscription, Subscriber };\n\n// The zen-observable package defines Observable.prototype[Symbol.observable]\n// when Symbol is supported, but RxJS interop depends on also setting this fake\n// '@@observable' string as a polyfill for Symbol.observable.\nconst { prototype } = Observable;\nconst fakeObsSymbol = \"@@observable\" as keyof typeof prototype;\nif (!prototype[fakeObsSymbol]) {\n  // @ts-expect-error\n  prototype[fakeObsSymbol] = function () {\n    return this;\n  };\n}\n\nexport { Observable };\n"]}

package/utilities/observables/asyncMap.js

@@ -1,7 +1,12 @@
 import { Observable } from "./Observable.js";
+// Like Observable.prototype.map, except that the mapping function can
+// optionally return a Promise (or be async).
 export function asyncMap(observable, mapFn, catchFn) {
     return new Observable(function (observer) {
         var promiseQueue = {
+            // Normally we would initialize promiseQueue to Promise.resolve(), but
+            // in this case, for backwards compatibility, we need to be careful to
+            // invoke the first callback synchronously.
             then: function (callback) {
                 return new Promise(function (resolve) { return resolve(callback()); });
             },
@@ -10,8 +15,10 @@ export function asyncMap(observable, mapFn, catchFn) {
             return function (arg) {
                 if (examiner) {
                     var both = function () {
-                        return observer.closed
-                            ? 0
+                        // If the observer is closed, we don't want to continue calling the
+                        // mapping function - it's result will be swallowed anyways.
+                        return observer.closed ?
+                            /* will be swallowed */ 0
                             : examiner(arg);
                     };
                     promiseQueue = promiseQueue.then(both, both).then(function (result) { return observer.next(result); }, function (error) { return observer.error(error); });
@@ -25,7 +32,9 @@ export function asyncMap(observable, mapFn, catchFn) {
             next: makeCallback(mapFn, "next"),
             error: makeCallback(catchFn, "error"),
             complete: function () {
-                promiseQueue.then(function () { return observer.complete(); });
+                // no need to reassign `promiseQueue`, after `observer.complete`,
+                // the observer will be closed and short-circuit everything anyways
+                /*promiseQueue = */ promiseQueue.then(function () { return observer.complete(); });
             },
         };
         var sub = observable.subscribe(handler);

package/utilities/observables/asyncMap.js.map

@@ -1 +1 @@
-{"version":3,"file":"asyncMap.js","sourceRoot":"","sources":["../../../src/utilities/observables/asyncMap.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAI7C,MAAM,UAAU,QAAQ,CACtB,UAAyB,EACzB,KAAuC,EACvC,OAA4C;IAE5C,OAAO,IAAI,UAAU,CAAI,UAAC,QAAQ;QAChC,IAAI,YAAY,GAAG;YAIjB,IAAI,YAAC,QAAmB;gBACtB,OAAO,IAAI,OAAO,CAAC,UAAC,OAAO,IAAK,OAAA,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAnB,CAAmB,CAAC,CAAC;YACvD,CAAC;SACe,CAAC;QAEnB,SAAS,YAAY,CACnB,QAAuC,EACvC,GAAqB;YAErB,OAAO,UAAC,GAAG;gBACT,IAAI,QAAQ,EAAE;oBACZ,IAAM,IAAI,GAAG;wBAGX,OAAA,QAAQ,CAAC,MAAM;4BACb,CAAC,CAA0B,CAAS;4BACpC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAFjB,CAEiB,CAAC;oBAEpB,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,CAC/C,UAAC,MAAM,IAAK,OAAA,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAArB,CAAqB,EACjC,UAAC,KAAK,IAAK,OAAA,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAArB,CAAqB,CACjC,CAAC;iBACH;qBAAM;oBACL,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;iBACpB;YACH,CAAC,CAAC;QACJ,CAAC;QAED,IAAM,OAAO,GAAgB;YAC3B,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC;YACjC,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC;YACrC,QAAQ;gBAGc,YAAY,CAAC,IAAI,CAAC,cAAM,OAAA,QAAQ,CAAC,QAAQ,EAAE,EAAnB,CAAmB,CAAC,CAAC;YACnE,CAAC;SACF,CAAC;QAEF,IAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,cAAM,OAAA,GAAG,CAAC,WAAW,EAAE,EAAjB,CAAiB,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { Observer } from \"./Observable.js\";\nimport { Observable } from \"./Observable.js\";\n\n// Like Observable.prototype.map, except that the mapping function can\n// optionally return a Promise (or be async).\nexport function asyncMap<V, R>(\n  observable: Observable<V>,\n  mapFn: (value: V) => R | PromiseLike<R>,\n  catchFn?: (error: any) => R | PromiseLike<R>\n): Observable<R> {\n  return new Observable<R>((observer) => {\n    let promiseQueue = {\n      // Normally we would initialize promiseQueue to Promise.resolve(), but\n      // in this case, for backwards compatibility, we need to be careful to\n      // invoke the first callback synchronously.\n      then(callback: () => any) {\n        return new Promise((resolve) => resolve(callback()));\n      },\n    } as Promise<void>;\n\n    function makeCallback(\n      examiner: typeof mapFn | typeof catchFn,\n      key: \"next\" | \"error\"\n    ): (arg: any) => void {\n      return (arg) => {\n        if (examiner) {\n          const both = () =>\n            // If the observer is closed, we don't want to continue calling the\n            // mapping function - it's result will be swallowed anyways.\n            observer.closed\n              ? /* will be swallowed */ (0 as any)\n              : examiner(arg);\n\n          promiseQueue = promiseQueue.then(both, both).then(\n            (result) => observer.next(result),\n            (error) => observer.error(error)\n          );\n        } else {\n          observer[key](arg);\n        }\n      };\n    }\n\n    const handler: Observer<V> = {\n      next: makeCallback(mapFn, \"next\"),\n      error: makeCallback(catchFn, \"error\"),\n      complete() {\n        // no need to reassign `promiseQueue`, after `observer.complete`,\n        // the observer will be closed and short-circuit everything anyways\n        /*promiseQueue = */ promiseQueue.then(() => observer.complete());\n      },\n    };\n\n    const sub = observable.subscribe(handler);\n    return () => sub.unsubscribe();\n  });\n}\n"]}
+{"version":3,"file":"asyncMap.js","sourceRoot":"","sources":["../../../src/utilities/observables/asyncMap.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,sEAAsE;AACtE,6CAA6C;AAC7C,MAAM,UAAU,QAAQ,CACtB,UAAyB,EACzB,KAAuC,EACvC,OAA4C;IAE5C,OAAO,IAAI,UAAU,CAAI,UAAC,QAAQ;QAChC,IAAI,YAAY,GAAG;YACjB,sEAAsE;YACtE,sEAAsE;YACtE,2CAA2C;YAC3C,IAAI,YAAC,QAAmB;gBACtB,OAAO,IAAI,OAAO,CAAC,UAAC,OAAO,IAAK,OAAA,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAnB,CAAmB,CAAC,CAAC;YACvD,CAAC;SACe,CAAC;QAEnB,SAAS,YAAY,CACnB,QAAuC,EACvC,GAAqB;YAErB,OAAO,UAAC,GAAG;gBACT,IAAI,QAAQ,EAAE,CAAC;oBACb,IAAM,IAAI,GAAG;wBACX,mEAAmE;wBACnE,4DAA4D;wBAC5D,OAAA,QAAQ,CAAC,MAAM,CAAC,CAAC;4BACf,uBAAuB,CAAE,CAAS;4BACpC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;oBAFf,CAEe,CAAC;oBAElB,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,IAAI,CAC/C,UAAC,MAAM,IAAK,OAAA,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAArB,CAAqB,EACjC,UAAC,KAAK,IAAK,OAAA,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAArB,CAAqB,CACjC,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC;QACJ,CAAC;QAED,IAAM,OAAO,GAAgB;YAC3B,IAAI,EAAE,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC;YACjC,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC;YACrC,QAAQ;gBACN,iEAAiE;gBACjE,mEAAmE;gBACnE,mBAAmB,CAAC,YAAY,CAAC,IAAI,CAAC,cAAM,OAAA,QAAQ,CAAC,QAAQ,EAAE,EAAnB,CAAmB,CAAC,CAAC;YACnE,CAAC;SACF,CAAC;QAEF,IAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC1C,OAAO,cAAM,OAAA,GAAG,CAAC,WAAW,EAAE,EAAjB,CAAiB,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { Observer } from \"./Observable.js\";\nimport { Observable } from \"./Observable.js\";\n\n// Like Observable.prototype.map, except that the mapping function can\n// optionally return a Promise (or be async).\nexport function asyncMap<V, R>(\n  observable: Observable<V>,\n  mapFn: (value: V) => R | PromiseLike<R>,\n  catchFn?: (error: any) => R | PromiseLike<R>\n): Observable<R> {\n  return new Observable<R>((observer) => {\n    let promiseQueue = {\n      // Normally we would initialize promiseQueue to Promise.resolve(), but\n      // in this case, for backwards compatibility, we need to be careful to\n      // invoke the first callback synchronously.\n      then(callback: () => any) {\n        return new Promise((resolve) => resolve(callback()));\n      },\n    } as Promise<void>;\n\n    function makeCallback(\n      examiner: typeof mapFn | typeof catchFn,\n      key: \"next\" | \"error\"\n    ): (arg: any) => void {\n      return (arg) => {\n        if (examiner) {\n          const both = () =>\n            // If the observer is closed, we don't want to continue calling the\n            // mapping function - it's result will be swallowed anyways.\n            observer.closed ?\n              /* will be swallowed */ (0 as any)\n            : examiner(arg);\n\n          promiseQueue = promiseQueue.then(both, both).then(\n            (result) => observer.next(result),\n            (error) => observer.error(error)\n          );\n        } else {\n          observer[key](arg);\n        }\n      };\n    }\n\n    const handler: Observer<V> = {\n      next: makeCallback(mapFn, \"next\"),\n      error: makeCallback(catchFn, \"error\"),\n      complete() {\n        // no need to reassign `promiseQueue`, after `observer.complete`,\n        // the observer will be closed and short-circuit everything anyways\n        /*promiseQueue = */ promiseQueue.then(() => observer.complete());\n      },\n    };\n\n    const sub = observable.subscribe(handler);\n    return () => sub.unsubscribe();\n  });\n}\n"]}

package/utilities/observables/iteration.js

@@ -1,4 +1,7 @@
 export function iterateObserversSafely(observers, method, argument) {
+    // In case observers is modified during iteration, we need to commit to the
+    // original elements, which also provides an opportunity to filter them down
+    // to just the observers with the given method.
     var observersWithMethod = [];
     observers.forEach(function (obs) { return obs[method] && observersWithMethod.push(obs); });
     observersWithMethod.forEach(function (obs) { return obs[method](argument); });

package/utilities/observables/iteration.js.map

@@ -1 +1 @@
-{"version":3,"file":"iteration.js","sourceRoot":"","sources":["../../../src/utilities/observables/iteration.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,sBAAsB,CACpC,SAA2B,EAC3B,MAAyB,EACzB,QAAY;IAKZ,IAAM,mBAAmB,GAAkB,EAAE,CAAC;IAC9C,SAAS,CAAC,OAAO,CAAC,UAAC,GAAG,IAAK,OAAA,GAAG,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAA5C,CAA4C,CAAC,CAAC;IACzE,mBAAmB,CAAC,OAAO,CAAC,UAAC,GAAG,IAAK,OAAC,GAAW,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAA9B,CAA8B,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import type { Observer } from \"./Observable.js\";\n\nexport function iterateObserversSafely<E, A>(\n  observers: Set<Observer<E>>,\n  method: keyof Observer<E>,\n  argument?: A\n) {\n  // In case observers is modified during iteration, we need to commit to the\n  // original elements, which also provides an opportunity to filter them down\n  // to just the observers with the given method.\n  const observersWithMethod: Observer<E>[] = [];\n  observers.forEach((obs) => obs[method] && observersWithMethod.push(obs));\n  observersWithMethod.forEach((obs) => (obs as any)[method](argument));\n}\n"]}
+{"version":3,"file":"iteration.js","sourceRoot":"","sources":["../../../src/utilities/observables/iteration.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,sBAAsB,CACpC,SAA2B,EAC3B,MAAyB,EACzB,QAAY;IAEZ,2EAA2E;IAC3E,4EAA4E;IAC5E,+CAA+C;IAC/C,IAAM,mBAAmB,GAAkB,EAAE,CAAC;IAC9C,SAAS,CAAC,OAAO,CAAC,UAAC,GAAG,IAAK,OAAA,GAAG,CAAC,MAAM,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAA5C,CAA4C,CAAC,CAAC;IACzE,mBAAmB,CAAC,OAAO,CAAC,UAAC,GAAG,IAAK,OAAC,GAAW,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,EAA9B,CAA8B,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import type { Observer } from \"./Observable.js\";\n\nexport function iterateObserversSafely<E, A>(\n  observers: Set<Observer<E>>,\n  method: keyof Observer<E>,\n  argument?: A\n) {\n  // In case observers is modified during iteration, we need to commit to the\n  // original elements, which also provides an opportunity to filter them down\n  // to just the observers with the given method.\n  const observersWithMethod: Observer<E>[] = [];\n  observers.forEach((obs) => obs[method] && observersWithMethod.push(obs));\n  observersWithMethod.forEach((obs) => (obs as any)[method](argument));\n}\n"]}

package/utilities/observables/subclassing.js

@@ -1,12 +1,26 @@
 import { Observable } from "./Observable.js";
 import { canUseSymbol } from "../common/canUse.js";
+// Generic implementations of Observable.prototype methods like map and
+// filter need to know how to create a new Observable from an Observable
+// subclass (like Concast or ObservableQuery). Those methods assume
+// (perhaps unwisely?) that they can call the subtype's constructor with a
+// Subscriber function, even though the subclass constructor might expect
+// different parameters. Defining this static Symbol.species property on
+// the subclass is a hint to generic Observable code to use the default
+// constructor instead of trying to do `new Subclass(observer => ...)`.
 export function fixObservableSubclass(subclass) {
     function set(key) {
+        // Object.defineProperty is necessary because the Symbol.species
+        // property is a getter by default in modern JS environments, so we
+        // can't assign to it with a normal assignment expression.
         Object.defineProperty(subclass, key, { value: Observable });
     }
     if (canUseSymbol && Symbol.species) {
         set(Symbol.species);
     }
+    // The "@@species" string is used as a fake Symbol.species value in some
+    // polyfill systems (including the SymbolSpecies variable used by
+    // zen-observable), so we should set it as well, to be safe.
     set("@@species");
     return subclass;
 }

package/utilities/observables/subclassing.js.map

@@ -1 +1 @@
-{"version":3,"file":"subclassing.js","sourceRoot":"","sources":["../../../src/utilities/observables/subclassing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAUnD,MAAM,UAAU,qBAAqB,CAEnC,QAAW;IACX,SAAS,GAAG,CAAC,GAAoB;QAI/B,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,YAAY,IAAI,MAAM,CAAC,OAAO,EAAE;QAClC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;KACrB;IAID,GAAG,CAAC,WAAW,CAAC,CAAC;IACjB,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["import { Observable } from \"./Observable.js\";\nimport { canUseSymbol } from \"../common/canUse.js\";\n\n// Generic implementations of Observable.prototype methods like map and\n// filter need to know how to create a new Observable from an Observable\n// subclass (like Concast or ObservableQuery). Those methods assume\n// (perhaps unwisely?) that they can call the subtype's constructor with a\n// Subscriber function, even though the subclass constructor might expect\n// different parameters. Defining this static Symbol.species property on\n// the subclass is a hint to generic Observable code to use the default\n// constructor instead of trying to do `new Subclass(observer => ...)`.\nexport function fixObservableSubclass<\n  S extends new (...args: any[]) => Observable<any>,\n>(subclass: S): S {\n  function set(key: symbol | string) {\n    // Object.defineProperty is necessary because the Symbol.species\n    // property is a getter by default in modern JS environments, so we\n    // can't assign to it with a normal assignment expression.\n    Object.defineProperty(subclass, key, { value: Observable });\n  }\n  if (canUseSymbol && Symbol.species) {\n    set(Symbol.species);\n  }\n  // The \"@@species\" string is used as a fake Symbol.species value in some\n  // polyfill systems (including the SymbolSpecies variable used by\n  // zen-observable), so we should set it as well, to be safe.\n  set(\"@@species\");\n  return subclass;\n}\n"]}
+{"version":3,"file":"subclassing.js","sourceRoot":"","sources":["../../../src/utilities/observables/subclassing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,uEAAuE;AACvE,wEAAwE;AACxE,mEAAmE;AACnE,0EAA0E;AAC1E,yEAAyE;AACzE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,MAAM,UAAU,qBAAqB,CAEnC,QAAW;IACX,SAAS,GAAG,CAAC,GAAoB;QAC/B,gEAAgE;QAChE,mEAAmE;QACnE,0DAA0D;QAC1D,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,YAAY,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,wEAAwE;IACxE,iEAAiE;IACjE,4DAA4D;IAC5D,GAAG,CAAC,WAAW,CAAC,CAAC;IACjB,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["import { Observable } from \"./Observable.js\";\nimport { canUseSymbol } from \"../common/canUse.js\";\n\n// Generic implementations of Observable.prototype methods like map and\n// filter need to know how to create a new Observable from an Observable\n// subclass (like Concast or ObservableQuery). Those methods assume\n// (perhaps unwisely?) that they can call the subtype's constructor with a\n// Subscriber function, even though the subclass constructor might expect\n// different parameters. Defining this static Symbol.species property on\n// the subclass is a hint to generic Observable code to use the default\n// constructor instead of trying to do `new Subclass(observer => ...)`.\nexport function fixObservableSubclass<\n  S extends new (...args: any[]) => Observable<any>,\n>(subclass: S): S {\n  function set(key: symbol | string) {\n    // Object.defineProperty is necessary because the Symbol.species\n    // property is a getter by default in modern JS environments, so we\n    // can't assign to it with a normal assignment expression.\n    Object.defineProperty(subclass, key, { value: Observable });\n  }\n  if (canUseSymbol && Symbol.species) {\n    set(Symbol.species);\n  }\n  // The \"@@species\" string is used as a fake Symbol.species value in some\n  // polyfill systems (including the SymbolSpecies variable used by\n  // zen-observable), so we should set it as well, to be safe.\n  set(\"@@species\");\n  return subclass;\n}\n"]}

package/utilities/policies/pagination.js

@@ -1,6 +1,8 @@
 import { __assign, __rest as __rest_1, __spreadArray } from "tslib";
 import { __rest } from "tslib";
 import { mergeDeep } from "../common/mergeDeep.js";
+// A very basic pagination field policy that always concatenates new
+// results onto the existing array, without examining options.args.
 export function concatPagination(keyArgs) {
     if (keyArgs === void 0) { keyArgs = false; }
     return {
@@ -10,6 +12,10 @@ export function concatPagination(keyArgs) {
         },
     };
 }
+// A basic field policy that uses options.args.{offset,limit} to splice
+// the incoming data into the existing array. If your arguments are called
+// something different (like args.{start,count}), feel free to copy/paste
+// this implementation and make the appropriate changes.
 export function offsetLimitPagination(keyArgs) {
     if (keyArgs === void 0) { keyArgs = false; }
     return {
@@ -19,12 +25,17 @@ export function offsetLimitPagination(keyArgs) {
             var merged = existing ? existing.slice(0) : [];
             if (incoming) {
                 if (args) {
+                    // Assume an offset of 0 if args.offset omitted.
                     var _b = args.offset, offset = _b === void 0 ? 0 : _b;
                     for (var i = 0; i < incoming.length; ++i) {
                         merged[offset + i] = incoming[i];
                     }
                 }
                 else {
+                    // It's unusual (probably a mistake) for a paginated field not
+                    // to receive any arguments, so you might prefer to throw an
+                    // exception here, instead of recovering by appending incoming
+                    // onto the existing array.
                     merged.push.apply(merged, incoming);
                 }
             }
@@ -32,6 +43,9 @@ export function offsetLimitPagination(keyArgs) {
         },
     };
 }
+// As proof of the flexibility of field policies, this function generates
+// one that handles Relay-style pagination, without Apollo Client knowing
+// anything about connections, edges, cursors, or pageInfo objects.
 export function relayStylePagination(keyArgs) {
     if (keyArgs === void 0) { keyArgs = false; }
     return {
@@ -44,6 +58,8 @@ export function relayStylePagination(keyArgs) {
             var firstEdgeCursor = "";
             var lastEdgeCursor = "";
             existing.edges.forEach(function (edge) {
+                // Edges themselves could be Reference objects, so it's important
+                // to use readField to access the edge.edge.node property.
                 if (canRead(readField("node", edge))) {
                     edges.push(edge);
                     if (edge.cursor) {
@@ -56,7 +72,10 @@ export function relayStylePagination(keyArgs) {
                 firstEdgeCursor = "";
             }
             var _b = existing.pageInfo || {}, startCursor = _b.startCursor, endCursor = _b.endCursor;
-            return __assign(__assign({}, getExtras(existing)), { edges: edges, pageInfo: __assign(__assign({}, existing.pageInfo), { startCursor: startCursor || firstEdgeCursor, endCursor: endCursor || lastEdgeCursor }) });
+            return __assign(__assign({}, getExtras(existing)), { edges: edges, pageInfo: __assign(__assign({}, existing.pageInfo), { 
+                    // If existing.pageInfo.{start,end}Cursor are undefined or "", default
+                    // to firstEdgeCursor and/or lastEdgeCursor.
+                    startCursor: startCursor || firstEdgeCursor, endCursor: endCursor || lastEdgeCursor }) });
         },
         merge: function (existing, incoming, _a) {
             var args = _a.args, isReference = _a.isReference, readField = _a.readField;
@@ -66,9 +85,11 @@ export function relayStylePagination(keyArgs) {
             if (!incoming) {
                 return existing;
             }
-            var incomingEdges = incoming.edges
-                ? incoming.edges.map(function (edge) {
+            var incomingEdges = incoming.edges ?
+                incoming.edges.map(function (edge) {
                     if (isReference((edge = __assign({}, edge)))) {
+                        // In case edge is a Reference, we read out its cursor field and
+                        // store it as an extra property of the Reference object.
                         edge.cursor = readField("cursor", edge);
                     }
                     return edge;
@@ -79,12 +100,16 @@ export function relayStylePagination(keyArgs) {
                 var startCursor = pageInfo_1.startCursor, endCursor = pageInfo_1.endCursor;
                 var firstEdge = incomingEdges[0];
                 var lastEdge = incomingEdges[incomingEdges.length - 1];
+                // In case we did not request the cursor field for edges in this
+                // query, we can still infer cursors from pageInfo.
                 if (firstEdge && startCursor) {
                     firstEdge.cursor = startCursor;
                 }
                 if (lastEdge && endCursor) {
                     lastEdge.cursor = endCursor;
                 }
+                // Cursors can also come from edges, so we default
+                // pageInfo.{start,end}Cursor to {first,last}Edge.cursor.
                 var firstCursor = firstEdge && firstEdge.cursor;
                 if (firstCursor && !startCursor) {
                     incoming = mergeDeep(incoming, {
@@ -105,9 +130,13 @@ export function relayStylePagination(keyArgs) {
             var prefix = existing.edges;
             var suffix = [];
             if (args && args.after) {
+                // This comparison does not need to use readField("cursor", edge),
+                // because we stored the cursor field of any Reference edges as an
+                // extra property of the Reference object.
                 var index = prefix.findIndex(function (edge) { return edge.cursor === args.after; });
                 if (index >= 0) {
                     prefix = prefix.slice(0, index + 1);
+                    // suffix = []; // already true
                 }
             }
             else if (args && args.before) {
@@ -116,13 +145,27 @@ export function relayStylePagination(keyArgs) {
                 prefix = [];
             }
             else if (incoming.edges) {
+                // If we have neither args.after nor args.before, the incoming
+                // edges cannot be spliced into the existing edges, so they must
+                // replace the existing edges. See #6592 for a motivating example.
                 prefix = [];
             }
             var edges = __spreadArray(__spreadArray(__spreadArray([], prefix, true), incomingEdges, true), suffix, true);
             var pageInfo = __assign(__assign({}, incoming.pageInfo), existing.pageInfo);
             if (incoming.pageInfo) {
                 var _b = incoming.pageInfo, hasPreviousPage = _b.hasPreviousPage, hasNextPage = _b.hasNextPage, startCursor = _b.startCursor, endCursor = _b.endCursor, extras = __rest_1(_b, ["hasPreviousPage", "hasNextPage", "startCursor", "endCursor"]);
+                // If incoming.pageInfo had any extra non-standard properties,
+                // assume they should take precedence over any existing properties
+                // of the same name, regardless of where this page falls with
+                // respect to the existing data.
                 Object.assign(pageInfo, extras);
+                // Keep existing.pageInfo.has{Previous,Next}Page unless the
+                // placement of the incoming edges means incoming.hasPreviousPage
+                // or incoming.hasNextPage should become the new values for those
+                // properties in existing.pageInfo. Note that these updates are
+                // only permitted when the beginning or end of the incoming page
+                // coincides with the beginning or end of the existing data, as
+                // determined using prefix.length and suffix.length.
                 if (!prefix.length) {
                     if (void 0 !== hasPreviousPage)
                         pageInfo.hasPreviousPage = hasPreviousPage;
@@ -140,6 +183,7 @@ export function relayStylePagination(keyArgs) {
         },
     };
 }
+// Returns any unrecognized properties of the given object.
 var getExtras = function (obj) { return __rest(obj, notExtras); };
 var notExtras = ["edges", "pageInfo"];
 function makeEmptyData() {