# @tars/utils

## @tars/utils

TARS 框架辅助工具集合

### Installation

```
$ npm install @tars/utils
```

### 01. 配置文件解析器

```javascript
var Config = require("@tars/utils").Config;
```

#### API

**parseFile(sFilePath, \[encoding, callback])**

解析指定文件

* `sFilePath`: 文件名
* `encoding`: 文件编码类型。 (默认值: utf8)
* `callback`: 回调函数，回调函数的格式 function callback(ret, config){}, 其中 ret 为对象{code: 返回码，成功为 0， 失败为-1, message: 描述, exception:如果成功为 undefined，如果失败为事件对象}， config 为解析器本身

#### parseText(sText)

解析字符串，并将解析的结果存于内部的\_data 属性中，可以通过 get 方法获取相应的值

* `sText`: 字符串
* `return`: true：解析成功, false: 解析失败

**get(key, defaultValue)**

文件被解析之后，会将结果存储到一个对象中，通过 get 方法可以获取制定的值。注：如果配置文件/字符串中有相同的 key，则 get 获取 key 对应的值时，不会获取所有的值，而是获取该 key 最后对应的那个值，也可以理解为对应相同的 key 后面的值覆盖前面的值。

* `key`: 需要取值的 key 值，格式为 x1.x2.x3，其中 x1，x2，x3 依次为深层次的 key，注：如果 key 值本身为 x1.x2 格式，取该 key 对应的值时需要写成\<x1.x2>,具体使用参见例子。
* `defaultValue`: 取不到结果的默认值

**getDomain(key, defaultValue)**

获取 key 对应的值中类型为 Object 的属性数组

* `key`: key 值。
* `defaultValue`: 取不到结果的默认值

**getDomainValue(key, defaultValue)**

获取 key 对应的值中类型为 Object 的属性值数组

* `key`: key 值。
* `defaultValue`: 取不到结果的默认值

**getDomainLine(key, defaultValue)**

获取 key 对应路径下的所有非空行

* `key`: key 值。
* `defaultValue`: 取不到结果的默认值
* `return`: 数组

**data**

通过该属性，可以获取文件解析的结果

### example

```javascript
var Config = require("@tars/utils").Config;

var config = new Config();
config.parseFile("./config.conf", "utf8");

var data = config.data;
console.log("data: ", data);
console.log(
  "get: tars.application.server.local: ",
  config.get("tars.application.server.local")
);
console.log(
  "getDomain: tars.application.server: ",
  config.getDomain("tars.application.server")
);
console.log(
  "getDomainValue: tars.application.server: ",
  config.getDomainValue("tars.application.server")
);
```

具体例子参见 examples 目录下的 test-config.js 文件

### 02. Endpoint 工具

```javascript
var Endpoint = require("@tars/utils").Endpoint;
```

#### API

**Class 方法：parse(desc)**

从字符串中解析出 Endpoint 信息

* `desc`: 字符串，例如：'tcp -h 127.0.0.1 -p 10000 -t 60000'
* `return`: 返回 Endpoint 实例。

**toString()**

Endpoint 信息转化成字符串

**copy()**

拷贝 Endpoint 实例

### example

```javascript
var Endpoint = require("@tars/utils").Endpoint;

var endpoint = Endpoint.parse("tcp -h 127.0.0.1 -p 10000 -t 60000");
console.log("endpoint: " + endpoint.toString());
console.log("endpoint.copy: " + endpoint.copy().toString());
```

具体例子参见 examples 目录下的 test-endpoint.js 文件

### 03. timeProvider 工具

```javascript
var timeProvider = require("@tars/utils").timeProvider;
```

#### API

**nowTimestamp()**

采用 Date.now()的方式获取时间，此种方式效率最高，Date.now()的方式的效率大概是 new Date().getTime()的 2 倍，是 process.hrtime()方式的 4 倍。

* `return`: 返回对象

```json
{
    hrtime: // 数组类型，[秒, 纳秒],
    timestamp: // 单位ms
}
```

**diff(oTime)**

当前时间相对于 oTime 的时间间隔

* `oTime`: 相对时间，nowTimestamp 函数返回的对象类型
* `return`: 浮点类型，时间间隔，单位毫秒
* 注：nowTimestamp 和 diff 配对使用

**dateTimestamp()**

获取当前的时间戳, 即机器从启动到当前的时间（process.hrtime）

* `return`: 返回对象

```json
{
    hrtime: // 数组类型，[秒, 纳秒],
    timestamp: // 单位ms
}
```

**dateTimestampDiff(oTime)**

当前时间相对于 oTime 的时间间隔

* `oTime`: 相对时间，dateTimestamp 函数返回的对象类型
* `return`: 浮点类型，时间间隔，单位毫秒
* 注：dateTimestamp 和 dateTimestampDiff 配对使用

### example

```javascript
var timeProvider = require("@tars/utils").timeProvider;

var i = 0,
  count = 10000000;
var tt1,
  tt2,
  interval = 0;
var t1 = new Date().getTime();
var t2 = t1;

tt1 = timeProvider.nowTimestamp();
for (i = 0; i < count; i++) {
  tt2 = timeProvider.diff(tt1);
}
t2 = new Date().getTime();
console.log("【hrTime】interval: " + (t2 - t1));

t1 = new Date().getTime();
tt1 = timeProvider.dateTimestamp();
for (i = 0; i < count; i++) {
  tt2 = timeProvider.dateTimestampDiff(tt1);
}
t2 = new Date().getTime();
console.log("【hrTime】interval: " + (t2 - t1));
```

具体例子参见 examples 目录下的 test-timer.js 文件

### 03. Promise 库

```javascript
var Promise = require("@tars/utils").Promise;
```

为 TARS 应用提供一个方便统一的 Promise 库。开发 TARS 应用时推荐大家使用此库而不是自己选择 Promise 库，当出现更好的 promise 方案时，我们可以直接替换此模块中的实现，直接对所有应用生效。

```javascript
var Promise = require("@tars/utils").Promise;
var promise = new Promise(function (resolve, reject) {
  setTimeout(function () {
    resolve(666);
  }, 3000);
});
promise.then(function (data) {
  console.log(data);
});
```

目前 TARS 中的 Promise 是基于 bluebird 库实现的，在 q、bluebird、原生 Promise 中 bluebird 性能最好。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tarscloud.gitbook.io/tarsdocs/tars.js/tars-utils.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.