values
The game's data kept on Arcadible, as a server of your own reaches it: JSON under a key, in a scope, for one game and one channel. The package is @arcadible/server-sdk, and a call is allowed by one of your game's keys.
import { values } from "@arcadible/server-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
| Member | Description |
|---|---|
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 server's calls are allowed by one of your game's keys, which names the game and the channel: the values a call reaches are that game's, on that channel.
- The key is
ARCADIBLE_KEY, an environment variable the SDK reads, never an argument (Including it). Without it, every call fails withinvalid, and nothing is sent; with one Arcadible doesn't take,unauthorized. - A key for staging reaches staging's values, and one for production, production's. Each channel has its own values.
- What a key may do is the scopes' (below): read all four, and write all but the developer's.
- Keep the key on your server. Anyone with it reads and writes the game's values as your server does.
Scopes
A scope says whose a value is. A server reads all four, and writes all but the developer's.
| Scope | Whose | Your server | Your game, for its player |
|---|---|---|---|
"developer" | Yours: what you publish for the game | Reads | Reads |
"game" | The game's, shared by every player | Reads and writes | Reads |
"server" | Your servers' own, your game's function included | Reads and writes | Nothing |
| A player | One player's, in this game: any player | Reads and writes | Reads and writes its own |
- Your server and your game's function share them, on the same channel: what one writes, the other reads.
- What the game reads, any player can. Keep what only your server 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 a ticket's player, 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 ticket = await tickets.check(token, { server: "https://example.com", game: "8f36cdfb-adad-4f37-b543-63cf1b401455", channel: "production" });
if (ticket.player === null || ticket.player.guest) return new Response("Log in to play", { status: 403 });
await values.write([{ scope: ticket.player, 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, whichlist'sprefixmakes 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.stringifymakes of it, soNaNis kept asnull, and a property that'sundefinedis left out. Only what it can't make text of at all,undefineditself, a function, or a cycle, fails withinvalid. - A
revisionis a number that changes each time a value is written, and is never0for 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
conflictsis a list of{ scope, key }, one for each item whoserevisionwasn't the value's, in the call's order, with thescopeas you gave it. An item with norevisionis never in it. revision: 0writes only if there's no value yet, so two servers can't both create one.- Without a revision, the last write wins.
- A write that fails with
unavailablemay have been kept: Arcadible may have written it before the answer was lost. Trying again with the samerevisionthen fails withconflict, since the value moved on to your own write. So afterunavailable, 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
scopeas it was given, ornullfor a key with none. sinceon 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 | nullwhen no item can namesince, andValue | Unchanged | nullwhen one can: a read with nosinceneeds no check forunchanged. That's whatUnchangedForsays, of the items' type. - An empty list resolves with
[], and asks nothing. - Fails with
invalidfor an item that isn't one, a key or a scope that isn't one, or a key named twice in a scope;too_manyfor more than 32 items;too_largewhen the values together are past 1 MB;deniedfor 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;0means only if there's no value. Otherwise the whole call fails withconflict, itsconflictsnaming the items, and nothing is written (Revisions andconflict). - 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
invalidandtoo_manyasreaddoes, and for a value that isn't JSON;deniedfor the developer's scope, or a player who isn't your game's;too_largefor a value past 64 KB, or the call's values together past 256 KB;fullwhen a scope's storage is used up. - A write that fails with
unavailablemay 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 arevisionreads first: if the first try landed, the revision moved on, and a retry is refused withconflict(Revisions andconflict).
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" }]);
| Option | Value | Default |
|---|---|---|
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 withconflict, itsconflictsnaming the items, and nothing is removed. - With
{ onConflict: "skip" }, each item is on its own: one whoserevisionisn't the value's any more is left as it is, the rest are removed, and the call resolves, never failing withconflict. 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, anddeniedaswritedoes. - A remove that fails with
unavailablemay 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 arevisionreads first: if the first try landed, the revision moved on, and a retry is refused withconflict.
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/" });
| Option | Value | Default |
|---|---|---|
prefix | Only the keys that start with it | Every key |
after | Where to go on from: the last page's next, as it came | The first key |
limit | How many keys, 1 to 100 | 50 |
- No options, or
null, is every key, 50 at a time. - Resolves with a page,
{ items, next }: each item is{ key, revision, updatedAt, size }, withsizethe value's, in bytes, ornullwhere Arcadible doesn't say;nextgoes back asafterfor the following page, as it came, and isnullat the end. - It isn't a snapshot: a value written between pages may show, or not.
- Fails with
invalidfor a scope, aprefix, anafter, or alimitthat isn't one, anddeniedfor 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.
| Code | Means | retry | What to do |
|---|---|---|---|
invalid | No key; a scope, a key, a value, an item, or an option that isn't one | no | Set ARCADIBLE_KEY; pass what it takes |
unauthorized | A key Arcadible doesn't take: revoked, or not one | no | Set ARCADIBLE_KEY to a key of the game's |
too_many | More than 32 items in a call | no | Make more than one call |
denied | Arcadible doesn't allow it: writing or removing the developer's values, or a player who isn't your game's | no | Write to a scope a server writes |
conflict | A value was written since the revision the call named. Nothing was written, and conflicts names the items | later | Read the value again, then write |
too_large | A value past 64 KB, a write's values together past 256 KB, or a read's past 1 MB | no | Keep less in one value, or in one call |
full | The scope's storage is used up | later | Remove values first |
busy | Too many calls for the game in a minute | yes | Slow down, and try again |
unavailable | Arcadible couldn't be reached, or its answer couldn't be read | yes | Try again |
A call waits up to 15 seconds for Arcadible, then fails with unavailable. New codes may be added, each with its retry. The Server SDK's other calls are in its reference.
Limits
For each game and channel:
| Limit | Value | When you reach it | What to do |
|---|---|---|---|
| A key | 1 to 128 letters, digits, -, _, ., or / | The call fails as invalid | Rename it |
| A value | 64 KB, as JSON | The write fails as too_large | Split it across keys |
| Items in a call | 32 | The call fails as too_many | Make more than one call |
| A write's values together | 256 KB | The write fails as too_large | Write fewer at once |
| A read's values together | 1 MB | The read fails as too_large | Read fewer at once |
| Keys in a list | 100 a page, 50 unless you ask | A limit past it is invalid | Go on from next |
| The developer's, the game's, and the server's | 10,000 keys and 64 MB, each scope | The write fails as full | Remove values first |
| A player's | 256 keys and 1 MB, each player | The write fails as full | Remove values first |
| Calls to Arcadible | 600 a minute, for a game on each channel, its keys and its function together | The call fails as busy | Slow down, and try again |
A call is counted once, however many items it names, and the Server SDK's other calls count toward the same 600. Every limit is also in Limits.
Examples
A board's top entries, which every player reads and only your server writes:
import { values, isArcadibleError } from "@arcadible/server-sdk";
async function submit(player: { id: string }, score: number): Promise<void> {
for (;;) {
const [board] = await values.read([{ scope: "game", key: "board" }]);
const entries = [...((board?.value as Entry[]) ?? []), { id: player.id, score }].sort((a, b) => b.score - a.score).slice(0, 100);
try {
await values.write([{ scope: "game", key: "board", value: entries, revision: board?.revision ?? 0 }]);
return;
} catch (err) {
if (!isArcadibleError(err, "conflict")) throw err;
}
}
}
type Entry = { id: string; score: number };
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 keeps a game's values itself, as channel local, so the game, its function, and your server beside it reach the same ones, and nothing reaches Arcadible.
- Set
ARCADIBLE_SERVEto the addressarc serveprints, andvaluesasks it, with no key (Underarc 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.jsonisdaily/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.