- `FunctionPropertyNames`

获取对象中的方法名称，返回union type

const t1 = {
add() {},
minus() {},
div() {},
result: 0,
};
type T1 = FunctionPropertyNames; // 'add' | 'minus' | 'div'
```

- `NonFunctionPropertyNames`

获取对象中非函数属性名称，返回union type

const t1 = {
add() {},
minus() {},
div() {},
result: 0,
};
type T1 = FunctionPropertyNames; // 'result'
```

- `ValueOf`

获取对象中`key`的值，返回由这些值组成的union type

```ts
const map = {
0: '0m',
1: '1m',
2: '2m',
3: '3m',
4: '4m',
5: '5m',
6: '6m',
} as const;

type T0 = ValueOf; // '0m' | '1m' | '2m' | '3m' | '4m' | '5m' | '6m'
```

- `WithRequired`

指定属性变为必选

```ts
type Input = {
a: number;
b?: string;
};
type Output = WithRequired // { a: number; b: string }
```

### algorithm

- `function nodeCountAtDepth(root: Record, depth: number, childrenKey: string = 'children'): number;`

计算指定层级的节点数量

```ts
const root = {
id: 1,
children: [
{ id: 2, children: [{ id: 21 }, { id: 22 }, { id: 23 }] },
{ id: 3, children: [{ id: 31 }, { id: 32 }, { id: 33 }] },
],
};
expect(tree.nodeCountAtDepth(root, 0)).to.be.equal(1);
expect(tree.nodeCountAtDepth(root, 1)).to.be.equal(2);
expect(tree.nodeCountAtDepth(root, 2)).to.be.equal(6);
```

- `const findNode = >(tree: T[], predicate: (node: T) => boolean, childrenKey = 'children'): T | null`

找到符合条件的节点

```ts
const root = {
id: 1,
children: [
{ id: 2, children: [{ id: 21 }, { id: 22 }, { id: 23 }] },
{ id: 3, children: [{ id: 31 }, { id: 32 }, { id: 33 }] },
],
};
const actual = tree.findNode([root], (node) => node.id === 3);
expect(actual).to.be.deep.equal(root.children[1]);

const actual2 = tree.findNode([root], (node) => node.id === 33);
expect(actual2).to.be.deep.equal(root.children[1].children[2]);
```

### file

- `toImage(file: BlobPart | FileURL, options?: BlobPropertyBag): Promise`

转换BlobPart或者文件地址为图片对象

- `validateImageSize(file: BlobPart | FileURL, limitSize: { width: number; height: number }, options?: BlobPropertyBag): Promise`

返回值:

```ts
interface ImageSizeValidationResult {
isOk: boolean;
width: number;
height: number;
}
```

图片宽，高校验

- `isImageExists(src: string, img: HTMLImageElement = new Image()): Promise`

检测图片地址是否可用

```ts
import { file } from '@d-matrix/utils';

const url = 'https://picsum.photos/200/300';
const res = await file.isImageExists(url);
```

传入HTML中已经存在的`img`元素

```js
import { file } from '@d-matrix/utils';

const $img = document.getElementById('img');
const res = await file.isImageExists(url, $img);
```

- `getFilenameFromContentDispositionHeader(header: { ['content-disposition']: string }): string`

从`Content-Disposition` response header中获取`filename`

```ts
import { file } from '@d-matrix/utils';

const header = {
'content-disposition': 'attachment;filename=%E5%A4%A7%E8%A1%8C%E6%8C%87%E5%AF%BC2024-06-27-2024-06-28.xlsx'
};
const filename = file.getFilenameFromContentDispositionHeader(header);
// '大行指导2024-06-27-2024-06-28.xlsx'
```

- `download(source: string | Blob, fileName = '', target?: HyperLinkTarget): void`

文件下载，`source`是文件地址或`blob`对象。

```ts
type HyperLinkTarget = "_self" | "_blank" | "_parent" | "_top"
```

- `downloadFileByIframe(source: string): boolean`

通过创建`iframe`进行文件下载

## support

- `isBrowserEnv(): boolean`

是否是浏览器环境

- `isWebSocket(): boolean`

是否支持WebSocket

- `isSharedWorker(): boolean`

是否支持SharedWorker

## timer

- `sleep(ms?: number): Promise`

使用`setTimeout`与`Promise`实现，暂停执行`ms`毫秒

```ts
await sleep(3000); // 暂停3秒
console.log('continue'); // 继续执行
```

## operator

- `trueTypeOf = (obj: unknown): string`

检查数据类型

```ts
trueTypeOf([]); // array
trueTypeOf({}); // object
trueTypeOf(''); // string
trueTypeOf(new Date()); // date
trueTypeOf(1); // number
trueTypeOf(function () {}); // function
trueTypeOf(/test/i); // regexp
trueTypeOf(true); // boolean
trueTypeOf(null); // null
trueTypeOf(undefined); // undefined
```

## decimal

- `format(value: number | string | undefined | null, options?: FormatOptions): string`

格式化数字，默认保留3位小数，可添加前缀，后缀，默认值为'--'，用法见[测试](./tests//decimal.cy.ts)

```ts
type FormatOptions = {
decimalPlaces?: number | false;
suffix?: string;
prefix?: string;
defaultValue?: string;
operation?: {
operator: 'add' | 'sub' | 'mul' | 'div' | 'toDecimalPlaces';
value: number;
}[];
};
```

## object

- `removeZeroValueKeys = >(obj: T, zeroValues = ZeroValues): T`

移除零值的键, 默认的零值是：`undefined`、`null`, `''`, `NaN`, `[]`, `{}`

```ts
removeZeroValueKeys({ a: '', b: 'abc', c: undefined, d: null, e: NaN, f: -1, g: [], h: {} })
// { b: 'abc', f: -1 }
```

- `typedKeys(obj: T): Array`

返回`tuple`，而不是`string[]`

```ts
const obj = { a: 1, b: '2' };
Object.keys(obj) // string[]
object.typedKeys({ a: 1, b: '2' }) // ('a' | 'b')[]
```

## array

- `moveImmutable(array: T[], fromIndex: number, toIndex: number): T[]`

```js
import { array } from '@d-matrix/utils';

const input = ['a', 'b', 'c'];

const array1 = array.moveImmutable(input, 1, 2);
console.log(array1);
//=> ['a', 'c', 'b']

const array2 = array.moveImmutable(input, -1, 0);
console.log(array2);
//=> ['c', 'a', 'b']

const array3 = array.moveImmutable(input, -2, -3);
console.log(array3);
//=> ['b', 'a', 'c']
```

- `moveMutable(array: T[], fromIndex: number, toIndex: number): void`

- `moveToStart(array: T[], predicate: (item: T) => boolean): T[]`

移动元素到数组首位，不会修改原数组

```js
import { array } from '@d-matrix/utils';

const list = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }, { id: 5 }];
const newList = array.moveToStart(list, (item) => item.id === 4);

// [{ id: 4 }, { id: 1 }, { id: 2 }, { id: 3 }, { id: 5 }]
```

- `moveMulti(arr: T[], indexes: number[], start: number): T[]`

移动多个元素到数组中指定的位置,用法,见[测试用例](tests/algorithm.cy.ts)

## number

- `randomInt(min: number, max: number): number`

返回`min`, `max`之间的随机整数

## echarts

- `mergeOption(defaults: EChartsOption, overrides: EChartsOption, option?: deepmerge.Options): EChartsOption`

deep merge Echarts配置，用法见[测试用例](./tests//echarts/echarts.cy.ts)

- `fill, XAxisField extends keyof T, YAxisField extends keyof T>(dataSource: T[], xAxisField:XAxisField, yAxisField: YAxisField): T[]`

场景：后端接口返回某几个时间点的数据，需求是在接口数据的基础上每隔5分钟补一个点，以达到图中的效果: [折线图](https://raw.githubusercontent.com/mrdulin/pic-bucket-01/master/Dingtalk_20240724140535.jpg)。

填充的点的Y轴值为前一个点的值, 时间示例: [9:23, 9:27] => [9:23, 9:25, 9:27, 9:30]，更多，见[测试用例](./tests/echarts/fill.cy.ts)

- `calcYAxisRange, Key extends keyof T>(data: T[], key: Key, decimalPlaces = 2, splitNumber = 5): { max:number; min:number }`

计算echarts YAxis的max和min属性，以达到根据实际数据动态调整，使折线图的波动明显。且第一个点始终在Y轴中间位置，[效果图](https://raw.githubusercontent.com/mrdulin/pic-bucket-01/master/Dingtalk_20240724140535.jpg)

## 测试

运行全部组件测试

```bash
npm run cy:component:all
```

运行单个组件测试

```bash
npm run cy:component -- tests/date.cy.ts
```

运行E2E测试

将`src`通过`tsc` build到`public/dist`目录

```bash
npm run build:public
```

启动一个Web服务器来访问`public/index.html`文件，`dist`目录的脚本可以通过``引入

```bash
npm run serve
```

最后启动cypress GUI客户端，选择E2E测试

```bash
npm run cy:open
```

## 发布

更新package version:

```bash
npm version or ...
```

构建:

```bash
npm build
```

发布：

```bash
npm publish --access public
```

网络原因导致连接registry服务器超时,可指定proxy

```bash
npm --proxy http://127.0.0.1:7890 publish
```

镜像站查询版本与手动同步:

[npm镜像站](https://npmmirror.com/package/@d-matrix/utils)

通过`git log`命令获取changelogs，用于填写GitHub Release内容:

```bash
git log --oneline --decorate
```

## 注意事项