grofc_utils 1.2.1 → 1.4.1

package/index.js

@@ -1,4 +1,5 @@
 export * from './src/array.js';
+export * from './src/event.js';
 export * from './src/guard.js';
 export * from './src/missingData.js';
 export * from './src/object.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grofc_utils",
-  "version": "1.2.1",
+  "version": "1.4.1",
   "description": "",
   "main": "index.js",
   "scripts": {
@@ -18,6 +18,10 @@
       "import": "./src/array.js",
       "types": "./types/src/array.d.ts"
     },
+    "./event": {
+      "import": "./src/event.js",
+      "types": "./types/src/event.d.ts"
+    },
     "./guard": {
       "import": "./src/guard.js",
       "types": "./types/src/guard.d.ts"

package/src/event.js

@@ -0,0 +1,139 @@
+import { isPlainObject, throwIfIsNotExpectedValue, throwIfIsNotFunction, throwIfIsNotPlainObject, throwIfIsNotString } from "./guard.js"
+import { assignWithDescriptors } from "./object.js";
+
+/**
+ * 创建一个事件发射器对象，用于管理和触发自定义事件
+ * @returns {{
+ *  dispatchSync:(
+ *      event:string,
+ *      ing:(
+ *          ingEvent:{
+ *              target,name:string,type:string|null,preData:object,phase:"ing",data:object
+ *          })=>void,
+ *      options:{target,name:string,type:string|null,status:object,data:object}
+ *  )=>object
+ *  on:(event:string,phase:"before"|"begin"|"end"|"after",callback:(event:{
+ *      target,name:string,type:string|null,preData:object,data:object
+ * })=>void)=>void
+ *  off:(event:string,phase:"before"|"begin"|"end"|"after",callback:(event:{
+ *      target,name:string,type:string|null,preData:object,data:object
+ * })=>void)=>void
+ * }} 包含dispatchSync, on, off方法的对象
+ */
+export function createEventEmitter() {
+    const listenerMap = new Map()
+    const dispatchSync = (event, ing = () => { }, options = {}) => {
+        throwIfIsNotString(event, "event");
+        throwIfIsNotFunction(ing, "ing");
+        throwIfIsNotPlainObject(options, "options");
+        const { type = null, target = null, data = {}, status = { cancellable: true }, ...customData } = options;
+        const baseEvent = {
+            get target() {
+                return target
+            },
+
+            get name() {
+                return event
+            },
+            get type() {
+                return type
+            },
+            get preData() {
+                return { ...data }
+            },
+            get customData() {
+                return { ...customData }
+            },
+            get status() {
+                return { ...status }
+            }
+        }
+        // 触发before阶段监听器，如果返回false且事件可取消则中断执行
+        const beforeEvent = assignWithDescriptors({
+            get phase() {
+                return "before"
+            }
+        }, baseEvent)
+        const beforeCallbackList = listenerMap.get(event + ":before") ?? [];
+        for (const callback of beforeCallbackList) {
+            if (callback(beforeEvent) === false && beforeEvent.status.cancellable) return;
+        }
+        // 触发begin阶段监听器
+        const beginEvent = assignWithDescriptors({
+            get phase() {
+                return "begin"
+            }
+        }, baseEvent);
+        const beginCallbackList = listenerMap.get(event + ":begin") ?? [];
+        for (const callback of beginCallbackList) {
+            callback(beginEvent)
+        }
+        // 执行ing阶段函数并获取当前数据
+        const ingEvent = assignWithDescriptors({
+            get phase() {
+                return "ing"
+            }
+        }, baseEvent)
+        const rawCurrentData = ing(ingEvent);
+        const currentData = typeof rawCurrentData === "object" && rawCurrentData !== null ? { ...rawCurrentData } : {};
+        // 触发end阶段监听器
+        const endEvent = assignWithDescriptors({
+            get phase() {
+                return "end"
+            },
+            get currentData() {
+                return { ...currentData }
+            }
+        }, baseEvent)
+        const endCallbackList = listenerMap.get(event + ":end") ?? []
+        for (const callback of endCallbackList) {
+            callback(endEvent)
+        }
+        // 触发after阶段监听器，并处理可能的递归事件调用
+        const afterEvent = assignWithDescriptors({
+            get phase() {
+                return "after"
+            },
+            get currentData() {
+                return { ...currentData }
+            }
+        }, baseEvent);
+        const afterCallbackList = listenerMap.get(event + ":after") ?? [];
+        for (const callback of afterCallbackList) {
+            const result = callback(afterEvent)
+            if (!isPlainObject(result)) continue;
+            const { event, ing, options } = result;
+            if (typeof event !== "string") continue;
+            dispatchSync(event, ing, options)
+        }
+    }
+    const on = (event, phase, callback) => {
+        throwIfIsNotString(event, "event");
+        throwIfIsNotExpectedValue(phase, "phase", "before", "begin", "end", "after");
+        throwIfIsNotFunction(callback, "callback");
+        const eventName = event + ":" + phase;
+        const funcList = listenerMap.get(eventName)
+        if (Array.isArray(funcList)) {
+            funcList.push(callback)
+        } else {
+            listenerMap.set(eventName, [callback]);
+        }
+    }
+    const off = (event, phase, callback) => {
+        throwIfIsNotString(event, "event");
+        throwIfIsNotExpectedValue(phase, "phase", "before", "begin", "end", "after");
+        throwIfIsNotFunction(callback, "callback");
+        const eventName = event + ":" + phase;
+        const list = listenerMap.get(eventName);
+        if (list) {
+            const index = list.indexOf(callback);
+            if (index !== -1) list.splice(index, 1);
+            if (list.length === 0) listenerMap.delete(eventName);
+        }
+    };
+    return {
+        dispatchSync,
+        on,
+        off
+    }
+}

package/src/guard.js

@@ -5,7 +5,6 @@
  */
 const getType = v => v === null ? "null" : typeof v
 
-
 class GuardError extends Error {
     /**
      * 
@@ -46,10 +45,51 @@ const throwRangeErrorGiveValue = (variable, name = "variable", ...acceptableRang
     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}.`)
 }
+
+/**
+ * 检查给定对象是否为普通对象
+ * 普通对象是指通过对象字面量 {} 或 new Object() 创建的对象，
+ * 不包括数组、函数以及其他自定义构造函数创建的实例
+ * @param {*} obj - 需要检查的对象
+ * @returns {boolean} 如果是普通对象返回 true，否则返回 false
+ */
+export function isPlainObject(obj) {
+    if (typeof obj !== "object" || obj === null) return false;
+    const prototype = Object.getPrototypeOf(obj);
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    return true
+}
+
 // ------------------------------------------------
 // 值校验守卫函数
 // ------------------------------------------------
-
+/**
+ * 检查变量是否为期望值之一，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @param {...*} expectedValues - 期望值列表
+ * @throws {TypeError} 当变量不是期望值之一时抛出类型错误
+ */
+export function throwIfIsNotExpectedValue(variable, name = "variable", ...expectedValues) {
+    safeGuardExecute(throwIfIsNotNonEmptyArray, ...expectedValues)
+    if (!expectedValues.includes(variable)) {
+        throwTypeErrorGiveType(variable, name, ...expectedValues);
+    }
+}
+/**
+ * 检查变量是否为不期望的值之一，如果是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @param {...*} unexpectedValues - 不期望的值列表
+ * @throws {TypeError} 当变量是不期望的值之一时抛出类型错误
+ */
+export function throwIfIsUnExpectedValue(variable, name = "variable", ...unexpectedValues) {
+    safeGuardExecute(throwIfIsNotNonEmptyArray, ...unexpectedValues)
+    if (unexpectedValues.includes(variable)) {
+        const [f, ...upexpedValuesWf] = unexpectedValues;
+        throwTypeErrorGiveType(variable, name, `not ${f}`, ...upexpedValuesWf);
+    }
+}
 /**
  * 检查变量是否为空值（不为 null 或 undefined）
  * @param {*} variable - 要检查的变量
@@ -231,6 +271,7 @@ export function throwIfIsNotBigInt(variable, name = "variable") {
 // ------------------------------------------------
 // 对象类型守卫函数
 // ------------------------------------------------
+
 /**
  * 检查变量是否为普通对象（非 null，非数组）
  * @param {*} variable - 要检查的变量
@@ -238,7 +279,7 @@ export function throwIfIsNotBigInt(variable, name = "variable") {
  * @throws {TypeError} 当变量不是普通对象时抛出类型错误
  */
 export function throwIfIsNotPlainObject(variable, name = "variable") {
-    if (typeof variable !== 'object' || variable === null || Array.isArray(variable)) {
+    if (!isPlainObject(variable)) {
         throwTypeErrorGiveType(variable, name, "a plain object");
     }
 }
@@ -381,18 +422,39 @@ export function throwIfIsNotIterableObject(variable, name = "") {
 //------------------------------------------------
 // 数组类型守卫函数
 // ------------------------------------------------
+/**
+ * 检查变量是否为数组，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @throws {TypeError} 当变量不是数组时抛出类型错误
+ */
 export function throwIfIsNotArray(variable, name = "variable") {
     if (!Array.isArray(variable)) {
         throwTypeErrorGiveType(variable, name, "an array");
     }
 }
+
+/**
+ * 检查变量是否为非空数组，如果不是则抛出错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @throws {TypeError} 当变量不是数组时抛出类型错误
+ * @throws {Error} 当变量是空数组时抛出错误
+ */
 export function throwIfIsNotNonEmptyArray(variable, name = "variable") {
     throwIfIsNotArray(variable, name);
     if (variable.length === 0) {
-        throwRangeErrorGiveValue(variable, name, "a non-empty array");
+        throw new Error(`Expected ${variable} to have at least one item, but got zero.`)
     }
 }
 
+/**
+ * 检查变量是否为仅包含字符串的数组，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @param {string} generalTerm - 通用术语（用于错误消息），默认值为`all elements of ${name || "array"}`
+ * @throws {TypeError} 当变量不是数组或包含非字符串元素时抛出类型错误
+ */
 export function throwIfIsNotStringArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
     throwIfIsNotArray(variable, name);
     const acceptType = "strings";
@@ -402,6 +464,54 @@ export function throwIfIsNotStringArray(variable, name = "variable", generalTerm
         }
     }
 }
+/**
+ * 检查变量是否为仅包含BigInt值的数组，如果不是则抛出类型错误
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或包含非BigInt元素时抛出类型错误
+ */
+export function throwIfIsNotBigIntArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "bigints";
+    for (const e of variable) {
+        if (typeof e !== "bigint") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-bigint value of type ${getType(e)}`)
+        }
+    }
+}
+/**
+ * 检查变量是否为仅包含Symbol值的数组，如果不是则抛出类型错误
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或包含非Symbol元素时抛出类型错误
+ */
+export function throwIfIsNotSymbolArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "symbols";
+    for (const e of variable) {
+        if (typeof e !== "symbol") {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-symbol value of type ${getType(e)}`)
+        }
+    }
+}
+/**
+ * 检查变量是否为仅包含普通对象的数组，如果不是则抛出类型错误
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或包含非普通对象元素时抛出类型错误
+ */
+export function throwIfIsNotPlainObjectArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
+    throwIfIsNotArray(variable, name);
+    const acceptType = "plain objects";
+    for (const e of variable) {
+        if (isPlainObject(variable)) {
+            throwTypeErrorForArray(generalTerm, acceptType, `a non-plain object value of type ${e}`)
+        }
+    }
+}
 export function throwIfIsNotNumberArray(variable, name = "variable", generalTerm = `all elements of ${name || "array"}`) {
     throwIfIsNotArray(variable, name);
     const acceptType = "numbers";

package/src/missingData.js

@@ -1,4 +1,4 @@
-import { throwIfIsNotNonNegativeInteger } from "./guard";
+import { throwIfIsNotNonNegativeInteger } from "./guard.js";
 
 /**
  * 前向填充（forward-fill）输入数据，向前填充无效值。

package/src/object.js

@@ -1,6 +1,12 @@
-import { throwIfIsNotPlainObject, throwIfKeyMissing } from "./guard";
-
-export function makeReadOnlyProperty(obj, name) {
+import { throwIfIsNotPlainObject, throwIfIsNotPlainObjectArray, throwIfKeyMissing } from "./guard.js";
+/**
+ * 将对象的指定属性设置为只读
+ * @param {Object} obj - 需要修改的对象
+ * @param {string} name - 需要设为只读的属性名
+ * @throws {TypeError} 当obj不是普通对象或name不是字符串时会抛出类型错误
+ * @throws {Error} 当对象中找不到指定属性时会抛出错误
+ */
+export function makePropertyReadOnly(obj, name) {
     throwIfIsNotPlainObject(obj);
     throwIfKeyMissing(obj, name, "obj");
     const descriptor = Object.getOwnPropertyDescriptor(obj, name);
@@ -10,4 +16,21 @@ export function makeReadOnlyProperty(obj, name) {
         configurable: false,
         enumerable: descriptor.enumerable ?? true
     })
+}
+
+/**
+ * 使用属性描述符将一个或多个源对象的属性分配到目标对象中
+ * @param {Object} target - 目标对象，将接收来自其他对象的属性
+ * @param {...Object} sources - 源对象列表，其所有可枚举和不可枚举属性都将被复制到目标对象中
+ * @throws {TypeError} 当target不是普通对象时抛出类型错误
+ * @throws {TypeError} 当sources中的任何一个元素不是普通对象时抛出类型错误
+ * @returns {void}
+ */
+export function assignWithDescriptors(target, ...sources) {
+    throwIfIsNotPlainObject(target);
+    throwIfIsNotPlainObjectArray(sources);
+    for (const obj of sources) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(obj))
+    }
+    return target;
 }

package/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./src/array.js";
+export * from "./src/event.js";
 export * from "./src/guard.js";
 export * from "./src/missingData.js";
 export * from "./src/object.js";

package/types/src/event.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 创建一个事件发射器对象，用于管理和触发自定义事件
+ * @returns {{
+ *  dispatchSync:(
+ *      event:string,
+ *      ing:(
+ *          ingEvent:{
+ *              target,name:string,type:string|null,preData:object,phase:"ing",data:object
+ *          })=>void,
+ *      options:{target,name:string,type:string|null,status:object,data:object}
+ *  )=>object
+ *  on:(event:string,phase:"before"|"begin"|"end"|"after",callback:(event:{
+ *      target,name:string,type:string|null,preData:object,data:object
+ * })=>void)=>void
+ *  off:(event:string,phase:"before"|"begin"|"end"|"after",callback:(event:{
+ *      target,name:string,type:string|null,preData:object,data:object
+ * })=>void)=>void
+ * }} 包含dispatchSync, on, off方法的对象
+ */
+export function createEventEmitter(): {
+    dispatchSync: (event: string, ing: (ingEvent: {
+        target: any;
+        name: string;
+        type: string | null;
+        preData: object;
+        phase: "ing";
+        data: object;
+    }) => void, options: {
+        target: any;
+        name: string;
+        type: string | null;
+        status: object;
+        data: object;
+    }) => object;
+    on: (event: string, phase: "before" | "begin" | "end" | "after", callback: (event: {
+        target: any;
+        name: string;
+        type: string | null;
+        preData: object;
+        data: object;
+    }) => void) => void;
+    off: (event: string, phase: "before" | "begin" | "end" | "after", callback: (event: {
+        target: any;
+        name: string;
+        type: string | null;
+        preData: object;
+        data: object;
+    }) => void) => void;
+};

package/types/src/guard.d.ts

@@ -1,3 +1,27 @@
+/**
+ * 检查给定对象是否为普通对象
+ * 普通对象是指通过对象字面量 {} 或 new Object() 创建的对象，
+ * 不包括数组、函数以及其他自定义构造函数创建的实例
+ * @param {*} obj - 需要检查的对象
+ * @returns {boolean} 如果是普通对象返回 true，否则返回 false
+ */
+export function isPlainObject(obj: any): boolean;
+/**
+ * 检查变量是否为期望值之一，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @param {...*} expectedValues - 期望值列表
+ * @throws {TypeError} 当变量不是期望值之一时抛出类型错误
+ */
+export function throwIfIsNotExpectedValue(variable: any, name?: string, ...expectedValues: any[]): void;
+/**
+ * 检查变量是否为不期望的值之一，如果是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @param {...*} unexpectedValues - 不期望的值列表
+ * @throws {TypeError} 当变量是不期望的值之一时抛出类型错误
+ */
+export function throwIfIsUnExpectedValue(variable: any, name?: string, ...unexpectedValues: any[]): void;
 /**
  * 检查变量是否为空值（不为 null 或 undefined）
  * @param {*} variable - 要检查的变量
@@ -171,9 +195,53 @@ export function throwIfIsNotIterable(variable: any, name?: string): void;
  * @throws {TypeError} 当变量不是可迭代对象时抛出类型错误
  */
 export function throwIfIsNotIterableObject(variable: any, name?: string): void;
+/**
+ * 检查变量是否为数组，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @throws {TypeError} 当变量不是数组时抛出类型错误
+ */
 export function throwIfIsNotArray(variable: any, name?: string): void;
+/**
+ * 检查变量是否为非空数组，如果不是则抛出错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @throws {TypeError} 当变量不是数组时抛出类型错误
+ * @throws {Error} 当变量是空数组时抛出错误
+ */
 export function throwIfIsNotNonEmptyArray(variable: any, name?: string): void;
+/**
+ * 检查变量是否为仅包含字符串的数组，如果不是则抛出类型错误
+ * @param {*} variable - 要检查的变量
+ * @param {string} name - 变量名称（用于错误消息），默认值为"variable"
+ * @param {string} generalTerm - 通用术语（用于错误消息），默认值为`all elements of ${name || "array"}`
+ * @throws {TypeError} 当变量不是数组或包含非字符串元素时抛出类型错误
+ */
 export function throwIfIsNotStringArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 检查变量是否为仅包含BigInt值的数组，如果不是则抛出类型错误
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或包含非BigInt元素时抛出类型错误
+ */
+export function throwIfIsNotBigIntArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 检查变量是否为仅包含Symbol值的数组，如果不是则抛出类型错误
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或包含非Symbol元素时抛出类型错误
+ */
+export function throwIfIsNotSymbolArray(variable: any, name?: string, generalTerm?: string): void;
+/**
+ * 检查变量是否为仅包含普通对象的数组，如果不是则抛出类型错误
+ * @param {*} variable - 需要检查的变量
+ * @param {string} [name="variable"] - 变量名称，用于错误消息显示
+ * @param {string} [generalTerm=`all elements of ${name || "array"}`] - 通用术语，用于错误消息显示
+ * @throws {TypeError} 当变量不是数组或包含非普通对象元素时抛出类型错误
+ */
+export function throwIfIsNotPlainObjectArray(variable: any, name?: string, generalTerm?: string): void;
 export function throwIfIsNotNumberArray(variable: any, name?: string, generalTerm?: string): void;
 /**
  * 检查变量是否为仅包含非NaN数字的数组，如果不是则抛出类型错误

package/types/src/object.d.ts

@@ -1 +1,17 @@
-export function makeReadOnlyProperty(obj: any, name: any): void;
+/**
+ * 将对象的指定属性设置为只读
+ * @param {Object} obj - 需要修改的对象
+ * @param {string} name - 需要设为只读的属性名
+ * @throws {TypeError} 当obj不是普通对象或name不是字符串时会抛出类型错误
+ * @throws {Error} 当对象中找不到指定属性时会抛出错误
+ */
+export function makePropertyReadOnly(obj: Object, name: string): void;
+/**
+ * 使用属性描述符将一个或多个源对象的属性分配到目标对象中
+ * @param {Object} target - 目标对象，将接收来自其他对象的属性
+ * @param {...Object} sources - 源对象列表，其所有可枚举和不可枚举属性都将被复制到目标对象中
+ * @throws {TypeError} 当target不是普通对象时抛出类型错误
+ * @throws {TypeError} 当sources中的任何一个元素不是普通对象时抛出类型错误
+ * @returns {void}
+ */
+export function assignWithDescriptors(target: Object, ...sources: Object[]): void;