[feat] Add support for custom URL parameters percent encoding

[matejmolnar]

This PR is trying to solve issue #55

Changes

Introduce a new type PercentEncodedParameter which can be passed as Any in urlParameters: [String: Any]. The value of this parameter won't get encoded during the URLRequest creation.

[cejanen]

@matejmolnar I played with it for a bit and I would propose a bit difference solution. Custom string encoding similar like specific array encoding is edge case. In 99% cases user is ok with parameters [String: Any]. Therefore I would not push them to wrap always parameters into RequestURLParametersType. I would better go with similar approach like we have for ArrayParameter.
We can do CustomEncodingParameter with either string which will be encoded for URL automatically or allow already encoded values.
Code which may help (draft):

if let percentedEncoded = value as? PercentEncodedParameter {
            queryItems.append(
                URLQueryItem(
                    name: key,
                    value: percentedEncoded.value
                )
                .percentEncodedWithValue(string: percentedEncoded.value)
            )
            return queryItems
        }
    
extension URLQueryItem {
    func percentEncoded() -> URLQueryItem {
        /// addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) encode parameters following RFC 3986
        /// which we need to encode other special characters correctly.
        /// We then also encode "+" sign with its HTTP equivalent

        var newQueryItem = self
        newQueryItem.value = value?
            .addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)?
            .replacingOccurrences(of: "+", with: "%2B")

        return newQueryItem
    }
    
    func percentEncodedWithValue(string: String) -> URLQueryItem {
        var newQueryItem = self
        newQueryItem.value = string
        return newQueryItem
    }
}

public struct PercentEncodedParameter {
    let value: String
    
    public init(_ value: String) {
        self.value = value
    }
}

[gajddo00]

@cejanen Agree, the intention behind designing ArrayParameter as it is was to avoid publishing a new breaking change to the library and making it optional for the user at the same time. For context, this is the Requestable+Convenience query building implementation, I'm also adding an adjusted sample from CJs draft if it makes sense.

// MARK: Build Query Items
private extension Requestable {
  func buildQueryItems(urlParameters: [String: Any]) -> [URLQueryItem] { ... }

  func buildQueryItems(key: String, value: Any) -> [URLQueryItem] {
      switch value {
      case let parameter as ArrayParameter:
          return buildArrayParameter(key: key, parameter: parameter)
       case let parameter as PercentEncodedParameter:
           return buildPercentEncodedParameter(key: key, parameter: parameter)
       default:
           return [URLQueryItem(name: key, value: String(describing: value))]
      }
  }
  
   func buildArrayParameter(
        key: String,
        parameter: ArrayParameter
    ) -> [URLQueryItem] { ... }
    
    func buildPercentEncodedParameter(
        key: String,
        parameter: PercentEncodedParameter
    ) -> [URLQueryItem] {
        [URLQueryItem(name: key, value: parameter.percentEncodedValue)]
    }
}

public struct PercentEncodedParameter {
    let value: String

    public var percentEncodedValue: String? {
        value.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)?
            .replacingOccurrences(of: "+", with: "%2B")
    }

    public init(value: String) {
        self.value = value
    }
}

is 'order to give a user the flexibility to encode the parameters however they want' this meant as the user can decide which parameters should be percent encoded or use literally any type of encoding for any parameter? then we'd be solving a different problem

[matejmolnar]

@cejanen @gajddo00 Thank you for the suggestions 🙏, I agree that it's a better approach although I had to adjust it a little.

[gajddo00]

Looks good to me 👍

[cejanen]

I tested it and it doesn't work as expected. Will try to do updates. It wasn't very clear from my side.

tested URL params
page=1&test=1+1

[cejanen]

@gajddo00 @matejmolnar At the end I decided for simplest solution. By default are data encoded on URLComponent and you can pass custom encoded data which are expected like encoded already. All tests pass multiple times.

[matejmolnar]

I think we could just move this extension to the URLParametersTests file, since it's not being used anywhere else 🤔

[matejmolnar]

Suggested change

	/// ["specialCharacter": PercentEncodedParameter(">")]
	/// ["specialCharacter": CustomEncodedParameter(">")]

[gajddo00]

🍓 Agreed as in most cases custom encoding won't be necessary, we can elevate this to the user, why not.