Skip to content
This repository
Newer
Older
100644 222 lines (172 sloc) 6.048 kb
66f813cd »
2011-10-06 README.md
1 ## About
2
40b346d3 »
2011-10-07 Edited README.md via GitHub
3 JugglingDB is cross-db ORM, providing **common interface** to access most popular database formats.
4 Currently supported are: mysql, mongodb, redis, neo4j and js-memory-storage (yep,
5 self-written engine for test-usage only). You can add your favorite database adapter, checkout one of the
6 existing adapters to learn how, it's super-easy, I guarantee.
66f813cd »
2011-10-06 README.md
7
8 ## Installation
9
680d1235 »
2012-01-18 Update readme
10 npm install jugglingdb
66f813cd »
2011-10-06 README.md
11
c4b0f3b4 »
2012-01-10 Update README.md
12 ## Participation
13
14 Check status of project on trello board: https://trello.com/board/jugglingdb/4f0a0b1e27d3103c64288388
15 Feel free to vote and comment on cards (tickets/issues), if you want to join team -- send me a message with your email.
16
66f813cd »
2011-10-06 README.md
17 ## Usage
18
19 ```javascript
c7ee4b73 »
2011-10-06 README.md
20 var Schema = require('./jugglingdb').Schema;
66f813cd »
2011-10-06 README.md
21 var s = new Schema('redis');
22 // define models
23 var Post = schema.define('Post', {
24 title: { type: String, length: 255 },
25 content: { type: Schema.Text },
f4642ec3 »
2011-10-11 Typo fix
26 date: { type: Date, default: Date.now },
66f813cd »
2011-10-06 README.md
27 published: { type: Boolean, default: false }
28 });
098fa989 » Anatoliy Chakkaev
2011-10-06 Edited README.md via GitHub
29 // simplier way to describe model
66f813cd »
2011-10-06 README.md
30 var User = schema.define('User', {
31 name: String,
098fa989 » Anatoliy Chakkaev
2011-10-06 Edited README.md via GitHub
32 bio: Schema.Text,
66f813cd »
2011-10-06 README.md
33 approved: Boolean,
34 joinedAt: Date,
35 age: Number
36 });
37
38 // setup relationships
39 User.hasMany(Post, {as: 'posts', foreignKey: 'userId'});
40 // creates instance methods:
41 // user.posts(conds)
8e05e599 »
2011-10-15 Scopes
42 // user.posts.build(data) // like new Post({userId: user.id});
43 // user.posts.create(data) // build and save
66f813cd »
2011-10-06 README.md
44
45 Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});
46 // creates instance methods:
47 // post.author(callback) -- getter when called with function
48 // post.author() -- sync getter when called without params
49 // post.author(user) -- setter when called with object
50
51 s.automigrate(); // required only for mysql NOTE: it will drop User and Post tables
52
53 // work with models:
54 var user = new User;
55 user.save(function (err) {
8e05e599 »
2011-10-15 Scopes
56 var post = user.posts.build({title: 'Hello world'});
66f813cd »
2011-10-06 README.md
57 post.save(console.log);
58 });
59
ae41cd69 »
2012-01-09 Describe consturctor calling without "new"
60 // or just call it as function (with the same result):
61 var user = User();
62 user.save(...);
63
66f813cd »
2011-10-06 README.md
64 // Common API methods
65
66 // just instantiate model
67 new Post
68 // save model (of course async)
69 Post.create(cb);
70 // all posts
71 Post.all(cb)
72 // all posts by user
63192ff3 »
2011-11-20 Describe object livecycle, update isValid usage
73 Post.all({where: {userId: user.id}});
66f813cd »
2011-10-06 README.md
74 // the same as prev
75 user.posts(cb)
76 // same as new Post({userId: user.id});
8e05e599 »
2011-10-15 Scopes
77 user.posts.build
66f813cd »
2011-10-06 README.md
78 // save as Post.create({userId: user.id}, cb);
8e05e599 »
2011-10-15 Scopes
79 user.posts.create(cb)
66f813cd »
2011-10-06 README.md
80 // find instance by id
81 User.find(1, cb)
82 // count instances
83 User.count(cb)
84 // destroy instance
85 user.destroy(cb);
86 // destroy all instances
87 User.destroyAll(cb);
8abce47c »
2011-10-10 Update validations stuff in README
88
89 // Setup validations
90 User.validatesPresenceOf('name', 'email')
91 User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
92 User.validatesInclusionOf('gender', {in: ['male', 'female']});
93 User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
94 User.validatesNumericalityOf('age', {int: true});
63192ff3 »
2011-11-20 Describe object livecycle, update isValid usage
95 User.validatesUniquenessOf('email', {message: 'email is not unique'});
8abce47c »
2011-10-10 Update validations stuff in README
96
63192ff3 »
2011-11-20 Describe object livecycle, update isValid usage
97 user.isValid(function (valid) {
98 if (!valid) {
99 user.errors // hash of errors {attr: [errmessage, errmessage, ...], attr: ...}
100 }
101 })
102
103 ```
104
105 ## Callbacks
106
107 The following callbacks supported:
108
109 - afterInitialize
110 - beforeCreate
111 - afterCreate
112 - beforeSave
113 - afterSave
114 - beforeUpdate
115 - afterUpdate
116 - beforeDestroy
117 - afterDestroy
118 - beforeValidation
119 - afterValidation
120
121 Each callback is class method of the model, it should accept single argument: `next`, this is callback which
122 should be called after end of the hook. Except `afterInitialize` because this method is syncronous (called after `new Model`).
123
124 ## Object lifecycle:
125
126 ```javascript
127 var user = new User;
128 // afterInitialize
129 user.save(callback);
130 // beforeValidation
131 // afterValidation
132 // beforeSave
133 // beforeCreate
134 // afterCreate
135 // afterSave
136 // callback
137 user.updateAttribute('email', 'email@example.com', callback);
138 // beforeValidation
139 // afterValidation
140 // beforeUpdate
141 // afterUpdate
142 // callback
143 user.destroy(callback);
144 // beforeDestroy
145 // afterDestroy
146 // callback
147 User.create(data, callback);
148 // beforeValidate
149 // afterValidate
150 // beforeCreate
151 // afterCreate
152 // callback
66f813cd »
2011-10-06 README.md
153 ```
154
155 Read the tests for usage examples: ./test/common_test.js
8abce47c »
2011-10-10 Update validations stuff in README
156 Validations: ./test/validations_test.js
66f813cd »
2011-10-06 README.md
157
158 ## Your own database adapter
159
40b346d3 »
2011-10-07 Edited README.md via GitHub
160 To use custom adapter, pass it's package name as first argument to `Schema` constructor:
66f813cd »
2011-10-06 README.md
161
162 mySchema = new Schema('couch-db-adapter', {host:.., port:...});
163
164 Make sure, your adapter can be required (just put it into ./node_modules):
165
166 require('couch-db-adapter');
167
168 ## Running tests
169
40b346d3 »
2011-10-07 Edited README.md via GitHub
170 All tests are written using nodeunit:
66f813cd »
2011-10-06 README.md
171
172 nodeunit test/common_test.js
173
40b346d3 »
2011-10-07 Edited README.md via GitHub
174 If you run this line, of course it will fall, because it requres different databases to be up and running,
175 but you can use js-memory-engine out of box! Specify ONLY env var:
66f813cd »
2011-10-06 README.md
176
177 ONLY=memory nodeunit test/common_test.js
178
179 of course, if you have redis running, you can run
180
181 ONLY=redis nodeunit test/common_test.js
182
183 ## Package structure
184
8abce47c »
2011-10-10 Update validations stuff in README
185 Now all common logic described in `./lib/*.js`, and database-specific stuff in `./lib/adapters/*.js`. It's super-tiny, right?
66f813cd »
2011-10-06 README.md
186
187 ## Project status
188
40b346d3 »
2011-10-07 Edited README.md via GitHub
189 This project was written in one weekend (1,2 oct 2011), and of course does not claim to be production-ready,
190 but I plan to use this project as default ORM for RailwayJS in nearest future.
191 So, if you are familiar with some database engines - please help me to improve adapter for that database.
66f813cd »
2011-10-06 README.md
192
40b346d3 »
2011-10-07 Edited README.md via GitHub
193 For example, I know, mysql implementation sucks now, 'cause I'm not digging too deep into SequelizeJS code,
194 and I think it would be better to replace sequelize with something low-level in nearest future, such
195 as `mysql` package from npm.
66f813cd »
2011-10-06 README.md
196
197 ## Contributing
198
199 If you have found a bug please write unit test, and make sure all other tests still pass before pushing code to repo.
200
201 ## Roadmap
202
203 ### Common:
204
098fa989 » Anatoliy Chakkaev
2011-10-06 Edited README.md via GitHub
205 + transparent interface to APIs
66f813cd »
2011-10-06 README.md
206 + -before and -after hooks on save, update, destroy
8e05e599 »
2011-10-15 Scopes
207 + scopes
66f813cd »
2011-10-06 README.md
208 + default values
209 + more relationships stuff
210 + docs
211
212 ### Databases:
213
214 + riak
215 + couchdb
216 + low-level mysql
217 + postgres
218 + sqlite
219
220 ## License
221
222 MIT
Something went wrong with that request. Please try again.