docs: renaming attributes (#203)

fixes #199
cyjake · Oct 19, 2021 · 91f7871 · 91f7871
1 parent 96cbf9e
commit 91f7871
Show file tree

Hide file tree

Showing 24 changed files with 4,187 additions and 1,454 deletions.
diff --git a/.jsdoc.json b/.jsdoc.json
@@ -6,7 +6,7 @@
     "plugins/markdown"
   ],
   "source": {
-    "include": ["index.js", "lib", "Readme.md"],
+    "include": ["index.js", "src", "Readme.md"],
     "includePattern": ".js$",
     "excludePattern": "^(?:docs|node_modules|test)"
   },

diff --git a/docs/api/BIGINT.html b/docs/api/BIGINT.html
diff --git a/docs/api/Bone.html b/docs/api/Bone.html
diff --git a/docs/api/Collection.html b/docs/api/Collection.html
diff --git a/docs/api/DataType.html b/docs/api/DataType.html
diff --git a/docs/api/INTEGER.html b/docs/api/INTEGER.html
diff --git a/docs/api/IndexHint.IndexHint.html b/docs/api/IndexHint.IndexHint.html
diff --git a/docs/api/STRING.html b/docs/api/STRING.html
diff --git a/docs/api/Spell.html b/docs/api/Spell.html
diff --git a/docs/api/global.html b/docs/api/global.html
diff --git a/docs/api/index.html b/docs/api/index.html
diff --git a/docs/api/module-lib_bone.html b/docs/api/module-lib_bone.html
diff --git a/docs/api/module-src_bone.html b/docs/api/module-src_bone.html
diff --git a/docs/api/module-lib_expr.html → docs/api/module-src_expr.html b/docs/api/module-lib_expr.html → docs/api/module-src_expr.html
diff --git a/docs/api/module-lib_spell.html → docs/api/module-src_spell.html b/docs/api/module-lib_spell.html → docs/api/module-src_spell.html
diff --git a/docs/basics.md b/docs/basics.md
@@ -137,17 +137,27 @@ class Shop extends Bone {
 }
 ```
 
-You can rename the attribute names too. By default, these names are transformed from column names by calling `static renameAttribute(oldName, newName)` in the `static describe()` method.
+We can rename the attribute names too. By default, these names are transformed from column names by converting them into camel case. If the names don't match, we can specify the column names manually in `static attributes`, such as:
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static attributes = {
+    deletedAt: { type: DATE, columnName: 'removed_at' },
+  }
+}
+```
+
+We can also rename the attribute in the `static initialize()` method, which gets called after models are loaded.
+
+```js
+class Shop extends Bone {
+  static initialize() {
     this.renameAttribute('removedAt', 'deletedAt')
   }
 }
 ```
 
-A lot of schema settings can be done within the `static describe()` method. We'll get to that later.
+A lot of schema settings can be done within the `static initialize()` method. We'll get to that later.
 
 ## Connecting Models to Database
 

diff --git a/docs/index.md b/docs/index.md
@@ -10,7 +10,7 @@ const { Bone, connect } = require('leoric')
 
 // define model
 class Post extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('author', { Model: 'User' })
     this.hasMany('comments')
   }

diff --git a/docs/querying.md b/docs/querying.md
@@ -437,7 +437,7 @@ Predefined associations can be found by examining `Model.relations`, which is ge
 
 ```js
 class Post extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('comments')
     this.belongsTo('author', { foreignKey: 'authorId', Model: 'User' })
   }

diff --git a/docs/zh/associations.md b/docs/zh/associations.md
@@ -47,7 +47,7 @@ Leoric 支持四种关联关系：
 
 ```js
 class Item extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('shop')
   }
 }
@@ -57,7 +57,7 @@ Leoric 会把关联关系的名称 `shop` 转为驼峰、首字母大写，再
 
 ```js
 class Item extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('shop', { className: 'Seller' })
   }
 }
@@ -73,7 +73,7 @@ class Item extends Bone {
 
 ```js
 class Item extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('shop', { foreignKey: 'sellerId' })
   }
 }
@@ -89,7 +89,7 @@ class Item extends Bone {
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('items')
   }
 }
@@ -103,7 +103,7 @@ Leoric 寻找对应数据模型的方式都是差不多的。首先将关联关
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('items', { className: 'Commodity' })
   }
 }
@@ -113,7 +113,7 @@ class Shop extends Bone {
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('items', { foreignKey: 'sellerId' })
   }
 }
@@ -137,7 +137,7 @@ class Shop extends Bone {
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     // the extra where is needed if you fancy this generic tag system
     this.hasMany('tagMaps', { foreignKey: 'targetId', where: { targetType: 0 } })
     this.hasMany('tags', { through: 'tagMaps' })
@@ -149,7 +149,7 @@ class Shop extends Bone {
 
 ```js
 class Tag extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('shopTagMaps', { className: 'TagMap', where: { targetType: 0 } })
     this.hasMany('shops', { through: 'shopTagMaps' })
   }
@@ -160,7 +160,7 @@ class Tag extends Bone {
 
 ```diff
 class Tag extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('shopTagMaps', { className: 'TagMap', where: { targetType: 0 } })
     this.hasMany('shops', { through: 'shopTagMaps' })
 +   this.hasMany('itemTagMaps', { className: 'TagMap', where: { targetType: 1 } })
@@ -185,7 +185,7 @@ class Tag extends Bone {
 
 ```js
 class User extends Bone {
-  static describe() {
+  static initialize() {
     this.hasOne('shop', { foreignKey: 'ownerId' })
   }
 }
@@ -195,7 +195,7 @@ class User extends Bone {
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('owner', { className: 'User' })
   }
 }

diff --git a/docs/zh/basics.md b/docs/zh/basics.md
@@ -120,33 +120,43 @@ await Shop.create({ name: 'Horadric Cube' })
 
 ## 覆盖命名约定
 
-绝大部分命名约定都有对应的覆盖方法，我们可以使用 `static get table()` 覆盖表名：
+绝大部分命名约定都有对应的覆盖方法，我们可以使用 `static table` 覆盖表名：
 
 ```js
 class Shop extends Bone {
-  static get table() { return 'stores' }
+  static table = 'stores'
 }
 ```
 
 还可以使用 `static get primaryKey()` 指定主键名：
 
 ```js
 class Shop extends Bone {
-  static get primaryKey() { return 'shopId' }
+  static primaryKey = 'shopId' }
 }
 ```
 
-也可以重命名属性名，在 `static describe()` 方法中调用 `static renameAttribute(oldName, newName)` 即可：
+以及使用 `static attributes` 自定义数据模型属性对应的字段名：
 
 ```js
 class Shop extends Bone {
-  static describe() {
+  static attributes = {
+    deletedAt: { type: DATE, columnName: 'removed_at' },
+  }
+}
+```
+
+如果数据模型的属性信息不在模型中直接维护，也可以等数据模型信息从数据库加载后，在 `static initialize()` 方法中重命名属性名：
+
+```js
+class Shop extends Bone {
+  static initialize() {
     this.renameAttribute('removedAt', 'deletedAt')
   }
 }
 ```
 
-`static describe()` 方法中可配置的项目有很多。我们之后再详细讨论。
+`static initialize()` 方法中可配置的项目有很多。我们之后再详细讨论。
 
 ## 连接数据模型和数据库
 

diff --git a/docs/zh/index.md b/docs/zh/index.md
@@ -10,7 +10,7 @@ const { Bone, connect } = require('leoric')
 
 // 基于 Bone 定义模型，映射关系表
 class Post extends Bone {
-  static describe() {
+  static initialize() {
     this.belongsTo('author', { Model: 'User' })
     this.hasMany('comments')
   }

diff --git a/docs/zh/querying.md b/docs/zh/querying.md
@@ -431,7 +431,7 @@ Leoric 提供两种构建 JOIN 查询的方式：
 
 ```js
 class Post extends Bone {
-  static describe() {
+  static initialize() {
     this.hasMany('comments')
     this.belongsTo('author', { foreignKey: 'authorId', Model: 'User' })
   }

diff --git a/src/bone.js b/src/bone.js
@@ -820,7 +820,7 @@ class Bone {
    * restore rows
    * @param {Object} conditions query conditions
    * @param {Object?} opts query options
-   * @returns
+   * @returns {Spell}
    */
   static restore(conditions, opts = {}) {
     const { deletedAt } = this.timestamps;

diff --git a/src/spell.js b/src/spell.js
@@ -65,7 +65,7 @@ function parseSelect(spell, ...names) {
  * @param {Spell} spell
  * @param {Object} obj - key-value pairs of attributes
  * @param {boolean} strict - check attribute exist or not
- * @returns
+ * @returns {Object}
  */
 function formatValueSet(spell, obj, strict = true) {
   const { Model, silent = false, command } = spell;