refactor(grid): rename at() to add() and make it accept multiple coor…

…dinates

The word "at" will have a different meaning, that's why it's renamed.

BREAKING CHANGE: The at() traverser is renamed to add()

README.md

@@ -214,7 +214,7 @@ statelessGrid.store // Map(0) {}
 statelessGrid.each((hex) => console.log(hex)).run() // logs nothing
 // However, stateless grids can always be traversed:
 statelessGrid
-  .traverse(at({ q: 1, r: 1 })) // traverse a single hex
+  .traverse(add({ q: 1, r: 1 })) // traverse a single hex
   .each((hex) => console.log(hex))
   .run()  // logs: Hex {q: 1, r: 1}
 
@@ -258,10 +258,10 @@ const hex = grid.getHex({ q: 1, r: 2 }) // logs: Hi there 👋
 If you want to update hexes in a grid, use Grid's `map()` method:
 
 ```typescript
-import { at, createHexPrototype, Grid } from 'honeycomb-grid'
+import { add, createHexPrototype, Grid } from 'honeycomb-grid'
 
 const hexPrototype = createHexPrototype(/* ... */)
-const grid = new Grid(hexPrototype, at({ q: 1, r: 2 })) // create a grid with a single hex
+const grid = new Grid(hexPrototype, add({ q: 1, r: 2 })) // create a grid with a single hex
 const mappedGrid = grid
   .map((hex) => {
     // hex is already cloned, so you can mutate it in-place

src/grid/functions/flatTraverse.test.ts

@@ -1,6 +1,6 @@
 import { CompassDirection } from '../../compass'
 import { createHex, createHexPrototype } from '../../hex'
-import { at, move } from '../traversers'
+import { add, move } from '../traversers'
 import { flatTraverse } from './flatTraverse'
 
 const hexPrototype = createHexPrototype()
@@ -14,7 +14,7 @@ test('returns an array of hexes if only a single traverser is passed', () => {
 })
 
 test('flattens the passed traversers into a single traverser and returns it', () => {
-  const traversers = [at({ q: 1, r: 2 }), move(CompassDirection.S, 2)]
+  const traversers = [add({ q: 1, r: 2 }), move(CompassDirection.S, 2)]
   const result = flatTraverse(traversers)(cursor, (coordinates) => createHex(hexPrototype, coordinates))
 
   expect(result).toEqual([

src/grid/functions/inStore.test.ts

@@ -1,13 +1,13 @@
 import { createHex, createHexPrototype } from '../../hex'
 import { Grid } from '../grid'
-import { at } from '../traversers'
+import { add } from '../traversers'
 import { inStore } from './inStore'
 
 test('returns whether the passed hex is present in the passed store', () => {
   const hexPrototype = createHexPrototype()
   const hex = createHex(hexPrototype, { q: 1, r: 2 })
 
   expect(inStore(hex, new Grid(hexPrototype, new Map([[hex.toString(), hex]])))).toBe(true)
-  expect(inStore(hex, new Grid(hexPrototype, at({ q: 3, r: 4 })))).toBe(false)
+  expect(inStore(hex, new Grid(hexPrototype, add({ q: 3, r: 4 })))).toBe(false)
   expect(inStore(hex, new Grid(hexPrototype))).toBe(false)
 })

src/grid/grid.test.ts

@@ -1,6 +1,6 @@
 import { cloneHex, createHex, createHexPrototype, Hex, toString } from '../hex'
 import { Grid } from './grid'
-import { at } from './traversers'
+import { add } from './traversers'
 import { Traverser } from './types'
 
 const hexPrototype = createHexPrototype()
@@ -160,7 +160,7 @@ describe('getHex()', () => {
 })
 
 test('has a hexes() method that returns the hexes from the last iteration', () => {
-  const grid1 = new Grid(hexPrototype, [at({ q: 1, r: 2 }), at({ q: 3, r: 4 })])
+  const grid1 = new Grid(hexPrototype, [add({ q: 1, r: 2 }, { q: 3, r: 4 })])
   expect(grid1.hexes()).toEqual([createHex(hexPrototype, { q: 1, r: 2 }), createHex(hexPrototype, { q: 3, r: 4 })])
 
   const grid2 = grid1.filter((hex) => hex.q === 1)
@@ -237,7 +237,7 @@ describe('each()', () => {
 
   test('iterates over each hex from the previous iterator/traverser', () => {
     const callback = jest.fn()
-    const grid1 = new Grid(hexPrototype, [at({ q: 1, r: 2 }), at({ q: 3, r: 4 })]).each(callback)
+    const grid1 = new Grid(hexPrototype, [add({ q: 1, r: 2 }, { q: 3, r: 4 })]).each(callback)
     // call run() separately to test that callback is called with the grid returned by each()
     grid1.run()
     expect(callback.mock.calls).toEqual([
@@ -247,8 +247,8 @@ describe('each()', () => {
 
     callback.mockReset()
 
-    const grid2 = new Grid(hexPrototype, [at({ q: 1, r: 2 }), at({ q: 3, r: 4 })])
-      .traverse([at({ q: 5, r: 6 })]) // 👈 now the last traverser
+    const grid2 = new Grid(hexPrototype, [add({ q: 1, r: 2 }, { q: 3, r: 4 })])
+      .traverse([add({ q: 5, r: 6 })]) // 👈 now the last traverser
       .each(callback)
     grid2.run()
     expect(callback.mock.calls).toEqual([[createHex(hexPrototype, { q: 5, r: 6 }), grid2]])
@@ -303,7 +303,7 @@ describe('filter()', () => {
   })
 
   test('filters hexes', () => {
-    const grid = new Grid(hexPrototype, [at({ q: 1, r: 1 }), at({ q: 2, r: 2 }), at({ q: 3, r: 3 })]).filter(
+    const grid = new Grid(hexPrototype, [add({ q: 1, r: 1 }, { q: 2, r: 2 }, { q: 3, r: 3 })]).filter(
       (hex) => hex.q !== 2,
     )
     expect(grid.hexes()).toEqual([createHex(hexPrototype, { q: 1, r: 1 }), createHex(hexPrototype, { q: 3, r: 3 })])
@@ -319,7 +319,7 @@ describe('takeWhile()', () => {
   })
 
   test('stops when the passed predicate returns false', () => {
-    const grid = new Grid(hexPrototype, [at({ q: 1, r: 1 }), at({ q: 2, r: 2 }), at({ q: 3, r: 3 })]).takeWhile(
+    const grid = new Grid(hexPrototype, [add({ q: 1, r: 1 }, { q: 2, r: 2 }, { q: 3, r: 3 })]).takeWhile(
       (hex) => hex.q !== 2,
     )
     expect(grid.hexes()).toEqual([createHex(hexPrototype, { q: 1, r: 1 })])
@@ -386,7 +386,7 @@ describe('traverse()', () => {
 
   test('runs any previous iterators', () => {
     const callback = jest.fn()
-    const grid = new Grid(hexPrototype, at({ q: 1, r: 2 }))
+    const grid = new Grid(hexPrototype, add({ q: 1, r: 2 }))
 
     grid.each(callback).traverse([]).run()
 
@@ -406,9 +406,7 @@ describe('run()', () => {
     const eachCallback = jest.fn()
     const filterCallback = jest.fn((hex) => hex.q > 1)
     const runCallback = jest.fn()
-    const grid = new Grid(hexPrototype, [at({ q: 1, r: 2 }), at({ q: 3, r: 4 })])
-      .each(eachCallback)
-      .filter(filterCallback)
+    const grid = new Grid(hexPrototype, [add({ q: 1, r: 2 }, { q: 3, r: 4 })]).each(eachCallback).filter(filterCallback)
 
     expect(eachCallback).not.toBeCalled()
 

src/grid/traversers/add.test.ts

@@ -0,0 +1,13 @@
+import { Hex } from '../../hex'
+import { add } from './add'
+
+test('accepts coordinates and returns a traverser that returns the hex with those coordinates', () => {
+  const getHex = jest.fn((coordinates) => coordinates)
+
+  expect(add({ q: 1, r: 2 }, { q: 3, r: 4 })({} as Hex, getHex)).toEqual([
+    { q: 1, r: 2 },
+    { q: 3, r: 4 },
+  ])
+  expect(getHex).toBeCalledWith({ q: 1, r: 2 })
+  expect(getHex).toBeCalledWith({ q: 3, r: 4 })
+})

src/grid/traversers/add.ts

@@ -0,0 +1,5 @@
+import { Hex, HexCoordinates } from '../../hex'
+import { Traverser } from '../types'
+
+export const add = <T extends Hex>(...coordinates: HexCoordinates[]): Traverser<T> => (_, getHex) =>
+  coordinates.map((coords) => getHex(coords))

src/grid/traversers/branch.ts

@@ -12,16 +12,16 @@ export const branch = <T extends Hex>(
   branch: Traverser<T> | Traverser<T>[],
 ): Traverser<T> => (cursor, getHex) => {
   const flatBranch = flatTraverse(branch)
-  const result: T[] = []
+  const hexes: T[] = []
   let _cursor = cursor
 
   for (const sourceCursor of flatTraverse(source)(_cursor, getHex)) {
     _cursor = sourceCursor
-    result.push(_cursor)
+    hexes.push(_cursor)
     for (const branchCursor of flatBranch(_cursor, getHex)) {
-      result.push(branchCursor)
+      hexes.push(branchCursor)
     }
   }
 
-  return result
+  return hexes
 }

src/grid/traversers/index.ts

@@ -1,4 +1,4 @@
-export * from './at'
+export * from './add'
 export * from './branch'
 export * from './line'
 export * from './rectangle'

src/grid/traversers/rectangle.ts

@@ -2,7 +2,7 @@ import { Compass, CompassDirection } from '../../compass'
 import { Hex, HexCoordinates, hexToOffset, OffsetCoordinates } from '../../hex'
 import { isOffset } from '../../utils'
 import { Traverser } from '../types'
-import { at } from './at'
+import { add } from './add'
 import { branch } from './branch'
 import { line } from './line'
 
@@ -19,7 +19,7 @@ export function rectangle<T extends Hex>(
       ? optionsFromOpposingCorners(optionsOrCornerA as HexCoordinates, cornerB, cursor.isPointy, cursor.offset)
       : (optionsOrCornerA as RectangleOptions)
 
-    return branch<T>([at(start), line(Compass.rotate(direction, 2), height - 1)], line(direction, width - 1))(
+    return branch<T>([add(start), line(Compass.rotate(direction, 2), height - 1)], line(direction, width - 1))(
       cursor,
       getHex,
     )