Read Data

Overview

---

Data can be retrieved using the equivalent function that were used to store it: key/value pairs, large data blobs or serialize and deserialize entire objects.

Syntax:

         .read( [options] )

         .readAll( [options] )

         .getItem( key, [options])

         .getObject( name, [options])

All functions can return data either via a callback or with a Promise. If "onsuccess" handler is not provided in the"Options", a Promise will be returned.

    Promise promise = prefsdb.read();

    prefsdb.read( { onsuccess: (response)=> {} });

Parameters

parameter	type	description
name | key	string	object or data key identifier
options	{ }	[Optional] An object containing additional parameters and overrides such as timeout, onsuccess, or onerror.

Promise vs. Callback

When reading data, if 'onsuccess' callback is not provided, a Promise will be returned.

.read()

The core read operation. Use either a Promise or a callback function to collect query results.

Usage:

    [Promise p] = .read()

    .read({ onsuccess: (result)=>{ } });

Same grouping rules must be applied to read data, as when the data was written. For instance, if you saved an object under a specific project and domain, you must use the same parameters to retrieve that object.

    const mySettings = {...}

    /* save settings */
    prefs_us.project("foo").domain("bar")
                .key("display-settings").write(mySettings);

    /* restore settings */
    prefs_us.project("foo").domain("bar")
                .key("display-settings")
                .read({
                    onsuccesss: (R)=>{ mySettings = R.value; } 
                });

.getItem()

Convenience method for familiarity with local Storage in a browser. However, unlike localStorage methods, this call is asynchronous. Use a Promise or a callback function to retrieve the query result.

Usage:

    [Promise p] = .getItem("name")

    .getItem("name", { onsuccess: (result)=>{} })

.getObject()

Retrieve a serialized object.

Usage:

    [Promise p] = .getObject("name");

    .getObject("name", { onsuccess: (result)=>{} })

Response

Generally a response will contain a combination of the fields below. Which ones? it mostly depends on the status of the query. For example, a successful response will not have error message.

{ 
    status  : "string", 
    success : boolean,
    ts      : "string|number",
    value   : {}
    values  : {}
    error   : "string",
    message : "string"

}

​ The response will contain one of the value or values fields. Which one it is will depend on the expected outcome of a request. If expected outcome is a single object or a single piece of data, then a value will be set. If the expected outcome is multiple objects or pieces of data, then values will be set.

Generally, any key/value operation will return a single value object and operations like .readAll() will typically return an array of data objects, thus the values field.

Callbacks vs Promises

All methods can either return a Promise or accept a callback as a parameter. You choose which one to use by supplying or not supplying a callback function. If there is no callback (Options: { "onsuccess":null }), a Promise will be returned, in which case you will need to process all responses manually.

Examples

---

Read key/value

First, include prefsdb.com Javascript library in your project:

    <script src="https://prefsdb.com/prefsdb.com.js"></script>

This will create prefs_us instance in your script.

JavaScript with a callbackJavaScript with Promise

prefs_us.read( { 
    onsuccess: (data) => {
        if (data.success) {
            var mydata = data.values;
        }
    },
    onerror: (error) => {
        console.log("Error: %o", error);
    }
});

prefs_us.read()
    .then( (response) => response.json())
    .then((data) => {
        console.log(data.values);
    })
    .catch( (error) => {
        console.log(error);
    });

Note

All data is returned as Content-Type: text/plain

Deserialize an object

To retrieve the saved instance of an object (deserialization) we use .read() function with a callback.

let obj = null;

prefs_us.read("myObj") 
    .then( (response) => response.json())
    .then( (data) => {
        obj = JSON.parse(data.value);
    })

Lists

Lists are un-ordered collections of data. Prefsdb.com makes it easy and effortless to collect data in a list.

prefs_us.list("signups")
        .read( (result) => { mylist = result.values; });