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.

All core data retrieval operations are doned with the .read() function. Other functions are basically syntactic sugar, aliases in one form or the other .

Syntax:

         .read( [callback], [options] )

         .getItem( key, [callback], [options])

         .getObject( name, [callback], [options])

[Promise promise = ] .read( [callback] , [options] )

Parameters

parameter	type	description
name | key	string	object or data key identifier
callback	function()	[Optional] A callback function where you retrieve your data. If null, a Promise will be returned, which you will need to handle yourself.
options	{ }	[Optional] An object containing additional parameters and overrides

.read()

The core read operation. Use either a Promise or a callback function to retrieve the query result.

Usage:

[Promise p] = .read( [callback] )

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( (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("key" [, callback])

It is equivalent to

.key("key").read([callback])

.getObject()

Retrieve a serialized object. An alias of .getItem().

Usage:

[Promise p] = .getObject("objName" [, callback] );

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, a Promise will be returned, in which case you will need to process all responses manually.

Examples

---

Read key/value

First, include prefs.us Javascript library in your project:

    <script src="https://prefs.us/prefs.us.js"></script>

This will create prefs_us instance in your script.

JavaScript with a callbackJavaScript with Promise

prefs_us.read( (data) => {
    if (data.success) {
        var mydata = data.values;
    }
});

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.getObject("myObj", (response) => {
    obj = JSON.parse(R.value);
});

Lists

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

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