npm package: @matteuccimarco/slim-iot-logger
Description: IoT sensor logger with SLIM storage - efficient time-series data for edge devices
Author: Marco Matteucci
Latest version: 0.1.0

# slim-iot-logger

[![npm version](https://img.shields.io/npm/v/slim-iot-logger.svg)](https://www.npmjs.com/package/slim-iot-logger)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Efficient IoT sensor logging with SLIM storage** - Perfect for edge devices, embedded systems, and resource-constrained environments.

## Why slim-iot-logger?

- **40-50% smaller storage** than JSON-based loggers
- **Automatic data retention** - set it and forget it
- **Built-in aggregations** - min/max/avg per time window
- **Time-range queries** - fast retrieval of historical data
- **Zero config persistence** - just point to a directory
- **TypeScript first** - full type safety

## Installation

```bash
npm install slim-iot-logger
```

## Quick Start

```typescript
import { createSensorLogger } from 'slim-iot-logger';

// Create logger (in-memory)
const logger = createSensorLogger();

// Or with persistence
const logger = createSensorLogger({
  dataDir: '/var/sensors',
  retention: '7d',           // Keep 7 days of data
  aggregationWindow: '1h',   // Aggregate hourly
});

// Log sensor readings
logger.log('temperature', 22.5, { unit: 'C' });
logger.log('humidity', 65, { unit: '%' });
logger.log('motion', true, { metadata: { location: 'living-room' } });

// Query data
const lastHour = logger.query('temperature', { since: '1h' });
const latest = logger.getLatest('temperature');

// Get aggregations
const hourlyAvg = logger.getAggregations('temperature', { since: '24h' });

// Export for transmission
const slim = logger.exportSLIM({ since: '1h' });
```

## Use Cases

### Home Automation Hub

```typescript
const logger = createSensorLogger({
  dataDir: './sensor-data',
  retention: '30d',
  aggregationWindow: '15m',
});

// Log from multiple sensors
logger.log('living-room/temp', 21.5);
logger.log('living-room/humidity', 55);
logger.log('bedroom/temp', 19.0);
logger.log('garage/door', 'closed');

// Check for anomalies
const readings = logger.query('living-room/temp', {
  since: '1h',
  filter: { value: { $gt: 28 } },
});

if (readings.length > 0) {
  console.log('Temperature alert!');
}
```

### Industrial Monitoring

```typescript
const logger = createSensorLogger({
  dataDir: '/data/machines',
  retention: '90d',
  aggregationWindow: '5m',
});

// High-frequency logging
setInterval(() => {
  logger.log('machine-1/rpm', getMachineRPM());
  logger.log('machine-1/temp', getMachineTemp());
  logger.log('machine-1/vibration', getVibration());
}, 1000);

// Periodic export to central server
setInterval(async () => {
  const slim = logger.exportSLIM({ since: '5m' });
  await sendToServer(slim);
}, 5 * 60 * 1000);
```

### Weather Station

```typescript
const logger = createSensorLogger({
  dataDir: './weather',
  retention: '365d',
  aggregationWindow: '1h',
});

// Log weather data
function logWeather() {
  const now = Date.now();
  logger.log('temperature', readTemp(), { unit: 'C', timestamp: now });
  logger.log('humidity', readHumidity(), { unit: '%', timestamp: now });
  logger.log('pressure', readPressure(), { unit: 'hPa', timestamp: now });
  logger.log('wind-speed', readWind(), { unit: 'km/h', timestamp: now });
  logger.log('rainfall', readRain(), { unit: 'mm', timestamp: now });
}

// Get daily summary
function getDailySummary() {
  return {
    temperature: logger.getAggregations('temperature', { since: '24h' }),
    rainfall: logger.aggregate('rainfall', '24h'),
  };
}
```

## API Reference

### createSensorLogger(options?)

Create a new sensor logger instance.

```typescript
interface LoggerOptions {
  dataDir?: string | null;      // Persistence directory (null = in-memory)
  autoSaveInterval?: number;    // Auto-save interval in ms
  retention?: string;           // Data retention: '7d', '24h', '30m', etc.
  cleanupInterval?: number;     // Cleanup check interval in ms
  aggregationWindow?: string;   // Aggregation window: '1h', '15m', etc.
  autoAggregate?: boolean;      // Enable auto-aggregation (default: true)
}
```

### logger.log(sensorId, value, options?)

Log a sensor reading.

```typescript
logger.log('temperature', 22.5);
logger.log('temperature', 22.5, { unit: 'C' });
logger.log('temperature', 22.5, {
  unit: 'C',
  timestamp: Date.now(),
  metadata: { location: 'outdoor' },
});
```

### logger.logBatch(readings)

Log multiple readings at once.

```typescript
logger.logBatch([
  { sensorId: 'temp1', value: 20, unit: 'C' },
  { sensorId: 'temp2', value: 21, unit: 'C' },
  { sensorId: 'humidity', value: 65, unit: '%' },
]);
```

### logger.query(sensorId, options?)

Query sensor readings.

```typescript
interface QueryOptions {
  since?: number | string;   // Start time: timestamp, '1h', '7d', ISO date
  until?: number | string;   // End time
  limit?: number;            // Max results
  order?: 'asc' | 'desc';    // Sort order (default: 'desc')
  filter?: object;           // Additional filter conditions
}

// Examples
logger.query('temperature');                    // All readings
logger.query('temperature', { since: '1h' });   // Last hour
logger.query('temperature', { limit: 10 });     // Last 10
logger.query('temperature', {
  since: '24h',
  filter: { value: { $gt: 25 } },
});
```

### logger.queryAll(options?)

Query all sensors.

```typescript
const allReadings = logger.queryAll({ since: '1h' });
```

### logger.getLatest(sensorId)

Get the most recent reading.

```typescript
const latest = logger.getLatest('temperature');
// { sensorId: 'temperature', value: 22.5, timestamp: 1234567890, ... }
```

### logger.getAggregations(sensorId, options?)

Get pre-computed aggregations.

```typescript
const hourly = logger.getAggregations('temperature', { since: '24h' });
// [{ periodStart, periodEnd, count, min, max, avg, sum, first, last }, ...]
```

### logger.aggregate(sensorId, since?, until?)

Manually aggregate data for a time range.

```typescript
const daily = logger.aggregate('temperature', '24h');
```

### logger.getSensors()

List all sensors with data.

```typescript
const sensors = logger.getSensors();
// ['temperature', 'humidity', 'motion']
```

### logger.getSensorInfo(sensorId)

Get detailed sensor information.

```typescript
const info = logger.getSensorInfo('temperature');
// { sensorId, readingCount, firstReading, lastReading, lastValue }
```

### logger.deleteSensor(sensorId)

Delete all data for a sensor.

```typescript
const deleted = logger.deleteSensor('old-sensor');
```

### logger.cleanup()

Manually trigger retention cleanup.

```typescript
const deleted = logger.cleanup();
```

### logger.exportSLIM(options?)

Export data as SLIM format.

```typescript
interface ExportOptions {
  sensors?: string[];            // Specific sensors (all if omitted)
  since?: number | string;       // Start time
  until?: number | string;       // End time
  includeAggregations?: boolean; // Include aggregation data
}

const slim = logger.exportSLIM({ since: '1h' });
const tempOnly = logger.exportSLIM({ sensors: ['temperature'] });
```

### logger.importSLIM(slim)

Import data from SLIM format.

```typescript
logger.importSLIM(slim);
```

### logger.stats()

Get logger statistics.

```typescript
const stats = logger.stats();
// { sensors, readings, aggregations, oldestReading, newestReading, memoryUsage }
```

### logger.save()

Manually save to disk (if persistence enabled).

```typescript
logger.save();
```

### logger.close()

Close the logger and cleanup resources.

```typescript
logger.close();
```

## Duration Strings

Time durations can be specified as:

| Format | Example | Description |
|--------|---------|-------------|
| `Xms`  | `500ms` | Milliseconds |
| `Xs`   | `30s`   | Seconds |
| `Xm`   | `15m`   | Minutes |
| `Xh`   | `2h`    | Hours |
| `Xd`   | `7d`    | Days |

## Requirements

- Node.js >= 18.0.0
- slim-db >= 0.1.0

## Related Packages

- [slim-db](https://www.npmjs.com/package/slim-db) - Embedded document database
- [slim-protocol-core](https://www.npmjs.com/package/slim-protocol-core) - SLIM serialization

## License

MIT