Keep a Version History
Lots of editors let you go back to an earlier version, like the version history
in Google Docs. With puter.kv, you can do this by saving a copy of the
document under a numbered key every time it's saved. Old copies can delete
themselves after a while.
This recipe uses notes, with three kinds of keys per note:
| Key | Holds |
|---|---|
note:<id> |
The current version |
note-history:<id>:00000007 |
A copy of version 7. Each save adds one |
note-revision:<id> |
The latest version number |
Save a Version
Each save gets the next version number, then writes the current version and a copy in one call:
const versionKey = (noteId, number) =>
`note-history:${ noteId }:${ String(number).padStart(8, '0') }`;
async function saveNote (noteId, text) {
const number = await puter.kv.incr(`note-revision:${ noteId }`);
const in30Days = Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30;
await puter.kv.set([
{ key: `note:${ noteId }`, value: { text, version: number } },
{
key: versionKey(noteId, number),
value: { text, number, savedAt: Date.now() },
expireAt: in30Days,
},
]);
return number;
}
puter.kv.incr() gives every save its own number, even when two
tabs save at once. The number is padded with zeros so the keys sort in order
(otherwise 10 would come before 9).
Passing an array to puter.kv.set() writes both keys in one
request. The copy gets an expireAt, a Unix time in seconds, so it's deleted
after 30 days. The current version has no expiry, so the note itself stays. The
two writes aren't a transaction, so if the call fails, one of them may already
be saved, and saving again fixes it.
If two tabs save at the same moment, both versions end up in the history, and whichever save arrived last becomes the current version.
Every version is a full copy, so a long note saved often takes up a lot of space. Save when the user pauses typing, or once a minute, rather than on every keystroke.
Show the History
To list a note's versions, call puter.kv.list() with the note's
prefix. With reverse: true the newest version comes first, and limit loads
one page at a time:
async function loadHistory (noteId, cursor) {
return await puter.kv.list({
pattern: `note-history:${ noteId }:`,
returnValues: true,
reverse: true,
limit: 20,
cursor,
});
}
const page = await loadHistory(noteId);
for ( const { value } of page.items ) {
console.log(value.number, new Date(value.savedAt), value.text);
}
The pattern ends with :, so listing the note abc doesn't also return the
versions of a note called abcd.
If there are more versions, the page includes a cursor. Pass it back to load
the next page of older versions, for example from a "Show older" button:
const older = await loadHistory(noteId, page.cursor);
Expired copies are skipped, so a page can hold fewer than limit items while
more are left. Add fetchUntilFull: true to fill each page when it can be.
Store a Large Collection covers
paging in more detail.
Restore a Version
To restore a version, read its copy and save it again:
async function restoreVersion (noteId, number) {
const version = await puter.kv.get(versionKey(noteId, number));
if ( version !== null ) { // null once the copy has expired
await saveNote(noteId, version.text);
}
}
Restoring adds a new version on top instead of deleting the newer ones, a bit
like git revert. If the user changes their mind, nothing is lost.
To undo the last save, restore the version before the current one:
async function undoLastSave (noteId) {
const note = await puter.kv.get(`note:${ noteId }`);
if ( note !== null && note.version > 1 ) {
await restoreVersion(noteId, note.version - 1);
}
}
Keep Only the Last Few Versions
To also cap how many copies a note keeps, delete the copy that falls out of the
window after each save. Version numbers go up by one, so after saving version 57
with 50 kept, version 7 goes. This is the whole saveNote() with that added:
const KEEP = 50;
async function saveNote (noteId, text) {
const number = await puter.kv.incr(`note-revision:${ noteId }`);
const in30Days = Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30;
await puter.kv.set([
{ key: `note:${ noteId }`, value: { text, version: number } },
{
key: versionKey(noteId, number),
value: { text, number, savedAt: Date.now() },
expireAt: in30Days,
},
]);
if ( number > KEEP ) {
await puter.kv.del(versionKey(noteId, number - KEEP));
}
return number;
}
If a delete fails, that one copy stays until it expires.
Delete a Note and Its History
There's no call that deletes every key with a prefix, so list the keys and
delete them one at a time. With stream: true, the list is read a page at a
time:
async function deleteNote (noteId) {
for await ( const page of puter.kv.list({ pattern: `note-history:${ noteId }:`, stream: true }) ) {
for ( const key of page.items ) {
await puter.kv.del(key);
}
}
await puter.kv.del(`note:${ noteId }`);
await puter.kv.del(`note-revision:${ noteId }`);
}
Deleting keys while the list is still being read is safe.
Full Code
const KEEP = 50;
const versionKey = (noteId, number) =>
`note-history:${ noteId }:${ String(number).padStart(8, '0') }`;
async function saveNote (noteId, text) {
const number = await puter.kv.incr(`note-revision:${ noteId }`);
const in30Days = Math.floor(Date.now() / 1000) + 60 * 60 * 24 * 30;
await puter.kv.set([
{ key: `note:${ noteId }`, value: { text, version: number } },
{
key: versionKey(noteId, number),
value: { text, number, savedAt: Date.now() },
expireAt: in30Days,
},
]);
if ( number > KEEP ) {
await puter.kv.del(versionKey(noteId, number - KEEP));
}
return number;
}
async function loadHistory (noteId, cursor) {
return await puter.kv.list({
pattern: `note-history:${ noteId }:`,
returnValues: true,
reverse: true,
limit: 20,
cursor,
});
}
async function restoreVersion (noteId, number) {
const version = await puter.kv.get(versionKey(noteId, number));
if ( version !== null ) { // null once the copy has expired
await saveNote(noteId, version.text);
}
}
async function undoLastSave (noteId) {
const note = await puter.kv.get(`note:${ noteId }`);
if ( note !== null && note.version > 1 ) {
await restoreVersion(noteId, note.version - 1);
}
}
async function deleteNote (noteId) {
for await ( const page of puter.kv.list({ pattern: `note-history:${ noteId }:`, stream: true }) ) {
for ( const key of page.items ) {
await puter.kv.del(key);
}
}
await puter.kv.del(`note:${ noteId }`);
await puter.kv.del(`note-revision:${ noteId }`);
}