README.md
1
# TaffyDB (taffy.js)
2
3
TaffyDB is an open source JavaScript library that provides powerful
4
in-memory database capabilities to both browser and server applications.
5
6
## Introduction
7
8
Have you ever noticed how JavaScript object literals look a lot like
9
records? And that if you wrap a group of them up in an array you have
10
something that looks a lot like a database table? We did too.
11
We created TaffyDB easily and efficiently manipulate these 'tables'
12
with a uniform and familiar SQL-like interface.
13
14
We use TaffyDB instead of ad-hoc data manipulation routines throughout
15
our applications. This reduces development time, improves performance,
16
simplifies maintenance, *and* increases quality.
18
Please see the [official website](http://www.taffydb.com) for more
19
complete documentation.
20
21
## What makes it sticky
22
23
- Extremely fast
24
- Powerful JavaScript-centric data selection engine
25
- SQL inspired features such as insert, update, unique, count, and more
26
- Robust cross browser support
27
- Easily extended with your own functions
28
- Compatible with any DOM library (jQuery, YUI, Dojo, etc)
29
30
TaffyDB is compatible with all modern browsers: IE9+, FF3+, Safari 5+,
31
and Chrome 1.0+. It also works in NodeJS 0.10+.
32
33
## Create a DB
34
Just pass in a JSON array:
36
```js
37
var product_db = TAFFY([
38
{ "item" : 1,
39
"name" : "Blue Ray Player",
40
"price" : 99.99
41
},
42
{ "item" : 2,
43
"name" : "3D TV",
44
"price" : 1799.99
45
}
46
]);
47
```
49
## Example queries
51
```js
52
// where item is equal to 1
53
var item1 = products({item:1});
55
// where price is less than 100
56
var lowPricedItems = products({price:{lt:100}});
58
// where name is like "Blue Ray"
59
var blueRayPlayers = products({name:{like:"Blue Ray"}});
61
// get first record
62
products().first();
64
// get last record
65
products().last();
66
```
67
68
## Example record manipulation
70
```js
71
// update the price of the Blue Ray Player to 89.99
72
products({item:1}).update({price:89.99});
74
// loop over the records and call a function
75
products().each(function (r) {alert(r.name)});
77
// sort the records by price descending
78
products.sort("price desc");
80
// select only the item names into an array
81
products().select("name"); // returns ["3D TV","Blue Ray Player"]
83
// Inject values from a record into a string template.
84
// Row value will be set to "<tr><td>3D TV</td><td>17999.99</td></tr>"
85
var row = products({item:2})
86
.supplant("<tr><td>{name}</td><td>{price}</td></tr>");
87
```
89
## Use it in Node.JS
90
TaffyDB is easy to use in Node.JS. Simply install using `npm` and `require` the
93
```js
94
$ npm install --production taffy
95
96
# and then in your code
97
TAFFY = require( 'taffy' ).taffy;
98
```
100
The automated regression test file `nodeunit_suite.js` is an excellent
101
example.
103
## Help improve taffydb
104
105
TaffyDB has been used and refined for years for numerous production tools and
106
commercial products. It is therefore is quite stable and reliable. However,
107
we want expand our regression test coverage so we can easily improve the code
108
with the confidence that we are unlikely to break exising capabilities.
110
### Getting started with development
111
112
Run the `install_dev.sh` script to install development utilities such as `jslint`,
113
`nodeunit`, and `uglifyjs` to the `bin` directory.
114
115
```js
116
./install_dev.sh
117
```
118
119
120
### Running regression tests
121
Running the nodeunit regression test suite is simple:
123
```js
124
cd taffydb
125
./install_dev.sh # as above
127
bin/nodeunit ./nodeunit_suite.js
128
```
130
Please do not send a pull request unless your changes have passed these
131
tests. We check, you know :)
133
### Adding to regression tests
134
We wish to substantially expand the number of tests, and your
135
help is welcome! The code, `nodeunit_suite.js`, should be easy to adjust.
136
Pull requests that include regression test inclusions are very much
137
appreciated. Alternately, if you just send along a test scenario, we'd be
138
happy to include it in the suite, time permitting.
140
## Documentation, support, updates
141
View more docs and examples, get support, and get notified of updates:
142
143
Web: http://taffydb.com
144
Twitter: http://twitter.com/biastoact
145
146
## Software License Agreement (BSD License)
147
Copyright (c)
148
All rights reserved.
149
150
151
Redistribution and use of this software in source and binary forms, with or without modification, are permitted provided that the following condition is met:
152
153
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
154
155
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
156
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.