lemon-core 4.2.7 → 5.0.0

package/dist/extended/cores/abstract-services.d.ts

@@ -0,0 +1,771 @@
+import { SearchType, OS2CoreService, OS2BaseOption, OS2QueryService } from '../../cores/';
+import { DynamoScanFilter, ApiHttpProxy } from '../../cores/';
+import { OS2Item } from '../../cores/';
+import type { Client } from '@opensearch-project/opensearch';
+import { OS2Synchronizer, CoreManager, CoreService, SearchResult, ManagerProxy, AbstractProxy, AbstractOS2Instance, OS2ConstructParams } from '../abstract-service';
+export { sourceToItem } from '../abstract-service';
+import { Incrementable, CoreModel, SearchBody, SearchQuery, NextContext, NextIdentity, SortTerm, SimpleSet, GeneralItem } from 'lemon-model';
+import { BulkItemsResult, IdentityToken, ListResult, PaginateParam } from './types';
+import { CrendentialForAWS } from '../../environ';
+import { ModelClass } from '../../cores/storage/model-fields';
+export type SearchParam<T> = T & {
+    [key: string]: string | number;
+};
+/**
+ * lookup table for common types.
+ */
+declare const $LUT: {
+    /**
+     * type: `CanDoAction`
+     */
+    CanDoAction: {
+        list: string;
+        read: string;
+        create: string;
+        update: string;
+        delete: string;
+    };
+};
+/**
+ * type: `CanDoActionType`
+ */
+export type CanDoActionType = keyof typeof $LUT.CanDoAction;
+/**
+ * Optional parameters for `canDo()`
+ */
+export interface CanDoOptions {
+    /** error scope to print */
+    errScope?: string;
+    /** flag to throw error if not allowed (default false) */
+    throwable?: boolean;
+    /** flag to use session (default true) */
+    useSession?: boolean;
+    /** current context to override */
+    context?: NextContext;
+}
+/**
+ * type: `ScanLastParams`
+ */
+export interface ScanLastParams<T = any> {
+    /** last cursor during scan */
+    last?: T;
+    /** (optional) limit to 1x scan */
+    limit?: number;
+    /** filter to scan */
+    filter?: DynamoScanFilter;
+}
+/**
+ * type: `ScanLastResult`
+ */
+export interface ScanLastResult<T = any> extends ListResult<T> {
+    /** count of scan */
+    count?: number;
+    /** (optinoal) last of scan if there are more */
+    last?: any;
+}
+/**
+ * type: `doSyncScanLastResult`
+ *
+ * @param .list can be BulkResponseItem[]
+ */
+export interface DoSyncScanLastResult<T = any> extends ListResult<T> {
+    /** count of scan */
+    count?: number;
+    /** (optinoal) last of scan if there are more */
+    last?: any;
+    /** errors of saveBulk */
+    errors?: boolean[];
+    /** statusCodes of saveBulk */
+    statusCodes?: number[];
+}
+/**
+ * class: `MyCoreService`
+ * - CoreService의 공통 부분을 채워넣는다.
+ */
+export declare abstract class MyCoreService<Model extends CoreModel<ModelType>, ModelType extends string, Proxy extends MyCoreProxy<ModelType, any>> extends CoreService<Model, ModelType> {
+    constructor(tableName?: string, ns?: string);
+    /**
+     * make proxy instance w/ this service.
+     */
+    abstract createProxy(context: NextContext): Proxy;
+    /**
+     * make proxy, and use callback to handle.
+     * - it will save automatically on success.
+     * - v5: on exception it saves only when `options.saveOnError` is true (default false, B5 § 6.7).
+     */
+    guardProxy: <T>(context: NextContext, callback: (proxy: Proxy) => Promise<T>, options?: {
+        saveOnError?: boolean;
+    }) => Promise<T>;
+    /**
+     * run search (via `$OS2`)
+     * - override this to hide `$OS2`
+     */
+    doSearch<T>(body: SearchBody): Promise<SearchResult<T>>;
+    /**
+     * check if using useSession from environ.
+     */
+    isUseSession(): boolean;
+    /**
+     * check if search-engine is supportable
+     * @returns
+     */
+    hasSearchEngine(): boolean;
+}
+/**
+ * class: `CoreManager`
+ * - shared core manager for all model
+ *
+ * @abstract
+ */
+export declare abstract class MyCoreManager<Model extends CoreModel<ModelType>, ModelType extends string, Service extends MyCoreService<Model, ModelType, any>> extends CoreManager<Model, ModelType, Service> {
+    readonly options?: {
+        /** enable to sync with the search engine (v5 default false — B5 § 6.7) */
+        enableSync?: boolean;
+        /** unique field */
+        uniqueField?: string;
+        /** initial next-id number of auto-seq (default 1000000) */
+        initialNo?: number;
+    };
+    /**
+     * namespace for log(print)
+     */
+    protected readonly logNS: string;
+    /**
+     * constructor
+     * @protected
+     */
+    protected constructor(type: ModelType, parent: Service, fields: string[] | ModelClass, options?: {
+        /** enable to sync with the search engine (v5 default false — B5 § 6.7) */
+        enableSync?: boolean;
+        /** unique field */
+        uniqueField?: string;
+        /** initial next-id number of auto-seq (default 1000000) */
+        initialNo?: number;
+    });
+    /**
+     * get the next sequenced no from `initialNo` (default 1000000)
+     *
+     * @param step (optional) next-step (>= 0)
+     * @returns next seq-no
+     */
+    nextId(step?: number): Promise<number>;
+    /**
+     * build default model for creation.
+     */
+    buildDefault(id: string): Model;
+    /**
+     * validate the request's model before saving.
+     * - `$org`에 따라서, 신규 생성인지 업데이트인지 구분 가능함.
+     *
+     * @param model request's model
+     * @param $org (optional) the origin model (valid ONLY if 업데이트)
+     * @returns validatated model.
+     */
+    validateModel(model: Model, $org?: Model): Promise<Model>;
+    /**
+     * find lookup-model (improved @2022)
+     * - lookup to `auto-id` by key.
+     * - if not exits, make the new id (auto-seq) and store the key.
+     * - type should be like `#<type>`.
+     *
+     * NOTE! must to support race condition.
+     *
+     * @param key any string
+     */
+    findLookup$(key: string | number, params?: {
+        /** rate to reset lock (default 0.9) */
+        resetRate?: number;
+        /** flag to use sha256 for hash (default true) */
+        useSha256?: boolean;
+        /** use meta to save lookup info (default false) */
+        isUseMeta?: boolean;
+        /** throw if lookup is not found (default false) - useful to check if exists of key */
+        throwable?: boolean;
+    }): Promise<Model>;
+    /**
+     * build search query from filters
+     */
+    buildQuery<T extends Model>(param: PaginateParam, model?: SearchParam<T>, options?: {
+        errScope?: string;
+        hidden?: boolean | number;
+        aggregation?: string;
+        aggrLimit?: number;
+    }): SearchBody;
+    /**
+     * Query 기준 추가하기.
+     */
+    addQueryTerm(body: SearchBody, term: 'filter' | 'must' | 'must_not', query: SearchQuery | SearchQuery[]): SearchBody;
+    /**
+     * sort 기준 추가하기.
+     */
+    addSortTerm(body: SearchBody, param?: PaginateParam): SearchBody;
+    /**
+     * build filter for scan.
+     * @returns DynamoScanFilter
+     */
+    buildScanFilter(params?: SearchParam<Model>): DynamoScanFilter;
+    /**
+     * execute scan with filter.
+     *
+     * @param $page
+     * @param filter
+     * @returns
+     */
+    doScan<R = {
+        key: string;
+        count: number;
+    }>($page: PaginateParam, filter?: DynamoScanFilter): Promise<ListResult<Model, R>>;
+    /**
+     * execute scan-last with filter.
+     *
+     * @param $param ScanLastParams
+     * @returns
+     */
+    doScanLast($param: ScanLastParams): Promise<ScanLastResult<Model>>;
+    /**
+     * basic ElasticSearch Query.
+     * you can override this method for customization.
+     *
+     * @param limit pagination limit (default 10)
+     * @param page page number (starts from 0)
+     * @param filters model filters
+     * @param param (optional) addtion params
+     */
+    list<R = {
+        key: string;
+        count: number;
+    }>($page: PaginateParam, $param?: SearchParam<Model>, options?: {
+        hidden?: boolean | number;
+        aggregation?: string;
+    }): Promise<ListResult<Model, R>>;
+    /**
+     * list of projection fields
+     * - ONLY fields defined in `goods-model`
+     * - 모델별 추가 필드목록만 추림
+     */
+    listProjections(params?: {
+        includes?: string[];
+        excludes?: string[];
+        sorted?: boolean;
+    }): string[];
+    /**
+     * fetch all list of goods for filtering.
+     *
+     * @override if required.
+     */
+    buildSearchAll(params?: {
+        size?: number;
+    }, sort?: SortTerm): SearchBody;
+    /**
+     * sync by scan with last record.
+     *
+     * **[좋은코드]**
+     * 1. 보기 좋아야함; 변수이름, 로직도 잘보이고, 함수의 목적
+     * 2. 테스트 가능한 코드 (또는 테스트가된 코드)
+     *  - Unit Test: 테스트 가능한 최소단위 (함수.. 블럭)
+     *  - Integrated Test: Group of Units (ex: my_sequence)
+     *
+     * @param $param
+     * @param options
+     * @returns
+     */
+    doSyncScanLast($param: ScanLastParams, options?: {
+        /** chunk-size of bulk (default: 10) */
+        size?: number;
+    }): Promise<DoSyncScanLastResult>;
+}
+/**
+ * class: `MyCoreProxy`
+ * - common parent of proxy.
+ */
+export declare class MyCoreProxy<U extends string, MyService extends MyCoreService<CoreModel<any>, any, any>> extends AbstractProxy<any, MyService> {
+    readonly managerProxies: {
+        [propKey: string]: MyManagerProxy<any, any, MyService>;
+    };
+    constructor(context: NextContext, service: MyService, cacheScope?: string);
+    /**
+     * check if in mocks mode.
+     * - override this to set mocks.
+     *
+     * @returns boolean
+     */
+    isMocks(): boolean;
+    /**
+     * register this.
+     */
+    register(mgr: MyManagerProxy<any, any, MyService>): number;
+    /**
+     * add into proxy lookup.
+     */
+    protected addManagerProxy(modelType: U, proxy: MyManagerProxy<any, any, MyService>): void;
+    /**
+     * get from lookup table.
+     */
+    getManagerProxy<Model, ModelManager extends MyCoreManager<Model, any, MyService>>(modelType: U): MyManagerProxy<Model, ModelManager, MyService>;
+    /**
+     * @override fetchIdentityAccess
+     * @deprecated not supported.
+     */
+    protected fetchIdentityAccess(identityId: string, domain?: string): Promise<any>;
+    /**
+     * get the `identity-token` (as session) from current req-context.
+     * - 1차 호출(front에서) 에서는 이 세션이 꼭 필요함.
+     * - 2차 호출(protocol이용) 에서는 선택사항으로, 조절가능해야함! (#TODO - 이걸 어떻게 구불할것인가?)
+     * - 로컬) 로컬 개발에서는 시뮬레이션 방법은 #TODO
+     *
+     * @param options.throwable flag to throw (default true)
+     */
+    getCurrentSession(options?: {
+        /** (default true) */
+        throwable?: boolean;
+        /** (default true) */
+        normalize?: boolean;
+        /** (default true) */
+        useSession?: string | boolean;
+        /** (optional) env.LOCAL_ACCOUNT */
+        LOCAL_ACCOUNT?: string;
+        /** (optional) env.USE_SESSION */
+        USE_SESSION?: string;
+        /** (optional) next context to override */
+        context?: NextContext;
+    }): IdentityToken;
+    /**
+     * find the current identity-id from context.
+     * - or, use env[LOCAL_ACCOUNT]
+     */
+    asCurrentIdentityId: (context?: NextContext) => string | null;
+    /**
+     * assert context condition.
+     */
+    assertContext(params?: {
+        /** call in local */
+        isLocal?: boolean;
+        /** authed by cognito identity-provider */
+        isAuthed?: boolean;
+        /** signed call with access-key */
+        isSigned?: boolean;
+        /** check if session has role */
+        hasRole?: string;
+    }, 
+    /** (optional) */
+    options?: {
+        /** (optional) throwable to throw error if error */
+        throwable?: boolean;
+        /** (optional) errScope to override in error */
+        errScope?: string;
+        /** (optional) next context to override */
+        context?: NextContext;
+    }): boolean;
+    /**
+     * check if current context has `admin` access
+     * 1. run in local mode (`$U.isLocalMode()`, v5 — no longer `domain='localhost'`)
+     * 2. access via signed access-key
+     * 3. authorized cognito and has `admin` role in identity-token.
+     *
+     * @param role (default) admin
+     * @param options optionals
+     * @returns boolean
+     */
+    hasAdminRole(role?: string, options?: {
+        errScope?: string;
+        context?: NextContext;
+    }): boolean;
+    /**
+     * prepare `next-context` w/ the customized { domain, userAgent }
+     *
+     * @param identityId the target identity-id
+     * @param options additional options.
+     */
+    asNextContext<T extends NextIdentity>(identityId?: string, options?: {
+        /** (optional) domain to override */
+        domain?: string;
+        /** (optional) userAgent to override */
+        userAgent?: string;
+        /** (optional) identity(object) to override */
+        identity?: T;
+        /** (optional) session(object) to override */
+        session?: IdentityToken;
+    }): NextContext<T>;
+    /**
+     * from `identity-token`, make base of model { sid, uid }
+     *
+     * @param proxy the current proxy.
+     * @returns base model
+     */
+    makeModelBase<M extends CoreModel<U>>(model: M, options?: {
+        /** use this parent to prepare base-model. (hiher than session) */
+        parent?: CoreModel;
+        /** flag to use session (default as confUseSession) */
+        useSession?: boolean;
+        /** flag to throw error (default true) */
+        throwable?: boolean;
+    }): Promise<M>;
+    /**
+     * Check if the user can perform a specific action on a model.
+     * - override this method to implement custom logic.
+     *
+     * @param action The action to check.
+     * @param model The model to check against. (.type is used to find the manager-proxy)
+     * @param options Optional parameters for the check.
+     * @returns True if the action is allowed, false otherwise.
+     */
+    canDo<M extends CoreModel<U>>(action: CanDoActionType, model?: M, options?: CanDoOptions): boolean;
+}
+/**
+ * class: `MyProxy`
+ * - common parent of manager-proxy.
+ */
+export declare class MyManagerProxy<MyModel extends CoreModel<ModelType>, MyManager extends MyCoreManager<MyModel, ModelType, MyService>, MyService extends MyCoreService<MyModel, ModelType, any>, ModelType extends string = string> extends ManagerProxy<MyModel, MyManager, ModelType> {
+    readonly proxy: MyCoreProxy<ModelType, MyService>;
+    constructor(proxy: MyCoreProxy<ModelType, MyService>, mgr: MyManager);
+    /**
+     * @override the default `normal()` to support _name.
+     */
+    normal: (N: MyModel) => MyModel;
+    /**
+     * pack the query parameter for list
+     * - `param` has the string values only including '', '!'
+     * - `model` has the valid data type. (number | string | ... )
+     *
+     * ```ts
+     * let model = bodyToModel(param)
+     * ```
+     *
+     * @param param the original query parameter.
+     * @param model the transformed model from `param`.
+     * @param options (optional)
+     * @returns
+     */
+    packSearchParam(param: SimpleSet, model?: MyModel, options?: {
+        /** flag to use identity-token (default false) */
+        useSession?: boolean;
+        /** flag to throw error (default true) */
+        throwable?: boolean;
+        /** default limit (default 10) */
+        limit?: number;
+        /** (optional) error scope to use */
+        errScope?: string;
+    }): {
+        $page: PaginateParam;
+        $param: SearchParam<MyModel>;
+    };
+    /**
+     * override this to validate request'body.
+     * @param model model from request.
+     * @param modelId (optional) modelId if to update the target model.
+     * @return validated model to save.
+     */
+    validateModel<T extends MyModel>(model: T, modelId?: string): Promise<T>;
+    /**
+     * callback before saving model.
+     * - could change field before saving.
+     *
+     * @param model the last model to save.
+     * @param $org (optional) original model (null if creating)
+     */
+    onBeforeSave<T extends MyModel>(model: T, $org?: T): Promise<T>;
+    /**
+     * callback after saving model.
+     * - could trigger the next step if created.
+     *
+     * @param model the saved model (null if deleted)
+     * @param $org (optional) original model (null if new created)
+     */
+    onAfterSave<T extends MyModel>(model: T, $org?: T): Promise<T>;
+    /**
+     * generate the next id
+     */
+    nextId(step?: number): Promise<string>;
+    /**
+     * create new model
+     * - use `.id` or `nextId()` for model-id
+     * - validate model in seperate way before using this.
+     *
+     * @param model creation model
+     * @param validate (optional) flag to validate (default is true)
+     */
+    makeModel<T extends MyModel>(model: T, validate?: boolean): Promise<T>;
+    /**
+     * Check if the current user can perform the specified action on the given model.
+     * - override this method to implement custom logic.
+     *
+     * @param action The action to check.
+     * @param model The model to check against.
+     * @param options Additional options for the check.
+     * @returns True if the action is allowed, false otherwise.
+     */
+    canDo<T extends MyModel>(action: CanDoActionType, model?: T, options?: CanDoOptions): boolean;
+    /**
+     * read multiple nodes.
+     * @param ids list of object-ids
+     * @param throwable (optional) flag to throw error if not found
+     */
+    mget<T extends MyModel = MyModel>(ids: string[], options?: {
+        throwable?: boolean;
+    } | boolean): Promise<T[]>;
+    /**
+     * update multiple nodes.
+     * @param updates list of models (should include id)
+     */
+    mset<T extends MyModel>(updates: Array<T>): Promise<T[]>;
+}
+/**
+ * parameters for Elasticsearch operations.
+ *
+ * @template T type of the body content.
+ */
+interface ElasticParams<T extends object = any> {
+    /**
+     * index name.
+     */
+    index: string;
+    /**
+     * document ID.
+     */
+    id?: string;
+    /**
+     * body content.
+     */
+    body: T;
+}
+/**
+ * parameters for Elasticsearch search operations.
+ *
+ * @template T type of the body content.
+ */
+interface ElasticSearchParams<T extends object = any> {
+    /**
+     * index name.
+     */
+    index: string;
+    /**
+     * search body content.
+     */
+    body: T;
+    /**
+     * search type
+     * (e.g., 'query_then_fetch', 'dfs_query_then_fetch').
+     */
+    search_type?: SearchType;
+}
+/**
+ * class: `OS2Service`
+ * - Master 권한 전용 Elasticsearch 관리 서비스
+ * - service for OS2: data path via FGAC (`$fgac`), index management via the master client.
+ */
+export declare class OS2Service<T extends OS2Item = any> extends OS2CoreService<any> {
+    readonly $fgac: OS2FGACManager;
+    /**
+     * constructor (no client here; the master client is created on first `client` access)
+     */
+    constructor(options: OS2BaseOption, fgac: OS2FGACManager);
+    /**
+     * build the master client: `auth` is read from config now (after engine init), and set only when both exist.
+     */
+    protected createClient(): Client;
+    /**
+     * delete index by name
+     */
+    deleteIndex(indexName: string): Promise<any>;
+    /**
+     * save single item
+     *
+     * @param id - id
+     * @param item - item to save
+     * @param type - document type (default: doc-type given at construction time)
+     */
+    saveItem(id: string, item: T): Promise<T>;
+    /**
+     * bulk save multiple items using elasticsearch client
+     *
+     * @param items - array of items to save
+     */
+    bulkItems(items: T[], options?: {
+        idName?: string;
+    }): Promise<BulkItemsResult>;
+    /**
+     * push item for time-series data (via FGAC; the result is the response body itself).
+     *
+     * @param item - item to push
+     */
+    pushItem(item: T): Promise<T>;
+    /**
+     * read item with projections
+     *
+     * @param id - item-id
+     * @param views - projections
+     */
+    readItem(id: string, views?: string[] | object): Promise<T>;
+    /**
+     * delete item with projections
+     *
+     * @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.
+     * @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>;
+}
+/**
+ * type: `OS2FGACManager`
+ * - FGAC(Fine Grained Access Controll) Proxy for OS2
+ */
+export declare class OS2FGACManager {
+    private _fgacProxy;
+    readonly options: OS2BaseOption;
+    constructor(options: OS2BaseOption);
+    hello: () => string;
+    get proxy(): ApiHttpProxy;
+    /** FGAC 기반 검색 */
+    doFgacSearch<R = any>(params: ElasticSearchParams): Promise<R>;
+    /** FGAC 기반 읽기: client.get() 대응 */
+    doFgacRead<R = any>(params: ElasticParams): Promise<R>;
+    /** FGAC 기반 저장: client.index() 대응 */
+    doFgacSave<R = any>(params: ElasticParams): Promise<R>;
+    /** FGAC 기반 저장: client.index() 대응 */
+    doFgacBulk(bulk: ElasticParams<any[]>): Promise<any[]>;
+    /** FGAC 기반 업데이트: client.update() 대응 */
+    doFgacUpdate<R = any>(params: ElasticParams): Promise<R>;
+    /** FGAC 기반 삭제: client.delete() 대응 */
+    doFgacDelete<R = any>(params: ElasticParams): Promise<R>;
+    /** FGAC 기반 Create (Strict - 존재하면 실패): client.create() 대응 */
+    doFgacCreate<R = any>(params: ElasticParams): Promise<R>;
+    /** FGAC 기반 인덱스 삭제: client.indices.delete() 대응 */
+    doFgacDeleteIndex<R = any>(index: string): Promise<R>;
+    /**
+     * FGAC 기반 인덱스 설명: client.indices.describe() 대응
+     */
+    doFgacDescribe<R = any>(index: string): Promise<{
+        settings: R;
+        mappings: R;
+    }>;
+    /**
+     * FGAC 기반 인덱스 Settings 변경: client.indices.putSettings() 대응
+     */
+    doFgacPutSettings<R = any>(index: string, settings: Record<string, any>): Promise<R>;
+    /**
+     * FGAC 기반 인덱스 Settings 조회: client.indices.getSettings() 대응
+     */
+    doFgacGetSettings<R = any>(index: string): Promise<R>;
+    /**
+     * FGAC 기반 인덱스 Mapping 조회: client.indices.getMapping() 대응
+     */
+    doFgacGetMapping<R = any>(index: string): Promise<R>;
+    /**
+     * FGAC 기반 인덱스 Mapping 변경: client.indices.putMapping() 대응
+     */
+    doFgacPutMapping<R = any>(index: string, mapping: Record<string, any>): Promise<R>;
+    /**
+     * FGAC 기반 인덱스 닫기: client.indices.close() 대응
+     */
+    doFgacCloseIndex<R = any>(index: string): Promise<R>;
+    /**
+     * FGAC 기반 인덱스 열기: client.indices.open() 대응
+     */
+    doFgacOpenIndex<R = any>(index: string): Promise<R>;
+}
+/** extended option for `OS2Instance` */
+export interface OS2Option extends OS2BaseOption {
+    /** (optional) role-name in FGAC */
+    roleName?: string;
+    /** (optional) user-name in FGAC */
+    userName?: string;
+}
+/**
+ * OS2 인스턴스
+ * - describeIndex(), destroyIndex(), search() with elastic initialized by master-key
+ * - one service set (fgac, elastic, query, synchronizer) only when `endpoint && indexName`.
+ */
+export declare class OS2Instance extends AbstractOS2Instance {
+    readonly elastic?: OS2Service;
+    readonly query?: OS2QueryService<any>;
+    readonly synchronizer?: OS2Synchronizer;
+    readonly fgac?: OS2FGACManager;
+    /**
+     * build one service set when `endpoint && indexName` (no client: it is created on first use).
+     */
+    constructor({ endpoint, indexName, idName, tableName, autocompleteFields, roleName, userName, }: OS2ConstructParams & {
+        /** (optional) id-name (default `$id`, `null` = unset) */
+        idName?: string;
+        /** (optional) role-name in FGAC */
+        roleName?: string;
+        /** (optional) user-name in FGAC */
+        userName?: string;
+    });
+    hello: () => string;
+    get options(): OS2Option;
+    get $X2(): typeof $X2;
+    /**
+     * search
+     */
+    search<T>(body: SearchBody, params?: {
+        indexName?: string;
+        searchType?: 'query_then_fetch' | 'dfs_query_then_fetch';
+    }): Promise<SearchResult<T>>;
+    /** synchronize dynamo contents to os2  */
+    synchronizeContents(options?: {
+        stopOnError?: boolean;
+    } & PaginateParam): Promise<{
+        index: string;
+        total: number;
+        failed: (CoreModel<any> & GeneralItem)[];
+        list?: (CoreModel<any> & GeneralItem)[];
+    }>;
+    /** bulk items with auto-complete options */
+    bulkItems(items: any[], options?: {
+        idName?: string;
+    }): Promise<BulkItemsResult>;
+}
+/**
+ * internal tools
+ */
+declare const $X2: {
+    /** describe endpoint-url into component */
+    describeEndpointUrl: (url: string, options?: {
+        throwable?: boolean;
+        errScope?: string;
+    }) => {
+        protocol: string;
+        host: string;
+        port: number;
+        region: string;
+        isTunnel: boolean;
+        isProxy: boolean;
+    };
+    /** load local credentials (for dev) */
+    loadCredentials: (profile?: string) => Promise<CrendentialForAWS>;
+};
+/**
+ * factory of `OS2Instance`
+ * - reads `OS2_ENDPOINT`, `OS2_INDEX`, `MY_DYNAMO_TABLE`, `OS2_AUTOCOMPLETE_FIELDS` (no version, no doc-type).
+ */
+export declare const _OS2: (options?: OS2Option) => OS2Instance;
+/**
+ * the default `OS2Instance`, built lazily by `_OS2()` on first access (S-25).
+ * - nothing is built at import: no client, no dynamo-stream listener.
+ * - without `OS2_ENDPOINT` it is an `OS2Instance` with `options === null`.
+ */
+export declare const $OS2: OS2Instance;
+/**
+ * explicit alias of `$OS2` (the same object). The name is kept; the meaning is OS2.
+ */
+export declare const $ES6Routed: OS2Instance;