Options

All .read(), .write(), .delete() and other methods take an optional Options parameter, and so do PrefsDB.getkey()/PrefsDB.createkey(). It is an object containing a set of values, overrides that can be utilized to change how prefsdb.com works.

---

timeout

Request / query timeout, in milliseconds. Default value is 10000 (10 seconds).

{
    timeout: 30000
}

This will make a request to read data give up after 5 seconds.

await db.key("theme").read({ timeout: 5000 });

---

onsuccess

Function to be called when data is received. Default value is null. A Promise is returned either way; the callback is an alternative to awaiting it.

{
    onsuccess: (response) => {
        data = response.value;
    }
}

The response will contain either value or values fields. Which one will be set will depend whether a query returns a single value or multiple values. The number of values returned will be reported in count field.

---

onerror

Function to be called when the request failed (e.g. a timeout — see Error Codes). Default value is null. Without it, handle errors with try/catch around await (or .catch()), or they will go unnoticed.

{
    onerror: (error) => {
        alert(error.message);
    }
}

Error object most likely will look like this:

{
    success: false, 
    ts: 1772942415973, 
    error: "TIMEOUT", 
    message: "The operation timed out."
}

A response from the server that reports a failure (e.g. "success": false with "message": "Missing API key") is not an error in this sense: it goes to onsuccess and resolves the Promise, so check response.success.

---

Read options

.read() also takes these, to read a large list in pages (see Reading in pages):

option	default	description
limit	—	How many values to return, from 1 up to 1,000.
after	—	Continue after a previous page: pass that response's next.
start	0	Skip this many values first. Use after or start, not both.

const page = await db.list("events").read({ limit: 100 });

Key options

PrefsDB.getkey() and PrefsDB.createkey() also take:

option	default	description
email	—	Email address for a brand-new key; a verification link is sent to it. Needed only when a new key is created (unless the site sponsors its users' keys).
namespace	—	Keeps keys apart when there's no browser Origin header (Node, scripts). Use a long random value and keep it secret. Not needed with a key created in your dashboard.
appcred	PrefsDB.APPCRED	An app credential from your dashboard's App Credentials panel. Does the same job as namespace, but a mistyped or revoked one is an error. Use one or the other, not both.
offline	true	Keep working offline: reads come from a local cache and writes are sent when the connection is back. See Offline and Optimistic Writes.
offlineTtl	28800	Seconds that writes saved offline can still be sent after this call (8 hours; at most 7 days).
sessionTtl	60	Seconds the session from this call lasts.
optimistic	false	Make writes resolve immediately, before the server confirms them.
throwOnError	false	Reject the Promise when the server refuses a request, instead of resolving with success: false. Applies to every request made with the returned object. See How the JavaScript client reports errors. Also an option of PrefsDB.client().
encryption	—	Turn on client-side encryption for the returned instance, e.g. { key }. Off unless you pass it. It changes what PrefsDB and the dashboard can do with your data: read that page first.
remember	false	Keep this device signed in, so PrefsDB.resume() gets the key back after a reload without the passphrase. true for 30 days, or { days, device }. Read Staying Signed In first. Sign-ins take it too.

Options example

    await db.key("username").write(stats, {
        onsuccess: (response)=>{
            console.log("Data saved ok");
        },
        onerror: (error)=>{
            console.log("error: %s", error.message);
        },
        timeout: 60000
    });