chore: introduces @tabulous/types and @tabulous/game-utils (#168)

- fix(web): die do not display the same face in multiplayer (states are correct).
- chore: introduces @tabulous/types and @tabulous/game-utils.

TODO.md

@@ -14,7 +14,6 @@
 
 ## UI
 
-- bug: die do not display the same face in multiplayer (states are correct)
 - when hovering target, highlight should have the dragged mesh's shape, not the target shape (what about parts?)
 - hand count on peer pointers/player tab?
 - score (Mah-jong, Belote)

apps/cli/jsconfig.json

@@ -1,4 +1,11 @@
 {
   "extends": "../../jsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["src/*"],
+      "@tabulous/server/*": ["../server/src/*"]
+    }
+  },
   "include": ["src/**/*.js", "tests/**/*.js"]
 }

apps/cli/package.json

@@ -13,7 +13,6 @@
     "typecheck": "tsc -p jsconfig.json --noEmit"
   },
   "dependencies": {
-    "@tabulous/cli": "workspace:^",
     "@urql/core": "^4.1.2",
     "add": "^2.0.6",
     "ajv": "^8.12.0",
@@ -29,6 +28,7 @@
     "undici": "^5.24.0"
   },
   "devDependencies": {
+    "@tabulous/types": "workspace:*",
     "strip-ansi": "^7.1.0"
   }
 }

apps/cli/src/commands/add-player.js

@@ -1,6 +1,4 @@
 // @ts-check
-/** @typedef {import('@tabulous/server/src/graphql').Player} Player */
-
 import { gql } from '@urql/core'
 import chalkTemplate from 'chalk-template'
 import kebabCase from 'lodash.kebabcase'
@@ -18,7 +16,7 @@ import { commonOptions } from './help.js'
 
 /**
  * @typedef {object} AddPlayerResult player addition command result
- * @property {Player} player - added player.
+ * @property {import('@tabulous/types').Player} player - added player.
  */
 
 const addPlayerMutation = gql`
@@ -33,7 +31,7 @@ const addPlayerMutation = gql`
 /**
  * Triggers player addition command
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<AddPlayerResult|string>} the added player (or help message).
+ * @returns the added player (or help message).
  */
 export default async function addPlayerCommand(argv) {
   const args = parseArgv(argv, {
@@ -57,7 +55,7 @@ export default async function addPlayerCommand(argv) {
 /**
  * Adds a new player account.
  * @param {AddPlayerArgs} args - creation arguments.
- * @returns {Promise<AddPlayerResult>} the added player.
+ * @returns the added player.
  */
 export async function addPlayer({ username, password }) {
   const { addPlayer: player } = await getGraphQLClient().mutation(
@@ -72,12 +70,7 @@ export async function addPlayer({ username, password }) {
   return attachFormater({ player }, formatPlayer)
 }
 
-/**
- *
- * @param {AddPlayerResult} result
- * @returns {string}
- */
-function formatPlayer({ player }) {
+function formatPlayer(/** @type {AddPlayerResult} */ { player }) {
   return chalkTemplate`player {bold ${player.username}} added with id {bold ${player.id}}`
 }
 

apps/cli/src/commands/catalog.js

@@ -1,6 +1,4 @@
 // @ts-check
-/** @typedef {import('@tabulous/server/src/graphql').CatalogItem} CatalogItem */
-
 import { gql } from '@urql/core'
 import chalkTemplate from 'chalk-template'
 
@@ -49,7 +47,7 @@ const listCatalogQuery = gql`
 /**
  * Triggers catalog command
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<CatalogResult|string>} this user catalog of accessible games (or help message).
+ * @returns this user catalog of accessible games (or help message).
  */
 export default async function catalogCommand(argv) {
   const args = parseArgv(argv, {
@@ -71,11 +69,11 @@ export default async function catalogCommand(argv) {
 /**
  * List all available games of a given user.
  * @param {CatalogArgs} args - catalog arguments.
- * @returns {Promise<CatalogResult>} this user catalog of accessible games.
+ * @returns this user catalog of accessible games.
  */
 export async function catalog({ username }) {
   const { id } = await findUser(username)
-  /** @type {{ listCatalog: CatalogItem[] }} */
+  /** @type {{ listCatalog: import('@tabulous/server/graphql').CatalogItem[] }} */
   const { listCatalog: catalog } = await getGraphQLClient().query(
     listCatalogQuery,
     signToken(id)
@@ -95,18 +93,14 @@ export async function catalog({ username }) {
 }
 
 /**
- * @param {CatalogItem} descriptor
- * @returns {string} the descriptor localized name.
+ * @param {import('@tabulous/server/graphql').CatalogItem} descriptor
+ * @returns the descriptor localized name.
  */
 function getLocaleName({ name, locales }) {
   return locales?.fr?.title ?? name
 }
 
-/**
- * @param {CatalogResult} result
- * @returns {string} formatted result
- */
-function formatCatalog({ games }) {
+function formatCatalog(/** @type {CatalogResult} */ { games }) {
   const output = []
   for (const { name, title, copyright } of games) {
     output.push(

apps/cli/src/commands/configure-loggers.js

@@ -1,6 +1,4 @@
 // @ts-check
-/** @typedef {import('@tabulous/server/src/graphql').LoggerLevel} LoggerLevel */
-
 import { gql } from '@urql/core'
 import chalkTemplate from 'chalk-template'
 
@@ -25,7 +23,7 @@ const configureLoggersMutation = gql`
 /**
  * Triggers logger configuration command
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<LoggerLevel[]|string>} the configured loggers (or help message).
+ * @returns the configured loggers (or help message).
  */
 export default async function configureLoggerCommand(argv) {
   const args = parseArgv(argv, {
@@ -44,7 +42,7 @@ export default async function configureLoggerCommand(argv) {
 
 /**
  * @param {string} input - input string containing levels.
- * @returns {LoggerLevel[]} parsed logger levels.
+ * @returns parsed logger levels.
  * @throws {Error} when the input string is not compliant.
  */
 function parseLevels(input) {
@@ -53,7 +51,7 @@ function parseLevels(input) {
     if (!name || !level) {
       throw new Error(`misformated levels: "${input}"`)
     }
-    return { name, level: /** @type {LoggerLevel['level']} */ (level) }
+    return { name, level }
   })
 }
 
@@ -65,8 +63,8 @@ function parseLevels(input) {
 
 /**
  * Configures logger levels.
- * @param {{ levels: LoggerLevel[] }} args - configuration arguments.
- * @returns {Promise<LoggerLevel[]>} the configured loggers.
+ * @param {{ levels: { name: string, level: string}[] }} args - configuration arguments.
+ * @returns the configured loggers.
  */
 export async function configureLevels({ levels }) {
   const { configureLoggerLevels: results } = await getGraphQLClient().mutation(
@@ -77,11 +75,7 @@ export async function configureLevels({ levels }) {
   return attachFormater(results, formatLogger)
 }
 
-/**
- * @param {LoggerLevel[]} levels
- * @returns {string} formatted results
- */
-function formatLogger(levels) {
+function formatLogger(/** @type {{ name: string, level: string }[]} */ levels) {
   return levels.map(({ name, level }) => `- ${name}: ${level}`).join('\n')
 }
 

apps/cli/src/commands/delete-game.js

@@ -1,6 +1,4 @@
 // @ts-check
-/** @typedef {import('@tabulous/server/src/graphql').Game} Game */
-
 import { gql } from '@urql/core'
 import chalkTemplate from 'chalk-template'
 
@@ -17,7 +15,7 @@ import { commonOptions } from './help.js'
 
 /**
  * @typedef {object} DeleteGameResult game deletion command result
- * @property {Game} game - deleted game.
+ * @property {import('@tabulous/types').Game} game - deleted game.
  */
 
 const deleteGameMutation = gql`
@@ -33,7 +31,7 @@ const deleteGameMutation = gql`
 /**
  * Triggers game deletion command
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<DeleteGameResult|string>} the deleted game (or help message).
+ * @returns the deleted game (or help message).
  */
 export default async function deleteGameCommand(argv) {
   const args = parseArgv(argv, {
@@ -57,15 +55,15 @@ export default async function deleteGameCommand(argv) {
 /**
  * Deletes an existing game.
  * @param {DeleteGameArgs} args - deletion arguments.
- * @returns {Promise<DeleteGameResult>} game deletion results.
+ * @returns game deletion results.
  */
 export async function deleteGame({ gameId }) {
   const { deleteGame: game } = await getGraphQLClient().mutation(
     deleteGameMutation,
     { gameId },
     signToken()
   )
-  return attachFormater({ game }, ({ game }) =>
+  return attachFormater({ game }, (/** @type {DeleteGameResult} */ { game }) =>
     game
       ? chalkTemplate`${formatGame(game)} {underline deleted}`
       : chalkTemplate`{underline no game} deleted`

apps/cli/src/commands/delete-player.js

@@ -1,6 +1,4 @@
 // @ts-check
-/** @typedef {import('@tabulous/server/src/graphql').Player} Player */
-
 import { gql } from '@urql/core'
 import chalkTemplate from 'chalk-template'
 
@@ -17,7 +15,7 @@ import { commonOptions } from './help.js'
 
 /**
  * @typedef {object} DeletePlayerResult player deletion command result
- * @property {Player} player - deleted player.
+ * @property {import('@tabulous/types').Player} player - deleted player.
  */
 
 const deletePlayerMutation = gql`
@@ -33,7 +31,7 @@ const deletePlayerMutation = gql`
 /**
  * Triggers player deletion command
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<DeletePlayerResult|string>} the deleted player (or help message).
+ * @returns the deleted player (or help message).
  */
 export default async function deletePlayerCommand(argv) {
   const args = parseArgv(argv, {
@@ -57,18 +55,20 @@ export default async function deletePlayerCommand(argv) {
 /**
  * Deletes an existing player account.
  * @param {DeletePlayerArgs} args - deletion arguments.
- * @returns {Promise<DeletePlayerResult>} player deletion results.
+ * @returns player deletion results.
  */
 export async function deletePlayer({ id }) {
   const { deletePlayer: player } = await getGraphQLClient().mutation(
     deletePlayerMutation,
     { id },
     signToken()
   )
-  return attachFormater({ player }, ({ player }) =>
-    player
-      ? chalkTemplate`${formatPlayer(player)} {underline deleted}`
-      : chalkTemplate`{underline no player} deleted`
+  return attachFormater(
+    { player },
+    (/** @type {DeletePlayerResult} */ { player }) =>
+      player
+        ? chalkTemplate`${formatPlayer(player)} {underline deleted}`
+        : chalkTemplate`{underline no player} deleted`
   )
 }
 

apps/cli/src/commands/grant.js

@@ -29,7 +29,7 @@ const grantAccessMutation = gql`
 /**
  * Triggers grant command.
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<GrantAccessResult|string>} whether the operation succeeded.
+ * @returns whether the operation succeeded.
  */
 export default async function grantCommand(argv) {
   const args = parseArgv(argv, {
@@ -56,7 +56,7 @@ export default async function grantCommand(argv) {
 /**
  * Grant a player access to a copyrighted game.
  * @param {GrantArgs} args - username and game name.
- * @returns {Promise<GrantAccessResult>} whether the operation succeeded.
+ * @returns whether the operation succeeded.
  */
 export async function grant({ username, gameName }) {
   const client = getGraphQLClient()
@@ -76,11 +76,7 @@ export async function grant({ username, gameName }) {
   )
 }
 
-/**
- * @param {GrantAccessResult} result
- * @returns {string} formatted result
- */
-function formatGrant({ grantAccess }) {
+function formatGrant(/** @type {GrantAccessResult} */ { grantAccess }) {
   return grantAccess
     ? chalkTemplate`🛣  access {green granted}\n`
     : chalkTemplate`🔶 {yellow no changes}\n`

apps/cli/src/commands/list-players.js

@@ -1,6 +1,4 @@
 // @ts-check
-/** @typedef {import('@tabulous/server/src/graphql').Player} Player */
-
 import { gql } from '@urql/core'
 import chalkTemplate from 'chalk-template'
 
@@ -18,7 +16,7 @@ import { commonOptions } from './help.js'
 /**
  * Triggers player list command.
  * @param {string[]} argv - array of parsed arguments (without executable and current file).
- * @returns {Promise<Player[]|string>} list of players or help message.
+ * @returns list of players or help message.
  */
 export default async function listPlayersCommand(argv) {
   const args = parseArgv(argv, commonArgSpec)
@@ -30,7 +28,7 @@ export default async function listPlayersCommand(argv) {
 
 /**
  * Fetches all pages of the player list
- * @returns {Promise<Player[]>} list of players.
+ * @returns list of players.
  */
 export async function listPlayers() {
   let from = 0
@@ -50,11 +48,10 @@ export async function listPlayers() {
   return attachFormater(players, formatPlayers)
 }
 
-/**
- * @param {number} from
- * @param {number} size
- */
-function makeListPlayersQuery(from, size) {
+function makeListPlayersQuery(
+  /** @type {number} */ from,
+  /** @type {number} */ size
+) {
   return gql`
     query listGamesQuery {
       listPlayers(from: ${from.toString()}, size: ${size.toString()}) {
@@ -71,11 +68,9 @@ function makeListPlayersQuery(from, size) {
   `
 }
 
-/**
- * @param {Player[]} players
- * @returns {string} - formatted result
- */
-function formatPlayers(players) {
+function formatPlayers(
+  /** @type {import('@tabulous/types').Player[]} */ players
+) {
   return players.map(player => `- ${formatPlayer(player)}`).join('\n')
 }