DEV Community: Armando

Sharing a Whiteboard at 120 kbps with an Unstable Connection

Armando — Mon, 14 Sep 2026 23:57:34 +0000

TL;DR: I set out to compress a shared whiteboard for a connection that's slow (~120 kbps practical) and drops without warning. The real problem wasn't compression. It was that I was sending information the other client already had. A byte ledger I built before adding audio is now producing numbers: shared audio sits around 40 kbps, leaving about 80 kbps for the whiteboard. The project turned into a lab (LOW-NET) around a bigger question: how little information does a shared experience need? Below: the progression, what's built, what's explicitly not measured yet, and the open questions.

Quick honesty note up front: this is the experiment I'm building, not a finished benchmark. Where numbers don't exist yet, I say so.

The constraint that started it

I work from Cuba. The practical working connection is around 120 kbps and it disappears and reappears at random: batch service, shared capacity, anything but a stable channel.

During an online English class, audio worked and live drawing didn't. A teacher can't show you how to write a phrase on a frozen screen.

That's the design environment. I design against an environment where roughly 120 kbps is a realistic working constraint and connectivity can be intermittent. The target comes from the environment itself, not from capping a link to generate a number.

Wrong model #1: compress the full state

First instinct, and a clean failure:

// "aaaaaaabbbb" -> [7, 'a', 4, 'b']
function rle(seq) {
  const out = [];
  let i = 0;
  while (i < seq.length) {
    let j = i;
    while (j < seq.length && seq[j] === seq[i]) j++;
    out.push(j - i, seq[i]);
    i = j;
  }
  return out;
}

A black-and-white canvas is a grid of bits; run-length encoding eats the repetitions; done. Correct mechanics, wrong abstraction. Two people drawing don't need the drawing. They need what changed.

The pivot: represent changes, not states

The structural change:

{ type: 'add',    shape }        // a stroke is born
{ type: 'update', id, next }     // a point moves
{ type: 'remove', id }           // a stroke is erased

Each client already holds the canvas; you send operations against it, not snapshots.
This is the "do the work once, on the side that owns the state" move, and for a whiteboard it's the difference between the operation graph and the framebuffer.
Old idea I re-derived the hard way: VNC (RFC 6143) refreshes only dirty screen regions. Same principle, different unit.

Serialization: binary + gzip, opportunistically

For the message layer I've been working with a custom binary encoding, gzip-compressed when it pays off (ArrayBuffer as the wire unit instead of a huge JSON). Two honest caveats:

Compression has a fixed cost. Below some payload size, a compressor can inflate your data stack (headers, nothing to exploit). On a ~120 kbps channel that threshold matters, and it needs measuring, not guessing.
"Binary + gzip wins over JSON" is still a working assumption here. The ledger I have measures whole-channel traffic, not per-representation comparisons, so I can't claim a crossover yet.

If you've got real thresholds for tiny payloads, I want them (see the end).

The byte ledger, and the first real number

Budget only means something if you can see it. Before adding audio I built a small system that registers the data being consumed and sent and lets me view it, so I could actually know whether I was inside the budget. 📊

Then I added shared audio, and it works. With a few participants, the audio channel registers around 40 kbps, leaving about 80 kbps for the whiteboard:

120 kbps  total budget
-40 kbps  shared audio
 80 kbps  whiteboard (and everything that comes after)

That is the first number with a name. It came from the ledger, not from a guess.

Audio, or: the part of the problem compression doesn't touch

Voice is what made the class human. The context worth knowing: codec design has been doing the hard version of this for decades. Opus is built for VoIP over constrained links. Its specification (RFC 6716) lands in the order of 6 to 510 kbps, and it ships with two ideas I keep coming back to:

Discontinuous Transmission (DTX): stop transmitting while nobody speaks (opus-codec.org).
In-band FEC: spend extra bits protecting against loss when the channel is lossy.

Both are "decide what not to send," which is the actual game. Compression is one corner of it.

Video, or: the delta of a face is enormous

Pixels are expensive. Video changes constantly even when nothing meaningful changes, and frames repeat whether the eye notices or not. Send only deltas applies, but a face generates huge deltas: lips, eyes, expression, every frame.

The uncomfortable question: what part of the video is information the other person needs?

Two tracks I'm exploring in parallel:

Very low-resolution video: still pixel-based, still costly. For ideas I'm borrowing from ThePrimeagen's ASCII art, particle systems and ASCII Doom videos, and I'm even toying with something shader-like that would carry information through those ASCII algorithms. 🕹️
Avatar / semantic representation: transmit body state instead of pixels:

{ head: { x, y, z, rot }, hands: [...], posture: 'seated' }

Same whiteboard intuition: find the minimum the other side needs, send that. The avatar currently works, although sending only the minimum makes it hard to carry the gestures of a human face in a congruent way. I don't yet know where it stops feeling human. That's a measurement on the list.

The assumption I had to unlearn: continuity

The bigger lesson wasn't bandwidth. A channel that does this:

available → degraded → unavailable → available → burst → unavailable → ...

behaves nothing like "120 kbps sustained." When there's no channel, compression does nothing. The question becomes what to do while you're disconnected: retain, prioritize, batch, and push when it returns.

My hypothesis is that this is a shared-capacity problem rather than a speed one: an antenna serving many devices in batches. I haven't verified it, and I offer it as what it is, an informal observation my model happens to fit, not a measurement. ⚠️

Related work I found: DTN

Researching "designing for a channel that can be absent" led me to Delay/Disruption Tolerant Networking. NASA's definition: an architecture for networks with disruptions, delays, and data-rate mismatches. Core mechanism: store-and-forward, hold the message, keep trying until there's a path.

This isn't something I invented: RFC 4838 (architecture) and RFC 9171 (Bundle Protocol v7) are public, and the field has decades of documented work.

Framing matters: my problem is not deep space 😅. LOW-NET is a handful of participants and a shared board, with delays of seconds rather than minutes. Implementing full Bundle Protocol v7 here would be over-engineering. The move was ingesting the ideas: no continuity as a first-class condition, not the protocol.

What I explicitly do NOT have yet

The numbers that would make this a benchmark post do not exist:

no measured savings for full-state vs deltas;
no measured binary-vs-JSON comparison on this codebase;
no measured video/avatar quality-vs-bitrate curve;
no reconnect/reconcile timing;
no compression-threshold measurements on real payloads.

What I do have so far: the ledger itself, and the ~40 kbps audio figure it produced.

The measurement plan (in order)

Byte ledger: built. Already produced the ~40 kbps audio figure.
Full state vs delta: at what point re-sending everything beats chained deltas.
Binary vs JSON: real sizes and parse times on actual payloads.
Batching: grouping changes into bursts for the degraded channel.
Reconnect: resume without duplicated work or data floods.
Minimal store-and-forward: a local queue that holds and delivers when the channel returns.
Audio: minimum tolerable quality tier. (Opus range above is the starting point.)
Avatar vs low-res video: the semantic-vs-pixel trade-off.
Prioritization: given a byte budget, what goes first.

Demo (draw in a room, stroke arrives): https://whiteboard-five-gamma.vercel.app. References: RLE, MDN ArrayBuffer, Opus (RFC 6716), VNC (RFC 6143), DTN (RFC 4838) (RFC 9171), ASCII experiments (ThePrimeagen). The lab is LOW-NET: an experiment in communicating meaning instead of unnecessarily communicating state.

What I'm asking

If you've measured compression thresholds on tiny payloads, built avatar-based presence, or run anything over genuinely broken networks, I want to compare notes. What surprised you? Where did your model break?

Let the Link Carry the Tracking: UTM, One Table, and Knowing When You Actually Need Signatures

Armando — Sat, 12 Sep 2026 01:13:31 +0000

The same offer goes into a Facebook group, a WhatsApp status, a Telegram channel and a classifieds site. The platform won't tell you which one works — but the link you publish can.

Before the code, four things you should never confuse:

which tagged link generated the visit;
which platform the visitor actually came from;
which visit turned into an inquiry;
which inquiry turned into a sale.

UTM answers #1. It never answers #2. Conversations are #3, sales are #4 — see "clicks are not sales" below.

Step 0 — a table that measures something

No UTM is useful without a place to land. A minimal events table is enough; no data warehouse, no customer SDK:

marketing_events (
  created_at,
  path,
  event,
  source,
  medium,
  campaign,
  content
)

source/medium/campaign/content start empty and get filled once you tag links. If storage is your constraint, aggregate by day instead of storing every event.

Storage depends on deployment, not on fashion:

SQLite — right on a small persistent server (one local file, no external service).
PostgreSQL/Supabase — right when that's already your stack (add a table, not a service).
Serverless (Vercel, Lambda) — the local filesystem is ephemeral: per-invocation, recycled, sometimes read-only. A SQLite file there is silent data loss. Put the database outside the function.

Step 1 — tag the link, don't beg the platform

The platform sends the full URL when someone clicks. So before publishing, embed what you need:

https://your-site.com/offer?utm_source=facebook

The label travels with the click. The platform is just transport.

The four parameters you'll actually use:

Param	Role	Example
`utm_source`	origin you want to tell apart	`facebook`
`utm_medium`	channel type	`social`
`utm_campaign`	promotion grouping	`camisas-2026-09`
`utm_content`	specific variant of the piece	`grupo-venta`

Same campaign, three sources:

?utm_source=facebook&utm_medium=social&utm_campaign=camisas-2026-09&utm_content=grupo-venta
?utm_source=whatsapp&utm_medium=messaging&utm_campaign=camisas-2026-09&utm_content=estado
?utm_source=revolico&utm_medium=classified&utm_campaign=camisas-2026-09&utm_content=anuncio-1

Start with only utm_source if you want; the rest is added when a question demands it.

Explicit assumption: you control the destination page (to read the query string) and you generate the links before posting. If a shortener or a third party generates them, you don't own the data anymore.

What UTM does and doesn't prove

Does: tells you which labeled link was used.
Doesn't: tell you the physical platform. Links get copied and forwarded; a "facebook" link clicked from WhatsApp still reads utm_source=facebook. That's inherent to the method, not a bug of your code.

The Referer header is a secondary signal only: browsers default to strict-origin-when-cross-origin (cross-origin sends just the origin), some policies strip it, apps often send none. Don't build primary attribution on it.

Step 2 — one axis per column, then GROUP BY

Giant compound labels are an antipattern:

utm_source=facebook-group-1-shirts-september-blue-post

Keep dimensions separate so each question has its own axis:

SELECT source, COUNT(*)
FROM marketing_events
WHERE campaign = 'camisas-2026-09'
GROUP BY source
ORDER BY 2 DESC;

source → which platform works. campaign → whether the whole campaign worked. Same campaign, many sources, comparable without losing identity.

Step 3 — single source of truth + one adapter per channel

The offer exists once:

id: oferta-2026-09-camisas
precio_cup: 2300

Each channel carries its own tracking + copy:

canales:
  - id: grupo-venta
    source: facebook
    medium: social
    content: grupo-venta
  - id: estado-wa
    source: whatsapp
    medium: messaging
    content: estado
  - id: revolico
    source: revolico
    medium: classified
    content: anuncio-1

URLs are generated from that config, so a price change is one edit and tagging can't be forgotten. Channels differ in text, image, tone and CTA, hence an adapter interface:

def render(oferta, canal):
    adapter = ADAPTERS[canal.id]
    return adapter.render(
        oferta=oferta,
        tracking=tracking_params(canal),
    )

What you published is a separate concern from analytics:

publicaciones (
  oferta,
  canal,
  pieza_hash,
  publicado_at
)

pieza_hash detects content changes so you don't republish the same piece twice — deduplication/idempotency, not security.

Step 4 — clicks are not sales

Channel	Visits	Inquiries	Sales
Facebook	100	10	1
WhatsApp	40	20	8
Classifieds	200	5	0

Classifieds won traffic; WhatsApp won business. Publication → visit auto-measures. Visit → inquiry → sale doesn't: record it (one column, a sheet), start manual, automate only when volume justifies it.

Step 5 — opaque IDs (why, when)

When you need URLs that don't expose campaign internals (shorter, stable, non-editable):

?c=7f3a

7f3a → a row with campaign/channel/content. It doesn't make attribution truer; it changes representation.

Step 6 — signatures (why almost never, and when yes)

HMAC with a shared secret verifies one thing: a value was generated by whoever holds the secret.

Use it when the parameter has consequences: coupons, discounts, affiliate links, attribution that pays someone.

Verbatim non-goals:

it does not prove the platform of origin;
it does not stop someone reusing a legitimate link 300 times (replay of a valid link is still a valid link);
it does not make tracking trustworthy in general — only the parameter it signs.

Decision checklist

Just started → events table + utm_source. Stop there.
Several channels per campaign → add medium/campaign/content, group by axis.
Growing ≥3 places → single source YAML + adapters + generate URLs.
Need to know what to keep publishing → manual conversion column before any dashboard.
URL looks too informative / needs to change scheme without breaking → opaque ID.
Parameter has money attached to it → HMAC. Otherwise don't.

The channel ranking is a GROUP BY. The data is yours. You don't need an enterprise tag manager to answer "which publication should I keep posting?"

Adapted from my original post on TallerWeb.

Authorized Web Audit: When the App Has No Backend, You Audit Its Assumptions

Armando — Sat, 12 Sep 2026 01:06:36 +0000

Field notes from an authorized audit of a small web store. The headline: there was no backend to attack, so the real findings were identifier manipulation (business logic) and clickjacking.

Setup / hypothesis

Small store on Vercel: catalog, product pages, cart, share-cart URLs, contact buttons.
Looked like Next.js. Turned out to be a React + Vite SPA — the initial misread that set the approach.
Mindset: from "how do I protect this?" to "how can I break it?"

Step 1 — Recon (domain only)

robots.txt, sitemap.xml, routes and params, product/cart flows, HTTP headers.
Result: 0 findings. No magic /admin, nothing in the sitemap.

Step 2 — "Where's the server?"

Expected /api/products, /api/cart. They did not exist.

$ curl -s https://TARGET/api/products
→ 404

The app was a SPA with no server and no database.

Implication for the scope: no server-side attack surface → no SQLi, no auth-bypass/authorization against an API, no server-side HTML injection. When you can't attack an API, you attack the assumptions of the app.

Step 3 — ID manipulation

Walk identifiers through real flows: /producto/1 → 2 → 3 …

Finding 1: products shown as sold out became reachable by changing the ID within certain flows.

Classification note (do this in your own reports): this is NOT classic IDOR. IDOR means a server protects a resource; there is no server here. The precise label is identifier manipulation + insufficient business-logic validation. Classifying correctly is security work.

Step 4 — Share-cart tampering

Share-cart URLs could be modified to introduce sold-out products. The logic accepted states the owner never intended (a stock state the business had ruled out).

Step 5 — Headers

$ curl -I https://TARGET
X-Frame-Options: (absent)
Content-Security-Policy: frame-ancestors (absent)

The app could be framed.

Step 6 — Clickjacking + combined PoC

<iframe src="https://TARGET"></iframe>

It loaded. The store was embeddable.

Combined PoC: external page loading a tampered cart URL in an iframe + own visual elements on top.

Scoped results

Not obtained: passwords, RCE, server access, DB, control of the app.

Demonstrated: state manipulation, manipulable cart, embeddable app, and the combination. Business angle: a third-party page rendering the legit store inside it → price/availability confusion, loss of trust, visual impersonation, complaints hitting an innocent owner.

The patch

X-Frame-Options: DENY        # or CSP frame-ancestors 'none'
# business logic: stop trusting client data; validate availability on every flow

Retest

Retried the attack after the fix → iframe no longer loads. Prefer "I tried again and it no longer works" over "I think it's fixed."

Lessons

Architecture = attack surface. React + Vite ≠ frontend + API + backend + DB, even if the customer sees the same shop.
Scanners miss business logic. No tool asks "should I be able to add a sold-out product to the cart?"
Attacks start with small questions. Change the ID. Change the URL. Frame the page. Then combine.

AI was used as a second opinion (stack identification). The decisive question stayed human: "What happens if I use this functionality in a way the developer didn't expect?"

Adapted from my original post on TallerWeb.

Optimizing for a 120 kbps Network That Drops: Do Less, Cache with Boundaries, Survive Offline

Armando — Sat, 12 Sep 2026 00:55:35 +0000

Reality check first: median fixed-connection download in Cuba is 3.48 Mbps vs 104.43 Mbps worldwide (Ookla via DataReportal), and the working condition is closer to 120 kbps, dropping at any moment.

The wrong question is "how do I make my app faster?". The right one:

How much work does my app actually need?

Optimization starts by not doing: not downloading, not computing, not requesting, not rendering, not sending what isn't necessary.

Rule 1 — eliminate before compressing

Data that is never sent beats data that is compressed.

Rule 2 — an API is a resource; return only what's used

Every request costs: DNS, connection, encryption, latency, server work, serialization, parsing, battery, user time. Don't return fields the component doesn't read.

// BAD: unnecessary fields (images, supplier, reviews, metadata)
// GOOD: only what the component uses
{"id": 1, "name": "linen shirt", "price": 2300}

Rule 3 — images: real resized sets, not one giant file

Shipping a 2400×1800 photo for a 300×225 thumbnail transports data you never need. Generate a set — 160/400/800/1600 px — and let the browser pick:

<img
  srcset="img-160.webp 160w, img-400.webp 400w, img-800.webp 800w"
  sizes="(max-width: 600px) 100vw, 400px"
  src="img-400.webp"
  alt="product">

Note: lazy loading ≠ size optimization. loading="lazy" delays when a file downloads; it doesn't make it smaller.

Rule 4 — run less code

Debounce a search box so c, ca, cam, cama fire one request, not four.
Memoize f(x) when recomputation is cheap compared to the network.
Virtualize long lists: 10,000 rows → render the ~20 visible.

Rule 5 — cache explicitly, with boundaries

Pattern: cache hit → return; miss → API → store → return. Benefits: latency, requests, server load, and — decisively — less dependency on the network.

Boundaries: memory is finite, so pick an eviction policy. LRU (Least Recently Used) evicts the least-recently-touched entry. I wrote adev-lru for exactly this. The real decision isn't the library — it's which information deserves to stay available locally.

Rule 6 — a cache can lie; bound the truth

DB says $550, cache says $500 → two versions of reality. Controls: TTL, invalidation, stale-while-revalidate, ETag, versioning, cache-aside.

Offline-first ≠ offline forever. Show cache → consult server → update.

Rule 7 — writing with no network: a local queue

Order created, address edited, product removed, all offline → hold operations in a local queue, sync when the network returns.

The question flips from "how do I make the internet never fail?" to "how does my app survive when it fails?"

Rule 8 — idempotency (the duplicate order)

Server got the POST; the 200 OK was lost; client retries → orders #123 and #124.

POST /orders
Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

Retry with the same key → same order, no duplicate. A network failure is not an operation failure.

Rule 9 — conflicts between devices (a lesson in smaller than you think)

Two offline devices edit the same record: price 500 vs 550. You now own a distributed-system problem. Options, with trade-offs:

optimistic concurrency / versioning — reject on write conflict, require the user to reload;
timestamps + last-write-wins — simple, silently loses the older edit;
eventual consistency — eventually everybody agrees; decide if the data tolerates it.

Pick explicitly; a cache is a place where "the data tolerates it" should be questioned.

Where this belongs

Performance as a later stage (build → publish → measure → optimize) gets you a fast app on a good network and nothing on a bad one. Under hard constraints the decisions live in the architecture: how much is downloaded and stored, and what happens when the connection fails.

TL;DR

Never send what isn't needed.
An API response is a payload, not a promise — return used fields only.
Images: resized sets + srcset/sizes + modern formats; lazy loading doesn't shrink files.
Debounce, memoize, virtualize — run less code.
Cache with a boundary (LRU) and correct-yourself mechanisms (TTL/SWR/ETag).
Offline writes belong in a queue; retries need an Idempotency-Key.
Conflicts are distributed-system problems, even on one laptop.

Internet is a dependency. Architecture decides how much of it you need.

Adapted from my original post on TallerWeb.

What building a life simulation taught me about probability and my father’s faith.

Armando — Wed, 06 May 2026 02:43:54 +0000

Some conversations stay with you longer than most books. One of the most memorable I've had was with my father. He argued that life must be the direct work of God because it was simply too improbable to arise on its own.

"Look at everything that had to happen for us to be here," he said. "This can't be a coincidence."

I understood his intuition perfectly. Life does feel like a miracle. But something in his reasoning felt off, not because I don't believe in God, but because I felt we were reading the universe backwards.

1. The Mistake of Looking at the Tree from the Last Leaf

I told my father that his argument was like examining a decision tree starting from the final leaf. When you begin at the end, your specific existence, your exact life, of course, everything looks impossibly lucky. Every unlikely turn, every fortunate event, every precise alignment seems miraculous.
But that feeling is an illusion. It's not that this path was special. It's that any path would have looked special once you reached the end of it.
A simple example: Flip a coin 1,000 times. Whatever sequence you get, heads, tails, tails, heads…, will be astronomically improbable. Yet every possible sequence is equally unlikely. One of them had to occur.
Life is that sequence: improbable, yes, but not more so than any other outcome.

2. Complexity Doesn't Need Magic, Just Simple Rules

To make my point clearer, I turned to something that has fascinated me for years as a software engineer: Conway's Game of Life.
It's a minimalist "universe" governed by ridiculously simple rules:
A cell lives or dies based only on how many neighbors it has.
No purpose. No design. No intelligence behind it.

And yet, from these basic rules emerge:
Gliders that move across the grid
Oscillators and spaceships
Self-replicating patterns
Structures that look almost engineered

The first time I saw complex behavior emerge from nothing, my mind was blown. So, like any curious programmer, I built my own version.
You can try it here: Conway's Game of Life

Repository if you want to check the code: github.com/Armando284/Conway-s-Life-Game

I implemented it in vanilla JavaScript with Canvas, optimizing the neighbor-counting logic and only adding controls to pause, adjust speed, and draw custom patterns. Watching random noise slowly organize into moving, breathing structures felt like witnessing a tiny universe learning to live.
I showed this to my father: "Look, no miracles, no designer inside the simulation. Just rules. And complexity appears anyway."

3. Artificial Evolution: When Life Emerges Without Being Pushed

I also shared another project I built: a simulation where simple creatures with neural networks evolve to survive in a 2D environment.
Repository: github.com/Armando284/life-simulation

In this simulation:
Each creature has a small neural network (inputs: sensors for food, obstacles, and energy; outputs: movement decisions).
They must navigate toward food while managing limited energy.
Only the ones that reach the goal reproduce, passing on slightly mutated "brains."
Over generations, surprisingly smart behaviors emerge, creatures learn to dodge obstacles, cluster around food, and move efficiently.

No one programmed the final strategies. The intelligence wasn't designed; it evolved through mutation, selection, and millions of small steps.
This is neuroevolution in action: combining neural networks with genetic algorithms. What started as random wiggling slowly turned into purposeful movement. It was mesmerizing to watch.

4. Why Our Intuition Fails with Probability

My father kept insisting life felt too special. He was right, but not in the way he thought.
Life is special to us. But the universe doesn't share our perspective. Our brains evolved for survival, not for understanding deep time or vast probabilities. We overestimate how "unlikely" a specific outcome is once it has already happened.
The truly surprising thing isn't that life emerged. It's that a universe with the right physical constants and rules wouldn't eventually produce it.

5. God Doesn't Need to Break His Own Rules

I closed our conversation with something said with love and respect:
"I do believe in God. But I don't think He has to break the rules of the universe to create what exists. If God created the rules, then life is a natural and beautiful consequence of them."
To me, this makes the universe even more elegant. A system where complexity and life can emerge on their own is more admirable than one that requires constant intervention.

6. What This Conversation Left Me With

I didn't convince my father, and he didn't convince me. That's okay. What mattered was the exchange, thoughtful, respectful, and full of wonder.
Life can be both improbable and inevitable. It can be deeply special without being magical. It can be extraordinarily complex without needing a designer at every step.
And above all, searching for explanations doesn't diminish the beauty of the world. It multiplies it.

Enhancing Cache with Configurable Data Persistence

Armando — Sun, 22 Dec 2024 07:20:12 +0000

Building on the foundations of this guide on creating an in-memory cache, we’ll take it further by introducing configurable data persistence. By leveraging the Adapter and Strategy patterns, we’ll design an extensible system that decouples storage mechanisms from the caching logic, allowing seamless integration of databases or services as needed.

The Vision: Decoupling Like an ORM

The goal is to make the cache extensible without altering its core logic. Inspired by ORM systems, our approach involves a shared API abstraction. This allows storage — such as localStorage, IndexedDB, or even a remote database—to work interchangeably with minimal code changes.

The Storage Adapter Base Class

Here’s the abstract class defining the API for any persistence system:

export abstract class StorageAdapter {
  abstract connect(): Promise<void>;
  abstract add(key: string, value: unknown): Promise<void>;
  abstract get(key: string): Promise<unknown | null>;
  abstract getAll(): Promise<Record<string, unknown>>;
  abstract delete(key: string): Promise<void>;
  abstract clear(): Promise<void>;
}

Any storage solution must extend this base class, ensuring consistency in interaction. For instance, here’s the implementation for IndexedDB:

Example: IndexedDB Adapter

This adapter implements the StorageAdapter interface to persist cache data in an IndexedDB store.

import { StorageAdapter } from './storage_adapter';

/**
 * IndexedDBAdapter is an implementation of the StorageAdapter 
 * interface designed to provide a persistent storage mechanism 
 * using IndexedDB. This adapter can be reused for other cache 
 * implementations or extended for similar use cases, ensuring 
 * flexibility and scalability.
 */
export class IndexedDBAdapter extends StorageAdapter {
  private readonly dbName: string;
  private readonly storeName: string;
  private db: IDBDatabase | null = null;

  /**
   * Initializes the adapter with the specified database and store 
   * names. Defaults are provided to make it easy to set up without 
   * additional configuration.
   */
  constructor(dbName: string = 'cacheDB', storeName: string = 'cacheStore') {
    super();
    this.dbName = dbName;
    this.storeName = storeName;
  }

  /**
   * Connects to the IndexedDB database and initializes it if 
   * necessary. This asynchronous method ensures that the database 
   * and object store are available before any other operations. 
   * It uses the `onupgradeneeded` event to handle schema creation 
   * or updates, making it a robust solution for versioning.
   */
  async connect(): Promise<void> {
    return await new Promise((resolve, reject) => {
      const request = indexedDB.open(this.dbName, 1);

      request.onupgradeneeded = (event) => {
        const db = (event.target as IDBOpenDBRequest).result;
        if (!db.objectStoreNames.contains(this.storeName)) {
          db.createObjectStore(this.storeName, { keyPath: 'key' });
        }
      };

      request.onsuccess = (event) => {
        this.db = (event.target as IDBOpenDBRequest).result;
        resolve();
      };

      request.onerror = () => reject(request.error);
    });
  }

  /**
   * Adds or updates a key-value pair in the store. This method is 
   * asynchronous to ensure compatibility with the non-blocking 
   * nature of IndexedDB and to prevent UI thread blocking. Using 
   * the `put` method ensures idempotency: the operation will 
   * insert or replace the entry.
   */
  async add(key: string, value: unknown): Promise<void> {
    await this._withTransaction('readwrite', (store) => store.put({ key, value }));
  }

  /**
   * Retrieves the value associated with a key. If the key does not 
   * exist, null is returned. This method is designed to integrate 
   * seamlessly with caching mechanisms, enabling fast lookups.
   */
  async get(key: string): Promise<unknown | null> {
    return await this._withTransaction('readonly', (store) =>
      this._promisifyRequest(store.get(key)).then((result) =>
        result ? (result as { key: string; value: unknown }).value : null
      )
    );
  }

  /**
   * Fetches all key-value pairs from the store. Returns an object 
   * mapping keys to their values, making it suitable for bulk 
   * operations or syncing with in-memory caches.
   */
  async getAll(): Promise<Record<string, unknown>> {
    return await this._withTransaction('readonly', (store) =>
      this._promisifyRequest(store.getAll()).then((results) =>
        results.reduce((acc: Record<string, unknown>, item: { key: string; value: unknown }) => {
          acc[item.key] = item.value;
          return acc;
        }, {})
      )
    );
  }

  /**
   * Deletes a key-value pair by its key. This method is crucial 
   * for managing cache size and removing expired entries. The 
   * `readwrite` mode is used to ensure proper deletion.
   */
  async delete(key: string): Promise<void> {
    await this._withTransaction('readwrite', (store) => store.delete(key));
  }

  /**
   * Clears all entries from the store. This method is ideal for 
   * scenarios where the entire cache needs to be invalidated, such 
   * as during application updates or environment resets.
   */
  async clear(): Promise<void> {
    await this._withTransaction('readwrite', (store) => store.clear());
  }

  /**
   * Handles transactions in a reusable way. Ensures the database 
   * is connected and abstracts the transaction logic. By 
   * centralizing transaction handling, this method reduces 
   * boilerplate code and ensures consistency across all operations.
   */
  private async _withTransaction<T>(
    mode: IDBTransactionMode,
    callback: (store: IDBObjectStore) => IDBRequest | Promise<T>
  ): Promise<T> {
    if (!this.db) throw new Error('IndexedDB is not connected');
    const transaction = this.db.transaction([this.storeName], mode);
    const store = transaction.objectStore(this.storeName);
    const result = callback(store);
    return result instanceof IDBRequest ? await this._promisifyRequest(result) : await result;
  }

  /**
   * Converts IndexedDB request events into Promises, allowing for 
   * cleaner and more modern asynchronous handling. This is 
   * essential for making IndexedDB operations fit seamlessly into 
   * the Promise-based architecture of JavaScript applications.
   */
  private async _promisifyRequest<T>(request: IDBRequest): Promise<T> {
    return await new Promise((resolve, reject) => {
      request.onsuccess = () => resolve(request.result as T);
      request.onerror = () => reject(request.error);
    });
  }
}

Integrating the Adapter into the Cache

The cache accepts an optional StorageAdapter. If provided, it initializes the database connection, loads data into memory, and keeps the cache and storage in sync.

private constructor(capacity: number, storageAdapter?: StorageAdapter) {
  this.capacity = capacity;
  this.storageAdapter = storageAdapter;

  if (this.storageAdapter) {
    this.storageAdapter.connect().catch((error) => {
      throw new Error(error);
    });

    this.storageAdapter.getAll().then((data) => {
      for (const key in data) {
        this.put(key, data[key] as T);
      }
    }).catch((error) => {
      throw new Error(error);
    });
  }

  this.hash = new Map();
  this.head = this.tail = undefined;

  this.hitCount = this.missCount = this.evictionCount = 0;
}

Why Adapter and Strategy Patterns?

Using the Adapter pattern:

Decouples the cache from specific storage mechanisms.
Ensures extensibility for new storage backends.

Combining with the Strategy pattern:

Enables runtime selection of the persistence layer.
Simplifies testing by mocking different adapters.

Key Design Practices

Abstract API: Keeps the cache logic agnostic of storage details.
Singleton Cache: Ensures shared state consistency.
Async Initialization: Avoids blocking operations during setup.
Lazy Loading: Only loads persisted data when a storage adapter is provided.

Next Steps

This design is robust but leaves room for enhancements:

Optimize sync logic for better performance.
Experiment with additional adapters like Redis or SQLite.

Try It Out! 🚀

If you’d like to test the cache in action, it’s available as an npm package: adev-lru. You can also explore the full source code on GitHub: adev-lru repository. I welcome any recommendations, constructive feedback, or contributions to make it even better! 💡

Happy coding! 🚀

How to Create an In-Memory Cache

Armando — Wed, 18 Dec 2024 14:14:04 +0000

In many projects, I’ve noticed that while a cache could be handy — especially on the client side— it’s often overlooked. Client-side caching is critical in enhancing user experience by reducing latency and offloading repeated server requests. For example, in applications with infinite scrolling or frequently updated dashboards, caching previously fetched data prevents unnecessary API calls, ensuring smoother interactions and faster rendering times.

In one of my recent projects, implementing a cache reduced API call volume by over 40%, leading to noticeable performance improvements and cost savings. This underlines why client-side caching should be considered a foundational optimization strategy. A cache tends to be one of the last features considered, despite its significant impact on performance with relatively simple implementation, whether due to development time constraints or other priorities.

A cache can be implemented at various levels in architecture: from backend caching using Redis, a CDN for static content, to an in-memory cache on the client or even using localStorage or IndexedDB for persistency. Ideally, these strategies should be combined to reduce the load and cost of databases and APIs, as well as the lag from client-server requests, especially for data that has already been fetched before.

In this article, we’ll explore how to design and implement an LRU (Least Recently Used) cache with TTL (Time-to-Live) support in JavaScript, creating a package similar to my adev-lru. By the end, you’ll have a working example that showcases the core principles and functionality of an effective caching solution.

What is an LRU Cache?

An LRU (Least Recently Used) cache ensures that the most recently accessed items remain in memory while evicting the least recently accessed ones when their capacity is exceeded. This strategy works by maintaining an order of usage: each accessory updates the item’s position in the cache, with the least accessed items being removed first.

Compared to other caching strategies, LRU balances simplicity and efficiency, making it well-suited for scenarios where recent usage is a reliable indicator of future access. For example, applications that cache API responses, thumbnails, or frequently accessed user preferences can leverage LRU to reduce redundant fetch operations without over-complicating the eviction process.

Unlike LFU (Least Frequently Used), which tracks access frequency and requires additional bookkeeping, LRU avoids this complexity while still achieving excellent performance in many real-world use cases. Similarly, FIFO (First In, First Out) and MRU (Most Recently Used) offer alternative eviction policies but may not align as well with usage patterns where recent activity is critical. By combining LRU with TTL (Time-to-Live) support in my implementation, it also handles scenarios where data needs automatic expiration, further enhancing its applicability in dynamic environments like live dashboards or streaming services. It’s especially useful in applications where access to the most recent data is critical.

Implementation

The LRUCache class is built to be efficient, support flexible configurations, and handle automatic evictions. Below are some key methods:

Creating the Cache

public static getInstance<T>(capacity: number = 10): LRUCache<T> {
    if (LRUCache.instance == null) {
        LRUCache.instance = new LRUCache<T>(capacity);
    }
    return LRUCache.instance;
}

This method ensures there is only one instance of the cache in the application, a design choice that simplifies resource management. By implementing the cache as a singleton, we avoid redundant memory usage and ensure consistent data across the application. This is particularly valuable in scenarios where multiple components or modules need access to the same cached data, as it prevents conflicts and ensures synchronization without requiring additional coordination logic. If no capacity is specified, it defaults to 10.

Adding an Item to the Cache

public put(key: string, value: T, ttl: number = 60_000): LRUCache<T> {
    const now = Date.now();
    let node = this.hash.get(key);
    if (node != null) {
        this.evict(node);
    }
    node = this.prepend(key, value, now + ttl);
    this.hash.set(key, node);
    if (this.hash.size > this.capacity) {
        const tailNode = this.pop();
        if (tailNode != null) {
            this.hash.delete(tailNode.key);
        }
    }
    return this;
}

This method adds or updates an item in the cache. When a key already exists, its corresponding item is evicted and re-added at the front of the cache. To do this the cache uses a Doubly Linked List to save the data as nodes and maintain the ability to delete data from the end of the list — Tail— and move it to the beginning of the list — Head —, to guarantee a constant O(1) read of every node’s data a Hash Table is used to save a pointer to each node of the list. This process aligns with the LRU principle by ensuring that recently accessed items are always prioritized, effectively marking them as “most recently used.” By doing so, the cache maintains an accurate order of usage, which is critical for making eviction decisions when the capacity is exceeded. This behavior ensures that resources are optimally managed, minimizing the retrieval time for frequently accessed data. If the key already exists, the item is moved to the front to mark it as recently used.

Retrieving an Item from the Cache

public get(key: string): T | undefined {
    const node = this.hash.get(key);
    const now = Date.now();
    if (node == null || node.ttl < now) {
        return undefined;
    }
    this.evict(node);
    this.prepend(node.key, node.value, node.ttl);
    return node.value;
}

This method retrieves stored items. If the item has expired, it is removed from the cache.

Performance Metrics

To evaluate the cache’s efficiency, I implemented performance metrics like hit rate, misses, and evictions:

private getHitRate(): number {
    const totalRequests = this.hitCount + this.missCount;
    return totalRequests === 0 ? 0 : this.hitCount / totalRequests;
}

Clearing the Cache

public clear(): void {
    this.hash.clear();
    this.head = this.tail = undefined;
}

This method clears all items and resets the cache state.

In my implementation, I have also added other methods like getOption which instead of returning T | undefined it return an instance of the monad Option for those who prefer a more functional approach. I also added a Writer monad to track every operation on the cache for logging purposes.

You can see all the other methods involved in this algorithm, very well commented, on this repository: https://github.com/Armando284/adev-lru

Comparing Cache Algorithms

An LRU cache is not the only option. Choosing the right caching algorithm depends heavily on the application’s specific requirements and access patterns. Below is a comparison of LRU with other commonly used caching strategies and guidance on when to use each:

LFU (Least Frequently Used): This algorithm evicts items that are accessed the least number of times. It’s ideal for scenarios where usage frequency over time is a better predictor of future access than recency. However, it typically requires additional bookkeeping to track access counts, making it more complex and computationally expensive than LRU. Use LFU for applications like recommendation engines or machine learning pipelines where historical usage patterns are critical.
FIFO (First In, First Out): This approach removes the oldest items, regardless of how often they are accessed. While it is simple to implement, FIFO might not be suitable for most use cases as it doesn’t consider usage patterns. It can work for applications with fixed, predictable workflows, such as caching static configurations or preloaded assets.
MRU (Most Recently Used): MRU evicts the most recently accessed items, the opposite of LRU. This strategy is best suited for situations where older data is more likely to be reused, such as rollback systems or certain types of undo operations.

When to Use LRU

LRU strikes a balance between simplicity and effectiveness, making it ideal for applications where recent activity correlates strongly with future use. For instance:

Web and API Caching: LRU is well-suited for reducing redundant API calls, especially in scenarios like paginated views, infinite scrolling, or frequent polling of live data.
Multimedia Applications: Cache recently played or viewed items like videos or images.
UI State Management: Store recently accessed component states to improve rendering performance.

In contrast, if access patterns show that frequency or insertion order is more relevant, algorithms like LFU or FIFO might be a better choice. Evaluating these trade-offs ensures that the caching strategy aligns with your application’s goals and resource constraints.

LFU (Least Frequently Used): Removes the least accessed items based on frequency.
FIFO (First In, First Out): Evicts the oldest item, regardless of recent usage.
MRU (Most Recently Used): Removes the most recently added items, contrary to LRU.

Conclusion

Implementing an in-memory cache can significantly enhance an application’s performance, reducing response times and improving user experience.

If you want to see a full LRU Cache in action you can use my npm package https://www.npmjs.com/package/adev-lru I would also love to get your feedback to keep improving it.

Try the package and share your thoughts or contribute if you feel like helping more 😁!