UNPKG

kuzzle-sdk

Version:
201 lines (200 loc) 6.78 kB
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; }