Flavors · one engine, pluggable codecs
Pick the codec that matches your ids.
@cloudbitmaps/core is codec-agnostic. Tiering, chunk-skipping intersection, compaction, encryption and the ten storage drivers live there and do not change. A flavor decides one thing — how a chunk of ids is represented on the wire and at rest.
Choose one
One of these ships. The other two are on this page so the shape of the plan is visible — there is no page for a package you cannot install, and a row becomes a link the day it publishes.
| Flavor | Status | Take it when | Cost of choosing it |
|---|---|---|---|
| @cloudbitmaps/roaring Adaptive containers — array, bitset, run | Shipped 0.4.1 | Ids are sparse or clustered and adaptive containers do real compression work. The default: if you are moving off Redis sets, start here. | A native dependency and its platform matrix. |
| @cloudbitmaps/bitset One bit per id — no containers, no branches | Coming | Ids are dense, or you want zero native dependency — edge runtimes, no platform matrix, nothing to compile. | Sparse sets pay full width per chunk. |
| @cloudbitmaps/soaring A separate algorithm, unproven | Research | Under research, with nothing to install. It ships only if the algorithm proves out against roaring on real workloads — and if it does not, this row goes away. | — |
Adding a flavor is one row here and one figure on its own page. Nothing else on the site changes, because nothing else depends on the codec.
Where the choice does not matter
Every flavor is a codec plugged into the same store. Swapping one is an import change and a re-publish of your segments — the drivers, the tier policy, the compaction daemon and the container format around the payload all stay put.
Cost
$0.75 per million incremental writes, against $346/mo standing for a Redis-HA node. Billed by the request either way — a codec changes bytes, not the pricing model.
The moat
100 of 2,000 chunks fetched when intersecting two 2,000,000-id segments — the shared keys only. Key alignment happens above the codec, so it survives every flavor. Step through it.
When to walk away
No flavor fixes this. Sub-millisecond p99 on a working set that fits a bounded hot cache is a different machine; a RAM store answers a single membership check 10–20× faster than any warm-tier round trip. Use Redis.
The API, whichever you pick
add · has · remove · count, and the full set algebra — intersect, union, andNot — plus *Into variants that write the result straight to a destination segment instead of returning it. A flavor is a CodecInterface implementation underneath ten drivers and three tiers, and changes none of these signatures.
Start with roaring.
It is the one that ships, and it is the right default unless you already know your ids are dense. The memory drivers need no configuration, so the quickstart runs before you decide anything about storage.
npm i @cloudbitmaps/roaring
# the memory drivers need nothing else
# add an SDK only for a real backend:
npm i @aws-sdk/client-s3