npm package: @iota-big3/sdk-timeseries
Description: Time series data processing and analytics for the IOTA Big3 SDK
Author: IOTA Big3 Team
Latest version: 1.0.0

# @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

```bash
npm install @iota-big3/sdk-timeseries
```

### Optional Dependencies

For specific storage backends:

```bash
# For InfluxDB
npm install @influxdata/influxdb-client

# For TimescaleDB
npm install pg

# For ingestion protocols
npm install mqtt kafkajs
```

## 🔧 Quick Start

### Basic Usage

```typescript
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

```typescript
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:

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

### Multi-Storage Pattern

For high availability and redundancy:

```typescript
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

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

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

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

#### Retry Policy

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

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

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

#### Connection Pool

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

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

## 📊 Data Types

### DataPoint

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

### QueryOptions

```typescript
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

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

### Modbus

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

## 🤖 ML Analytics (Coming Soon)

### Anomaly Detection

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

### Forecasting

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

## 🧪 Testing

```bash
# 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](./examples) directory for:

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

## 🤝 Contributing

Please see the main [IOTA Big3 SDK Contributing Guide](../../CONTRIBUTING.md).

## 📄 License

MIT © IOTA Big3 SDK Team