Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

Cache REST responses offline

http.request fetches from an existing API. Revision 18 adds data.cache to keep chosen JSON values in native SQLite for the next offline launch (contracts §5.5.1). This is disposable data. Keep user edits in writable buckets with data.put.

Enable a bucket in the store build:

{
"data": { "days": 1 },
"cache": ["days"],
"http": { "origins": ["https://api.example.com"] }
}

Revision 18 is the package’s reserved minimum, not the number every app should copy. For a new declaration use since >= max(18, shipped store schema version + 1) and raise the app schema version to at least that number. For example, an app whose store baseline is 19 declares since: 20 and version: 20. The starter template uses 18 because it has no previous store baseline.

If data.cache already shipped, preserve its recorded since and shape. If the CLI refuses a change, restore the recorded declaration from .valence/baseline.json (storeSchema.methods["data.cache"]); do not rename it to data.cache.v2 or rebaseline to bypass the refusal. A renamed method does not delegate to the package implementation. The following declaration is for the store-19 example:

"data.cache": {
"since": 20,
"params": { "bucket": "string", "key": "string", "value": "json?" },
"returns": "void"
}

Regenerate and ship the native host. An OTA cannot add the compiled grant. Removing a grant in a store build clears that bucket’s retained overlays before native startup exposes reads; underlying server rows, cursors and pending writes remain intact. Import the app’s generated bridge:

import { call, has } from './bridge.g';
if (has('data.cache')) {
const response = await call('http.request', {
url: 'https://api.example.com/day/2026-11-01',
});
if (response.status === 200) {
await call('data.cache', {
bucket: 'days', key: '2026-11-01', value: JSON.parse(response.body),
});
}
}
const day = await call('data.get', { bucket: 'days', key: '2026-11-01' });

Read SQLite first for an immediate offline paint, then refresh online. Validate the API payload before caching it. Handle transport failures by retaining the previous value. One encoded JSON value may occupy at most 65,536 UTF-8 bytes; larger values fail E_TOO_LARGE without replacing the previous value. The page must prune stale keys using data.cache({bucket, key, value: null}). Null removes the overlay and reveals any server row underneath. There is no literal-null cache value.

That 64 KiB value cap is the only limit there is. No cap on the number of cached rows, no cap on total cached bytes, no TTL, no eviction. A page with a grant can fill the device one value at a time, and the user’s only remedy then is clearing app data — which also destroys their synced rows and anything they have written but not yet pushed.

It is not the only unbounded store — prefs.set has no cap either — but it is the one where the absence matters, and that is why it is easy to miss. prefs holds a handful of settings; the cache exists to accumulate a row per fetched resource, so growing without limit is its normal operating mode rather than a misuse of it. Everything here whose growth is bounded is bounded visibly: a read-only bucket cannot grow on the device without a server row, notify.schedule caps pending reminders at 64 and tells you when it refuses, state.save refuses a blob over 65,536 UTF-8 bytes, and http.request caps the request body, the response body and the headers separately. The store you write to most often, because caching an API is its whole purpose, is the one with no ceiling.

The retention rule has to stay yours: only your page knows which keys are worth keeping. So write it with your first data.cache call rather than after a support ticket. The shape that works is a prune at the end of whatever load filled the cache — keep what the UI can still reach, drop the rest:

// After loading a date, keep only the dates the strip can navigate to.
async function pruneDays(reachable: Set<string>) {
let after: string | undefined;
for (;;) {
const rows = await call('data.list', { bucket: 'days', limit: 500, after });
if (!rows.length) return;
for (const row of rows) {
// usn -2 is a cache overlay; -1 is an unsent user write; anything else came from the server.
if (row.usn === -2 && !reachable.has(row.key)) {
await call('data.cache', { bucket: 'days', key: row.key, value: null });
}
}
after = rows[rows.length - 1].key;
}
}

usn: -2 is also how you measure the overlay. data.count counts the merged view, which is the point of the merged view, so it cannot tell you how much of the bucket is cache. Listing and counting the -2 rows can.

valence doctor reports the grant and this missing ceiling in its REST cache row, naming your granted buckets, so the decision is visible at release time. It passes rather than warns: doctor cannot see whether your page prunes, and a warning no correct app can clear is a warning nobody reads.

A compiled ceiling — a per-bucket maxRows, or one cacheMaxBytes, evicting the oldest write first — is the real fix, so that an app which never prunes degrades into a smaller cache instead of a full disk. It is not in 0.4: the cache table has no written-at column, so “oldest” does not exist yet and adding it is a database migration.

data.list, getMany, get and count combine cached and synced rows with one row per key. Cache wins until a pull or seed import replaces that key, including with a tombstone. Other keys survive. Key pagination and prefix filters span both sources; concurrent writes are not a multi-page snapshot. List/batch rows identify cache values with usn: -2 (local-only). -1 still means an unsent user write. Cache values are page-supplied and must not be treated as authenticated server records by native code. Use the underlying kv table for server provenance, or a bucket without a cache grant.

Caching sends no network request, queues nothing, emits no sync event and changes no sync cursor, outcome or freshness. Await the write and refetch. sync.status describes server sync, not REST freshness. Cache-only data never satisfies the OTA updater’s synced-pair gate. For an API-only app, keep the bucket schema stable; an OTA requiring a new schema still needs the normal sync readiness protocol.

A cache grant does not remove a bucket from sync. With sync.base configured, normal unscoped sync pulls the active manifest’s read-only data pairs, including cache-enabled buckets. A scoped sync may select fewer buckets. Publish the normal sync endpoint even when a bucket will contain only REST overlays. For a new empty days bucket at schema 1, the dynamic endpoint answers HTTP 200:

{ "bucket": "days", "schema": 1, "rows": [], "max": 0, "more": false }

Keep any existing server history and cursor; never replace a nonempty bucket’s endpoint with this example. Static sync needs the equivalent valid empty index under the normal static protocol. A 404 makes the run incomplete (failed), without undoing successful work in other buckets or deleting queued edits; it is not an instruction to skip this bucket. With no sync.base, no pull is attempted. There is no per-bucket cache-only sync exemption in 0.4. The reference adapter in examples/rest-sync-adapter serves only items and returns 404 for other names; add empty overlay buckets there explicitly too.

A new data schema starts with no cached values. Old-schema values remain for rollback until ordinary post-commit garbage collection removes that pair.

A bundle that fails its trial takes every cached value with it. The host drops the whole cache on each of the two strikes, because one strike already puts the last good bundle back on screen. The reason is that a cache key is not versioned by anything a rollback moves: requires.data is the bucket schema, and a release that changes the shape of a REST payload it caches normally leaves that alone — so the same bucket, schema and key would hand the reverted bundle the failed one’s shape, through a read that prefers the cached value over the server row. Your server rows, cursors and queued writes are untouched; the cache costs a refetch, which is what makes it disposable. The schema-bump sentence above is the other case: there the old schema’s values are still the right shape for the bundle being reverted to. The failing page cannot refill it on the way out: dropping the cache is one step of a rollback whose other steps are asynchronous, and the failed bundle’s page is still on screen and still able to call the bridge through all of them — so from just before the drop until the document that rollback asked for starts, data.cache fails E_DENIED and says why. Not merely until the next page load: the failed page can navigate itself, and a rollback whose own reload fails leaves the cache closed rather than open — and logs that it could not serve the replacement, naming the trial and the error, because a rollback that stops half way shows the page nothing. A REST response that lands in that window is simply not cached; the page that replaces it fetches again. Recorded account switch/sign-out clears all cached values alongside writable rows, and emits sync.changed for cache-enabled buckets. A refused E_PENDING switch leaves them intact; refresh and first account adoption preserve them. Record account IDs for account data, and discard responses from fetches started under a previous account. Writes during a transition fail E_INTERNAL.

Unknown buckets and dot-segment keys fail E_PARAMS. Writable buckets and buckets without the compiled cache grant fail E_DENIED. Android device acceptance for this addition is recorded separately from unit checks; iOS remains experimental and untested.

Last updated: