Patrones: mini-base de datos por entidad, colas y batching

Ya tienes las tres piezas: un almacén transaccional, una base de datos SQLite dentro del objeto y alarmas que lo despiertan solo. Por separado son capacidades; juntas dan lugar a un puñado de patrones que, una vez los ves, reorganizan tu forma de diseñar backend en el edge. Tres destacan sobre los demás: el objeto como base de datos por entidad, la cola durable gobernada por alarmas, y el batching de escrituras hacia un almacén externo. No son trucos sueltos; son las formas naturales que toma el estado cuando cómputo, memoria y tiempo comparten dueño.

Un objeto como base de datos por entidad

El patrón fundacional es tratar cada objeto como la base de datos de una sola entidad. En lugar de una tabla salas gigante con millones de filas en una base central, tienes un objeto Sala por sala, y cada uno lleva su propio SQLite con solo sus mensajes. La identidad hace de clave: derivas el objeto del identificador de la entidad con idFromName, y la plataforma se encarga de que siempre caigas en la misma instancia.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const salaId = new URL(request.url).searchParams.get("sala") ?? "general";
    // el nombre de la entidad se convierte en la identidad del objeto
    const id = env.SALA.idFromName(salaId);
    const sala = env.SALA.get(id);
    return sala.fetch(request);
  },
} satisfies ExportedHandler<Env>;

Cada sala queda así aislada, consistente y coubicada con su propio estado. El dominio se reparte en millones de bases diminutas que no se coordinan entre sí, y la escala se consigue teniendo más objetos, no un objeto más grande. Es la traducción directa del principio del nivel: un único dueño por cada porción de estado.

La elección de idFromName frente a newUniqueId no es un detalle menor. idFromName es determinista: el mismo nombre de entidad —el identificador de la sala, el correo del usuario— produce siempre el mismo objeto, sin que tengas que guardar en ninguna parte la correspondencia entre entidad y objeto. Esa función pura de nombre a identidad es lo que convierte al esquema de nombres de tu dominio en el índice de tu enjambre de objetos, y lo que hace que enrutar a la entidad correcta sea tan barato como calcular un identificador.

Colas durables con alarmas

El segundo patrón nace de casar el almacén con las alarmas. Un objeto puede aceptar trabajo, guardarlo en su almacén como una cola ordenada por clave, y programar una alarma para drenarlo más tarde. Entre encolar y procesar el objeto puede dormirse: la cola es durable y la alarma lo despertará. Es un planificador de trabajo por entidad, sin cola externa ni proceso vigilante.

export class ColaTareas {
  constructor(private state: DurableObjectState, private env: Env) {}

  async encolar(tarea: Tarea): Promise<void> {
    const clave = `t:${Date.now()}:${crypto.randomUUID()}`;
    await this.state.storage.put(clave, tarea);
    // si no hay alarma pendiente, programa el drenaje
    if ((await this.state.storage.getAlarm()) === null) {
      await this.state.storage.setAlarm(Date.now() + 1_000);
    }
  }

  async alarm(): Promise<void> {
    const lote = await this.state.storage.list<Tarea>({ prefix: "t:", limit: 50 });
    for (const [clave, tarea] of lote) {
      await procesar(tarea);
      await this.state.storage.delete(clave);
    }
    // si queda trabajo, vuelve a citarse
    if ((await this.state.storage.list({ prefix: "t:", limit: 1 })).size > 0) {
      await this.state.storage.setAlarm(Date.now() + 1_000);
    }
  }
}

flowchart TB
E[eventos que llegan] --> BUF[buffer en el almacen del objeto]
BUF -.alarma cada segundo.-> DR[alarm drena un lote]
DR --> OUT[procesa y borra las claves hechas]
DR -.queda trabajo.-> BUF
style DR fill:#a6e3a1,color:#11111b

Batching de escrituras

El tercer patrón resuelve un problema de coste y de límites. Imagina miles de eventos por segundo —clics, métricas, latidos— que quieres registrar en un destino externo caro o con cupo, como D1 o una API. Escribir uno por uno es lento y se estrella contra los límites. La solución es interponer un objeto: los eventos entran en su almacén rápido y local, y una alarma vuelca todo lo acumulado en un solo lote cada pocos segundos. El objeto absorbe la ráfaga y la convierte en un goteo ordenado.

Los tres, en un solo objeto

Los patrones no viven separados: se componen. Un mismo objeto por entidad puede ser a la vez su base de datos, su cola y su amortiguador. Mira un agregador de métricas por proyecto: cada evento se inserta en el SQLite local, una alarma se asegura de volcar el lote a un destino externo cada pocos segundos, y todo ocurre dentro de un único dueño que nadie más toca.

export class MetricasProyecto {
  constructor(private state: DurableObjectState, private env: Env) {
    this.state.storage.sql.exec(
      "CREATE TABLE IF NOT EXISTS buffer (evento TEXT, ts INTEGER)",
    );
  }

  async registrar(evento: string): Promise<void> {
    this.state.storage.sql.exec("INSERT INTO buffer VALUES (?, ?)", evento, Date.now());
    // programa el volcado solo si no hay uno ya pendiente
    if ((await this.state.storage.getAlarm()) === null) {
      await this.state.storage.setAlarm(Date.now() + 10_000);
    }
  }

  async alarm(): Promise<void> {
    const filas = this.state.storage.sql.exec("SELECT evento, ts FROM buffer").toArray();
    if (filas.length === 0) return;
    await this.env.DESTINO.enviarLote(filas);   // un solo viaje externo por lote
    this.state.storage.sql.exec("DELETE FROM buffer");
  }
}

Un solo objeto de treinta líneas reúne el almacenamiento estructurado, la cola durable y el batching temporizado —tres piezas que, cableadas con servicios sueltos, habrían sido un pequeño sistema distribuido con sus propios modos de fallo—. Y es correcto por construcción, porque un único hilo gobierna a la vez el buffer, la alarma y el volcado, sin carreras entre el evento que entra y el lote que sale.