# @apexo/type 中文文档

规范地址：https://npmcn.com/package/%40apexo/type/

版本：0\.0\.3
npm 元数据更新时间：2025-11-30T04:25:15.028Z
中文译文更新时间：2026-11-06T16:09:28.189Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40apexo/type
原文对照：https://npmcn.com/package/%40apexo/type/?lang=original
项目主页：https://github.com/bytetologic/apexo.js/tree/main#readme
源码仓库：https://github.com/bytetologic/apexo.js#main

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：53.7 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-11-29T17:25:25.137Z
- 最新版本发布：2025-11-30T04:25:14.804Z
- 近 30 天下载量：2772（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

@apexo/type是一个小型的零依赖性库,可以让你在JavaScript和TypeScript中轻松可靠的类型检查.

## 安装

```sh
npm install @apexo/type
```

也可以使用：`pnpm add @apexo/type`、`yarn add @apexo/type`、`bun add @apexo/type`

## README

# @ apexo/ 类型

花了几个小时写验证代码, 只是为了意识到你在每一个功能中都做了同样的事情? 或者你让AI为你生产 现在你的捆绑被重复的锅炉板胀了?

**@ apexo/ 类型** 是一个小型的库 , 用来检查您的类型 。 你为什么需要它? 因为JavaScript的类型检查很奇怪:

-   `typeof null` 说这是个 `"object"` (但事实并非如此)
-   `typeof []` 说这是个 `"object"` (阵列需要不同的检查)
-   `typeof NaN` 说这是个 `"number"` (虽然NaN的意思是"不是数字")
-   无法检查对象中的空值或循环

你可以自己写所有的支票:

```javascript
function processUser(data) {
    if (data === null || data === undefined) {
        throw new Error('Data is required');
    }
    if (typeof data !== 'object' || Array.isArray(data)) {
        throw new Error('Data must be an object');
    }
    if (typeof data.name !== 'string' || data.name.trim() === '') {
        throw new Error('Name must be a non-empty string');
    }
    if (typeof data.age !== 'number' || isNaN(data.age) || data.age < 0) {
        throw new Error('Age must be a positive number');
    }
    // Finally, your actual logic...
}
```

或者你该用 **@ apexo/ 类型** 然后用三行来完成:

```javascript
import { isObject, isNotEmpty, isPositive } from '@apexo/type';

function processUser(data) {
    if (!isObject(data)) throw new Error('Data must be an object');
    if (!isNotEmpty(data.name)) throw new Error('Name is required');
    if (!isPositive(data.age)) throw new Error('Age must be positive');
    // Your actual logic, front and center
}
```

## 我为什么要这么做?

Java 脚本 `typeof` 在许多现实世界的情景中,操作员不足:

-   `typeof null === 'object'` (没有! )
-   `typeof [] === 'object'` (阵列需要特殊处理)
-   没有办法检查 `NaN`,空值,或验证复杂的结构

**@ apexo/ 类型** 通过提供:

-   **运行时间安全**: 在处理前验证APIs、用户输入或任何不可信来源的数据
-   **类型脚本集成**:在代码中自动输入守护器的狭义类型,给您完整的IntelliSense支持
-   **可读代码**: 替换动词检查, 如 `if (value !== null && value !== undefined && typeof value === 'string' && value.trim() !== '')` 与 `if (isNotEmpty(value))`
-   **边际案件处理**: 正确处理棘手的 JavaScript 边缘大小写(`null`, (中文(简体) ), `undefined`, (中文(简体) ), `NaN`, (中文(简体) ), `Symbol`, (中文(简体) ), `BigInt`,循环参考)

## 它有多小吗?

-   **~12KB 变焦** (整个图书馆)
-   **树能震动**:只有捆绑你使用的东西。 导入 `isString`您的捆绑将不包括日期验证器或循环参考检测
-   **零依赖关系**: 外部软件包中无 bloat
-   **无副作用**: 标记为 `"sideEffects": false` 以便摇动最优的树木

## 我怎么安装?

```bash
npm install @apexo/type
```

或与您的首选软件包管理器 :

```bash
pnpm add @apexo/type
yarn add @apexo/type
```

## 我该怎么用?

### 基本类型警卫

类型守护符返回布尔并自动缩小类型Script类型 :

```typescript
import { isString, isNumber, isArray } from '@apexo/type';

function process(input: unknown) {
    if (isString(input)) {
        // TypeScript knows input is string here
        console.log(input.toUpperCase());
    }
    
    if (isArray(input)) {
        // TypeScript knows input is any[] here
        console.log(input.length);
    }
}
```

### 验证值

除类型检查外, 验证特定属性 :

```typescript
import { isPositive, isEven, isFutureDate, isEmpty } from '@apexo/type';

isPositive(10);  // true
isEven(7);       // false
isEmpty('   ');  // true
isFutureDate(new Date('2050-01-01')); // true
```

### 高级公用事业

```typescript
import { whatTypeOf, hasCircularReference } from '@apexo/type';

whatTypeOf(null);        // "null" (not "object"!)
whatTypeOf([]);          // "array"
whatTypeOf(new Date());  // "date"

const obj: any = {};
obj.self = obj;
hasCircularReference(obj); // { hasCircular: true, path: "root.self -> root" }
```

## 正在装入库

### ES模块(建议)

```typescript
import { isString, isObject } from '@apexo/type';
```

### 常见JS

```javascript
const { isString, isObject } = require('@apexo/type');
```

### 类型脚本

库以TypeScript书写并包含出框的完整类型定义.

## 是否有类型脚本定义 ?

没错! 图书馆是 **类型脚本第一** 包括完整的类型定义。 所有类型守护人员都使用TypeScript类型上游语法(`value is Type`),提供自动类型缩小:

```typescript
function example(input: unknown) {
    if (isString(input)) {
        // input is automatically typed as 'string'
        input.toLowerCase(); // ✅ TypeScript knows this is safe
    }
}
```

## 我能用到哪里来?

**JavaScript 运行的地方 :**

-   ✅ **节点.js** (v14+) (中文(简体) )
-   ✅ **浏览器** (现代浏览器, IE11+ 有多填充)
-   ✅ **德诺**
-   ✅ **阿宝**
-   ✅ **边缘函数** (Vercel, Cloudflare工人等)
-   ✅ **原生反应**

库有零依赖性,只使用标准的JavaScript特性,使其普遍兼容.

* * *

## API 参考

### 初级

-   `isString(value)` - 检查值是否为字符串
-   `isNumber(value)` - 检查值是否是一个数字(而不是NaN)
-   `isNumberStr(value)` - 检查值是数字还是数字字符串
-   `isBoolean(value)` - 检查值是否为布尔值
-   `isNil(value)` - 检查值是否为 `null` 或者说 `undefined`
-   `isNull(value)` - 检查值是否为 `null`
-   `isUndefined(value)` - 检查值是否为 `undefined`
-   `isBigInt(value)` - 检查值是否为 BigInt
-   `isSymbol(value)` - 检查值是否为符号
-   `isPrimitive(value)` - 检查值是否为原始类型

### 对象结构( R)

-   `isObject(value)` - 检查值是否为非无效对象(不包括数组)
-   `isPlainObject(value)` - 检查值是否为普通对象(`{}` 或者说 `new Object()`(中文(简体) )
-   `isArray(value)` - 检查值是否为数组
-   `isArrayLike(value)` - 检查值是否类似数组(有长度属性)
-   `isFunction(value)` - 检查值是否为函数
-   `isClass(value)` - 检查值是否为类构建器
-   `isIterable(value)` - 检查值是否可以持续
-   `isAsyncIterable(value)` - 检查值是否可同步
-   `isGeneratorFunction(value)` - 检查值是否为生成函数
-   `isWindow(value)` - 检查是否为窗口对象

### 高级类型

-   `isPromise(value)` - 检查值是否为承诺
-   `isMap(value)` - 检查值是否是地图
-   `isSet(value)` - 检查值是否为集
-   `isWeakMap(value)` - 检查值是否为弱映射
-   `isWeakSet(value)` - 检查值是否为弱点集
-   `isRegExp(value)` - 检查值是否为RegExp
-   `isDate(value)` - 检查值是否为日期对象
-   `isError(value)` - 检查值是否为错误
-   `isTypeError(value)` - 检查值是否为类型错误
-   `isReferenceError(value)` - 检查值是否为引用错误
-   `isSyntaxError(value)` - 检查值是否为语法错误
-   `isRangeError(value)` - 检查值是否为范围错误
-   `isURIError(value)` - 检查值是否为 URIEROR
-   `isEvalError(value)` - 检查值是否为 EvalError
-   `isAggregateError(value)` - 检查值是否为聚合错误
-   `isBuffer(value)` - 检查值是缓冲(Node.js)还是ArrayBuffer/View
-   `isJson(value)` - 检查值是否为有效的 JSON 字符串

### 空检查

-   `isEmpty(value)` - 检查值是否为空(无效、未定义、空字符串/阵列/对象)
-   `isNotEmpty(value)` - 逆向的 `isEmpty`
-   `isEmptyStr(value)` - 检查值是否为空字符串(或仅为白空)
-   `isEmptyArr(value)` - 检查值是否为空数组
-   `isEmptyObj(value)` - 检查值是否为空对象

### 数量 校验器

-   `isFiniteNumber(value)` - 检查值是否为有限数字
-   `isInteger(value)` - 检查值是否为整数
-   `isFloat(value)` - 检查值是否为浮点
-   `isSafeInteger(value)` - 检查值是否是一个安全的整数
-   `isPositive(value)` - 检查值是否 > 0
-   `isNegative(value)` - 检查值是否 < 0
-   `isZero(value)` - 检查值是否为 0
-   `isEven(value)` - 检查值是否均匀
-   `isOdd(value)` - 检查值是否为奇数
-   `isPrime(value)` - 检查值是否为质数
-   `isInRange(value, min, max)` - 检查值是否在 \[min, 最大\]
-   `isBetween(value, min, max)` - 检查值是否严格在(最小值,最大值)之间

### 日期验证器

-   `isValidDate(value)` - 检查值是否为有效日期( 非无效日期)
-   `isStrictDate(value)` - 别提了 `isValidDate`
-   `isFutureDate(date)` - 检查日期是否在未来
-   `isPastDate(date)` - 检查日期是否过去
-   `isToday(date)` - 检查日期是不是今天
-   `isSameDay(a, b)` - 检查两个日期是否在同一天
-   `isLeapYear(year)` - 检查年份是否为一跃而起
-   `isISODateString(value)` - 检查值是否为 ISO 8601 日期字符串
-   `isValidISODateOnly(value)` - 检查值是否为有效的 YYY- MM- DD 字符串
-   `isValidTimeString(value)` - 检查值是否是一个有效的时间字符串( HH: mm)
-   `isDateTimeString(value)` - 检查值是否是一个有效的日期时间字符串
-   `isTimestamp(value)` - 检查值是否是一个有效的时间戳
-   `isDateLike(value)` - 检查是否可以转换为有效的日期
-   `isForwardTime(date, offset?)` - 检查日期是否在日期之后+抵消
-   `isBackwardTime(date, offset?)` - 检查日期是否在现在之前 - 页:1

### 公用事业

-   `whatTypeOf(value)` - 返回一个特定的类型字符串(例如“阵列”、“日期”、“无”)
-   `hasCircularReference(obj)` - 探测物体/阵列中的循环参考

* * *

## 建筑

图书馆的组织效率最高:

```
src/
├── guards/          # Type guards (value is Type)
│   ├── primitives.ts   # Basic types
│   ├── objects.ts      # Object structures
│   ├── advanced.ts     # Promises, Maps, Sets
│   ├── errors.ts       # Error types
│   └── empty.ts        # Empty checks
├── validators/      # Value validators (boolean)
│   ├── number.ts       # Numeric validations
│   └── date.ts         # Date validations
└── utils/           # Helper utilities
    ├── type-of.ts      # Enhanced typeof
    └── circular-ref.ts # Circular reference detection
```

这种结构可以让捆绑者在不使用时去掉所有类别的检查.

* * *

## 许可证

[麻省理工学院](https://github.com/bytetologic/apexo.js?tab=MIT-1-ov-file)

## 仓库

[https://github.com/bytetologic/apexo.js/tree/main/packages/type 页面存档备份,存于互联网档案馆](https://github.com/bytetologic/apexo.js/tree/main/packages/type)

## 常见问题

### @apexo/type 是什么？

@apexo/type是一个小型的零依赖性库,可以让你在JavaScript和TypeScript中轻松可靠的类型检查\.

### 如何安装 @apexo/type？

在项目目录运行 npm install @apexo/type，或使用 pnpm add / yarn add / bun add。

### @apexo/type 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @apexo/type 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @apexo/type 可以商用吗？

@apexo/type 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @apexo/type 的下载量有多少？

根据 npm 官方下载统计，@apexo/type 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,772 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @apexo/type 还在维护吗？

最新版本 0\.0\.3 发布于 2025/11/30（11 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/11/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。