You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
JoinJS is a JavaScript library to map complex database joins to nested objects. It is a simpler alternative that gives you direct control over your database interactions compared to a full-blown Object-Relation Mapper (ORM).
3
+
JoinJS is a JavaScript library to map complex database joins to nested objects. It's a simpler alternative to a full-blown Object-Relation Mapper (ORM), but gives you direct control over your database interactions.
4
4
5
5
## Motivation
6
-
ORMs generally introduce a thick layer of abstraction between objects and the database which usually hinders rather than helps the productivity of the developer. In complex use cases, it is difficult enough to devise queries that will generate the desired results, but now you have to *teach*the ORM to generate the same query. For anyone who has worked with an ORM knows that that's extra time and you may not be able to produce the same query. In the worst case scenario, the ORM may hit the database multiple times for something that you were able to do in a single query.
6
+
ORMs generally introduce a thick layer of abstraction between objects and database tables. This usually hinders rather than helps developer productivity. In complex use cases, it is difficult enough to devise efficient queries, but with ORMs, you also have to *teach*them to generate the same query. It takes extra time to do this and you may not be able to produce the same query. In the worst case scenario, the ORM may hit the database multiple times for something that you were able to do in a single query.
7
7
8
-
JoinJS takes a much simpler approach (inspired by a Java library called [MyBatis](http://mybatis.github.io/mybatis-3/)). You can use any database driver or query builder (such as [Kenx.js](http://knexjs.org/)) to query your database, however you use JoinJS to convert the returned result set in to a hierarchy of nested objects.
8
+
JoinJS takes a much simple and straightforward approach inspired by a Java library called [MyBatis](http://mybatis.github.io/mybatis-3/). You can use any database driver or query builder (such as [Kenx.js](http://knexjs.org/)) to query your database, however you use JoinJS to convert the returned results to a hierarchy of nested objects.
9
9
10
10
## Example
11
-
Suppose you have a one-to-many relationship between a `Team` and its `Player`s. You want to retrieve all teams along with their players. Here's the query for to do this:
11
+
Suppose you have a one-to-many relationship between a `Team` and its `Players`. You want to retrieve all teams along with their players. Here's the query for to do this:
12
12
13
13
```sql
14
14
SELECTt.idAS team_id,
@@ -20,7 +20,7 @@ FROM teams t
20
20
ONt.id=p.team_id;
21
21
```
22
22
23
-
Assume that this query returns the following result set
23
+
Assume that this query returns the following result set:
24
24
25
25
```javascript
26
26
var resultSet = [
@@ -41,21 +41,21 @@ You can use JoinJS to convert this result set in to an array of teams with neste
41
41
name:'New England Patriots'
42
42
players: [
43
43
{ id:1, name:'Tom Brady' },
44
-
{ id:2, name:'Rob Gronkowski' },
44
+
{ id:2, name:'Rob Gronkowski' }
45
45
]
46
46
},
47
47
{
48
48
id:2,
49
49
name:'New York Jets'
50
50
players: [
51
51
{ id:1, name:'Tom Brady' },
52
-
{ id:2, name:'Rob Gronkowski' },
52
+
{ id:2, name:'Rob Gronkowski' }
53
53
]
54
54
}
55
55
]
56
56
```
57
57
58
-
To teach JoinJS how to do this, you must create result maps that describe your objects:
58
+
To teach JoinJS how to do this, you must create two result maps that describe your objects:
59
59
60
60
```javascript
61
61
var resultMaps = [
@@ -79,15 +79,13 @@ var resultMaps = [
79
79
]
80
80
```
81
81
82
-
Once you have created these result maps, you can simply call JoinJS to map your result set in to objects:
82
+
Once you have created these result maps, you can simply call JoinJS to convert your result set in to objects:
83
83
84
84
```javascript
85
85
var mappedResult =joinjs.map(resultSet, resultMaps, 'teamMap', 'team_');
86
86
```
87
87
88
-
That's it! It doesn't matter how deep or complex your object hierarchy is, JoinJS can map it for you by supplying the appropriate result maps. Read the documentation below for more details. You can find more examples in the [test suite](https://github.com/archfirst/joinjs/tree/master/test). Check out the following project for an example of a real application built with JoinJS:
89
-
90
-
-[Manage My Money](https://github.com/archfirst/manage-my-money-server) - An application to manage your personal finances
88
+
That's it! It doesn't matter how deep or complex your object hierarchy is, JoinJS can map it for you. Read the documentation below for more details. You can find more examples in the [test suite](https://github.com/archfirst/joinjs/tree/master/test). Also check out the [Manage My Money](https://github.com/archfirst/manage-my-money-server) project for an example of a full-fledged application built with JoinJS and other libraries to manage personal finances.
91
89
92
90
## Installation
93
91
@@ -98,56 +96,56 @@ $ npm install join-js
98
96
## Documentation
99
97
100
98
### ResultMap
101
-
ResulpMaps are used to teach JoinJS how to map result sets to objects. Each result map focuses on a single object. The properties of a ResultMap are described below. You can find many examples of result maps in the [test suite](https://github.com/archfirst/joinjs/tree/master/test).
99
+
ResulpMaps are used to teach JoinJS how to map database results to objects. Each result map focuses on a single object. The properties of a ResultMap are described below. You can find several examples in the [test suite](https://github.com/archfirst/joinjs/tree/master/test).
102
100
103
-
-`{String} mapId` - A unique identifier for the map
101
+
-`mapId {String}` - A unique identifier for the map
104
102
105
-
-`{function} createNew`(optional) - A function that returns a blank new instance of the mapped object. Use these property to construct your custom objects instead of generic `Object`s.
103
+
-`createNew {function} (optional)` - A function that returns a blank new instance of the mapped object. Use this property to construct a custom object instead of generic JavaScript `Object`.
106
104
107
-
-`{Object} idProperty`(optional) - mapping of id property from result set to mapped object. Default is `{name: 'id', column: 'id'}`.
105
+
-`idProperty {Object} (optional)` - specifies the name of the id property in the mapped object and in the result set. Default is `{name: 'id', column: 'id'}`.
108
106
-`name` - property that identifies the mapped object
109
107
-`column` - property that identifies the database record in the result set
110
108
111
-
-`{Array} properties` - mapping of other properties from result set to mapped object
109
+
-`properties {Array} (optional)` - mappings for other properties. Each mapping contains:
112
110
-`name` - property name in the mapped object
113
111
-`column` - property name in the result set
114
112
115
-
-`{Array} associations` - specifies references to other objects
116
-
-`name` - property name of the association reference in the mapped object
113
+
-`associations {Array} (optional)` - mappings for associations to other objects. Each mapping contains:
114
+
-`name` - property name of the association in the mapped object
117
115
-`mapId` - identifier of the map for the associated object
118
-
-`columnPrefix` (optional) - a column prefix to apply to every element of the associated object. Default is an empty string.
116
+
-`columnPrefix (optional)` - a prefix to apply to every column of the associated object. Default is an empty string.
119
117
120
-
-`{Array} collections` - specifies an array of references to other objects
121
-
-`name` - property name of the array in the mapped object
118
+
-`collections {Array} (optional)` - mappings for collections of other objects. Each mapping contains:
119
+
-`name` - property name of the collection in the mapped object
122
120
-`mapId` - identifier of the map for the associated objects
123
-
-`columnPrefix` (optional) - a column prefix to apply to every element of the associated objects. Default is an empty string.
121
+
-`columnPrefix (optional)` - a prefix to apply to every column of the associated object. Default is an empty string.
124
122
125
123
### API
126
-
JoinJS exposes two very simple functions that give you the power to map any result set to one of more JavaScript objects.
124
+
JoinJS exposes two very simple functions that give you the full power to map any result set to one of more JavaScript objects.
127
125
128
126
129
127
#### map(resultSet, maps, mapId, columnPrefix)
130
128
131
-
Maps a resultSet to a collection.
129
+
Maps a resultSet to an array of objects.
132
130
133
-
-`{Array} resultSet` - an array of database results
134
-
-`{Array} maps` - an array of result maps
135
-
-`{String} mapId` - mapId of the top-level objects in the resultSet
136
-
-`{String} columnPrefix`(optional) - prefix that should be applied to the column names of the top-level objects
131
+
-`resultSet {Array}` - an array of database results
132
+
-`maps {Array}` - an array of result maps
133
+
-`mapId {String}` - mapId of the top-level objects in the resultSet
134
+
-`columnPrefix {String} (optional)` - prefix that should be applied to the column names of the top-level objects
0 commit comments