Shared Type Bindings

This document describes the shared type bindings between the TypeScript frontend and Python backend to ensure type safety and prevent runtime errors.

ProfileName Enum

Profile names are defined as enums in both languages to prevent case-sensitivity bugs and typos.

TypeScript (Frontend)

Location: frontend/src/types/index.ts

export enum ProfileName {
  Quiet = 'Quiet',
  Balanced = 'Balanced',
  Default = 'Default',
  Performance = 'Performance',
}

Usage:

import { ProfileName } from './types';

// Type-safe profile references
const preset = ProfileName.Balanced;

// Use in comparisons
if (profile.name === ProfileName.Quiet) {
  // ...
}

// Iterate all profiles
Object.values(ProfileName).forEach(name => {
  console.log(name); // 'Quiet', 'Balanced', 'Default', 'Performance'
});

Python (Backend)

Location: backend/nvidia_oc/config/enums.py

from enum import Enum

class ProfileName(str, Enum):
    """Standard profile names matching frontend TypeScript enum."""

    QUIET = "Quiet"
    BALANCED = "Balanced"
    DEFAULT = "Default"
    PERFORMANCE = "Performance"

Usage:

from nvidia_oc.config import ProfileName

# Type-safe profile references
preset = ProfileName.BALANCED

# Use in comparisons
if profile_name == ProfileName.QUIET:
    # ...

# Iterate all profiles
for name in ProfileName:
    print(name.value)  # "Quiet", "Balanced", "Default", "Performance"

Maintaining Consistency

When adding new profiles:

Add to both enums in the same order
Match the casing exactly (e.g., "Balanced" not "balanced")
Update YAML files to use matching names
Run tests to verify both frontend and backend work

Example: Adding a New Profile

Step 1: Add to TypeScript enum

export enum ProfileName {
  Quiet = 'Quiet',
  Balanced = 'Balanced',
  Default = 'Default',
  Performance = 'Performance',
  Extreme = 'Extreme',  // NEW
}

Step 2: Add to Python enum

class ProfileName(str, Enum):
    QUIET = "Quiet"
    BALANCED = "Balanced"
    DEFAULT = "Default"
    PERFORMANCE = "Performance"
    EXTREME = "Extreme"  # NEW

Step 3: Create YAML file

# backend/profiles/extreme.yaml
name: Extreme
description: Maximum overclock for benchmarking
core_offset: 200
memory_offset: 1000
power_limit: 110

Step 4: Add to defaults

# backend/nvidia_oc/config/defaults.py
DEFAULT_PROFILES: Dict[str, str] = {
    ProfileName.QUIET: "../../../configs/quiet.yaml",
    ProfileName.BALANCED: "../../../configs/balanced.yaml",
    ProfileName.PERFORMANCE: "../../../configs/performance.yaml",
    ProfileName.DEFAULT: "../../../configs/default.yaml",
    ProfileName.EXTREME: "../../../configs/extreme.yaml",  # NEW
}

Benefits

✅ Type safety: TypeScript and Python catch typos at compile time
✅ Auto-completion: IDEs provide suggestions for valid profile names
✅ Refactoring: Renaming a profile updates all references automatically
✅ No case bugs: Prevents "Quiet" vs "quiet" mismatches
✅ Documentation: Enum serves as single source of truth

Testing

Verify consistency between frontend and backend:

# Check frontend enum
grep -A 5 "export enum ProfileName" frontend/src/types/index.ts

# Check backend enum
grep -A 5 "class ProfileName" backend/nvidia_oc/config/enums.py

# Verify API returns matching names
curl http://localhost:8000/api/profiles | jq '.[].name'

All profile names should match exactly across all three locations.

3.5 KiB Raw Permalink Blame History