There's been lots of updates to Hyper this month, including not one but two breaking changes! (Trying to stick to semver here, even when the breaking changes seem minor.)

New Documentation Site

Perhaps the most exciting news, Hyper has a new home for documentation! We outgrew using just a README a while ago and now we finally have a brand new home for Hyper. This will make finding the documentation you need even easier.

Next to the headline new features:

asXML support

Hyper now has built-in support for dealing with XML apis using the asXML helper method.

head and options shortcut methods

Need to make head or options? Now you can do it without having to call setMethod first.

More Accurate Status Codes

Hyper now returns more accurate status codes for 502 Bad Gateway and 408 Request Timeout responses. Previously, these responses were returned as 504 Gateway Timeout responses. Hyper now normalizes the responses from the different CFML engines into a consistent response. 502 Bad Gateway is returned instead of 504 Gateway Timeout for invalid hosts. 408 Request Timeout is returned if the request takes longer than the configured timeout value.

Easier Custom Hyper Clients

It is now more straightforward to register a custom Hyper client. Inside your config/WireBox.cfc in an afterAspectsLoad method, you can get a reference to a HyperBuilder, configure it as you would for a request, and then call the registerAs method passing in your desired WireBox alias.

// config/WireBox.cfc
component {

   // ...
   
   function afterApsectsLoad() {
       injector.getInstance( "HyperBuilder@hyper" )
           .setBaseUrl( "https://api.github.com" )
           .asJson()
           .withHeaders( {
               "Authorization": coldbox.getUtil().getSystemSetting( "GITHUB_TOKEN" )
           } )
           .registerAs( "GitHubClient" );
   }

}

This is a welcome improvement as the init arguments do not exactly match the method names. Also, for defaults like requestCallbacks, responseCallbacks, or even queryParams, passing in arrays of functions or arrays or structs is not as straightforward as calling the related methods. Now, you can use the Hyper methods you are familiar with when registering your custom Hyper clients.

Faking Requests

We kind of buried the lead here, but Hyper now ships with the ability to fake requests for testing.

Here's a quick example:

hyper.fake( {
    "https://google.com/*": function( newFakeResponse, req ) {
         return newFakeResponse( 404, "Not Found" );
    }
} );

var resA = hyper.get( "https://google.com" );
expect( resA.getStatus() ).toBe( "404 Not Found" );

var resB = hyper.get( "https://does-not-exist.also-does-not-exist" );
expect( resB.getStatus() ).toBe( "200 OK" );

There's a lot to love here, so make sure to give the documentation a visit.

We hope you love these updates to Hyper! Happy HTTP'ing!