Cache

Le cache sert aux valeurs que vous pouvez vous permettre de perdre et de recalculer : un calcul coûteux, une réponse d'API tierce. Chaque valeur a une durée de vie (TTL) et expire ensuite. Pour les données qui doivent durer, utilisez le KV store.

API

Le framework fournit createCache, importé depuis @bext-stack/framework/kv. Il fonctionne sur tout store qui implémente CacheStore (get, set, delete). Le store kvStore enregistre les valeurs dans le KV de votre application :

import { createCache, kvStore } from "@bext-stack/framework/kv";

// Shared across requests, scoped to your app, stored in KV with its TTL
const cache = createCache({ store: kvStore({ appId: "<app-id>" }), prefix: "rates" });

const rates = await cache.remember("eur", 300, () => fetchRates("EUR")); // TTL in seconds
await cache.put("flag", true, 60);
await cache.get<boolean>("flag"); // true | null
await cache.forget("flag");

Les valeurs sont encodées en JSON : vous mettez en cache des objets typés, pas seulement des chaînes. Elles doivent donc être sérialisables en JSON (une Date revient sous forme de chaîne).

Méthode	Description
`get<T>(key)`	Lire une valeur, ou `null` si elle est absente ou expirée.
`put(key, value, ttlSecs?)`	Écrire une valeur. Sans TTL (ou avec `0`), elle n'expire pas.
`remember(key, ttlSecs, factory)`	Lire la valeur, ou la calculer avec `factory`, la stocker et la retourner.
`has(key)`	Indiquer si une valeur est présente.
`forget(key)`	Supprimer une valeur.
`pull<T>(key)`	Lire puis supprimer une valeur.
`add(key, value, ttlSecs?)`	Écrire seulement si la clé est absente ; retourne `true` si la valeur a été écrite.

Choisir le store

Store	Portée
`kvStore({ appId })`	Partagé entre les requêtes, limité à votre application, stocké dans le KV avec son TTL.
`memoryStore()`	En mémoire, propre à l'instance qui exécute le code. Adapté à un cache de courte durée et aux tests.

Vous pouvez aussi fournir votre propre store : un objet avec get(key), set(key, value, ttlSecs?) et delete(key), synchrones ou asynchrones. get doit renvoyer exactement la chaîne reçue par set, ou null.

L'option prefix préfixe toutes les clés (rates:eur), ce qui évite les collisions avec vos autres clés KV. remember ne considère que null comme absent : false, 0 et "" sont mis en cache comme toute autre valeur. En revanche, une factory qui renvoie null est rappelée à chaque lecture.

Mettre un loader en cache

Pour mettre en cache le résultat d'un loader de page, enveloppez-le dans cachedLoader. Le cache est partagé par tous les workers de rendu et indexé par hôte, route, paramètres de route et chaîne de requête. Les cookies et les en-têtes n'en font pas partie : n'enveloppez donc que des loaders dont le résultat ne dépend pas du visiteur.

import { cachedLoader } from "@bext-stack/framework";

export const loader = cachedLoader(
  { ttl: 60, tags: ["projects"] }, // ttl in seconds, 60 when omitted
  async ({ params }) => ({ project: await getProject(params!.slug) }),
);

Option	Description
`ttl`	Durée de vie en secondes. Absente ou `0` : 60 secondes.
`tags`	Tags utilisés pour invalider les entrées avec `revalidateTag`.
`vary`	Fonction `(args) => string` qui ajoute des éléments à la clé, par exemple une langue.

Seules les requêtes GET passent par le cache. Un résultat null, undefined ou une Response n'est pas mis en cache, et le résultat est stocké en JSON.

revalidateTag("projects"), importé depuis @bext-stack/framework/cache, supprime les entrées qui portent ce tag et retourne le nombre d'entrées supprimées.

import { revalidateTag } from "@bext-stack/framework/cache";

revalidateTag("projects");

Cache ou KV

	Cache (`createCache`)	KV (`sdk.kv`)
Usage	Valeurs recalculables	Données durables
Durée de vie	Courte, expire après le TTL	Conservée jusqu'à suppression (TTL optionnel)
Motif typique	`remember(key, ttl, factory)`	`get` / `set` / `delete` / `list`

Utilisez le cache pour mémoïser un calcul coûteux ou une réponse que vous pouvez récupérer à nouveau. Utilisez KV quand la donnée doit survivre : état lié à une session, enregistrements de job, tout ce que vous ne pouvez pas recalculer.

Et ensuite

Page	Ce qu'elle couvre
KV Store	Le store de chaînes durable
Présentation du SDK	Le client `createSdk`