Run Code Only Once


Some things should only happen once, like showing a welcome tour or giving out a daily reward. The obvious way is to read a flag, do the thing, then set the flag. But two tabs can both read the flag before either one sets it, and then both do it. This is called a race condition.

To avoid it, check and set the flag in one call. The onlyIfAbsent option of puter.kv.set() writes a key only when it doesn't exist yet, and resolves to true only for the call that wrote it.

Run Once

Pass { onlyIfAbsent: true } and only run the action when the call resolves to true:

if ( await puter.kv.set('welcomeTourShown', true, { onlyIfAbsent: true }) ) {
    showWelcomeTour();
}

The first call writes the key and resolves to true. Every call after that finds the key, writes nothing and resolves to false. When two tabs try at the same moment, only one of them gets true.

Data in puter.kv is stored per user and per app, so this runs once per user, across all their tabs and devices. Two calls at nearly the same moment from different places can both get true, so use it where a rare repeat is harmless, like a tour. To show the tour again, delete the key with puter.kv.del().

Run Once per Day

Put the date in the key, so each day gets a new key. The third argument of puter.kv.set() is when the key expires, as a Unix timestamp in seconds, so old keys delete themselves:

const today = new Date().toISOString().slice(0, 10);   // '2026-10-31', in UTC
const inTwoDays = Math.floor(Date.now() / 1000) + 2 * 24 * 60 * 60;

if ( await puter.kv.set(`dailyReward:${ today }`, true, inTwoDays, { onlyIfAbsent: true }) ) {
    giveDailyReward();
}

For once an hour, use toISOString().slice(0, 13) instead. To hold a key only while some work runs, see Set a Lock or Cooldown.

Allow It a Few Times

To allow an action more than once, count the tries with puter.kv.incr(). It adds 1 on the server and returns the new count, so two tabs that try at once get different numbers. This allows three free exports a day:

const key = `freeExports:${ today }`;
const used = await puter.kv.incr(key);
if ( used === 1 ) {
    await puter.kv.expire(key, 2 * 24 * 60 * 60);   // delete it after 2 days
}

if ( used <= 3 ) {
    await exportFile();
} else {
    showUpgradePrompt();
}

Since puter.kv.incr() takes no expiry, the first try sets one with puter.kv.expire(). Tries that get turned down still count, so the number can go past 3, and anything over 3 is turned down anyway. Add Counters covers counting in more detail.

Run Once Across All Users

Code in the browser can be changed by the user, and puter.kv only holds one user's data. To run something once for everyone, or to guard something valuable like a payment, do the check in a worker. Inside a worker, me.puter is Puter.js signed in as you, the worker's owner, so every request reads and writes the same keys.

Services that send webhooks, like payment providers, send an event again if your reply is slow or fails. This worker route claims each event's ID before handling it:

router.post('/webhooks/payments', async ({ request }) => {
    const event = await request.json();
    const key = `handled:${ event.id }`;
    const inAWeek = Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60;

    if ( ! await me.puter.kv.set(key, true, inAWeek, { onlyIfAbsent: true }) ) {
        return { received: true };   // already handled
    }

    try {
        await handlePayment(event);
    } catch ( error ) {
        await me.puter.kv.del(key);   // let the next retry handle it
        throw error;
    }
    return { received: true };
});

A retry arrives seconds or minutes after the first delivery, so it finds the claim and skips the event. Keep the key longer than the sender keeps retrying. A week is enough for most services. If handling the event fails, the key is deleted and the worker answers 500, so the next retry handles it. Build an API with a Worker covers routes that outside services call.

← All recipes