@iota-big3/sdk-timeseries

Industrial-grade time-series data platform for the IOTA Big3 SDK ecosystem.

🚀 Features

• High Performance: Handle 1M+ data points/second with sub-second query response times
• Multiple Storage Backends: InfluxDB, TimescaleDB, Apache Druid, Prometheus
• Resilience Patterns: Circuit breakers, retry policies, connection pooling
• Industrial Protocols: OPC-UA, Modbus, BACnet support (coming soon)
• Advanced Analytics: ML-based anomaly detection, forecasting, pattern recognition
• Multi-Protocol Ingestion: HTTP, gRPC, MQTT, Kafka, WebSocket

📦 Installation

npm install @iota-big3/sdk-timeseries

Optional Dependencies

For specific storage backends:

# For InfluxDB
npm install @influxdata/influxdb-client

# For TimescaleDB
npm install pg

# For ingestion protocols
npm install mqtt kafkajs

🔧 Quick Start

Basic Usage

import { createStorageAdapter } from "@iota-big3/sdk-timeseries";

// Create adapter with InfluxDB
const adapter = createStorageAdapter({
  type: "influxdb",
  connection: {
    url: "http://localhost:8086",
    org: "my-org",
    bucket: "iot-data",
    token: process.env.INFLUXDB_TOKEN,
  },
});

// Connect
await adapter.connect();

// Write data
await adapter.write([
  {
    metric: "temperature",
    timestamp: new Date(),
    value: 23.5,
    tags: { sensor: "sensor1", location: "room1" },
  },
]);

// Query data
const result = await adapter.query({
  metrics: ["temperature"],
  startTime: new Date(Date.now() - 3600000), // 1 hour ago
  endTime: new Date(),
  aggregation: "avg",
  aggregationWindow: "5m",
});

console.log(`Average temperature: ${result.data[0].value}`);

Advanced Configuration

const adapter = createStorageAdapter({
  type: "timescaledb",
  connection: {
    url: "postgresql://user:pass@localhost:5432/tsdb",
    schema: "iot",
    tableName: "sensor_data",
  },
  // Connection pooling
  connectionPool: {
    minSize: 2,
    maxSize: 10,
    acquireTimeout: 30000,
  },
  // Circuit breaker
  circuitBreaker: {
    threshold: 5,
    resetTimeout: 30000,
    errorThresholdPercentage: 50,
  },
  // Retry policy
  retry: {
    maxAttempts: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffMultiplier: 2,
  },
});

🏗️ Architecture

Storage Adapters

The SDK uses an adapter pattern to support multiple time-series databases:

// Available adapters
const influxAdapter = createInfluxDBAdapter(config);
const timescaleAdapter = createTimescaleDBAdapter(config);
// Coming soon: Druid, Prometheus

Multi-Storage Pattern

For high availability and redundancy:

import { MultiStorageAdapter } from "@iota-big3/sdk-timeseries";

const multiAdapter = new MultiStorageAdapter([
  { type: "influxdb", connection: primaryConfig },
  { type: "timescaledb", connection: backupConfig },
]);

// Writes to all backends
await multiAdapter.write(dataPoints);

// Queries from primary, fails over to backup
const result = await multiAdapter.query(options);

Resilience Patterns

Circuit Breaker

import { CircuitBreaker } from "@iota-big3/sdk-timeseries";

const breaker = new CircuitBreaker("database", {
  threshold: 5,
  resetTimeout: 30000,
});

await breaker.execute(() => adapter.query(options));

Retry Policy

import { RetryPolicies } from "@iota-big3/sdk-timeseries";

const policy = RetryPolicies.exponential({
  maxAttempts: 5,
  maxDelay: 30000,
});

await policy.execute(() => adapter.write(points));

Connection Pool

import { ConnectionPool } from "@iota-big3/sdk-timeseries";

const pool = new ConnectionPool(factory, {
  minSize: 5,
  maxSize: 20,
  idleTimeout: 300000,
});

📊 Data Types

DataPoint

interface DataPoint {
  metric: string;
  timestamp: Date;
  value: number;
  tags?: Record<string, string>;
  metadata?: Record<string, any>;
}

QueryOptions

interface QueryOptions {
  metrics?: string[];
  startTime: Date;
  endTime: Date;
  aggregation?: AggregationType;
  aggregationWindow?: string;
  tags?: Record<string, string>;
  limit?: number;
  orderBy?: "time" | "value";
  orderDirection?: "asc" | "desc";
}

Aggregation Types

• Basic: sum, avg, min, max, count, first, last
• Statistical: median, stddev, percentile, variance
• Advanced: rate, derivative, integral, moving_average

🔌 Industrial Protocols (Coming Soon)

OPC-UA

const opcuaConfig = {
  endpoint: "opc.tcp://localhost:4840",
  securityMode: "SignAndEncrypt",
};

Modbus

const modbusConfig = {
  host: "192.168.1.100",
  port: 502,
  unitId: 1,
};

🤖 ML Analytics (Coming Soon)

Anomaly Detection

const anomalies = await adapter.detectAnomalies(series, {
  method: "isolation_forest",
  sensitivity: 0.8,
});

Forecasting

const forecast = await adapter.forecast(series, {
  method: "prophet",
  horizon: 24, // hours
});

🧪 Testing

# Run tests
npm test

# With coverage
npm run test:coverage

# Watch mode
npm run test:watch

📈 Performance

Target metrics:

• Ingestion: 1M+ points/second
• Query latency: <100ms for 24-hour range
• Compression: 10:1 ratio
• Concurrent queries: 1000+

🔒 Security

• Connection encryption (TLS/SSL)
• API key authentication
• Role-based access control (coming soon)
• Data encryption at rest (coming soon)

📚 Examples

See the examples directory for:

• Storage adapter demos
• Performance testing
• Industrial IoT scenarios
• Multi-storage patterns

🤝 Contributing

Please see the main IOTA Big3 SDK Contributing Guide.

📄 License

MIT © IOTA Big3 SDK Team