JSORM.db.engine

From Jsorm

Overview

An engine is responsible for implementing the actual storage of table, whether in memory or persistent storage, local or remote. Each instance of an engine stores exactly one table. The engine's underlying storage can be anything it chooses:

• A hash in memory
• An array in memory
• A remote data source
• A RESTful service
• A local disk file
• Anything else

jsormdb ships with two engines:

• array: unindexed
• hash: fully indexed (default)

Additionally, the object JSORM.db.engine has a convenience function constructQuery() which is used to convert a standard search term, primitive or composite, into a function that can be used to check a record for matching the term. See [#Query] for more information.

Limitations

The ability of an engine to actually connect with a storage location may be significantly constrained by the operating environment. For example, a browser will normally only allow a network communication to the server from which the JavaScript itself was received, and will normally not allow any local disk access at all. On the other hand, a Rhino JavaScript environment program or Mozilla plugin will have much broader access.

Signature

An engine is expected to have a single parameter passed to it at instantiation, the implementation of its index. For more information on indexes, see JSORM.db.index. The engine is not required to accept the index. A particular engine implementation may choose to do any of the following:

• Accept the passed index object as its index
• Ignore the index entirely and remain unindexed
• Ignore the index entirely but use its own index

In general, an engine should choose one of the first two options, as the user creating the jsormdb may desire to choose one particular index over another. However, the engine must be able to function if no index is passed, i.e. it should be capable of recognizing that there is no index and continue to function either with a default index or unindexed.

The actual constructor should be a function that does not require the "new" keyword, and thus should be named in lower-case.

An engine is expected to have the following method signature:

• length: Method to return the number of records in the engine.

store = JSORM.db.engine.hash();
store.insert([{name: "John", uid: 200},{name: "Jill", uid: 210}];
store.length(); // 2

• insert: Method to insert new records. Engine is responsible for updating its own index. Single argument, records, may be a single record or multiple records in an array. Expected to return an array with the internal index references for all of the inserted records.

store.insert([{name: "John", uid: 200},{name: "Jill", uid: 210}];

• remove: Method to remove one or more records. Engine is responsible for updating its own index. Single argument, index, may be a single index entry or multiple indexes in an array. The index is relevant only to this engine, and is as returned by this engine. Expected to return an array of all records removed.

store.remove(2); // remove item at index 2. Index "2" has meaning only to the engine itself
store.remove([2,5]); // remove items at index 2 and 5. Indexes "2" and "5" have meaning only to the engine itself

• clear: Method to clear out all data.

store.clear();
store.length(); // 0

• get: Method to get records. Expected to accept two arguments: index and fields. Index is a single entry or an array of entries of the indexes of the records desired. The index is the internal index relevant only to this engine. If index is null or undefined, return all records. Fields is an object. Those entries that exist in the fields object are the fields of the matching records desired. If fields is null or undefined, return the entire record.

store.get(); // returns all records as an array [{name: "John", uid: 200},{name: "Jill", uid: 210}]
store.get(2); // return item at internal index 2 [{}]
store.get([2,5]); // return items at internal index 2 and 5 [{},{}]

• update: Method to update some records with new data. Expected to accept two arguments: data and index. Data is an object with the new data. Each field in object will be applied to each matching record. Index is a single internal index or array of indexes of the records to update. Expected to return an array, one entry per record changed, in the same order as the index argument. Each entry in the array should be an object with the old data that existed prior to the call to update.

store = JSORM.db.engine.hash();
store.insert([{name: "John", uid: 200},{name: "Jill", uid: 210},{name: "Karl", uid: 220},{name: "Kathy", uid: 230}];
store.update({name: "Jimmy},[0,2]); // returns [{name: "John"},{name: "Karl"}]

• addIndex: Method to add one or more fields to indexing. The engine may choose to ignore this call if it chooses to do so. If the index already exists, no action should be taken, nor should any error be returned or thrown. Argument can be a single string or an array of strings.

store.addIndex("name");
store.addInex(["name","city"]);

• removeIndex: Method to remove one or more fields from indexing. The engine may choose to ignore this call if it chooses to do so. If the index does not exist, no action should be taken, nor should any error be returned or thrown. Argument can be a single string or an array of strings.

store.removeIndex("name");
store.removeIndex(["name","city"]

• query: Method to perform a search on the data in the engine. The engine is responsible for determining whether or not to consult an index before doing a full table scan. Expected to return an array of internal indexes whose records match the query. Expected to take the following arguments:
  • where: query of standard format that is being matched. See the query format in Jsormdb#Querying_Data.
  • limit: array of indexes, internal to the engine itself, to which to limit the search.

store.query({field: "name", compare: "equals", value: "John"},[2,3,4]);

Query

In the query method, the engine is provided with a standard search term, primitive or composite, that is used to determine the suitable matching records. This search term can be used in one of two ways:

• Index: If the engine has an index, it can be used to match
• Full-table scan: If the table has no index, or the index cannot search for this particular search term, then a full-table scan, i.e. a record-by-record comparison, must be used.

In order to simplify a full-table scan, JSORM.db.engine object provides a method, constructQuery(), that will return a function when passed a standard query. This function takes as its argument a single JavaScript object, i.e. a record from the table, and returns true if the record matches the query or false if it does not. The engine may choose to be relieved of the burden of parsing the query with each and every record, or at all, by delegating the conversion to the method and then passing the function.

Retrieving the function is done in one of two ways:

// standard
var fn = JSORM.db.engine.constructQuery(where);
// if the engine in which we are operating has JSORM.db.engine as its prototype, i.e. inherits from JSORM.db.engine
var fn = this.constructQuery(where);

The function can then be used as follows

// repeat on each record in the engine, e.g. if the data is in an array in data
for (i=0; i<data.length; i++) {
  match = fn(data[i]); // true if matches, false if not
}

Return Safety

For all methods, an engine can safely return a direct reference to an object in memory, if it so chooses. JSORM.db.db will clone any objects before returning them to the user.