AgentStorage

The AgentStorage library helps you manage data in the persistent data table typically created by calling the imp API method server.save() table and read using server.load().

If you are using the AgentStorage class, it is highly recommended that you remove all server.save() and server.load() calls from your code.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

To add this library to your project, add

#require "AgentStorage.class.nut:1.0.0"

to the top of your agent code

Class Usage

Constructor: AgentStorage()

The class constructor creates a new AgentStorage object. It has no parameters.

#require "AgentStorage.class.nut:1.0.0"

db <- AgentStorage();

Class Methods

read(key)

The read() method attempts to read a value from the persistent data table. If the key key exists, its value will be returned, otherwise the method returns null.

local apiKey = db.read("apiKey");
if (apiKey != null) {
    webRequest(apiKey);
}

write(key, data)

The write() method inserts or updates data in the persistent data table and returns the inserted/updated value.

http.onrequest(function(req, resp) {
    if ("apiKey" in req.query) {
        db.write("apiKey", req.query.apiKey);
    }
    resp.send(200, "OK");
});

setDefault(key, data)

The setDefault() method ensures the specified key exists in the persistent data table. If the key does not yet exist, setDefault() creates it then writes data to it; it returns what was written. If the key already exists, setDefault() does not modify the persistent data table, and returns the existing data.

// Write 1 to timesRun if it doesn't exist yet
timesRun <- db.setDefault("timesRun", 1);
server.log("This code has run " + timesRun + " times");
db.write("timesRun", timesRun + 1);

exists(key)

Returns true if the specified key key exists in the persistent data table, or false if not.

if (!db.exists("username")) {
    throw "Missing required field 'username'";
} else {
    webRequest(username);
}

remove(key)

Removes a field from the persistent data table and returns the removed value. If the key was not found, remove() returns null.

// Write a value
db.write("field", 123);
server.log(db.read("field"));

// Remove a value
db.remove("field");
server.log(db.read("field"));

clear()

The clear() method clears the persistent data table of all keys and values.

http.onrequest(function(req, resp) {
    local path = req.path.tolower();
    if (path == "/reset" || path == "/reset/") {
        db.clear();
    }
    resp.send(200, "OK");
});

len()

The len() method returns the number of top level elements in the persistent data table.

if (db.len() == 0) {
    // No data in server.save yet
    // Do something...
}

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release

License

The AgentStorage library is licensed under the MIT License.