slim-iot-logger

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

npm install slim-iot-logger

Quick Start

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

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

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

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.

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.

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.

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.

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.

const allReadings = logger.queryAll({ since: '1h' });

logger.getLatest(sensorId)

Get the most recent reading.

const latest = logger.getLatest('temperature');
// { sensorId: 'temperature', value: 22.5, timestamp: 1234567890, ... }

logger.getAggregations(sensorId, options?)

Get pre-computed aggregations.

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.

const daily = logger.aggregate('temperature', '24h');

logger.getSensors()

List all sensors with data.

const sensors = logger.getSensors();
// ['temperature', 'humidity', 'motion']

logger.getSensorInfo(sensorId)

Get detailed sensor information.

const info = logger.getSensorInfo('temperature');
// { sensorId, readingCount, firstReading, lastReading, lastValue }

logger.deleteSensor(sensorId)

Delete all data for a sensor.

const deleted = logger.deleteSensor('old-sensor');

logger.cleanup()

Manually trigger retention cleanup.

const deleted = logger.cleanup();

logger.exportSLIM(options?)

Export data as SLIM format.

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.

logger.importSLIM(slim);

logger.stats()

Get logger statistics.

const stats = logger.stats();
// { sensors, readings, aggregations, oldestReading, newestReading, memoryUsage }

logger.save()

Manually save to disk (if persistence enabled).

logger.save();

logger.close()

Close the logger and cleanup resources.

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 - Embedded document database
• slim-protocol-core - SLIM serialization

License

MIT