@allkit/shared 0.0.1 → 0.0.3

package/skills/references/is.md

@@ -0,0 +1,415 @@
+# is
+
+类型判断工具函数 / Type checking utility functions
+
+## Overview / 概述
+
+提供一系列类型判断函数，用于在运行时检测变量的类型。Provide a series of type checking functions for runtime type detection.
+
+## Functions
+
+### isDef
+
+判断不是 undefined / Check if not undefined
+
+```ts
+function isDef<T>(val?: T): val is T
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `val` | `T \| undefined` | 要检测的值 |
+
+**Returns / 返回值**
+
+- `val is T`: 如果值不是 undefined，返回 true
+
+**Example / 示例**
+
+```ts
+isDef('test')     // true
+isDef(undefined)   // false
+isDef(null)       // true (null is not undefined)
+```
+
+---
+
+### isUnDef
+
+判断是 undefined / Check if undefined
+
+```ts
+function isUnDef<T>(val?: T): val is T
+```
+
+**Example / 示例**
+
+```ts
+isUnDef(undefined) // true
+isUnDef('test')   // false
+```
+
+---
+
+### isObject
+
+判断是 Object（含数组、Map）/ Check if is Object (includes Array, Map)
+
+```ts
+function isObject(val: any): val is Record<any, any>
+```
+
+**Example / 示例**
+
+```ts
+isObject({})           // true
+isObject([])           // true
+isObject(new Map())    // true
+isObject(null)         // false
+isObject('string')     // false
+```
+
+---
+
+### isPlainObject
+
+判断是原始 Object（不含数组）/ Check if is plain Object
+
+```ts
+function isPlainObject(val: unknown): val is Record<string, unknown>
+```
+
+**Example / 示例**
+
+```ts
+isPlainObject({})           // true
+isPlainObject({ a: 1 })     // true
+isPlainObject([])           // false
+isPlainObject(new Map())    // false
+```
+
+---
+
+### isEmpty
+
+判断是空（含空数组、空对象、空 Map）/ Check if is empty
+
+```ts
+function isEmpty<T>(val: T): val is T
+```
+
+**Example / 示例**
+
+```ts
+isEmpty([])              // true
+isEmpty({})              // true
+isEmpty(new Map())       // true
+isEmpty(new Set())       // true
+isEmpty('')              // true
+isEmpty([1, 2])         // false
+isEmpty({ a: 1 })       // false
+```
+
+---
+
+### isEmptyValue
+
+检测是否空值（空 string/undefined/null）/ Check if is empty value
+
+```ts
+function isEmptyValue(val: string | number | null | undefined): boolean
+```
+
+**Example / 示例**
+
+```ts
+isEmptyValue('')        // true
+isEmptyValue(null)      // true
+isEmptyValue(undefined) // true
+isEmptyValue('test')   // false
+isEmptyValue(0)        // false
+```
+
+---
+
+### isDate
+
+判断是日期对象 / Check if is Date object
+
+```ts
+function isDate(val: unknown): val is Date
+```
+
+**Example / 示例**
+
+```ts
+isDate(new Date())     // true
+isDate('2024-01-01')  // false
+isDate(Date.now())    // false
+```
+
+---
+
+### isNullOrUnDef
+
+判断是 null 或 undefined / Check if is null or undefined
+
+```ts
+function isNullOrUnDef(val: unknown): val is null | undefined
+```
+
+**Example / 示例**
+
+```ts
+isNullOrUnDef(null)       // true
+isNullOrUnDef(undefined)  // true
+isNullOrUnDef('')         // false
+isNullOrUnDef(0)          // false
+```
+
+---
+
+### isNumber
+
+是否是 number / Check if is number
+
+```ts
+function isNumber(val: unknown): val is number
+```
+
+**Example / 示例**
+
+```ts
+isNumber(123)      // true
+isNumber('123')    // false
+isNumber(NaN)      // true
+isNumber(Infinity) // true
+```
+
+---
+
+### isInteger
+
+判断是否为整数（支持负数）/ Check if is integer
+
+```ts
+function isInteger(val: unknown): boolean
+```
+
+**Example / 示例**
+
+```ts
+isInteger(123)       // true
+isInteger('123')      // true
+isInteger(-456)       // true
+isInteger('3.14')     // false
+isInteger(3.14)       // false
+isInteger('')         // false
+```
+
+---
+
+### isNumeric
+
+判断是否为数值（整数或小数）/ Check if is numeric
+
+```ts
+function isNumeric(val: unknown): boolean
+```
+
+**Example / 示例**
+
+```ts
+isNumeric(123)      // true
+isNumeric('123')    // true
+isNumeric('3.14')   // true
+isNumeric(-456.78)  // true
+isNumeric('abc')    // false
+```
+
+---
+
+### isPromise
+
+是否是 Promise / Check if is Promise
+
+```ts
+function isPromise<T>(val: any): val is Promise<T>
+```
+
+**Example / 示例**
+
+```ts
+isPromise(Promise.resolve())  // true
+isPromise(async () => {})     // true
+isPromise({ then: () => {} }) // true (duck typing)
+isPromise('test')             // false
+```
+
+---
+
+### isFunction
+
+是否是函数 / Check if is function
+
+```ts
+function isFunction(val: unknown): val is Function
+```
+
+**Example /示例**
+
+```ts
+isFunction(() => {})    // true
+isFunction(class {})    // true
+isFunction(function(){})// true
+isFunction('test')      // false
+```
+
+---
+
+### isArray
+
+是否是数组 / Check if is array
+
+```ts
+function isArray(val: any): val is Array<any>
+```
+
+**Example / 示例**
+
+```ts
+isArray([])           // true
+isArray(new Array())  // true
+isArray({ length: 0 })// false
+isArray('test')       // false
+```
+
+---
+
+### isUrl
+
+是否是 URL / Check if is URL
+
+```ts
+function isUrl(path: string): boolean
+```
+
+**Parameters / 参数**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `path` | `string` | 要检测的字符串 |
+
+**Returns / 返回值**
+
+- `boolean`: 如果是有效的 URL 返回 true
+
+**Example / 示例**
+
+```ts
+isUrl('http://www.baidu.com')  // true
+isUrl('https://example.com')   // true
+isUrl('/api/user')             // true
+isUrl('not-a-url')             // false
+```
+
+---
+
+### isWindow
+
+是否是 Window / Check if is Window
+
+```ts
+function isWindow(val: any): val is Window
+```
+
+**Example / 示例**
+
+```ts
+isWindow(window)     // true (in browser)
+isWindow(document)   // false
+isWindow({})         // false
+```
+
+---
+
+### isMap
+
+是否是 Map / Check if is Map
+
+```ts
+function isMap(val: unknown): val is Map<any, any>
+```
+
+**Example / 示例**
+
+```ts
+isMap(new Map())     // true
+isMap({})            // false
+isMap([])            // false
+```
+
+---
+
+### isRegExp
+
+是否是正则 / Check if is RegExp
+
+```ts
+function isRegExp(val: unknown): val is RegExp
+```
+
+**Example / 示例**
+
+```ts
+isRegExp(/test/)           // true
+isRegExp(new RegExp('test')) // true
+isRegExp('test')           // false
+```
+
+---
+
+## Use Cases / 使用场景
+
+### 表单验证 / Form Validation
+
+```ts
+function validateValue(value: unknown) {
+  if (isEmptyValue(value)) {
+    return 'Value is required'
+  }
+  if (!isString(value) && !isNumber(value)) {
+    return 'Invalid value type'
+  }
+  return null
+}
+```
+
+### 数据处理 / Data Processing
+
+```ts
+function processData(data: unknown) {
+  if (isPlainObject(data)) {
+    // 处理普通对象
+  } else if (isArray(data)) {
+    // 处理数组
+  } else if (isDate(data)) {
+    // 处理日期
+  }
+}
+```
+
+### 类型守卫 / Type Guards
+
+```ts
+function handleValue(value: string | number | Date) {
+  if (isDate(value)) {
+    // TypeScript knows value is Date here
+    return value.getTime()
+  }
+  // TypeScript knows value is string | number here
+  return value
+}
+```