Compatibility Management ❌ Internal API

/**
 * String in a valid semver format specifying bottom of a minor version or special "defaults" prerelease of a major
 */
type MinimumMinorSemanticVersion = `${bigint}.${bigint}.0` | `${bigint}.0.0-defaults`;

/**
 * String in a valid semver format of a specific version at least specifying minor
 */
type SemanticVersion = `${bigint}.${bigint}.${bigint}` | `${bigint}.${bigint}.${bigint}-${string}`;

/**
 * Generic type for runtimeOptionsAffectingDocSchemaConfigMap
 */
type ConfigMap<T> = {
  [K in keyof T]-?: Record<MinimumMinorSemanticVersion, T[K]>;
};

/**
 * Generic type for runtimeOptionsAffectingDocSchemaConfigValidationMap  
 */
type ConfigValidationMap<T> = {
  [K in keyof T]-?: (configValue: T[K]) => SemanticVersion | undefined;
};

/**
 * Checks if the minVersionForCollab is valid (at least lowestMinVersionForCollab and less than or equal to current package version)
 * @param minVersionForCollab - The minimum version to validate
 * @returns True if the version is valid for collaboration
 */
function isValidMinVersionForCollab(minVersionForCollab: MinimumVersionForCollab): boolean;

/**
 * Returns a default configuration given minVersionForCollab and configuration version map
 * @param minVersionForCollab - The minimum version for collaboration
 * @param configMap - Map of versions to configuration values
 * @returns Partial configuration object appropriate for the version
 */
function getConfigsForMinVersionForCollab<T extends Record<SemanticVersion, unknown>>(
  minVersionForCollab: SemanticVersion,
  configMap: ConfigMap<T>
): Partial<T>;

/**
 * Generic function to validate runtime options against the minVersionForCollab
 * @param minVersionForCollab - The minimum version for collaboration
 * @param runtimeOptions - The runtime options to validate
 * @param validationMap - Map of validation functions for each option
 * @throws Error if any runtime option is incompatible with the minimum version
 */
function getValidationForRuntimeOptions<T extends Record<string, unknown>>(
  minVersionForCollab: SemanticVersion,
  runtimeOptions: Partial<T>,
  validationMap: ConfigValidationMap<T>
): void;

/**
 * Helper function to map ContainerRuntimeOptionsInternal config values to minVersionForCollab
 * @param configToMinVer - Array of tuples mapping config values to minimum versions
 * @returns Function that maps a config value to its minimum required version
 */
function configValueToMinVersionForCollab<
  T extends string | number | boolean | undefined | object,
  Arr extends readonly [T, SemanticVersion][]
>(
  configToMinVer: Arr
): (configValue: T) => SemanticVersion | undefined;

/**
 * Default minimum version for collaboration when unspecified by user
 */
const defaultMinVersionForCollab: "2.0.0-defaults";

// ❌ These imports will NOT work - APIs are internal
// import { 
//   isValidMinVersionForCollab,
//   getConfigsForMinVersionForCollab,
//   getValidationForRuntimeOptions,
//   configValueToMinVersionForCollab,
//   defaultMinVersionForCollab,
//   type SemanticVersion,
//   type ConfigMap
// } from "@fluidframework/runtime-utils";

// Version validation
const minVersion = "2.5.0" as SemanticVersion;
if (isValidMinVersionForCollab(minVersion)) {
  console.log("Version is valid for collaboration");
} else {
  console.error("Version is not compatible");
}

// Configuration management based on version
interface RuntimeConfig {
  enableFeatureX: boolean;
  compressionLevel: number;
  gcEnabled: boolean;
}

const versionConfigMap: ConfigMap<RuntimeConfig> = {
  enableFeatureX: {
    "2.0.0": false,
    "2.5.0": true,
    "3.0.0": true
  },
  compressionLevel: {
    "2.0.0": 1,
    "2.3.0": 2,
    "2.8.0": 3
  },
  gcEnabled: {
    "2.0.0": false,
    "2.10.0": true
  }
};

const config = getConfigsForMinVersionForCollab("2.5.0", versionConfigMap);
console.log(config); // { enableFeatureX: true, compressionLevel: 2, gcEnabled: false }

// Runtime options validation
const compressionLevelValidator = configValueToMinVersionForCollab([
  [1, "2.0.0"],
  [2, "2.3.0"], 
  [3, "2.8.0"]
] as const);

const gcEnabledValidator = configValueToMinVersionForCollab([
  [false, "2.0.0"],
  [true, "2.10.0"]
] as const);

const validationMap = {
  compressionLevel: compressionLevelValidator,
  gcEnabled: gcEnabledValidator
};

const runtimeOptions = {
  compressionLevel: 3,
  gcEnabled: true
};

try {
  getValidationForRuntimeOptions("2.5.0", runtimeOptions, validationMap);
  console.log("Runtime options are valid");
} catch (error) {
  console.error("Runtime options validation failed:", error.message);
}

// Using default minimum version
const defaultConfig = getConfigsForMinVersionForCollab(
  defaultMinVersionForCollab,
  versionConfigMap
);

// Feature flag management based on versions
class FeatureFlagManager {
  private readonly featureConfigMap: ConfigMap<FeatureFlags>;
  
  constructor() {
    this.featureConfigMap = {
      newSummaryFormat: {
        "2.0.0-defaults": false,
        "2.8.0": true
      },
      advancedGC: {
        "2.0.0-defaults": false,
        "2.12.0": true
      },
      compression: {
        "2.0.0-defaults": false,
        "2.5.0": true
      }
    };
  }
  
  getFeatureFlags(minVersion: SemanticVersion): FeatureFlags {
    return getConfigsForMinVersionForCollab(minVersion, this.featureConfigMap);
  }
  
  isFeatureEnabled(
    feature: keyof FeatureFlags,
    minVersion: SemanticVersion
  ): boolean {
    const flags = this.getFeatureFlags(minVersion);
    return flags[feature] ?? false;
  }
}

// Runtime options validator factory
function createRuntimeOptionsValidator<T extends Record<string, unknown>>(
  validationRules: ConfigValidationMap<T>
) {
  return (options: Partial<T>, minVersion: SemanticVersion): void => {
    getValidationForRuntimeOptions(minVersion, options, validationRules);
  };
}

// Comprehensive runtime options validation
const runtimeOptionsValidator = createRuntimeOptionsValidator({
  summaryFormat: configValueToMinVersionForCollab([
    ["legacy", "2.0.0-defaults"],
    ["optimized", "2.8.0"],
    ["compressed", "2.12.0"]
  ] as const),
  
  gcMode: configValueToMinVersionForCollab([
    ["disabled", "2.0.0-defaults"],
    ["mark-and-sweep", "2.10.0"],
    ["incremental", "2.15.0"]
  ] as const),
  
  compressionAlgorithm: configValueToMinVersionForCollab([
    ["none", "2.0.0-defaults"],
    ["gzip", "2.5.0"],
    ["lz4", "2.8.0"]
  ] as const)
});

// Version-aware container setup
function setupContainer(
  minVersionForCollab: SemanticVersion = defaultMinVersionForCollab
): ContainerConfiguration {
  // Validate the version first
  if (!isValidMinVersionForCollab(minVersionForCollab)) {
    throw new Error(`Invalid minimum version for collaboration: ${minVersionForCollab}`);
  }
  
  // Get version-appropriate configuration
  const baseConfig = getConfigsForMinVersionForCollab(
    minVersionForCollab,
    defaultConfigMap
  );
  
  // Apply any custom runtime options with validation
  const runtimeOptions = {
    summaryFormat: "optimized",
    gcMode: "mark-and-sweep",
    compressionAlgorithm: "gzip"
  };
  
  runtimeOptionsValidator(runtimeOptions, minVersionForCollab);
  
  return {
    ...baseConfig,
    runtimeOptions,
    minVersionForCollab
  };
}

// Migration helper for version upgrades
class VersionMigrationManager {
  async migrateToVersion(
    currentVersion: SemanticVersion,
    targetVersion: SemanticVersion,
    container: IContainer
  ): Promise<void> {
    if (!isValidMinVersionForCollab(targetVersion)) {
      throw new Error(`Target version ${targetVersion} is not valid`);
    }
    
    // Get configurations for both versions
    const currentConfig = getConfigsForMinVersionForCollab(
      currentVersion, 
      migrationConfigMap
    );
    const targetConfig = getConfigsForMinVersionForCollab(
      targetVersion,
      migrationConfigMap
    );
    
    // Apply migrations for each changed setting
    await this.applyConfigurationMigrations(
      container,
      currentConfig,
      targetConfig
    );
  }
}