timestar

Node.js client for the TimeStar time series database with native compression.

Communicates over a protobuf binary protocol and compresses all data in-process using a native C++ addon, achieving up to 200x compression on timestamps and sub-millisecond query latency.

Features

• Protobuf binary protocol -- all requests and responses use application/protobuf by default (JSON fallback available)
• Native C++ compression compiled via cmake-js and node-addon-api:
  • FFOR (Frame-of-Reference) for timestamps and integers
  • ALP (Adaptive Lossless floating-Point) for doubles
  • RLE (Run-Length Encoding) for booleans
  • zstd for strings
• All 15 API endpoints -- write, query, delete, metadata, retention, streaming, derived queries, anomaly detection, and forecasting
• TypeScript-first -- full type definitions for every request and response

Prerequisites

Requirement	Version	Notes
Node.js	>= 18	Uses native fetch and node:http
C++ compiler	gcc or clang	Required to build the native addon
CMake	>= 3.15	Build system for the native addon
zstd library	any	sudo apt install libzstd-dev (Debian/Ubuntu) or brew install zstd (macOS)

Install

npm install timestar

The native compression addon compiles automatically on install via cmake-js. If the build fails, ensure the prerequisites above are installed.

Quick Start

Connect

import { TimestarClient } from "timestar";

const client = new TimestarClient({
  host: "localhost",
  port: 8086,
});

Write Points

// Array fields — type auto-detected from contents
await client.write({
  measurement: "cpu",
  tags: { host: "server-01", region: "us-east" },
  fields: {
    usage: [55.2, 62.8, 49.1],
    throttled: [false, false, true],
  },
  timestamps: [1700000000000, 1700000001000, 1700000002000],
});

// Single scalar shorthand
await client.write({
  measurement: "cpu",
  tags: { host: "server-01" },
  fields: { usage: 55.2 },
  timestamps: [1700000000000],
});

// Explicit type when needed (e.g., force int64 for whole numbers)
await client.write({
  measurement: "counters",
  tags: { host: "server-01" },
  fields: { requests: { int64Values: [1000, 2000, 3000] } },
  timestamps: [1700000000000, 1700000001000, 1700000002000],
});

Field Type Detection

Field values are auto-detected from their contents:

Value	Detected type	Example
number	double (scalar)	{ usage: 55.2 }
boolean	bool (scalar)	{ active: true }
string	string (scalar)	{ name: "sensor-1" }
bigint	int64 (scalar)	{ count: 42n }
number[]	double array	{ usage: [55.2, 62.8] }
boolean[]	bool array	{ active: [true, false] }
string[]	string array	{ tags: ["a", "b"] }

To override auto-detection, wrap in a WriteField object with the explicit type key:

// Whole numbers auto-detect as double — use int64Values to force integer storage
{ requests: { int64Values: [1000, 2000, 3000] } }

// All four explicit types:
{ temperature: { doubleValues: [22.5, 23.1] } }
{ active:      { boolValues: [true, false] } }
{ label:       { stringValues: ["a", "b"] } }
{ count:       { int64Values: [100n, 200n] } }

Query

const result = await client.query(
  "SELECT usage FROM cpu WHERE host = 'server-01'",
  {
    startTime: 1700000000000,
    endTime: 1700000003000,
  },
);

for (const series of result.series) {
  console.log(series.fields.usage.timestamps);
  console.log(series.fields.usage.values);
}

Derived Queries

Combine multiple queries with a formula:

const derived = await client.derived(
  {
    a: "SELECT usage FROM cpu WHERE host = 'server-01'",
    b: "SELECT usage FROM cpu WHERE host = 'server-02'",
  },
  "a + b",
  {
    startTime: 1700000000000,
    endTime: 1700000060000,
    aggregationInterval: "10s",
  },
);

console.log(derived.timestamps, derived.values);

Subscribe to Live Data

for await (const batch of client.subscribe({ query: "SELECT usage FROM cpu" })) {
  for (const point of batch.points) {
    console.log(point.timestamp, point.value);
  }
}

API Reference

Health

Method	Signature	Returns	Description
health	health()	Promise<HealthResponse>	Returns server health status
isHealthy	isHealthy()	Promise<boolean>	Lightweight check -- returns true if the server responds 200

Write

Method	Signature	Returns	Description
write	write(points: WritePoint | WritePoint[])	Promise<WriteResponse>	Write one or more points with automatic compression

Query

Method	Signature	Returns	Description
query	query(query: string, options?: QueryOptions)	Promise<QueryResponse>	Execute a query with optional time range and aggregation interval

Delete

Method	Signature	Returns	Description
delete	delete(items: DeleteRequestItem | DeleteRequestItem[])	Promise<DeleteResponse>	Delete series, measurements, or specific time ranges. Single items use /delete; arrays use batch delete.

Metadata

Method	Signature	Returns	Description
measurements	measurements(options?: MeasurementsOptions)	Promise<MeasurementsResponse>	List measurements with optional prefix filter and pagination
tags	tags(measurement: string, options?: TagsOptions)	Promise<TagsResponse>	List tag keys and values for a measurement
fields	fields(measurement: string)	Promise<FieldsResponse>	List fields and their types for a measurement
cardinality	cardinality(measurement: string)	Promise<CardinalityResponse>	Get estimated series count and per-tag cardinality

Retention

Method	Signature	Returns	Description
setRetention	setRetention(measurement: string, ttl: string, downsample?: DownsamplePolicy)	Promise<void>	Set a retention policy with optional downsampling
getRetention	getRetention(measurement: string)	Promise<RetentionGetResponse>	Get the retention policy for a measurement
deleteRetention	deleteRetention(measurement: string)	Promise<void>	Remove the retention policy for a measurement

Streaming

Method	Signature	Returns	Description
subscribe	subscribe(request: SubscribeRequest)	AsyncGenerator<StreamingBatch>	Subscribe to live data via SSE. Supports single queries, multi-query with formulas, and backfill.
subscriptions	subscriptions()	Promise<SubscriptionsResponse>	List active subscriptions and their stats

Derived Queries, Anomaly Detection, and Forecasting

Method	Signature	Returns	Description
derived	derived(queries: Record<string, string>, formula: string, options: DerivedQueryOptions)	Promise<DerivedQueryResponse>	Combine multiple queries with a formula (e.g. "a + b", "a / b * 100")
anomalies	anomalies(queries: Record<string, string>, formula: string, options: DerivedQueryOptions)	Promise<AnomalyResponse>	Run anomaly detection on derived data. Returns raw values, upper/lower bounds, scores, and ratings.
forecast	forecast(queries: Record<string, string>, formula: string, options: DerivedQueryOptions)	Promise<ForecastResponse>	Generate forecasts with confidence bounds. Returns past data, forecast values, and upper/lower bands.

Compression

The client uses Approach B: field values and timestamps are compressed client-side into bytes fields within the protobuf messages. The server decompresses them directly, avoiding any intermediate representation.

Four compression algorithms are used, each matched to its data type:

Algorithm	Data Type	How It Works	Typical Ratio
FFOR (Frame-of-Reference)	Timestamps, integers	Subtracts a per-block minimum and bit-packs the residuals. Exceptions (outliers) are stored separately.	~200x
ALP (Adaptive Lossless floating-Point)	Doubles	Encodes IEEE 754 doubles by finding a decimal exponent/factor pair that converts most values to exact integers, then FFOR-compresses those integers.	~15x
RLE (Run-Length Encoding)	Booleans	Stores alternating run lengths of true/false as varints.	~200x
zstd	Strings	Newline-joins all strings and compresses with Zstandard.	~22x

All compression runs in the native C++ addon (no JS overhead in the hot path). Single scalar field values skip compression entirely to avoid overhead exceeding savings.

Benchmarks

Measured performance on the native protobuf+compression path:

• Write throughput: 74M points/sec
• Query latency: sub-millisecond for typical queries

Run benchmarks locally:

# Full benchmark suite
npm run bench

# Compare compressed vs uncompressed
npm run bench:compare

# Benchmark without compression
npm run bench:no-compress

Configuration

The TimestarClient constructor accepts a TimestarClientOptions object:

Option	Type	Default	Description
host	string	"localhost"	TimeStar server hostname
port	number	8086	TimeStar server port
authToken	string	undefined	Bearer token for authentication
useProtobuf	boolean	true	Use protobuf binary protocol. Set to false for JSON.

Error Handling

All API methods throw TimestarError on failure:

import { TimestarClient, TimestarError } from "timestar";

try {
  await client.query("SELECT ...");
} catch (err) {
  if (err instanceof TimestarError) {
    console.error(err.message);    // Error message from the server
    console.error(err.statusCode); // HTTP status code
    console.error(err.code);       // Optional error code
  }
}

License

MIT