Skip to main content

values

The game's data kept on Arcadible, as your game's function reaches it: JSON under a key, in a scope, for one game and one channel. The package is @arcadible/function-sdk, and a call needs no key and nothing set up.

import { values } from "@arcadible/function-sdk";

interface Values {
read<T extends ReadItem>(items: readonly T[]): Promise<(Value | UnchangedFor<T> | null)[]>;
write(items: readonly WriteItem[]): Promise<Written[]>;
remove(items: readonly RemoveItem[], options?: RemoveOptions): Promise<void>;
list(scope: Scope, options?: ListOptions): Promise<Page<Entry>>;
}

type Scope = "developer" | WritableScope;
type WritableScope = "game" | "server" | { readonly id: string };

type ReadItem = { scope: Scope; key: string; since?: number };
type WriteItem = { scope: WritableScope; key: string; value: unknown; revision?: number };
type RemoveItem = { scope: WritableScope; key: string; revision?: number };
type RemoveOptions = { onConflict?: "reject" | "skip" };

type Value = { scope: Scope; key: string; value: unknown; revision: number; updatedAt: string };
type Unchanged = { scope: Scope; key: string; revision: number; unchanged: true };
type Written = { scope: Scope; key: string; revision: number; updatedAt: string };
type UnchangedFor<T> = T extends { key: string; since?: undefined } ? never : Unchanged;
type Conflict = { scope: Scope; key: string };

type ListOptions = { prefix?: string; after?: string | null; limit?: number };
type Page<T> = { items: T[]; next: string | null };
type Entry = { key: string; revision: number; updatedAt: string; size: number | null };

Members​

MemberDescription
read(items)Values, across scopes, in one snapshot
write(items)Replaces values, all of them or none
remove(items, options)Removes values, all of them or none
list(scope, options)A scope's keys, without their values

Access​

A function's calls are allowed by Arcadible, which runs it: Arcadible knows which game and channel each run of your function is for, and stands in for a key.

  • Nothing to set up: no key, no environment variable, and no argument. The values a call reaches are your game's, on the channel of the build that runs the function.
  • Staging's function reaches staging's values, and production's, production's. Each channel has its own values.
  • What a function may do is the scopes' (below): read all four, and write all but the developer's.
  • Only in a function, on Arcadible or under arc serve: anywhere else, every call fails with invalid.

Scopes​

A scope says whose a value is. A function reads all four, and writes all but the developer's.

ScopeWhoseYour functionYour game, for its player
"developer"Yours: what you publish for the gameReadsReads
"game"The game's, shared by every playerReads and writesReads
"server"Your function's own, and your servers'Reads and writesNothing
A playerOne player's, in this game: any playerReads and writesReads and writes its own
  • Your function and a server of your own share them, on the same channel: what one writes, the other reads.
  • What the game reads, any player can. Keep what only your function should know, such as a match's answers, in "server".
  • A player's values are for a player of your game, logged in. A guest has none.

A player​

A player's scope is the player: anything with their id, such as what players.primary(request) gives, an entry of players.read, or a { id } you kept. Only the id is read. An id alone, null, or anything else fails with invalid.

const me = players.primary(request);
if (me === null || me.guest) return Response.json({ code: "guest" }, { status: 403 });
await values.write([{ scope: me, key: "progress", value: { level: 3 } }]);

Keys, values, and revisions​

  • A key is 1 to 128 letters, digits, -, _, ., and /. A / is a character like the rest, which list's prefix makes use of: match/4821.
  • A value is anything JSON holds, up to 64 KB, by JSON's own rules: what's kept is what JSON.stringify makes of it, so NaN is kept as null, and a property that's undefined is left out. Only what it can't make text of at all, undefined itself, a function, or a cycle, fails with invalid.
  • A revision is a number that changes each time a value is written, and is never 0 for a value that exists. Don't read anything else into it.
  • A time, updatedAt, is an ISO time, in UTC, to the millisecond: 2026-11-10T03:12:00.000Z.

Revisions and conflict​

A write or a remove that names a revision is made only if it's still the value's, so two writers never overwrite each other unseen.

  • Read, then write with the revision you read. When someone wrote in between, the call fails with conflict, and nothing in it is written: read again, and decide again.
  • The error names the items that conflicted: its conflicts is a list of { scope, key }, one for each item whose revision wasn't the value's, in the call's order, with the scope as you gave it. An item with no revision is never in it.
  • revision: 0 writes only if there's no value yet, so two runs of your function can't both create one.
  • Without a revision, the last write wins.
  • A write that fails with unavailable may have been kept: Arcadible may have written it before the answer was lost. Trying again with the same revision then fails with conflict, since the value moved on to your own write. So after unavailable, read again before you write again.
const [match] = await values.read([{ scope: "game", key: "match/4821" }]);
try {
await values.write([{ scope: "game", key: "match/4821", value: play(match?.value, move), revision: match?.revision ?? 0 }]);
} catch (err) {
if (!isArcadibleError(err, "conflict")) throw err;
// someone moved first: read the match again. err.conflicts is [{ scope: "game", key: "match/4821" }]
}

read(items)​

read<T extends ReadItem>(items: readonly T[]): Promise<(Value | UnchangedFor<T> | null)[]>

The values of the items, across scopes, in one request and one snapshot.

const [match, seats] = await values.read([
{ scope: "game", key: "match/4821" },
{ scope: "server", key: "seats/4821" },
]);
  • Resolves with a list as long as the one given, in its order: for each, the value, with the scope as it was given, or null for a key with none.
  • since on an item, a revision you have: when the value is still at it, the entry is { scope, key, revision, unchanged: true }, without its value.
  • In TypeScript, an entry is typed Value | null when no item can name since, and Value | Unchanged | null when one can: a read with no since needs no check for unchanged. That's what UnchangedFor says, of the items' type.
  • An empty list resolves with [], and asks nothing.
  • Fails with invalid for an item that isn't one, a key or a scope that isn't one, or a key named twice in a scope; too_many for more than 32 items; too_large when the values together are past 1 MB; denied for a player who isn't your game's.

write(items)​

write(items: readonly WriteItem[]): Promise<Written[]>

Replaces each item's value, whole, across scopes: all of them, or none.

await values.write([
{ scope: "game", key: "match/4821", value: next, revision: match?.revision ?? 0 },
{ scope: "server", key: "seats/4821", value: taken, revision: seats?.revision ?? 0 },
]);
  • Resolves with each item's { scope, key, revision, updatedAt }, in the order given: the value's new revision.
  • With revision, an item is written only if that's still the value's revision; 0 means only if there's no value. Otherwise the whole call fails with conflict, its conflicts naming the items, and nothing is written (Revisions and conflict).
  • Every item or none, always: a write has no way to skip an item, since what's written together is meant to agree. Write what's independent in calls of its own.
  • Without revision, the value is replaced whatever it was.
  • An empty list resolves with [], and asks nothing.
  • Fails with invalid and too_many as read does, and for a value that isn't JSON; denied for the developer's scope, or a player who isn't your game's; too_large for a value past 64 KB, or the call's values together past 256 KB; full when a scope's storage is used up.
  • A write that fails with unavailable may have landed, since Arcadible may have acted before its answer was lost: try it again, which is safe, since the same write twice ends the same. One that names a revision reads first: if the first try landed, the revision moved on, and a retry is refused with conflict (Revisions and conflict).

remove(items, options)​

remove(items: readonly RemoveItem[], options?: RemoveOptions): Promise<void>

Removes what each item holds: all of them, or none.

await values.remove([{ scope: "server", key: "seats/4821" }]);
OptionValueDefault
onConflict"reject": a conflict fails the call. "skip": it leaves that item, and the rest go"reject"
  • Resolves with nothing. Removing a key with no value does nothing.
  • With revision, an item is removed only if that's still the value's revision; otherwise the whole call fails with conflict, its conflicts naming the items, and nothing is removed.
  • With { onConflict: "skip" }, each item is on its own: one whose revision isn't the value's any more is left as it is, the rest are removed, and the call resolves, never failing with conflict. It's for clearing many values at once, where one that changed since you listed it shouldn't keep the rest (Examples).
  • An empty list asks nothing.
  • Fails with invalid, too_many, and denied as write does.
  • A remove that fails with unavailable may have landed, since Arcadible may have acted before its answer was lost: try it again, which is safe, since removing twice ends the same. One that names a revision reads first: if the first try landed, the revision moved on, and a retry is refused with conflict.

list(scope, options)​

list(scope: Scope, options?: ListOptions): Promise<Page<Entry>>

One scope's keys, in order, by byte, each with its revision, time, and size, and never its value.

const { items, next } = await values.list("game", { prefix: "match/" });
OptionValueDefault
prefixOnly the keys that start with itEvery key
afterWhere to go on from: the last page's next, as it cameThe first key
limitHow many keys, 1 to 10050
  • No options, or null, is every key, 50 at a time.
  • Resolves with a page, { items, next }: each item is { key, revision, updatedAt, size }, with size the value's, in bytes, or null where Arcadible doesn't say; next goes back as after for the following page, as it came, and is null at the end.
  • It isn't a snapshot: a value written between pages may show, or not.
  • Fails with invalid for a scope, a prefix, an after, or a limit that isn't one, and denied for a player who isn't your game's.

Codes​

Every call that fails rejects with an ArcadibleError: act on its code, a string such as "conflict", and on its retry for a code you don't handle. isArcadibleError(err, code) says whether what you caught is one, with that code.

CodeMeansretryWhat to do
invalidA scope, a key, a value, an item, or an option that isn't one; a call made outside a functionnoPass what the call takes
too_manyMore than 32 items in a callnoMake more than one call
unauthorizedA call made over a minute after its request camenoCall while the request is answered
deniedArcadible doesn't allow it: writing or removing the developer's values, or a player who isn't your game'snoWrite to a scope a function writes
conflictA value was written since the revision the call named. Nothing was written, and conflicts names the itemslaterRead the value again, then write
too_largeA value past 64 KB, a write's values together past 256 KB, or a read's past 1 MBnoKeep less in one value, or in one call
fullThe scope's storage is used uplaterRemove values first
busyToo many calls to Arcadible in a minuteyesSlow down, and try again
unavailableArcadible couldn't be reached, or its answer couldn't be readyesTry again

A call waits up to 15 seconds for Arcadible, then fails with unavailable. New codes may be added, each with its retry. The Function SDK's other calls are in its reference.

Limits​

For each game and channel:

LimitValueWhen you reach itWhat to do
A key1 to 128 letters, digits, -, _, ., or /The call fails as invalidRename it
A value64 KB, as JSONThe write fails as too_largeSplit it across keys
Items in a call32The call fails as too_manyMake more than one call
A write's values together256 KBThe write fails as too_largeWrite fewer at once
A read's values together1 MBThe read fails as too_largeRead fewer at once
Keys in a list100 a page, 50 unless you askA limit past it is invalidGo on from next
The developer's, the game's, and the server's10,000 keys and 64 MB, each scopeThe write fails as fullRemove values first
A player's256 keys and 1 MB, each playerThe write fails as fullRemove values first
Calls to Arcadible600 a minute, for a game on each channel, its function and its keys togetherThe call fails as busySlow down, and try again

A call is counted once, however many items it names, and the Function SDK's other calls count toward the same 600. Every limit is also in Limits.

Examples​

A move in a match, checked by your game's own rules, and written only if no one moved meanwhile:

import { players, values, isArcadibleError } from "@arcadible/function-sdk";

export default {
async fetch(request: Request): Promise<Response> {
const me = players.primary(request);
if (me === null) return Response.json({ code: "guest" }, { status: 403 });
const { id, move } = await request.json();
const [match, seats] = await values.read([
{ scope: "game", key: `match/${id}` },
{ scope: "server", key: `seats/${id}` },
]);
if (match === null || seats === null) return Response.json({ code: "no_match" }, { status: 404 });
const next = play(match.value, seats.value, me, move); // your rules: throws on a move that isn't allowed
try {
await values.write([{ scope: "game", key: `match/${id}`, value: next, revision: match.revision }]);
} catch (err) {
if (!isArcadibleError(err, "conflict")) throw err;
return Response.json({ code: "moved" }, { status: 409 });
}
return Response.json(next);
},
};

Removing a match's records once it's over, across scopes, in one call:

await values.remove([
{ scope: "game", key: "match/4821" },
{ scope: "server", key: "seats/4821" },
]);

Clearing matches no one has played for a day, a page at a time, leaving any that moved since it was listed:

const { items } = await values.list("game", { prefix: "match/", limit: 32 });
const idle = items.filter((entry) => Date.parse(entry.updatedAt) < Date.now() - 24 * 60 * 60 * 1000);
await values.remove(
idle.map((entry) => ({ scope: "game" as const, key: entry.key, revision: entry.revision })),
{ onConflict: "skip" },
);

Under arc serve​

arc serve runs your function beside your game, and keeps the game's values itself, as channel local, so the game, your function, and a server of your own beside it reach the same ones, and nothing reaches Arcadible.

  • Nothing to set up, as on Arcadible (Under arc serve).
  • The developer's values are files in your project, in .arcadible-data/values/, one a value, as JSON, read as they change: .arcadible-data/values/daily/2026-11-12.json is daily/2026-11-12.
  • The rest are kept in .arc/values/local.json, so a match survives a restart. Delete it to start over.
  • The limits on what a value and a scope hold apply there too; the limits on how often you call don't.