/**
 * Converts an array of coordinate strings into PostgreSQL/PostGIS ST_Point() function calls.
 * This utility is used to generate SQL geometry expressions for spatial database operations.
 *
 * The function expects coordinate strings in "longitude latitude" format separated by a space.
 * It wraps each coordinate pair in a `ST_Point()` function call for use in SQL queries.
 *
 * @param points - Array of coordinate strings in "lon lat" format (e.g., ["-73.935242 40.730610"])
 * @returns {string[]} Array of PostgreSQL/PostGIS ST_Point() function calls
 *
 * @example
 * // Basic usage with single coordinate
 * stPoints(["-73.935242 40.730610"]);
 * // Returns: ["ST_Point(-73.935242,40.730610)"]
 *
 * @example
 * // Multiple coordinates
 * stPoints(["-73.935242 40.730610", "-122.419416 37.774929"]);
 * // Returns: ["ST_Point(-73.935242,40.730610)", "ST_Point(-122.419416,37.774929)"]
 *
 * @example
 * // Usage in SQL query construction
 * const points = stPoints(["-73.935242 40.730610"]);
 * const sql = `SELECT * FROM locations WHERE ST_Distance(location, ${points[0]}) < 1000`;
 *
 * @example
 * // Edge case: Empty array
 * stPoints([]);
 * // Returns: []
 *
 * @example
 * // Edge case: Single coordinate with extra spaces
 * stPoints(["  -73.935242   40.730610  "]);
 * // Returns: ["ST_Point(-73.935242,40.730610)"]
 *
 * @note
 * - Input format: "longitude latitude" (space-separated)
 * - Output format: ST_Point(longitude,latitude)
 * - ST_Point() is a PostGIS function that creates a point geometry
 * - Coordinates are not validated for range or format
 */
export const stPoints = (points: string[]): string[] => {
  // Initialize array to store the ST_Point function calls
  const stpoints: string[] = [];

  // Process each coordinate string in the input array
  points.forEach((element) => {
    // Split the coordinate string by space to separate longitude and latitude
    // Join them back with a comma to create "lon,lat" format for ST_Point()
    const coordinates = element.split(' ').join(',');

    // Create the ST_Point() function call string
    const stPointCall = `ST_Point(${coordinates})`;

    // Add to the results array
    stpoints.push(stPointCall);
  });

  return stpoints;
};

/**
 * Example SQL usage:
 *
 * // Original coordinate array
 * const coordinates = ["-73.935242 40.730610", "-122.419416 37.774929"];
 *
 * // Convert to ST_Point() calls
 * const pointCalls = stPoints(coordinates);
 * // pointCalls = ["ST_Point(-73.935242,40.730610)", "ST_Point(-122.419416,37.774929)"]
 *
 * // Use in SQL query
 * const query = `
 *   INSERT INTO locations (name, geom)
 *   VALUES
 *     ('New York', ${pointCalls[0]}),
 *     ('San Francisco', ${pointCalls[1]})
 * `;
 *
 * // Or in a SELECT query
 * const searchQuery = `
 *   SELECT * FROM locations
 *   WHERE ST_DWithin(
 *     geom,
 *     ${pointCalls[0]},
 *     1000  -- Distance in meters
 *   )
 * `;
 *
 * Security Considerations:
 * 1. This function does not validate coordinate values
 * 2. Consider using parameterized queries to prevent SQL injection
 * 3. For untrusted input, validate coordinates are numeric and within valid ranges
 */
