feat: 已实现方法增加jsdoc注释 (#53)

* feat: 新增函数的jsdoc注释

* fix: 修复isPromise可能带来的异常风险

* perf: 优化isPromise的实现方式

package.json

@@ -28,10 +28,10 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "docs": "pnpm -F xparcai-utils-docs run docs:dev",
-    "docs:build": "pnpm -F xparcai-utils-docs run docs:build",
     "create": "esno scripts/create-subpackage.ts",
     "build": "pnpm -r --filter=./packages/* run build",
+    "docs": "pnpm -F xparcai-utils-docs run docs:dev",
+    "docs:build": "pnpm -F xparcai-utils-docs run docs:build",
     "release": "pnpm run build && pnpm run test run && run-s release:*",
     "release:bummp": "bumpp -r",
     "release:publish": "pnpm -r --filter=./packages/* publish",

packages/is/src/isArray.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是array类型
+ * @param data 某个数据
+ * @returns 是否是array类型
+ */
 export function isArray<T>(data: unknown): data is T[] {
   return isType(data, 'Array')
 }

packages/is/src/isBigInt.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是bigint类型
+ * @param data 某个数据
+ * @returns 是否是bigint类型
+ */
 export function isBigInt(data: unknown): data is bigint {
   return isType(data, 'BigInt')
 }

packages/is/src/isBoolean.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是boolean类型
+ * @param data 某个数据
+ * @returns 是否是boolean类型
+ */
 export function isBoolean(data: unknown): data is boolean {
   return isType(data, 'Boolean')
 }

packages/is/src/isDate.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是Date类型
+ * @param data 某个数据
+ * @returns 是否是Date类型
+ */
 export function isDate(data: unknown): data is Date {
   return isType(data, 'Date')
 }

packages/is/src/isFalse.ts

@@ -1,3 +1,8 @@
+/**
+ * 某个数据是否为false
+ * @param data 某个数据
+ * @returns 是否为false
+ */
 export function isFalse(data: unknown): data is false {
   return data === false
 }

packages/is/src/isFunction.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
-export function isFunction<T extends Function>(data: unknown): data is T {
+/**
+ * 某个数据/方法是否是function类型
+ * @param data 某个数据/方法
+ * @returns 是否是function类型
+ */
+export function isFunction<T>(data: unknown): data is T extends Function ? T : Function {
   return isType(data, 'Function')
 }

packages/is/src/isMap.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是Map类型
+ * @param data 某个数据
+ * @returns 是否是Map类型
+ */
 export function isMap<K, V>(data: unknown): data is Map<K, V> {
   return isType(data, 'Map')
 }

packages/is/src/isNaN.ts

@@ -1,3 +1,8 @@
+/**
+ * 某个数据是否是NaN
+ * @param data 某个数据
+ * @returns 是否是NaN
+ */
 export function isNaN(data: unknown): data is number {
   return Number.isNaN(data)
 }

packages/is/src/isNull.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是null类型
+ * @param data 某个数据
+ * @returns 是否是null类型
+ */
 export function isNull(data: unknown): data is null {
   return isType(data, 'Null')
 }

packages/is/src/isNumber.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是number类型
+ * @param data 某个数据
+ * @returns 是否是number类型
+ */
 export function isNumber(data: unknown): data is number {
   return isType(data, 'Number')
 }

packages/is/src/isObject.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是object类型
+ * @param data 某个数据
+ * @returns 是否是object类型
+ */
 export function isObject<T>(data: unknown): data is T {
   return isType(data, 'Object')
 }

packages/is/src/isPromise.ts

@@ -1,9 +1,15 @@
 import { isFunction } from './isFunction'
+import { isObject } from './isObject'
 
-export function isPromise<T = any>(data: unknown): data is Promise<T> {
+/**
+ * 某个数据/方法是否是Promise
+ * @param data 某个数据/方法
+ * @returns 是否是Promise
+ */
+export function isPromise<T>(data: unknown): data is Promise<T> {
   return (
-    !!data
-    && isFunction((data as any).then)
-    && isFunction((data as any).catch)
+    isObject<{ then: Function, catch: Function }>(data)
+    && isFunction(data.then)
+    && isFunction(data.catch)
   )
 }

packages/is/src/isRegExp.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是RegExp类型
+ * @param data 某个数据
+ * @returns 是否是RegExp类型
+ */
 export function isRegExp(data: unknown): data is RegExp {
   return isType(data, 'RegExp')
 }

packages/is/src/isSet.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是Set类型
+ * @param data 某个数据
+ * @returns 是否是Set类型
+ */
 export function isSet<T>(data: unknown): data is Set<T> {
   return isType(data, 'Set')
 }

packages/is/src/isString.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是string类型
+ * @param data 某个数据
+ * @returns 是否是string类型
+ */
 export function isString(data: unknown): data is string {
   return isType(data, 'String')
 }

packages/is/src/isSymbol.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是symbol类型
+ * @param data 某个数据
+ * @returns 是否是symbol类型
+ */
 export function isSymbol(data: unknown): data is symbol {
   return isType(data, 'Symbol')
 }

packages/is/src/isTrue.ts

@@ -1,3 +1,8 @@
+/**
+ * 某个数据是否为true
+ * @param data 某个数据
+ * @returns 是否为true
+ */
 export function isTrue(data: unknown): data is true {
   return data === true
 }

packages/is/src/isType.ts

@@ -20,6 +20,13 @@ type Types =
   | 'Error'
   | 'Math'
   | 'Argument'
+
+/**
+ * 某个数据是否符合某个类型
+ * @param data 某个数据
+ * @param type 某个类型
+ * @returns 是否符合某个类型
+ */
 export function isType(data: unknown, type: Types): boolean {
   return toRawType(data) === type
 }

packages/is/src/isUndefined.ts

@@ -1,5 +1,10 @@
 import { isType } from './isType'
 
+/**
+ * 某个数据是否是undefined类型
+ * @param data 某个数据
+ * @returns 是否是undefined类型
+ */
 export function isUndefined(data: unknown): data is undefined {
   return isType(data, 'Undefined')
 }

packages/object/src/deepCopy.ts

@@ -1,20 +1,23 @@
 import { isArray, isDate, isObject, isRegExp } from '@xparcai-utils/is'
 
 /**
- * @func deepCopy
- * @param {T} data 将要复制的对象
- * @returns {T} 复制后的对象
- * @desc 深拷贝对象
+ * 深拷贝某个数据
+ * @param {T} data 某个数据
+ * @returns {T} 拷贝后的数据
  */
 export function deepCopy<T>(data: T): T
+
 /**
- * @func deepCopy
- * @param {T} data 将要复制的对象
- * @param {H extends object} [hash]  记录已复制过对象的哈希值
- * @returns {T} 复制后的对象
- * @desc 深拷贝对象
+ * 深拷贝某个数据
+ * @param {T} data 某个数据
+ * @param {H extends object} [hash] 解决循环依赖传入的记录对象
+ * @returns {T} 拷贝后的数据
  */
 export function deepCopy<T, H extends object>(data: T, hash?: H): T
+
+/**
+ * 深拷贝实现
+ */
 export function deepCopy<T>(data: T, hash: any = new WeakMap()): T {
   // 日期对象直接返回一个新的日期对象
   if (isDate(data)) {

packages/string/index.ts

@@ -1 +1 @@
-export * from './src'
+export * from './src/toSlash'

packages/string/src/toSlash.ts

@@ -0,0 +1,8 @@
+/**
+ * 反 \ 转换为 /
+ * @param str 字符串
+ * @returns 转换后的字符串
+ */
+export function toSlash(str: string): string {
+  return str.replace(/\\/g, '/')
+}

packages/tool/__test__/toRawType.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { toRawType } from '../index'
+import { toRawType } from '..'
 
 describe('@xparcai-utils/tool', () => {
   it('toRawType', () => {

packages/tool/src/toRawType.ts

@@ -1,3 +1,8 @@
+/**
+ * 获取某个数据的原始类型
+ * @param data 某个数据
+ * @returns 原始类型
+ */
 export function toRawType(data: unknown): string {
   return Object.prototype.toString.call(data).slice(8, -1)
 }