GaviaはIndexedDBのためのActiveRecord風ライブラリです。 検索結果をjQueryDeferred風のオリジナルDeferredオブジェクトで返すため、 コールバックを多用することなく宣言的かつ簡潔に処理を書くことが出来ます。
依存関係もなく、GaviaのみでIndexedDBの処理を完結させることが出来ます。
bower install gavia
bowerはWeb開発用のJavaScriptパッケージマネージャです。
MIT LICENSE
var db = new Gavia('test-db', {
store: {
keyPath: 'id',
autoIncrement: true,
index: {
unique: true
}
}
});
var test = db.store.create();
test.hoge = 'hogehoge';
test.save().done(function() {
console.log('save done');
});
db.store.filter(function(record) {
return record.hoge.length > 5;
}).done(function(results) {
results.forEach(function(result) {
console.log(result);
});
});
簡単なTODOアプリをGaviaを使って構築してみました。
http://kokudori.github.io/gavia/example/index.html
ソースはGistにて公開しています。
https://gist.github.com/kokudori/5559908
DBを作成するにはGaviaコンストラクタを使います。
gaviaDBObject = new Gavia('DBName', version, { // optional version
'ObjectStoreName': {
keyPath: 'keyName', // optional
autoIncrement: Boolean, // optional
index: { // optional
keyPath: 'indexKeyName', // optional
name: 'indexName', // optional
unique: Boolean, // optional
multiEntry: Boolean // optional
}
},
...
})
名前 | 概要 | デフォルト値 |
---|---|---|
DBName | 作成するDBの名前。 IndexedDB内で一意の文字列を指定。 | 省略不可 |
version | DBのバージョンを指定。 バージョンが上がるとオブジェクトストアの構成を変更する。 | 1 |
ObjectStoreName | 作成するオブジェクトストアの名前。 DB内で一意の文字列を指定。 | 省略不可 |
keyPath | 指定するオブジェクトストアの主キー。 | 省略するとオブジェクトの保存時にキーを指定する必要がある。 |
autoIncrement | オブジェクトを保存するたびにキー値を自動でインクリメントするかどうか。 | |
index | オブジェクトストアのindexを指定。 | |
index: keyPath | indexとなるプロパティの名前。 | オブジェクトストアのkeyPath |
index: name | 作成するindexの名前。 | indexのkeyPath。 |
index: unique | indexが一意かどうか。 | |
index: multiEntry |
作成したgaviaDBObjectへはGavia['DBName']
でも同様にアクセス出来ます。
また、gaviaDBObjectから個々のオブジェクトストアへも、
オブジェクトストア名からプロパティアクセス可能です。
var db = new Gavia('sample-db', {
'sample-store': {
keyPath: 'id'
}
});
assert(db === Gavia['sample-db']);
db['sample-store']; // ストアオブジェクト
オブジェクトストアへのメソッド群はGavia.Store.fnに定義されています。 また、Gavia.Store.fnへ新たにユーザー定義メソッドを作ることも出来ます。
また、ほぼ全てのメソッドはDeferredを返します。
名前 | 概要 |
---|---|
all | 全てのオブジェクトを取得。 |
bound | lower <= key <= upper となるオブジェクトを全て取得。 |
boundThan | lower < key < upper となるオブジェクトを全て取得。 |
clear | オブジェクトストアの全オブジェクトを削除。 |
create | 新しくオブジェクトを作成。 |
delete | オブジェクトを削除 |
find | keyを元にオブジェクトを取得。 |
lower | key <= upper となるオブジェクトを全て取得。 |
lowerThan | key < upper となるオブジェクトを全て取得。 |
transaction | データの作成、削除を1つのトランザクション内で完結させる。 |
upper | lower <= key となるオブジェクトを全て取得。 |
upperThan | lower < key となるオブジェクトを全て取得。 |
Gavia['sample-db']['sample-store']
.find(10).done(function(result) {
console.log(result);
});
オブジェクトストアに属する全オブジェクトを取得。
deferred = gaviaStoreObject.all({
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.all().done(function(results) {
console.log(results); // 1 ~ 9
});
gaviaStoreObject.all({
offset: 2,
limit: 4
}).done(function(results) {
console.log(results); // 3 ~ 6
});
gaviaStoreObject.all({
count: true
}).done(function(count) {
console.log(count); // 9
});
lower <= key <= upper
となるオブジェクトを全て取得。
とは違い、境界を含む。
deferred = gaviaStoreObject.bound(lower, upper, {
direction: Gavia.Store.direction, // optional
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
direction | オブジェクトを探索する方向を指定。 詳しくは後述する。 | |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
Gavia.Store.directionはオブジェクトストアの探索方向を指定するものです。 探索方向は昇順、重複なし昇順、降順、重複なし降順の4つがあります。
名前 | 概要 |
---|---|
Gavia.Store.direction.next | 昇順 |
Gavia.Store.direction.nextunique | 重複なし昇順 |
Gavia.Store.direction.prev | 降順 |
Gavia.Store.direction.prevunique | 重複なし降順 |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.bound(2, 8).done(function(results) {
console.log(results); // 2 ~ 8
});
gaviaStoreObject.bound(2, 8, {
direction: Gavia.Store.direction.prev
}).done(function(results) {
console.log(results); // 8 ~ 2
});
gaviaStoreObject.bound(2, 8, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // 4 ~ 6
});
gaviaStoreObject.bound(2, 8, {
count: true
}).done(function(count) {
console.log(count); // 7
});
lower < key < upper
となるオブジェクトを全て取得。
とは違い、境界を含まない。
deferred = gaviaStoreObject.boundThan(lower, upper, {
direction: Gavia.Store.direction, // optional
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
direction | オブジェクトを探索する方向を指定。 詳しくはGavia.Store.directionを参照。 | |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.boundThan(2, 8).done(function(results) {
console.log(results); // 3 ~ 7
});
gaviaStoreObject.boundThan(2, 8, {
direction: Gavia.Store.direction.prev
}).done(function(results) {
console.log(results); // 7 ~ 3
});
gaviaStoreObject.boundThan(2, 8, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // 5 ~ 7
});
gaviaStoreObject.boundThan(2, 8, {
count: true
}).done(function(count) {
console.log(count); // 5
});
オブジェクトストアに属するオブジェクトを全て削除する。
deferred = gaviaStoreObject.clear();
gaviaStoreObject.clear().done(function() {
console.log('clear done');
});
オブジェクトを新しく作成。 saveするまでオブジェクトストアには保存されない。
Object = gaviaStoreObject.create(key); // optional key
名前 | 概要 | デフォルト値 |
---|---|---|
key | keyPathを設定している場合は、作成時にkeyを設定する。 | 省略可能。 |
var obj = gaviaStoreObject.create();
var obj2 = gaviaStoreObject.create(123);
オブジェクトストアから特定のオブジェクトを削除。
deferred = gaviaStoreObject.delete(key);
名前 | 概要 | デフォルト値 |
---|---|---|
key | 削除したいオブジェクトのkey。 | 省略不可。 |
gaviaStoreObject.delete(123).done(function() {
console.log('delete done');
});
オブジェクトストアから、値もしくは述語関数にマッチするオブジェクトを返す。
deferred = gaviaStoreObject.filter(value, {
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
deferred = gaviaStoreObject.filter(prediacte, {
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
value | keyと一致するオブジェクトを返す。 | 省略不可 |
predicate | 述語関数。 関数がtrueを返した時に渡されていたオブジェクト群を返す。 | 省略不可 |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを
// idプロパティとして持つオブジェクトが存在すると仮定。
gaviaStoreObject.filter(function(result) {
return result.id % 2 === 0;
}).done(function(odd) {
console.log(odd); // id -> [2, 4, 6, 8]
});
gaviaStoreObject.filter(function(result) {
return result.id % 2 === 0;
}, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // id -> [4, 6]
});
gaviaStoreObject.filter(function(result) {
return result.id % 2 === 0;
}, {
count: true
}).done(function(count) {
console.log(count); // 4
});
gaviaStoreObject.filter(5).done(function(result) {
console.log(result); // id -> 5
});
gaviaStoreObject.filter(5, {
offset: 6
}).done(function(result) {
console.log(result); // undefined
});
gaviaStoreObject.filter(5, {
count: true
}).done(function(count) {
console.log(count); // 1
});
オブジェクトストアからkeyを元にオブジェクトを取得。
deferred = gaviaStoreObject.find(key, {
index: 'indexName' // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
key | 探索対象のオブジェクトのkey。 | 省略不可 |
index | indexを指定 |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.find(123).done(function(result) {
console.log(result); // key が123のオブジェクト
});
gaviaStoreObject.find(123, {
index: 'id'
}).done(function(result) {
console.log(result); // key が123のオブジェクト
});
key <= upper となるオブジェクトを全て取得。
lowerThanとは違い、境界を含む。
deferred = gaviaStoreObject.lower(upper, {
direction: Gavia.Store.direction, // optional
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
upper | upper**以下**となるkeyを持つオブジェクトを取得する。 | 省略不可。 |
direction | オブジェクトを探索する方向を指定。 詳しくはGavia.Store.directionを参照。 | |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.lower(6).done(function(results) {
console.log(results); // 1 ~ 6
});
gaviaStoreObject.lower(6, {
direction: Gavia.Store.direction.prev
}).done(function(results) {
console.log(results); // 6 ~ 1
});
gaviaStoreObject.lower(6, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // 3 ~ 5
});
gaviaStoreObject.lower(6, {
count: true
}).done(function(count) {
console.log(count); // 6
});
key < upper となるオブジェクトを全て取得。
lowerとは違い、境界を含まない。
deferred = gaviaStoreObject.lowerThan(upper, {
direction: Gavia.Store.direction, // optional
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
upper | upper**より下**となるkeyを持つオブジェクトを取得する。 | 省略不可。 |
direction | オブジェクトを探索する方向を指定。 詳しくはGavia.Store.directionを参照。 | |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.lowerThan(6).done(function(results) {
console.log(results); // 1 ~ 5
});
gaviaStoreObject.lowerThan(6, {
direction: Gavia.Store.direction.prev
}).done(function(results) {
console.log(results); // 5 ~ 1
});
gaviaStoreObject.lowerThan(6, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // 3 ~ 5
});
gaviaStoreObject.lowerThan(6, {
count: true
}).done(function(count) {
console.log(count); // 5
});
対象のオブジェクトストアへの複数の操作を1つのトランザクション内で行う。
deferred = gaviaStoreObject.transaction(store..., callback);
storeは複数指定可能。 callbackは引数の最後にしなければならない。
名前 | 概要 | デフォルト値 |
---|---|---|
store | ||
callback | トランザクション内で行う処理。 callbackへは、transactionに渡したstore...と同じだけの数のtransactionStoreオブジェクトが引数として渡される。 falseを返すと、transaction全体がabortされる。 |
callbackに渡されるオブジェクト。 storeに対して変更を行うメソッドが2つ用意されている。
// store, other, anotherはいずれもGaviaのオブジェクトストアを意味する。
store.transaction(function(store) {
store.add({
id: 123
});
store.remove(234);
});
store.transaction(other, another, function(store, other, another) {
store.add({
id: 123
});
other.remove(234);
another.add({
id: 123
});
});
store.tramsaction(other, function(other) {
store.add({
id: 123
});
other.remove(234);
return false; // ここで書かれた処理全体が取り消される。
});
lower <= key となるオブジェクトを全て取得。
upperThanとは違い、境界を含む。
deferred = gaviaStoreObject.upper(lower, {
direction: Gavia.Store.direction, // optional
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
lower | lower**以上**となるkeyを持つオブジェクトを取得する。 | 省略不可。 |
direction | オブジェクトを探索する方向を指定。 詳しくはGavia.Store.directionを参照。 | |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.upper(4).done(function(results) {
console.log(results); // 4 ~ 9
});
gaviaStoreObject.upper(4, {
direction: Gavia.Store.direction.prev
}).done(function(results) {
console.log(results); // 9 ~ 4
});
gaviaStoreObject.upper(4, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // 6 ~ 8
});
gaviaStoreObject.upper(4, {
count: true
}).done(function(count) {
console.log(count); // 6
});
lower < key となるオブジェクトを全て取得。
upperとは違い、境界を含まない。
deferred = gaviaStoreObject.upperThan(lower, {
direction: Gavia.Store.direction, // optional
index: 'indexName', // optional
offset: Number, // optional
limit: Number, // optional
count: Boolean // optional
});
名前 | 概要 | デフォルト値 |
---|---|---|
lower | lower**より上**となるkeyを持つオブジェクトを取得する。 | 省略不可。 |
direction | オブジェクトを探索する方向を指定。 詳しくはGavia.Store.directionを参照。 | |
index | indexを指定 | |
offset | offset分、最初のオブジェクトを飛ばして取得。 | 0 |
limit | 取得する最大数。 | |
count | trueの場合、取得したオブジェクトの数を返す。 | false |
// gaviaStoreObject に 1 ~ 9のkeyを持つオブジェクトが存在すると仮定。
gaviaStoreObject.upperThan(4).done(function(results) {
console.log(results); // 5 ~ 9
});
gaviaStoreObject.upperThan(4, {
direction: Gavia.Store.direction.prev
}).done(function(results) {
console.log(results); // 9 ~ 5
});
gaviaStoreObject.upperThan(4, {
offset: 2,
limit: 2
}).done(function(results) {
console.log(results); // 7 ~ 9
});
gaviaStoreObject.upperThan(4, {
count: true
}).done(function(count) {
console.log(count); // 5
});
オブジェクトストアに保存されるオブジェクトへのメソッド群はGavia.Record.fnに定義されています。 また、Gavia.Record.fnへ新たにユーザー定義メソッドを作ることも出来ます。
名前 | 概要 |
---|---|
delete | そのオブジェクトが属するオブジェクトストアから、対象のオブジェクトを削除する。 |
save | そのオブジェクトが属するオブジェクトストアへ、対象のオブジェクトを保存する。 |
update | オブジェクトのプロパテイ群を更新する。 saveメソッドを実行するまで、プロパティの更新はDBへ更新されない。 |
Gavia['sample-db']['sample-store']
.create(123)
.update({
name: 'Kokudori',
age: 20
}).save().done(function() {
console.log('create, update and save done');
});
そのオブジェクトが属するオブジェクトストアから、対象のオブジェクトを削除する。
deferred = gaviaRecordObject.delete(keyName); // optional keyName
名前 | 概要 | デフォルト値 |
---|---|---|
keyName | 削除するオブジェクトのkeyとなるプロパティの名前。 keyPath、又はautoIncrementが指定されている場合は省略可能。 |
gaviaRecordObject.delete().done(function() {
console.log('delete done');
});
gaviaRecordObject.delete('id').done(function() {
console.log('delete done');
});
そのオブジェクトが属するオブジェクトストアへ、対象のオブジェクトを保存する。
deferred = gaviaRecordObject.save(key); // optional key
名前 | 概要 | デフォルト値 |
---|---|---|
key | 保存するオブジェクトのkey。 keyPath、又はautoIncrementが指定されている場合は省略可能。 |
gaviaRecordObject.save().done(function() {
console.log('save done');
});
gaviaRecordObject.save(123).done(function() {
console.log('save done');
});
オブジェクトのプロパテイ群を更新する。 saveメソッドを実行するまで、プロパティの更新はDBへ更新されない。
gaviaRecordObject = gaviaRecordObject.update(properties);
名前 | 概要 | デフォルト値 |
---|---|---|
properties | 更新するプロパテイ群。 プロパティ名とプロパティ値を指定。 |
gaviaRecordObject.update({
hoge: 123,
piyo: 234
});
jQueryDeferredライクな独自のDeferredオブジェクトです。 非同期処理を合成することが出来ます。
名前 | 概要 |
---|---|
Deferred.when | 複数のDeferredが全て成功するまで待つDeferredを返す。 |
done | Deferredが**成功**した時に呼ばれる関数を登録するメソッド。 既に成功している場合は登録後すぐに呼ばれる。 |
fail | Deferredが**失敗**した時に呼ばれる関数を登録するメソッド。 既に失敗している場合は登録後すぐに呼ばれる。 |
then | 値もしくはDeferredを返す関数を渡す。 値を返した場合は成功値を合成、 Deferredを返した場合はDeferredを合成する関数として振る舞う。 |
resolve\* | Deferredに**成功**値を渡す。 既にDeferredが成功、もしくは失敗している場合は無視される。 |
reject\* | Deferredに**失敗**値を渡す。 既にDeferredが成功、もしくは失敗している場合は無視される。 |
promise | Deferredからpromise, resolve, rejectメソッドを削除したものを返す。 コールバックの登録のみを意図する場合に使用する。 GaviaのStore/Record APIは全てpromiseしたものを返している。 |
*: promiseメソッドの返り値には存在しないメソッド
var deferred = new Gavia.Deferred().promise();
deferred.then(function(value) {
return value + 1;
}).done(function(value) {
assert(value, 2);
});
deferred.resolve(1);
複数のDeferredが全て成功するまで待つDeferredを返す。
deferred = Gavia.Deferred.when(deferred1, deferred2, .. deferredN);
名前 | 概要 | デフォルト値 |
---|---|---|
deferredN | 合成する各Deferredオブジェクト promiseされていてもされていなくてもどちらでも良い。 |
Gavia.Deferred.when(deferred1, deferred2, deferred3)
.done(function(result1, result2, result3) {
console.log("全てのdeferredが成功");
// 各resultパラメータには対応するdeferredの成功値が格納されている
});
Gavia.Deferred.when(deferred1, deferred2, deferred3)
.fail(function(result) {
console.log("いずれかのdeferredが失敗");
// resultパラメータは最初に失敗したdeferredの失敗値
});
Deferredが成功した時に呼ばれる関数を登録するメソッド。 既に成功している場合は登録後すぐに呼ばれる。
deferred = deferred.done(callback);
名前 | 概要 | デフォルト値 |
---|---|---|
callback | deferredが成功した時に呼ばれる関数。 deferredの成功値がパラメータに渡される。 |
deferred.done(function(result) {
console.log("deferredが成功");
// resultパラメータにはdeferredの成功値が格納されている
});
Deferredが失敗した時に呼ばれる関数を登録するメソッド。 既に失敗している場合は登録後すぐに呼ばれる。
deferred = deferred.fail(callback);
名前 | 概要 | デフォルト値 |
---|---|---|
callback | deferredが失敗した時に呼ばれる関数。 deferredの失敗値がパラメータに渡される。 |
deferred.fail(function(result) {
console.log("deferredが失敗");
// resultパラメータにはdeferredの失敗値が格納されている
});
値もしくはDeferredを返す関数を渡す。 値を返した場合は成功値を合成、 Deferredを返した場合はDeferredを合成する関数として振る舞う。
deferredN = deferred1.then(deferred2).then(value);
名前 | 概要 | デフォルト値 |
---|---|---|
deferred2 | deferred1に合成するdeferredオブジェクト。 deferredNはdeferred1とdeferred2がどちらも成功すると成功に、 どちらかもしくはどちらもが失敗すると失敗として扱われる。 | |
value | deferred1の成功値に対する写像。 |
deferred
.then(value)
.then(otherDeferred)
.done(function(result) {
// deferred, otherDeferredのいずれもが成功
})
.fail(function(result) {
// deferred, otherDeferredのいずれかもしくはどちらかが失敗
})
Deferredに成功値を渡す。 既にDeferredが成功、もしくは失敗している場合は無視される。 (promiseメソッドの返り値には存在しないメソッド)
deferred = deferred.resolve(value);
名前 | 概要 | デフォルト値 |
---|---|---|
value | deferredの成功値 |
deferred
.resolve(value)
.done(function(result) {
assert(result, value);
});
Deferredに失敗値を渡す。 既にDeferredが成功、もしくは失敗している場合は無視される。 (promiseメソッドの返り値には存在しないメソッド)
deferred = deferred.reject(value);
名前 | 概要 | デフォルト値 |
---|---|---|
value | deferredの失敗値 |
deferred
.reject(value)
.fail(function(result) {
assert(result, value);
});
Deferredからpromise, resolve, rejectメソッドを削除したものを返す。 コールバックの登録のみを意図する場合に使用する。 GaviaのStore/Record APIは全てpromiseしたものを返している。
promise = deferred.promise();
deferred
.resolve(value)
.promise()
.done(function(result) {
assert(result, value);
});
Document is built using the pamflet.
pamflet is markdown to html generator by scala.