suanpan_node_sdk 2.0.0-beta.8 → 2.0.2

package/README.md

@@ -1,96 +1,688 @@
-## 简介
-目前 Node Sdk
+# Table of contents
+- [Introduction](#introduction)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [API Reference](#api-reference)
+  - [Parameter](#parameter)
+    - [.get([key])](#getkey)
+  - [Message](#message)
+      - [constructor(headers, payload)](#constructorheaders-payload)
+        - [headers](#headers)
+        - [payload](#payload)
+  - [MessageListener](#messagelistener)
+    - [.onMessage(messageHandler)](#onmessagemessagehandler)
+  - [MessageChannelFactory](#messagechannelfactory)
+    - [.createMessageChannel()](#createmessagechannel)
+  - [MessageChannel](#messagechannel)
+    - [.receiveMessage()](#receivemessage)
+    - [.sendMessage(message)](#sendmessagemessage)
+    - [MessageHandler](#messagehandler)
+  - [MessageChain](#messagechain)
+    - [constructor](#constructor)
+    - [.send(payload)](#sendpayload)
+  - [MessageBuilder](#messagebuilder)
+    - [.fromMessagePayload(message)](#frommessagepayloadmessage)
+    - [.fromMessageHeaders(message)](#frommessageheadersmessage)
+    - [.withPayload(payload)](#withpayloadpayload)
+    - [.setHeader(key, value)](#setheaderkey-value)
+    - [.setHeaderIfAbsent(key, value)](#setheaderifabsentkey-value)
+    - [.build()](#build)
+  - [Storage](#storage)
+    - [.append(objectName, content)](#appendobjectname-content)
+    - [.putObject(objectName, data)](#putobjectobjectname-data)
+    - [.listObjects(prefix, recursive)](#listobjectsprefix-recursive)
+    - [.fGetObject(objectName, filePath)](#fgetobjectobjectname-filepath)
+    - [.fPutObject(objectName, filePath)](#fputobjectobjectname-filepath)
+    - [.deleteObject(objectName)](#deleteobjectobjectname)
+    - [.deleteMultiObjects(objectNames)](#deletemultiobjectsobjectnames)
+    - [.checkObjectNameExist(objectName)](#checkobjectnameexistobjectname)
+    - [.getObjectToJSON(objectName)](#getobjecttojsonobjectname)
+    - [.getObjectToString(objectName)](#getobjecttostringobjectname)
+    - [.getObjectToBuffer(objectName)](#getobjecttobufferobjectname)
+    - [.getObjectToStream(objectName)](#getobjecttostreamobjectname)
+  - [StoragePath](#storagepath)
+    - [constructor([options])](#constructoroptions)
+    - [.getUserPath([userId])](#getuserpathuserid)
+    - [.getAppPath([appId])](#getapppathappid)
+    - [.getComponentPath([componentId])](#getcomponentpathcomponentid)
+    - [.getNodePath([nodeId])](#getnodepathnodeid)
+    - [.getAppLogPath(userId)](#getapplogpathuserid)
+    - [.getNodeLogPath(userId)](#getnodelogpathuserid-nodeid)
+    - [.getAppTempDir(userId)](#getapptempdiruserid)
+  - [ObjectStorageLogger](#objectstoragelogger)
+    - [constructor(options)](#constructoroptions-1)
+    - [.info(message[, flush])](#infomessage-flush)
+    - [.debug(message[, flush])](#debugmessage-flush)
+    - [.warn(message[, flush])](#warnmessage-flush)
+    - [.error(message[, flush])](#errormessage-flush)
+  - [EventLogger](#eventlogger)
+    - [.info(message)](#infomessage)
+    - [.debug(message)](#debugmessage)
+    - [.warn(message)](#warnmessage)
+    - [.error(message)](#errormessage)
+- [Type Reference](#type-reference)
+  - [MessageHeaders](#messageheaders)
+  - [LogLevel](#loglevel)
+  - [StorageLoggerOptions](#storageloggeroptions)
+  - [Platform](#platform)
+# Introduction
+算盘组件之间通过 Redis 消息队列进行消息通信，SDK 对 Redis 提供的 Stream API 进行了封装，提供了发送消息/对象存储等方法。
+![image.png](https://cdn.nlark.com/yuque/0/2021/png/502931/1630910242408-c966cd0d-34fe-4bf9-ac47-ac72d50cfe42.png#clientId=u685e5f8c-6bda-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=320&id=ube246cc1&margin=%5Bobject%20Object%5D&name=image.png&originHeight=682&originWidth=1494&originalType=binary&ratio=1&rotation=0&showTitle=false&size=122605&status=done&style=none&taskId=ubb851989-49e6-45e1-a536-f14880aa017&title=&width=702)
 
-- 支持消息收发
-- 读取组件的右面板参数
-- Event Log Sender
-- 支持 oss 类型的 storage 功能 [beta]
+[1.x 版本文档](https://github.com/xuelang-group/suanpan-node-sdk/blob/master/docs/1.x.x-version.md)
 
-[SDK 目录约定](https://xuelangyun.yuque.com/suanpan_doc/public/bokg7z)
+[SDK 目录约定](https://xuelangyun.yuque.com/suanpan_doc/public/bokg7z)           
+# Install
 
-## Installation
-```powershell
-npm install suanpan_node_sdk -S 
-// or beta
-npm install suanpan_node_sdk@beta -S
+Make sure you have Node 10 or greater installed.
+Get the library：
+```shell
+$ npm install suanpan_node_sdk --save
 ```
-## Docker
-可以使用基础镜像 node_sdk_base:latest
-latest可替换为指定的SDK版本号
-例如：
+# Quick Start
+
+```typescript
+import { MessageListener, MessageHandler } from 'suanpan_node_sdk';
+
+const messageHandler: MessageHandler = (message, chain) => {
+  const headers = message.headers;
+  const payload = message.payload;
+
+  const requestId = headers.requestId;
+  const timestamp = headers.timestamp;
+
+  /** Business logic here */
+
+  chain.send({ // 发送消息
+    out1: 'xxxx',
+    out2: true,
+    out3: { success: true, result: [1, 2, 3] }
+  });
+}
+
+MessageListener.onMessage(messageHandler);
 ```
-ARG ARCH="amd64"
-FROM registry.cn-shanghai.aliyuncs.com/shuzhi-$ARCH/node_sdk_base:latest
+# Features
+
+- [获取右面板参数](#parameter)
+- [流计算消息接受与发送](#messagelistener)
+- [对象（OSS/MINIO）存储 API](#storage)
+- [Logkit 结构化日志存储（EventLogger）](#eventlogger)
+- [对象存储日志收集器（ObjectStorageLogger）](#objectstoragelogger)
+
+# API Reference 
+## Parameter
+
+获取配置参数，以及内置一些常用参数，例如：AppId，NodeId 等
+### .get([key])
+Parameter Class 提供一个**静态方法** `.get([key])` 获取配置参数。
+
+**parameters**:
+
+- `key {string}`：参数名称。如果 key 为空，则获取“全部”配置参数。
+
+**example**:
+```typescript
+import { Parameter, JSONObject } from 'suanpan_node_sdk';
+/**
+ * 内置参数
+ */
+const userId = Parameter.UserId
+const appId = Parameter.AppId;
+const nodeId = Parameter.NodeId;
+const componentId = Parameter.ComponentId;
+
+/**
+ * 获取“单个”配置参数
+ */
+const paramValue = Parameter.get<string>('paramKey');
+
+/**
+ * 获取“全部”配置参数
+ */
+const params = Parameter.get<JSONObject>();
 ```
+## Message
+
+Message entity object. The constructor includes headers and payload. The message’s payload Object can not be set after the initial creation. However, the mutability of the header values themselves (or the payload Object) is intentionally left as a decision for the framework user.
+#### constructor(headers, payload)
+##### headers
+
+- headers { [MessageHeaders](#messageHeaders) } - Represents a collection of message headers for a message. **The built-in read-only headers are:**
+   - `requestId`：An identifier for this message instance.
+   - `timestamp`：The time the message was created. Changes each time a message is mutated.
+##### payload
+
+- payload {Object} - The data type of payload should strictly comply with the input / output port conventions of suanpan, such as: `{ in1: 111 }, { out1: 222 }`. The content wrapped by the message can be any Javascript type, and because the interface is parameterized, you can retrieve the payload in a type-safe fashion.
+
+
 
-基础镜像中 suanpan_node_sdk 通过全局安装
-本地开发可以通过`npm install -D suanpan_node_sdk`来提供代码提示
+**example：**
+```typescript
+import { Message } from 'suanpan_node_sdk';
 
-## 功能列表
-### 1. 获得右面板配置参数(parameter)
-```javascript
-const sp = require('suanpan_node_sdk').sp
-const spParameter = sp.parameter
-console.log(spParameter)
+const customHeader = {
+  'x-stream-id': 'xxxx'
+};
+
+const payload = {
+	out1: 100
+};
+const message = new Message(customHeader, payload);
+```
+## MessageListener
+
+流计算消息监听类，`MessageListener` 提供一个静态方法 `onMessage` 来处理发送的消息。
+### .onMessage(messageHandler)
+**parameters：**
+
+- messageHandler { [MessageHandler](#messageHandler) }：消息处理回调函数。
+
+**example** 参照 [**Quick Start**](#quick-Start)
+**​**
+
+## MessageChannelFactory
+
+消息双向管道工厂类，`MessageChannelFactory` 提供一个静态方法 `createMessageChannel` 返回 `MessageChannel` 消息双向管道实例。
+### .createMessageChannel()
+**return：**
+
+- [**MessageChannel**](#messageChannel)
+
+**example：**
+```typescript
+import { MessageChannelFactory } from 'suanpan_node_sdk';
+
+(async () => {
+	const channel = MessageChannelFactory.createMessageChannel();
+  channel.receiveMessage().then(message => {
+    /** Business logic here */
+  });
+})();
+```
+## MessageChannel
+
+消息双向通道**接口**，支撑流计算消息的**接收和发送。不支持用户显示创建，仅能从 MessageChannelFactory 创建**
+### .receiveMessage()
+接收消息，用户可以返回的 Message 自定义消息的处理逻辑。
+**return：**
+
+- Promise<[**Message**](#message)>
+### .sendMessage(message)
+**parameters：**
+
+- message { [Message](#message)} - 消息实例
+
+### MessageHandler
+
+MessageHandler 是 Node SDK 定义的消息处理程序（此处仅表示函数类型），它作为回调函数注册到 channel 中。函数定义如下：
+```typescript
+type MessageHandler = (message: Message, chain: MessageChain) => void | Promise<void>;
 ```
+函数参数 parameters 定义中包含：
+
+- message { [Message](#message) } - 传递的消息实体
+- chain { [MessageChain](#messageChain) } - 消息链，用于发送同源消息（组件的同步/异步机制）
+
+**example**: 
+```typescript
+import { MessageHandler } from 'suanpan_node_sdk';
+
+const messageHandler: MessageHandler = (message, chain) => {
+  const headers = message.headers;
+  const payload = message.payload;
 
-### 2. 发送消息与接受消息
-#### 构建发送包
-```javascript
-let msgPackOut = {
-    out1: "a", //将发送 "a" 到第一个消息出口
-    out2: "b", //将发送 "b" 到第二个消息出口
+  const requestId = headers.requestId;
+  const timestamp = headers.timestamp;
+
+  /** Business logic here */
+
+  chain.send({ // 发送消息
+    out1: 'xxxx',
+    out2: true,
+    out3: { success: true, result: [1, 2, 3] }
+  });
 }
 ```
-`msgPackOut` 对象的 `key` 由 `out` 与数字拼接而成的 key，表示第 N 个消息出口  
-`msgPackOut` 对象的 `value` 表示发送到对应出口的数据（value 必须是字符串）
-
-#### 监听 call 事件
-每当有新消息到达组件，则会触发Call事件
-```javascript
-sp.onCall((req, res) => {
-    let msgPackIn = req.msg
-    console.log(msgPackIn)
-    // msgPackIn结构如下
-    //{in1:"a"}
-    // key(inN) 表示第N个消息入口, value是字符串
-  
-    // doSomething here
-    res.send(msgPackOut) // 调用 res.send 发送数据包到下游节点
-})
+## MessageChain
+
+消息链，用于发送同源消息（组件的同步/异步机制）
+### constructor
+
+- message { [Message](#message)} - 消息实体，包含 `headers` 和 `payload` 两部分
+- channel { [MessageChannel](#messageChannel) } - 消息传输双向管道
+### .send(payload)
+**parameters:**
+
+- payload { Object } -  The data type of payload should strictly comply with the output port conventions of suanpan, such as: `{ out1: 111 }, { out2: 222 }`
+
+**example:**
+```typescript
+import { MessageChain, MessageBuilder, MessageChannelFactory } from 'suanpan_node_sdk';
+
+(async () => {
+
+  const requestMessage = MessageBuilder
+    .withPayload({ in1: 'sss'})
+    .setHeaderIfAbsent('requestId', 'uuid')
+    .setHeaderIfAbsent('x-stream-id', '12345')
+    .build();
+
+  const messageChannel = MessageChannelFactory.createMessageChannel();
+  const chain = new MessageChain(requestMessage, messageChannel);
+
+  chain.send({ out1: 1234 })
+})();
+```
+## MessageBuilder
+
+消息建造者。双向消息管道传输媒介 Message 的建造者，并提供多种静态方法帮助用户构建自定义消息。
+### .fromMessagePayload(message)
+提取并仅保留 message payload，返回当前建造者实例。
+
+**parameters:**
+
+- message { [Message](#message) } - 消息实例
+
+**return：**
+
+- [MessageBuilder](#messageBuilder)
+
+
+
+### .fromMessageHeaders(message)
+提取并仅保留 message headers，返回当前建造者实例。
+
+**parameters:**
+
+- message { [Message](#message) } - 消息实例
+
+**return：**
+
+- [MessageBuilder](#messageBuilder)
+
+
+
+### .withPayload(payload)
+添加消息 payload，返回当前建造者实例。
+
+**parameters:**
+
+- [payload](#payload)
+
+**return：**
+
+- [MessageBuilder](#messageBuilder)
+
+### .setHeader(key, value)
+添加消息 header，返回当前建造者实例。
+
+**parameters:**
+
+- key {string} - header key's name
+- value {string} - header key's value
+
+**return：**
+
+- [MessageBuilder](#messageBuilder)
+
+
+### .setHeaderIfAbsent(key, value)
+用法同 [.setHeader](#.setHeader(key,-value))，消息 header key'name 不存在时添加
+​
+
+### .build()
+生成消息 Message 实例。
+**return：**
+
+- [Message](#message)
+
+
+
+## Storage
+
+Storage 是对对象存储（目前支持 Aliyun OSS以及开源 Minio）API 的封装。
+### .append(objectName, content)
+Append an object to the bucket, it's almost same as [putObject](#.putObject(objectName,-data)), but it can add content to existing object rather than override it.
+**parameters**:
+
+- objectName {string} - Name store on OSS
+- content {string} - What would you like to add to bucket
+
+**example**: 
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+  await Storage.Instance.append('/studio/userId/appId/nodeId/log.txt', 'redis subscribed.');
+})();
 ```
+### .putObject(objectName, data)
+Uploads an object from a stream/Buffer/string.
+**parameters**:
+
+- objectName {string} - Name store on OSS
+- data {String | Buffer | ReadStream} - object data
 
-#### 主动发送信息
-```powershell
-sp.sendMessage(msgPackOut)
+**example**: 
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+  await Storage.Instance.putObject('/studio/userId/appId/nodeId/data.js', 'const f = () => { console.log("a")}');
+})();
 ```
+### .listObjects(prefix[, recursive][, maxKeys])
+List objects in the bucket.
+**parameters**:
 
-### 3. EventLogger Sender
-提供 log 格式化的存储形式持久化在数据库中，app 释放后仍然保留，用于不同用户查看修改错误，用户重新部署后清除。logkit 能够直接运行在算盘 Server 中，也可以单独运行。架构图：
-![image.png](https://cdn.nlark.com/yuque/0/2021/png/502931/1615780837866-0a9141e8-3da1-4fff-98aa-cc4ace5e7aed.png#align=left&display=inline&height=384&margin=%5Bobject%20Object%5D&name=image.png&originHeight=836&originWidth=1044&size=78619&status=done&style=none&width=480)
-Node Sdk 提供 event log（内部使用 socketio 作为接口的基础协议）接口单向传输到 logkit。
+- `prefix {string}` - Name prefix store on OSS，such as `/studio/userId/appId/nodeId`
+- `recursive {boolean}` - Default：true。Recursively find all objects under “prefix”
+- `maxKeys {Number}` - Max objects, default is 100, limit to 1000
 
-代码示例：
-```javascript
-let { sp, EventLogger } = require('suanpan_node_sdk');
+**example：**
+```typescript
+import { Storage, ObjectItem } from 'suanpan_node_sdk';
 
-const eventLogger = EventLogger.Instance;
+(async () => {
+  const objects: ObjectItem[] = await Storage.Instance.listObjects('/studio/userId/appId/nodeId/', true, 200);
+})();
+```
+### .fGetObject(objectName, filePath)
+Downloads and saves the object as a file in the local filesystem.
+**parameters**:
 
-sp.onCall((req, res) => {
+- `objectName {string}` - Name store on OSS
+- `filePath {string}` - Path on the local filesystem to which the object data will be written.
 
-  if (!req.msg) {
-    // 发送 event log
-    eventLogger.warn('received message is empty.');
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+  await Storage.Instance.fGetObject('/studio/userId/appId/nodeId/coco.ts', '/tmp/coco.ts');
+})();
+```
+### .fPutObject(objectName, filePath)
+Uploads contents from a file to objectName.
+**parameters**:
+
+- `objectName {string}` - Name store on OSS
+- `filePath {string}` - Path of the file to be uploaded.
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+  await Storage.Instance.fPutObject('/studio/userId/appId/nodeId/coco.ts', '/tmp/coco.ts');
+})();
+```
+### .deleteObject(objectName)
+Removes an object. If delete object not exists, will also delete success.
+**parameters**:
+
+- `objectName {string}` - Name store on OSS
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+  await Storage.Instance.deleteObject('/studio/userId/appId/nodeId/coco.ts');
+})();
+```
+### .deleteMultiObjects(objectNames)
+Removes multiple objects.
+**parameters**:
+
+- `objectNames {string[]}` - List of objects in the bucket to be removed. such as`['objectname1','objectname2']`
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+  const objectList = ['/studio/userId/appId/nodeId/coco1.ts', '/studio/userId/appId/nodeId/coco2.ts'];
+  await Storage.Instance.deleteMultiObjects(objectList);
+})();
+```
+### .checkObjectNameExist(objectName)
+Check whether the object exists，Returns true if it exists, otherwise false
+**parameters**:
+
+- `objectName {string}` - Name store on OSS
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+	const exist = await Storage.Instance.checkObjectNameExist('/studio/not.json');
+  if (exist) {
+  	// do something
   }
+})();
+```
+### .getObjectToJSON(objectName)
+Get an object to JSON object
+**parameters**:
 
-  res.send({
-    out1: 'hello world this send in call'
-  });
+- `objectName {string}` - Name store on OSS
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+	const json = await Storage.Instance.getObjectToJSON('/studio/not.json');
+})();
+```
+### .getObjectToString(objectName)
+Get an object to string.
+**parameters**:
+
+- `objectName {string}` - Name store on OSS
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+	const str = await Storage.Instance.getObjectToString('/studio/log.txt');
+})();
+```
+### .getObjectToBuffer(objectName)
+Get an object to Buffer.
+**parameters**:
+
+- `objectName {string}` - Name store on OSS
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+	const buf = await Storage.Instance.getObjectToBuffer('/studio/log.txt');
+})();
+```
+### .getObjectToStream(objectName)
+Get an object to read stream.
+
+**parameters:**
+
+- `objectName {string}` - Name store on OSS
+
+**example：**
+```typescript
+import { Storage } from 'suanpan_node_sdk';
+
+(async () => {
+	const stream = await Storage.Instance.getObjectToStream('/studio/demo.txt');
+	stream.pipe(fs.createWriteStream('some file.txt'));
+})();
+```
+## StoragePath
+
+对象存储路径工具类。
+### constructor([options])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| userId | string | 否 | 用户 Id |
+| appId | string | 否 | 项目 Id |
+| componentId | string | 否 | 组件 Id |
+| nodeId | string | 否 | 节点 Id |
+
+### .getUserPath([userId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| userId | string | 否 | 默认使用当前用户 Id |
+
+### .getAppPath([appId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| appId | string | 否 | 默认使用当前项目Id |
+
+### .getComponentPath([componentId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| componentId | string | 否 | 默认使用当前组件 Id |
+
+### .getNodePath([nodeId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| nodeId | string | 否 | 默认使用当前节点 Id |
+
+### .getAppLogPath([userId][, appId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| userId | string | 否 | 默认使用当前用户 Id |
+| appId | string | 否 | 默认使用当前项目Id |
+
+### .getNodeLogPath([userId][, appId][, nodeId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| userId | string | 否 | 默认使用当前用户 Id |
+| appId | string | 否 | 默认使用当前项目 Id |
+| nodeId | string | 否 | 默认使用当前节点 Id |
+
+### .getAppTempDir([userId][, appId])
+| 参数名 | 参数类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| userId | string | 否 | 默认使用当前用户 Id |
+| appId | string | 否 | 默认使用当前项目 Id |
+
+## ObjectStorageLogger
+
+对象存储日志收集器
+### constructor([options](#storageLoggerOptions))
+| **属性名** | **类型** | **是否必填** | **说明** |
+| --- | --- | --- | --- |
+| storagePath | string | **是** | 完整对象存储路径 objectName，例如：`/studio/userId/appId/nodeId/log-2021-1014.txt` |
+| console | boolean | 否 | 默认 false。开启后日志将会 print 到标准输入输出 |
+| level | [Loglevel](#logLevel) | 否 | 默认 1 (debug)。日志等级 |
+| maxItems | number | 否 | 默认 1。表示缓存长度。当日志积累条数 >= maxItems 时，将会触发 flush 操作，将日志上传到对象存储。 |
+| flushInterval | number | 否 | 默认 0，单位 ms。即实时将日志保存到对象存储中。如果想控制每隔 1s 钟收集一次。设置其值为：1000 |
+
+### .info(message[, flush])
+### .debug(message[, flush])
+### .warn(message[, flush])
+### .error(message[, flush])
+**parameters**:
+
+- `message {string}` - 日志内容
+- `flush {boolean}` - 默认：false。flush 为 true 时将会立即刷新日志到对象存储。
+
+**example：**
+```typescript
+import { StoragePath, ObjectStorageLogger } from 'suanpan_node_sdk';
+
+const storagePath = new StoragePath();
+
+const storageLogger = new ObjectStorageLogger({
+  storagePath: storagePath.getNodeLogPath() + '/log.txt'
 });
+
+storageLogger.info('append this log');
+```
+## EventLogger
+
+- EventLogger 提供日志的结构化存储（持久化在数据库中），模版释放后仍然保留，用于不同用户查看修改错误，用户重新部署后清除。logkit 能够直接运行在算盘 Server 中，也可以单独运行。
+- EventLogger（内部使用 socketio 作为接口的基础协议）单向传输到 logkit。用户可以自己将业务日志通过 EventLogger 发送到算盘 logkit。
+- EventLogger 默认情况下：用户代码（MessageHandler）运行时 Error，将会自动触发 EventLogger 的 error 事件，将结构化错误信息发送到 logkit。
+### .info(message)
+### .debug(message)
+### .warn(message)
+### .error(message)
+**parameters**:
+
+- `message {string}` - logkit 日志内容
+
+**example：**
+
+```typescript
+import { EventLogger, MessageListener, MessageHandler } from 'suanpan_node_sdk';
+
+const messageHandler: MessageHandler = (message, chain) => {
+  const headers = message.headers;
+  const payload = message.payload;
+
+  const requestId = headers.requestId;
+  const timestamp = headers.timestamp;
+  
+  if(!payload.in1) {
+    EventLogger.Instance.error('received message is empty.');
+    return;
+  }
+
+  chain.send({ // 发送消息
+    out1: 'xxxx',
+    out2: true,
+    out3: { success: true, result: [1, 2, 3] }
+  });
+}
+
+MessageListener.onMessage(messageHandler);
 ```
+# Type Reference
 
-默认情况下，用户代码（onCall）中运行时 Error，将会自动触发 event log 的 error 事件，将结构化错误信息发送到 logkit。等于在 `after onCall` 中插入如下代码：
-```javascript
-eventLogger.error(e.message)
+- [MessageHeaders](#messageHeaders)
+- [LogLevel](#logLevel)
+- [StorageLoggerOptions](#storageLoggerOptions)
+- [Platform](#platform)
+## MessageHeaders
+```typescript
+export interface MessageHeaders {
+  requestId: string;
+  timestamp: number;
+  extra: JSONObject;
+}
+```
+## LogLevel
+```typescript
+export enum LogLevel {
+  DEBUG = 1,
+  INFO = 2,
+  WARN = 3,
+  ERROR = 4
+}
+```
+## StorageLoggerOptions
+```typescript
+type StorageLoggerOptions = {
+    storagePath: string;
+    console?: boolean;
+    level?: LogLevel;
+    maxItems?: number;
+    flushInterval?: number;
+};
+```
+## Platform
+```typescript
+enum Platform {
+    WINDOWS = 0,
+    MACINTOSH = 1,
+    LINUX = 2
+}
 ```
-**注**：确保 sdk 版本在 `1.4.2` 以上