@lemoncloud/ssocio-stacks-api 0.23.313

package/README.md

@@ -0,0 +1,4 @@
+# @lemoncloud/ssocio-stacks-api
+
+- 관리용 서비스 API
+

package/dist/cores/abstract-controllers.d.ts

@@ -0,0 +1,175 @@
+/**
+ * `abstract-controllers.ts`
+ * - pre-coded Model basic CRUD with backend-service and backend-proxy on GeneralWEBController.
+ *
+ * @author      Albert <albert@lemoncloud.io>
+ * @date        2022-05-02 initial version
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-06-21 optimized w/ `abstract-services`
+ * @date        2022-06-24 fixed some failures.
+ * @date        2022-06-28 supports `doGetList` w/ search-id.
+ * @date        2022-08-02 use `nextId()` w/ `manager.initialNo`.
+ * @date        2022-08-03 improved `transformer` w/ helpers.
+ * @date        2022-08-09 opt w/ `session-token` in CRUD.
+ * @date        2022-09-21 optimized the model management.
+ * @date        2022-11-09 param `isCreate` in `bodyToModel`, and support `GET /<type>/<cmd>/admin`
+ * @date        2022-11-11 cleanup and optimized names.
+ * @date        2022-12-29 optimized with `lemon-core@3.2.1`
+ * @date        2023-01-18 optimized with `lemon-core@3.2.4`
+ * @date        2023-01-20 optimized `doSearch()` w/ `SearchParam()`
+ * @date        2023-02-09 optimized `doPutBulk()`, and `doPostBulk()`
+ * @date        2023-02-13 optimized `doList()` to support `stereo` filter.
+ * @date        2023-02-15 optimized with `lemon-core@3.2.5`
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NextContext } from 'lemon-core';
+import { GeneralWEBController, NextHandler, SimpleSet } from 'lemon-core';
+import { CoreModel, AbstractTransformer, View, Body } from 'lemon-model';
+import { BulkBody, ListResult, PaginatedListResult, PaginateParam } from './types';
+import { MyCoreManager, MyCoreService, MyCoreProxy } from './abstract-services';
+export { CoreModel, AbstractTransformer };
+/**
+ * type: `CRUDCreationOptions`
+ * - options for cunstructor.
+ */
+interface CRUDCreationOptions {
+    /**
+     * (optional) flag to use `session-token` in CRUD
+     * - initialize this as `true` if required to use `session-token`
+     *
+     * @see proxy.getCurrenSession()
+     */
+    useSession?: boolean;
+}
+/**
+ * class: `AbstractCRUDController`
+ * - abstract high level class not to create directly.
+ */
+export declare abstract class AbstractCRUDController<ModelType extends string, MyModel extends CoreModel<ModelType>, MyView extends View, MyBody extends Body, MyService extends MyCoreService<MyModel, ModelType, MyCoreProxy<ModelType, MyService>>, MyManager extends MyCoreManager<MyModel, ModelType, MyService>, MyTransformer extends AbstractTransformer<MyModel, MyView, MyBody>> extends GeneralWEBController {
+    /**
+     * service instances
+     */
+    protected readonly service: MyService;
+    /**
+     * namespace for log(print)
+     */
+    protected readonly logNS: string;
+    /**
+     * my model manager
+     */
+    protected readonly manager: MyManager;
+    /**
+     * transformer between model and view.
+     */
+    protected readonly transformer: MyTransformer;
+    /** options in creation */
+    protected readonly options?: CRUDCreationOptions;
+    /**
+     * get the manager's type (= model-type)
+     */
+    get modelType(): ModelType;
+    /**
+     * get config of using session.
+     */
+    get confUseSession(): boolean;
+    /**
+     * model transformer from model to view
+     */
+    modelAsView(model: MyModel, useOnlyDefined?: boolean): MyView;
+    /**
+     * model transformer from body to body
+     */
+    bodyToModel(body: MyBody, isCreate?: boolean): MyModel;
+    /**
+     * from `session-token`, make base of model { sid, uid }
+     * @param proxy the current proxy.
+     * @returns base model
+     */
+    protected makeModelBase(proxy: MyCoreProxy<ModelType, any>): Promise<MyModel>;
+    /** load yml as model list */
+    loadMockData<T extends object>(name: string, base?: string): Promise<T[]>;
+    /**
+     * load mock-model from `.yml` file.
+     */
+    loadFromFile(file: string): Promise<MyModel & {
+        list: any[];
+    }>;
+    /**
+     * public constructor
+     *
+     * @param type - api controller's type name (ex: tests for `/tests`)
+     * @param service - backend service
+     * @param manager - my model manager in backend-service
+     * @param transformer - GeneralCRUDWEBControllerOptions
+     */
+    constructor(type: string, service: MyService, manager: MyManager, transformer: MyTransformer, options?: CRUDCreationOptions);
+    /**
+     * say hello
+     */
+    hello: () => string;
+    /**
+     * GET /<typeName>
+     * - list types
+     *
+     * ```sh
+     * $ http ':8888/<typeName>'
+     */
+    doList: NextHandler<PaginateParam & SimpleSet, PaginatedListResult<MyView>>;
+    /**
+     * list types by id
+     * - id means the search(query) id to use.
+     *
+     * ```sh
+     * $ http ':8888/<typeName>/<id>/list'
+     */
+    doGetList: NextHandler<PaginateParam & SimpleSet, PaginatedListResult<MyView>>;
+    /**
+     * internal admin command
+     */
+    doGetAdmin: NextHandler;
+    /**
+     * read a `MyModel`
+     *
+     * ```sh
+     * $ http ':8888/<typeName>/1'
+     */
+    doGet: NextHandler<any, MyView>;
+    /**
+     * create(or insert) a `MyModel`
+     * - `id` must be emptry (or '0')
+     *
+     * ```sh
+     * $ http POST ':8888/<typeName>/0' "key"="modelValue"
+     */
+    doPost(id: string, param: any, body: MyBody, $ctx?: NextContext): Promise<MyView>;
+    /**
+     * create(or insert) multi `MyModel`
+     * - `id` must be emptry (or '0')
+     *
+     * ```sh
+     * $ http POST ':8888/<typeName>/0/bulk' "key"="modelValue"
+     */
+    doPostBulk: NextHandler<any, MyView[], BulkBody<MyBody> | MyBody[]>;
+    /**
+     * update a `MyModel`
+     *
+     * ```sh
+     * $ http PUT ':8888/<typeName>/1000002' name="test-update"
+     */
+    doPut: NextHandler<any, MyView, MyBody>;
+    /**
+     * delete a `MyModel`
+     *
+     * ```sh
+     * $ http DELETE ':8888/<typeName>/1000003'
+     */
+    doDelete: NextHandler<any, MyView>;
+    /**
+     * bulk update a `TypeModel`
+     *
+     * ```sh
+     * $ http PUT ':8888/types/0/bulk'
+     */
+    doPutBulk: NextHandler<any, ListResult<MyView>, BulkBody<MyBody> | MyBody[]>;
+}

package/dist/cores/abstract-rest-apis.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `abstract-rest-api.ts`
+ * - support the rest-api pattern w/ remote service.
+ *
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-09-21 optimized w/ `abstract-rest-apis`
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { NextContext } from 'lemon-core';
+import { Reversable } from 'lemon-model';
+import { PaginatedListResult, PaginateParam } from './types';
+export { Reversable };
+/**
+ * support rest-api from remote service.
+ * - useful to use the common CRUD RestAPI.
+ */
+export declare class RestAPI<View extends object = any, Body = View, Model = View> {
+    readonly context: NextContext;
+    readonly endpoint: string;
+    readonly _reverser?: Reversable<Model, View, Body>;
+    readonly options?: {
+        isProd?: boolean;
+    };
+    constructor(context: NextContext, endpoint: string, _reverser?: Reversable<Model, View, Body>, options?: {
+        isProd?: boolean;
+    });
+    protected asProtocol(id?: string, cmd?: string): {
+        hello: () => string;
+        asTargetUrl: () => string;
+        execute: <T = any>(param?: any, body?: any, mode?: string) => Promise<T>;
+        enqueue: <T_1 = any>(param?: any, body?: any, mode?: string, callback?: string, delaySeconds?: number) => Promise<string>;
+        notify: (param?: any, body?: any, mode?: string, callback?: string) => Promise<string>;
+    };
+    /** get the current transform (may throw error) */
+    get reverser(): Reversable<Model, View, Body>;
+    /** say hello */
+    hello: () => string;
+    /** list model as view */
+    list: <T extends PaginateParam>(param?: T) => Promise<PaginatedListResult<View>>;
+    /** read model as view */
+    read: (id: string, param?: any) => Promise<View>;
+    /** insert model w/ body w/o id */
+    insert: (body: Body, param?: any) => Promise<View>;
+    /** update model w/ body by id */
+    update: (id: string, body: Body, param?: any) => Promise<View>;
+    /** delete model by id */
+    delete: (id: string, param?: any) => Promise<View>;
+    /** enqueue vis SQS */
+    enqueue: (params: {
+        id?: string;
+        cmd?: string;
+        mode?: string;
+        param?: any;
+        body?: any;
+    }, delay?: number) => Promise<string>;
+    /** execute vis API */
+    execute: <T = any>(params: {
+        id?: string;
+        cmd?: string;
+        mode?: string;
+        param?: any;
+        body?: any;
+    }) => Promise<T>;
+    /**
+     * set by model.
+     */
+    set: (id: string, model: Model) => Promise<Model>;
+    /**
+     * get by id
+     */
+    get: (id: string, throwable?: boolean) => Promise<Model>;
+    /**
+     * make new (w/ auto id)
+     */
+    new: (model: Model) => Promise<Model>;
+    /**
+     * delete (w/ auto id)
+     */
+    del: (id: string) => Promise<Model>;
+}
+/**
+ * rest-api for dummy
+ * - save model in memory.
+ */
+export declare class DummyRestAPI<View = any, Body = View, Model = View> extends RestAPI {
+    readonly context: NextContext;
+    readonly endpoint: string;
+    readonly _reverser?: Reversable<Model, View, Body>;
+    initialNo: number;
+    constructor(context: NextContext, endpoint: string, _reverser?: Reversable<Model, View, Body>, initialNo?: number);
+    /** say hello */
+    hello: () => string;
+    /** internal dummy memory */
+    protected $buf: {
+        [key: string]: any;
+    };
+    read: (id: string, param?: any) => Promise<View>;
+    insert: (body: any, param?: any) => Promise<View>;
+    update: (id: string, body: any, param?: any) => Promise<View>;
+    delete: (id: string, param?: any) => Promise<View>;
+}
+/**
+ * factory to create `rest-api` instance for both real and dummy.
+ */
+export declare const $createApi: <View extends object = object, Body_1 = View, Model = View>($context: NextContext, endpoint: string, reversor?: Reversable<Model, View, Body_1>, options?: {
+    isProd?: boolean;
+    isDummy?: boolean;
+    initialNo?: number;
+}) => RestAPI<View, Body_1, Model>;

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

@@ -0,0 +1,220 @@
+import { CoreManager, CoreModel, CoreService, SearchBody, ManagerProxy, AbstractProxy, NextContext, NextIdentityCognito, SortTerm, SimpleSet, SearchResult } from 'lemon-core';
+import { SessionToken } from '../service/backend-types';
+import { ListResult, PaginateParam } from './types';
+export declare type SearchParam<T> = T & {
+    [key: string]: string | 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.
+     */
+    guardProxy: <T>(context: NextContext, callback: (proxy: Proxy) => Promise<T>) => Promise<T>;
+    /**
+     * run search
+     * - override this to hide `$ES6`
+     */
+    doSearch<T>(body: SearchBody): Promise<SearchResult<T>>;
+}
+/**
+ * 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?: {
+        /** 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[], uniqueField?: string, options?: {
+        /** initial next-id number of auto-seq (default 1000000) */
+        initialNo?: number;
+    });
+    nextId(): 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>): SearchBody;
+    /**
+     * 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($page: PaginateParam, $param?: SearchParam<Model>): Promise<ListResult<Model>>;
+    /**
+     * 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;
+}
+/**
+ * class: `MyCoreProxy`
+ * - common parent of proxy.
+ */
+export declare class MyCoreProxy<U extends string, MyService extends MyCoreService<CoreModel<U>, U, any>> extends AbstractProxy<U, MyService> {
+    readonly managerProxies: {
+        [propKey: string]: MyManagerProxy<any, any, MyService>;
+    };
+    constructor(context: NextContext, service: MyService, cacheScope?: string);
+    /**
+     * 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, U, MyService>>(modelType: U): MyManagerProxy<Model, ModelManager, MyService>;
+    /**
+     * get the `session-token` from current req-context.
+     * - 1차 호출(front에서) 에서는 이 세션이 꼭 필요함.
+     * - 2차 호출(protocol이용) 에서는 선택사항으로, 조절가능해야함! (#TODO - 이걸 어떻게 구불할것인가?)
+     * - 로컬) 로컬 개발에서는 시뮬레이션 방법은 #TODO
+     *
+     * @param options.throwable flag to throw (default true)
+     */
+    getCurrenSession(options?: {
+        throwable?: boolean;
+    }): SessionToken;
+    /**
+     * find the current identity-id from context.
+     * - or, use env[LOCAL_ACCOUNT]
+     */
+    asCurrentIdentityId: (context?: NextContext) => string | null;
+    /**
+     * prepare `next-context` w/ the customized { domain, userAgent }
+     * @param identityId the target identity-id
+     */
+    asNextContext(identityId: string, params?: {
+        domain?: string;
+        userAgent?: string;
+    }): NextContext<NextIdentityCognito<any>>;
+}
+/**
+ * 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 session-token (default false) */
+        useSession?: boolean;
+    }): {
+        $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 create)
+     */
+    onBeforeSave(model: MyModel, $org?: MyModel): Promise<MyModel>;
+    /**
+     * 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(model: MyModel, validate?: boolean): Promise<MyModel>;
+}

package/dist/cores/commons.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `commons.ts`
+ * - common tools to export.
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-11-01 optimized w/ `commons`
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { ListParam, PaginateParam } from './types';
+/**
+ * extract only the defined attribute.
+ * ex) `{ a:1, b: undefined }` -> `{ a:1 }`
+ */
+export declare const onlyDefined: <T>(N: T) => T;
+/**
+ * list param parser
+ * @param param
+ */
+export declare function parseListParam(param?: ListParam, $def?: {
+    limit?: number;
+}): Required<ListParam>;
+/**
+ * paginate param parser
+ */
+export declare function parsePaginateParam(param?: PaginateParam, 
+/** default value or conditions */
+options?: {
+    noLimit?: boolean;
+    limit?: number;
+    page?: number;
+}): PaginateParam;

package/dist/cores/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `index.ts`
+ * - shared export in `/cores`
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-06-21 optimized w/ `abstract-services`
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+export * from './types';
+export * from './commons';
+export * from './abstract-services';
+export * from './abstract-controllers';
+export * from './abstract-rest-apis';

package/dist/cores/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * `types.ts`
+ * - common types used in `/cores`
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-06-21 optimized w/ `abstract-services`
+ * @date        2022-06-28 added `Codable` interface for general types.
+ * @date        2023-01-18 optimized with `lemon-core@3.2.4`
+ * @date        2023-02-15 optimized with `lemon-core@3.2.5`
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { CoreModel, View, Body } from 'lemon-model';
+export { CoreModel, View, Body };
+/**
+ * type `ListResult`
+ */
+export interface ListResult<T, R = string> {
+    /**
+     * total searched count
+     */
+    total?: number;
+    /**
+     * max items count in the page
+     */
+    limit?: number;
+    /**
+     * current page number.
+     */
+    page?: number;
+    /**
+     * items searched
+     */
+    list: T[];
+    /**
+     * (optional) aggr list
+     */
+    aggr?: R[];
+}
+export interface AggrKeyCount {
+    /** name of key(or bucket name) */
+    key: string;
+    /** number of count */
+    val: number;
+}
+/**
+ * type `PaginatedListResult`
+ */
+export interface PaginatedListResult<T> extends ListResult<T> {
+    /**
+     * current page
+     */
+    page: number;
+}
+/**
+ * type `ListParam`
+ */
+export interface ListParam {
+    /**
+     * max items count to be fetched
+     */
+    limit?: number;
+    /**
+     * (optional) sorting order
+     *  - 'asc': older first
+     *  - 'desc': newer first
+     *  - string: extended sorting features
+     */
+    sort?: 'asc' | 'desc' | string;
+}
+/**
+ * type `PaginateParam`
+ */
+export interface PaginateParam extends ListParam {
+    /**
+     * page # to fetch (0-indexed)
+     */
+    page?: number;
+    /**
+     * (optional) flag to filter by uid
+     */
+    uid?: string;
+}
+/**
+ * type `BulkUpdateBody`
+ */
+export interface BulkUpdateBody<T> extends BulkBody<T> {
+    /**
+     * list bulk update model with id
+     */
+    list: T[];
+}
+/**
+ * body data for bulk
+ */
+export interface BulkBody<T> {
+    list: T[];
+}
+/**
+ * list of the selected model-id
+ */
+export interface BodyList<T extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    list: T[];
+}

package/dist/lib/categories-types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `lib/categories-types.ts`
+ * - types for category support
+ *
+ *
+ * @author      Steve <steve@lemoncloud.io>
+ * @date        2022-10-18 initial version
+ *
+ * @copyright (C) 2022 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+import { GenericNode } from './types';
+/**
+ * type: `CategoryNode`
+ * - represent a single node of category tree.
+ * - node should have single parent's node.
+ */
+export interface CategoryNode extends GenericNode {
+    /** category-id */
+    id?: string;
+    /** this name */
+    name?: string;
+    /** id of parent node */
+    parent?: string;
+    /** name of parent node */
+    parentName?: string;
+    /** current depth (= parent.depth + 1) */
+    depth?: number;
+    /**
+     * the node path from root to node
+     * - list of [[id, name].join(':'),...]
+     */
+    paths?: string[];
+}