Debian Codegraph @

closure-library/closure/goog/db/index.js

raw
1 // Copyright 2011 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Wrapper for an IndexedDB index.
17 *
18 */
19
20
21 goog.provide('goog.db.Index');
22
23 goog.require('goog.async.Deferred');
24 goog.require('goog.db.Cursor');
25 goog.require('goog.db.Error');
26 goog.require('goog.db.KeyRange');
27 goog.require('goog.debug');
28
29
30
31 /**
32 * Creates an IDBIndex wrapper object. Indexes are associated with object
33 * stores and provide methods for looking up objects based on their non-key
34 * properties. Should not be created directly, access through the object store
35 * it belongs to.
36 * @see goog.db.ObjectStore#getIndex
37 *
38 * @param {!IDBIndex} index Underlying IDBIndex object.
39 * @constructor
40 * @final
41 */
42 goog.db.Index = function(index) {
43 /**
44 * Underlying IndexedDB index object.
45 *
46 * @type {!IDBIndex}
47 * @private
48 */
49 this.index_ = index;
50 };
51
52
53 /**
54 * @return {string} Name of the index.
55 */
56 goog.db.Index.prototype.getName = function() {
57 return this.index_.name;
58 };
59
60
61 /**
62 * @return {*} Key path of the index.
63 */
64 goog.db.Index.prototype.getKeyPath = function() {
65 return this.index_.keyPath;
66 };
67
68
69 /**
70 * @return {boolean} True if the index enforces that there is only one object
71 * for each unique value it indexes on.
72 */
73 goog.db.Index.prototype.isUnique = function() {
74 return this.index_.unique;
75 };
76
77
78 /**
79 * Helper function for get and getKey.
80 *
81 * @param {string} fn Function name to call on the index to get the request.
82 * @param {string} msg Message to give to the error.
83 * @param {IDBKeyType} key The key to look up in the index.
84 * @return {!goog.async.Deferred} The resulting deferred object.
85 * @private
86 */
87 goog.db.Index.prototype.get_ = function(fn, msg, key) {
88 var d = new goog.async.Deferred();
89 var request;
90 try {
91 request = this.index_[fn](key);
92 } catch (err) {
93 msg += ' with key ' + goog.debug.deepExpose(key);
94 d.errback(goog.db.Error.fromException(err, msg));
95 return d;
96 }
97 request.onsuccess = function(ev) { d.callback(ev.target.result); };
98 request.onerror = function(ev) {
99 msg += ' with key ' + goog.debug.deepExpose(key);
100 d.errback(goog.db.Error.fromRequest(ev.target, msg));
101 };
102 return d;
103 };
104
105
106 /**
107 * Fetches a single object from the object store. Even if there are multiple
108 * objects that match the given key, this method will get only one of them.
109 *
110 * @param {IDBKeyType} key Key to look up in the index.
111 * @return {!goog.async.Deferred} The deferred object for the given record.
112 */
113 goog.db.Index.prototype.get = function(key) {
114 return this.get_('get', 'getting from index ' + this.getName(), key);
115 };
116
117
118 /**
119 * Looks up a single object from the object store and gives back the key that
120 * it's listed under in the object store. Even if there are multiple records
121 * that match the given key, this method returns the first.
122 *
123 * @param {IDBKeyType} key Key to look up in the index.
124 * @return {!goog.async.Deferred} The deferred key for the record that matches
125 * the key.
126 */
127 goog.db.Index.prototype.getKey = function(key) {
128 return this.get_('getKey', 'getting key from index ' + this.getName(), key);
129 };
130
131
132 /**
133 * Helper function for getAll and getAllKeys.
134 *
135 * @param {string} fn Function name to call on the index to get the request.
136 * @param {string} msg Message to give to the error.
137 * @param {IDBKeyType=} opt_key Key to look up in the index.
138 * @return {!goog.async.Deferred} The resulting deferred array of objects.
139 * @private
140 */
141 goog.db.Index.prototype.getAll_ = function(fn, msg, opt_key) {
142 // This is the most common use of IDBKeyRange. If more specific uses of
143 // cursors are needed then a full wrapper should be created.
144 var IDBKeyRange = goog.global.IDBKeyRange || goog.global.webkitIDBKeyRange;
145 var d = new goog.async.Deferred();
146 var request;
147 try {
148 if (opt_key) {
149 request = this.index_[fn](IDBKeyRange.only(opt_key));
150 } else {
151 request = this.index_[fn]();
152 }
153 } catch (err) {
154 if (opt_key) {
155 msg += ' for key ' + goog.debug.deepExpose(opt_key);
156 }
157 d.errback(goog.db.Error.fromException(err, msg));
158 return d;
159 }
160 var result = [];
161 request.onsuccess = function(ev) {
162 var cursor = ev.target.result;
163 if (cursor) {
164 if (fn == 'openKeyCursor') {
165 // openKeyCursor returns a cursor with undefined key/value. See
166 // https://w3c.github.io/IndexedDB/#dom-idbobjectstore-openkeycursor.
167 result.push(cursor.primaryKey);
168 } else {
169 result.push(cursor.value);
170 }
171 cursor['continue']();
172 } else {
173 d.callback(result);
174 }
175 };
176 request.onerror = function(ev) {
177 if (opt_key) {
178 msg += ' for key ' + goog.debug.deepExpose(opt_key);
179 }
180 d.errback(goog.db.Error.fromRequest(ev.target, msg));
181 };
182 return d;
183 };
184
185
186 /**
187 * Gets all indexed objects. If the key is provided, gets all indexed objects
188 * that match the key instead.
189 *
190 * @param {IDBKeyType=} opt_key Key to look up in the index.
191 * @return {!goog.async.Deferred} A deferred array of objects that match the
192 * key.
193 */
194 goog.db.Index.prototype.getAll = function(opt_key) {
195 return this.getAll_(
196 'openCursor', 'getting all from index ' + this.getName(), opt_key);
197 };
198
199
200 /**
201 * Gets the keys to look up all the indexed objects. If the key is provided,
202 * gets all records for objects that match the key instead.
203 *
204 * @param {IDBKeyType=} opt_key Key to look up in the index.
205 * @return {!goog.async.Deferred} A deferred array of keys for objects that
206 * match the key.
207 */
208 goog.db.Index.prototype.getAllKeys = function(opt_key) {
209 return this.getAll_(
210 'openKeyCursor', 'getting all keys from index ' + this.getName(),
211 opt_key);
212 };
213
214
215 /**
216 * Opens a cursor over the specified key range. Returns a cursor object which is
217 * able to iterate over the given range.
218 *
219 * Example usage:
220 *
221 * <code>
222 * var cursor = index.openCursor(goog.db.KeyRange.bound('a', 'c'));
223 *
224 * var key = goog.events.listen(
225 * cursor, goog.db.Cursor.EventType.NEW_DATA,
226 * function() {
227 * // Do something with data.
228 * cursor.next();
229 * });
230 *
231 * goog.events.listenOnce(
232 * cursor, goog.db.Cursor.EventType.COMPLETE,
233 * function() {
234 * // Clean up listener, and perform a finishing operation on the data.
235 * goog.events.unlistenByKey(key);
236 * });
237 * </code>
238 *
239 * @param {!goog.db.KeyRange=} opt_range The key range. If undefined iterates
240 * over the whole object store.
241 * @param {!goog.db.Cursor.Direction=} opt_direction The direction. If undefined
242 * moves in a forward direction with duplicates.
243 * @return {!goog.db.Cursor} The cursor.
244 * @throws {goog.db.Error} If there was a problem opening the cursor.
245 */
246 goog.db.Index.prototype.openCursor = function(opt_range, opt_direction) {
247 return goog.db.Cursor.openCursor(this.index_, opt_range, opt_direction);
248 };