Discussion: response data that's awkward to work with

[shayypy]

What is the problem?

I recently encountered an issue when fetching the game summary of a game that had not yet started wherein many fields differed from their types in ways that just make for bad DX.

In particular, home_team_lineup and visitor_team_lineup were empty arrays rather than something like a record with missing keys (so one could check lineup.goalies rather than checking that lineup is not an array).

What is the solution?

At face value the solution is to just type the values as they may appear, but as mentioned this makes for a bad developer experience, so my proposal is for the library to convert these confusing types before returning them, kind of like it does with params:

async getGameSummary(gameId) {
    const config = this._getGameCenterConfig(gameId, 'gamesummary');
    const res = await axios.get(this._getEndpoint(this._gameCenterBaseUrl, config), this._axiosConfig);
    const data = res.data.GC.Gamesummary;
    if (Array.isArray(data.home_team_summary)) {
        data.home_team_summary = { goalies: [], players: [] };
    }
    if (Array.isArray(data.visitor_team_summary)) {
        data.visitor_team_summary = { goalies: [], players: [] };
    }
    return data;
}

Something like the above. I would also personally take this as an opportunity to unwrap all the responses so .GC.Gamesummary isn't necessary for the end user (as v2 since this would be breaking). But that's just me, and the modified response could of course be re-wrapped.

The problematic response in question

For posterity (and for my own reference), here's the parts of the response whose types differ (I'll be submitting a PR at some point to adapt for some of these that aren't mentioned above)

// AHL game 1026609, 1hr before game start
{
    "GC": {
        "Gamesummary": {
            "meta": {
                "game_length": "", // new key
                "htv_game_id": "1080747", // new key
                "flo_core_event_id": "12828410", // new key
                "flo_live_event_id": "136134", // new key
            },
            "periods": {
                // type `Periods` asserts that keys `1`, `2`, and `3` are all present (and ignores the existence of subsequent periods)
                "1": {"id":"1","short_name":"1","long_name":"1st","sort_order":"1","period_id":"1","length":"1200","mandatory":"1"}
            },
            "mvps": [null, null, null], // not typed as nullable
            "penalties": null, // not typed as nullable
            "goals": null, // not typed as nullable
            "goalies": null, // not typed as nullable
            "home_team_lineup": [], // not typed as array (see above)
            "visitor_team_lineup": [], // not typed as array (see above)
            "shotsByPeriod": {
                // `2` and `3` required (see `periods`)
                "visitor": {"1":0},
                "home": {"1":0}
            },
            "goalsByPeriod": {
                // `2` and `3` required (see `periods`)
                "visitor": {"1":0},
                "home": {"1":0}
            }
        }
    }
}