Statok Node Client

Lightweight, non-blocking Node.js client for emitting Statok metrics from services and jobs.

This package is a TypeScript port of the core Statok Go client.

Install

npm install @prostoteam/statoknode

Quick Start

import { init, count, countUnique, total, value, valueSparse, label } from "@prostoteam/statoknode";

const client = init("payments-api", {
  apiKey: "your-statok-api-key",
});

count("requests", 1, "service=api", label("method", "GET"));
countUnique(42n, "daily_active_users", "service=api");
total("host.net.kb", 2048, "iface=eth0", "dir=rx");
value("latency_ms", 123.4, "service=api", "endpoint=/login");
valueSparse("host.fs.capacity_kb", 1024 * 1024, "mount=/");

await client.close();

Safety Model

• Metric calls never perform network I/O and never return promises.
• Metric calls catch internal errors and do not throw into the application.
• Events enter a bounded in-memory queue; when the queue is full, new events are dropped silently.
• Each client forwards at most 20,000 value/valueSparse samples per wall-clock second. Later value samples in that second are silently ignored before queueing; counter and unique events are unaffected.
• Batches, retry memory, counter aggregation, dictionary size, and total series memory are capped internally.
• Timers are unref()ed so the client does not keep a Node process alive by itself.
• Transport failures are isolated to the background worker and logged through the configured logger.
• 401, unauthorized, and unsupported_protocol_version stop further sends for the current client instance.

API

const client = new Client(workload, config);
const client = init(workload, config);

client.count(metric, delta, ...labels);
client.countUnique(uniqueID, metric, ...labels);
client.total(metric, total, ...labels);
client.value(metric, value, ...labels);
client.valueSparse(metric, value, ...labels);
client.dropped();
await client.close();

Package-level helpers (count, countUnique, total, value, valueSparse) use the client created by init.

uniqueID accepts non-negative safe integers, bigint, decimal strings, Buffer, or Uint8Array. Decimal strings are canonicalized, so "00042" and 42n deduplicate within one batch.

Configuration

type Config = {
  apiKey?: string;
  transport?: Transport;
  logger?: { printf?: (format: string, ...args: unknown[]) => void };
};

Development

npm install
npm test