kuzzle-sdk/src/core/Observer.d.ts

Official Javascript SDK for Kuzzle

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;
}