feat(hex): add isHex() function and overload corners() to either acce…

…pt a hex or hex settings

isHex() uses the newly added readonly property __isHoneycombHex to determine if the passed value is
a hex (which has this property on its prototype).

playground/render.ts

@@ -7,7 +7,7 @@ const draw = SVG().addTo('body').size('100%', '100%')
 export const render = (hex: Hex) => {
   const { x, y } = hexToPoint(hex)
   const polygon = draw
-    .polygon(corners(hex, hex).map(({ x, y }) => `${x},${y}`))
+    .polygon(corners(hex).map(({ x, y }) => `${x},${y}`))
     .fill('none')
     .stroke({ width: 1, color: '#999' })
   const text = draw

src/hex/functions/corners.ts

@@ -1,6 +1,7 @@
 import { Hex, HexSettings, Orientation, Point } from '../types'
 import { heightFlat, heightPointy } from './height'
 import { hexToPoint } from './hexToPoint'
+import { isHex } from './isHex'
 import { widthFlat, widthPointy } from './width'
 
 export const cornersPointy = (width: number, height: number, { x, y }: Point) => [
@@ -21,9 +22,16 @@ export const cornersFlat = (width: number, height: number, { x, y }: Point) => [
   { x: x - width * 0.25, y: y - height * 0.5 },
 ]
 
-// todo: use separate functions for absolute and relative corners?
-export const corners = ({ orientation, dimensions: { xRadius, yRadius }, origin }: HexSettings, hex?: Hex): Point[] => {
-  const point = hex ? hexToPoint(hex) : origin
+// todo: add to docs that when passed a hex, its corners relative to the "origin hex" are returned (different per hex coordinates)
+// and when passed hexSettings, corners relative to any hex's origin are returned (always the same)
+export function corners(hex: Hex): Point[]
+export function corners(hexSettings: HexSettings): Point[]
+export function corners(hexOrHexSettings: HexSettings): Point[] {
+  const {
+    orientation,
+    dimensions: { xRadius, yRadius },
+  } = hexOrHexSettings
+  const point = isHex(hexOrHexSettings) ? hexToPoint(hexOrHexSettings) : hexOrHexSettings.origin
   return orientation === Orientation.POINTY
     ? cornersPointy(widthPointy(xRadius), heightPointy(yRadius), point)
     : cornersFlat(widthFlat(xRadius), heightFlat(yRadius), point)

src/hex/functions/createHexPrototype.ts

@@ -103,6 +103,7 @@ export const createHexPrototype = <T extends DefaultHexPrototype>(
   // use Object.defineProperties() to create readonly properties
   // origin is set in the final "step"
   Object.defineProperties(prototype, {
+    __isHoneycombHex: { value: true },
     // todo: all props set with `value` are writable (somehow the default `writable: false` doesn't apply). Not sure if this is a problem though
     // see: Object.getOwnPropertyDescriptors(hexPrototype)
     col: {
@@ -112,7 +113,7 @@ export const createHexPrototype = <T extends DefaultHexPrototype>(
     },
     corners: {
       get() {
-        return corners(this, this)
+        return corners(this)
       },
     },
     dimensions: { value: normalizeDimensions(prototype) },

src/hex/functions/index.ts

@@ -7,6 +7,7 @@ export * from './height'
 export * from './hexToOffset'
 export * from './hexToPoint'
 export * from './isFlat'
+export * from './isHex'
 export * from './isPointy'
 export * from './offsetToAxial'
 export * from './width'

src/hex/functions/isHex.ts

@@ -0,0 +1,4 @@
+import { isObject } from '../../utils'
+import { Hex } from '../types'
+
+export const isHex = (value: unknown): value is Hex => isObject<Hex>(value) && !!value.__isHoneycombHex

src/hex/functions/offsetToAxial.ts

@@ -1,12 +1,12 @@
 import { offsetFromZero } from '../../utils'
-import { DefaultHexPrototype, HexCoordinates, OffsetCoordinates } from '../types'
+import { AxialCoordinates, DefaultHexPrototype, OffsetCoordinates } from '../types'
 
-export const offsetToAxialPointy = (col: number, row: number, offset: number): HexCoordinates => ({
+export const offsetToAxialPointy = (col: number, row: number, offset: number): AxialCoordinates => ({
   q: col - offsetFromZero(offset, row),
   r: row,
 })
 
-export const offsetToAxialFlat = (col: number, row: number, offset: number): HexCoordinates => ({
+export const offsetToAxialFlat = (col: number, row: number, offset: number): AxialCoordinates => ({
   q: col,
   r: row - offsetFromZero(offset, col),
 })

src/hex/types.ts

@@ -49,6 +49,7 @@ export interface HexSettings {
 }
 
 export interface DefaultHexPrototype extends HexSettings {
+  readonly __isHoneycombHex: true
   readonly col: number
   readonly corners: Point[]
   readonly height: number

src/utils/isObject.ts

@@ -1,2 +1,5 @@
+/**
+ * In TypeScript: pass a type variable to isObject() for best result. E.g.: `isObject<MyObject>(value)`
+ */
 export const isObject = <T = Record<string, unknown>>(value: unknown): value is T =>
   typeof value === 'object' && value !== null