@gitlon/validate 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,350 @@
+# @gitlon/validate
+
+常用表单与业务校验函数。全部函数为独立命名导出，返回 `boolean`，不生成错误文案。
+
+## 安装
+
+```bash
+pnpm add @gitlon/validate
+```
+
+也可安装聚合包：
+
+```bash
+pnpm add gitlon
+```
+
+## 导入
+
+直接使用子包：
+
+```ts
+import {
+  isBankCard,
+  isChinese,
+  isDate,
+  isEmail,
+  isEmpty,
+  isEnglish,
+  isIdCard,
+  isInteger,
+  isNumber,
+  isPassword,
+  isPhone,
+  isPositiveNumber,
+  isUrl,
+} from '@gitlon/validate'
+```
+
+通过主包使用：
+
+```ts
+import { isEmail, isPassword, isPhone } from 'gitlon'
+```
+
+## API 总览
+
+| 函数 | 校验内容 |
+| --- | --- |
+| `isEmpty` | 空值、空白字符串、空数组、无可枚举属性对象 |
+| `isNumber` | 有限数字或可转换为有限数字的值 |
+| `isInteger` | 整数或整数字符串 |
+| `isPositiveNumber` | 大于 0 的数字或数字字符串 |
+| `isEmail` | 常用邮箱格式 |
+| `isPhone` | 中国大陆 11 位手机号 |
+| `isUrl` | 绝对 HTTP/HTTPS URL |
+| `isIdCard` | 中国大陆 18 位身份证格式及校验码 |
+| `isBankCard` | 12～19 位银行卡号及 Luhn 校验码 |
+| `isDate` | JavaScript 可解析日期 |
+| `isChinese` | 仅连续中文字符 |
+| `isEnglish` | 仅连续英文字母 |
+| `isPassword` | 可配置长度和字符要求的密码 |
+
+所有函数签名均接收 `unknown`，便于直接校验表单值：
+
+```ts
+function isEmail(value: unknown): boolean
+```
+
+## 空值
+
+```ts
+isEmpty(null)       // true
+isEmpty(undefined)  // true
+isEmpty('')         // true
+isEmpty('   ')      // true
+isEmpty([])         // true
+isEmpty({})         // true
+
+isEmpty(0)          // false
+isEmpty(false)      // false
+isEmpty([0])        // false
+isEmpty({ id: 1 })  // false
+```
+
+```ts
+function isEmpty(value: unknown): boolean
+```
+
+规则：
+
+- 字符串先执行 `trim()`，再判断是否为空。
+- 数组按 `length` 判断。
+- 对象按自身可枚举属性数量判断。
+- `Date`、`Map`、`Set` 等没有自身可枚举属性的对象会被视为空；该函数主要面向字符串、数组和普通对象。
+
+## 数字
+
+```ts
+isNumber(12)        // true
+isNumber(-12.5)     // true
+isNumber('12.5')    // true
+isNumber('1e3')     // true
+
+isNumber('')        // false
+isNumber('   ')     // false
+isNumber('12px')    // false
+isNumber(NaN)       // false
+isNumber(Infinity)  // false
+```
+
+```ts
+function isNumber(value: unknown): boolean
+function isInteger(value: unknown): boolean
+function isPositiveNumber(value: unknown): boolean
+```
+
+整数和正数示例：
+
+```ts
+isInteger(12)       // true
+isInteger('12')     // true
+isInteger(12.5)     // false
+
+isPositiveNumber(1)    // true
+isPositiveNumber('1')  // true
+isPositiveNumber(0)    // false
+isPositiveNumber(-1)   // false
+```
+
+`isPositiveNumber` 使用严格大于 `0` 的规则。
+
+## 邮箱
+
+```ts
+isEmail('user@example.com') // true
+isEmail('user+tag@test.cn') // true
+
+isEmail('user@example')     // false
+isEmail('@example.com')     // false
+```
+
+```ts
+function isEmail(value: unknown): boolean
+```
+
+用于常见表单邮箱格式判断，不追求覆盖完整 RFC 邮箱语法。
+
+## 手机号
+
+```ts
+isPhone('13812345678')   // true
+isPhone('19812345678')   // true
+
+isPhone('138 1234 5678') // false
+isPhone('12812345678')   // false
+```
+
+```ts
+function isPhone(value: unknown): boolean
+```
+
+只接受未经分隔的中国大陆 11 位手机号，规则为 `1[3-9]xxxxxxxxx`。如需先清理和分组显示，使用 `@gitlon/format` 的 `formatPhone`。
+
+## URL
+
+```ts
+isUrl('https://example.com')      // true
+isUrl('http://localhost:3000/a')  // true
+
+isUrl('ftp://example.com')        // false
+isUrl('/users/1')                 // false
+isUrl('example.com')              // false
+```
+
+```ts
+function isUrl(value: unknown): boolean
+```
+
+只接受带 `http://` 或 `https://` 协议的绝对 URL。相对路径和其他协议返回 `false`。
+
+## 身份证
+
+```ts
+isIdCard('11010519491231002X') // true
+isIdCard('11010519491231002x') // true
+
+isIdCard('110105194912310021') // false
+isIdCard('110105491231002')    // false
+```
+
+```ts
+function isIdCard(value: unknown): boolean
+```
+
+校验：
+
+- 18 位格式；
+- 前 17 位为数字；
+- 末位为数字或 `X`；
+- 加权校验码。
+
+不校验行政区划、出生日期是否真实存在，也不代表身份证真实有效。
+
+## 银行卡
+
+```ts
+isBankCard('4111111111111111') // true
+isBankCard('5555555555554444') // true
+
+isBankCard('123456789012')     // false
+isBankCard('4111 1111 1111 1111') // false
+```
+
+```ts
+function isBankCard(value: unknown): boolean
+```
+
+只接受 12～19 位纯数字，并执行 Luhn 校验。不识别发卡行，也不保证卡号真实存在。含空格或横线的展示值需先清理。
+
+## 日期
+
+```ts
+isDate('2026-09-15')          // true
+isDate('2026-09-15T10:30:00') // true
+isDate(new Date())            // true
+isDate(Date.now())            // true
+
+isDate('not-a-date')          // false
+isDate(null)                  // false
+isDate('')                    // false
+```
+
+```ts
+function isDate(value: unknown): boolean
+```
+
+字符串和数字交给原生 `Date` 解析。解析规则及结果可能受运行环境和时区影响；需要严格格式校验时，应在业务层明确格式后再判断。
+
+## 中文与英文
+
+```ts
+isChinese('你好世界') // true
+isChinese('你好 world') // false
+isChinese('中文123') // false
+
+isEnglish('Hello')    // true
+isEnglish('hello world') // false
+isEnglish('hello123') // false
+```
+
+```ts
+function isChinese(value: unknown): boolean
+function isEnglish(value: unknown): boolean
+```
+
+- `isChinese` 只接受 `\u4e00`～`\u9fff` 范围内的连续字符。
+- `isEnglish` 只接受 `A-Z`、`a-z` 连续字母。
+- 空格、数字和标点均不通过。
+
+## 密码
+
+默认要求 6～20 位，同时包含字母和数字：
+
+```ts
+isPassword('Gitlon123') // true
+isPassword('123456')    // false：缺少字母
+isPassword('abcdef')    // false：缺少数字
+isPassword('abc')       // false：长度不足
+```
+
+自定义规则：
+
+```ts
+isPassword('Gitlon!123', {
+  minLength: 8,
+  maxLength: 30,
+  requireLetter: true,
+  requireNumber: true,
+  requireSpecial: true,
+})
+// true
+```
+
+```ts
+interface PasswordValidateOptions {
+  minLength?: number
+  maxLength?: number
+  requireLetter?: boolean
+  requireNumber?: boolean
+  requireSpecial?: boolean
+}
+
+function isPassword(value: unknown, options?: PasswordValidateOptions): boolean
+```
+
+| 选项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `minLength` | `6` | 最小长度 |
+| `maxLength` | `20` | 最大长度 |
+| `requireLetter` | `true` | 至少包含一个英文字母 |
+| `requireNumber` | `true` | 至少包含一个数字 |
+| `requireSpecial` | `false` | 至少包含一个非字母、非数字字符 |
+
+不限制特殊字符集合，也不检查弱密码、连续字符、泄露密码或业务账号信息。
+
+## 类型导入
+
+```ts
+import type { PasswordValidateOptions } from '@gitlon/validate'
+```
+
+使用聚合包时：
+
+```ts
+import type { PasswordValidateOptions } from 'gitlon'
+```
+
+## 表单示例
+
+```ts
+import { isEmail, isEmpty, isPassword, isPhone } from '@gitlon/validate'
+
+interface RegisterForm {
+  email: string
+  password: string
+  phone: string
+}
+
+function validateRegister(form: RegisterForm): Record<string, string> {
+  const errors: Record<string, string> = {}
+
+  if (isEmpty(form.email)) {
+    errors.email = '请输入邮箱'
+  } else if (!isEmail(form.email)) {
+    errors.email = '邮箱格式错误'
+  }
+
+  if (!isPhone(form.phone)) {
+    errors.phone = '手机号格式错误'
+  }
+
+  if (!isPassword(form.password)) {
+    errors.password = '密码需为 6～20 位且包含字母和数字'
+  }
+
+  return errors
+}
+```
+
+校验函数只判断当前值是否符合格式，不负责错误文案、异步请求、唯一性校验或真实性校验。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlon/validate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Common validation utilities for gitlon",
   "type": "module",
   "main": "./dist/index.cjs",