@slugbugblue/trax 1.0.1 → 1.1.1

package/RELEASE.v1.1.1.md

@@ -0,0 +1,5 @@
+## 1.1.1 - 2026-02-28
+
+- Clean up typescript with strict tsc option
+- Export typescript types together with the code
+

package/gl-sast-report.json

@@ -0,0 +1 @@
+{"version":"15.2.2","vulnerabilities":[],"scan":{"analyzer":{"id":"semgrep","name":"Semgrep","url":"https://gitlab.com/gitlab-org/security-products/analyzers/semgrep","vendor":{"name":"GitLab"},"version":"6.15.1"},"scanner":{"id":"semgrep","name":"Semgrep","url":"https://github.com/returntocorp/semgrep","vendor":{"name":"GitLab"},"version":"1.145.0"},"type":"sast","start_time":"2026-02-28T20:29:59","end_time":"2026-02-28T20:30:11","status":"success","observability":{"events":[{"event":"collect_sast_scan_metrics_from_pipeline","property":"54b1ad92-5d39-416b-9075-916f3da22681","label":"semgrep","value":0,"version":"6.15.1","exit_code":0,"override_count":0,"passthrough_count":0,"custom_exclude_path_count":0,"time_s":12,"file_count":7}]}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Trax game engine",
   "keywords": [
     "trax",
@@ -11,20 +11,28 @@
   "bugs": "https://gitlab.com/slugbugblue/trax/issues",
   "license": "Apache-2.0",
   "author": "Chad Transtrum <chad@transtrum.net>",
-  "types": "./src/types.d.ts",
+  "types": "./src/engine.d.ts",
+  "typings": "./src/engine.d.ts",
   "exports": {
-    ".": "./src/engine.js",
+    ".": {
+      "types": "./src/engine.d.ts",
+      "default": "./src/engine.js"
+    },
     "./version": "./src/version.js",
     "./version.js": "./src/version.js"
   },
-  "repository": "gitlab:slugbugblue/trax",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/slugbugblue/trax.git"
+  },
   "scripts": {
     "genversion": "genversion --esm src/version.js",
-    "git-add": "git add src/version.js",
+    "git-add": "git add src/version.js src/engine.d.ts",
+    "ts-build": "tsc -p tsconfig.build.json && rm -f src/version.d.ts",
     "test": "xo && c8 ava",
     "prepare": "[ -n \"$CI\" ] || husky",
-    "preversion": "npm test",
-    "version": "npm run genversion ; npm run git-add",
+    "preversion": "npm audit --audit-level=high && npm test",
+    "version": "npm run genversion ; npm run ts-build ; npm run git-add",
     "postversion": "git push && git push --tags"
   },
   "dependencies": {
@@ -32,8 +40,8 @@
     "@slugbugblue/point": "^1.0.0"
   },
   "devDependencies": {
-    "ava": "^6.4.1",
-    "c8": "^10.1.3",
+    "ava": "^7.0.0",
+    "c8": "^11.0.0",
     "genversion": "^3.0.2",
     "husky": "^9.1.7",
     "prettier": "^3.6.2",
@@ -57,15 +65,5 @@
     "singleQuote": true,
     "trailingComma": "all",
     "useTabs": false
-  },
-  "xo": {
-    "prettier": true,
-    "space": true,
-    "rules": {
-      "curly": [
-        "error",
-        "multi-line"
-      ]
-    }
   }
 }

package/src/engine.d.ts

@@ -0,0 +1,313 @@
+/** A digital representation of a Trax game. */
+export class Trax {
+  /** @readonly */
+  static readonly version: '1.1.1'
+  /** @readonly @type {Record<TraxVariant, string>} */
+  static readonly names: Record<TraxVariant, string>
+  /** @readonly */
+  static readonly variants: Set<string>
+  /** 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: number | PointLike, y?: number) => Point
+  /** 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: number) => Color
+  /** 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: string) => number
+  /** 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: string) => 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: number) => string
+  /** 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: string) => number
+  /** 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?: TraxVariant, moves?: string | string[], id?: string)
+  id: string
+  rules: TraxVariant
+  move: number
+  turn: number
+  over: boolean
+  left: number
+  right: number
+  top: number
+  bottom: number
+  notation: string
+  /** @type {Record<TileId, Tile>} */
+  tiles: Record<TileId, Tile>
+  /** @type TileId[] */
+  path: TileId[]
+  invalid: boolean
+  /** Save the current game data to a variable.
+   * @returns {SaveState} an opaque save state object
+   * @see restore for restoring the state
+   */
+  save(): SaveState
+  /** Restore a previously saved position.
+   * @arg {SaveState} saved - the previously saved state
+   * @see save for saving the state
+   */
+  restore(saved: SaveState): void
+  /** The name of this variant. */
+  get name(): string
+  /** The number of tiles currently in play. */
+  get count(): number
+  /** The color of the current player, w or b. */
+  get color(): Color
+  /** True if the game is over. */
+  get gameOver(): boolean
+  /** 1 or 2 for a win, 0 for a tie, false if the game is still in progress. */
+  get winner(): number | false
+  /** Provides the tile ID for the tile at the given location.
+   * @arg {PointLike} loc
+   * returns {TileId}
+   */
+  tileId(loc: PointLike): string
+  /** 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: TileType, loc: Point): Tile
+  /** The type of tile at the given location.
+   * @arg {PointLike} loc - the location the tile is in
+   * @returns {ValidTiles|undefined} the type of tile, or undefined if no tile
+   */
+  tileAt(loc: PointLike): ValidTiles | undefined
+  validTile(type: string, loc: Point): type is ValidTiles
+  /** 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: Point, s?: string | boolean): TileType[]
+  get height(): number
+  get width(): number
+  /** Determine if a location is valid to play in.
+   * @arg {Point} loc - the location to check
+   * @returns {boolean}
+   */
+  validLocation(loc: Point): boolean
+  /** Find all possible locations to play in. Note that these are not
+   * necessarily valid locations, just empty ones that border existing tiles.
+   */
+  possibleLocations(): Point[]
+  /** Find all possible moves as a list of notations,
+   * ie: ['@1+', '@1/', '@1\\', ...]
+   *
+   * Note that moves are not guaranteed to be valid.
+   */
+  possibleMoves(): string[]
+  /** 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: Point): Tile[]
+  /** 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: ValidTiles, loc: Point): string
+  /** 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: string): RawMove
+  /** 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: Color, loc: Point, from: string): LineEnd
+  /** 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: Color, loc: Point): LineEnd[]
+  /** 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: Point, locB: Point): boolean
+  /** Determine if the game has ended.
+   * @arg {Tile[]} tiles - a list of the tiles placed during the last move.
+   */
+  checkWin(tiles: Tile[]): void
+  /** 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: number | string,
+    notation?: string,
+  ): {
+    dropped: Tile[]
+    notation: string
+    valid: boolean
+  }
+  /** 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: string | string[]): void
+  /** Add the current move notation to the notation string
+   * @arg {string} notation - the notation of the current move
+   */
+  updateNotation(notation: string): void
+  /** An array of the moves made in the game. */
+  get moves(): string[]
+  /** Drop a tile onto the board. This is a lower level call. Use play() if possible instead.
+   * @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
+   */
+  dropTile(
+    type: string | ValidTiles,
+    loc?: Point,
+    tentative?: string | boolean,
+  ): TileDrop
+  /** 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: string): string[]
+  /** 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: string, to: string, via: string): false | string
+  /** 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(): string
+  /** 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: TileDrop): string
+  /** 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?: boolean,
+    bottomToTop?: boolean,
+    rotate?: boolean,
+    drops?: TileDrop,
+  ): string
+  /** 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(): string
+  /** Get the normalized code for this position. All symmetrical positions will
+   * result in the same normalized code.
+   */
+  get normalized(): string
+}
+export type Color = 'w' | 'b'
+/**
+ * One end of a line and the tiles taken to get there.
+ */
+export type LineEnd = {
+  loc: Point
+  path: TileId[]
+}
+export type Notation = string
+/**
+ * A tile type and a location determine a raw move.
+ */
+export type RawMove = {
+  type: TileType
+  loc: Point
+}
+/**
+ * Treat the save state as an opaque object,
+ * produced by save() and fed into restore().
+ */
+export type SaveState = {
+  id: string
+  move: number
+  turn: number
+  over: boolean
+  left: number
+  right: number
+  top: number
+  bottom: number
+  notation: Notation
+  tiles: string
+  path: string
+  invalid: boolean
+}
+export type Slash = '/' | '\\' | '+'
+/**
+ * A single tile on the board.
+ */
+export type Tile = {
+  id: TileId
+  loc: Point
+  type: TileType
+  move: number
+  seq: number
+}
+export type TileId = string
+/**
+ * When a tile is dropped, this object represents the results.
+ */
+export type TileDrop = {
+  dropped: Tile[]
+  notation: Notation
+  valid: boolean
+}
+export type TileType = ValidTiles | 'x'
+export type TraxVariant = 'trax' | 'traxloop' | 'trax8'
+export type ValidTiles = 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
+import type { PointLike } from '@slugbugblue/point'
+import { Point } from '@slugbugblue/point'

package/src/engine.js

@@ -4,9 +4,82 @@
  * @license Apache-2.0
  */
 
-/// <reference path="./types.d.ts" />
-
+/** @import { PointLike } from '@slugbugblue/point' */
 import { Point } from '@slugbugblue/point'
+import { version } from './version.js'
+
+// Type definitions
+
+/** Color is a single character to represent white or black. */
+/** @typedef {'w' | 'b'} Color */
+
+/**
+ * One end of a line and the tiles taken to get there.
+ * @typedef {Object} LineEnd
+ * @property {Point} loc
+ * @property {TileId[]} path
+ */
+
+/** A notation of a move. */
+/** @typedef {string} Notation */
+
+/**
+ * A tile type and a location determine a raw move.
+ * @typedef {Object} RawMove
+ * @property {TileType} type
+ * @property {Point} loc
+ */
+
+/**
+ * Treat the save state as an opaque object,
+ * produced by save() and fed into restore().
+ * @typedef {Object} SaveState
+ * @property {string} id
+ * @property {number} move
+ * @property {number} turn
+ * @property {boolean} over
+ * @property {number} left
+ * @property {number} right
+ * @property {number} top
+ * @property {number} bottom
+ * @property {Notation} notation
+ * @property {string} tiles
+ * @property {string} path
+ * @property {boolean} invalid
+ */
+
+/** Representations of the different ways a tile can curve. */
+/** @typedef {'/' | '\\' | '+'} Slash */
+
+/**
+ * A single tile on the board.
+ * @typedef {Object} Tile
+ * @property {TileId} id
+ * @property {Point} loc
+ * @property {TileType} type
+ * @property {number} move
+ * @property {number} seq
+ */
+
+/** A TileId is just a string. */
+/** @typedef {string} TileId */
+
+/**
+ * When a tile is dropped, this object represents the results.
+ * @typedef {Object} TileDrop
+ * @property {Tile[]} dropped
+ * @property {Notation} notation
+ * @property {boolean} valid
+ */
+
+/** Invalid tiles are represented by 'x'. */
+/** @typedef {ValidTiles | 'x'} TileType */
+
+/** All of the variants supported by the engine. */
+/** @typedef {'trax' | 'traxloop' | 'trax8'} TraxVariant */
+
+/** Tile type names are single letters a-f encoding edge colors. */
+/** @typedef {'a' | 'b' | 'c' | 'd' | 'e' | 'f'} ValidTiles */
 
 // Fun trax helper constants
 
@@ -50,11 +123,11 @@ const symmetry = {
 // Fun trax helper functions
 
 /** Apply certain combinations of symmetry.
- * @arg {TileType} tile - the tile to apply symmetry to
+ * @arg {ValidTiles} 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}
+ * @returns {ValidTiles}
  */
 const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
   if (rightToLeft) tile = symmetry.mirror[tile]
@@ -63,34 +136,35 @@ const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
   return tile
 }
 
-// Unexpected note: str.includes(t) is true if t is '' but false if t is undefined
+// Note: String(undefined) === 'undefined', which is never a valid tile letter,
+// so these functions correctly return false when t is undefined.
 /** The color at the top of the tile.
- * @arg {string} t - the tile to check
+ * @arg {string | undefined} 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
+  'abc'.includes(String(t)) ? 'b' : 'def'.includes(String(t)) ? 'w' : false
 
 /** The color at the bottom of the tile.
- * @arg {string} t - the tile to check
+ * @arg {string | undefined} 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
+  'bdf'.includes(String(t)) ? 'b' : 'ace'.includes(String(t)) ? 'w' : false
 
 /** The color at the right edge of the tile.
- * @arg {string} t - the tile to check
+ * @arg {string | undefined} 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
+  'ade'.includes(String(t)) ? 'b' : 'bcf'.includes(String(t)) ? 'w' : false
 
 /** The color at the left edge of the tile.
- * @arg {string} t - the tile to check
+ * @arg {string | undefined} 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
+  'cef'.includes(String(t)) ? 'b' : 'abd'.includes(String(t)) ? 'w' : false
 
 /** Add an empty space to the position encoding string.
  * @arg {string} code - The position encoding string
@@ -98,7 +172,7 @@ const leftColor = (t) =>
  */
 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
+  const lastNumber = /** @type {number} */ (code.codePointAt(code.length - 1)) // Undefined if code is empty, which is ok
   if (lastNumber > 47 && lastNumber < 57) {
     return code.slice(0, -1) + String.fromCodePoint(lastNumber + 1)
   }
@@ -118,6 +192,8 @@ const codeRowLength = (row) =>
 /** A digital representation of a Trax game. */
 export class Trax {
   // Static class properties
+  /** @readonly */
+  static version = version
   /** @readonly @type {Record<TraxVariant, string>} */
   static names = {
     trax: 'Trax',
@@ -137,17 +213,29 @@ export class Trax {
    * @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]
+  static colorOf = (playerNumber) => {
+    /** @type {Record<number, Color>} */
+    const map = { 1: 'w', 2: 'b' }
+    return map[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]
+  static playerNumber = (color) => {
+    /** @type {Record<string, number>} */
+    const map = { b: 2, w: 1 }
+    return map[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]
+  static other = (color) => {
+    /** @type {Record<string, Color>} */
+    const map = { b: 'w', w: 'b' }
+    return map[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
@@ -171,7 +259,8 @@ export class Trax {
     col = col.toUpperCase()
     let n = 0
     while (col.length > 0) {
-      n += (col.codePointAt(0) - 64) * 26 ** (col.length - 1)
+      const cp = /** @type {number} */ (col.codePointAt(0))
+      n += (cp - 64) * 26 ** (col.length - 1)
       col = col.slice(1)
     }
 
@@ -312,10 +401,12 @@ export class Trax {
 
   /** 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
+   * @returns {ValidTiles|undefined} the type of tile, or undefined if no tile
    */
   tileAt(loc) {
-    return (this.tiles[this.tileId(loc)] || {}).type
+    return /** @type {ValidTiles | undefined} */ (
+      (this.tiles[this.tileId(loc)] || {}).type
+    )
   }
 
   /** Is this tile valid?
@@ -435,7 +526,7 @@ export class Trax {
     const invalids = {}
     let check = loc.around
     while (check.length > 0) {
-      const pos = check.shift()
+      const pos = /** @type {Point} */ (check.shift())
       if (this.validLocation(pos)) {
         const possibles = this.possibleTiles(pos)
         if (possibles.length === 1) {
@@ -495,6 +586,7 @@ export class Trax {
    * takes to get there.
    */
   follow(color, loc, from) {
+    /** @type {TileId[]} */
     const path = []
     let id = this.tileId(loc)
     let tile = this.tileAt(loc)
@@ -820,7 +912,9 @@ export class Trax {
         /** @type string */
         let encoded = applySymmetry(tile, rightToLeft, bottomToTop, rotate)
         if (this.path.includes(this.tileId(loc))) {
-          encoded = String.fromCodePoint(encoded.codePointAt(0) + this.turn * 6)
+          encoded = String.fromCodePoint(
+            /** @type {number} */ (encoded.codePointAt(0)) + this.turn * 6,
+          )
         }
 
         if (

package/src/version.js

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