Write Data

Overview

---

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

All functions take two parameters: the data, and the options construct. Options is optional.

Syntax:

         .write( data, [options])

         .post( data, [options])

         .setItem( item, [options])

         .putObject( object, [options])

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

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

Methods like putObject() or getObject() handle Simple Object Storage Service (SOSS) to store and retrieve files.

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.
options	{ }	Optional object containing overrides, such as set your own request timeout, onsuccess and onerror handlers. This parameter is optional, however, omitting it carries certain implications. Functions that return data will return a Promise instance if onsuccess option is not provided.

.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 prefsdb.com Javascript library in your project:

<script src="https://prefsdb.com/prefsdb.com.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. Prefsdb.com makes it easy and effortless to collect data in a list.

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

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 (has to do with internal key constraints being triggered).

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

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: prefsdb.com 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"
}