Skip to content

Add kv.list() pagination playground example #2760

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
reynaldichernando merged 3 commits into from
Apr 3, 2026
+86 −11
Merged

Add kv.list() pagination playground example #2760

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9fcdab2
Add kv.list() pagination playground example
tmchow Apr 2, 2026
5343030
fix: address review feedback - restore code example, create new pagin…
tmchow Apr 3, 2026
5ecf952
minor refactor
reynaldichernando Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 33 additions & 6 deletions src/docs/src/KV/list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,22 +86,49 @@ If the user has no keys, the array will be empty.

<strong class="example-title">Paginate results with a cursor</strong>

```html
```html;kv-list-pagination
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
const firstPage = await puter.kv.list({ limit: 2 });
puter.print(`First page: ${firstPage.items}<br>`);
// Create sample data
for (let i = 1; i <= 6; i++) {
await puter.kv.set(`item-${i}`, `value-${i}`);
}
puter.print('Created 6 key-value pairs<br><br>');

// Paginate with cursor (2 items per page)
let currentCursor = undefined;
let page = 1;
do {
const result = await puter.kv.list({
limit: 2,
returnValues: true,
cursor: currentCursor,
});
const items = result.items;
puter.print(`<b>Page ${page}:</b><br>`);
for (const item of items) {
puter.print(` ${item.key} => ${item.value}<br>`);
}
puter.print('<br>');
currentCursor = result.cursor;
page++;
} while (currentCursor);

puter.print('Done paginating.<br><br>');

if (firstPage.cursor) {
const secondPage = await puter.kv.list({ cursor: firstPage.cursor });
puter.print(`Second page: ${secondPage.items}<br>`);
// Cleanup
for (let i = 1; i <= 6; i++) {
await puter.kv.del(`item-${i}`);
}
puter.print('Cleaned up sample data.');
})();
</script>
</body>
</html>

```

<strong class="example-title">Sort keys lexicographically</strong>
Expand Down
6 changes: 6 additions & 0 deletions src/docs/src/examples.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,6 +407,12 @@ const examples = [
slug: 'kv-list',
source: '/playground/examples/kv-list.html',
},
{
title: 'List (Pagination)',
description: 'Paginate key-value results with a cursor and limit using puter.kv.list(). Run and modify this example in the playground.',
slug: 'kv-list-pagination',
source: '/playground/examples/kv-list-pagination.html',
},
{
title: 'List (Sorted)',
description: 'See how keys are returned in lexicographic order with puter.kv.list(). Run and modify this example in the playground.',
Expand Down
41 changes: 41 additions & 0 deletions src/docs/src/playground/examples/kv-list-pagination.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
<html>
<body>
<script src="https://js.puter.com/v2/"></script>
<script>
(async () => {
// Create sample data
for (let i = 1; i <= 6; i++) {
await puter.kv.set(`item-${i}`, `value-${i}`);
}
puter.print('Created 6 key-value pairs<br><br>');

// Paginate with cursor (2 items per page)
let currentCursor = undefined;
let page = 1;
do {
const result = await puter.kv.list({
limit: 2,
returnValues: true,
cursor: currentCursor,
});
const items = result.items;
puter.print(`<b>Page ${page}:</b><br>`);
for (const item of items) {
puter.print(` ${item.key} => ${item.value}<br>`);
}
puter.print('<br>');
currentCursor = result.cursor;
page++;
} while (currentCursor);

puter.print('Done paginating.<br><br>');

// Cleanup
for (let i = 1; i <= 6; i++) {
await puter.kv.del(`item-${i}`);
}
puter.print('Cleaned up sample data.');
})();
</script>
</body>
</html>
11 changes: 6 additions & 5 deletions src/docs/src/playground/examples/kv-list.html
View file
Open in desktop
Comment thread
tmchow marked this conversation as resolved.
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,25 @@
await puter.kv.set('name', 'Puter Smith');
await puter.kv.set('age', 21);
await puter.kv.set('isCool', true);
document.write("Key-value pairs created/updated<br><br>");
puter.print("Key-value pairs created/updated<br><br>");

// (2) Retrieve all keys
const keys = await puter.kv.list();
document.write(`Keys are: ${keys}<br><br>`);
puter.print(`Keys are: ${keys}<br><br>`);

// (3) Retrieve all keys and values
const key_vals = await puter.kv.list(true);
document.write(`Keys and values are: ${(key_vals).map((key_val) => key_val.key + ' => ' + key_val.value)}<br><br>`);
puter.print(`Keys and values are: ${(key_vals).map((key_val) => key_val.key + ' => ' + key_val.value)}<br><br>`);

// (4) Match keys with a pattern
const keys_matching_pattern = await puter.kv.list('is*');
document.write(`Keys matching pattern are: ${keys_matching_pattern}<br>`);
puter.print(`Keys matching pattern are: ${keys_matching_pattern}<br>`);

// (5) Delete all keys (cleanup)
await puter.kv.del('name');
await puter.kv.del('age');
await puter.kv.del('isCool');
})();
</script>
</body>
</body>
</html>