lichess-org / api

Lichess API documentation and examples
https://lichess.org/api
GNU Affero General Public License v3.0
414 stars 140 forks source link

Fix incorrect types in GameJson.analysis #292

Closed LukFil closed 6 months ago

LukFil commented 7 months ago

Hi, I've noticed that the documentation of GameJson.analysis does not quite match what the docs say.

The docs say that in analysis array, an item must have a key 'eval', that is number. Playing around with parsing the responses, I found that the behaviour is different: it seems that there is either 'eval' or 'mate', but never both. This is how I best would express it in Typescript:

type Judgment = {
  name: string;
  comment: string;
};

type BaseChessAnalysisItem = {
  best?: string;
  variation?: string;
  judgment?: Judgment;
};

type EvalAnalysisItem = BaseChessAnalysisItem & {
  eval: number;
  mate?: never; 
};

type MateAnalysisItem = BaseChessAnalysisItem & {
  mate: number;
  eval?: never; 
};

type AnalysisItem = EvalAnalysisItem | MateAnalysisItem;

type Analysis = AnalysisItem[];

I also went into lila source, code, and I believe that the appropriate code is in here, lines 12-35. Now, I am no scala wizard, but I am not certain it actually enforces here that either 'mate' or 'eval' but never both exist, so in my change I have simply removed 'eval' from the required array, and added 'mate' as another optional field.

If preferred, I am happy to implement it in the way to match the typescript description I provided.

Hope this is helpful, Lukas