@osdk/client 2.5.0-beta.1 → 2.5.0-beta.2

package/build/esm/observable/internal/ListQuery.js

@@ -16,44 +16,74 @@
 
 import deepEqual from "fast-deep-equal";
 import groupBy from "object.groupby";
-import { auditTime, combineLatest, connectable, map, of, ReplaySubject, switchMap } from "rxjs";
 import invariant from "tiny-invariant";
 import { additionalContext } from "../../Client.js";
 import { ObjectDefRef, UnderlyingOsdkObject } from "../../object/convertWireToOsdkObjects/InternalSymbols.js";
 import { DEBUG_ONLY__cacheKeysToString } from "./CacheKey.js";
 import { DEBUG_ONLY__changesToString } from "./Changes.js";
+import { createCollectionConnectable } from "./createCollectionConnectable.js";
+import { isObjectInstance } from "./isObjectInstance.js";
 import { objectSortaMatchesWhereClause as objectMatchesWhereClause } from "./objectMatchesWhereClause.js";
 import { storeOsdkInstances } from "./ObjectQuery.js";
 import { Query } from "./Query.js";
+import { removeDuplicates } from "./removeDuplicates.js";
+import { NoOpSortingStrategy, OrderBySortingStrategy } from "./sorting/SortingStrategy.js";
 export const API_NAME_IDX = 1;
 export const TYPE_IDX = 0;
 export const WHERE_IDX = 2;
 export const ORDER_BY_IDX = 3;
-class BaseListQuery extends Query {
-  //
-  // Per list type implementations
-  //
+/**
+ * Base class for collection-based queries (lists and links)
+ * Provides common functionality for working with collections of objects
+ */
+export class BaseListQuery extends Query {
+  /**
+   * The sorting strategy to use for this collection
+   * @protected
+   */
+  sortingStrategy = new NoOpSortingStrategy();
+
+  // Collection-specific behavior is implemented by subclasses
+  /**
+   * Token for the next page of results
+   * @protected
+   */
+
+  /**
+   * Promise tracking an in-progress page fetch
+   * @protected
+   */
 
   //
   // Shared Implementations
   //
 
   /**
-   * Only intended to be "protected" and used by subclasses but exposed for
-   * testing.
+   * Standard method to update a list of objects
+   * Handles common list update patterns for both ListQuery and SpecificLinkQuery
    *
-   * @param objectCacheKeys
-   * @param append
-   * @param status
-   * @param batch
-   * @returns
+   * @param items Objects or cache keys to add to the list
+   * @param status Status to set for the list
+   * @param batch Batch context to use
+   * @param append Whether to append to the existing list or replace it
+   * @returns The updated entry
    */
-  _updateList(objectCacheKeys, append, status, batch) {
+  _updateList(items, status, batch, append = false) {
     if (process.env.NODE_ENV !== "production") {
       const logger = process.env.NODE_ENV !== "production" ? this.logger?.child({
         methodName: "updateList"
       }) : this.logger;
-      logger?.debug(`{status: ${status}}`, JSON.stringify(objectCacheKeys, null, 2));
+      logger?.debug(`{status: ${status}, append: ${append}}`, JSON.stringify(items, null, 2));
+    }
+    let objectCacheKeys;
+    if (items.length === 0) {
+      objectCacheKeys = [];
+    } else if (isObjectInstance(items[0])) {
+      // Items are object instances, need to store them first
+      objectCacheKeys = this.storeObjects(items, batch);
+    } else {
+      // Items are already cache keys
+      objectCacheKeys = items;
     }
     objectCacheKeys = this.#retainReleaseAppend(batch, append, objectCacheKeys);
     objectCacheKeys = this._sortCacheKeys(objectCacheKeys, batch);
@@ -62,14 +92,32 @@ class BaseListQuery extends Query {
       data: objectCacheKeys
     }, status, batch);
   }
+
+  /**
+   * Common implementation for writing to store for collection-based queries
+   * @param data The collection data to write to the store
+   * @param status The status to set
+   * @param batch The batch context
+   */
   writeToStore(data, status, batch) {
     const entry = batch.read(this.cacheKey);
     if (entry && deepEqual(data, entry.value)) {
+      // Check if both data AND status are the same
+      if (entry.status === status) {
+        if (process.env.NODE_ENV !== "production") {
+          this.logger?.child({
+            methodName: "writeToStore"
+          }).debug(`Collection data was deep equal and status unchanged (${status}), skipping update`);
+        }
+        // Return the existing entry without writing to avoid unnecessary notifications
+        return entry;
+      }
       if (process.env.NODE_ENV !== "production") {
         this.logger?.child({
           methodName: "writeToStore"
-        }).debug(`Object was deep equal, just setting status`);
+        }).debug(`Collection data was deep equal, just updating status from ${entry.status} to ${status}`);
       }
+      // Keep the same value but update status and lastUpdated
       return batch.write(this.cacheKey, entry.value, status);
     }
     if (process.env.NODE_ENV !== "production") {
@@ -78,9 +126,37 @@ class BaseListQuery extends Query {
       }).debug(`{status: ${status}},`, DEBUG_ONLY__cacheKeysToString(data.data));
     }
     const ret = batch.write(this.cacheKey, data, status);
-    batch.changes.registerList(this.cacheKey);
+    this.registerCacheChanges(batch);
     return ret;
   }
+
+  /**
+   * Register changes to the cache based on the specific collection type
+   * Implemented by subclasses to handle specific change registration
+   */
+
+  /**
+   * Common method to store objects in the cache and return their cache keys
+   * Used by collection queries when storing object references
+   *
+   * @param objects Array of objects to store
+   * @param batch The batch context to use
+   * @returns Array of cache keys for the stored objects
+   */
+  storeObjects(objects, batch) {
+    // Store the individual objects in their respective cache entries
+    return objects.length > 0 ? storeOsdkInstances(this.store, objects, batch) : [];
+  }
+
+  /**
+   * Common method for managing object reference counting and appending results
+   * Used by collection queries when updating object references
+   *
+   * @param batch The batch context to use
+   * @param append Whether to append to existing objects or replace them
+   * @param objectCacheKeys Array of object cache keys to process
+   * @returns The final array of object cache keys after retain/release/append
+   */
   #retainReleaseAppend(batch, append, objectCacheKeys) {
     const existingList = batch.read(this.cacheKey);
 
@@ -115,73 +191,102 @@ class BaseListQuery extends Query {
       }
     });
   }
-}
-export class ListQuery extends BaseListQuery {
-  // pageSize?: number; // this is the internal page size. we need to track this properly
-
-  #type;
-  #apiName;
-  #whereClause;
 
-  // this represents the minimum number of results we need to load if we revalidate
-  #minNumResults = 0;
-  #nextPageToken;
-  #pendingPageFetch;
-  #orderBy;
-  #objectSet;
-  #sortFns;
-  constructor(store, subject, apiType, apiName, whereClause, orderBy, cacheKey, opts) {
-    super(store, subject, opts, cacheKey, process.env.NODE_ENV !== "production" ? store.client[additionalContext].logger?.child({}, {
-      msgPrefix: `ListQuery<${cacheKey.otherKeys.map(x => JSON.stringify(x)).join(", ")}>`
-    }) : undefined);
-    this.#type = apiType;
-    this.#apiName = apiName;
-    this.#whereClause = whereClause;
-    this.#orderBy = orderBy;
-    this.#objectSet = store.client({
-      type: this.#type,
-      apiName: this.#apiName
-    }).where(this.#whereClause);
-    this.#sortFns = createOrderBySortFns(this.#orderBy);
-  }
-  get canonicalWhere() {
-    return this.#whereClause;
+  /**
+   * Creates a payload from collection parameters
+   * Default implementation that covers common fields for all collection types
+   * Subclasses may override to add type-specific fields if needed
+   *
+   * @param params Common collection parameters
+   * @returns A typed payload for the specific collection type
+   */
+  createPayload(params) {
+    return {
+      resolvedList: params.resolvedData,
+      isOptimistic: params.isOptimistic,
+      fetchMore: this.fetchMore,
+      hasMore: this.nextPageToken != null,
+      status: params.status,
+      lastUpdated: params.lastUpdated
+    }; // Type assertion needed since we don't know exact subtype
   }
+
+  /**
+   * Creates a connectable observable for this collection
+   * Common implementation shared by all collection types
+   *
+   * @param subject The subject to connect to
+   * @returns A connectable observable of the collection's payload type
+   */
   _createConnectable(subject) {
-    return connectable(subject.pipe(switchMap(listEntry => {
-      return combineLatest({
-        resolvedList: listEntry?.value?.data == null || listEntry.value.data.length === 0 ? of([]) : combineLatest(listEntry.value.data.map(cacheKey => this.store.getSubject(cacheKey).pipe(map(objectEntry => objectEntry?.value)))),
-        isOptimistic: of(listEntry.isOptimistic),
-        fetchMore: of(this.fetchMore),
-        hasMore: of(this.#nextPageToken != null),
-        status: of(listEntry.status),
-        lastUpdated: of(listEntry.lastUpdated)
-      });
-    }),
-    // like throttle but returns the tail
-    auditTime(0)), {
-      resetOnDisconnect: false,
-      connector: () => new ReplaySubject(1)
-    });
+    return createCollectionConnectable(subject, this.store, params => this.createPayload(params));
   }
+
+  /**
+   * @override Reset pagination state before a fetch
+   */
   _preFetch() {
-    this.#nextPageToken = undefined;
+    this.nextPageToken = undefined;
+    super._preFetch();
   }
+
+  /**
+   * Common fetchMore implementation for pagination
+   * Handles pending request management and loading states
+   */
+  fetchMore = () => {
+    if (this.pendingPageFetch) {
+      return this.pendingPageFetch;
+    }
+    if (this.pendingFetch) {
+      this.pendingPageFetch = new Promise(async res => {
+        await this.pendingFetch;
+        res(this.fetchMore());
+      });
+      return this.pendingPageFetch;
+    }
+    if (this.nextPageToken == null) {
+      return Promise.resolve(undefined);
+    }
+    this.store.batch({}, batch => {
+      this.setStatus("loading", batch);
+    });
+    this.pendingFetch = this.fetchPageAndUpdate("loaded", this.abortController?.signal).then(() => void 0).finally(() => {
+      this.pendingPageFetch = undefined;
+    });
+    return this.pendingFetch;
+  };
+
+  /**
+   * Minimum number of results to load initially
+   * May be overridden by subclasses for specific collection types
+   * @protected
+   */
+  minResultsToLoad = 0;
+
+  /**
+   * Common _fetchAndStore implementation for pagination
+   * Uses fetchPageAndUpdate to load the initial set of data
+   * Will load multiple pages if necessary to reach minResultsToLoad
+   */
   async _fetchAndStore() {
     if (process.env.NODE_ENV !== "production") {
       this.logger?.child({
         methodName: "_fetchAndStore"
       }).debug("fetching pages");
     }
+
+    // Keep fetching pages until we have the minimum number of results or no more pages
     while (true) {
-      const entry = await this.#fetchPageAndUpdate(this.#objectSet, "loading", this.abortController?.signal);
+      const entry = await this.fetchPageAndUpdate("loading", this.abortController?.signal);
       if (!entry) {
         // we were aborted
         return;
       }
-      !entry.value?.data ? process.env.NODE_ENV !== "production" ? invariant(false) : invariant(false) : void 0;
-      const count = entry.value.data.length;
-      if (count > this.#minNumResults || this.#nextPageToken == null) {
+
+      // Check if we have enough results or no more pages
+      const count = entry.value?.data.length || 0;
+      if (count >= this.minResultsToLoad || this.nextPageToken == null) {
         break;
       }
     }
@@ -190,69 +295,237 @@ export class ListQuery extends BaseListQuery {
     });
     return Promise.resolve();
   }
-  fetchMore = () => {
-    if (this.#pendingPageFetch) {
-      return this.#pendingPageFetch;
-    }
-    if (this.pendingFetch) {
-      this.#pendingPageFetch = new Promise(async res => {
-        await this.pendingFetch;
-        res(this.fetchMore());
-      });
-      return this.#pendingPageFetch;
+
+  /**
+   * Template method for fetching a page of data and updating the store
+   * Provides common error handling and abort signal checking
+   *
+   * @param status The status to set for the entry
+   * @param signal Optional AbortSignal for cancellation
+   * @returns A promise that resolves to the updated entry or undefined if aborted
+   */
+  async fetchPageAndUpdate(status, signal) {
+    if (process.env.NODE_ENV !== "production") {
+      this.logger?.child({
+        methodName: "fetchPageAndUpdate"
+      }).debug(`Fetching data with status: ${status}`);
     }
-    if (this.#nextPageToken == null) {
-      return Promise.resolve();
+
+    // Early abort check
+    if (signal?.aborted) {
+      return undefined;
     }
-    this.store.batch({}, batch => {
-      this.setStatus("loading", batch);
-    });
-    this.pendingFetch = this.#fetchPageAndUpdate(this.#objectSet, "loaded", this.abortController?.signal).finally(() => {
-      this.#pendingPageFetch = undefined;
-    });
-    return this.pendingFetch;
-  };
-  async #fetchPageAndUpdate(objectSet, status, signal) {
-    const append = this.#nextPageToken != null;
     try {
-      let {
-        data,
-        nextPageToken
-      } = await objectSet.fetchPage({
-        $nextPageToken: this.#nextPageToken,
-        $pageSize: this.options.pageSize,
-        // For now this keeps the shared test code from falling apart
-        // but shouldn't be needed ideally
-        ...(Object.keys(this.#orderBy).length > 0 ? {
-          $orderBy: this.#orderBy
-        } : {})
-      });
+      // Call the subclass-specific implementation to fetch data
+      const result = await this.fetchPageData(signal);
+
+      // Check for abort again after fetch
       if (signal?.aborted) {
-        return;
+        return undefined;
       }
-      this.#nextPageToken = nextPageToken;
 
-      // Our caching really expects to have the full objects in the list
-      // so we need to fetch them all here
-      if (this.#type === "interface") {
-        data = await reloadDataAsFullObjects(this.store.client, data);
-      }
+      // Store the fetched data using batch operations
       const {
         retVal
       } = this.store.batch({}, batch => {
-        return this._updateList(storeOsdkInstances(this.store, data, batch), append, nextPageToken ? status : "loaded", batch);
+        const append = this.nextPageToken != null;
+        const finalStatus = result.nextPageToken ? status : "loaded";
+        return this._updateList(this.storeObjects(result.data, batch), finalStatus, batch, append);
       });
       return retVal;
-    } catch (e) {
-      this.logger?.error("error", e);
-      this.store.getSubject(this.cacheKey).error(e);
+    } catch (error) {
+      // Log any errors that occur
+      if (process.env.NODE_ENV !== "production") {
+        this.logger?.child({
+          methodName: "fetchPageAndUpdate"
+        }).error("Error fetching data", error);
+      }
 
-      // rethrowing would result in many unhandled promise rejections
-      // which i don't think we want
-      // throw e;
+      // For unexpected errors, write error status if not aborted
+      if (!signal?.aborted) {
+        const {
+          retVal
+        } = this.store.batch({}, batch => {
+          return this.handleFetchError(error, status, batch);
+        });
+        return retVal;
+      }
+
+      // If aborted, just return undefined
+      return undefined;
     }
   }
 
+  /**
+   * Abstract method that subclasses implement for their specific data fetching logic
+   *
+   * @param signal Optional AbortSignal for cancellation
+   * @returns A promise that resolves to the fetched data
+   */
+
+  /**
+   * Handle fetch errors by setting appropriate error state
+   * Default implementation that subclasses can override
+   *
+   * @param error The error that occurred
+   * @param status The intended status if successful
+   * @param batch The batch context to use
+   * @returns The updated entry with error status
+   */
+  handleFetchError(_error, _status, batch) {
+    // Default implementation writes an empty list with error status
+    // Most subclasses should be able to use this
+    return this.writeToStore({
+      data: []
+    }, "error", batch);
+  }
+
+  /**
+   * Sort the collection items using the configured sorting strategy
+   * @param objectCacheKeys - The cache keys to sort
+   * @param batch - The batch context
+   * @returns Sorted array of cache keys
+   */
+  _sortCacheKeys(objectCacheKeys, batch) {
+    return this.sortingStrategy.sortCacheKeys(objectCacheKeys, batch);
+  }
+
+  /**
+   * Unified method for updating collection data in the store
+   * Handles storing, sorting, deduplication, and reference counting
+   *
+   * @param items - Either object cache keys or object instances to update
+   * @param options - Configuration options for the update
+   * @param batch - The batch context to use
+   * @returns The updated entry
+   */
+  updateCollection(items, options, batch) {
+    if (process.env.NODE_ENV !== "production") {
+      const logger = process.env.NODE_ENV !== "production" ? this.logger?.child({
+        methodName: "updateCollection"
+      }) : this.logger;
+      logger?.debug(`{status: ${options.status}, append: ${options.append}}`, JSON.stringify(items, null, 2));
+    }
+
+    // Step 1: Convert items to object cache keys if needed
+    let objectCacheKeys;
+    if (items.length === 0) {
+      objectCacheKeys = [];
+    } else if (isObjectInstance(items[0])) {
+      // Items are object instances, need to store them first
+      objectCacheKeys = this.storeObjects(items, batch);
+    } else {
+      // Items are already cache keys
+      objectCacheKeys = items;
+    }
+
+    // Step 2: Handle retain/release/append logic
+    objectCacheKeys = this.#retainReleaseAppend(batch, options.append ?? false, objectCacheKeys);
+
+    // Step 3: Sort using the configured sorting strategy
+    objectCacheKeys = this._sortCacheKeys(objectCacheKeys, batch);
+
+    // Step 4: Remove duplicates
+    objectCacheKeys = removeDuplicates(objectCacheKeys, batch);
+
+    // Step 5: Write to store
+    return this.writeToStore({
+      data: objectCacheKeys
+    }, options.status, batch);
+  }
+}
+
+/**
+ * Implements filtered and sorted object collection queries.
+ * - Handles where clause filtering and orderBy sorting
+ * - Manages pagination through fetchMore
+ * - Auto-updates when matching objects change
+ * - Uses canonicalized cache keys for consistency
+ */
+export class ListQuery extends BaseListQuery {
+  // pageSize?: number; // this is the internal page size. we need to track this properly
+
+  #type;
+  #apiName;
+  #whereClause;
+
+  // Using base class minResultsToLoad instead of a private property
+  #orderBy;
+  #objectSet;
+
+  /**
+   * Register changes to the cache specific to ListQuery
+   */
+  registerCacheChanges(batch) {
+    batch.changes.registerList(this.cacheKey);
+  }
+  constructor(store, subject, apiType, apiName, whereClause, orderBy, cacheKey, opts) {
+    super(store, subject, opts, cacheKey, process.env.NODE_ENV !== "production" ? store.client[additionalContext].logger?.child({}, {
+      msgPrefix: `ListQuery<${cacheKey.otherKeys.map(x => JSON.stringify(x)).join(", ")}>`
+    }) : undefined);
+    this.#type = apiType;
+    this.#apiName = apiName;
+    this.#whereClause = whereClause;
+    this.#orderBy = orderBy;
+    this.#objectSet = store.client({
+      type: this.#type,
+      apiName: this.#apiName
+    }).where(this.#whereClause);
+    // Initialize the sorting strategy
+    this.sortingStrategy = new OrderBySortingStrategy(this.#apiName, this.#orderBy);
+    // Initialize the minResultsToLoad inherited from BaseCollectionQuery
+    this.minResultsToLoad = 0;
+  }
+  get canonicalWhere() {
+    return this.#whereClause;
+  }
+
+  /**
+   * Implements fetchPageData from BaseCollectionQuery template method
+   * Fetches a page of data
+   */
+  async fetchPageData(signal) {
+    // Fetch the data with pagination
+    const resp = await this.#objectSet.fetchPage({
+      $nextPageToken: this.nextPageToken,
+      $pageSize: this.options.pageSize,
+      // For now this keeps the shared test code from falling apart
+      // but shouldn't be needed ideally
+      ...(Object.keys(this.#orderBy).length > 0 ? {
+        $orderBy: this.#orderBy
+      } : {})
+    });
+    if (signal?.aborted) {
+      throw new Error("Aborted");
+    }
+    this.nextPageToken = resp.nextPageToken;
+    let fetchedData = resp.data;
+
+    // Our caching really expects to have the full objects in the list
+    // so we need to fetch them all here
+    if (this.#type === "interface") {
+      fetchedData = await reloadDataAsFullObjects(this.store.client, fetchedData);
+    }
+    return {
+      ...resp,
+      data: fetchedData
+    };
+  }
+
+  /**
+   * Handle fetch errors by setting appropriate error state and notifying subscribers
+   */
+  handleFetchError(error, _status, batch) {
+    this.logger?.error("error", error);
+    this.store.getSubject(this.cacheKey).error(error);
+
+    // We don't call super.handleFetchError because ListQuery has special error handling
+    // but we still use writeToStore to create a properly structured Entry
+    return this.writeToStore({
+      data: []
+    }, "error", batch);
+  }
+
   /**
    * Will revalidate the list if its query is affected by invalidating the
    * apiName of the object type passed in.
@@ -278,6 +551,13 @@ export class ListQuery extends BaseListQuery {
       await this.revalidate(/* force */true);
     }
   };
+  invalidateObjectType = async (objectType, changes) => {
+    if (this.cacheKey.otherKeys[1] === objectType) {
+      // Only invalidate lists for the matching apiName
+      changes?.modified.add(this.cacheKey);
+      return this.revalidate(true);
+    }
+  };
 
   /**
    * Note: This method is not async because I want it to return right after it
@@ -294,6 +574,9 @@ export class ListQuery extends BaseListQuery {
       this.logger?.child({
         methodName: "maybeUpdateAndRevalidate"
       }).debug(DEBUG_ONLY__changesToString(changes));
+      this.logger?.child({
+        methodName: "maybeUpdateAndRevalidate"
+      }).debug(`Already in changes? ${changes.modified.has(this.cacheKey)}`);
     }
     if (changes.modified.has(this.cacheKey)) return;
     // mark ourselves as updated so we don't infinite recurse.
@@ -354,7 +637,7 @@ export class ListQuery extends BaseListQuery {
         for (const obj of toAdd) {
           newList.push(this.store.getCacheKey("object", obj.$objectType, obj.$primaryKey));
         }
-        this._updateList(newList, /* append */false, status, batch);
+        this._updateList(newList, status, batch, /* append */false);
       });
       if (needsRevalidation) {
         return this.revalidate(true);
@@ -427,20 +710,6 @@ export class ListQuery extends BaseListQuery {
       }
     };
   }
-  _sortCacheKeys(objectCacheKeys, batch) {
-    if (Object.keys(this.#orderBy).length > 0) {
-      objectCacheKeys = objectCacheKeys.sort((a, b) => {
-        for (const sortFn of this.#sortFns) {
-          const ret = sortFn(batch.read(a)?.value?.$as(this.#apiName), batch.read(b)?.value?.$as(this.#apiName));
-          if (ret !== 0) {
-            return ret;
-          }
-        }
-        return 0;
-      });
-    }
-    return objectCacheKeys;
-  }
   registerStreamUpdates(sub) {
     const logger = process.env.NODE_ENV !== "production" ? this.logger?.child({
       methodName: "registerStreamUpdates"
@@ -505,7 +774,7 @@ export class ListQuery extends BaseListQuery {
     if (state === "ADDED_OR_UPDATED") {
       const object = objOrIface.$apiName !== objOrIface.$objectType ? objOrIface.$as(objOrIface.$objectType) : objOrIface;
       this.store.batch({}, batch => {
-        storeOsdkInstances(this.store, [object], batch);
+        this.storeObjects([object], batch);
       });
     } else if (state === "REMOVED") {
       this.#onOswRemoved(objOrIface, logger);
@@ -554,37 +823,6 @@ export class ListQuery extends BaseListQuery {
     });
   }
 }
-function removeDuplicates(objectCacheKeys, batch) {
-  const visited = new Set();
-  objectCacheKeys = objectCacheKeys.filter(key => {
-    batch.read(key);
-    if (visited.has(key)) {
-      return false;
-    }
-    visited.add(key);
-    return true;
-  });
-  return objectCacheKeys;
-}
-function createOrderBySortFns(orderBy) {
-  return Object.entries(orderBy).map(([key, order]) => {
-    return (a, b) => {
-      const aValue = a?.[key];
-      const bValue = b?.[key];
-      if (aValue == null && bValue == null) {
-        return 0;
-      }
-      if (aValue == null) {
-        return 1;
-      }
-      if (bValue == null) {
-        return -1;
-      }
-      const m = order === "asc" ? -1 : 1;
-      return aValue < bValue ? m : aValue > bValue ? -m : 0;
-    };
-  });
-}
 
 // Hopefully this can go away when we can just request the full object properties on first load
 async function reloadDataAsFullObjects(client, data) {