npm package: @lyohhhh/utils
Description: utils
Author: lyohhhh
Latest version: 0.2.21

# @lyohhhh/utils

轻量的 TypeScript 实用函数集合，支持 ESM/CJS 与类型声明。

安装命令（任选其一）：

```bash
# pnpm
pnpm add @lyohhhh/utils -S

# npm
npm install @lyohhhh/utils --save

# yarn
yarn add @lyohhhh/utils

# bun
bun add @lyohhhh/utils
```

## 快速上手

```ts
// ESM
import { debounce, isEmpty } from '@lyohhhh/utils';

// CJS
// const { debounce, isEmpty } = require('@lyohhhh/utils');

const fn = debounce(() => console.log('hi'), 300);
console.log(isEmpty('')); // true
```

## API

### 缓存 cache

提供通用缓存与 Web 缓存（localStorage）封装，支持过期时间。

```ts
import { createCache, createWebCache } from '@lyohhhh/utils';

// Web（浏览器）使用
const webCache = createWebCache('app', 1000); // key 前缀 + 过期毫秒
webCache.set('token', 'abc');
webCache.get('token'); // 'abc' 或过期后为 null
webCache.remove('token');
webCache.clear(); // 清空所有（委托给 localStorage.clear）

// 自定义存储实现（Node/服务端）
const store = new Map<string, string>();
const cache = createCache({
  key: 'ns',
  expire: 500,
  getItem: store.has,
  setItem: store.set,
  removeItem: store.delete,
  clear: store.clear,
});
```

### 插件 plugins

```ts
import { debounce, throttle } from '@lyohhhh/utils';

// 防抖（默认 leading=true）
const onResize = debounce(() => console.log('resize'), 300, true);

// 节流
const onScroll = throttle(() => console.log('scroll'), 200);
```

### HTTP 客户端 http

基于 axios 的轻封装，提供默认配置、拦截器钩子、取消重复请求、失败自动重试、URL 前缀拼接等能力。

```ts
import createAxios, { Axios } from '@lyohhhh/utils';

// 创建实例（可覆盖默认项）
const request = createAxios({
  baseURL: 'https://api.example.com',
  timeout: 10000,
  requestOptions: {
    urlPrefix: '/v1',
    isReturnDefaultResponse: true, // 如需拿到完整 AxiosResponse
  },
  axiosHooks: {
    requestInterceptorsHook(config) {
      // 注入 token
      config.headers = {
        ...config.headers,
        Authorization: 'Bearer token',
      };
      return config;
    },
    responseInterceptorsHook(response) {
      // 可在此做统一错误码处理/数据提取
      return response;
    },
  },
});

// 发起请求
async function demo() {
  const res = await request.get({ url: '/users', params: { page: 1 } });
  console.log(res.data);
}
```

可用配置（节选）：

- `requestOptions.urlPrefix`: 接口前缀拼接（如 `/api`、`/v1`）
- `requestOptions.ignoreCancelToken`: 是否忽略重复请求合并/取消
- `requestOptions.isOpenRetry` / `retryCount`: 网络失败自动重试
- `axiosHooks.*`: 请求/响应拦截、错误处理钩子

### 函数工具 func

若干常用函数工具：对象序列化、深合并、深拷贝、类型守卫等。

```ts
import {
  objectToQuery,
  merge,
  deepClone,
  isObject,
  isFunction,
} from '@lyohhhh/utils';

// 对象转查询串（会过滤 null/undefined/''）
objectToQuery({ a: 1, b: undefined, c: '', d: 0 }); // 'a=1&d=0'

// 深度合并（对象递归、数组覆盖、非对象忽略）
const a = { x: 1, y: { z: 2, arr: [1, 2] } };
const b = { y: { z: 3, arr: [3] }, k: 9 };
merge(a, b); // { x:1, y:{ z:3, arr:[3] }, k:9 }

// 深拷贝（含 Date/Array/循环引用）
const obj: any = { a: 1, b: { c: [1, 2] } };
obj.self = obj;
const cloned = deepClone(obj);

// 类型守卫
isObject({}); // true
isFunction(() => {}); // true
```

### 校验 validate

```ts
import {
  isExternal,
  isLinkHttp,
  isLinkTel,
  isLinkMailto,
  isEmpty,
  isValidPassword,
  isValidTransactionPassword,
} from '@lyohhhh/utils';

isExternal('mailto:test@example.com'); // true
isLinkHttp('https://a.com'); // true
isLinkTel('tel:123456'); // true
isLinkMailto('mailto:test@example.com'); // true
isEmpty(''); // true
isValidPassword('Abc123'); // true（6-16 位，至少两类字符，不能含中文/空白）
isValidTransactionPassword('123456'); // true（6 位纯数字）
```

## 导出与类型

- ESM：`dist/index.mjs`，CJS：`dist/index.cjs`；类型：`dist/index.d.ts`
- 支持按需导入：`import { throttle } from '@lyohhhh/utils'`