grofc_utils 1.0.0

package/types/src/guard.d.ts

@@ -0,0 +1,223 @@
+/**
+ * 检查变量是否为空值（不为 null 或 undefined）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量为 null 或 undefined 时抛出类型错误
+ */
+export function throwIfIsNullishValue(variable: any, name?: string): void;
+/**
+ * 检查变量是否为真值（truthy）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量为假值（falsy）时抛出类型错误
+ */
+export function throwIfIsFalsyValue(variable: any, name?: string): void;
+/**
+ * 检查变量是否为数字类型
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是数字类型时抛出类型错误
+ */
+export function throwIfIsNotNumber(variable: any, name?: string): void;
+/**
+ * 检查数字变量是否为 NaN（非数字）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量是 NaN 时抛出类型错误
+ */
+export function throwIfIsNotComparableNumber(variable: any, name?: string): void;
+/**
+ * 检查变量是否为有限数字（排除 Infinity 和 -Infinity，但允许 NaN）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是有限数字时抛出类型错误
+ */
+export function throwIfIsNotFiniteNumber(variable: any, name?: string): void;
+/**
+ * 检查变量是否为正有限数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是正有限数时抛出范围错误
+ */
+export function throwIfIsNotPositiveFiniteNumber(variable: any, name?: string): void;
+/**
+ * 检查变量是否为负有限数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是负有限数时抛出范围错误
+ */
+export function throwIfIsNotNegativeFiniteNumber(variable: any, name?: string): void;
+/**
+ * 检查变量是否为非负有限数（大于等于0的有限数）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是非负有限数时抛出范围错误
+ */
+export function throwIfIsNotNonNegativeFiniteNumber(variable: any, name?: string): void;
+/**
+ * 检查变量是否为整数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是整数时抛出类型错误
+ */
+export function throwIfIsNotInteger(variable: any, name?: string): void;
+/**
+ * 检查变量是否为正整数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是正整数时抛出范围错误
+ */
+export function throwIfIsNotPositiveInteger(variable: any, name?: string): void;
+/**
+ * 检查变量是否为负整数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是负整数时抛出范围错误
+ */
+export function throwIfIsNotNegativeInteger(variable: any, name?: string): void;
+/**
+ * 检查变量是否为非负整数（自然数，包括0）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是非负整数时抛出范围错误
+ */
+export function throwIfIsNotNonNegativeInteger(variable: any, name?: string): void;
+/**
+ * 检查变量是否为普通对象（非 null，非数组）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是普通对象时抛出类型错误
+ */
+export function throwIfIsNotPlainObject(variable: any, name?: string): void;
+/**
+ * 检查对象是否缺少所有指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少所有指定键时抛出错误
+ */
+export function throwIfAllKeysMissing(variable: any, keys: string | string[], name?: string): void;
+/**
+ * 检查对象是否缺少任意指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少任何一个指定键时抛出错误
+ */
+export function throwIfSomeKeysMissing(variable: any, keys: string | string[], name?: string): void;
+/**
+ * 检查变量是否为函数类型，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @throws {TypeError} 当变量不是函数类型时抛出类型错误
+ */
+export function throwIfIsNotFunction(variable: any, name?: string): void;
+/**
+ * 检查变量是否为可迭代对象或字符串
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是可迭代对象或字符串时抛出类型错误
+ */
+export function throwIfIsNotIterable(variable: any, name?: string): void;
+/**
+ * 检查变量是否为可迭代对象，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是可迭代对象时抛出类型错误
+ */
+export function throwIfIsNotIterableObject(variable: any, name?: string): void;
+export function throwIfIsNotArray(variable: any, name?: string): void;
+export function throwIfIsNotNonEmptyArray(variable: any, name?: string): void;
+/**
+ * 检查变量是否为仅包含非NaN数字的数组，如果不是则抛出类型错误
+ *
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或数组元素不符合要求时抛出错误
+ */
+export function throwIfIsNotComparableNumberArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含有限数（有限 number）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、-Infinity
+ */
+export function throwIfIsNotFiniteNumberArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含正有限数（> 0 的有限 number）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、负数、零
+ */
+export function throwIfIsNotPositiveFiniteNumberArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含非负有限数（>= 0 的有限 number）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、负数
+ */
+export function throwIfIsNotNonNegativeFiniteNumberArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含负有限数（< 0 的有限 number）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、正数、零
+ */
+export function throwIfIsNotNegativeFiniteNumberArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含整数的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、小数
+ */
+export function throwIfIsNotIntegerArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含正整数（> 0 的整数）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、负数、零、小数
+ */
+export function throwIfIsNotPositiveIntegerArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含非负整数（>= 0 的整数）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、负数、小数
+ */
+export function throwIfIsNotNonNegativeIntegerArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 校验变量是否为仅包含负整数（< 0 的整数）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、正数、零、小数
+ */
+export function throwIfIsNotNegativeIntegerArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 检查数字变量是否为 NaN（非数字）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量是 NaN 时抛出类型错误
+ */
+export function throwIfIsNotNumberOrIsNaN(variable: any, name?: string): void;
+/**
+ * 检查变量是否为仅包含非NaN数字的数组，如果不是则抛出类型错误
+ *
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或数组元素不符合要求时抛出错误
+ */
+export function throwIfIsNumberArrayWithoutNaN(variable: any, name?: string, generalTerm?: string): void;

package/types/src/missingData.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 前向填充（forward-fill）输入数据，向前填充无效值。
+ *
+ * - 若输入为可迭代对象，将展开为迭代序列；若输入为非可迭代的对象，将包装为一个数组
+ * - 函数默认舍弃先导无效值，除非设置了`defaultValue`
+ * - 函数将以最近的上一次有效值填充无效值，无效值默认为 `undefined`
+ * - 函数默认使用`Object.is`进行判断无效值，因此可传入`NaN`，也请注意区分`-0`和`+0`
+ * - 对于传入的对象，函数不会进行拷贝，而是直接引用
+ *
+ * @template T
+ * @param {T | Iterable<T>} inputData - 输入数据（一个值或可迭代对象等）
+ * @param {{
+ *   len?: number,
+ *   invalidityChecker?: T | T[] | ((value: T) => boolean),
+ *   defaultValue?: T
+ *   checkDefaultValue?: boolean
+ * }} options
+ * @param options.len - 期望输出的元素总数，当 `len` 未提供时，输出长度 = 从第一个有效值开始到输入结束的长度，且不会自动扩展。
+ * @param options.invalidityChecker - 用于判断无效值的标准(默认: `undefined`)
+ * @param options.defaultValue - 若提供，则用以填充前导无效值，默认开启有效性检查。
+ * @param options.checkDefaultValue - 是否对 defaultValue 进行有效性检查（默认: `true`）
+ * @returns {T[]} 填充后的结果数组，长度不超过 `len`
+ *
+ * @example
+ * forwardFill("abc",{len:2}) //=> ["abc", "abc"]
+ * forwardFill(new String("abc")) // => ["a", "b", "c"]
+ * forwardFill([1, undefined, 3], { len: 5 }) // => [1, 1, 3, 3, 3]
+ * forwardFill(null, { len: 2, invalidityChecker: null, defaultValue: 0 }) // => [0, 0]
+ * forwardFill(new Map([[1,2],['a',2]])) // => [[1,2],['a',2]]
+ * const obj = {};forwardFill(obj,{len:2}) // => [obj, obj]
+ */
+export function forwardFill<T>(inputData: T | Iterable<T>, options?: {
+    len?: number;
+    invalidityChecker?: T | T[] | ((value: T) => boolean);
+    defaultValue?: T;
+    checkDefaultValue?: boolean;
+}): T[];

package/types/src/random.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 本函数用于生成指定范围内的随机整数。包含边界。
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} 属于 [min,max]
+ */
+export function randomInt(a: number, b: number): number;
+/**
+ * 本函数用于生成指定范围内的随机整数数组。
+ * @param {number} len
+ * @param {Iterable<number>} range 默认为[0,100]
+ * @returns {number[]} 每个元素属于[min,max]
+ */
+export function randomInts(len: number, range?: Iterable<number>): number[];
+/**
+ * 本函数用于生成指定范围内的随机浮点数。
+ * @param {number} a
+ * @param {number} b
+ * @returns {number} 属于 [min,max)
+ */
+export function randomFloat(a: number, b: number): number;
+/**
+ * 本函数用于生成指定范围内的随机浮点数数组。
+ * @param {number} len
+ * @param {Iterable<number>} range 默认为[0,1]
+ * @returns {number[]} 每个元素属于[min,max)
+ */
+export function randomFloats(len: number, range?: Iterable<number>): number[];
+/**
+ * 利用box-muller变换生成标准正态分布随机数
+ * @returns {number} 服从标准正态分布的随机数
+ */
+export function randomGaussian(): number;
+/**
+ * 生成标准正态分布随机数数组
+ * @param {number} len 数组长度
+ * @param {()=>number} generator 标准正态分布随机数生成器
+ * @returns
+ */
+export function randomGaussians(len: number, generator?: () => number): number[];
+/**
+ * 生成指定均值和标准差的正态分布随机数
+ * @param {number} mu 正态分布的均值
+ * @param {number} sigma 正态分布的标准差
+ * @param {()=>number} generator 标准正态分布随机数生成器
+ * @returns
+ */
+export function randomNormal(mu?: number, sigma?: number, generator?: () => number): number;
+/**
+ * 生成指定均值和标准差的正态分布随机数数组
+ * @param {number} len 数组长度
+ * @param {number} mu 正态分布的均值
+ * @param {number} sigma 正态分布的标准差
+ * @param {()=>number} generator 标准正态分布随机数生成器
+ * @returns {number[]}
+ */
+export function randomNormals(len: number, mu?: number, sigma?: number, generator?: () => number): number[];
+/**
+ * 生成指定维度和模长的随机向量
+ * @param {number} dim 生成向量的维度
+ * @param {number} mod 生成向量的模长
+ * @param {()=>number} generator 标准正态分布随机数生成器
+ * @returns {number[]}
+ */
+export function randomVector(dim?: number, mod?: number, generator?: () => number): number[];
+/**
+ * 生成指定数量的随机向量数组
+ * @param {number} len 需要生成的向量数量
+ * @param {number} dim 向量的维度，默认为2
+ * @param {number} mod 向量的模长，默认为1
+ * @param {()=>number} generator 随机数生成器函数，默认为randomGaussian
+ * @returns {number[][]} 包含len个随机向量的数组，每个向量都是指定维度和模长的数组
+ */
+export function randomVectors(len: number, dim?: number, mod?: number, generator?: () => number): number[][];
+/**
+ * 生成一个指定行列数的随机矩阵
+ * @param {number} rows 矩阵的行数，默认为2
+ * @param {number} cols 矩阵的列数，默认等于行数
+ * @param {(r: number, c: number) => number} generator 用于生成矩阵元素的函数，接收行列索引作为参数，默认生成0-10的随机整数
+ * @returns {number[][]} 二维数组表示的矩阵，大小为rows×cols
+ */
+export function randomMatrix(rows?: number, cols?: number, generator?: (r: number, c: number) => number): number[][];
+/**
+ * 生成指定数量的随机矩阵数组
+ * @param {number} len 需要生成的矩阵数量
+ * @param {number} rows 每个矩阵的行数
+ * @param {number} cols 每个矩阵的列数，默认等于行数
+ * @param {(r: number, c: number) => number} generator 用于生成矩阵元素的函数，接收行列索引作为参数，默认生成0-10的随机整数
+ * @returns {number[][][]} 包含len个矩阵的数组，每个矩阵都是二维数组
+ */
+export function randomMatrices(len: number, rows?: number, cols?: number, generator?: (r: number, c: number) => number): number[][][];
+/**
+ * 传入高斯随机数生成器，并生成对应的函数对象
+ * @param {()=>number} generator
+ * @returns {{
+ *  randomGaussian: ()=>number,
+ *  randomGaussians: (len:number)=>number[],
+ *  randomNormal: (mu:number,sigma:number)=>number,
+ *  randomNormals: (len:number,mu:number,sigma:number)=>number[],
+ *  randomVector: (dim:number,mod:number)=>number[]
+ * }}
+ */
+export function withGaussianGenerator(generator: () => number): {
+    randomGaussian: () => number;
+    randomGaussians: (len: number) => number[];
+    randomNormal: (mu: number, sigma: number) => number;
+    randomNormals: (len: number, mu: number, sigma: number) => number[];
+    randomVector: (dim: number, mod: number) => number[];
+};
+/**
+ * 传入矩阵元素生成器，并生成对应的矩阵操作函数对象
+ * @param {(r: number, c: number) => number} generator 用于生成矩阵元素的函数，接收行列索引作为参数
+ * @returns {{
+ *   randomMatrix: (rows: number, cols: number) => number[][],
+ *   randomMatrices: (len: number, rows: number, cols: number) => number[][][]
+ * }} 返回包含随机矩阵生成函数的对象
+ */
+export function withMatrixGenerator(generator: (r: number, c: number) => number): {
+    randomMatrix: (rows: number, cols: number) => number[][];
+    randomMatrices: (len: number, rows: number, cols: number) => number[][][];
+};
+export function randomColor(): string;
+export function randomColors(len: any): string[];
+/**
+ * @template T
+ * @param {Iterable<T>} inputFlow
+ * @returns {T[]}
+ */
+export function randomSort<T>(inputFlow: Iterable<T>): T[];
+/**
+ * 简单随机选取一个样本
+ * @template T
+ * @param {Iterable<T>} inputFlow
+ * @returns {T}
+ */
+export function randomPick<T>(inputFlow: Iterable<T>): T;
+/**
+ * 简单放回抽样
+ * @template T
+ * @param {Iterable<T>} inputList
+ * @param {number} len
+ * @returns {T[]}
+ */
+export function randomPicks<T>(inputList: Iterable<T>, len: number): T[];
+/**
+ * 带权重的随机选取一个样本
+ * @template T
+ * @param {Map<T,number>} inputMap
+ * @returns {T}
+ */
+export function randomChoice<T>(inputMap: Map<T, number>): T;
+/**
+ * 带权重的放回抽样
+ * @template T
+ * @param {Map<T,number>} inputMap
+ * @param {number} len
+ * @returns {T[]}
+ */
+export function randomChoices<T>(inputMap: Map<T, number>, len: number): T[];
+/**
+ * 随机抽取样本，由于采用了蓄水池抽样，数据输出的顺序与原顺序相关联
+ * @template T
+ * @param {Iterable<T>} inputFlow
+ * @param {number} len
+ * @returns {T[]}
+ */
+export function randomSample<T>(inputFlow: Iterable<T>, len: number): T[];
+/**
+ * @template T
+ * @param {Iterable<T>} inputFlow
+ * @returns {T[]}
+ */
+export function shuffle<T>(inputFlow: Iterable<T>): T[];

package/types/src/string.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 将字符串按照指定步长进行分块处理
+ * @param {string} input - 需要分块的输入字符串
+ * @param {number} step - 分块步长，必须为非零整数。正数表示从左到右分块，负数表示从右到左分块
+ * @returns {string[]} 返回分块后的字符串数组
+ * @throws {TypeError} 当input不是字符串或step不是整数时抛出
+ * @throws {RangeError} 当step为0时抛出
+ */
+export function chunkString(input: string, step: number): string[];