@slugbugblue/trax 0.11.0 → 0.13.0

package/src/engine.js

@@ -20,16 +20,29 @@
 // and given a single letter name, so 'bbww' becomes 'a', which gives us six
 // different tile names: a-f
 
-import { Point } from './point.js'
+import { Point } from '@slugbugblue/trax/point'
 
+// Type definitions
 // Fun trax helper constants
 
 const zero = new Point(0, 0)
 const moveNumberRegex = /^(\d+)[.):]?$/
 const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
 
+/** @type ValidTiles[] */
+const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
+
+/** Tiles are represented by the letters a-f.
+ * Slashes are represented by / \ or +.
+ * @readonly
+ * @type {Record<ValidTiles, Slash>}
+ */
 const slash = { a: '\\', b: '+', c: '/', d: '/', e: '+', f: '\\' }
 
+/** Symmetry helper to convert from one tile to another.
+ * @readonly
+ * @type {Record<string, Record<ValidTiles, ValidTiles>>}
+ */
 const symmetry = {
   // Convert tile to different views
   flip: { a: 'd', b: 'b', c: 'f', d: 'a', e: 'e', f: 'c' },
@@ -40,6 +53,13 @@ const symmetry = {
 
 // Fun trax helper functions
 
+/** Apply certain combinations of symmetry.
+ * @arg {TileType} tile - the tile to apply symmetry to
+ * @arg {boolean} [rightToLeft] - mirror the tile
+ * @arg {boolean} [bottomToTop] - flip the tile
+ * @arg {boolean} [rotate] - rotate the tile counterclockwise
+ * @returns {TileType}
+ */
 const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
   if (rightToLeft) tile = symmetry.mirror[tile]
   if (bottomToTop) tile = symmetry.flip[tile]
@@ -48,15 +68,38 @@ const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
 }
 
 // Unexpected note: str.includes(t) is true if t is '' but false if t is undefined
+/** The color at the top of the tile.
+ * @arg {string} t - the tile to check
+ * @returns {Color|false} the color or false if t is not a valid tile
+ */
 const upColor = (t) =>
   'abc'.includes(t) ? 'b' : 'def'.includes(t) ? 'w' : false
+
+/** The color at the bottom of the tile.
+ * @arg {string} t - the tile to check
+ * @returns {Color|false} the color or false if t is not a valid tile
+ */
 const downColor = (t) =>
   'bdf'.includes(t) ? 'b' : 'ace'.includes(t) ? 'w' : false
+
+/** The color at the right edge of the tile.
+ * @arg {string} t - the tile to check
+ * @returns {Color|false} the color or false if t is not a valid tile
+ */
 const rightColor = (t) =>
   'ade'.includes(t) ? 'b' : 'bcf'.includes(t) ? 'w' : false
+
+/** The color at the left edge of the tile.
+ * @arg {string} t - the tile to check
+ * @returns {Color|false} the color or false if t is not a valid tile
+ */
 const leftColor = (t) =>
   'cef'.includes(t) ? 'b' : 'abd'.includes(t) ? 'w' : false
 
+/** Add an empty space to the position encoding string.
+ * @arg {string} code - The position encoding string
+ * @returns {string}
+ */
 const addBlank = (code) => {
   // Encode missing tiles as digits 0-9, for 1-10 missing
   const lastNumber = code.codePointAt(code.length - 1) // This is NaN if code is empty, which is ok
@@ -67,27 +110,60 @@ const addBlank = (code) => {
   return code + '0'
 }
 
-// Ugh, this is a dirty little function to get the length of an encoded position row
+// Ugh, this is a dirty little function to get
+/** The length of an encoded position row.
+ * @arg {string} row - the encoded row
+ * @returns {number} - the actual length of the row
+ */
 const codeRowLength = (row) =>
   row.replace(/\d/g, (n) => '.'.repeat(Number(n) + 1)).length
 
 // This is where the magic happens
+/** A digital representation of a Trax game. */
 export const Trax = class {
   // Static class properties
+
+  /** @readonly @type {Record<TraxVariant, string>} */
   static names = {
     trax: 'Trax',
     traxloop: 'Loop Trax',
     trax8: '8x8 Trax',
   }
 
+  /** @readonly */
   static variants = new Set(Object.keys(this.names)) // Known variants
 
   // Static class methods
+
+  /** Create an x,y Point object with special functions.
+   * @arg {number|PointLike} x - either the x value, or an object with x,y keys
+   * @arg {number} [y] - if x is a number, y must be provided as well
+   * @returns {Point} a new Point object
+   */
   static point = (x, y) => new Point(x, y)
+
+  /** Given a player number, get the color.
+   * @arg {number} playerNumber - the player number, 1 or 2
+   * @returns {Color} the color of that player, w or b
+   */
   static colorOf = (playerNumber) => ({ 1: 'w', 2: 'b' }[playerNumber])
+
+  /** Given a color, get the player number.
+   * @arg {string} color - the color, w or b
+   * @returns {number} the player number, 1 or 2
+   */
   static playerNumber = (color) => ({ b: 2, w: 1 }[color])
+
+  /** Given a color, get the other color.
+   * @arg {string} color - the color, w or b
+   * @returns {Color} the other color, b or w
+   */
   static other = (color) => ({ b: 'w', w: 'b' }[color])
 
+  /** Encode a numeric column number into the Trax notation column letter.
+   * @arg {number} col - the colum number, with 0 just to the left of the tiles
+   * @returns {string} the encoded column letter
+   */
   static encodeCol = (col) => {
     // For notation purposes: 0 -> @, 6 -> F, 28 -> AB
     let n = ''
@@ -99,6 +175,10 @@ export const Trax = class {
     return n || '@'
   }
 
+  /** Decode a Trax notation column letter back to a number.
+   * @arg {string} col - the Trax column letter
+   * @returns {number} the column number
+   */
   static decodeCol = (col) => {
     // Turn letters back into numbers
     col = col.toUpperCase()
@@ -112,6 +192,11 @@ export const Trax = class {
   }
 
   // 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} [id='trax'] - an id used to differentiate tiles from multiple games
+   */
   constructor(rules = 'trax', moves = [], id = 'trax') {
     if (!Trax.variants.has(rules)) rules = 'trax'
     this.id = String(id)
@@ -124,7 +209,9 @@ export const Trax = class {
     this.top = 1
     this.bottom = 0
     this.notation = ''
+    /** @type {Record<TileId, Tile>} */
     this.tiles = {}
+    /** @type TileId[] */
     this.path = []
     this.invalid = false
     // Moves might be a notation string
@@ -133,9 +220,14 @@ export const Trax = class {
     }
   }
 
+  /** Save the current game data to a variable.
+   * @returns {SaveState} an opaque save state object
+   * @see restore for restoring the state
+   */
   save() {
     // In order to evaluate potential moves, we have to modify the state
     return {
+      id: this.id,
       move: this.move,
       turn: this.turn,
       over: this.over,
@@ -150,8 +242,14 @@ export const Trax = class {
     }
   }
 
+  /** Restore a previously saved position.
+   * @arg {SaveState} saved - the previously saved state
+   * @see save for saving the state
+   * @returns {void}
+   */
   restore(saved) {
     // So we need to be able to restore it when we are done
+    this.id = saved.id
     this.move = saved.move
     this.turn = saved.turn
     this.over = saved.over
@@ -169,37 +267,47 @@ export const Trax = class {
     }
   }
 
+  /** The name of this variant. */
   get name() {
-    // Get the name of this variant
     return Trax.names[this.rules]
   }
 
+  /** The number of tiles currently in play. */
   get count() {
-    // Get the number of tiles currently in play
     return Object.keys(this.tiles).length
   }
 
+  /** The color of the current player, w or b. */
   get color() {
-    // Get the color of the current player (w or b)
     return Trax.colorOf(this.turn)
   }
 
+  /** True if the game is over. */
   get gameOver() {
-    // Returns true if the game is over
     return this.over
   }
 
+  /** 1 or 2 for a win, 0 for a tie, false if the game is still in progress. */
   get winner() {
-    // Returns false if the game is still in progress
-    return this.over ? this.turn : false // Or 1 or 2 for a win, or 0 for a tie
+    return this.over ? this.turn : false
   }
 
+  /** Provides the tile ID for the tile at the given location.
+   * @arg {PointLike} loc
+   * returns {TileId}
+   */
   tileId(loc) {
     return this.id + '-' + String(loc.x) + 'x' + String(loc.y)
   }
 
+  /** Add a tile to the board. Note that no validity checking is done here,
+   * except that invalid tiles are not actually placed on the board, so this
+   * should only be called externally.
+   * @arg {TileType} type
+   * @arg {Point} loc
+   * @returns {Tile} the tile placed on the board.
+   */
   addTile(type, loc) {
-    // Note: no validity checking is done here
     const id = this.tileId(loc)
     const tile = { type, loc, id, move: this.move, seq: this.count }
     if (type === 'x') {
@@ -215,10 +323,17 @@ export const Trax = class {
     return tile
   }
 
+  /** The type of tile at the given location.
+   * @arg {PointLike} loc - the location the tile is in
+   * @returns {TileType|undefined} the type of tile, or undefined if no tile
+   */
   tileAt(loc) {
     return (this.tiles[this.tileId(loc)] || {}).type
   }
 
+  /** Is this tile valid?
+   * @type {(type: string, loc: Point) => type is TileType}
+   */
   validTile(type, loc) {
     if (this.count === 0 && loc.x === 0 && loc.y === 0) {
       return type === 'd' || type === 'e'
@@ -237,10 +352,15 @@ export const Trax = class {
     )
   }
 
+  /** Get a list of possible tiles that can be played in this location.
+   * @arg {Point} loc - the location to check
+   * @arg {string | boolean} s=false - if provided, a direction modifier, '/', '\\', or '+'
+   * @returns {TileType[]}
+   */
   possibleTiles(loc, s = false) {
-    // S: slash (/ or \ or +)
+    /** @type TileType[] */
     const possibles = []
-    for (const t of ['a', 'b', 'c', 'd', 'e', 'f']) {
+    for (const t of tileTypes) {
       if ((!s || s === slash[t]) && this.validTile(t, loc)) possibles.push(t)
     }
 
@@ -277,20 +397,20 @@ export const Trax = class {
   }
 
   possibleLocations() {
-    const locs = { [this.tileId(zero)]: zero } // If no tiles are placed, we can play a starting tile
-    const maybe = (loc) => {
-      // Add a loc if a tile isn't already there
-      const id = this.tileId(loc)
-      locs[id] = locs[id] || loc
-    }
+    if (this.count === 0) return [zero]
+    /** @type Record<TileId, Point> */
+    const possibles = {}
 
     for (const tile of Object.values(this.tiles)) {
-      locs[tile.id] = 'tile' // Add an existing tile
-      tile.loc.around.map((loc) => maybe(loc))
+      tile.loc.around.map((loc) => {
+        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(locs).filter((loc) => loc !== 'tile')
+    return Object.values(possibles)
   }
 
   possibleMoves() {
@@ -400,6 +520,7 @@ export const Trax = class {
   }
 
   checkWin(tiles) {
+    /** @type {Color|false} */
     let winner = false
     const colors = [this.color, Trax.other(this.color)] // Check win for current player first
     for (const color of colors) {
@@ -432,13 +553,22 @@ export const Trax = class {
     }
   }
 
+  /** Play a move. Can be called either as:
+   * - play(moveNumber, notation) to ensure move safety, or
+   * - play(notation) for quicker access.
+   * @arg moveNumber {(number|string)} the move number or the notation
+   * @arg {string} [notation] - the notation, if a move number was provided
+   * @returns {{dropped: Tile[], notation: string, valid: boolean}}
+   */
   play(moveNumber, notation) {
     // Generic API call for playing a move with move number safety
     // or, alternately, pass only a single value, notation, for a quick play
     if (notation) {
-      if (moveNumber !== this.move + 1) return { valid: false }
+      if (moveNumber !== this.move + 1) {
+        return { dropped: [], notation: '', valid: false }
+      }
     } else {
-      notation = moveNumber
+      notation = String(moveNumber)
     }
 
     return this.dropTile(notation)
@@ -482,6 +612,7 @@ export const Trax = class {
     this.notation += note
   }
 
+  /** An array of the moves made in the game. */
   get moves() {
     return this.notation
       .replace(/\n/g, ' ')
@@ -489,8 +620,14 @@ export const Trax = class {
       .filter((n) => !n.endsWith('.'))
   }
 
-  dropTile(type, loc, tentative = false) {
-    // Pass in tentative to not save the move
+  /** 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 {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
+   */
+  dropTile(type, loc, tentative) {
+    /** @type Tile[] */
     let dropped = []
     let notation = ''
     let valid = false
@@ -607,11 +744,12 @@ export const Trax = class {
     let y = startY
     do {
       const loc = new Point(x, y)
-      let tile = this.tileAt(loc) // Normal tile for normal orientation
+      const tile = this.tileAt(loc) // Normal tile for normal orientation
       if (tile) {
-        tile = applySymmetry(tile, rightToLeft, bottomToTop, rotate)
+        /** @type string */
+        let encoded = applySymmetry(tile, rightToLeft, bottomToTop, rotate)
         if (this.path.includes(this.tileId(loc))) {
-          tile = String.fromCodePoint(tile.codePointAt(0) + this.turn * 6)
+          encoded = String.fromCodePoint(encoded.codePointAt(0) + this.turn * 6)
         }
 
         if (
@@ -619,10 +757,10 @@ export const Trax = class {
           drops.dropped &&
           drops.dropped.some((t) => loc.eq(t.loc))
         ) {
-          tile = tile.toUpperCase()
+          encoded = encoded.toUpperCase()
         }
 
-        line += tile
+        line += encoded
       } else {
         line = addBlank(line)
       }

package/src/point.js

@@ -13,71 +13,109 @@
  * limitations under the License.
  */
 
-const is = (v, s) => (typeof v).slice(0, 3) === s // Sigh
-
-// Are you tired of doing x,y movements in multiple statements? I am.
+/** Because javascript doesn't have a "0 < 3 < 7" syntax.
+ * @arg {number} end1 - A number on one end or the other
+ * @arg {number} mid - The middle number
+ * @arg {number} end2 - The other end
+ * @returns {boolean} - If the number is in the middle
+ */
+const between = (end1, mid, end2) => {
+  const low = Math.min(end1, end2)
+  const high = Math.max(end1, end2)
+  return low <= mid && mid <= high
+}
 
-// Point: an immutable two-dimensional location (x,y)
-// with functions for moving around quickly to neighboring points
+/** Are you tired of doing x,y movements in multiple statements?
+ *
+ * I know I am.
+ *
+ * Point: an immutable two-dimensional location (x,y) with
+ * functions for moving around quickly to neighboring points.
+ */
 export const Point = class {
   #x = 0
   #y = 0
 
   static dirs = ['up', 'down', 'left', 'right']
 
+  /** You can call this with new Point(point) or new Point({x, y}) or new Point(x, y)
+   * @arg {number | PointLike} x - the x value or a point
+   * @arg {number} [y] - the y value
+   */
   constructor(x, y) {
-    if (is(x, 'obj') && is(x.x, 'num') && is(x.y, 'num')) {
-      // You can call this with new Point(point) or new Point({x,y})
+    if (
+      typeof x === 'object' &&
+      typeof x.x === 'number' &&
+      typeof x.y === 'number'
+    ) {
       this.#x = x.x
       this.#y = x.y
     } else {
-      // Or with new Point(x, y)
-      if (!is(x, 'num')) throw new SyntaxError('x must be a number')
-      if (!is(y, 'num')) throw new SyntaxError('y must be a number')
+      if (typeof x !== 'number' || Number.isNaN(x)) {
+        throw new SyntaxError('x must be a number or a point-like object')
+      }
+
+      if (typeof y !== 'number' || Number.isNaN(x)) {
+        throw new SyntaxError('y must be a number')
+      }
+
       this.#x = x
       this.#y = y
     }
   }
 
+  /** The horizontal value of the point. */
   get x() {
     return this.#x
   }
 
+  /** Throws an error. Points are immutable. */
   set x(_) {
     throw new ReferenceError('Point is immutable')
   }
 
+  /** The vertical value of the point. */
   get y() {
     return this.#y
   }
 
+  /** Throws an error. Points are immutable. */
   set y(_) {
     throw new ReferenceError('Point is immutable')
   }
 
+  /** The point immediately above this point. */
   get up() {
     return new Point(this.#x, this.#y - 1)
   }
 
+  /** The point immediately below this point. */
   get down() {
     return new Point(this.#x, this.#y + 1)
   }
 
+  /** The point to the immediate left of this point. */
   get left() {
     return new Point(this.#x - 1, this.#y)
   }
 
+  /** The point to the immediate right of this point. */
   get right() {
     return new Point(this.#x + 1, this.#y)
   }
 
+  /** A list of the four points that surround this point: up, down, left, and right. */
   get around() {
     return [this.up, this.down, this.left, this.right]
   }
 
+  /** Move in a specific direction by passing in a direction string.
+   * @arg {string} direction - any string that begins with u, d, l, or r
+   * @returns {Point}
+   */
   dir(direction) {
     const error = 'direction must be one of: up, down, left, right, u, d, l, r'
-    if (!is(direction, 'str')) throw new SyntaxError(error)
+    if (typeof direction !== 'string') throw new SyntaxError(error)
     direction = direction.toLowerCase()
     if (direction[0] === 'u') return this.up
     if (direction[0] === 'd') return this.down
@@ -86,29 +124,35 @@ export const Point = class {
     throw new SyntaxError(error)
   }
 
+  /** @arg {PointLike} from - the point to measure x against. */
   distX(from) {
     return Math.abs(this.#x - from.x)
   }
 
+  /** @arg {PointLike} from - the point to measure y against. */
   distY(from) {
     return Math.abs(this.#y - from.y)
   }
 
+  /** @arg {PointLike} from - the point to measure against. */
   distance(from) {
     return Math.hypot(this.distX(from), this.distY(from))
   }
 
+  /** @arg {PointLike} that - the point to test equality against. */
   eq(that) {
     return this.#x === that.x && this.#y === that.y
   }
 
-  in(topLeft, bottomRight) {
-    return (
-      this.x >= topLeft.x &&
-      this.x <= bottomRight.x &&
-      this.y >= topLeft.y &&
-      this.y <= bottomRight.y
-    )
+  /** Bounding box corners can be passed in any order.
+   * @arg {PointLike} a - one corner of the bounding box
+   * @arg {PointLike} b - the opposite corner
+   * @returns {boolean} - true if the point is on or in the box
+   */
+  in(a, b) {
+    // Allow for the bounding points to be passed in any order
+    // as long as they are opposite corners:
+    return between(a.x, this.x, b.x) && between(a.y, this.y, b.y)
   }
 
   // Play nicely with the rest of the world
@@ -117,6 +161,7 @@ export const Point = class {
     return 'Point(' + this.#x + ',' + this.#y + ')'
   }
 
+  /** @returns {PointLike} */
   toJSON() {
     return { x: this.#x, y: this.#y }
   }