@qubit-ltd/common-decorator 3.10.0 → 3.10.2

package/README.md

@@ -21,6 +21,7 @@ With this library, you can easily add common methods to your domain classes, imp
 - **Normalization Support**: `@Normalizable` decorator enables field normalization
 - **Type Safety**: `@Type` and `@ElementType` decorators for type checking
 - **Serialization Utilities**: Built-in JSON serialization/deserialization support
+- **Utility Functions**: Standalone helper functions for ID conversion, JSON serialization, and more
 - **High Test Coverage**: Comprehensive test suite ensuring reliability of all features
 
 ## Installation
@@ -79,6 +80,17 @@ pnpm add @qubit-ltd/common-decorator
 - [Configuration](#configuration)
   - [Bundling with webpack](#webpack)
   - [Bundling with vite](#vite)
+- [Utility Functions](#utility-functions)
+  - [stringifyId](#stringifyId)
+  - [toJSON](#util-toJSON)
+  - [toJsonString](#util-toJsonString)
+  - [hasOwnProperty](#hasOwnProperty)
+  - [hasOwnPrototypeFunction](#hasOwnPrototypeFunction)
+  - [hasPrototypeFunction](#hasPrototypeFunction)
+  - [getDefaultInstance](#getDefaultInstance)
+  - [getFieldType](#getFieldType)
+  - [getFieldElementType](#getFieldElementType)
+  - [getSourceField](#getSourceField)
 - [Recent Updates](#recent-updates)
 - [Contributing](#contributing)
 - [License](#license)
@@ -1163,6 +1175,328 @@ must be at least `7.24.0`.
     });
     ```
 
+## <span id="utility-functions">Utility Functions</span>
+
+The library provides several standalone utility functions that can be used without decorating classes.
+
+### <span id="stringifyId">stringifyId(id)</span>
+
+- Parameters:
+  - `id: string|number|bigint`: The ID to be converted to a string.
+- Returns:
+  - `string`: The string representation of the ID, or an empty string if the ID is `null` or `undefined`.
+
+This function converts an ID to a string representation. It handles different types of IDs:
+- If the ID is `null` or `undefined`, it returns an empty string.
+- If the ID is already a string, it returns the string as is.
+- If the ID is a number or bigint, it converts it to a string.
+- If the ID is any other type of object, it serializes it to a JSON string.
+
+```javascript
+import { stringifyId } from '@qubit-ltd/common-decorator';
+
+stringifyId(123);          // "123"
+stringifyId("abc");        // "abc"
+stringifyId(123456789012345678901n);  // "123456789012345678901"
+stringifyId(null);         // ""
+stringifyId(undefined);    // ""
+stringifyId({ id: 123 });  // '{"id":123}'
+```
+
+### <span id="util-toJSON">toJSON(value, options)</span>
+
+- Parameters:
+  - `value: any`: The value to be converted to a JSON-serializable object.
+  - `options: null|undefined|object`: Additional options for serialization.
+- Returns:
+  - `object`: A plain JavaScript object ready to be serialized by `JSON.stringify()`.
+
+This function converts a value to an object that can be serialized by `JSON.stringify()`. If the value has a `toJSON()` method, it will use that method to determine what data to serialize.
+
+Available options include:
+- `normalize: boolean`: Whether to normalize the object before serializing (default: `true`).
+- `removeEmptyFields: boolean`: Whether to remove empty fields from the object (default: `false`).
+- `convertNaming: boolean`: Whether to convert property names to a different naming style (default: `false`).
+- `sourceNamingStyle: string`: The naming style of source object (default: `'LOWER_CAMEL'`).
+- `targetNamingStyle: string`: The naming style for the resulting object (default: `'LOWER_UNDERSCORE'`).
+- `space: string|number`: Whitespace for formatting (default: `null`).
+
+```javascript
+import { toJSON } from '@qubit-ltd/common-decorator';
+
+const user = {
+  firstName: 'John',
+  lastName: 'Doe',
+  age: 30,
+  toJSON() {
+    return {
+      fullName: `${this.firstName} ${this.lastName}`,
+      age: this.age,
+    };
+  },
+};
+
+// Using the object's toJSON method
+const result = toJSON(user);
+// { fullName: 'John Doe', age: 30 }
+
+// Converting naming style
+const resultWithNaming = toJSON(user, {
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_CAMEL',
+  targetNamingStyle: 'LOWER_UNDERSCORE',
+});
+// { full_name: 'John Doe', age: 30 }
+```
+
+### <span id="util-toJsonString">toJsonString(obj, options)</span>
+
+- Parameters:
+  - `obj: object`: The object to be serialized into a JSON string.
+  - `options: null|undefined|object`: Additional options for serialization.
+- Returns:
+  - `string`: A JSON string representation of the object.
+
+This function serializes an object to a JSON string with additional options. It supports native `bigint` values and other customization options.
+
+Available options are the same as for `toJSON()`.
+
+```javascript
+import { toJsonString } from '@qubit-ltd/common-decorator';
+
+const user = {
+  firstName: 'John',
+  lastName: 'Doe',
+  age: 30,
+};
+
+// Basic serialization
+const json = toJsonString(user);
+// '{"firstName":"John","lastName":"Doe","age":30}'
+
+// Pretty-printed JSON with naming style conversion
+const prettyJson = toJsonString(user, {
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_CAMEL',
+  targetNamingStyle: 'LOWER_UNDERSCORE',
+  space: 2,
+});
+/*
+{
+  "first_name": "John",
+  "last_name": "Doe", 
+  "age": 30
+}
+*/
+
+// Handling bigint values
+const bigData = {
+  id: 9223372036854775807n,
+  name: 'Big Integer'
+};
+toJsonString(bigData);
+// '{"id":9223372036854775807,"name":"Big Integer"}'
+```
+
+### <span id="hasOwnProperty">hasOwnProperty(Class, field)</span>
+
+- Parameters:
+  - `Class: function`: The constructor of the class to check.
+  - `field: string`: The name of the property to check for.
+- Returns:
+  - `boolean`: Returns true if and only if the property is directly defined by the class (either on its prototype or default instance), not inherited from parent classes.
+
+This function determines whether a class directly owns a specific property. Unlike JavaScript's built-in `Object.prototype.hasOwnProperty`, this function accepts a class constructor rather than an object instance, checks both the prototype and default instance, and only reports properties owned directly by the class, not those inherited from parent classes.
+
+```javascript
+import { hasOwnProperty } from '@qubit-ltd/common-decorator';
+
+class Parent {
+  constructor() {
+    this.parentField = 'parent';
+  }
+}
+
+class Child extends Parent {
+  constructor() {
+    super();
+    this.childField = 'child';
+  }
+}
+
+hasOwnProperty(Child, 'childField');  // true
+hasOwnProperty(Child, 'parentField'); // false (inherited from Parent)
+```
+
+### <span id="hasOwnPrototypeFunction">hasOwnPrototypeFunction(Class, name)</span>
+
+- Parameters:
+  - `Class: function`: Constructor for the specified class.
+  - `name: string`: The name of the specified prototype function.
+- Returns:
+  - `boolean`: Returns true if and only if the specified function is directly defined on the prototype of the class itself (not inherited from parent classes).
+
+This function determines whether the specified prototype function is directly defined in the prototype of a specified class (not inherited from parent classes). It uses `Object.prototype.hasOwnProperty` to ensure only "own properties" of the prototype are considered.
+
+```javascript
+import { hasOwnPrototypeFunction } from '@qubit-ltd/common-decorator';
+
+class Parent {
+  parentMethod() { return 'parent'; }
+}
+
+class Child extends Parent {
+  childMethod() { return 'child'; }
+}
+
+hasOwnPrototypeFunction(Child, 'childMethod');  // true
+hasOwnPrototypeFunction(Child, 'parentMethod'); // false (inherited from Parent)
+```
+
+### <span id="hasPrototypeFunction">hasPrototypeFunction(Class, name)</span>
+
+- Parameters:
+  - `Class: function`: Constructor for the specified class.
+  - `name: string`: The name of the specified prototype function.
+- Returns:
+  - `boolean`: Returns true if the specified function exists anywhere in the prototype chain of the class, whether defined by the class itself or inherited from a parent class.
+
+This function determines whether the specified prototype function exists anywhere in the prototype chain of a specified class. It checks the entire prototype chain, including methods inherited from parent classes, using `Reflect.has()`.
+
+```javascript
+import { hasPrototypeFunction } from '@qubit-ltd/common-decorator';
+
+class Parent {
+  parentMethod() { return 'parent'; }
+}
+
+class Child extends Parent {
+  childMethod() { return 'child'; }
+}
+
+hasPrototypeFunction(Child, 'childMethod');  // true
+hasPrototypeFunction(Child, 'parentMethod'); // true (inherited from Parent)
+```
+
+### <span id="getDefaultInstance">getDefaultInstance(Class)</span>
+
+- Parameters:
+  - `Class: function`: The constructor of the specified class.
+- Returns:
+  - `object`: The default instance of the specified class, or a new instance will be created if it does not exist.
+
+This function gets the default instance of the specified class, or creates a new instance if it does not exist. It's used internally by many of the library's functions to get default values.
+
+```javascript
+import { getDefaultInstance } from '@qubit-ltd/common-decorator';
+
+class User {
+  constructor() {
+    this.name = '';
+    this.age = 0;
+  }
+}
+
+const defaultUser = getDefaultInstance(User);
+console.log(defaultUser.name); // ''
+console.log(defaultUser.age);  // 0
+```
+
+### <span id="getFieldType">getFieldType(Class, field, path, options)</span>
+
+- Parameters:
+  - `Class: function`: The constructor of the class of the object.
+  - `field: string`: The name of the field.
+  - `path: string` (optional): The path of the field in the property tree of the original root object.
+  - `options: object` (optional): Additional options for type resolution.
+- Returns:
+  - `function|undefined`: The type of the specified field of the object, or `undefined` if the field type cannot be inferred.
+
+This function gets the type of the specified field of an object. It first checks the annotated type information, then the additional type information in options, and finally tries to infer from the default field value.
+
+```javascript
+import { getFieldType } from '@qubit-ltd/common-decorator';
+
+class Address {
+  constructor() {
+    this.street = '';
+    this.city = '';
+  }
+}
+
+class User {
+  constructor() {
+    this.name = '';
+    this.address = new Address();
+  }
+}
+
+const addressType = getFieldType(User, 'address');
+console.log(addressType === Address); // true
+```
+
+### <span id="getFieldElementType">getFieldElementType(Class, field, path, options)</span>
+
+- Parameters:
+  - `Class: function`: The constructor of the class of the object.
+  - `field: string`: The name of the field.
+  - `path: string` (optional): The path of the field in the property tree of the original root object.
+  - `options: object` (optional): Additional options for type resolution.
+- Returns:
+  - `function|null`: The element type of the specified field of the object, or `null` if the field element type cannot be inferred.
+
+This function gets the element type of a field of an object, particularly useful for collections (arrays, sets, maps). It checks annotated element type information, additional type information in options, and tries to infer from default field values.
+
+```javascript
+import { getFieldElementType, ElementType } from '@qubit-ltd/common-decorator';
+
+class Item {
+  constructor() {
+    this.id = 0;
+    this.name = '';
+  }
+}
+
+class Shop {
+  constructor() {
+    this.items = [];
+  }
+}
+
+// Using decorator to specify element type
+class DecoratedShop {
+  constructor() {
+    this.items = [];
+  }
+}
+ElementType(Item)(DecoratedShop, 'items');
+
+console.log(getFieldElementType(DecoratedShop, 'items') === Item); // true
+```
+
+### <span id="getSourceField">getSourceField(targetField, options)</span>
+
+- Parameters:
+  - `targetField: string`: The key of the target object.
+  - `options: object`: The options for naming style conversion.
+- Returns:
+  - `string`: The corresponding key of the source object.
+
+This function gets the name of the field of the source object from the corresponding field of the target object, supporting naming style conversion between different conventions (camelCase, snake_case, etc.).
+
+```javascript
+import { getSourceField } from '@qubit-ltd/common-decorator';
+
+const options = {
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_UNDERSCORE',
+  targetNamingStyle: 'LOWER_CAMEL',
+};
+
+const sourceField = getSourceField('firstName', options);
+console.log(sourceField); // 'first_name'
+```
+
 ## <span id="recent-updates">Recent Updates</span>
 
 ### Test Coverage Enhancements (December 2023)

package/README.zh_CN.md

@@ -21,6 +21,7 @@
 - **规范化支持**：`@Normalizable` 装饰器实现字段规范化
 - **类型安全**：`@Type` 和 `@ElementType` 装饰器用于类型检查
 - **序列化工具**：内置 JSON 序列化/反序列化支持
+- **工具函数**：独立的辅助函数，用于ID转换、JSON序列化等功能
 - **高测试覆盖率**：全面的测试套件确保所有功能的可靠性
 
 ## 安装
@@ -79,6 +80,17 @@ pnpm add @qubit-ltd/common-decorator
 - [配置](#configuration)
     - [使用 webpack 打包](#webpack)
     - [使用 vite 打包](#vite)
+- [工具函数](#utility-functions)
+    - [stringifyId](#stringifyId)
+    - [toJSON](#util-toJSON)
+    - [toJsonString](#util-toJsonString)
+    - [hasOwnProperty](#hasOwnProperty)
+    - [hasOwnPrototypeFunction](#hasOwnPrototypeFunction)
+    - [hasPrototypeFunction](#hasPrototypeFunction)
+    - [getDefaultInstance](#getDefaultInstance)
+    - [getFieldType](#getFieldType)
+    - [getFieldElementType](#getFieldElementType)
+    - [getSourceField](#getSourceField)
 - [最新更新](#recent-updates)
 - [贡献](#contributing)
 - [许可证](#license)
@@ -939,6 +951,328 @@ expect(opt1.convertNaming).toBe(false);
     });
     ```
 
+## <span id="utility-functions">工具函数</span>
+
+本库提供了几个独立的工具函数，可以在不装饰类的情况下使用。
+
+### <span id="stringifyId">stringifyId(id)</span>
+
+- 参数：
+    - `id: string|number|bigint`：要转换为字符串的ID。
+- 返回值：
+    - `string`：ID的字符串表示形式，如果ID为`null`或`undefined`，则返回空字符串。
+
+此函数将ID转换为字符串表示形式。它处理不同类型的ID：
+- 如果ID为`null`或`undefined`，则返回空字符串。
+- 如果ID已经是字符串，则按原样返回该字符串。
+- 如果ID是数字或bigint，则将其转换为字符串。
+- 如果ID是任何其他类型的对象，则将其序列化为JSON字符串。
+
+```javascript
+import { stringifyId } from '@qubit-ltd/common-decorator';
+
+stringifyId(123);          // "123"
+stringifyId("abc");        // "abc"
+stringifyId(123456789012345678901n);  // "123456789012345678901"
+stringifyId(null);         // ""
+stringifyId(undefined);    // ""
+stringifyId({ id: 123 });  // '{"id":123}'
+```
+
+### <span id="util-toJSON">toJSON(value, options)</span>
+
+- 参数：
+    - `value: any`：要转换为可JSON序列化对象的值。
+    - `options: null|undefined|object`：序列化的附加选项。
+- 返回值：
+    - `object`：可以被`JSON.stringify()`序列化的普通JavaScript对象。
+
+此函数将值转换为可以被`JSON.stringify()`序列化的对象。如果该值具有`toJSON()`方法，则将使用该方法来确定要序列化的数据。
+
+可用选项包括：
+- `normalize: boolean`：是否在序列化前规范化对象（默认值：`true`）。
+- `removeEmptyFields: boolean`：是否从对象中删除空字段（默认值：`false`）。
+- `convertNaming: boolean`：是否将属性名转换为不同的命名风格（默认值：`false`）。
+- `sourceNamingStyle: string`：源对象的命名风格（默认值：`'LOWER_CAMEL'`）。
+- `targetNamingStyle: string`：结果对象的命名风格（默认值：`'LOWER_UNDERSCORE'`）。
+- `space: string|number`：用于格式化的空白字符（默认值：`null`）。
+
+```javascript
+import { toJSON } from '@qubit-ltd/common-decorator';
+
+const user = {
+  firstName: 'John',
+  lastName: 'Doe',
+  age: 30,
+  toJSON() {
+    return {
+      fullName: `${this.firstName} ${this.lastName}`,
+      age: this.age,
+    };
+  },
+};
+
+// 使用对象的toJSON方法
+const result = toJSON(user);
+// { fullName: 'John Doe', age: 30 }
+
+// 转换命名风格
+const resultWithNaming = toJSON(user, {
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_CAMEL',
+  targetNamingStyle: 'LOWER_UNDERSCORE',
+});
+// { full_name: 'John Doe', age: 30 }
+```
+
+### <span id="util-toJsonString">toJsonString(obj, options)</span>
+
+- 参数：
+    - `obj: object`：要序列化为JSON字符串的对象。
+    - `options: null|undefined|object`：序列化的附加选项。
+- 返回值：
+    - `string`：对象的JSON字符串表示形式。
+
+此函数将对象序列化为具有附加选项的JSON字符串。它支持原生`bigint`值和其他自定义选项。
+
+可用选项与`toJSON()`相同。
+
+```javascript
+import { toJsonString } from '@qubit-ltd/common-decorator';
+
+const user = {
+  firstName: 'John',
+  lastName: 'Doe',
+  age: 30,
+};
+
+// 基本序列化
+const json = toJsonString(user);
+// '{"firstName":"John","lastName":"Doe","age":30}'
+
+// 带有命名风格转换的美化JSON
+const prettyJson = toJsonString(user, {
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_CAMEL',
+  targetNamingStyle: 'LOWER_UNDERSCORE',
+  space: 2,
+});
+/*
+{
+  "first_name": "John",
+  "last_name": "Doe", 
+  "age": 30
+}
+*/
+
+// 处理bigint值
+const bigData = {
+  id: 9223372036854775807n,
+  name: 'Big Integer'
+};
+toJsonString(bigData);
+// '{"id":9223372036854775807,"name":"Big Integer"}'
+```
+
+### <span id="hasOwnProperty">hasOwnProperty(Class, field)</span>
+
+- 参数：
+    - `Class: function`：要检查的类的构造函数。
+    - `field: string`：要检查的属性名称。
+- 返回值：
+    - `boolean`：仅当该属性由类直接定义（无论是在其原型上还是在默认实例上）而非从父类继承时，返回true。
+
+此函数确定一个类是否直接拥有特定属性。与JavaScript内置的`Object.prototype.hasOwnProperty`不同，此函数接受类构造函数而非对象实例，同时检查原型和默认实例，并且只报告由类直接拥有的属性，而非那些从父类继承的属性。
+
+```javascript
+import { hasOwnProperty } from '@qubit-ltd/common-decorator';
+
+class Parent {
+  constructor() {
+    this.parentField = 'parent';
+  }
+}
+
+class Child extends Parent {
+  constructor() {
+    super();
+    this.childField = 'child';
+  }
+}
+
+hasOwnProperty(Child, 'childField');  // true
+hasOwnProperty(Child, 'parentField'); // false (从Parent继承)
+```
+
+### <span id="hasOwnPrototypeFunction">hasOwnPrototypeFunction(Class, name)</span>
+
+- 参数：
+    - `Class: function`：指定类的构造函数。
+    - `name: string`：指定原型函数的名称。
+- 返回值：
+    - `boolean`：当且仅当指定函数直接定义在类本身的原型上（不是从父类继承）时返回true。
+
+此函数确定指定的原型函数是否直接定义在指定类的原型中（不是从父类继承）。它使用`Object.prototype.hasOwnProperty`来确保只考虑原型的"自有属性"。
+
+```javascript
+import { hasOwnPrototypeFunction } from '@qubit-ltd/common-decorator';
+
+class Parent {
+  parentMethod() { return 'parent'; }
+}
+
+class Child extends Parent {
+  childMethod() { return 'child'; }
+}
+
+hasOwnPrototypeFunction(Child, 'childMethod');  // true
+hasOwnPrototypeFunction(Child, 'parentMethod'); // false (从Parent继承)
+```
+
+### <span id="hasPrototypeFunction">hasPrototypeFunction(Class, name)</span>
+
+- 参数：
+    - `Class: function`：指定类的构造函数。
+    - `name: string`：指定原型函数的名称。
+- 返回值：
+    - `boolean`：如果指定函数存在于类的原型链中的任何位置（无论是由类本身定义还是从父类继承），则返回true。
+
+此函数确定指定的原型函数是否存在于指定类的原型链中的任何位置。它检查整个原型链，包括从父类继承的方法，使用`Reflect.has()`。
+
+```javascript
+import { hasPrototypeFunction } from '@qubit-ltd/common-decorator';
+
+class Parent {
+  parentMethod() { return 'parent'; }
+}
+
+class Child extends Parent {
+  childMethod() { return 'child'; }
+}
+
+hasPrototypeFunction(Child, 'childMethod');  // true
+hasPrototypeFunction(Child, 'parentMethod'); // true (从Parent继承)
+```
+
+### <span id="getDefaultInstance">getDefaultInstance(Class)</span>
+
+- 参数：
+    - `Class: function`：指定类的构造函数。
+- 返回值：
+    - `object`：指定类的默认实例，如果不存在则创建一个新实例。
+
+此函数获取指定类的默认实例，如果不存在则创建一个新实例。它被库的许多函数内部使用，以获取默认值。
+
+```javascript
+import { getDefaultInstance } from '@qubit-ltd/common-decorator';
+
+class User {
+  constructor() {
+    this.name = '';
+    this.age = 0;
+  }
+}
+
+const defaultUser = getDefaultInstance(User);
+console.log(defaultUser.name); // ''
+console.log(defaultUser.age);  // 0
+```
+
+### <span id="getFieldType">getFieldType(Class, field, path, options)</span>
+
+- 参数：
+    - `Class: function`：对象所属类的构造函数。
+    - `field: string`：字段的名称。
+    - `path: string`（可选）：字段在原始根对象的属性树中的路径。
+    - `options: object`（可选）：类型解析的附加选项。
+- 返回值：
+    - `function|undefined`：对象指定字段的类型，如果无法推断字段类型，则为`undefined`。
+
+此函数获取对象指定字段的类型。它首先检查注解的类型信息，然后检查选项中的附加类型信息，最后尝试从默认字段值推断。
+
+```javascript
+import { getFieldType } from '@qubit-ltd/common-decorator';
+
+class Address {
+  constructor() {
+    this.street = '';
+    this.city = '';
+  }
+}
+
+class User {
+  constructor() {
+    this.name = '';
+    this.address = new Address();
+  }
+}
+
+const addressType = getFieldType(User, 'address');
+console.log(addressType === Address); // true
+```
+
+### <span id="getFieldElementType">getFieldElementType(Class, field, path, options)</span>
+
+- 参数：
+    - `Class: function`：对象所属类的构造函数。
+    - `field: string`：字段的名称。
+    - `path: string`（可选）：字段在原始根对象的属性树中的路径。
+    - `options: object`（可选）：类型解析的附加选项。
+- 返回值：
+    - `function|null`：对象指定字段的元素类型，如果无法推断字段元素类型，则为`null`。
+
+此函数获取对象字段的元素类型，特别适用于集合（数组、集合、映射）。它检查注解的元素类型信息，选项中的附加类型信息，并尝试从默认字段值推断。
+
+```javascript
+import { getFieldElementType, ElementType } from '@qubit-ltd/common-decorator';
+
+class Item {
+  constructor() {
+    this.id = 0;
+    this.name = '';
+  }
+}
+
+class Shop {
+  constructor() {
+    this.items = [];
+  }
+}
+
+// 使用装饰器指定元素类型
+class DecoratedShop {
+  constructor() {
+    this.items = [];
+  }
+}
+ElementType(Item)(DecoratedShop, 'items');
+
+console.log(getFieldElementType(DecoratedShop, 'items') === Item); // true
+```
+
+### <span id="getSourceField">getSourceField(targetField, options)</span>
+
+- 参数：
+    - `targetField: string`：目标对象的键。
+    - `options: object`：命名风格转换的选项。
+- 返回值：
+    - `string`：源对象的对应键。
+
+此函数从目标对象的对应字段获取源对象的字段名称，支持不同命名规范（驼峰命名法、蛇形命名法等）之间的命名风格转换。
+
+```javascript
+import { getSourceField } from '@qubit-ltd/common-decorator';
+
+const options = {
+  convertNaming: true,
+  sourceNamingStyle: 'LOWER_UNDERSCORE',
+  targetNamingStyle: 'LOWER_CAMEL',
+};
+
+const sourceField = getSourceField('firstName', options);
+console.log(sourceField); // 'first_name'
+```
+
 ## <span id="recent-updates">最新更新</span>
 
 ### 测试覆盖增强（2023年12月）