@slugbugblue/trax 0.21.0 → 0.22.0

package/docs/analyst.md

@@ -1,236 +0,0 @@
-# analyst.js API documentation
-
-This module provides additional analysis of Trax games, which can be used in the
-CLI and for bots.
-
-## Example usage
-
-```javascript
-import { Trax } from '@slugbugblue/trax'
-import { analyze, suggest } from '@slugbugblue/trax/analyst'
-
-const trax = new Trax('trax', '@0/ @1/ B0\\')
-
-const analysis = analyze(trax)
-
-console.log(JSON.stringify(analysis.edge, null, 2))
-console.log(JSON.stringify(analysis.threats, null, 2))
-console.log(JSON.stringify(analysis.scores, null, 2))
-
-const suggestion = suggest(trax)
-
-console.log(JSON.stringify(suggestion.options, null, 2))
-
-trax.play(suggestion.pick.move)
-```
-
-## API
-
-### Analysis class
-
-Available either as `Analysis` to be used with `new`, or it can also be returned
-using the `analyze` shortcut function.
-
-Provides important properties and functions to understand the current state of a
-Trax game.
-
-#### constructor
-
-##### `new Analysis(game)`
-
-##### `analyze(game)`
-
-Provide a Trax `game`, ideally with at least one move and not yet completed.
-
-#### computed properties
-
-##### `game`
-
-The Trax object that represents the position originally analyzed.
-
-##### `edge`
-
-An object with two properties, `b` and `w`, which are string representations of
-the traced edge, with one character per space, along with an array named `edge`
-which contains the full internal details of each edge space. This object is
-tightly tied to the internal representation of the edge tracing algorithm and as
-such is subject to change in future iterations.
-
-Edge tracing begins in the top left of the tiles (ie, space A0 or the nearest
-playable space to it) and walks clockwise around the perimeter of the played
-tiles, recording information about the lines that lead to each space. Note that
-the edge spaces are just outside the existing tiles, not on the tiles
-themselves. The following keys are present in each edge space representation:
-
-- `x` and `y`: The location of the edge space, which can be directly used to
-  create a `Point` for use in any function that takes a location.
-- `c`: The color of the line that leads into this space. This can be `b` or `w`
-  or `l` or `r`, the latter two representing both black and white lines ("left
-  turn") or neither ("right turn").
-- `t`: The type of space, which is `n` for a normal space, `c` for a space
-  inside a cave that has limits on which tiles can be legally played in it, or
-  `x` if there are no legal moves available for this space, which can happen
-  both in caves or in 8x8 Trax when the game size limits have been reached.
-- `w` and `b`: True if the next line of the same color is the other end of this
-  line.
-- `nw` and `nb`: The number of the white and/or black lines coming to this
-  space, which can then be used to find the other end of the line.
-- `pb` and `pw`: True if the next line of the same color is part of a
-  connectable pair of lines with this color.
-- `zb` and `zw`: The character used in the black or white string representation
-  of this space.
-- `idx`: The index of this edge space in the edge array.
-
-For the edge string, the following characters are used as a hopefully useful
-shorthand summary of the tiles surrounding the space. To make regex pattern
-matching simpler, the black string is constructed by first swapping the colors,
-so that it appears as though all black tiles are white tiles.
-
-- `b`: a black line enters this space.
-- `w`: a white line enters this space.
-- `l`: both a black and a white line enter this space.
-- `a`: a white line enters this space, and the next white line in the edge is
-  the other end of this line.
-- `c`: a white line enters this space, and the next white line in the edge forms
-  a connectable pair with this line.
-- `m`: both a black and a white line enter this space, and the next white line
-  in the edge is the other end of the white line.
-- `p`: both a black and a white line enter this space, and the next while line
-  in the edge forms a connectable pair with the white line.
-- `r`: no lines enter this space, but it represents a right-corner in the edge.
-
-##### `threats`
-
-Analyzes the existing threats for the current game position. Returns an object
-with both `b` and `w` keys, where each is an object with zero or more "depth"
-keys. Threats of depth 0 are corners or connectable-pairs. Threats of depth 1
-are immediate attacks. Threats of depth 2 are Ls. etc.
-
-Note that the threats are not checked for faultiness at this time. In other
-words, there may be a faulty L listed as a threat even if it is not currently
-possible to activate the L successfully. To ensure that the listed threats are
-valid, use the `validateThreats()` method call.
-
-The "depth" keys are arrays of the threats at that level, which means that a
-simple count of the threats at each level can give a good first guess at the
-"score" of the current position. Each element of the array is an object with the
-following keys:
-
-- `threat`: The threat pattern as it was fed into the threats database. This is
-  a simple edge string.
-- `match`: The portion of the actual edge string that matched the pattern, which
-  may or may not be exactly the same as the pattern.
-- `at`: The index of the edge string at which the pattern match began.
-- `value`: The multiplier for this threat. Most often this is `1`, but some
-  threats can be re-formed, and this will be `2` in those cases.
-
-##### `faulty`
-
-An object with two keys, `w` and `b`, each of which is a list of threats that
-were found to be faulty. This object will be empty if `validateThreats()` has
-not yet been called.
-
-Example data:
-
-```javascript
-{
-  w: [{ threat: 'Arw?!pW', match: 'arwpa', at: 1, level: 2, value: 1 }],
-  b: [],
-}
-```
-
-##### `score`
-
-Computes a rough "score" of the current position using the list of threats. A
-positive score means that the player whose turn it is has a potential advantage,
-with the larger the number of higher the advantage. A negative score indicates a
-disadvantage.
-
-##### `scores`
-
-Returns the same score as above, but packaged into an object with both a `b` and
-`w` key, to more easily grab the score of a particular player without regard to
-whose turn it is. Note that `b` will not necessarily be equal to `w` times -1
-because the scores can change depending on who has the initiative.
-
-#### methods
-
-##### `count.w(level)`
-
-Returns the number of threats for white at the given level.
-
-##### `count.b(level)`
-
-Returns the number of threats for black at the given level.
-
-##### `inCave(loc)`
-
-For any given location, returns true if that location is found within a cave.
-
-##### `spaceType(loc)`
-
-For any given location, determine the type of playable space. Returns one of:
-
-- `n`: This location can be played in normally.
-- `x`: A move is not valid in this location.
-- `c`: This location is in a cave, but otherwise has no restrictions on its
-  play.
-- `C`: This location is in a cave, and certain plays at this position result in
-  illegal moves.
-
-##### `validateThreats()`
-
-Ensure that all of the threats that are present for each color are actually
-valid. If it finds any faulty threats, it will update the `score` and populate
-the `faulty` property with each threat that was found to be invalid.
-
-### Suggestion class
-
-Accessible from `suggest(game)`, this class is returned with several useful
-pieces of information.
-
-#### properties
-
-##### `all`
-
-A list of all the moves analyzed, ordered by highest scoring move first.
-
-Each move is an object with the following properties:
-
-- `move`: the notation of the move
-- `score`: the score of the move
-- `analysis`: the analysis object of the position for this move
-
-##### `options`
-
-A smaller subset of the `all` list, with only the moves that are worth
-considering.
-
-##### `pick`
-
-A random selection of one of the `options`.
-
-##### `ms`
-
-The number of milliseconds spent performing the analyses required to create the
-suggestion.
-
-#### computed properties
-
-- `best`: quick access to the top-scoring move
-- `analyzed`: quick access to a count of the number of moves analyzed
-
-## License
-
-Copyright 2022-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/docs/lru.md

@@ -1,151 +0,0 @@
-# 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/docs/point.md

@@ -1,148 +0,0 @@
-# point.js API documentation
-
-This module provides a class structure to work with `x`, `y` locations as a
-single point.
-
-Since I don't need it to be super fancy, there isn't a lot of extra
-functionality here.
-
-## Example usage
-
-```javascript
-import { Point } from '@slugbugblue/trax/point.js'
-
-const zero = new Point(0, 0)
-
-const up = zero.up
-console.log('up:', up.x, up.y) // up: 0 -1
-
-const rt = zero.right
-console.log('rt:', rt) // rt: Point(1,0)
-
-const up2 = zero.dir('up')
-console.log('up === up2 ?', up.eq(up2)) // up === up2 ? true
-
-// distances
-console.log(zero.distX(up), zero.distX(rt)) // 0 1
-console.log(up.distX(rt), up.distY(rt)) // 0 0
-console.log(zero.distance(up), zero.distance(rt)) // 1 1
-console.log(up.distance(rt)) // 1.4142135623730951
-```
-
-## API
-
-### Point class
-
-A Point instance is a representation of an immutable point in two dimensional
-space, represented by an `x` and a `y` component. Since this implementation was
-created for game boards, we assume that all points are integers, though that is
-not a requirement, and the math will work equally well on non-integers.
-
-#### constructor
-
-##### `new Point(fromPoint)`
-
-##### `new Point(x, y)`
-
-You can create a point from either a point-like object (ie, any object with both
-an `x` and a `y` key with numeric values), or from individual `x` and `y`
-numbers. Once a point is created, it cannot be changed; however, you can use its
-functions to return other points relative to it.
-
-#### properties
-
-##### `x` and `y` immutable properties
-
-You can return the individual `x` or `y` property of a point by accessing it
-directly. Attempts to change these properties will fail.
-
-##### `up`, `down`, `left`, `right` calculated properties
-
-Since points are immutable, to move a point, you need to create a new point.
-These calculated properties provide quick access to cardinal integer neighboring
-points.
-
-##### `around` calculated property
-
-Or, get an array of all four cardinal points around the existing point.
-
-#### methods
-
-##### `dir(direction)`
-
-Pass in a string named direction (ie, one of `up`, `down`, `left`, or `right`)
-to get a point one integer away from the existing point in the direction
-indicated. This does the exact same thing as the calculated properties with
-these names, but it can be done using a variable instead.
-
-##### `distX(from)`, `distY(from)`
-
-Returns the difference between the `x` or `y` properties of two points. This
-will always be represented by zero or a positive number.
-
-##### `distance(from)`
-
-Returns the distance between two points. This will never be a negative number.
-
-##### `eq(to)`
-
-Returns `true` if the given point or point-like object is at the same location
-as the existing point.
-
-##### `in(a, b)`
-
-Pass in two points (or point-like objects) to define a rectangular bounding box.
-Each point represents opposite corners of the box.
-
-Returns `true` if the calling point is located inside the box or along any of
-its edges (ie, both bounding points are considered "inside").
-
-#### Plays well with others
-
-The Point class also includes functionality to provide useful default results
-when used in other contexts.
-
-##### `toString()`
-
-Returns a string representation of the point in the format `Point(x,y)`. This
-allows simple logging calls with `console.log(point)`.
-
-##### `toJSON()`
-
-JSON cannot encode special classes, but this class can be stored as a bare
-object with `x` and `y` keys when converted to JSON. Note, though, that when
-parsing the resultant JSON string, all Point functionality is not restored by
-default. For example:
-
-```javascript
-const zero = new Point(0, 0)
-const json = JSON.stringify(zero) // '{"x":0,"y":0}'
-const jsonzero = JSON.parse(json) // { x: 0, y: 0 }
-
-console.log(zero.eq(jsonzero)) // true
-jsonzero.eq(zero) // TypeError: jsonzero.eq is not a function
-
-// However, the object can easily be turned back into a Point:
-const reconstituted = new Point(jsonzero)
-console.log(reconstituted.eq(zero)) // true
-```
-
-##### `util.inspect.custom()`
-
-When running in the node command line interpreter, a point will be
-pretty-printed using the magic of `util.inspect`.
-
-## License
-
-Copyright 2019-2022 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.