@slugbugblue/trax 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @slugbugblue/trax
 
+## 0.23.0 - 2023-03-28
+
+Release candidate
+
+Finalize work with jsdoc/typescript
+
 ## 0.22.0 - 2023-03-25
 
 - Pull point.js into its own package: `@slugbugblue/point`
@@ -28,7 +34,7 @@
 - Drop support for node 14; node v16.15 is our minimum supported version
 - More puzzles from Martin M. S. Pedersen -- bringing the total to 100+
 - Enhance the docker configuration and document it in the README
-- Refine faulty threat detection and add test for once case it was failing
+- Refine faulty threat detection and add test for one case it was failing
 
 ## 0.19.0 - 2023-02-06
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Trax game engine",
   "keywords": [
     "trax",

package/src/engine.js

@@ -1,20 +1,9 @@
-/* Copyright 2019-2022 Chad Transtrum
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+/** Trax engine.
+ * @copyright 2019-2022
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// Trax internals. Woot.
-
 import { Point } from '@slugbugblue/point'
 
 // Fun trax helper constants
@@ -36,7 +25,9 @@ const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
  * */
 const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
 
-/** Slashes are represented by / \ or +.
+/** Slashes indicate the direction the tile is placed. A forward slash or a
+ * backslash indicate the tile is a "curve" and the plus sign indicates the
+ * tile is a "straight".
  * @readonly
  * @type {Record<ValidTiles, Slash>}
  */
@@ -197,10 +188,10 @@ export class Trax {
   // Trax class constructor
   /** Create a new Trax game
    * @arg {TraxVariant} [rules='trax'] - the variant to play
-   * @arg {string|string[]} [moves=[]] - the initial moves to pre-play
+   * @arg {string|string[]} [moves=''] - the initial moves to pre-play
    * @arg {string} [id='trax'] - an id used to differentiate tiles from multiple games
    */
-  constructor(rules = 'trax', moves = [], id = 'trax') {
+  constructor(rules = 'trax', moves = '', id = 'trax') {
     if (!Trax.variants.has(rules)) rules = 'trax'
     this.id = String(id)
     this.rules = rules
@@ -311,6 +302,7 @@ export class Trax {
    */
   addTile(type, loc) {
     const id = this.tileId(loc)
+    /** @type {Tile} */
     const tile = { type, loc, id, move: this.move, seq: this.count }
     if (type === 'x') {
       this.invalid = true // Invalid tile is being played
@@ -334,7 +326,7 @@ export class Trax {
   }
 
   /** Is this tile valid?
-   * @type {(type: string, loc: Point) => type is TileType}
+   * @type {(type: string, loc: Point) => type is ValidTiles}
    */
   validTile(type, loc) {
     if (this.count === 0 && loc.x === 0 && loc.y === 0) {
@@ -377,6 +369,10 @@ export class Trax {
     return this.right - this.left + 1
   }
 
+  /** Determine if a location is valid to play in.
+   * @arg {Point} loc - the location to check
+   * @returns {boolean}
+   */
   validLocation(loc) {
     if (this.over) return false
     if (this.tileAt(loc)) return false
@@ -398,26 +394,31 @@ export class Trax {
     return false
   }
 
+  /** Find all possible locations to play in. Note that these are not
+   * necessarily valid locations, just empty ones that border existing tiles.
+   */
   possibleLocations() {
     if (this.count === 0) return [zero]
     /** @type Record<TileId, Point> */
     const possibles = {}
 
     for (const tile of Object.values(this.tiles)) {
-      tile.loc.around.map((loc) => {
+      for (const loc of tile.loc.around) {
         const id = this.tileId(loc)
         if (!(id in this.tiles)) possibles[id] = loc
-        return loc
-      })
+      }
     }
 
-    // Get rid of all the real tiles and return all the maybes
     return Object.values(possibles)
   }
 
+  /** Find all possible moves as a list of notations,
+   * ie: ['@1+', '@1/', '@1\\', ...]
+   *
+   * Note that moves are not guaranteed to be valid.
+   */
   possibleMoves() {
-    // Returns a list of every currently possible move
-    // as notations, ie ['@1+', '@1/', '@1\\', ...]
+    /** @type {string[]} */
     const possibles = []
     if (this.over) return possibles // Shortcut if the game is over
     for (const loc of this.possibleLocations()) {
@@ -430,9 +431,14 @@ export class Trax {
     return possibles
   }
 
+  /** Called after a move was just played, to determine the forced moves.
+   * @arg {Point} loc - the location just played at
+   * @returns {Tile[]} a list of tiles that should be added as part of the move
+   */
   forcedMoves(loc) {
-    // We just played at loc, so return all forced moves
+    /** @type {Tile[]} */
     const forced = []
+    /** @type {Record<string, boolean>} */
     const invalids = {}
     let check = loc.around
     while (check.length > 0) {
@@ -455,16 +461,26 @@ export class Trax {
     return forced
   }
 
+  /** Determine the notation for a move. Note that this must be determined
+   * BEFORE the move is placed on the board.
+   * @arg {ValidTiles} type - the tile placed on the board
+   * @arg {Point} loc - the location the tile is placed
+   * @returns {string} the notation of the move
+   */
   notate(type, loc) {
-    // Notation depends on the position of the board BEFORE the move
     let notation = Trax.encodeCol(loc.x - this.left + 1)
     notation += String(loc.y - this.top + 1)
     notation += slash[type]
     return notation
   }
 
+  /** Turn a move notation into a tile type and location.
+   * @arg {string} notation - a notation for a single move to be played at
+   * the current board position
+   * @returns {RawMove} the tile type and location of the move
+   */
   decodeNotation(notation) {
-    // Return {type, loc} from a notation
+    /** @type {RawMove} */
     const bad = { type: 'x', loc: zero }
     const match = notation.match(notationRegex)
     if (match === null) return bad
@@ -477,6 +493,14 @@ export class Trax {
     return bad
   }
 
+  /** Follow a color from one location through one or more tiles to the other
+   * end of the color line.
+   * @arg {Color} color - the color to follow
+   * @arg {Point} loc - the location to start
+   * @arg {string} from - the edge of the tile to start from
+   * @returns {LineEnd} the ending location and a list of the tile ids the path
+   * takes to get there.
+   */
   follow(color, loc, from) {
     const path = []
     let id = this.tileId(loc)
@@ -504,7 +528,13 @@ export class Trax {
     return { loc, path }
   }
 
+  /** Given a tile and a color, follow the line for that color to each end.
+   * @arg {Color} color - the color of ends of interest
+   * @arg { Point} loc - the location of the tile of interest
+   * @returns {LineEnd[]} a list of two items, each one end of the line
+   */
   findEnds(color, loc) {
+    /** @type {LineEnd[]} */
     const ends = []
     const tile = this.tileAt(loc)
     if (upColor(tile) === color) ends.push(this.follow(color, loc, 'top'))
@@ -514,6 +544,11 @@ export class Trax {
     return ends
   }
 
+  /** Determine if a given line ends the game.
+   * @arg {Point} locA - one end of the line
+   * @arg {Point} locB - the other end of the line
+   * @returns {boolean} - true if this line wins the game
+   */
   lineWin(locA, locB) {
     if (this.rules === 'traxloop') return false
     if (this.width > 7 && locA.distX(locB) > this.width) return true
@@ -521,6 +556,9 @@ export class Trax {
     return false
   }
 
+  /** Determine if the game has ended.
+   * @arg {Tile[]} tiles - a list of the tiles placed during the last move.
+   */
   checkWin(tiles) {
     /** @type {Color|false} */
     let winner = false
@@ -529,13 +567,13 @@ export class Trax {
       if (winner) continue // Skip the second player if the first has won
       for (const tile of tiles) {
         if (winner) continue // Skip the remaining tiles once we find a win
-        const ends = this.findEnds(color, tile.loc)
-        if (ends[0].loc.eq(ends[1].loc)) {
+        const [end1, end2] = this.findEnds(color, tile.loc)
+        if (end1.loc.eq(end2.loc)) {
           winner = color // Loop win
-          this.path = ends[0].path // Both paths are essentially the same
-        } else if (this.lineWin(ends[0].loc, ends[1].loc)) {
+          this.path = end1.path // Both paths are essentially the same
+        } else if (this.lineWin(end1.loc, end2.loc)) {
           winner = color // Line win, paths need to be combined
-          this.path = [...ends[0].path.reverse(), ...ends[1].path.slice(1)]
+          this.path = [...end1.path.reverse(), ...end2.path.slice(1)]
         }
       }
     }
@@ -576,6 +614,11 @@ export class Trax {
     return this.dropTile(notation)
   }
 
+  /** Play one or more moves.
+   * @arg {string|string[]} moves - the list of moves, provided either as a
+   * space-separated string of notations, or as a list of notations. Move
+   * numbers are optional, but if provided will be checked for accuracy.
+   */
   playMoves(moves) {
     // Play one or more moves, from a string or a list of moves
     // If move numbers are included, ensure they are accurate
@@ -603,6 +646,9 @@ export class Trax {
     }
   }
 
+  /** Add the current move notation to the notation string
+   * @arg {string} notation - the notation of the current move
+   */
   updateNotation(notation) {
     this.move++
     let note = this.move + '. ' + notation
@@ -623,7 +669,7 @@ export class Trax {
   }
 
   /** Drop a tile onto the board. This is a lower level call. Use play() if possible instead.
-   * @arg {string|TileType} type - a special move, a tile type, or a notation
+   * @arg {string|ValidTiles} type - a special move, a tile type, or a notation
    * @arg {Point} [loc] - a location if type is a tile type
    * @arg {string|boolean} [tentative] - if truthy, the move will not be saved
    * @returns {TileDrop} an object representing the results of the drop
@@ -673,6 +719,11 @@ export class Trax {
     return { dropped, notation, valid }
   }
 
+  /** Symmetry helper. Rotates a move around the board in case we are trying to
+   * play a symmetrical rather than an exact move.
+   * @arg {string} move - the notation of the move to be rotated
+   * @returns {string[]} the four rotations of this move
+   */
   moveRotations(move) {
     // Symmetry helper, rotate a move around the board
     const match = move.match(notationRegex)
@@ -695,15 +746,24 @@ export class Trax {
     return [...moves]
   }
 
+  /** Play a provisional move if it is valid.
+   * @arg {string} from - the normalized encoding of the starting position
+   * @arg {string} to - the normalized encoding of the ending position
+   * @arg {string} via - the move to be used to transition
+   * @returns {false|string} if the provisional move is invalid: false; if the
+   * provisional move will never be valid for any future moves:
+   * 'delete-provisional'; if the provisional move is valid, the correct
+   * notation, which may be symmetrically adjusted as needed
+   */
   provisionalMove(from, to, via) {
     // Test a provisional move against the current state
-    let rows = from.slice(1).split(':')
+    const lines = from.slice(1).split(':')
     let cols = 0
-    for (const row of rows) {
-      cols = Math.max(cols, codeRowLength(row))
+    for (const line of lines) {
+      cols = Math.max(cols, codeRowLength(line))
     }
 
-    rows = rows.length
+    const rows = lines.length
     if (
       (this.width > rows && this.height > cols) ||
       (this.width > cols && this.height > rows)
@@ -726,15 +786,31 @@ export class Trax {
     return false
   }
 
+  /** Get an encoded representation of the current position, useful for drawing
+   * the board without having to do much analysis.
+   * @returns {string} the current position code
+   */
   get icon() {
     return this.positionCode()
   }
 
+  /** Get an encoded representation of the current position, with a set of
+   * tiles highlighted differently, useful for showing the effects of a move.
+   * @arg {TileDrop} drops - the drops of the most recent play
+   * @returns {string} the current position code, with drops highlighted
+   */
   dropsIcon(drops) {
     return this.positionCode(undefined, undefined, undefined, drops)
   }
 
-  // Symmetry helper, draw the board from different angles
+  /** Symmetry helper, draw the board from different angles.
+   * @arg {boolean} [rightToLeft] - reverse order horizontally
+   * @arg {boolean} [bottomToTop] - reverse order vertically
+   * @arg {boolean} [rotate] - rotate the tiles by 90 degrees
+   * @arg {TileDrop} [drops] - the drops of the most recent play, if you want
+   * them highlighted
+   * @returns {string} an encoding of the position
+   */
   positionCode(rightToLeft, bottomToTop, rotate, drops) {
     const startX = rightToLeft ? this.right : this.left
     const startY = bottomToTop ? this.bottom : this.top
@@ -799,9 +875,11 @@ export class Trax {
     return code.join(':')
   }
 
+  /** Trax has the potential for symmetry, so this gives us the ability to
+   * examine horizontal, vertical, and rotational symmetry for a color.
+   * @returns {string} a position code that matches all symmetrical positions
+   */
   normalize() {
-    // Trax has the potential for symmetry, so this gives us the ability to
-    // examine horizontal, vertical, and rotational symmetry for a color
     let norm = 'z'
     const bools = [true, false]
     for (const rightToLeft of bools) {
@@ -816,6 +894,9 @@ export class Trax {
     return (this.color || 't').toUpperCase() + norm
   }
 
+  /** Get the normalized code for this position. All symmetrical positions will
+   * result in the same normalized code.
+   */
   get normalized() {
     return this.normalize()
   }

package/src/types.d.ts

@@ -7,6 +7,21 @@
 /** Color is a single character to represent white or black. */
 type Color = 'w' | 'b'
 
+/** One end of a line and the tiles taken to get there. */
+type LineEnd = {
+  loc: Point
+  path: TileId[]
+}
+
+/** A notation of a move. */
+type Notation = string
+
+/** A tile type and a location determine a raw move. */
+type RawMove = {
+  type: TileType
+  loc: Point
+}
+
 /** Treat the save state as an opaque object,
  * produced by save() and fed into restore().
  */
@@ -19,7 +34,7 @@ type SaveState = {
   right: number
   top: number
   bottom: number
-  notation: string
+  notation: Notation
   tiles: string
   path: string
   invalid: boolean
@@ -42,7 +57,7 @@ type Tile = {
 /** When a tile is dropped, this object represents the results. */
 type TileDrop = {
   dropped: Tile[]
-  notation: string
+  notation: Notation
   valid: boolean
 }
 

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.22.0'
+export const version = '0.23.0'