@sailboat-computer/data-storage/src/types.ts

Shared data storage library for sailboat computer v3

/**
 * Data Storage Types
 * 
 * This file contains type definitions for the data storage package.
 */

// Import types from sailboat-types package
import {
  common,
  data_manager,
  hardware_interface
} from '@sailboat-computer/sailboat-types';

// Define constants for string literal types
export const CircuitBreakerState = {
  CLOSED: 'circuit_closed' as common.CircuitBreakerState,
  OPEN: 'circuit_open' as common.CircuitBreakerState,
  HALF_OPEN: 'circuit_half_open' as common.CircuitBreakerState
};

export const HealthStatus = {
  HEALTHY: 'health_healthy' as common.HealthStatus,
  DEGRADED: 'health_degraded' as common.HealthStatus,
  UNHEALTHY: 'health_unhealthy' as common.HealthStatus,
  CRITICAL: 'health_critical' as common.HealthStatus,
  UNKNOWN: 'health_unknown' as common.HealthStatus
};

export const AlertSeverity = {
  INFO: 'system_info' as common.AlertSeverity,
  WARNING: 'system_warning' as common.AlertSeverity,
  ALARM: 'system_alarm' as common.AlertSeverity,
  CRITICAL: 'system_critical' as common.AlertSeverity,
  EMERGENCY: 'system_emergency' as common.AlertSeverity
};

// Re-export core data-manager types for convenience
export const StorageTier = data_manager.StorageTier;
export const StorageErrorCode = data_manager.StorageErrorCode;
export const BatchPriority = data_manager.BatchPriority;

// Type aliases for enum types
export type CircuitBreakerStateType = common.CircuitBreakerState;
export type HealthStatusType = common.HealthStatus;
export type AlertSeverityType = common.AlertSeverity;
export type StorageTierType = data_manager.StorageTier;
export type StorageErrorCodeType = data_manager.StorageErrorCode;
export type BatchPriorityType = data_manager.BatchPriority;

// Re-export interfaces
export type StorageProviderHealth = data_manager.StorageProviderHealth;
export type StorageProviderConfig = data_manager.StorageProviderConfig;
export type RedisConfig = data_manager.RedisConfig;
export type InfluxDBConfig = data_manager.InfluxDBConfig;
export type PostgreSQLConfig = data_manager.PostgreSQLConfig;
export type StorageConfig = data_manager.StorageConfig;
export type DataMetadata = data_manager.DataMetadata;
export type StoredData = data_manager.StoredData;
export type StorageOptions = data_manager.StorageOptions;
export type CleanupResult = data_manager.CleanupResult;
export type StorageStatus = data_manager.StorageStatus;
export type LocalStorageStatus = data_manager.LocalStorageStatus;
export type SyncResult = data_manager.SyncResult;
export type ClearResult = data_manager.ClearResult;
export type ResilienceMetrics = data_manager.ResilienceMetrics;
export type StorageProvider = data_manager.StorageProvider;
export type StorageManager = data_manager.StorageManager;
export type DataCondition = data_manager.DataCondition;

// Re-export hardware-interface types for convenience
export type RawSensorData = hardware_interface.RawSensorData;

// Define DataQueryResponse interface
export interface DataQueryResponse {
  results: StoredData[];
  totalCount: number;
  hasMore: boolean;
  nextCursor?: string;
}

// Implementation-specific interfaces with extended properties

/**
 * Extended BatchConfig interface with implementation-specific properties
 */
export interface BatchConfig extends data_manager.BatchConfig {
  priorityOverride: boolean;
  maxRetries?: number;
  retryDelayMs?: number;
}

// Define BatchingConfig as an alias for BatchConfig for backward compatibility
export type BatchingConfig = BatchConfig;

/**
 * Extended DataQuery interface with implementation-specific properties
 */
export interface DataQuery extends data_manager.DataQuery {
  id?: string;
  tags?: Record<string, string>;
  limit?: number;
  offset?: number;
  sensors?: string[];
  aggregation?: 'raw' | 'minute' | 'hour' | 'day';
  filters?: Record<string, any>;
}


// Implementation-specific interfaces that don't need to be in the contract

/**
 * Storage manager options
 */
export interface StorageManagerOptions {
  providers?: {
    hot?: StorageProviderConfig;
    warm?: StorageProviderConfig;
    cold?: StorageProviderConfig;
  };
  batching?: BatchConfig;
  resilience?: {
    circuitBreaker?: {
      failureThreshold: number;
      resetTimeoutMs: number;
    };
    retry?: {
      maxRetries: number;
      baseDelayMs: number;
    };
    timeout?: {
      defaultTimeoutMs: number;
    };
  };
  logger?: {
    level: 'debug' | 'info' | 'warn' | 'error';
    console: boolean;
  };
  // Additional properties used in implementation
  retryAttempts?: number;
  retryDelayMs?: number;
  enableMetrics?: boolean;
  metricsInterval?: number;
}

/**
 * Unified storage manager options
 */
export interface UnifiedStorageManagerOptions {
  localStorage: {
    directory: string;
    maxSizeBytes?: number;
    encrypt?: boolean;
    compressionLevel?: number;
  };
  sync: {
    enabled: boolean;
    intervalMs: number;
    batchSize: number;
  };
  resilience?: {
    circuitBreaker?: {
      failureThreshold: number;
      resetTimeoutMs: number;
    };
    retry?: {
      maxRetries: number;
      baseDelayMs: number;
    };
    timeout?: {
      defaultTimeoutMs: number;
      operationTimeouts?: Record<string, number>;
    };
    bulkhead?: {
      maxConcurrentOperations: number;
      maxQueueSize: number;
    };
    rateLimit?: {
      defaultTokensPerSecond: number;
      defaultBucketSize: number;
      tokensPerSecond: number;
      bucketSize: number;
      operationLimits?: any;
      waitWhenLimited: boolean;
      maxWaitTimeMs: number;
      bypassOperations?: string[];
    };
  };
  // Logger options
  logger?: {
    level: 'debug' | 'info' | 'warn' | 'error';
    console: boolean;
  };
}

/**
 * Unified storage manager interface
 */
export interface UnifiedStorageManager extends StorageManager {
  getLocalStatus(): Promise<LocalStorageStatus>;
  clearLocalCache(): Promise<ClearResult>;
  synchronize(): Promise<SyncResult>;
  getResilienceMetrics(): ResilienceMetrics;
}

/**
 * Batch manager interface
 */
export interface BatchManager {
  initialize(config: BatchConfig): void;
  stop(): void;
  addToBatch(data: any, metadata: DataMetadata, priority: BatchPriorityType): void;
  flush(): Promise<void>;
  getBatchStatus(): BatchStatus;
}

/**
 * Batch status
 */
export interface BatchStatus {
  pendingItems: number;
  lastFlush?: Date;
  averageBatchSize: number;
  totalBatches: number;
  failedBatches: number;
}

/**
 * Downsampling engine interface
 */
export interface DownsamplingEngine {
  initialize(rules: DownsamplingRule[]): void;
  downsample(data: StoredData[]): Promise<StoredData[]>;
  registerDownsampler(downsampler: Downsampler): void;
  getDownsampler(strategyType: string): Downsampler | undefined;
}

/**
 * Downsampling rule
 */
export interface DownsamplingRule {
  id: string;
  name: string;
  dataType: string;
  strategy: DownsamplingStrategy;
  criticalDataConditions?: DataCondition[];
}

/**
 * Downsampler interface
 */
export interface Downsampler {
  readonly type: string;
  downsample(data: StoredData[], strategy: any): Promise<StoredData[]>;
}

/**
 * Lifecycle manager interface
 */
export interface LifecycleManager {
  initialize(config: LifecycleManagerConfig): void;
  stop(): void;
  runCleanup(): Promise<void>;
  runMigration(): Promise<void>;
  runDownsampling(ruleId: string): Promise<void>;
  getPolicies(): LifecyclePolicy[];
  onBeforeMigration(handler: MigrationHandler): void;
  onAfterMigration(handler: MigrationHandler): void;
  onBeforeDownsampling(handler: DownsamplingHandler): void;
  onAfterDownsampling(handler: DownsamplingHandler): void;
}

/**
 * Lifecycle manager configuration
 */
export interface LifecycleManagerConfig {
  policies: LifecyclePolicy[];
  downsamplingRules: DownsamplingRule[];
  downsamplingSchedules: DownsamplingSchedule[];
  cleanupInterval: number;
  migrationInterval: number;
}

/**
 * Lifecycle policy
 */
export interface LifecyclePolicy {
  category: string;
  hotRetentionDays: number;
  warmRetentionDays: number;
  coldRetentionDays: number;
  migrationThresholdDays: number;
  downsample: boolean;
  downsamplingRuleId?: string;
}

/**
 * Downsampling schedule
 */
export interface DownsamplingSchedule {
  ruleId: string;
  cronExpression: string;
  enabled: boolean;
}

/**
 * Migration handler
 */
export type MigrationHandler = (data: StoredData, fromTier: StorageTierType, toTier: StorageTierType) => Promise<void>;

/**
 * Downsampling handler
 */
export type DownsamplingHandler = (data: StoredData[], rule: DownsamplingRule) => Promise<void>;

/**
 * Downsampling strategy types
 */
export type DownsamplingStrategy =
  | TimeBasedStrategy
  | GeospatialStrategy
  | CycleBasedStrategy
  | GeotemporalStrategy
  | GeotemporalGridStrategy
  | MaintenanceBasedStrategy;

/**
 * Time-based downsampling strategy
 */
export interface TimeBasedStrategy {
  type: 'time-based';
  levels: {
    ageThreshold: number;
    interval: string;
    aggregations: AggregationConfig[];
  }[];
}

/**
 * Aggregation configuration
 */
export interface AggregationConfig {
  function: string;
  field: string;
  outputField?: string;
  groupBy?: string[];
}

/**
 * Geospatial downsampling strategy
 */
export interface GeospatialStrategy {
  type: 'geospatial';
  simplificationTolerance: number;
  preserveDirectionChanges: boolean;
  minAngleChange: number;
  preserveKeyPoints: boolean;
}

/**
 * Cycle-based downsampling strategy
 */
export interface CycleBasedStrategy {
  type: 'cycle-based';
  cycleDetection: {
    startCondition: DataCondition;
    endCondition: DataCondition;
  };
  samplesPerCycle: number;
  preserveExtrema: boolean;
}

/**
 * Geotemporal downsampling strategy
 */
export interface GeotemporalStrategy {
  type: 'geotemporal';
  gridResolution: {
    latitude: number;
    longitude: number;
  };
  timeIntervals: string[];
  aggregations: AggregationConfig[];
  adaptiveResolution?: boolean;
}

/**
 * Geotemporal grid downsampling strategy
 */
export interface GeotemporalGridStrategy {
  type: 'geotemporal-grid';
  baseGridSize: number;
  adaptiveGridLevels: number;
  coastalResolutionBoost?: number;
  temporalHierarchy: {
    recent: { maxAge: number, resolution: number };
    mediumTerm: { maxAge: number, resolution: number };
    longTerm: { maxAge: number, resolution: number };
    historical: { maxAge: number, resolution: number };
    seasonal: { resolution: number };
  };
  vesselPosition?: { latitude: number, longitude: number };
  plannedRoute?: Array<{ latitude: number, longitude: number }>;
  historicalAreaOfInterest?: Array<{ 
    latitude: number, 
    longitude: number, 
    weight: number 
  }>;
  criticalFeatureThresholds?: {
    pressureChangeRate?: number;
    windSpeed?: number;
    waveHeight?: number;
    temperatureGradient?: number;
  };
}

/**
 * Maintenance-based downsampling strategy
 */
export interface MaintenanceBasedStrategy {
  type: 'maintenance-based';
  maintenanceEventType: string;
  samplesBeforeEvent: number;
  samplesAfterEvent: number;
  normalSamplingInterval: string;
  detailedSamplingInterval: string;
}