data-faker-plus 0.0.5 → 0.0.7

package/README.md

@@ -1,49 +1,46 @@
-# Data Faker
+# Getting Started
 
-注意下面的仅仅是演示案例，具体详情请参见
-[DataFaker 国外官网](https://df-docs-lgxj441cg-bloom-lmh.vercel.app/)
-[DataFaker 国内官网](https://ootjp8xe3-datafaker-9j23z0sk.maozi.io/)
+[Official Website](https://df-docs-lgxj441cg-bloom-lmh.vercel.app/)
+[中文官网](https://ootjp8xe3-datafaker-9j23z0sk.maozi.io/)
 
-## 起步
+## Introduction
 
-### 介绍
+`DataFaker` is a data generator that relies on `faker.js` under the hood while extending it with template syntax. It enables you to quickly generate various types of data, including referenced data and recursive data, meeting your data generation needs across different scenarios. It is particularly suitable for the following use cases:
 
-`DataFaker` 是一个数据生成器，底层依赖 `faker.js`，并在之上扩展了模板语法，能够帮助你快速生成各类的数据，包括引用数据和递归数据，满足你在不同场景下各类数据的生成需求。它特别适用于以下场景：
+- Mock data for front-end development
+- Unit testing and integration testing
+- API interface prototyping
+- Database sample data generation
+- Demonstration and teaching examples
 
-- 前端开发中的模拟数据
-- 单元测试和集成测试
-- API 接口原型设计
-- 数据库样本数据生成
-- 演示和教学用例
+[A Tribute to faker.js](https://faker.nodejs.cn/guide/)
 
-[致敬 faker.js](https://faker.nodejs.cn/guide/)
+## Features
 
-### 特性
+- **Non-intrusive**: `DataFaker` only enhances `faker.js` without modifying it. You can still use `faker.js` as you did before.
+- **Templating**: `DataFaker` defines data structures using templates, similar to defining database table structures.
+- **Model-oriented**: `DataFaker` encapsulates templates into models, using models as basic units and providing a model reuse mechanism to allow your data templates to be reused in multiple places.
+- **Context mechanism**: `DataFaker` adopts a context mechanism to maintain the correlation between data.
+- **Multi-language support**: Leveraging the underlying `faker.js`, `DataFaker` also supports more than 70 language environments.
+- **Multi-data source**: With the help of `faker.js`'s underlying database, `DataFaker` can generate data covering 26 categories such as animals and books.
+- **Configurable**: `DataFaker` supports personalized configuration methods.
 
-- 无侵入：`DataFaker` 对`faker.js`只做增强不做修改，你仍然可以像以前那样使用 `faker.js`
-- 模板化：`DataFaker`以模板的方式来定义数据结构，就像定义数据库表结构那样
-- 面向模型：`DataFaker`将模板封装为了模型，以模型为基本单元，提供了模型复用机制，让你的数据模板可在多处复用
-- 上下文机制：`DataFaker`采用上下文机制保持数据之间的关联性
-- 多语言：`DataFaker`底层依托`faker.js`，其同样也支持 `70` 多种语言环境
-- 多数据源：`DataFaker` 借助了 `faker.js` 的底层数据库，能够生成涵盖动物、书本等 `26` 类数据
-- 可配置：`DataFaker` 支持个性化配置方式
+# Basic Usage
 
-## 基本使用
+Using `DataFaker` is very simple; you just need to:
 
-`DataFaker`使用起来十分的简单，你只需要：
+1. Define a data model
+2. Generate data
 
-1. 定义数据模型
-2. 生成数据
+## Defining a Model - defineModel
 
-### 定义模型-defineModel
+The `defineModel` method is used to define a data model and accepts two parameters:
 
-`defineModel`方法用于定义数据模型，它接受两个参数：
-
-- 模型名称
-- 数据模板
+- Model name
+- Data template
 
 ```ts
-// 定义模型
+// Define the model
 const userModel = defineModel('user', {
   id: 'string.uuid',
   name: 'person.fullName',
@@ -51,17 +48,17 @@ const userModel = defineModel('user', {
 });
 ```
 
-### 生成数据-fakeData
+## Generating Data - fakeData
 
-使用`fakeData`函数并传入数据模型就能生成模型模板对象的数据，如下所示：
+Use the `fakeData` function and pass in the data model to generate data matching the model template object, as shown below:
 
 ```ts
-// 生成数据
+// Generate data
 const data = fakeData(userModel);
 console.log(data);
 ```
 
-生成的数据如下：
+The generated data is as follows:
 
 ```json
 {
@@ -71,11 +68,11 @@ console.log(data);
 }
 ```
 
-## 核心概念
+# Core Concepts
 
-### 模板语法
+## Template Syntax
 
-`DataFaker`通过模板来定义数据结构，就像定义一个数据库表那样，每一个数据结构就是一个`schema`。
+`DataFaker` defines data structures through templates, just like defining a database table—each data structure is a `schema`.
 
 ```ts {15-20}
 const addressModel = defineModel('address', {
@@ -85,17 +82,17 @@ const addressModel = defineModel('address', {
 const userModel = defineModel('user', {
   id: 'number.int',
   firstName: 'person.firstName',
-  secondeName: 'person.lastName',
+  secondName: 'person.lastName',
   age: ['number.int', { min: 18, max: 65 }],
-  hobby: ['helpers.arrayElements', ['篮球', '足球', '乒乓球', '羽毛球']],
+  hobby: ['helpers.arrayElements', ['Basketball', 'Football', 'Table Tennis', 'Badminton']],
   email: ctx => {
-    return faker.internet.email({ firstName: ctx.firstName, lastName: ctx.secondeName });
+    return faker.internet.email({ firstName: ctx.firstName, lastName: ctx.secondName });
   },
   address: addressModel,
   children: {
-    // 引用自身，此时必须使用模型别名'user'而不能使用userModel
+    // Reference the model itself; in this case, you must use the model alias 'user' instead of userModel
     refModel: 'user',
-    // 控制自引用递归深度
+    // Control the depth of self-referential recursion
     deep: 3,
   },
 });
@@ -103,17 +100,17 @@ const userDatas = fakeData(userModel);
 console.dir(userDatas, { depth: Infinity });
 ```
 
-### 模型复用
+## Model Reuse
 
-使用`cloneModel`函数我们能够克隆一个模型，其需要提供两个参数
+The `cloneModel` function allows you to clone a model, which requires two parameters:
 
-- 参数 【1】：克隆的新的模型别名
-- 参数 【2】：要克隆的模型对象
+- Parameter [1]: The alias of the new cloned model
+- Parameter [2]: The model object to be cloned
 
-比如我们以`userModel`模型为原型，克隆出了一个学生模型，并将其别名命名为`studentModel`
+For example, we take the `userModel` as a prototype to clone a student model and name its alias `studentModel`:
 
 ```ts {2,17-19}
-// 用户模型
+// User model
 const userModel = defineModel('user', {
   id: 'number.int',
   firstName: 'person.firstName',
@@ -124,17 +121,17 @@ const userModel = defineModel('user', {
   },
   children: {
     refModel: 'user',
-    // 控制自引用递归深度
+    // Control the depth of self-referential recursion
     deep: 1,
   },
 });
-// 克隆学生模型
+// Clone the student model
 const studentModel = cloneModel('student', userModel);
 const studentDatas = fakeData(studentModel);
 console.dir(studentDatas, { depth: Infinity });
 ```
 
-生成数据如下：
+The generated data is as follows:
 
 ```json
 {
@@ -161,16 +158,16 @@ console.dir(studentDatas, { depth: Infinity });
 }
 ```
 
-### 钩子函数
+## Hook Functions
 
-钩子函数就是在数据生成前后或数据生成中执行的函数，它能让你在数据生成前后或数据生成中操作数据项和模板，改变数据生成方式，`DataFaker`提供了四类钩子函数：
+Hook functions are functions executed before, after, or during data generation. They allow you to manipulate data items and templates before, after, or during data generation, changing the way data is generated. `DataFaker` provides four types of hook functions:
 
-- 数据生成前操作模板-`beforeAllCbs`
-- 数据生成后操作数据-`afterAllCbs`
-- 数据项生成前设置模板-`beforeEachCbs`
-- 数据项生成后操作数据-`afterEachCbs`
+- `beforeAllCbs`: Manipulate templates before data generation
+- `afterAllCbs`: Manipulate data after data generation
+- `beforeEachCbs`: Set templates before data item generation
+- `afterEachCbs`: Manipulate data after data item generation
 
-> 比如我希望为所有引用数据添加 id`属性
+> For example, if you want to add an `id` attribute to all referenced data:
 
 ```ts
 const addressModel = defineModel('address', {
@@ -180,7 +177,7 @@ const addressModel = defineModel('address', {
     refModel: 'address',
   },
 });
-// 用户模型
+// User model
 const userModel = defineModel('user', {
   firstName: 'person.firstName',
   secondName: 'person.lastName',
@@ -191,7 +188,7 @@ const userDatas = fakeData(userModel, {
   hooks: {
     afterEachCbs: ctx => {
       if (ctx.type === 'object' && ctx.value) {
-        // 对所有引用类型添加id
+        // Add an id to all reference types
         ctx.value['id'] = faker.string.uuid();
       }
       return ctx;
@@ -201,7 +198,7 @@ const userDatas = fakeData(userModel, {
 console.dir(userDatas, { depth: Infinity });
 ```
 
-生成数据如下：
+The generated data is as follows:
 
 ```ts
 {
@@ -222,9 +219,9 @@ console.dir(userDatas, { depth: Infinity });
 }
 ```
 
-### 引用数据和自引用
+## Referenced Data and Self-Reference
 
-`DataFaker`支持引用数据和生成自引用递归数据
+`DataFaker` supports referenced data and the generation of self-referential recursive data.
 
 ```ts
 const addressModel = defineModel('address', {
@@ -236,7 +233,7 @@ const addressModel = defineModel('address', {
     deep: 1,
   },
 });
-// 用户模型
+// User model
 const userModel = defineModel('user', {
   firstName: 'person.firstName',
   secondName: 'person.lastName',
@@ -251,7 +248,7 @@ const userDatas = fakeData(userModel);
 console.dir(userDatas, { depth: Infinity });
 ```
 
-生成数据如下：
+The generated data is as follows:
 
 ```json
 {
@@ -259,11 +256,11 @@ console.dir(userDatas, { depth: Infinity });
   "secondName": "Adams",
   "age": 41,
   "address": [
-    // 第一个address数据
+    // First address data
     {
       "country": "Democratic Republic of the Congo",
       "city": "Elisefurt",
-      // 递归1层
+      // 1 level of recursion
       "children": [
         {
           "country": "Nauru",
@@ -275,7 +272,7 @@ console.dir(userDatas, { depth: Infinity });
         }
       ]
     },
-    // 第二个address数据
+    // Second address data
     {
       "country": "Ecuador",
       "city": "Hamillworth",
@@ -291,7 +288,7 @@ console.dir(userDatas, { depth: Infinity });
       ]
     }
   ],
-  // 第一层children
+  // First-level children
   "children": {
     "firstName": "Lisette",
     "secondName": "Gutmann",
@@ -326,7 +323,7 @@ console.dir(userDatas, { depth: Infinity });
         ]
       }
     ],
-    // 第二层children
+    // Second-level children
     "children": {
       "firstName": "Rex",
       "secondName": "Farrell",
@@ -366,19 +363,20 @@ console.dir(userDatas, { depth: Infinity });
 }
 ```
 
-## 装饰器语法
+# Decorator Syntax
+
+## Basic Usage
 
-### 基本使用
+To better support TypeScript, `DataFaker` introduces decorator syntax. Essentially, decorator syntax is syntactic sugar for `defineModel`, designed to maintain compatibility between existing classes and models.
 
-`DataFaker`为了更好的支持`ts`,引入了装饰器语法，装饰器语法本质上就是`defineModel`的语法糖，它设计的初衷就是为了保持现有类和模型的共通性。
-比如现在项目中本来就有`User`和`Address`两个类作为 ts 类型
+For example, if your project already has two classes (`User` and `Address`) used as TypeScript types:
 
 ```ts
 class Address {
   declare city: string;
   declare children: Address[];
 }
-// 用户类
+// User class
 class User {
   declare id: string;
   declare firstName: string;
@@ -390,12 +388,12 @@ class User {
 }
 ```
 
-为了将这两个类利用起来，而不是重新使用`defineModel`来定义数据模型，我们可以使用装饰器语法来将现有的类型类定义为`User`和`Address`数据模型。
+To utilize these two classes instead of redefining data models with `defineModel`, you can use decorator syntax to define the existing type classes as `User` and `Address` data models:
 
-- 使用`@DataModel`装饰器定义数据模型，它接受一个模型别名作为参数
-- 使用`@DataField`装饰器来定义字段，与[模板语法](/模板语法)中定义字段是一致的
+- Use the `@DataModel` decorator to define a data model, which accepts a model alias as a parameter.
+- Use the `@DataField` decorator to define fields, consistent with field definition in [Template Syntax](/Template-Syntax).
 
-如下所示：
+As shown below:
 
 ```ts
 @DataModel('address')
@@ -428,7 +426,7 @@ const userDatas = fakeData('user', 2);
 console.dir(userDatas, { depth: Infinity });
 ```
 
-数据生成结果如下：
+The data generation result is as follows:
 
 ```ts
 [
@@ -467,9 +465,9 @@ console.dir(userDatas, { depth: Infinity });
 ];
 ```
 
-### 基于原生基础的数据模型继承
+## Data Model Inheritance Based on Native Classes
 
-装饰器语法可以更加方便的实现模型继承，只需要像原生继承那样，无需做任何改动，如下所示，`User` 类从 `Person` 类的数据模型中继承了 `email` 和 `children` 字段：
+Decorator syntax enables easier model inheritance—simply follow the native inheritance approach without any additional modifications. As shown below, the `User` class inherits the `email` and `children` fields from the `Person` class data model:
 
 ```ts
 @DataModel('person')
@@ -496,7 +494,7 @@ const userDatas = fakeData('user', 2);
 console.dir(userDatas, { depth: Infinity });
 ```
 
-生成数据如下：
+The generated data is as follows:
 
 ```ts
 [
@@ -531,14 +529,14 @@ console.dir(userDatas, { depth: Infinity });
 ];
 ```
 
-## 多种配置方式
+# Multiple Configuration Methods
 
-### 全局配置
+## Global Configuration
 
-下面演示全局定义数据生成钩子函数
+The following demonstrates defining data generation hook functions globally:
 
 ```ts
-// 全局定义beforeAllCbs回调函数
+// Globally define the beforeAllCbs callback function
 DataFaker.setHooks({
   beforeAllCbs: schema => {
     console.log(schema);
@@ -547,9 +545,9 @@ DataFaker.setHooks({
 });
 ```
 
-### 模板中配置
+## Configuration in Templates
 
-下面演示模板中定义引用类型生成数量
+The following demonstrates defining the number of generated reference types in a template:
 
 ```ts
 const userModel = defineModel('user', {
@@ -560,21 +558,21 @@ const userModel = defineModel('user', {
 });
 ```
 
-### 运行时配置
+## Runtime Configuration
 
-下面展示运行时配置引用数据生成方式
+The following shows configuring the generation method of referenced data at runtime:
 
 ```ts
 const userDatas = fakeData(userModel, {
   refRules: {
-    // address引用数据生成一个，然后其address.childern自引用数据生成一个
+    // Generate 1 piece of address reference data, and then generate 1 piece of address.children self-referential data
     address: {
       [COUNT]: 1,
       children: {
         [COUNT]: 1,
       },
     },
-    // 自引用递归深度为1，且只生成一个，address引用属性同上
+    // The self-referential recursion depth is 1, and only 1 piece of data is generated; the address reference property is the same as above
     children: {
       [DEEP]: 1,
       [COUNT]: 1,