Data Storage Client

A client library for the Sailboat Computer Data Storage Service with resilience features and offline support.

Features

• Simplified API: Easy-to-use interface for storing and retrieving data
• Caching: LRU cache with TTL for frequently accessed data
• Resilience: Circuit breakers, retries, and timeouts for API calls
• Offline Support: Local storage fallback when service is unavailable
• Real-time Updates: WebSocket support for data change notifications
• Type Safety: Full TypeScript support with generated types

Installation

npm install @sailboat-computer/data-storage-client

Quick Start

import { createDataStorageClient } from '@sailboat-computer/data-storage-client';

// Create a client
const client = createDataStorageClient({
  serviceUrl: 'http://localhost:3000',
  cache: {
    enabled: true,
    maxItems: 1000,
    defaultTtlMs: 60000, // 1 minute
  },
  offline: {
    enabled: true,
    maxBufferSize: 1000,
    syncIntervalMs: 60000, // 1 minute
  },
});

// Initialize the client
await client.initialize();

// Store data
const id = await client.store({ value: 42 }, 'sensor-readings');

// Retrieve data
const data = await client.retrieve({ id });

// Update data
await client.update({
  data: { value: 43 },
  metadata: {
    id,
    category: 'sensor-readings',
    timestamp: new Date(),
  },
});

// Delete data
await client.delete(id);

// Subscribe to data changes
const subscriptionId = client.subscribe('sensor-readings', (data) => {
  console.log('Data changed:', data);
});

// Unsubscribe from data changes
client.unsubscribe(subscriptionId);

// Close the client
await client.close();

Configuration Options

Client Options

interface DataStorageClientOptions {
  // Service URL
  serviceUrl: string;
  
  // Authentication token
  authToken?: string;
  
  // Local storage directory
  localDir?: string;
  
  // Cache options
  cache?: {
    // Whether to enable caching
    enabled: boolean;
    
    // Maximum cache size in items
    maxItems: number;
    
    // Default TTL in milliseconds
    defaultTtlMs: number;
    
    // Category-specific TTLs
    categoryTtls?: Record<string, number>;
  };
  
  // Resilience options
  resilience?: {
    // Circuit breaker options
    circuitBreaker?: {
      // Failure threshold before opening circuit
      failureThreshold: number;
      
      // Reset timeout in milliseconds
      resetTimeoutMs: number;
    };
    
    // Retry options
    retry?: {
      // Maximum number of retries
      maxRetries: number;
      
      // Base delay in milliseconds
      baseDelayMs: number;
    };
    
    // Timeout options
    timeout?: {
      // Default timeout in milliseconds
      defaultTimeoutMs: number;
    };
  };
  
  // Offline options
  offline?: {
    // Whether to enable offline mode
    enabled: boolean;
    
    // Maximum offline buffer size
    maxBufferSize: number;
    
    // Sync interval in milliseconds
    syncIntervalMs: number;
  };
}

Storage Options

interface StorageOptions {
  // Data timestamp
  timestamp?: Date;
  
  // Data tags
  tags?: Record<string, string>;
  
  // Storage tier
  tier?: StorageTier;
  
  // Data priority
  priority?: 'low' | 'normal' | 'high' | 'critical';
  
  // Time to live in seconds
  ttl?: number;
}

Data Query

interface DataQuery {
  // Data ID
  id?: string;
  
  // Data category
  category?: string;
  
  // Time range
  timeRange?: {
    // Start time
    start?: string;
    
    // End time
    end?: string;
  };
  
  // Sort options
  sort?: {
    // Sort field
    field: string;
    
    // Sort order
    order: 'asc' | 'desc';
  };
}

Advanced Usage

Offline Mode

The client automatically detects when the service is unavailable and switches to offline mode. In offline mode, all operations are stored locally and synchronized when the service becomes available again.

// Check if the client is in offline mode
const status = await client.getStatus();
console.log('Offline mode:', status.offline);

// Force synchronization
await client.forceSynchronization();

Caching

The client uses an LRU cache to store frequently accessed data. You can configure the cache size and TTL for different categories.

const client = createDataStorageClient({
  serviceUrl: 'http://localhost:3000',
  cache: {
    enabled: true,
    maxItems: 1000,
    defaultTtlMs: 60000, // 1 minute
    categoryTtls: {
      'sensor-readings': 30000, // 30 seconds
      'system-status': 300000, // 5 minutes
    },
  },
});

Real-time Updates

The client can subscribe to data changes using WebSockets.

// Subscribe to all changes in a category
const subscriptionId = client.subscribe('sensor-readings', (data) => {
  console.log('Data changed:', data);
});

// Unsubscribe when done
client.unsubscribe(subscriptionId);

Error Handling

The client uses a resilience framework to handle errors and recover from failures.

try {
  await client.store({ value: 42 }, 'sensor-readings');
} catch (error) {
  if (error.code === 'CIRCUIT_OPEN') {
    console.log('Circuit breaker is open, service is unavailable');
  } else if (error.code === 'TIMEOUT') {
    console.log('Operation timed out');
  } else if (error.code === 'NETWORK_ERROR') {
    console.log('Network error');
  } else {
    console.log('Unknown error:', error);
  }
}

Development

Building

npm run build

Testing

npm test

Linting

npm run lint

License

MIT