Copy page

puter.kv.set()

Websites Puter Apps Node.js Workers

When passed a key and a value, will add it to the user's key-value store, or update that key's value if it already exists.

Each app has its own key-value store within each user's account. Another app can only reach it if the user explicitly grants that with puter.perms.requestAppData() — and never for entries you write with disableSharing.

Syntax 

puter.kv.set(key, value)
puter.kv.set(key, value, expireAt)
puter.kv.set({ key, value, expireAt })
puter.kv.set([ { key, value, expireAt }, ... ])
puter.kv.set({ items: [ { key, value, expireAt }, ... ] })

Parameters

key (String) (required)

A string containing the name of the key you want to create/update. The maximum allowed key size is 1 KB.

value (String | Number | Boolean | Object | Array)

A string containing the value you want to give the key you are creating/updating. The maximum allowed value size is 400 KB.

expireAt (Number) (optional)

A number containing when the key should expire in timestamp seconds.

disableSharing (Boolean) (optional)

Pass inside the trailing options object — set(key, value, { disableSharing: true }) — to mark this entry private to your app. A private entry cannot be read, listed, changed, or deleted by any other app, even one the user has granted access to your app's data with puter.perms.requestAppData(). Use it for anything another app should never see, such as a cached access token: a user approving a request cannot see what your store holds.

The batch form takes it too — set([...items], { disableSharing: true }) marks every entry in the batch.

Your own app reads and writes the entry normally. Writing the same key again without the flag makes it shareable once more, since set replaces the whole entry.

items (Array) (batch only)

An array of { key, value, expireAt? } objects, set in a single request. Each key is required and follows the same 1 KB key / 400 KB value limits. You can pass the array directly (set([...])) or wrapped in an object (set({ items: [...] })).

You may also pass a single object instead of positional arguments: set({ key, value, expireAt }).

Return value

A Promise that will resolves to true when the key-value pair has been created or the existing key's value has been updated.

Examples

Store a value no other app can ever read

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.kv.set('accessToken', 'secret-value', { disableSharing: true })
            .then(() => puter.print('Stored privately'));
    </script>
</body>
</html>

Create a new key-value pair

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        puter.kv.set('name', 'Puter Smith').then((success) => {
            puter.print(`Key-value pair created/updated: ${success}`);
        });
    </script>
</body>
</html>

Set multiple key-value pairs at once

<html>
<body>
    <script src="https://js.puter.com/v2/"></script>
    <script>
        (async () => {
            await puter.kv.set([
                { key: 'name', value: 'Puter Smith' },
                { key: 'age',  value: 21 },
            ]);
            puter.print('Batch set complete');
        })();
    </script>
</body>
</html>

NEXT

get()

PREVIOUS

Key-Value Store