feat(grid): add spiral() traverser

Like most traversers it accepts an `at` and `start` option and a `radius` and `rotation` options. It
always starts at the cursor (or `at`/`start`) and spirals outward until the required radius is
reached (in Northern direction of the first hex).

src/grid/traversers/index.ts

@@ -3,3 +3,4 @@ export * from './branch'
 export * from './line'
 export * from './rectangle'
 export * from './ring'
+export * from './spiral'

src/grid/traversers/ring.ts

@@ -1,7 +1,7 @@
 import { Hex, HexCoordinates } from '../../hex'
 import { assertCubeCoordinates } from '../../utils'
 import { distance } from '../functions'
-import { Traverser } from '../types'
+import { Rotation, Traverser } from '../types'
 
 export const ring = <T extends Hex>({ start, at, center, rotation }: RingOptions): Traverser<T, T[]> => (
   cursor,
@@ -38,11 +38,6 @@ export const ring = <T extends Hex>({ start, at, center, rotation }: RingOptions
   return hexes.slice(startIndex + (start ? 0 : 1)).concat(hexes.slice(0, startIndex))
 }
 
-export enum Rotation {
-  CLOCKWISE = 'CLOCKWISE',
-  COUNTERCLOCKWISE = 'COUNTERCLOCKWISE',
-}
-
 export interface RingOptions {
   center: HexCoordinates
   start?: HexCoordinates

src/grid/traversers/spiral.test.ts

@@ -0,0 +1,107 @@
+import { createHex, createHexPrototype } from '../../hex'
+import { spiral } from './spiral'
+
+const hexPrototype = createHexPrototype()
+const getHex = jest.fn((coordinates) => createHex(hexPrototype, coordinates))
+const cursor = createHex(hexPrototype, { q: 1, r: 2 })
+
+describe('when called with a radius', () => {
+  test('returns a traverser that returns hexes in a spiral around but excluding the cursor', () => {
+    expect(spiral({ radius: 2 })(cursor, getHex)).toEqual([
+      cursor.clone({ q: 2, r: 1 }),
+      cursor.clone({ q: 2, r: 2 }),
+      cursor.clone({ q: 1, r: 3 }),
+      cursor.clone({ q: 0, r: 3 }),
+      cursor.clone({ q: 0, r: 2 }),
+      cursor.clone({ q: 1, r: 1 }),
+      cursor.clone({ q: 2, r: 0 }),
+      cursor.clone({ q: 3, r: 0 }),
+      cursor.clone({ q: 3, r: 1 }),
+      cursor.clone({ q: 3, r: 2 }),
+      cursor.clone({ q: 2, r: 3 }),
+      cursor.clone({ q: 1, r: 4 }),
+      cursor.clone({ q: 0, r: 4 }),
+      cursor.clone({ q: -1, r: 4 }),
+      cursor.clone({ q: -1, r: 3 }),
+      cursor.clone({ q: -1, r: 2 }),
+      cursor.clone({ q: 0, r: 1 }),
+      cursor.clone({ q: 1, r: 0 }),
+    ])
+  })
+})
+
+describe('when called with at coordinates', () => {
+  test('returns a traverser that returns hexes in a spiral around but excluding the "at" coordinates', () => {
+    expect(spiral({ at: { q: 1, r: 3 }, radius: 2 })(cursor, getHex)).toEqual([
+      cursor.clone({ q: 1, r: 2 }),
+      cursor.clone({ q: 2, r: 2 }),
+      cursor.clone({ q: 2, r: 3 }),
+      cursor.clone({ q: 1, r: 4 }),
+      cursor.clone({ q: 0, r: 4 }),
+      cursor.clone({ q: 0, r: 3 }),
+      cursor.clone({ q: 2, r: 1 }),
+      cursor.clone({ q: 3, r: 1 }),
+      cursor.clone({ q: 3, r: 2 }),
+      cursor.clone({ q: 3, r: 3 }),
+      cursor.clone({ q: 2, r: 4 }),
+      cursor.clone({ q: 1, r: 5 }),
+      cursor.clone({ q: 0, r: 5 }),
+      cursor.clone({ q: -1, r: 5 }),
+      cursor.clone({ q: -1, r: 4 }),
+      cursor.clone({ q: -1, r: 3 }),
+      cursor.clone({ q: 0, r: 2 }),
+      cursor.clone({ q: 1, r: 1 }),
+    ])
+  })
+})
+
+describe('when called with start coordinates', () => {
+  test('returns a traverser that returns hexes in a spiral around and including the "start" coordinates', () => {
+    expect(spiral({ start: { q: 2, r: 1 }, radius: 2 })(cursor, getHex)).toEqual([
+      cursor.clone({ q: 2, r: 1 }),
+      cursor.clone({ q: 2, r: 0 }),
+      cursor.clone({ q: 3, r: 0 }),
+      cursor.clone({ q: 3, r: 1 }),
+      cursor.clone({ q: 2, r: 2 }),
+      cursor.clone({ q: 1, r: 2 }),
+      cursor.clone({ q: 1, r: 1 }),
+      cursor.clone({ q: 3, r: -1 }),
+      cursor.clone({ q: 4, r: -1 }),
+      cursor.clone({ q: 4, r: 0 }),
+      cursor.clone({ q: 4, r: 1 }),
+      cursor.clone({ q: 3, r: 2 }),
+      cursor.clone({ q: 2, r: 3 }),
+      cursor.clone({ q: 1, r: 3 }),
+      cursor.clone({ q: 0, r: 3 }),
+      cursor.clone({ q: 0, r: 2 }),
+      cursor.clone({ q: 0, r: 1 }),
+      cursor.clone({ q: 1, r: 0 }),
+      cursor.clone({ q: 2, r: -1 }),
+    ])
+  })
+})
+
+describe('when called with a counterclockwise rotation', () => {
+  test('returns a traverser that returns hexes in a spiral around the cursor in a counterclockwise rotation', () => {
+    expect(spiral({ radius: 2, rotation: 'counterclockwise' })(cursor, getHex)).toEqual([
+      cursor.clone({ q: 2, r: 1 }),
+      cursor.clone({ q: 1, r: 1 }),
+      cursor.clone({ q: 0, r: 2 }),
+      cursor.clone({ q: 0, r: 3 }),
+      cursor.clone({ q: 1, r: 3 }),
+      cursor.clone({ q: 2, r: 2 }),
+      cursor.clone({ q: 2, r: 0 }),
+      cursor.clone({ q: 1, r: 0 }),
+      cursor.clone({ q: 0, r: 1 }),
+      cursor.clone({ q: -1, r: 2 }),
+      cursor.clone({ q: -1, r: 3 }),
+      cursor.clone({ q: -1, r: 4 }),
+      cursor.clone({ q: 0, r: 4 }),
+      cursor.clone({ q: 1, r: 4 }),
+      cursor.clone({ q: 2, r: 3 }),
+      cursor.clone({ q: 3, r: 2 }),
+      cursor.clone({ q: 3, r: 1 }),
+      cursor.clone({ q: 3, r: 0 }),
+    ])
+  })
+})

src/grid/traversers/spiral.ts

@@ -0,0 +1,24 @@
+import { CompassDirection } from '../../compass'
+import { Hex, HexCoordinates } from '../../hex'
+import { Rotation, Traverser } from '../types'
+import { branch } from './branch'
+import { line } from './line'
+import { ring } from './ring'
+
+export const spiral = <T extends Hex>({ radius, start, at, rotation }: SpiralOptions): Traverser<T, T[]> => (
+  cursor,
+  getHex,
+) => {
+  const center = start ? getHex(start) : at ? getHex(at) : cursor
+  return branch<T>(line({ start, at, direction: CompassDirection.N, length: radius }), ring({ center, rotation }))(
+    getHex(center),
+    getHex,
+  )
+}
+
+export interface SpiralOptions {
+  radius: number
+  start?: HexCoordinates
+  at?: HexCoordinates
+  rotation?: Rotation | 'CLOCKWISE' | 'clockwise' | 'COUNTERCLOCKWISE' | 'counterclockwise'
+}

src/grid/types.ts

@@ -8,3 +8,8 @@ export interface Traverser<T extends Hex, R extends Iterable<T> = Iterable<T>> {
 export interface Callback<T extends Hex, R> {
   (hex: T, grid: Grid<T>): R
 }
+
+export enum Rotation {
+  CLOCKWISE = 'CLOCKWISE',
+  COUNTERCLOCKWISE = 'COUNTERCLOCKWISE',
+}