Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

* add more options in model creation.

* more readme.
  • Loading branch information...
commit 0eb22c84222de362210ee5af1a84f71610b43191 1 parent 856e76d
@redblaze authored
Showing with 177 additions and 79 deletions.
  1. +172 −77 README.md
  2. +4 −1 lib/node-mysql.js
  3. +1 −1  package.json
View
249 README.md
@@ -1,6 +1,6 @@
# node-mysql
-An enhancement to the mysql lib to make it a bit easier to use. Based on mysql's existing funtionalities, it also
+An enhancement to the mysql lib to make it a bit easier to use. Based on the existing funtionalities of (npm) mysql, it also
* Handles transactions.
* Provides a simple ORM, which
@@ -44,9 +44,9 @@ var BaseTable = db.Table;
* [db.transaction](#db-transaction)
* [db.cursor](#db-cursor)
* [db.end](#db-end)
+ * [db.add](#db-add)
+ * [db.get](#db-get)
* [DB.format](#DB-format)
-* Row and Table
- * [define concrete classes](#row-table-instantiation)
* Table
* [new Table](#new-Table)
* [table.create](#table-create)
@@ -249,62 +249,178 @@ var cursorTest = function(cb) {
This function destructs the db object.
-<a name="DB-format" />
-### DB.format(query_string, variable_bindings)
+<a name="db-add"/>
-This is a wrapper of the query string formatting functionality
-provided by the mysql package. Note that this is a global static
-method defined on the class DB. It is NOT an instance method defined
-a a DB instance db.
+### db.add(config);
+
+This function is used to define a model that belongs to the db object. The model config object is of the following format:
+
+```json
+{
+ "name": {
+ "type": "String",
+ "description": "the name of the table"
+ },
+ "idFieldName": {
+ "type": "String",
+ "optional": true,
+ "default": "id",
+ "description": "the name of the primary id column"
+ },
+ "versionFieldName": {
+ "type": "String",
+ "optional": true,
+ "default": "version",
+ "description": "optimistic lock version"
+ },
+ "createdFieldName": {
+ "type": "String",
+ "optional": true,
+ "default": "date_created",
+ "description": "creation time of the row"
+ },
+ "updatedFieldName": {
+ "type": "String",
+ "optional": true,
+ "default": "last_updated",
+ "description": "last update time of the row"
+ },
+ "Row": {
+ "type": "Object",
+ "optional": true,
+ "default": "{}",
+ "description": "the overriding method definition for the Row class of this model"
+ },
+ "Table": {
+ "type": "Object",
+ "optional": true,
+ "default": "{}",
+ "description": "the overriding method definition for the Table class of this model"
+ }
+}
+```
+
+Note that db.add returns a Table object, which can be further chained
+with linking/joining functions such as [linksTo](#table-linksTo),
+[linkedBy](#table-linkedBy) and [relatesTo](#table-relatesTo).
__Example__
```javascript
-DB.format('select * from users where id = ?' [userId]);
+db.add({
+ name: 'orders',
+ idFieldName: 'order_id',
+ Row: {
+ getFirstOrderItem: function(conn, cb) {
+ var me = this;
+
+ cps.seq([
+ function(_, cb) {
+ me.linkedBy(conn, 'items', cb);
+ },
+ function(items, cb) {
+ cb(null, items[0]);
+ }
+ ], cb);
+ }
+ },
+ Table: {
+ createOrderUsingCoupon: function(conn, dto, coupon, cb) {
+ dto['coupon_id'] = coupon.getId();
+ this.create(conn, dto, cb);
+ }
+ }
+})
+ .linkedBy({
+ name: 'items',
+ key: 'order_id',
+ table: 'order_items'
+ })
+ .linksTo({
+ name: 'user',
+ key: 'user_id',
+ table: 'users'
+ })
+ .linksTo({
+ name: 'coupon',
+ key: 'coupon_id',
+ table: 'coupons'
+ })
+ .linksTo({
+ name: 'credit_card',
+ key: 'credit_card_id',
+ table: 'credit_cards'
+ })
+;
+
```
-<a name="row-table-instantiation" />
-### Concrete Classes for Row and Table
-Both Row and Table are abstract classes. They must be made concrete
-before being used. Here's an example to set up the Row and Table for
-a particular database table:
+In this example:
+
+* We created a model for the table "orders" in the database.
+* We add a method getFirstOrderItem into the Row class of this model.
+* We add a method createOrderWithCoupon into the Table class of this model.
+* We follow the foreign key relations of the "orders" table to define some link relations.
+
+<a name="db-get"/>
+### db.get(table_name)
+
+Once you use db.add to create a model in the db object, you can then
+use db.get to retrieve it by name. The return value of
+db.get if a object of the following format:
+
+```json
+{
+ "Row": {
+ "type": "Row object"
+ },
+ "Table": {
+ "type": "Table object"
+ }
+}
+```
__Example__
```javascript
+var Order = db.get('orders');
+var Coupon = db.get('coupons');
-var User = function() {
- var cls = {
- };
-
- var Row = Class(db.Row, {
- _init: function(data) {
- this.parent._init.call(this, data, {
- table: Table
- });
+db.connect(function(conn, cb) {
+ cps.seq([
+ function(_, cb) {
+ Coupon.Table.findByCode(conn, '10-percent-off', cb);
+ }
+ function(coupon, cb) {
+ var dto = {/*dto data*/};
+ Order.createOrderWithCoupon(conn, dto, coupon, cb);
+ },
+ function(order, cb) {
+ order.getFirstOrderItem(conn, cb);
+ },
+ function(firstItem, cb) {
+ console.log(firstItem);
+ cb()
}
- });
+ ], cb);
+}, cb);
+```
- var TableClass = Class(db.Table, {
- });
- var Table = new TableClass({
- 'name': 'users',
- 'idFieldName': 'id',
- 'rowClass': Row,
- 'db': dw
- });
+<a name="DB-format" />
+### DB.format(query_string, variable_bindings)
+
+This is a wrapper of the query string formatting functionality
+provided by the mysql package. Note that this is a global static
+method defined on the class DB. It is NOT an instance method defined
+a a DB instance db.
- $U.extend(cls, {
- Row: Row,
- Table: Table
- });
+__Example__
- return cls;
-}();
+```javascript
+DB.format('select * from users where id = ?' [userId]);
```
-
<a name="new-Table"/>
### new Table(table_config)
@@ -559,8 +675,8 @@ The config object has the following schema:
"description": "The key that belongs to the current table and links to another table."
},
"table": {
- "type": "Table"
- "description": "The Table object for the other table to join. This object must be constructed using the constructor of Table."
+ "type": "String",
+ "description": "The name of the table that the current table links to."
}
}
```
@@ -568,23 +684,16 @@ The config object has the following schema:
__Example__
```javascript
- var Table = new TableClass({
- 'name': 'orders',
- 'idFieldName': 'id',
- 'rowClass': Row,
- 'db': db.main
- });
-
- Table
+ Order.Table
.linksTo({
name: 'credit_card',
- table: CreditCard.Table,
key: 'credit_card_id'
+ table: 'credit_cards'
})
.linksTo({
name: 'shipping_address',
- table: Address.Table,
key: 'shipping_address_id'
+ table: 'addresses'
})
;
```
@@ -610,8 +719,8 @@ The config object has the following schema:
"description": "The key that belongs to the other table and links to the current table."
},
"table": {
- "type": "Table"
- "description": "The Table object for the other table to join. This object must be constructed using the constructor of Table."
+ "type": "String",
+ "description": "The name of the table that the current table is linked by."
}
}
```
@@ -619,14 +728,7 @@ The config object has the following schema:
__Example__
```javascript
- var Table = new TableClass({
- 'name': 'orders',
- 'idFieldName': 'id',
- 'rowClass': Row,
- 'db': db.main
- });
-
- Table
+ Order.Table
.linkedBy({
name: 'items',
table: OrderItem.Table,
@@ -652,16 +754,16 @@ The config object has the following schema:
"description": "The name of the field to add to the row's data."
},
"through": {
- "type": "Table",
- "description": "The Table object for the through table, which joins both the current table and the target table."
+ "type": "String",
+ "description": "The name of the through table, which joins both the current table and the target table."
},
"leftKey": {
"type": "String",
"description": "The key that belongs to the current table and joins with the through table."
},
"table": {
- "type": "Table"
- "description": "The Table object for the target table to include."
+ "type": "String",
+ "description": "The name of the target table that the current table is joining thourgh the through-table."
},
"rightKey": {
"type": "String",
@@ -673,20 +775,13 @@ The config object has the following schema:
__Example__
```javascript
- var Table = new TableClass({
- 'name': 'orders',
- 'idFieldName': 'id',
- 'rowClass': Row,
- 'db': db.main
- });
-
- Table
+ Order.Table
.relatesTo({
name: 'coupons',
- through: OrderCoupon.Table,
leftKey: 'order_id',
- table: Coupon.Table,
- rightKey: 'coupon_id'
+ through: 'order_coupons',
+ rightKey: 'coupon_id',
+ table: 'coupons'
})
;
```
View
5 lib/node-mysql.js
@@ -27,7 +27,10 @@ var DB = Class(_DB, {
db: this,
name: cfg.name,
rowClass: Row,
- idFieldName: cfg.idFieldName
+ idFieldName: cfg.idFieldName || 'id',
+ versionFieldName: cfg.versionFieldName || 'version',
+ createdFieldName: cfg.createdFieldName || 'date_created',
+ updatedFieldName: cfg.updatedFieldName || 'last_updated'
});
$U.extend(model, {
View
2  package.json
@@ -3,7 +3,7 @@
"description": "A wrapper of node.js mysql package to make it a bit easier to use.",
"main": "./lib/node-mysql",
"author": "Chiyan Chen",
- "version": "0.2.9",
+ "version": "0.3.0",
"repository" : {
"type" : "git",
"url" : "https://github.com/redblaze/node-mysql.git"
Please sign in to comment.
Something went wrong with that request. Please try again.