Write

With prefs.us, we can write and store simple key/value pairs, large data blobs or serialize and deserialize entire objects.

To store data we use .write() and .post() functions. They both take up to three parameters (two of them being optional). They only differ by the size of the data they can handle.

Use .write() method to store simple key/value data pairs - something that HTTP GET would handle. Use .post() method to store large blobs or to serialize objects.

Syntax:

         .write( data, callback, options)

         .post( data, callback, options)

[Promise promise = ] .write( data , [callback] , [options] )

[Promise promise = ] .post( object, [callback] , [options] )

parameter	type	description
data	text | object	Data to be stored. Use .write() to store simple "key"="value" pairs, and .post() to store large data chunks or to serialize objects.
callback	function()	Optional callback function. Use it to capture a response.
options	{ }	Optional object containing overrides, such as set your own request timeout, etc.

Key/value Example

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

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

Then set your API Key token.

prefs_us.getkey("keyId", ["secret1", "secret2", ...]);

IMPORTANT!

Make sure to use the same secrets in the seed array. If you change seed parameters or even reorder them within an array - it will result in a new key being generated and existing data under the old key may be lost.

You are now ready to store and retrieve data.

For instance, to store a value identified by a key named foobar

prefs_us.key("foobar")
        .write("theme=light,score=200,level=3");

or

prefs_us.key("theme")
        .write("light")
        .key("score")
        .write(200)
        .key("level")
        .write(3)

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

prefs_us.list("signups")
        .add("jane.doe@somewhere.com");

Object serialization

The sample code below serializes (saves) an object instance as "myObj".

const obj = { field1: "A", field2: "B", ... };

prefs_us.key("myObj").post(obj);

Deserialization

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

let obj = null;

prefs_us.key("myObj").read( (response) => {
    obj = JSON.parse(R.value);
});

Organizing stored data.

Any piece of data can be additionally categorized and stored under a named project, domain, or subdomain.

JavaScriptJavapython

const data = "base64abcd...";

prefs_us.using(APIKEY);
prefs_us.ttl(10)                // store for 10 days only
        .project('my-project')  // grouping
        .domain('test-domain')  // grouping
        .key('JohnDoe')         // additional (optional) identifier for posted data blob
        .post(data);            // use HTTP POST  

import com.gorny.prefsus;

String data = "base64abcd...";
PrefsUs prefs = new PrefsUs(APIKEY);

prefs.ttl(10)               // store for 10 days only
    .project("my-project")  // grouping
    .domain("test-domain")  // grouping
    .key("JohnDoe")         // additional identifier
    .post(data);            // use HTTP POST  

import prefus as prefs

String data = "base64abcd...";
prefs.using(APIKEY);

#
# Python comments space filler. 
# TODO: prefs.us integrations for all major server side tech like fastAPI?
#

prefs.ttl(10)              # store for 10 days only
    .project("my-project") # grouping
    .domain("test-domain") # grouping
    .key("JohnDoe")        # data chunk identifier
    .post(data);           # use HTTP POST

The piece of data save above can be retrieved using the sample code below. An optional callback was added to check the result of read/write operation.

JavaScript Read Example

prefs_us.project('my-project')
    .domain('test-domain')
    .key('JohnDoe')
    .read( (incoming) => {
        if (incoming.status === 'success') {
            var mydata = incoming.values;
        }
    });

Handling Errors

The callback function will return a response whether the operation was successful or not. If the operation failed for some reason, an error code and an error message will be provided.

Write success

A successful write operation will return the following response:

{ 
    success: true,
    status: "success",
    message: "", 
    updated: "1", 
    ts: "2026-03-12 02:15:56" 
}

Write failure

A failed operation will have its sucess status set to false and offer more details about the error with error code and an error message.

{
    success: false, 
    status: "error", 
    ts: "2026-03-12 03:18:28", 
    error: "400 Bad Request", 
    message: "Missing API key"
}