puter.kv.decr()

Decrements the value of a key. A missing or expired key starts from 0 and loses any TTL it had, and a live key keeps its TTL. The call rejects if the target holds anything other than a number, including a numeric string. The target is the whole value, or with a path map, the field at each path.

Syntax

puter.kv.decr(key)
puter.kv.decr(key, amount)
puter.kv.decr(key, pathAndAmount)
puter.kv.decr(key, amount, optConfig)

Parameters

key (String) (required)

The key of the value to decrement.

amount (Number | Object) (optional)

The amount to decrement the value by, which may be fractional or negative. Defaults to 1.

When amount is an object, each of its keys is a path to a field inside the stored value, such as "user.score", and its value is the amount to subtract from that field.

The amount must be within ±9,007,199,254,740,991 (Number.MAX_SAFE_INTEGER). A larger one is applied clamped to that bound. A counter stays exact only while its total is inside the same range, so store anything that has to count past it as a string with puter.kv.set().

Paths support dot notation, array indexes at any level ([0], items[0], or some.path[1].to.value), and quoted property names (["key.with.dots"]). An empty path ("") targets the whole stored value. Use non-negative integer indexes in brackets to address arrays. When a path continues through an array element (for example, [0].score), that element must already exist. Missing object parents are created automatically, but sparse array elements aren't. A path may chain at most 31 levels, and a deeper one rejects with bad_request. Quoted names can't be empty. All of a call's paths go into one write, so a call fits at most 1,500 path segments and, with short field names, about 60 paths. Split larger changes across calls. See Rate Limits and Quotas.

optConfig (Object) (optional)

The last argument. It takes these properties:

• handle (String): Works on data another user shared with you, using the handle from puter.kv.listShared(). The key is then relative to the shared prefix, and the share needs write access. See Sharing with other users.
• appUuid (String): Works on another app's data, which the user let your app reach with puter.perms.request('appData', …). It can't be combined with handle.

Pass optConfig after amount, as in puter.kv.decr('stats', 1, { handle }). An object in the place of amount is read as a path map.

Return value

A Promise that resolves to the new value. That's a number for the plain form, or the whole stored value when amount is a path map.

Errors

A rejection carries an Error with a stable code:

Examples

Decrement the value of a key

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.kv.decr('testDecrKey').then((newValue) => {
            puter.print(`New value: ${newValue}`);
        });
    </script>
</body>
</html>

Decrement a property within an object value

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        (async () => {
            // If 'stats' contains: { user: { score: 10 } }
            await puter.kv.set('stats', {user: {score: 10}})

            // This decrements user.score by 2
            const newValue = await puter.kv.decr('stats', {"user.score": 2});

            // newValue will be: { user: { score: 8 } }
            puter.print(`New value: ${JSON.stringify(newValue)}`);
        })();
    </script>
</body>
</html>