@use 'sass:map';
@use 'sass:meta';
@use 'sass:list';
@use '../variables/maps' as smth;

/// Takes a potential alias for a keyword value and returns the corresponding
/// keyword based on an alias resolution map.
///
/// @param {String} $alias - The shortcut or alias used for the keyword.
/// @param {Map} $alias-map [smth.$direction-resolution-map] - The map of
/// keywords as keys with lists of their aliases as values.
///
/// @return {String | Null} Returns the parameter keyword string if the given
/// alias is found in the alias map, otherwise returns `null`.
///
/// @access public
/// @group Utilities
/// @require {variable} $map-alias-resolutions
///
/// @throw Invalid $alias data type.
/// @throw Invalid $alias-map data type.
@function resolve-alias($alias, $alias-map: smth.$map-alias-resolutions) {
  @if meta.type-of($alias) != 'string' {
    @error 'Invalid data type of [ #{meta.type-of($alias)} ] for $alias ' +
        'passed to the [ resolve-alias() ] function. The data type of $alias must ' +
        'be a string.';
  }

  @if meta.type-of($alias-map) != 'map' {
    @error 'Invalid data type of [ #{meta.type-of($alias-map)} ] for ' +
        '$alias-map passed to the [ resolve-alias() ] function. The data type ' +
        'of $alias-map must be a map.';
  }

  @each $key in map.keys($alias-map) {
    $aliases: map.get($alias-map, $key);

    @if list.index($aliases, $alias) {
      @return $key;
    }
  }

  @return null;
}