lemon-core 4.3.0 → 5.0.1

package/dist/cores/elastic/os2-service.d.ts

@@ -0,0 +1,372 @@
+import { Incrementable, SearchBody } from 'lemon-model';
+import type { Client, ClientOptions } from '@opensearch-project/opensearch';
+import $hangul from './hangul-service';
+export { $hangul };
+export type SearchType = 'query_then_fetch' | 'dfs_query_then_fetch';
+export interface SearchResponse<T = any> {
+    total: number;
+    list: Array<T>;
+    last: Array<T>;
+    aggregations: T;
+}
+/**
+ * options for construction.
+ * - v5: the doc-type and version options are removed (typeless OpenSearch only).
+ */
+export interface OS2BaseOption {
+    /**
+     * endpoint url of OpenSearch
+     */
+    endpoint: string;
+    /**
+     * index-name
+     */
+    indexName: string;
+    /**
+     * id-name (optional if time-seriese)
+     */
+    idName?: string;
+    /**
+     * is TIMESERIES data?
+     */
+    timeSeries?: boolean;
+    /**
+     * fields to provide autocomplete(Search-as-You-Type) feature
+     */
+    autocompleteFields?: string[] | null;
+}
+/**
+ * common type of item
+ */
+export interface OS2Item {
+    _id?: string;
+    _version?: number;
+    _score?: number;
+    /**
+     * only has simple string or number (and in arrays)
+     */
+    [key: string]: string | string[] | number | number[] | undefined;
+}
+/**
+ * options for retrying searchAll
+ */
+export interface RetryOptions {
+    /** do retry? (default true) */
+    do?: boolean;
+    /** retry after t msec (default 5000ms) */
+    t?: number;
+    /** maximum Retries (default 3 times) */
+    maxRetries?: number;
+}
+/**
+ * parameters for searchAll
+ */
+interface ElasticSearchAllParams {
+    /** search-type */
+    searchType?: SearchType;
+    /** limit (default -1) */
+    limit?: number;
+    /** options for retrying (default true)*/
+    retryOptions?: RetryOptions;
+}
+/** ****************************************************************************************************************
+ *  OS2 Client Service
+ ** ****************************************************************************************************************/
+/**
+ * abstarct class: `OS2ClientService`
+ * - holds the options and the OpenSearch client.
+ * - the client is created on the first `client` access (not in the constructor).
+ */
+export declare abstract class OS2ClientService<T extends OS2Item = any> {
+    protected _options: OS2BaseOption;
+    /** the client, created on first access of `client` */
+    protected _client?: Client;
+    /**
+     * default constuctor w/ options (no client is created here).
+     * @param options { endpoint, indexName } is required.
+     */
+    constructor(options: OS2BaseOption);
+    /**
+     * build the client for `options.endpoint` (override to add `auth`).
+     * @see https://opensearch.org/docs/latest/clients/javascript/index/
+     */
+    protected createClient(): Client;
+    /**
+     * build a client for `options.endpoint` with extra client options (e.g. `auth`); loads the package on first use.
+     */
+    protected newClient(extra?: Partial<ClientOptions>): Client;
+    /**
+     * get the client instance (created once, on first access).
+     */
+    get client(): Client;
+    /**
+     * get the current options.
+     */
+    get options(): OS2BaseOption;
+    /**
+     * say hello
+     */
+    abstract hello(): string;
+    /**
+     * save an item
+     * @param id - item id
+     * @param item - item to save
+     */
+    abstract saveItem(id: string, item: T): Promise<T>;
+    /**
+     * push item for time-series data
+     * @param item - item to push
+     */
+    abstract pushItem(item: T): Promise<T>;
+    /**
+     * read item with projections
+     * @param id - item id
+     * @param views - projections
+     */
+    abstract readItem(id: string, views?: string[] | object): Promise<T>;
+    /**
+     * delete an item by id
+     * @param id - item id
+     */
+    abstract deleteItem(id: string): Promise<T>;
+    /**
+     * update an item
+     * @param id - item id
+     * @param item - item to update
+     * @param increments - fields to increment
+     */
+    abstract updateItem(id: string, item: T | null, increments?: any, options?: {
+        maxRetries?: number;
+    }): Promise<T>;
+    /**
+     * search raw results using a query body
+     * @param body - search query
+     * @param searchType - type of search
+     */
+    abstract searchRaw<T extends object = any>(body: any, searchType?: string): Promise<T>;
+    /**
+     * search and return formatted response
+     * @param body - search query
+     * @param searchType - type of search
+     */
+    abstract search(body: any, searchType?: string): Promise<any>;
+}
+/** ****************************************************************************************************************
+ *  OS2CoreService
+ ** ****************************************************************************************************************/
+/**
+ * class: `OS2CoreService`
+ * - extends `OS2ClientService`: document CRUD, search and index management via the client.
+ * - the parent of `OS2Service`.
+ */
+export declare class OS2CoreService<T extends OS2Item = any> extends OS2ClientService {
+    static readonly DECOMPOSED_FIELD = "_decomposed";
+    static readonly QWERTY_FIELD = "_qwerty";
+    /**
+     * default constuctor w/ options.
+     * @param options { endpoint, indexName } is required.
+     */
+    constructor(options: OS2BaseOption);
+    /**
+     * say hello of identity.
+     */
+    hello: () => string;
+    /**
+     * list of index
+     */
+    listIndices(): Promise<{
+        list: {
+            pri: number;
+            rep: number;
+            docsCount: number;
+            docsDeleted: number;
+            health: string;
+            index: string;
+            status: string;
+            uuid: string;
+            priStoreSize: string;
+            storeSize: string;
+        }[];
+    }>;
+    /**
+     * get mapping of an index
+     * @param indexName - name of the index
+     */
+    getIndexMapping(): Promise<any>;
+    /**
+     * find the index by name
+     * @param indexName - name of the index
+     */
+    findIndex(indexName?: string): Promise<{
+        pri: number;
+        rep: number;
+        docsCount: number;
+        docsDeleted: number;
+        health: string;
+        index: string;
+        status: string;
+        uuid: string;
+        priStoreSize: string;
+        storeSize: string;
+    }>;
+    /**
+     * create index by name
+     * @param settings - creating settings
+     */
+    createIndex(settings?: any): Promise<{
+        status: any;
+        index: string;
+        acknowledged: any;
+    }>;
+    /**
+     * destroy search index
+     */
+    destroyIndex(): Promise<{
+        status: any;
+        index: string;
+        acknowledged: any;
+    }>;
+    /**
+     * refresh search index - refresh index to make all items searchable
+     */
+    refreshIndex(): Promise<any>;
+    /**
+     * flush search index - force store changes into search index immediately
+     */
+    flushIndex(): Promise<any>;
+    /**
+     * describe `settings` and `mappings` of index.
+     */
+    describe(): Promise<{
+        settings: any;
+        mappings: any;
+    }>;
+    /**
+     * save single item
+     *
+     * - typeless: no `type` param (v5).
+     *
+     * @param id - id
+     * @param item - item to save
+     */
+    saveItem(id: string, item: T): Promise<T>;
+    /**
+     * push item for time-series data.
+     *
+     * - typeless: no `type` param (v5).
+     *
+     * @param item - item to push
+     */
+    pushItem(item: T): Promise<T>;
+    /**
+     * read item with projections (typeless `GET /{index}/_doc/{id}`)
+     *
+     * @param id - item-id
+     * @param views - projections
+     */
+    readItem(id: string, views?: string[] | object): Promise<T>;
+    /**
+     * delete item with projections (typeless `DELETE /{index}/_doc/{id}`)
+     *
+     * @param id - item-id
+     */
+    deleteItem(id: string): Promise<T>;
+    /**
+     * update item (throw if not exist)
+     * `update table set a=1, b=b+2 where id='a1'`
+     * 0. no of `a1` -> 1,2 (created)
+     * 1. a,b := 10,20 -> 11,22
+     * 2. a,b := 10,null -> 11,2 (upsert)
+     * 3. a,b := null,20 -> 1,22
+     *
+     * @param id - item-id
+     * @param item - item to update
+     * @param increments - item to increase
+     * @param options - (optional) request option of client.
+     */
+    updateItem(id: string, item: T | null, increments?: Incrementable, options?: {
+        maxRetries?: number;
+    }): Promise<T>;
+    /**
+     * run search and get the raw response (`search_type` in the query string).
+     * @param body - Elasticsearch Query DSL that defines the search request (e.g., size, query, filters).
+     * @param searchType - type of search (e.g., 'query_then_fetch', 'dfs_query_then_fetch').
+     */
+    searchRaw<T extends object = any>(body: SearchBody, searchType?: SearchType): Promise<T>;
+    /**
+     * run search, and get the formatmted response.
+     * @param body - Elasticsearch Query DSL that defines the search request (e.g., size, query, filters).
+     * @param searchType - type of search (e.g., 'query_then_fetch', 'dfs_query_then_fetch').
+     *
+     */
+    search(body: SearchBody, searchType?: SearchType): Promise<SearchResponse>;
+    /**
+     * search all until limit (-1 means no-limit)
+     * @param body - Elasticsearch Query DSL that defines the search request (e.g., size, query, filters).
+     * @param params - parameters including search type, limit, and retry options.
+     */
+    searchAll<T>(body: SearchBody, params?: ElasticSearchAllParams): Promise<T[]>;
+    /**
+     * create async generator that yields items queried until last
+     *
+     * @param body - Elasticsearch Query DSL that defines the search request (e.g., size, query, filters).
+     * @param params - parameters including search type, limit, and retry options.
+     */
+    generateSearchResult(body: SearchBody, params?: ElasticSearchAllParams): AsyncGenerator<any[], void, unknown>;
+    /**
+     * prepare default setting
+     * - migrated from engine-v2.
+     * - v5: always the typeless mapping (`mappings.properties`); no doc-type or version, no `standard` filter.
+     *
+     * @param idName        id-name
+     * @param shards        number of shards (default 4)
+     * @param replicas      number of replicas (default 1)
+     * @param timeSeries    flag of TIMESERIES (default false)
+     */
+    static prepareSettings(params: {
+        idName: string;
+        timeSeries?: boolean;
+        shards?: number;
+        replicas?: number;
+    }): any;
+    /**
+     * generate autocomplete fields into the item body to be indexed
+     * @param body  item body to be saved into ES6 index
+     * @private
+     */
+    protected popullateAutocompleteFields<T = any>(body: T): T;
+}
+interface ErrorReasonDetail<T = any> {
+    status: number;
+    type: string;
+    reason?: string;
+    cause?: T;
+}
+interface ErrorReason {
+    status: number;
+    message: string;
+    reason: ErrorReasonDetail;
+}
+/**
+ * error samples
+ */
+export declare const $ERROR: {
+    asJson: (e: any) => any;
+    throwAsJson: (e: any) => never;
+    parseMeta: <T extends {
+        type?: string;
+        value?: any;
+        error?: string;
+        list?: any[];
+        [key: string]: any;
+    }>(meta: any) => T;
+    /**
+     * parse a client error into `{ status, message, reason }`.
+     * - `type` comes from `meta.body.error.type` (same in both clients); it falls back to `message` only
+     *   when the body has no error type (e.g. a meta-only sample of elastic 7.x).
+     * - output form is unchanged: `<TYPE upper, last token dropped, _ as space>` like `VERSION CONFLICT ENGINE`.
+     * - errors without `meta` (FGAC `http-fetch`, network) give `reason = null` and are rethrown by `handler`.
+     */
+    asError: (e: any) => ErrorReason;
+    handler: (name: string, cb?: (e: Error, E?: ErrorReason) => any) => (e: any) => any;
+};