foreslash 0.2.4 → 0.3.1

package/lib/index.d.ts

@@ -169,7 +169,7 @@ type RetryOption = {
  * ```js
  * // 基本用法, 默认重试 3 次, 每次失败后会立即重新调用
  * const res = await retry(() => fetch(url, params))
- * // 重试 10 次
+ * // 重试 10 次, 最多会调用传入的函数 10 次
  * const res = await retry(() => fetch(url, params), { times: 10 })
  * // 延迟模式, 每次失败后会等待 1 秒再重新调用
  * const res = await retry(() => fetch(url, params), { delay: 1000 })
@@ -196,8 +196,7 @@ declare function retry<T>(asyncFunction: RetryFunction<T>, option?: RetryOption)
  */
 declare function sleep(time?: number): Promise<unknown>;
 
-type TryitResultType<Res, Err> = [undefined, Res] | [Err, undefined];
-type TryitResult<Res, Err extends Error> = Res extends Promise<infer R> ? Promise<TryitResultType<R, Err>> : TryitResultType<Res, Err>;
+type TryitResult<Res, Err> = [undefined, Res] | [Err, undefined];
 /**
  * 将一个函数处理为 `error-first` 的函数
  * @param fn 需要处理的函数, 可以是异步函数
@@ -207,11 +206,6 @@ type TryitResult<Res, Err extends Error> = Res extends Promise<infer R> ? Promis
  * 如果出现异常则 `result` 为 `undefined`, `error` 是原函数抛出的错误
  * @example
  * ```js
- * // Sync Function
- * const normalFn = () => { return 1 }
- * const errorFn = () => { throw new Error('1') }
- * tryit(normalFn)() // [undefined, 1]
- * tryit(errorFn)() // [Error('1'), undefined]
  * // Async Function
  * const normalAsyncFn = () => { return Promise.resolve(1) }
  * const errorAsyncFn = () => { return Promise.reject('1') }
@@ -220,6 +214,24 @@ type TryitResult<Res, Err extends Error> = Res extends Promise<infer R> ? Promis
  * ```
  * @version 0.2.0
  */
+declare function tryit<Args extends any[], Res, Err extends Error>(fn: (...args: Args) => Promise<Res>): (...args: Args) => Promise<TryitResult<Res, Err>>;
+/**
+ * 将一个函数处理为 `error-first` 的函数
+ * @param fn 需要处理的函数, 可以是异步函数
+ * @returns 处理过的函数, 调用后返回一个 `error-first` 的元组 `[error, result]`;\
+ * 如果原函数是异步函数, 则返回值会是 `Promise<[error, result]>`;\
+ * 如果运行正常则 `result` 是原函数的返回值, `error` 为 `undefined`;\
+ * 如果出现异常则 `result` 为 `undefined`, `error` 是原函数抛出的错误
+ * @example
+ * ```js
+ * // Sync Function
+ * const normalFn = () => { return 1 }
+ * const errorFn = () => { throw new Error('1') }
+ * tryit(normalFn)() // [undefined, 1]
+ * tryit(errorFn)() // [Error('1'), undefined]
+ * ```
+ * @version 0.2.0
+ */
 declare function tryit<Args extends any[], Res, Err extends Error>(fn: (...args: Args) => Res): (...args: Args) => TryitResult<Res, Err>;
 
 interface PromiseLikeConstructor {
@@ -308,6 +320,19 @@ declare function isArrayLike(value: unknown): value is ArrayLike<any>;
  */
 declare function isBigInt(value: unknown): value is bigint;
 
+/**
+ * 类型守卫，判断给定的值是否为 `Blob` 对象
+ * @param value 要判断的值
+ * @example
+ * ```js
+ * isBlob(new Blob()) // true
+ * isBlob(new ArrayBuffer(8)) // false
+ * isBlob([1, 2, 3]) // false
+ * ```
+ * @version 0.3.0
+ */
+declare function isBlob(value: any): value is Blob;
+
 /**
  * 类型守卫，判断给定的值是否为布尔类型
  * @param value 要判断的值
@@ -1153,6 +1178,18 @@ declare function titleCase(str: string, options?: {
     keepNumber?: boolean;
 }): string;
 
+/**
+ * 将字符串的首字母大写
+ * @param str 字符串
+ * @returns 首字母大写后的字符串
+ * @example
+ * ```js
+ * capitalize('hello world') // 'Hello world'
+ * ```
+ * @version 0.3.0
+ */
+declare function capitalize(str: string): string;
+
 type VarCase = {
     code: string;
     /** 是否为全大写 */
@@ -1239,6 +1276,74 @@ declare function caseKebab(str: string, keepLetterCase?: boolean, keepNumber?: b
  */
 declare function caseSnake(str: string, keepLetterCase?: boolean, keepNumber?: boolean): string;
 
+/**
+ * 给一个多行的字符串清除缩进效果
+ * @param str 需要处理的字符串
+ * @param count 缩进数量, 默认为 `2`
+ * @param indentStr 缩进字符串, 默认为 ` `(一个空格)
+ * @returns 处理过的字符串
+ * @example
+ * ```js
+ * dedent(`  a\n  b\n    c`) // `a\nb\n  c`
+ * dedent(`*a\n**b\n****c`, 3, '*') // `a\nb\n*c`
+ * ```
+ * @version 0.3.1
+ */
+declare function dedent(str: string, count?: number | null, indentStr?: string): string;
+/**
+ * 给一个多行的字符串清除缩进效果
+ * @param str 需要处理的字符串
+ * @param option 缩进效果配置
+ * - `count` 缩进数量, 默认为 `2`
+ * - `indentStr` 缩进字符串, 默认为 ` `(一个空格)
+ * @returns 处理过的字符串
+ * @example
+ * ```js
+ * dedent(`  a\n  b\n    c`) // `a\nb\n  c`
+ * dedent(`*a\n**b\n****c`, { count: 3, indentStr: '*' }) // `a\nb\n*c`
+ * ```
+ * @version 0.3.1
+ */
+declare function dedent(str: string, option?: {
+    count?: number;
+    indentStr?: string;
+}): string;
+
+/**
+ * 给一个多行的字符串添加缩进效果
+ * @param str 需要处理的字符串
+ * @param count 缩进数量, 默认为 `2`
+ * @param indentStr 缩进字符串, 默认为 ` `(一个空格)
+ * @returns 处理过的字符串
+ * @example
+ * ```js
+ * indent(`a\nb\n  c`) // `  a\n  b\n    c`
+ * indent(`a\nb\n  c`, 1, '*') // `*a\n*b\n*  c`
+ * ```
+ * @version 0.3.1
+ */
+declare function indent(str: string, count?: number | null, indentStr?: string): string;
+/**
+ * 给一个多行的字符串添加缩进效果
+ * @param str 需要处理的字符串
+ * @param option 缩进效果配置
+ * - `count` 缩进数量, 默认为 `2`
+ * - `indentStr` 缩进字符串, 默认为 ` `(一个空格)
+ * - `ignoreEmptyLine` 是否忽略空行, 默认为是
+ * @returns 处理过的字符串
+ * @example
+ * ```js
+ * indent(`a\nb\n  c`) // `  a\n  b\n    c`
+ * indent(`a\nb\n  c`, { count: 1, indentStr: '*' }) // `*a\n*b\n*  c`
+ * ```
+ * @version 0.3.1
+ */
+declare function indent(str: string, option?: {
+    count?: number;
+    indentStr?: string;
+    ignoreEmptyLine?: boolean;
+}): string;
+
 /**
  * 分割单词, 适用于分割、转换变量名的场景
  * - 任何非英文字母、数字的字符均会视为分割符
@@ -1253,6 +1358,18 @@ declare function caseSnake(str: string, keepLetterCase?: boolean, keepNumber?: b
  */
 declare function splitWords(str: string): string[];
 
+/**
+ * 将字符串的首字母小写
+ * @param str 字符串
+ * @returns 首字母小写后的字符串
+ * @example
+ * ```js
+ * uncapitalize('Hello world') // 'hello world'
+ * ```
+ * @version 0.3.0
+ */
+declare function uncapitalize(str: string): string;
+
 /**
  * 调用`Object.prototype.toString`获取对象类型名称
  * @param value 要判断的类型
@@ -1490,6 +1607,130 @@ type CloneOptions = {
  */
 declare function deepClone<T>(obj: T, options?: Partial<CloneOptions>, map?: Map<any, any>): T;
 
+/**
+ * 合并策略, 可以是 `'keep'` `'override'` `'merge'` 或者一个方法
+ * - `'keep'` 表示保留原值
+ * - `'override'` 表示覆盖为新值
+ * - 如果是自定义合并方法, 那么你的方法接收的第一个参数是需要合并的值以及其路径
+ *   - `{ target: 原值; source: 新值; path: 路径数组; unhandledValue: 如果无法处理则返回这个 }`
+ */
+type MergeStrategy = 'keep' | 'override' | MergeStrategyFunction;
+type MergeStrategyFunction<T = any, S = any, Res = any> = (param: {
+    target: T;
+    source: S;
+    path: (string | symbol)[];
+    unhandledValue: any;
+    map: Map<any, any>;
+    typeStrategy: MergeTypeStrategy;
+    /** 深拷贝, 直接传值即可, 参数已经预设好了 */
+    cloner: <T>(obj: T) => T;
+    /** 深合并, 直接传值即可, 参数已经预设好了 */
+    merger: (target: any, source: any, path: (string | symbol)[]) => any;
+}) => Res;
+/** 所有内部识别的值类型 */
+type BaseMargeType = 'Number' | 'String' | 'Boolean' | 'Symbol' | 'BigInt' | 'Null' | 'Undefined' | 'Object' | 'Array' | 'Set' | 'Map' | 'FormData' | 'Date' | 'RegExp' | 'Promise' | 'Function' | 'Generator' | 'Iterator' | 'ArrayBuffer' | 'Buffer' | 'DataView' | 'Blob' | 'File' | 'TypedArray' | 'WeakSet' | 'WeakMap' | 'WeakRef' | 'Error';
+/** 来源对象上的值类型, 不会有 `'Empty'` */
+type SourceMergeType = BaseMargeType | 'Any';
+/** 目标对象上的值类型, 如果某个字段目标上没有而来源上有, 那么就为 `"Empty"` */
+type TargetMergeType = BaseMargeType | 'Empty' | 'Any';
+/** 合并类型, 其中来源对象上不会有 `'Empty'` */
+type MergeType = `${SourceMergeType}2${TargetMergeType}`;
+/** 根据目标对象类型和来源对象类型获取合并策略 */
+type MergeTypeStrategy = {
+    [mergeType in MergeType]?: MergeStrategy;
+};
+type MergeEmptyPlaceholder = A.x & {
+    '@@merge/placeholder': true;
+};
+/** `deepMerge` 深合并的空值占位符 */
+declare const $$Empty: Readonly<{
+    '@@merge/placeholder': true;
+}>;
+/**
+ * 判断给定的参数是否为 `deepMerge` 深合并的空值占位符
+ * @param arg 需要判定的参数
+ * @returns 是否为空值占位符
+ */
+declare function isMergeEmptyPlaceholder(arg: any): arg is MergeEmptyPlaceholder;
+
+/** `deepMerge` 深合并方法的配置参数 */
+type MergeOption = {
+    /** 针对不同的类型设置不同的合并方法 */
+    typeStrategy?: Partial<MergeTypeStrategy>;
+    /** `deepMerge` 内部使用 `deepClone` 拷贝对象之类的值 */
+    cloneOptions?: CloneOptions;
+};
+
+/**
+ * 深合并, 作为基底的对象称为目标对象(target), 往之合并内容的对象称为来源对象(source)
+ * - 不能处理循环引用等特殊场景
+ * - 满足基本的合并功能, 以下行为是其默认行为
+ *   - 普通对象、FormData 这类对象会递归合并
+ *   - 数组会以拼接的方式合并
+ *     - `{ a: [1, 2] }` 和 `{ a: [3, 4] }` 会合并为 `{ a: [1, 2, 3, 4] }`
+ *   - Set、Map 会直接合并, 其中 Map 合并时来源对象会覆盖目标对象相同 Key 的值
+ *     - Set 和 Map 视为不同类型, 会用来源对象的值覆盖
+ *   - Set 和数组会互相合并
+ *     - `{ a: [1, 2] }` 和 `{ a: Set([3, 4]) }` 会合并为 `{ a: [1, 2, 3, 4] }`
+ *     - `{ a: Set([1, 2]) }` 和 `{ a: [3, 4] }` 会合并为 `{ a: Set([1, 2, 3, 4]) }`
+ *   - 来源对象的基本类型值不会覆盖对象
+ *   - 来源对象的空值(null、undefined)不会覆盖其他类型的值
+ *   - 来源对象的非空值会覆盖目标对象的空值(目标对象不存在某个键时也视为空值)
+ *   - 其他情况: 不同类型、原始类型、其他不能合并/拼接的值会以来源对象的为准作覆盖
+ * - 可以根据类型配置不同的策略, 策略可以是 `"keep"` `"override"` 或者一个方法
+ *   - `"keep"` 保留目标对象的值
+ *   - `"override"` 保留来源对象的值
+ *   - 传入方法:
+ *     - 类型 `(param: { target: any; source: any; path: (string | symbol)[]; unhandledValue: any; map: Map<any, any> }) => any`
+ *     - `target` 当前目标对象上这个位置的值
+ *     - `source` 当前来源对象上这个位置的值
+ *     - `path` 当前处理的值在对象上的位置
+ *     - `map` 用于处理循环引用等情况的 Map 对象
+ *     - `unhandledValue` 将这个值返回, 可以跳过处理, 交给兜底逻辑
+ *     - 返回值: 合并后的对象
+ *   - 合并类型: 一个字符串 `${来源对象值类型}2${目标对象值类型}`, 常见类型见下
+ *     - 基本类型 `"Number"` `"String"` `"Boolean"` `"Symbol"` `"BigInt"` `"Null"` `"Undefined"`
+ *     - 常见对象 `"Object"` `"Array"` `"Set"` `"Map"` `"FormData"` `"Date"` `"RegExp"` `"Promise"`
+ *     - 函数 `"Function"`
+ *       - 这些均视为函数 `"AsyncFunction"` `"GeneratorFunction"`, 不能拿来用
+ *     - 生成器函数运行后得到生成器 `"Generator"`
+ *     - 迭代器 `"Iterator"`
+ *       - 这些均视为迭代器, 不能拿来用
+ *       - `"String Iterator"` `"Array Iterator"` `"RegExp String Iterator"`
+ *       - `"Map Iterator"` `"Set Iterator"` `"Segmenter String Iterator"`
+ *       - `"Iterator Helper"`
+ *     - 二进制流&文件 `"ArrayBuffer"` `"Buffer"` `"DataView"` `"Blob"` `"File"`
+ *     - 类型数组 `"TypedArray"`
+ *       - 这些均视为类型数组, 不能拿来用
+ *       - `"Int8Array"` `"Int16Array"` `"Int32Array"`
+ *       - `"Uint8Array"` `"Uint8ClampedArray"` `"Uint16Array"` `"Uint32Array"`
+ *       - `"Float32Array"` `"Float64Array"`
+ *       - `"BigInt64Array"` `"BigUint64Array"`
+ *     - 弱引用 `"WeakSet"` `"WeakMap"` `"WeakRef"`
+ *     - 报错信息 `"Error"`
+ *       - 任意类型的错误视为报错信息
+ *     - 其他类型 `"Any"` 表示所有类型(用于兜底), 空类型 `"Empty"` 表示目标对象上没有这个键
+ *       - `"Empty"` 不会出现在来源对象上, 因此只会有 `"Any2Empty"`, 而不会有 `"Empty2Any"`
+ *   - 策略优先级是:
+ *     - 精确指定优先级最高: 如 `"Object2Object"` 优先于 `"Object2Any"`
+ *     - 来源对象精确指定优先级高: 如 `"Object2Any"` 优先于 `"Any2Object"`
+ *     - 空类型 `"Empty"` 视为精确指定
+ * @param target 目标对象
+ * @param source 来源对象, 往目标对象合并内容
+ * @param option 配置
+ * - `option.typeStrategy`: 针对不同的类型设置不同的合并方法
+ * - `option.cloneOptions`: `deepMerge` 内部使用 `deepClone` 拷贝对象之类的值
+ * @example
+ * ```js
+ * const obj1 = { arr: [1, 2], obj: { a: [1], b: { c: 2 } }, p: '1' }
+ * const obj2 = { arr: [3], obj: { a: [2], b: { c: 4, d: 3 } }, p: '2' }
+ * const obj3 = deepMerge(obj1, obj2)
+ * obj3 // { arr: [1, 2, 3], obj: { a: [1, 2], b: { c: 4, d: 3 } }, p: '2' }
+ * ```
+ * @version 0.3.0
+ */
+declare function deepMerge<Target, Source, Result = Target & Source>(target: Target, source: Source, option?: MergeOption): Result;
+
 /**
  * 快速深拷贝
  * - 功能较为齐全, 相对 `deepClone` 而言运行更快
@@ -1549,7 +1790,15 @@ declare function isEmpty(value: unknown): boolean;
  * - `getKey` 自定义 key 的生成规则, 默认使用内部方法生成 key
  * - `ttl` 缓存的过期时间, 单位毫秒, 为 0 表示不过期, 默认不过期
  * - `count` 缓存最大使用次数, 为 0 表示不限次数, 默认不限次数
- * @returns
+ * @returns 记忆化的函数, 输入相同参数再次调用时会直接返回之前的结果而不会调用原函数
+ * @example
+ * ```js
+ * // 计算斐波那契数列
+ * const fib = memo(function (n) {
+ *   if (n < 2) return n
+ *   return fib(n - 1) + fib(n - 2)
+ * })
+ * ```
  */
 declare function memo<TArgs extends any[], TRes>(fn: (...args: TArgs) => TRes, options?: {
     getKey?: (...args: TArgs) => string | number;
@@ -1737,4 +1986,5 @@ declare function throttle<T extends any[]>(fn: (...args: T) => any, delay: numbe
     reset: () => void;
 };
 
-export { type CloneOptions, type CustomCloner, type RangeOptions, type TypedArray, _, acceptableFileName, acceptableFileType, camelCase, caseCamel, caseConvert, caseKebab, casePascal, caseSnake, clamp, compose, _curryMore as curry, debounce, deepClone, defer, fastClone, getAcceptableExtByMIME, getAcceptableMIMEByExt, getGlobalThis, getTag, isArray, isArrayBuffer, isArrayLike, isBigInt, isBigInt64Array, isBigUint64Array, isBoolean, isBuffer, isDataView, isDate, isEmpty, isFile, isFloat32Array, isFloat64Array, isFormData, isFunction, isInt16Array, isInt32Array, isInt8Array, isInteger, isIterable, isMap, isNil, isNull, isNumber, isObject, isPlaceholder, isPrimitive, isPromise, isPromiseLike, isRegExp, isSet, isString, isSymbol, isTypedArray, isUint16Array, isUint32Array, isUint8Array, isUint8ClampedArray, isUndefined, isWeakMap, isWeakSet, isWrapperBigInt, isWrapperBoolean, isWrapperNumber, isWrapperObject, isWrapperString, isWrapperSymbol, kebabCase, memo, noop, not, parallel, pascalCase, pass, passWith, pipe, randomBase32String, randomChoice, randomHexString, randomInt, randomIntFloor, randomString, range, remove, retry, shuffle, sleep, snakeCase, splitWords, throttle, titleCase, tryit, ulid, uuidNil, uuidV4, withResolvers };
+export { $$Empty, _, acceptableFileName, acceptableFileType, camelCase, capitalize, caseCamel, caseConvert, caseKebab, casePascal, caseSnake, clamp, compose, _curryMore as curry, debounce, dedent, deepClone, deepMerge, defer, fastClone, getAcceptableExtByMIME, getAcceptableMIMEByExt, getGlobalThis, getTag, indent, isArray, isArrayBuffer, isArrayLike, isBigInt, isBigInt64Array, isBigUint64Array, isBlob, isBoolean, isBuffer, isDataView, isDate, isEmpty, isFile, isFloat32Array, isFloat64Array, isFormData, isFunction, isInt16Array, isInt32Array, isInt8Array, isInteger, isIterable, isMap, isMergeEmptyPlaceholder, isNil, isNull, isNumber, isObject, isPlaceholder, isPrimitive, isPromise, isPromiseLike, isRegExp, isSet, isString, isSymbol, isTypedArray, isUint16Array, isUint32Array, isUint8Array, isUint8ClampedArray, isUndefined, isWeakMap, isWeakSet, isWrapperBigInt, isWrapperBoolean, isWrapperNumber, isWrapperObject, isWrapperString, isWrapperSymbol, kebabCase, memo, noop, not, parallel, pascalCase, pass, passWith, pipe, randomBase32String, randomChoice, randomHexString, randomInt, randomIntFloor, randomString, range, remove, retry, shuffle, sleep, snakeCase, splitWords, throttle, titleCase, tryit, ulid, uncapitalize, uuidNil, uuidV4, withResolvers };
+export type { BaseMargeType, CloneOptions, CustomCloner, MergeOption, MergeStrategy, MergeStrategyFunction, MergeType, MergeTypeStrategy, RangeOptions, SourceMergeType, TargetMergeType, TypedArray };