Cache
API cache reference
Every c.get("cache") method in VitNode API routes: defineCacheEntry options, entry handles, flush, key format, serialization and behavior without Redis.
c.get("cache") is available in every Hono handler. Plugins read and write it only through typed entries: defineCacheEntry declares one, and entry() reads and writes it. Values are stored as JSON in Redis, or in a small in-memory store when Redis is not configured. For a step-by-step example, see Cache API data.
Methods
| Method | Returns | Behavior |
|---|---|---|
entry(definition, ...keyArgs) | CacheEntryHandle | One entry, with its key built from keyArgs. See Entry handle. |
flush() | Promise<void> | Deletes every entry of the current request's plugin. A no-op when the context has no plugin. See Clear every entry of a plugin. |
c.get("cache") has nothing else: its type is DomainCache (from @vitnode/api/lib/cache), and the object at runtime has only these two methods. In a service, depend on just what you call, for example cache: Pick<EnvVariablesVitNode["cache"], "entry">, and pass c.get("cache"). |
VitNode core keeps its own cache store behind that object: the system store, locks, lease sets and the Redis connection status, which sessions, staff permission sets, presence, the queue worker and the Content Engine's public reads use. It is not reachable from c.get("cache") and is not a plugin API. Its module can be imported through the package's deep paths like any other file, but it may change in any release.
Keys
| What | Stored as |
|---|---|
entry(...) | vitnode:cache-entry:{definition pluginId}:{name}:v{version}:{JSON key parts} |
flush() also removes | vitnode:cache:{pluginId}:*, keys left by the removed string-keyed API |
The plugin in an entry's key is the plugin that defined it, not the one handling the request. Key parts are encoded as a JSON array, so "1" and 1 are different keys.
Definition options
defineCacheEntry from your plugin's @/api/builders (bindApiPlugin(manifest).defineCacheEntry) declares an entry. The unbound version in @vitnode/api/lib/cache-entry also takes pluginId.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | - | Letters, digits, ., _ and -, starting with a letter or digit, up to 100 characters. Unique within the plugin. |
version | number | Yes | - | Whole number, at least 1. Bump it to drop every stored entry. Never derived from the schema. |
schema | z.ZodType | Yes | - | Validates writes and reads. Its input must be JSON; z.date() is a compile error. |
ttlSeconds | number | Yes | - | Whole number, at least 1. Capped at 15 by the in-memory fallback. |
key | (...args) => (string | number | boolean)[] | No | () => [] | Builds the key parts from entry()'s arguments. At most 8 parts: strings up to 256 characters, finite numbers or booleans. |
Entry handle
| Handle method | Returns | Behavior |
|---|---|---|
get() | Promise<Output | undefined> | The schema's output, or undefined on a miss. A stored null, false, 0 or "" is a hit. |
set(value) | Promise<void> | Validates the schema's input and stores its JSON for ttlSeconds. Throws CacheEntryValidationError when invalid. |
remember(loader) | Promise<Output> | Returns the parsed hit, or runs loader, validates, stores and returns the parsed result. Throws like set for an invalid result. |
delete() | Promise<void> | Removes the entry. |
setIfMissing(value) | Promise<Output> | Stores value only when no valid value is stored, atomically (SET NX in Redis), and returns the value that is current afterwards. Without a store, returns value unstored. For first-writer-wins tokens, such as a generation. |
key | string | The storage key, for logs. |
- Reads treat malformed JSON, a value the schema rejects, a different
version, no store and a Redis error as a miss; a rejected value is deleted. - Writes copy the value to JSON first and reject a
Date,Map, class instance,NaN,Infinity,bigint, circular reference, orundefinedor missing (sparse) array item;undefinedobject properties are omitted. What is stored is that JSON (the schema's input), not the schema's output. - Errors:
CacheEntryValidationErrorfor an invalid write;CacheEntryDefinitionErrorfor an invalidname,version,ttlSecondsor key part. Both are exported from@vitnode/api/lib/cache-entry. Redis errors are never thrown.
Without Redis and when Redis fails
When the redis option in vitnode.api.config.ts is not set, the cache lives in the memory of each API process:
- It holds up to 10,000 keys and drops the least recently used one when full.
- Every TTL is capped at 15 seconds, whatever
ttlSecondssays. delete()andflush()only reach the process that runs them. With one instance that is all of them; with several, the others keep their copy until it expires - hence the short cap.- A restart empties it, so the first requests after a deploy all miss.
Run more than one instance? Connect Redis so every instance shares one cache.
When Redis is configured but fails, the error never reaches your route, and VitNode does not fall back to the in-memory store. A failed read counts as a miss, so remember() runs the loader on every request during an outage, and a failed write or delete is skipped. Commands fail immediately while Redis is unreachable instead of waiting in a queue, so an outage does not stall requests. Plan for the database load of a cache that misses everything, and remember that a delete() lost in an outage leaves the old value until its TTL.
Only CacheEntryValidationError and CacheEntryDefinitionError are thrown: they are bugs in your code, not cache failures.