JSONL Store
Usa esta habilidad cuando un trabajo programado necesite recordar lo que ya ha hecho — alertas emitidas, IDs procesados, eventos capturados — pero una base de datos sea excesiva. JSON Lines (un objeto JSON por línea) es amigable para añadiduras, legible por humanos, greppable, y se transmite sin cargar todo el archivo. Este ayudante añade añadiduras atómicas, lecturas en flujo que sobreviven a una línea corrupta y append_unique(record, key) para que el mismo ID nunca se escriba dos veces entre ejecuciones.
Cuándo invocarlo
- El usuario dice: "registrar resultados en un archivo JSONL", "añadir eventos al disco", "deduplicar por ID entre ejecuciones", "mantener un historial simple sin base de datos".
- Un script cron o programado necesita estado duradero entre ejecuciones en un archivo plano.
Cuándo NO invocarlo
- Necesitas consultas, índices o escritores concurrentes — usa SQLite (
sqlite-state) o una base de datos real. - Los registros son enormes o binarios — JSONL es para filas estructuradas pequeñas.
Ejemplo concreto
Entrada del usuario:
Después de cada ejecución, añade nuevas alertas a alerts.jsonl pero nunca el mismo ID de alerta dos veces.
Salida:
# Copia assets/store.py a tu proyecto, luego:
from store import JsonlStore
store = JsonlStore("data/alerts.jsonl")
for alert in new_alerts:
if store.append_unique(alert, key="id"):
send(alert) # solo se dispara para IDs no vistos en ninguna ejecución anterior
print("tamaño del historial:", store.count())
Las lecturas se transmiten línea por línea, por lo que un año de historial nunca se carga completamente en memoria, y una línea final a medio escribir de un fallo se omite sin romper la siguiente ejecución.
Patrón a aplicar
- Un objeto JSON por línea; añade con
ensure_ascii=Falsepara que el texto se mantenga legible. - Lecturas en flujo con un generador; omite líneas en blanco o corruptas en lugar de lanzar una excepción.
- Deduplica con
seen_keys(key)/append_unique(record, key)para hacer las ejecuciones idempotentes. - Combínalo con un programador para que el archivo sea la memoria duradera entre invocaciones.
Referencia: assets/store.py.
Fuente
Destilado del manejo de estado de bots programados del autor. v1.0.0. Ver también: [[sqlite-state]], [[cron-dispatch]], [[pipeline-orchestrator]].
→ Construye el bot completo y ejecutable con Trawlkit.