shared-position-utils.js

// Shared position utilities for handling coordinate-based logic

/**
 * Compare two position objects for equality
 * @param {Object} pos1 - First position {x, y}
 * @param {Object} pos2 - Second position {x, y}
 * @returns {boolean} - True if positions are equal
 */
function positionsEqual(pos1, pos2) {
  if (!pos1 || !pos2) return false;
  return pos1.x === pos2.x && pos1.y === pos2.y;
}

/**
 * Find an item in an array by its position
 * @param {Array} array - Array of objects with position property
 * @param {Object} targetPosition - Target position {x, y}
 * @returns {Object|undefined} - Found item or undefined
 */
function findByPosition(array, targetPosition) {
  return array.find(item => positionsEqual(item.position, targetPosition));
}

/**
 * Filter array items that match a specific position
 * @param {Array} array - Array of objects with position property
 * @param {Object} targetPosition - Target position {x, y}
 * @returns {Array} - Array of matching items
 */
function filterByPosition(array, targetPosition) {
  return array.filter(item => positionsEqual(item.position, targetPosition));
}

/**
 * Check if a position exists in an array of positioned objects
 * @param {Array} array - Array of objects with position property
 * @param {Object} targetPosition - Target position {x, y}
 * @returns {boolean} - True if position exists in array
 */
function positionExists(array, targetPosition) {
  return array.some(item => positionsEqual(item.position, targetPosition));
}

/**
 * Generate a string identifier from position (for UI keys, maps, etc.)
 * @param {Object} position - Position {x, y}
 * @returns {string} - Position string like "x-y"
 */
function positionToString(position) {
  return `${position.x}-${position.y}`;
}

/**
 * Parse a position string back to position object
 * @param {string} positionString - Position string like "x-y"
 * @returns {Object} - Position {x, y}
 */
function stringToPosition(positionString) {
  const [x, y] = positionString.split('-').map(Number);
  return { x, y };
}

module.exports = {
  positionsEqual,
  findByPosition,
  filterByPosition,
  positionExists,
  positionToString,
  stringToPosition
};