kuzzle-sdk
Version:
Official Javascript SDK for Kuzzle
201 lines (200 loc) • 6.78 kB
TypeScript
import { Kuzzle } from "../Kuzzle";
import { RealtimeDocument } from "./RealtimeDocument";
import { JSONObject, KDocument, KDocumentContentGeneric } from "../types";
import { RealtimeDocumentSearchResult } from "./searchResult/RealtimeDocument";
import { ArgsDocumentControllerGet, ArgsDocumentControllerMGet, ArgsDocumentControllerSearch } from "../controllers/Document";
export type ObserverOptions = {
/**
* Refresh delay in ms when the SDK is using the HTTP protocol.
*
* @default 5000
*/
pullingDelay: number;
};
/**
* The Observer class allows to manipulate realtime documents.
*
* A RealtimeDocument is like a normal document from Kuzzle except that it is
* connected to the realtime engine and its content will change with changes
* occuring on the database.
*
* They can be retrieved using methods with the same syntax as in the Document
* Controller:
*
* ```js
* const docs = await observer.get('montenegro', 'budva', 'foobar');
*
* const result = await observer.search('montenegro', 'budva', { query: { exists: 'beaches' } });
* ```
*
* Realtime documents are resources that should be disposed either with the
* stop() or the dispose() method otherwise subscriptions will never be
* terminated, documents will be keep into memory and you will end with a
* memory leak.
*
* ```js
* await observer.stop('nyc-open-data', 'yellow-taxi');
* ```
*
* A good frontend practice is to instantiate one observer for the actual page
* and/or component(s) displaying realtime documents and to dispose them when
* they are not displayed anymore.
*
* If the SDK is using the HTTP protocol, then documents are retrieved through the
* document.mGet method every specified interval (default is 5 sec). This interval
* can be modified with the `pullingDelay` option of the constructor.
*/
export declare class Observer {
/**
* Map used to keep track of the observed documents ids by collections.
*
* @internal
*/
private documentsByCollection;
/**
* Map containing the list of realtime documents managed by this observer.
*
* This map is used to update realtime documents content when notifications
* are received.
*
* @internal
*/
private documents;
/**
* @internal
*/
private sdk;
/**
* @internal
*/
private options;
/**
* @internal
*/
private pullingTimer;
/**
* Method to refresh documents.
* Either through the realtime notifications system or by pulling documents
* with the document.mGet method (HTTP protocol)
*/
readonly mode: "realtime" | "pulling";
/**
* Instantiate a new Observer
*
* @param sdk SDK instance
*/
constructor(sdk: Kuzzle, options?: ObserverOptions);
/**
* Stop observing documents and release associated ressources.
*
* Can be used either with:
* - a list of documents from a collection: stop observing those documents
* - an index and collection: stop observing all documents in the collection
*
* @param index Index name
* @param collection Collection name
* @param documents Array of documents
*
*/
stop(index?: string, collection?: string, documents?: Array<{
_id: string;
}>): Promise<void>;
private disposeDocuments;
private disposeCollection;
/**
* Unsubscribe from every collections and clear all the realtime documents.
*
* @internal
*/
private disposeAll;
/**
* Gets a realtime document
*
* @param index Index name
* @param collection Collection name
* @param id Document ID
* @param options Additional options
*
* @returns The realtime document
*/
get<TKDocumentContent extends KDocumentContentGeneric>(index: string, collection: string, id: string, options?: ArgsDocumentControllerGet): Promise<RealtimeDocument<TKDocumentContent>>;
/**
*
* Gets multiple realtime documents.
*
* @param index Index name
* @param collection Collection name
* @param ids Document IDs
* @param options Additional options
*
* @returns An object containing 2 arrays: "successes" and "errors"
*/
mGet<TKDocumentContent extends KDocumentContentGeneric>(index: string, collection: string, ids: string[], options?: ArgsDocumentControllerMGet): Promise<{
/**
* Array of successfully retrieved documents
*/
successes: RealtimeDocument<TKDocumentContent>[];
/**
* Array of the IDs of not found documents.
*/
errors: string[];
}>;
/**
* Searches for documents and returns a SearchResult containing realtime
* documents.
*
* @param index Index name
* @param collection Collection name
* @param searchBody Search query
* @param options Additional options
*
* @returns A SearchResult containing realtime documents
*/
search<TKDocumentContent extends KDocumentContentGeneric>(index: string, collection: string, searchBody?: JSONObject, options?: ArgsDocumentControllerSearch): Promise<RealtimeDocumentSearchResult<TKDocumentContent>>;
/**
* Retrieve a realtime document from a document
*
* @param index Index name
* @param collection Collection name
* @param document Document to observe
*
* @returns A realtime document
*/
observe<TKDocumentContent extends KDocumentContentGeneric>(index: string, collection: string, document: KDocument<TKDocumentContent>): Promise<RealtimeDocument<TKDocumentContent>>;
/**
* Adds a document and retrieve managed realtime document
*
* @internal
*
* Use observe() to retrieve a realtime document.
*/
addDocument<TKDocumentContent extends KDocumentContentGeneric>(index: string, collection: string, document: KDocument<TKDocumentContent>): RealtimeDocument<TKDocumentContent>;
/**
* Start subscription or pulling on the collection
*
* @internal
*/
watchCollection(index: string, collection: string): Promise<void>;
private restartPulling;
/**
* Use the document.mGet method to pull documents from observed collections
* and update internal realtime documents.
*
* This method never returns a rejected promise.
*/
private pullingHandler;
private clearPullingTimer;
/**
* Renew a collection subscription with filters according to the list of
* currently managed documents.
*
* @internal
*/
private resubscribe;
/**
* Handler method to process notifications and update realtime documents content.
*
* @internal
*/
private notificationHandler;
}