@squidcloud/client 1.0.71 → 1.0.73

package/dist/typescript-client/src/destruct.manager.d.ts

@@ -5,7 +5,7 @@ export declare class DestructManager {
     private readonly destructors;
     private readonly isDestructedSubject;
     get isDestructing(): boolean;
-    get isDestructingObservable(): Observable<boolean>;
+    observeIsDestructing(): Observable<void>;
     onPreDestruct(fn: DestructorFn): void;
     onDestruct(fn: DestructorFn): void;
     destruct(): Promise<void>;

package/dist/typescript-client/src/query/join-query-builder.factory.d.ts

@@ -1,4 +1,4 @@
-import { DocumentData, FieldName, Operator, PrimitiveFieldType } from '@squidcloud/common';
+import { BaseQueryBuilderInterface, DocumentData, FieldName, Operator, PrimitiveFieldType } from '@squidcloud/common';
 import { Observable } from 'rxjs';
 import { DocumentReference } from '../document-reference';
 import { Alias } from './query.types';
@@ -7,7 +7,7 @@ import { Alias } from './query.types';
  * To learn more about join queries, see
  * {@link https://docs.squid.cloud/docs/client-sdk/queries#joining-data-across-collections-and-integrations}.
  */
-export declare class JoinQueryBuilder<DocumentType extends DocumentData, MyAlias extends Alias, ReturnType extends Record<MyAlias, DocumentReference<DocumentType> | undefined>> {
+export declare class JoinQueryBuilder<DocumentType extends DocumentData, MyAlias extends Alias, ReturnType extends Record<MyAlias, DocumentReference<DocumentType> | undefined>> extends BaseQueryBuilderInterface<ReturnType> {
     private readonly collectionName;
     private readonly integrationId;
     private readonly querySubscriptionManager;

package/dist/typescript-client/src/query/query-builder.factory.d.ts

@@ -44,11 +44,17 @@ export declare class QueryBuilder<DocumentType extends DocumentData> extends Sim
     private readonly documentReferenceFactory;
     private readonly queryBuilderFactory;
     private readonly documentIdentityService;
+    private forceFetchFromServer;
     getSortOrder(): FieldSort<DocumentType>[];
     /**
      * @inheritDoc
      */
     snapshot(): Promise<Array<DocumentReference<DocumentType>>>;
+    /**
+     * Forces the query to return data from the server even if there is a query that already returned the requested
+     * result.
+     */
+    setForceFetchFromServer(): this;
     /**
      * @inheritDoc
      */

package/dist/typescript-client/src/query/query-subscription.manager.d.ts

@@ -12,9 +12,24 @@ export declare class QuerySubscriptionManager {
     private readonly documentStore;
     private readonly destructManager;
     private readonly documentIdentityService;
+    /**
+     * As long as there are mutations in flight we do not want to send queries because it causes race conditions,
+     * preventing parallel queries and mutations simplifies the mental model.
+     */
     readonly safeToSendQueriesToServer: BehaviorSubject<boolean>;
+    /**
+     * An observable used by the data manager, the query subscription manager (this class) identifies when a document no
+     * longer has queries that it is part of their result, such document is considered orphan. The data manager will mark
+     * as orphan.
+     */
     onOrphanDocuments: Subject<string[]>;
+    /** All the currently running queries with their full state. */
     private readonly ongoingQueries;
+    /**
+     * The number of queries that are currently in-flight (about to be sent to the server or sent but did not get a
+     * response yet). This is used by the data manager to prevent it from sending mutations while there are in-flight
+     * queries.
+     */
     private readonly inflightQueriesCount;
     /**
      * The two maps below maintain the relation between document ids we know about locally to clientRequestIds (queries).
@@ -22,11 +37,31 @@ export declare class QuerySubscriptionManager {
      */
     private readonly clientRequestIdToLocalDocuments;
     private readonly localDocumentToClientRequestIds;
+    /**
+     * A data structure for mapping queries to allow reverse queries search (given a document, find all the matching
+     * queries)
+     */
     private readonly queryMappingManager;
     constructor(rpcManager: RpcManager, clientIdService: ClientIdService, documentStore: DocumentStore, destructManager: DestructManager, documentIdentityService: DocumentIdentityService);
+    /**
+     * Returns true if the client knows about this clientRequestId. It may happen that it will return false in the case
+     * that the client unsubscribed from a query but the server sent a mutation update for this clientRequestId.
+     */
     hasOngoingQuery(clientRequestId: ClientRequestId): boolean;
+    /**
+     * Returns the query associated with the given clientRequestId. Throws error if the clientRequestId is not known.
+     */
     getQuery(clientRequestId: ClientRequestId): Query;
-    setGotResponseFromServer(clientRequestId: ClientRequestId): void;
+    /**
+     * A query receives updates from two different sources:
+     * 1 - An initial snapshot from the server or from a parent query
+     * 2 - Incremental updates from the server (or from a parent query before the query is registered)
+     *
+     * If an incremental update is received before the snapshot was received, we cannot process it for this query.
+     * This boolean indicates whether the initial snapshot was received.
+     */
+    setGotInitialResult(clientRequestId: ClientRequestId): void;
+    /** Given a document, returns all the queries that should be notified with the new document properties. */
     findQueriesForDocument(doc: SquidDocument, squidDocId: SquidDocId): Array<QuerySubscriptionId>;
     /**
      * Given the new document's properties, finds all the queries that should be notified with the new properties and
@@ -35,12 +70,33 @@ export declare class QuerySubscriptionManager {
      * will need to be notified due to the change of properties).
      */
     setClientRequestIdsForLocalDoc(squidDocId: SquidDocId, properties: SquidDocument | undefined): Array<ClientRequestId>;
+    /**
+     * Due to an error when syncing a document, all the queries that are subscribed to this document should be notified
+     * and error out.
+     */
     errorOutAllQueries(squidDocId: SquidDocId, err: any): void;
+    /** Notifies to all the given queries (identified by their clientRequestId) with the updated query result. */
     notifyAllSubscriptions(clientRequestIds: ClientRequestId[]): void;
-    processQuery(query: Query, rootAlias: Alias, joins: Record<string, Query>, joinConditions: Record<Alias, JoinCondition>, subscribe: boolean): Observable<Array<Record<Alias, SquidDocument | undefined>>>;
+    /**
+     * Given an ongoing query, search for candidate ongoing queries that can serve as a parent.
+     * If there is a parent query, the result of that query can be used for serving the current query.
+     * We will still register the current query on the server, but we do not need to run the query, apply security rules,
+     * etc.
+     */
+    private findValidParentQuery;
+    processQuery(query: Query, rootAlias: Alias, joins: Record<string, Query>, joinConditions: Record<Alias, JoinCondition>, subscribe: boolean, forceFetchFromServer: boolean): Observable<Array<Record<Alias, SquidDocument | undefined>>>;
+    /**
+     * Returns whether the given document ID has a query that has this document ID as a result.
+     * A document without a query is considered "un-tracked".
+     */
     hasOngoingQueryForDocId(squidDocId: string): boolean;
+    /**
+     * Removes a query from the mapping and updates the orphan documents as needed.
+     */
     private removeClientRequestIdMapping;
+    /** Will resolve once all the in-flight queries are done. */
     waitForAllQueriesToFinish(): Promise<void>;
+    /** Register logic for cleaning up the query when it is unsubscribed. */
     private registerQueryFinalizer;
     /** Creates a graph of ongoing queries and returns the root of the graph. */
     private createOngoingQueryGraph;
@@ -49,16 +105,31 @@ export declare class QuerySubscriptionManager {
     private join;
     private getOngoingQueriesBfs;
     private updateOngoingQueryWithNewDataFromSupportingQuery;
-    private allOngoingQueriesGotServerResult;
+    private allOngoingQueriesGotInitialResult;
     private completeAllSupportedQueries;
     private predestruct;
     unsubscribe(): void;
     hasSubscription(clientRequestId: ClientRequestId): boolean;
     /** Sends the query request to the server and makes sure to unsubscribe once the subject completes. */
-    private sendQueryToServer;
+    private sendQueryToServerOrUseParentQuery;
     /**
-     * naive way to refresh queries/subscriptions when we have a new client id
+     * Uses the parent query as the source of data for the given ongoing query until the ongoing query is registered on
+     * the server. It prevents the parent query from being unsubscribed until the query is registered on the server and
+     * the first snapshot is received from the parent query.
+     * 1 - Prevents the parent query from being unsubscribed
+     * 2 - Connects the results of the parent query to the result of the current ongoing query
+     * 3 - Registers the query on the server
      */
+    private useParentOngoingQuery;
+    /**
+     * Sends the /query request to the server. It:
+     * 1 - Waits for when it is safe to send a query to the server (no in-flight mutations)
+     * 2 - Increments the number of inflightQueriesCount to prevent parallel mutations
+     * 3 - Handles errors
+     * 4 - Marks the query as registered
+     */
+    private sendQueryToServer;
+    /** naive way to refresh queries/subscriptions when we have a new client id */
     private refreshOngoingQueries;
     private migrateDocIds;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/client",
-  "version": "1.0.71",
+  "version": "1.0.73",
   "description": "A typescript implementation of the Squid client",
   "main": "dist/index.js",
   "types": "dist/typescript-client/src/index.d.ts",

package/dist/common/src/auth.types.d.ts

@@ -1 +0,0 @@
-export {};