# @mdsfe/toolkit

[English](./README.md) | [简体中文](./README.zh-CN.md)

`@mdsfe/toolkit` 是一个轻量、模块化、面向浏览器场景的 TypeScript 工具库。它参考了 `epfe-utils` 中实用的分层方式，但去除了业务耦合，使其更适合公开协作、独立维护，并最终作为 npm 公共包发布。

## 为什么要开源化

- 把可复用能力沉淀成稳定底座，而不是零散内部工具集合
- 降低接入成本，让文档、导出边界和包元信息更清晰
- 方便外部协作、问题反馈、版本演进和 npm 分发
- 让业务模块与通用工具彻底解耦

## 特性

- 运行时零依赖
- TypeScript 优先，默认生成类型声明
- 同时支持函数式 API 和 `*Utils` 静态类封装
- 支持按子路径导入，便于 tree-shaking
- 对浏览器项目友好，也可安全导入到非浏览器环境

## 模块划分

```text
src/
  browser/     查询参数解析、存储封装、运行时检测
  format/      日期、字节、数字、金额格式化
  function/    debounce、throttle、memoize、retry、compose、pipe、curry
  object/      深拷贝、isEmpty、pick、omit
  string/      HTML 转义、关键词高亮、空白压缩
  types/       公共类型定义
  validation/  基于规则的校验工具
```

## 安装

```bash
npm install @mdsfe/toolkit
```

## 快速开始

```ts
import {
  debounce,
  deepClone,
  formatDate,
  parseQuery,
  validate,
  required,
  email,
} from '@mdsfe/toolkit';

const profile = deepClone({
  name: 'Alice',
  email: 'alice@example.com',
});

const query = parseQuery('https://example.com?a=1&a=2&b=3');
const rules = [required('name'), email('email')];
const result = validate(profile, rules);

const log = debounce((value: string) => console.log(value), 200);

console.log(formatDate(Date.now(), 'YYYY-MM-DD HH:mm:ss'));
console.log(query, result.isValid);
log('toolkit');
```

## 类式调用示例

```ts
import {
  BrowserUtils,
  CommonUtils,
  FormatUtils,
  FunctionUtils,
  ValidationUtils,
} from '@mdsfe/toolkit';

const cloned = CommonUtils.deepClone({ id: 1 });
const date = FormatUtils.formatDate(Date.now(), 'YYYY-MM-DD');
const query = BrowserUtils.getUrlAllParams('https://example.com?a=1');
const handler = FunctionUtils.debounce(() => console.log('run'), 150);
const result = ValidationUtils.validate(
  { name: 'toolkit' },
  [ValidationUtils.required('name')]
);

console.log(cloned, date, query, result.isValid);
handler();
```

## 子路径导入

```ts
import { parseQuery } from '@mdsfe/toolkit/browser';
import { debounce, retry } from '@mdsfe/toolkit/function';
import { deepClone, isEmpty } from '@mdsfe/toolkit/object';
import { compactWhitespace, highlightKeyword } from '@mdsfe/toolkit/string';
import { formatBytes, formatCurrency } from '@mdsfe/toolkit/format';
import { validate, required } from '@mdsfe/toolkit/validation';
```

## 兼容性辅助函数

为了更平滑地从 `epfe-utils` 迁移，当前保留了若干熟悉但实现更稳妥的工具：

- `getUrlAllParams`
- `getUrlQuery`
- `getSession`
- `setSession`
- `getUserOsInfo`
- `isImageUrl`
- `paddingZero`

## 本地开发

```bash
npm install
npm run build
npm run typecheck
npm run release:check
```

## 规划

- 保持公共 API 小而稳
- 在正式大范围 npm 分发前补齐测试
- 在 `mdsfe` scope 发布权限准备好后发布 `@mdsfe/toolkit`
- 将业务适配层继续留在包外维护

## 开源协作文档

- [English README](./README.md)
- [贡献指南](./CONTRIBUTING.md)
- [行为准则](./CODE_OF_CONDUCT.md)
- [安全策略](./SECURITY.md)
- [变更记录](./CHANGELOG.md)
- [许可证](./LICENSE)