Write Data

Overview

---

At the core, prefs.us can write and store anything from simple key/value pairs, to large data blobs, or serialize and deserialize entire objects.

All functions take up to three parameters: the data, a callback function, and options. Two of them (callback and options) are... optional.

Syntax:

         .write( data, [callback], [options])

         .post( data, [callback], [options])

         .setItem( item, [callback], [options])

         .putObject( object, [callback], [options])

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

The core write operations can be performed with either .write() or .post() functions. All others are aliases in one form or the other and typically only differ by the size or type 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.

Parameters

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.

Response

Generally a response will contain a an indicator of how many fields were changed. Field updated show how many values were updated - should be 1 or 2. 2 is not an error, it is a correct number indicating internal update path.

{ 
    success: true, 
    status: "success",
    updated: "1",  
    message: "", 
    ts: "2026-03-26 21:16:11" }
}

When no data was written, either the data has not changed or attempt was made to write an empty value.

{ 
    success: true, 
    status: "success", 
    updated: "0", 
    message: "No new data written.", 
    ts: "2026-03-26 21:14:07" 
}

.write()

Use .write() method to store simple key/value data pairs - something that HTTP GET would handle.

.post()

Use .post() method to store large blobs or to serialize objects. Equivalent of HTTP POST.

.setItem()

Convenience alias method for familiarity with local Storage in a browser.

Usage

.setItem("key", "value")

It is equivalent to

.key("key").post("value")

.putObject()

Convenience method for object serialization.

Usage:

.putObject("name", object)

It is equivalent to

.key("name").post(object)

Examples

---

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)

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);

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")
        .add("jane.doe@somewhere.com");

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"
}