Intégration Hono

Le package @bext/hono fournit un middleware Hono qui injecte les services bext dans votre contexte de requête, ainsi qu'un client autonome à utiliser en dehors des gestionnaires de requêtes.

Installation#

bash

npm install @bext/hono
# or
bun add @bext/hono

Dépendances homologues : hono >= 4.0.0

Intergiciel#

Ajoutez le middleware pour injecter c.var.bext dans tous les gestionnaires :

typescript

import { Hono } from "hono";
import { bextMiddleware, type BextEnv } from "@bext/hono";

const app = new Hono<BextEnv>();

// Add bext services to all routes
app.use(bextMiddleware());

app.post("/api/products", async (c) => {
  const product = await createProduct(c.req.json());

  // Invalidate cached product pages
  await c.var.bext.cache.invalidateTag("products");

  // Notify connected clients
  await c.var.bext.realtime.publish("products", { action: "created", product });

  return c.json(product, 201);
});

export default app;

Configuration personnalisée#

typescript

app.use(bextMiddleware({
  baseUrl: "http://127.0.0.1:3061",  // SDK sidecar URL
  appId: "my-app",                    // App identifier for multi-app isolation
}));

Client autonome#

Pour une utilisation en dehors des gestionnaires de requêtes (scripts, Workers, etc.) :

typescript

import { createBextClient } from "@bext/hono";

const bext = createBextClient();

// Same API as c.var.bext
await bext.cache.invalidateTag("products");
await bext.realtime.publish("updates", { type: "deploy" });
await bext.kv.set("config:feature-flags", { darkMode: true });

Référence API#

Clientbext#

typescript

interface BextClient {
  cache: BextCache;
  realtime: BextRealtime;
  kv: BextKv;
  queue: BextQueue;
  tasks: BextTasks;
}

Cache#

typescript

interface BextCache {
  invalidateTag(tag: string): Promise<void>;
  invalidatePath(path: string): Promise<void>;
}

En temps réel#

typescript

interface BextRealtime {
  publish(topic: string, data: unknown): Promise<void>;
}

Magasin KV#

typescript

interface BextKv {
  get<T = unknown>(key: string): Promise<T | null>;
  set(key: string, value: unknown, opts?: { ttl?: number }): Promise<void>;
  delete(key: string): Promise<void>;
}

Files d'attente#

typescript

interface BextQueue {
  push(name: string, payload: unknown, opts?: { delay?: number }): Promise<void>;
  pull<T = unknown>(name: string): Promise<QueueMessage<T> | null>;
  ack(name: string, id: string): Promise<void>;
}

interface QueueMessage<T = unknown> {
  id: string;
  data: T;
  attempts: number;
}

Tâches#

typescript

interface BextTasks {
  register(name: string, definition: { cron: string; command: string }): Promise<void>;
  list(): Promise<TaskInfo[]>;
  cancel(name: string): Promise<void>;
}

interface TaskInfo {
  name: string;
  cron: string;
  command: string;
  registeredAt: number;
  lastRun: number | null;
}

Exemple : CRUD complet avec mise en cache#

typescript

import { Hono } from "hono";
import { bextMiddleware, type BextEnv } from "@bext/hono";

const app = new Hono<BextEnv>();
app.use(bextMiddleware());

// List products (ISR-cached by bext, invalidated on mutation)
app.get("/api/products", async (c) => {
  const products = await db.products.findMany();
  return c.json(products);
});

// Create product — invalidate cache + push event
app.post("/api/products", async (c) => {
  const data = await c.req.json();
  const product = await db.products.create(data);

  await c.var.bext.cache.invalidateTag("products");
  await c.var.bext.realtime.publish("products", { action: "created", id: product.id });

  return c.json(product, 201);
});

// Delete product — invalidate + event + queue cleanup job
app.delete("/api/products/:id", async (c) => {
  const id = c.req.param("id");
  await db.products.delete(id);

  await c.var.bext.cache.invalidateTag("products");
  await c.var.bext.cache.invalidatePath(`/products/${id}`);
  await c.var.bext.realtime.publish("products", { action: "deleted", id });
  await c.var.bext.queue.push("cleanup", { type: "product-assets", productId: id });

  return c.json({ deleted: true });
});

export default app;

Conseil

c.var.bext est disponible uniquement dans les routes exécutées après bextMiddleware(). Pour les scripts ou les tâches en arrière-plan hors du contexte d’une requête, utilisez plutôt createBextClient().

En rapport#

Présentation des frameworks — règles de détection automatique et choix entre Hono et PRISM
Intégration Express — les mêmes services via le middleware req.bext
Mise en cache — interactions de invalidateTag / invalidatePath avec le cache en périphérie de bext
Des flux durables — orchestration de tâches en plusieurs étapes via la file
Tâches planifiées — enregistrement de tâches cron depuis des gestionnaires Hono

Links#

hono.dev — Documentation du cadre Hono