Store Items by ID

Key-ValueData Modeling

Store a small list keeps items in an array and edits them by index. When the same user edits the list from two tabs or devices at once, a delete in one tab shifts the indexes, and the other tab can edit or delete the wrong item.

Storing the list as an object keyed by item ID avoids that. Each item has a fixed ID, so an edit or delete always targets the correct item. The list is still one key-value entry, and you read all of it with a single puter.kv.get() call.

Add an Item

To add an item, use the puter.kv.update() method with the id as the path:

const id = crypto.randomUUID();

await puter.kv.update('todos', {
    [id]: { text: 'Buy milk', done: false, at: Date.now() },
});

The id becomes the key you reference later to update or delete that item. Because it is used as a KV path, use a path-safe unique string; crypto.randomUUID() is a safe default.

Show the List

To load the list, use the puter.kv.get() method. One read returns every item:

const todos = await puter.kv.get('todos') ?? {};

const items = Object.entries(todos)
    .map(([id, todo]) => ({ id, ...todo }))
    .sort((a, b) => a.at - b.at);

An object has no inherent order, and the stored field order is not preserved on read, so carry an at or order field on each item and sort when you render. At sizes that fit in one entry, sorting in memory costs nothing measurable.

Edit an Item

To change one field of one item, use the puter.kv.update() method with the item's id and the field you are changing:

await puter.kv.update('todos', { [`${ id }.done`]: true });

This changes that one item and leaves the rest of the list as it was.

Delete an Item

To remove an item, use the puter.kv.remove() method with its id:

await puter.kv.remove('todos', id);

It also takes several paths in one call, so remove('todos', idA, idB) deletes two items at once.

When to Switch

One entry holds up to 400 KB, which is a few thousand small items. If your list holds more than that, or you expect it to, store a large collection instead, which gives you:

← All recipes