What is the type of “props.moves” in the React client's board?

[jakehsiao]

I know the type of "props.G" is defined by the project, and "props.ctx" is "Ctx", but what is the type of "props.moves"?

export function Board(props: {G: IGame, ctx: Ctx, moves: any}) { ... }

Currently I am using "any" but this is not a safe way at all.

Also, it's quite appreciated to add some examples and documentations on using boardgame.io with typescript.

[delucis]

Here's a small example using Typescript, but yes proper TS documentation is still needed.

We don't have strongly typed moves, although it might be theoretically possible to compute them from a game definition, so for now moves is

type moves = Record<
  string,
  (...args: any[]) => void
>;

If you follow the example linked above though you shouldn't have to type this manually. If you specifically need the moves type you can use BoardProps['moves'].

[jakehsiao]

@delucis Thanks, this demo is quite helpful. Maybe it's impossible for typescript now to give a 100% type check.

[delucis]

@jakehsiao It’s tricky. If you declare your game as const game = { ... } as const, in theory Typescript can read all the moves keys and iterate over them to produce the type of props.moves (here’s an experimental implementation). However, then you have to type everything in the game definition manually. If you use the Game type (or other types like Move), like const game: Game = { ... }, then Typescript can’t parse specific moves any more as it just sees the generic Game type.

I’m not sure the trade-off of typing everything manually is worth it, even though having auto-completion and type safety on the client would be nice.

[drmercer]

@delucis I believe one way to get the best of both worlds (detailed type information + automatic type checking) would be to use an identity function with a generic type signature, like so:

function defineGame<Gm extends Game>(game: Gm): Gm {
  return game;
}

// example usage - MyGame will have detailed type information while ensuring it complies with the Game type.
const MyGame = defineGame({
  moves: {
    ...
  },
});

Then you could use the experimental type linked in your answer to get the type of client.moves based on the type of MyGame.

Vue uses this pattern for similar reasons with their defineComponent function - see here.

[delucis]

Interesting idea. Funnily enough, there used to be a Game() wrapper function you had to pass your game object to. Now it just gets called internally to simplify the public API.

I’m a bit hesitant about adding things like this only for typing purposes, and this also only partially solves the issue. It’s fairly rare to write out the full game definition in a single object literal — usually moves get broken into separate functions, bits of config get broken up for re-use in various scenarios, etc. I guess you could still extend this logic and have defineMove, defineTurn, define… helpers etc., although this does add quite a bit of boilerplate.

One other stumbling point is you still need to assert as const:

const game = defineGame({ moves: {} } as const);

Also this makes it tricky to type G because of microsoft/TypeScript#26242. Currently, you can type your game as Game<G> and it will type check your G in moves and elsewhere. However, because currently there’s no support for inferring only some of the type arguments, we’d need a workaround like:

function defineGame<G extends any = any>() {
  return function <Gm extends Game<G>>(game: Gm): Gm {
    return game;
  }
}

interface MyGameState {
  score: number;
}

export const MyGame = defineGame<MyGameState>()({ moves: {} } as const);

TS Playground ↗︎

Works! But is I think maybe more confusing than anything? Admittedly, this could partially be a userland thing. If we expect games to extend Game as we currently do, it wouldn’t matter if you used an object that is just Game or something like the above returns. So these helpers could be applied only by people who really want them. That would potentially allow us to integrate the client types and have them only kick in if the provided game type allowed it.

If you fancy playing around with any of this, I’d be happy to take a look or answer questions.

[drmercer]

One other stumbling point is you still need to assert as const:

As far as I can tell, as const isn't necessary here, unless your object includes arrays you want treated as tuples or primitives you want typed as literals. All it does for objects themselves is make the properties readonly. (See the release notes for as const.) In my testing, defineGame works fine without it.

Also this makes it tricky to type G

Agreed, that is an unfortunate downside. I tried typing G by specifying a return type on the setup function (see below), but it doesn't work unless I also specify that type on the g param in the move functions. Vue manages to solve a similar problem somehow (the props param to their setup function is typed automagically based on the props options field). I wonder how to accomplish the same thing here. 🤔

interface MyState {
  myStateProp: string;
}

export const MyGame = declareGame({
  setup(): MyState {
    return {
      myStateProp: 'hi',
    };
  },
  minPlayers: 2,
  moves: {
    myMove(g: MyState, ctx, arg1: string) {
      console.log(g.myStateProp);
    },
  },
});

I'll play around with this with the game I'm building and see if I can figure anything out.

[delucis]

Cleaned up the example linked above so it works with strict type checks and incorporated the curried defineGame function. You can try it out on TS Playground.