shard-tsdb

Pure-JS time-series database with Blackjack V2 compressed blocks — built for sensors, walks, and smooth deltas where generic stores waste space. Backends: in-memory (default) or IndexedDB (browser).

| | | |--|--| | npm | [email protected] | | site | slidphilabs.vercel.app | | license | MIT |

Why this exists

Time-series from sensors and game/telemetry counters often look like runs, ±1 walks, and smooth deltas. Storing them as raw floats or gzipped JSON is easy — and bulky. shard-tsdb packs points into Blackjack V2 blocks so you get a small pure-JS TSDB without native codecs or a server.

For record-class integer sequence ratios (zeros / ramps / walks), see sibling Zero Range Wave.

Install

npm i shard-tsdb

Node ≥ 18. Works in the browser with the IndexedDB backend.

Quick start

import { ShardTSDB } from "shard-tsdb";

const db = new ShardTSDB({ backend: "memory", blockSize: 256 });

const tags = { sensor: "temp-1" };
await db.put("room", tags, Date.now(), 21.5);
await db.putBatch(
  "room",
  tags,
  [1, 2, 3, 4, 5].map((i) => Date.now() + i * 1000),
  [21.5, 21.6, 21.6, 21.7, 21.5],
);
await db.flushAll();

const { tss, vals } = await db.range("room", tags, 0, Date.now() + 1e12);
const last = await db.last("room", tags, 10);
const st = await db.stats("room", tags);
// { blocks, points, bytes, avgBitsPerPoint }

Browser:

const db = new ShardTSDB({ backend: "indexeddb" });

API (ShardTSDB)

| Method | Description | |--------|-------------| | constructor({ backend?, blockSize? }) | backend: 'memory' | 'indexeddb' | | put(name, tags, ts, val) | Append one point | | putBatch(name, tags, tss[], vals[]) | Append many | | flushAll() | Force block flush | | range(name, tags, start, end) | Points in time range | | last(name, tags, n) | Last n points | | stats(name, tags) | Block/point/byte stats |

Also exports BlackjackV2 / BlackjackCodec for direct series coding.

Donate to Slid Phi Labs

→ Donate $29.99 · Support $199

Related packages

| Package | Role | |---------|------| | zero-range-wave-compression | ZRW v5 — beats gzip/brotli on zeros/ramps/walks | | blackjack-compression | Blackjack v4 general int/byte/file compressor | | shard-zip | Adaptive Fib + Blackjack V2 + CLI | | slid-phi | Omni-Dormant integer pathways | | CuNi Studio | Exact multi-target code playground |

Brand home: slidphilabs.vercel.app

License

MIT