grofc_utils 1.0.0

package/src/guard.js

@@ -0,0 +1,564 @@
+/**
+ * 获取变量的类型字符串表示
+ * @param {*} v - 要检查类型的变量
+ * @returns {string} 变量的类型字符串
+ */
+const getType = v => v === null ? "null" : typeof v
+
+
+class GuardError extends Error {
+    /**
+     * 
+     * @param {string|Error} cause
+     */
+    constructor(cause) {
+        if (cause instanceof Error) {
+            super(`Guard execution failed: ${cause.message}`);
+            this.originalError = cause;
+            this.stack = cause.stack;
+        } else {
+            super(`Guard execution failed: ${cause || "Unknown error"}`);
+            this.originalError = null;
+        }
+        this.name = "GuardError";
+    }
+}
+const safeGuardExecute = (guardFunc, ...args) => {
+    try {
+        guardFunc(...args)
+    } catch (err) {
+        throw new GuardError(err);
+    }
+}
+
+const throwTypeErrorGiveType = (variable, name = "variable", ...acceptableTypeDescs) => {
+    if (acceptableTypeDescs.length === 1) throw TypeError(`Expected ${name} to be ${acceptableTypeDescs}, but got ${getType(variable)}.`)
+    else if (acceptableTypeDescs.length > 1) throw TypeError(`Expected ${name} to be ${acceptableTypeDescs.slice(0, -1).join(" ,")} or ${acceptableTypeDescs[acceptableTypeDescs.length - 1]}, but got ${getType(variable)}.`)
+}
+const throwTypeErrorGiveValue = (variable, name = "variable", ...acceptableValueDescs) => {
+    if (acceptableValueDescs.length === 1) throw TypeError(`Expected ${name} to be ${acceptableValueDescs}, but got ${variable}.`)
+    else if (acceptableValueDescs.length > 1) throw TypeError(`Expected ${name} to be ${acceptableValueDescs.slice(0, -1).join(" ,")} or ${acceptableValueDescs[acceptableValueDescs.length - 1]}, but got ${variable}.`)
+}
+const throwTypeErrorForArray = (name = "variable", acceptableTypeDesc, unexpectedElementDesc) => {
+    throw TypeError(`Expected all elements of ${name} to be ${acceptableTypeDesc}, but found ${unexpectedElementDesc}.`)
+}
+const throwRangeErrorGiveValue = (variable, name = "variable", ...acceptableRangeDescs) => {
+    if (acceptableRangeDescs.length === 1) throw RangeError(`Expected ${name} to be ${acceptableRangeDescs}, but got ${variable}.`)
+    else if (acceptableRangeDescs.length > 1) throw RangeError(`Expected ${name} to be ${acceptableRangeDescs.slice(0, -1).join(" ,")} or ${acceptableRangeDescs[acceptableRangeDescs.length - 1]}, but got ${variable}.`)
+}
+// ------------------------------------------------
+// 值校验守卫函数
+// ------------------------------------------------
+
+/**
+ * 检查变量是否为空值（不为 null 或 undefined）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量为 null 或 undefined 时抛出类型错误
+ */
+export function throwIfIsNullishValue(variable, name = "variable") {
+    if (variable == null) {
+        throwTypeErrorGiveValue(variable, name, "not null or undefined")
+    }
+}
+
+/**
+ * 检查变量是否为真值（truthy）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量为假值（falsy）时抛出类型错误
+ */
+export function throwIfIsFalsyValue(variable, name = "variable") {
+    if (!variable) {
+        throwTypeErrorGiveValue(variable, name, "a truthy value")
+    }
+}
+
+// ------------------------------------------------
+// 数字类型守卫函数
+// ------------------------------------------------
+/**
+ * 检查变量是否为数字类型
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是数字类型时抛出类型错误
+ */
+export function throwIfIsNotNumber(variable, name = "variable") {
+    if (typeof variable !== "number") {
+        throwTypeErrorGiveType(variable, name, "a number")
+    }
+}
+/**
+ * 检查数字变量是否为 NaN（非数字）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量是 NaN 时抛出类型错误
+ */
+export function throwIfIsNotComparableNumber(variable, name = "variable") {
+    throwIfIsNotNumber(variable, name)
+    if (Number.isNaN(variable)) {
+        throwTypeErrorGiveValue(variable, name, "comparable number(not NaN)")
+    }
+}
+export const throwIfIsNotNumberOrIsNaN = throwIfIsNotComparableNumber;
+/**
+ * 检查变量是否为有限数字（排除 Infinity 和 -Infinity，但允许 NaN）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是有限数字时抛出类型错误
+ */
+export function throwIfIsNotFiniteNumber(variable, name = "variable") {
+    throwIfIsNotNumber(variable, name)
+    if (!Number.isFinite(variable)) {
+        throwTypeErrorGiveValue(variable, name, "a finite number")
+    }
+}
+
+/**
+ * 检查变量是否为正有限数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是正有限数时抛出范围错误
+ */
+export function throwIfIsNotPositiveFiniteNumber(variable, name = "variable") {
+    throwIfIsNotFiniteNumber(variable, name)
+    if (variable <= 0) {
+        throwRangeErrorGiveValue(variable, name, "a positive finite number");
+    }
+}
+
+/**
+ * 检查变量是否为负有限数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是负有限数时抛出范围错误
+ */
+export function throwIfIsNotNegativeFiniteNumber(variable, name = "variable") {
+    throwIfIsNotFiniteNumber(variable, name)
+    if (variable >= 0) {
+        throwRangeErrorGiveValue(variable, name, "a negative finite number");
+    }
+}
+
+/**
+ * 检查变量是否为非负有限数（大于等于0的有限数）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是非负有限数时抛出范围错误
+ */
+export function throwIfIsNotNonNegativeFiniteNumber(variable, name = "variable") {
+    throwIfIsNotFiniteNumber(variable, name)
+    if (variable < 0) {
+        throwRangeErrorGiveValue(variable, name, "a non-negative finite number");
+    }
+}
+
+/**
+ * 检查变量是否为整数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是整数时抛出类型错误
+ */
+export function throwIfIsNotInteger(variable, name = "variable") {
+    throwIfIsNotNumber(variable, name)
+    if (!Number.isInteger(variable)) {
+        throwTypeErrorGiveValue(variable, name, "an integer");
+    }
+}
+
+/**
+ * 检查变量是否为正整数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是正整数时抛出范围错误
+ */
+export function throwIfIsNotPositiveInteger(variable, name = "variable") {
+    throwIfIsNotInteger(variable, name)
+    if (variable <= 0) {
+        throwRangeErrorGiveValue(variable, name, "a positive integer");
+    }
+}
+
+/**
+ * 检查变量是否为负整数
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是负整数时抛出范围错误
+ */
+export function throwIfIsNotNegativeInteger(variable, name = "variable") {
+    throwIfIsNotInteger(variable, name)
+    if (variable >= 0) {
+        throwRangeErrorGiveValue(variable, name, "a negative integer");
+    }
+}
+
+/**
+ * 检查变量是否为非负整数（自然数，包括0）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {RangeError} 当变量不是非负整数时抛出范围错误
+ */
+export function throwIfIsNotNonNegativeInteger(variable, name = "variable") {
+    throwIfIsNotInteger(variable, name)
+    if (variable < 0) {
+        throwRangeErrorGiveValue(variable, name, "a non-negative integer");
+    }
+}
+// ------------------------------------------------
+// 对象类型守卫函数
+// ------------------------------------------------
+/**
+ * 检查变量是否为普通对象（非 null，非数组）
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是普通对象时抛出类型错误
+ */
+export function throwIfIsNotPlainObject(variable, name = "variable") {
+    if (typeof variable !== 'object' || variable === null || Array.isArray(variable)) {
+        throwTypeErrorGiveType(variable, name, "a plain object");
+    }
+}
+/**
+ * 检查对象是否缺少所有指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少所有指定键时抛出错误
+ */
+export function throwIfAllKeysMissing(variable, keys, name = "variable") {
+    throwIfIsNotPlainObject(variable);
+    if (!Array.isArray(keys)) {
+        if (typeof keys === "string") keys = [keys];
+        else safeGuardExecute(throwTypeErrorGiveType, keys, name, "string", "an array of string");
+    }
+    if (keys.every(key => !(key in variable))) {
+        throw new Error(`Expected ${name} to have at least one attribute of [${keys.map(k => `'${k}'`).join(" ,")}], but cannot find.`)
+    }
+}
+/**
+ * 检查对象是否缺少任意指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少任何一个指定键时抛出错误
+ */
+export function throwIfSomeKeysMissing(variable, keys, name = "variable") {
+    throwIfIsNotPlainObject(variable);
+    if (!Array.isArray(keys)) {
+        if (typeof keys === "string") keys = [keys];
+        else safeGuardExecute(throwTypeErrorGiveType, keys, name, "string", "an array of string");
+    }
+    const l = keys.filter(key => !(key in variable))
+    if (l.length) {
+        throw new Error(`Expected ${name} to have at all attributes of [${keys.map(k => `'${k}'`).join(" ,")}], but missing [${l.map(k => `'${k}'`).join(" ,")}].`)
+    }
+}
+// ------------------------------------------------
+// 函数类型守卫函数
+// ------------------------------------------------
+/**
+ * 检查变量是否为函数类型，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @throws {TypeError} 当变量不是函数类型时抛出类型错误
+ */
+export function throwIfIsNotFunction(variable, name = "variable") {
+    if (typeof variable !== "function") {
+        throwTypeErrorGiveType(variable, name, "a function")
+    }
+}
+// ------------------------------------------------
+// 可迭代守卫函数
+// ------------------------------------------------
+/**
+ * 检查变量是否为可迭代对象或字符串
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是可迭代对象或字符串时抛出类型错误
+ */
+export function throwIfIsNotIterable(variable, name = "variable") {
+    if (variable == null || typeof variable[Symbol.iterator] !== "function") {
+        throwTypeErrorGiveType(variable, name, "an iterable");
+    }
+}
+/**
+ * 检查变量是否为可迭代对象，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当变量不是可迭代对象时抛出类型错误
+ */
+export function throwIfIsNotIterableObject(variable, name = "") {
+    if (typeof variable !== 'object' || variable === null || typeof variable[Symbol.iterator] !== 'function') {
+        throwTypeErrorGiveType(variable, name, "an iterable object");
+    }
+}
+
+//------------------------------------------------
+// 数组类型守卫函数
+// ------------------------------------------------
+export function throwIfIsNotArray(variable, name = "variable") {
+    if (!Array.isArray(variable)) {
+        throwTypeErrorGiveType(variable, name, "an array");
+    }
+}
+export function throwIfIsNotNonEmptyArray(variable, name = "variable") {
+    throwIfIsNotArray(variable, name);
+    if (variable.length === 0) {
+        throwRangeErrorGiveValue(variable, name, "a non-empty array");
+    }
+}
+/**
+ * 检查变量是否为仅包含非NaN数字的数组，如果不是则抛出类型错误
+ * 
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或数组元素不符合要求时抛出错误
+ */
+export function throwIfIsNotComparableNumberArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "comparable numbers(not NaN)";
+    // 验证数组中的每个元素都是非NaN的数字
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+    }
+}
+
+export const throwIfIsNumberArrayWithoutNaN = throwIfIsNotComparableNumberArray;
+
+/**
+ * 校验变量是否为仅包含有限数（有限 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, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "finite numbers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含正有限数（> 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, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "positive finite numbers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (e <= 0) {
+            const desc = e === 0 ? "zero" : `a negative number (${e})`;
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含非负有限数（>= 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, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "non-negative finite numbers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (e < 0) {
+            const desc = `a negative number (${e})`;
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含负有限数（< 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, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "negative finite numbers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (e >= 0) {
+            const desc = e === 0 ? "zero" : `a positive number (${e})`;
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含整数的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、小数
+ */
+export function throwIfIsNotIntegerArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "integers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (!Number.isInteger(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-integer value (${e})`);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含正整数（> 0 的整数）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、负数、零、小数
+ */
+export function throwIfIsNotPositiveIntegerArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "positive integers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (!Number.isInteger(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-integer value (${e})`);
+        }
+        if (e <= 0) {
+            const desc = e === 0 ? "zero" : `a negative number (${e})`;
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含非负整数（>= 0 的整数）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、负数、小数
+ */
+export function throwIfIsNotNonNegativeIntegerArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "non-negative integers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (!Number.isInteger(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-integer value (${e})`);
+        }
+        if (e < 0) {
+            const desc = `a negative number (${e})`;
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}
+
+/**
+ * 校验变量是否为仅包含负整数（< 0 的整数）的数组。
+ * @param {*} variable - 待校验的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息上下文
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 元素合称，用于错误消息上下文
+ * @throws {TypeError} 若 variable 不是数组，或包含非数字、NaN、Infinity、正数、零、小数
+ */
+export function throwIfIsNotNegativeIntegerArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "negative integers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`);
+        }
+        if (Number.isNaN(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, "NaN");
+        }
+        if (!Number.isFinite(e)) {
+            const desc = e > 0 ? "Infinity" : "-Infinity";
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+        if (!Number.isInteger(e)) {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-integer value (${e})`);
+        }
+        if (e >= 0) {
+            const desc = e === 0 ? "zero" : `a positive number (${e})`;
+            throwTypeErrorForArray(generalTerm, acceptType, desc);
+        }
+    }
+}

package/src/missingData.js

@@ -0,0 +1,65 @@
+import { throwIfIsNotNonNegativeInteger } from "./guard";
+
+/**
+ * 前向填充（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(inputData, options = { checkDefaultValue: true }) {
+    if ("len" in options) {
+        throwIfIsNotNonNegativeInteger(options.len, "options.len");
+        if (options.len === 0) return [];
+    }
+    const result = []
+    const dataList = typeof inputData === "object"
+        && typeof inputData?.[Symbol.iterator] === 'function' ?
+        inputData : [inputData]
+    const checkInvalidity = typeof options.invalidityChecker === "function" ? options.invalidityChecker
+        : Array.isArray(options.invalidityChecker) ? (v) => options.invalidityChecker.some(w => Object.is(v, w))
+            : (v) => Object.is(v, options.invalidityChecker);
+    let currentValue, hasValidValue = false;
+    if ("defaultValue" in options) {
+        currentValue = options.defaultValue;
+        hasValidValue = options.checkDefaultValue ? !checkInvalidity(options.defaultValue) : true;
+    }
+    for (const gottenValue of dataList) {
+        if (!checkInvalidity(gottenValue)) {
+            currentValue = gottenValue;
+            hasValidValue = true;
+        }
+        if (!hasValidValue) continue;
+        result.push(currentValue);
+        if (result.length >= options.len) return result;
+    }
+    if (!hasValidValue) return result;
+    while (result.length < options.len) {
+        result.push(currentValue);
+    }
+    return result;
+}