grofc_utils 1.0.0 → 1.1.0

package/eslint.config.js

@@ -0,0 +1,12 @@
+import js from "@eslint/js";
+import globals from "globals";
+import { defineConfig } from "eslint/config";
+
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+    languageOptions: { globals: globals.browser }
+  },
+]);

package/index.js

@@ -1,5 +1,6 @@
 export * from './src/array.js';
 export * from './src/guard.js';
 export * from './src/missingData.js';
+export * from './src/object.js';
 export * from './src/random.js';
 export * from './src/string.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grofc_utils",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "",
   "main": "index.js",
   "scripts": {
@@ -26,6 +26,10 @@
       "import": "./src/missingData.js",
       "types": "./types/src/missingData.d.ts"
     },
+    "./object": {
+      "import": "./src/object.js",
+      "types": "./types/src/object.d.ts"
+    },
     "./random": {
       "import": "./src/random.js",
       "types": "./types/src/random.d.ts"
@@ -40,6 +44,9 @@
   "license": "ISC",
   "type": "module",
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
     "vitest": "^4.0.6"
   }
 }

package/src/guard.js

@@ -204,6 +204,30 @@ export function throwIfIsNotNonNegativeInteger(variable, name = "variable") {
         throwRangeErrorGiveValue(variable, name, "a non-negative integer");
     }
 }
+//
+// 字符串类型守卫函数
+//
+export function throwIfIsNotString(variable, name = "variable") {
+    if (typeof variable !== "string") {
+        throwTypeErrorGiveType(variable, name, "string")
+    }
+}
+//
+// symbol类型守卫函数
+//
+export function throwIfIsNotSymbol(variable, name = "variable") {
+    if (typeof variable !== "symbol") {
+        throwTypeErrorGiveType(variable, name, "symbol")
+    }
+}
+//
+// bigint类型守卫函数
+//
+export function throwIfIsNotBigInt(variable, name = "variable") {
+    if (typeof variable !== "bigint") {
+        throwTypeErrorGiveType(variable, name, "bigint")
+    }
+}
 // ------------------------------------------------
 // 对象类型守卫函数
 // ------------------------------------------------
@@ -218,10 +242,25 @@ export function throwIfIsNotPlainObject(variable, name = "variable") {
         throwTypeErrorGiveType(variable, name, "a plain object");
     }
 }
+/**
+ * 检查对象是否包含指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string} key - 要检查的键名
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当variable不是普通对象或key不是字符串时抛出类型错误
+ * @throws {Error} 当对象中找不到指定键时抛出错误
+ */
+export function throwIfKeyMissing(variable, key, name = "variable") {
+    throwIfIsNotPlainObject(variable);
+    throwIfIsNotString(key);
+    if (!(key in variable)) {
+        throw new Error(`Expected ${name} to have key : "${key}", but cannot find.`)
+    }
+}
 /**
  * 检查对象是否缺少所有指定的键
  * @param {*} variable - 要检查的对象
- * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string[]} keys - 要检查的键名数组
  * @param {string} name - 变量名称（用于错误消息）
  * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
  * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
@@ -229,18 +268,15 @@ export function throwIfIsNotPlainObject(variable, name = "variable") {
  */
 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");
-    }
+    safeGuardExecute(throwIfIsNotStringArray, keys, name, "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.`)
+        throw new Error(`Expected ${name} to have at least one keys of [${keys.map(k => `'${k}'`).join(" ,")}], but cannot find.`)
     }
 }
 /**
  * 检查对象是否缺少任意指定的键
  * @param {*} variable - 要检查的对象
- * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string[]} keys - 要检查的键名数组
  * @param {string} name - 变量名称（用于错误消息）
  * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
  * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
@@ -248,13 +284,58 @@ export function throwIfAllKeysMissing(variable, keys, name = "variable") {
  */
 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");
-    }
+    safeGuardExecute(throwIfIsNotStringArray, keys, name, "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(" ,")}].`)
+        throw new Error(`Expected ${name} to have at all keys of [${keys.map(k => `'${k}'`).join(" ,")}], but missing [${l.map(k => `'${k}'`).join(" ,")}].`)
+    }
+}
+/**
+ * 检查对象是否包含指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string} property - 要检查的键名
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当variable不是普通对象或property不是字符串时抛出类型错误
+ * @throws {Error} 当对象中找不到指定键时抛出错误
+ */
+export function throwIfOwnPropertyMissing(variable, property, name = "variable") {
+    throwIfIsNotPlainObject(variable);
+    throwIfIsNotString(property);
+    if (Object.hasOwn(variable, property)) {
+        throw new Error(`Expected ${name} to have own property : "${property}", but cannot find.`)
+    }
+}
+/**
+ * 检查对象是否缺少所有指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string[]}properties- 要检查的键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当properties不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少所有指定键时抛出错误
+ */
+export function throwIfAllOwnPropertiesMissing(variable, properties, name = "variable") {
+    throwIfIsNotPlainObject(variable);
+    safeGuardExecute(throwIfIsNotStringArray, properties, name, "an array of string");
+    if (properties.every(p => !Object.hasOwn(variable, p))) {
+        throw new Error(`Expected ${name} to have at least one own property of [${properties.map(k => `'${k}'`).join(" ,")}], but cannot find.`)
+    }
+}
+/**
+ * 检查对象是否缺少任意指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string[]} properties - 要检查的键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当 properties 不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少任何一个指定键时抛出错误
+ */
+export function throwIfSomeOwnPropertiesMissing(variable, properties, name = "variable") {
+    throwIfIsNotPlainObject(variable);
+    safeGuardExecute(throwIfIsNotStringArray, properties, name, "an array of string");
+    const l = properties.filter(p => !Object.hasOwn(variable, p))
+    if (l.length) {
+        throw new Error(`Expected ${name} to have at all own properties of [${properties.map(k => `'${k}'`).join(" ,")}], but missing [${l.map(k => `'${k}'`).join(" ,")}].`)
     }
 }
 // ------------------------------------------------
@@ -311,6 +392,25 @@ export function throwIfIsNotNonEmptyArray(variable, name = "variable") {
         throwRangeErrorGiveValue(variable, name, "a non-empty array");
     }
 }
+
+export function throwIfIsNotStringArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "strings";
+    for (const e of variable) {
+        if (typeof e !== "string") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-string value of type ${getType(e)}`)
+        }
+    }
+}
+export function throwIfIsNotNumberArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "numbers";
+    for (const e of variable) {
+        if (typeof e !== "number") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-number value of type ${getType(e)}`)
+        }
+    }
+}
 /**
  * 检查变量是否为仅包含非NaN数字的数组，如果不是则抛出类型错误
  * 

package/src/object.js

@@ -0,0 +1,13 @@
+import { throwIfIsNotPlainObject, throwIfKeyMissing } from "./guard";
+
+export function setReadOnlyProperty(obj, name) {
+    throwIfIsNotPlainObject(obj);
+    throwIfKeyMissing(obj, name, "obj");
+    const descriptor = Object.getOwnPropertyDescriptor(obj, name);
+    Object.defineProperty(obj, name, {
+        value: descriptor.value,
+        writable: false,
+        configurable: false,
+        enumerable: descriptor.enumerable ?? true
+    })
+}

package/src/random.js

@@ -151,7 +151,7 @@ export function randomVectors(len, dim = 2, mod = 1, generator = randomGaussian)
  * @param {(r: number, c: number) => number} generator 用于生成矩阵元素的函数，接收行列索引作为参数，默认生成0-10的随机整数
  * @returns {number[][]} 二维数组表示的矩阵，大小为rows×cols
  */
-export function randomMatrix(rows = 2, cols = rows, generator = (_r, _c) => randomInt(0, 10)) {
+export function randomMatrix(rows = 2, cols = rows, generator = () => randomInt(0, 10)) {
     throwIfIsNotNonNegativeInteger(rows, "rows");
     throwIfIsNotNonNegativeInteger(cols, "cols");
     throwIfIsNotFunction(generator, "generator");
@@ -166,7 +166,7 @@ export function randomMatrix(rows = 2, cols = rows, generator = (_r, _c) => rand
  * @param {(r: number, c: number) => number} generator 用于生成矩阵元素的函数，接收行列索引作为参数，默认生成0-10的随机整数
  * @returns {number[][][]} 包含len个矩阵的数组，每个矩阵都是二维数组
  */
-export function randomMatrices(len, rows = 2, cols = rows, generator = (_r, _c) => randomInt(0, 10)) {
+export function randomMatrices(len, rows = 2, cols = rows, generator = () => randomInt(0, 10)) {
     throwIfIsNotNonNegativeInteger(len, "len");
     return Array.from({ length: len }, () => randomMatrix(rows, cols, generator))
 }

package/tsconfig.json

@@ -11,7 +11,7 @@
     // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
 
     /* Language and Environment */
-    "target": "es2021",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
     // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
     // "jsx": "preserve",                                /* Specify what JSX code is generated. */
     // "experimentalDecorators": true,                   /* Enable experimental support for legacy experimental decorators. */
@@ -108,5 +108,11 @@
     // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
     "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
   },
-  "exclude": ["./src","types","./generate.exports.js"]
+  "exclude": [
+    "./src",
+    "types",
+    "test",
+    "eslint.config.js",
+    "./generate.exports.js"
+  ]
 }

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./src/array.js";
 export * from "./src/guard.js";
 export * from "./src/missingData.js";
+export * from "./src/object.js";
 export * from "./src/random.js";
 export * from "./src/string.js";

package/types/src/guard.d.ts

@@ -82,6 +82,9 @@ export function throwIfIsNotNegativeInteger(variable: any, name?: string): void;
  * @throws {RangeError} 当变量不是非负整数时抛出范围错误
  */
 export function throwIfIsNotNonNegativeInteger(variable: any, name?: string): void;
+export function throwIfIsNotString(variable: any, name?: string): void;
+export function throwIfIsNotSymbol(variable: any, name?: string): void;
+export function throwIfIsNotBigInt(variable: any, name?: string): void;
 /**
  * 检查变量是否为普通对象（非 null，非数组）
  * @param {*} variable - 要检查的变量
@@ -89,26 +92,64 @@ export function throwIfIsNotNonNegativeInteger(variable: any, name?: string): vo
  * @throws {TypeError} 当变量不是普通对象时抛出类型错误
  */
 export function throwIfIsNotPlainObject(variable: any, name?: string): void;
+/**
+ * 检查对象是否包含指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string} key - 要检查的键名
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当variable不是普通对象或key不是字符串时抛出类型错误
+ * @throws {Error} 当对象中找不到指定键时抛出错误
+ */
+export function throwIfKeyMissing(variable: any, key: string, name?: string): void;
 /**
  * 检查对象是否缺少所有指定的键
  * @param {*} variable - 要检查的对象
- * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string[]} keys - 要检查的键名数组
  * @param {string} name - 变量名称（用于错误消息）
  * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
  * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
  * @throws {Error} 当对象缺少所有指定键时抛出错误
  */
-export function throwIfAllKeysMissing(variable: any, keys: string | string[], name?: string): void;
+export function throwIfAllKeysMissing(variable: any, keys: string[], name?: string): void;
 /**
  * 检查对象是否缺少任意指定的键
  * @param {*} variable - 要检查的对象
- * @param {string|string[]} keys - 要检查的键名或键名数组
+ * @param {string[]} keys - 要检查的键名数组
  * @param {string} name - 变量名称（用于错误消息）
  * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
  * @throws {GuardError} 当 keys 不是字符串或字符串数组时抛出守卫错误
  * @throws {Error} 当对象缺少任何一个指定键时抛出错误
  */
-export function throwIfSomeKeysMissing(variable: any, keys: string | string[], name?: string): void;
+export function throwIfSomeKeysMissing(variable: any, keys: string[], name?: string): void;
+/**
+ * 检查对象是否包含指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string} property - 要检查的键名
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当variable不是普通对象或property不是字符串时抛出类型错误
+ * @throws {Error} 当对象中找不到指定键时抛出错误
+ */
+export function throwIfOwnPropertyMissing(variable: any, property: string, name?: string): void;
+/**
+ * 检查对象是否缺少所有指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string[]}properties- 要检查的键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当properties不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少所有指定键时抛出错误
+ */
+export function throwIfAllOwnPropertiesMissing(variable: any, properties: any, name?: string): void;
+/**
+ * 检查对象是否缺少任意指定的键
+ * @param {*} variable - 要检查的对象
+ * @param {string[]} properties - 要检查的键名数组
+ * @param {string} name - 变量名称（用于错误消息）
+ * @throws {TypeError} 当 variable 不是普通对象时抛出类型错误
+ * @throws {GuardError} 当 properties 不是字符串或字符串数组时抛出守卫错误
+ * @throws {Error} 当对象缺少任何一个指定键时抛出错误
+ */
+export function throwIfSomeOwnPropertiesMissing(variable: any, properties: string[], name?: string): void;
 /**
  * 检查变量是否为函数类型，如果不是则抛出类型错误
  * @param {*} variable - 要检查的变量
@@ -132,6 +173,8 @@ export function throwIfIsNotIterable(variable: any, name?: string): void;
 export function throwIfIsNotIterableObject(variable: any, name?: string): void;
 export function throwIfIsNotArray(variable: any, name?: string): void;
 export function throwIfIsNotNonEmptyArray(variable: any, name?: string): void;
+export function throwIfIsNotStringArray(variable: any, name?: string, generalTerm?: string): void;
+export function throwIfIsNotNumberArray(variable: any, name?: string, generalTerm?: string): void;
 /**
  * 检查变量是否为仅包含非NaN数字的数组，如果不是则抛出类型错误
  *

package/types/src/object.d.ts

@@ -0,0 +1 @@
+export function setReadOnlyProperty(obj: any, name: any): void;

package/readme.md

@@ -1,4 +0,0 @@
-### 如何使用？
-```
-npm install github:xinyuan-noname/grofc_utils
-```