Photo-Weather Shared Package

Shared TypeScript types, constants, and utilities for the Photo-to-DB backend and Angular frontend projects.

📦 Installation

npm install @mhaines/photo-weather-shared

🚀 Usage

Import Types

import {
  WeatherData,
  TidalData,
  ImageMetadata,
  ExifData,
  ApiResponse
} from '@mhaines/photo-weather-shared';

Import Constants

import {
  ENDPOINTS,
  QUERY_PARAMS,
  DEFAULTS,
  WeatherProvider,
  DataQuality
} from '@mhaines/photo-weather-shared';

Import Utilities

import {
  validateCoordinates,
  calculateDistance,
  formatDateForAPI,
  getRelativeTime
} from '@mhaines/photo-weather-shared';

📋 What's Included

🌤️ Weather Types

• WeatherData - Complete weather information structure
• TidalData - Tidal conditions and predictions
• WeatherDataRequest - Request parameters for weather APIs
• WeatherProvider, DataQuality enums

📷 Image Types

• ImageMetadata - Complete image information
• ExifData - Camera and GPS metadata
• ImageUploadRequest/Response - Upload API contracts
• ImageQueryParams - Filtering and pagination

🌐 API Types

• ApiResponse<T> - Standardized API response format
• ApiError - Error response structure
• HealthCheckResponse - System health information
• HttpStatus enum - Standard HTTP status codes

🔧 Utilities

• Coordinates: Validation, distance calculation, formatting
• Dates: API formatting, validation, relative time
• Constants: API endpoints, query parameters, defaults

🎯 Frontend Usage (Angular)

Service Integration

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import {
  ENDPOINTS,
  ImageUploadResponse,
  WeatherData,
  ApiResponse
} from '@mhaines/photo-weather-shared';

@Injectable()
export class PhotoService {
  constructor(private http: HttpClient) {}

  uploadImage(formData: FormData): Observable<ImageUploadResponse> {
    return this.http.post<ImageUploadResponse>(ENDPOINTS.IMAGES.UPLOAD, formData);
  }

  getWeatherData(lat: number, lon: number): Observable<ApiResponse<WeatherData>> {
    return this.http.get<ApiResponse<WeatherData>>(ENDPOINTS.WEATHER.BASE, {
      params: { latitude: lat.toString(), longitude: lon.toString() }
    });
  }
}

Component Usage

import { Component } from '@angular/core';
import {
  ImageMetadata,
  WeatherData,
  formatDisplayDateTime,
  getRelativeTime
} from '@mhaines/photo-weather-shared';

@Component({
  template: `
    <div *ngFor="let image of images">
      <h3>{{ image.originalName }}</h3>
      <p>Uploaded: {{ getRelativeTime(image.uploadDate) }}</p>
      <div *ngIf="image.weatherData">
        <p>Temperature: {{ image.weatherData.temperature.value }}°{{ image.weatherData.temperature.unit }}</p>
        <p *ngIf="image.weatherData.tidalData">
          Tide: {{ image.weatherData.tidalData.tidalPhase }}
        </p>
      </div>
    </div>
  `
})
export class ImageListComponent {
  images: ImageMetadata[] = [];
  
  getRelativeTime = getRelativeTime;
}

🔧 Backend Usage (Node.js)

API Response Formatting

import { ApiResponse, ImageUploadResponse } from '@mhaines/photo-weather-shared';

export function createSuccessResponse<T>(data: T, message: string): ApiResponse<T> {
  return {
    success: true,
    data,
    message
  };
}

export function createErrorResponse(error: string, message: string): ApiResponse {
  return {
    success: false,
    error,
    message
  };
}

Validation

import { validateCoordinates, isValidWeatherDate } from '@mhaines/photo-weather-shared';

export function validateWeatherRequest(lat: number, lon: number, date: Date) {
  const coordValidation = validateCoordinates(lat, lon);
  if (!coordValidation.isValid) {
    throw new Error(coordValidation.errors.join(', '));
  }
  
  if (!isValidWeatherDate(date)) {
    throw new Error('Invalid date for weather data');
  }
}

🔄 Development Workflow

Making Changes

1. Update types/constants/utilities in this package
2. Build and publish new version
3. Update both backend and frontend projects
4. Ensures consistency across projects

Publishing

npm run build
npm version patch  # or minor/major
npm publish

Updating Projects

# In backend project
npm update @mhaines/photo-weather-shared

# In frontend project  
npm update @mhaines/photo-weather-shared

📝 Type Safety Benefits

• Consistent APIs: Same types across backend and frontend
• Compile-time Validation: Catch mismatches early
• IntelliSense Support: Better developer experience
• Refactoring Safety: Changes propagate across projects
• Documentation: Types serve as living documentation

🎯 Best Practices

1. Version Carefully: Breaking changes require major version bump
2. Document Changes: Update README for new features
3. Test Thoroughly: Validate in both backend and frontend
4. Keep Focused: Only shared code belongs here
5. Semantic Versioning: Follow semver for predictable updates

Shared package ensures type safety and consistency across your Photo-to-DB ecosystem! 🚀