JSORM.db.parser

From Jsorm

Contents 1 Overview 2 Signature 2.1 Read 2.2 Write

Overview

A parser is responsible for converting between the plain old JavaScript objects (POJSO?) that jsormdb uses and any random encoding format. It is expected to convert in both directions. The parser is not responsible for opening up any communications channels; it is only expected to convert between formats. In that respect, a parser is very much like a codec. Its input is either a raw format or objects, and its output is the converse. The parser works in concert with the channel, managed by jsormdb.

The general process flow for a load is as follows:

1. jsormdb uses the channel to get data from a remote data source. This data is encoded in any arbitrary format.
2. jsormdb takes the output from the channel and hands it to the parser.
3. The parser converts the output from the channel into POJSO, returning the POJSO to jsormdb.
4. jsormdb takes the output from the parser and loads it into the database.

The encoding format could be anything at all. For example:

• JSON
• XML
• CSV
• Pig Latin

As long as a parser exists that can convert between the encoding format and POJSO for jsormdb, it will work.

A parser shipped with jsormdb will normally be in the object JSORM.db.parser. Only the JSORM.db.parser.json parser for JSON ships by default.

Signature

A parser is not required to have configuration parameters, but may choose to. These configuration parameters are normally used to set up configuration of the conversion, for example id values and the root (in XML or JSON) of the actual data. For specific configuration of the json parser that ships with jsormdb, see JSORM.db.parser.json.

A parser is expected to have the following methods defined:

• read: Called when the parser is expected to convert from its encoding format to POJSO suitable for jsormdb.
• write: Called when the parser is expected to convert from POJSO to its encoding format suitable for consumption by some other service.

Read

Read accepts a single element as an argument. The element is the output as received from the channel. This is normally a string, but is not required to be. The return value is expected to be a JavaScript object with the following elements:

• records: Array of JavaScript objects suitable for loading into the jsormdb database.
• id: The field in each record of records that represents the unique identifier of the record.

It is critical that each record have a unique identifier. If not, it is impossible for jsormdb to reliably reconcile its local copy of records with a remote data source. Additionally, if condensed mode is used, it is impossible for jsormdb to know which records to condense. Thus, it is the responsibility of the remote data source to determine what the ID field is, and to return that as part of the read().

Write

Write accepts a single element as an argument. The element is an array of data or records, possibly in jsormdb record format, possibly in journal format, e.g. in journal or condensed update mode. The return value is expected to be a single item in an encoded format suitable for consumption by the remote data source. This is normally a string, but is not required to be.