@slugbugblue/trax 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @slugbugblue/trax
 
+## 0.19.0 - 2023-02-06
+
+- Added a simple LRU cache to increase the efficiency of the analysis engine
+
 ## 0.18.0 - 2023-02-05
 
 - Analysis improvements:

package/Dockerfile

@@ -1,5 +1,9 @@
-FROM node:19.5.0-slim
+# Use the latest nodejs long-term-support release,
+# on the latest Alpine Linux for its small footprint
+FROM node:lts-alpine
+# Install current source code globally
 COPY . /src
 WORKDIR /src
 RUN npm install -g @slugbugblue/trax
+# Use the trax CLI as the starting point
 ENTRYPOINT ["/usr/local/bin/trax"]

package/README.md

@@ -4,7 +4,7 @@ This project aims to provide tools for working with Trax games in Javascript.
 
 - Trax game-playing engine
 - Position analysis engine
-- Over 50 puzzles to help hone your Trax skills
+- Over 60 puzzles to help hone your Trax skills
 - Command-line interface for ease of use
 
 ## Description
@@ -153,9 +153,10 @@ threats.
 
 ### Puzzles database
 
-The puzzles database is provided in `puzzles.js`, and so far just contains
-puzzles that I've been using to test the analysis engine, along with the list of
-publicly available puzzles at [the traxgame.com puzzles page][traxpuzzles].
+The puzzles database is provided in `puzzles.js`, and contains puzzles that I've
+been using to test the analysis engine, publicly available puzzles from [the
+traxgame.com puzzles page][traxpuzzles], and [puzzles curated][puzzlebook] by
+[Martin M. S. Pedersen][traxplayer].
 
 ## Roadmap
 

package/benchmark/benchmarks.json

@@ -38,5 +38,23 @@
       "count": 58,
       "ms": 59031
     }
+  },
+  "0.19.0": {
+    "puzzles.firstmove.tutorial": {
+      "count": 16,
+      "ms": 9753
+    },
+    "puzzles.firstmove.beginner": {
+      "count": 15,
+      "ms": 17376
+    },
+    "puzzles.firstmove.tough": {
+      "count": 25,
+      "ms": 26380
+    },
+    "puzzles.firstmove.total": {
+      "count": 56,
+      "ms": 55167
+    }
   }
 }

package/docs/lru.md

@@ -0,0 +1,151 @@
+# lru.js API documentation
+
+This module provides a simple Least Recently Used cache.
+
+Internally, this uses a Map, which give us insertion-ordering for free. The
+first item in the list is the oldest. The last item is the most recently set or
+accessed. Most of the base functionality of the Map are replicated.
+
+Since I don't need it to be super fancy, there isn't a lot of extra
+functionality here.
+
+## Example usage
+
+```javascript
+import { LRU } from '@slugbugblue/trax/lru.js'
+
+const cache = new LRU(100)
+
+cache.set('a', 1)
+cache.set('b', 2)
+
+// Get an item from the cache
+console.log(cache.get('a')) // 1
+
+// Accessing a key makes it the most recent:
+console.log(cache.keys()) // [Map Iterator] { 'b', 'a' }
+console.log(cache.hits) // 1
+
+console.log(cache.get('z')) // undefined
+console.log(cache.misses) // 1
+
+console.log(cache.size) // 2
+console.log(cache.capacity) // 100
+```
+
+## API
+
+### LRU class
+
+An LRU cache is a way to remember a limited set of items, with the oldest
+expiring when the capacity is reached.
+
+#### constructor
+
+##### `new LRU(capacity)`
+
+Create the cache by specifying the maximum number of items it should hold.
+
+#### computed properties
+
+##### `capacity`
+
+The maximum number of items the cache can hold. This cannot be changed after the
+cache creation.
+
+##### `size`
+
+The number of items currently stored in the cache.
+
+##### `hits`
+
+The number of times a `get` call has found an item in the cache.
+
+##### `misses`
+
+The number of times a `get` call has not found an item in the cache.
+
+##### `expired`
+
+The number of times an item has been removed from the cache.
+
+#### methods
+
+##### `get(key)`
+
+Retrieve an item from the cache. If the item is found in the cache, `hits` will
+be updated, the item will be marked as the most-recently-used item, and the
+value will be returned. If the item is not present in the cache, `misses` will
+be updated, and `undefined` will be returned.
+
+Note that if you had stored `undefined` as the value in the cache, the return of
+`undefined` doesn't necessarily represent a cache miss.
+
+##### `peek(key)`
+
+Retrieve an item from the cache, if present, but without updating any of the
+LRU-specific information about the retrieval attempt. The item's age will not be
+updated. If the item is not present in the cache, `undefined` will be returned.
+
+##### `set(key, value)`
+
+Store an item in the cache. If the item is already present in the cache, it will
+be replaced and marked as the most-recently-used item.
+
+##### `delete(key)`
+
+Remove an item from the cache.
+
+##### `clear()`
+
+Clears all items and statistics from the cache. The maximum capacity will not
+change.
+
+##### `entries()`
+
+Returns an iterator that operates over all the \[key, value\] pairs stored in
+the cache. The entries will be in order from oldest to newest.
+
+##### `has(key)`
+
+Returns true if a key is found in the cache, false otherwise.
+
+##### `keys()`
+
+Returns an iterator that operates over all the keys stored in the cache. The
+keys will be returned oldest first, newest last.
+
+##### `values()`
+
+Returns an iterator that operates over all the values stored in the cache. The
+values will be returned oldest first, newest last.
+
+#### Plays well with others
+
+The LRU class also includes functionality to provide useful default results when
+used in other contexts.
+
+##### `toString()`
+
+Returns a string representation of the cache in the format `LRU(75 of 1000)`.
+This allows simple logging calls with `console.log(cache)`.
+
+##### `util.inspect.custom()`
+
+When running in the node command line interpreter, an LRU cache instance will be
+pretty-printed using the magic of `util.inspect`.
+
+## License
+
+Copyright 2023 Chad Transtrum
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+the files in this project 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -14,8 +14,9 @@
   "types": "./src/types.d.ts",
   "exports": {
     ".": "./src/engine.js",
-    "./point": "./src/point.js",
     "./analyst": "./src/analyst.js",
+    "./lru": "./src/lru.js",
+    "./point": "./src/point.js",
     "./puzzles": "./src/puzzles.js",
     "./threats": "./src/threats.js",
     "./tty": "./src/tty.js",

package/src/analyst.js

@@ -6,9 +6,12 @@
 
 import { Point } from '@slugbugblue/trax/point'
 import { Trax } from '@slugbugblue/trax'
+import { LRU } from '@slugbugblue/trax/lru'
 
 import { threats } from '@slugbugblue/trax/threats'
 
+const cache = new LRU(2750)
+
 /** Helper function to generate a unique id for the analysis. */
 const id = () => {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
@@ -252,7 +255,7 @@ const passiveAttack = (from) => threatCount(from) > 1
 const underAttack = (from) => attackCount(from) + threatCount(from) > 0
 
 // Analysis class
-export const Analysis = class {
+export class Analysis {
   /** @type {TraxVariant} */
   #rules = 'trax'
   #id = 'analysis'
@@ -554,7 +557,7 @@ export const Analysis = class {
   /**
    * @arg {FoundThreat} threat - a threat
    * @arg {string} color - the player color
-   * @returns {InstanceType<typeof Point>[]} - locations relevant to the threat
+   * @returns {Point[]} - locations relevant to the threat
    */
   #threatLocs(threat, color) {
     const { edge } = this.edge
@@ -658,7 +661,7 @@ export const Analysis = class {
         // we just assume that this threat is also valid ...
         if (game.over && game.turn === Trax.playerNumber(color)) return true
 
-        const { threats } = new Analysis(game, true)
+        const { threats } = analyze(game, true)
 
         // If we give our opponent an attack, this is a faulty move
         const faulty = (threats[Trax.other(color)][1]?.length ?? 0) - other
@@ -712,11 +715,19 @@ export const Analysis = class {
 
 /** Analyze a game position.
  * @arg {Trax} game - the position to analyze
+ * @arg {boolean} partial - if the position should only be partially analyzed
  * @returns {Analysis}
  */
-export const analyze = (game) => new Analysis(game)
+export const analyze = (game, partial = false) => {
+  const id = (partial ? 'y' : 'n') + game.rules + game.normalized
+  const cached = cache.get(id)
+  if (cached) return cached
+  const analysis = new Analysis(game, partial)
+  cache.set(id, analysis)
+  return analysis
+}
 
-export const Suggestion = class {
+export class Suggestion {
   /** @type {PositionScore[]} */
   all = []
   /** @type {PositionScore[]} */

package/src/engine.js

@@ -127,7 +127,7 @@ const codeRowLength = (row) =>
 
 // This is where the magic happens
 /** A digital representation of a Trax game. */
-export const Trax = class {
+export class Trax {
   // Static class properties
 
   /** @readonly @type {Record<TraxVariant, string>} */

package/src/lru.js

@@ -0,0 +1,153 @@
+/** Least Recently Used cache
+ * @copyright 2023
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+/** LRU cache: a class for remembering things. It uses a Map internally and
+ * exposes most of the same interface.
+ */
+export class LRU {
+  /** @type Map */
+  #cache
+  #capacity = 0
+  #hits = 0
+  #misses = 0
+  #expired = 0
+
+  /** Instantiate this class with the max number of cached items
+   * @arg {number} capacity - the maximum number of items to cache
+   */
+  constructor(capacity = 1000) {
+    this.#cache = new Map()
+    if (typeof capacity === 'number' && capacity >= 1) {
+      this.#capacity = Math.floor(capacity)
+    } else {
+      throw new SyntaxError('capacity must be a positive integer')
+    }
+  }
+
+  /** The maximum capacity. */
+  get capacity() {
+    return this.#capacity
+  }
+
+  /** The current size. */
+  get size() {
+    return this.#cache.size
+  }
+
+  /** Number of times we have had a cache hit. */
+  get hits() {
+    return this.#hits
+  }
+
+  /** Number of times we have had a cache miss. */
+  get misses() {
+    return this.#misses
+  }
+
+  /** Number of times we have expired a cache entry. */
+  get expired() {
+    return this.#expired
+  }
+
+  /** Retrieve an item from the cache.
+   * @arg {any} key - the key of the cached item
+   * @returns {any} - the cached item or undefined
+   */
+  get(key) {
+    if (this.#cache.has(key)) {
+      // Update the least recently used order
+      const value = this.#cache.get(key)
+      this.#cache.delete(key)
+      this.#cache.set(key, value)
+      this.#hits++
+    } else {
+      this.#misses++
+    }
+
+    return this.#cache.get(key)
+  }
+
+  /** Retrieve an item from the cache without triggering any LRU handling.
+   * @arg {any} key - the key of the cached item to retrieve
+   * @returns {any} - the cached item or undefined
+   */
+  peek(key) {
+    return this.#cache.get(key)
+  }
+
+  /** Store an item in the cache.
+   * @arg {any} key - the key of the cached item
+   * @arg {any} value - the value to store
+   */
+  set(key, value) {
+    // To update an item, remove and re-add it to track LRU status
+    this.#cache.delete(key)
+
+    // If there are too many items, expire one before adding more
+    if (this.#cache.size >= this.#capacity) {
+      this.#expired++
+      const [expire] = this.#cache[Symbol.iterator]().next().value
+      this.#cache.delete(expire)
+    }
+
+    this.#cache.set(key, value)
+  }
+
+  /** Delete an item from the cache.
+   * @arg {any} key - the key of the cached item
+   * @returns {boolean} true if the item was in the cache
+   */
+  delete(key) {
+    return this.#cache.delete(key)
+  }
+
+  /** Clear the cache and all its statistics. */
+  clear() {
+    this.#cache.clear()
+    this.#hits = 0
+    this.#misses = 0
+    this.#expired = 0
+  }
+
+  /** Get an iterator to return [key, value] pairs from the cache. Does not
+   * update any LRU information. */
+  entries() {
+    return this.#cache.entries()
+  }
+
+  /** Determine if a key is already in the cache. Does not trigger hit/miss.
+   * @arg {any} key - the key to check
+   * @returns {boolean} true if the key is in the cache
+   */
+  has(key) {
+    return this.#cache.has(key)
+  }
+
+  /** Get an iterator for the keys stored in cache, in order from least to most
+   * recent. Does not update any LRU information. */
+  keys() {
+    return this.#cache.keys()
+  }
+
+  /** Get an iterator for the values stored in cache, in order from least to
+   * most recent. Does not update any LRU information. */
+  values() {
+    return this.#cache.values()
+  }
+
+  // Play nicely with the rest of the world
+  toString() {
+    return `LRU(${this.#cache.size} of ${this.#capacity})`
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](_, options) {
+    const [y, s, n] = [options.stylize, 'special', 'number']
+    return `${y('LRU', s)}(${y(this.#cache.size, n)} of ${y(
+      this.#capacity,
+      n,
+    )})`
+  }
+}

package/src/point.js

@@ -32,7 +32,7 @@ const between = (end1, mid, end2) => {
  * Point: an immutable two-dimensional location (x,y) with
  * functions for moving around quickly to neighboring points.
  */
-export const Point = class {
+export class Point {
   #x = 0
   #y = 0
 

package/src/threats.js

@@ -21,7 +21,7 @@ const REGEX = {
   '?': 'b?', // Zero or one black piece
 }
 
-export const Threat = class {
+export class Threat {
   #depth = 0
   #pattern = ''
   #rx
@@ -72,7 +72,7 @@ export const Threat = class {
   }
 }
 
-export const ThreatsDB = class {
+export class ThreatsDB {
   #db = {}
   #depth = 0
 

package/src/version.js

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