toBeMultiLineStringGeometry

[M-Scott-Lassiter]

Description

This is a building block matcher. Geometries are the basis of all objects, and we need a way to reliably test that they have been formatted appropriately.

This matcher focuses only on "MultiLineString". All coordinates must be valid coordinates per the WGS-84 standard. Any non-conforming values should fail. However, the "coordinates" property MAY have an empty array ([ ]) as a valid value. It MAY NOT have an array of empty arrays as a value ([ [ ], [ ] ]).

A Geometry object represents points, curves, and surfaces in coordinate space. Every Geometry object is a GeoJSON object no matter where it occurs in a GeoJSON text.

• The value of a Geometry object's "type" member MUST be one of the seven geometry types (per Section 1.4: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", and "GeometryCollection").
• A GeoJSON Geometry object of any type other than "GeometryCollection" has a member with the name "coordinates". The value of the "coordinates" member is an array. The structure of the elements in this array is determined by the type of geometry. GeoJSON processors MAY interpret Geometry objects with empty "coordinates" arrays as null objects.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3.1

For type "MultiLineString", the "coordinates" member is an array of LineString coordinate arrays.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.5

The geometry object should have a "type" and a "coordinates" property. It is prohibited from having a "geometry", "properties", or "features" property.

Implementations MUST NOT change the semantics of GeoJSON members and types.

The GeoJSON "coordinates" and "geometries" members define Geometry objects. FeatureCollection and Feature objects, respectively, MUST NOT contain a "coordinates" or "geometries" member.

The GeoJSON "geometry" and "properties" members define a Feature object. FeatureCollection and Geometry objects, respectively, MUST NOT contain a "geometry" or "properties" member.

The GeoJSON "features" member defines a FeatureCollection object. Feature and Geometry objects, respectively, MUST NOT contain a "features" member.
https://datatracker.ietf.org/doc/html/rfc7946#section-7.1

Although illogical, it is NOT PROHIBITED from having a "geometries" property, although if present it would be considered a foreign member.

Other foreign members ARE allowed (see https://datatracker.ietf.org/doc/html/rfc7946#section-6.1). None of these foreign members should get checked for validity of any type; they may contain anything that is valid JSON.

See GeoJSON Spec: What does it mean to extend GeoJSON without using a foreign member? for further clarification.

Bounding boxes, if present, must validate (see isValidBoundingBox).

A GeoJSON object represents a Geometry, Feature, or collection of Features.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3

A GeoJSON object MAY have a member named "bbox" to include information on the coordinate range for its Geometries, Features, or FeatureCollections.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-5

Valid GeoJSON MultiLineString Examples

Multiple Points:

    {
        "type": "MultiLineString",
        "coordinates": [
            [
                [101.0, 1.0]
            ],
            [
                [102.0, 2.0],
                [103.0, 3.0]
            ]
        ]
    }

An empty coordinates

{
    "type": "MultiLineString",
    "coordinates": [ ]
}

Contained as an object within a geometries array on a GeometryCollection:

{
    "type": "GeometryCollection",
    "geometries": [{
        "type": "MultiLineString",
        "coordinates": [
            [
                [100.0, 0.0, 0],
                [101.0, 1.0, 0]
            ],
            [
                [102.0, 2.0, 0],
                [103.0, 3.0, 0]
            ]
        ]
    }, {
        "type": "MultiPoint",
        "coordinates": [
            [101.0, 0.0],
            [102.0, 1.0]
        ]
    }]
}

In each case, the matcher should only get passed the object in its entirety, not the individual components, and not as part of another collection object.

Example Matcher Usage

const multiLineString = {
    "type": "MultiLineString",
    "coordinates": [
        [
            [100.0, 0.0],
            [101.0, 1.0]
        ],
        [
            [102.0, 2.0],
            [103.0, 3.0]
        ]
    ]
}
const multiPoint = {
    type: "MultiPoint",
    coordinates: [
        [101.0, 0.0],
        [102.0, 1.0]
    ]
}

expect(multiLineString).toBeMultiLineStringGeometry()

expect(multiPoint).not.toBeMultiLineStringGeometry()
expect(multiLineString.coordinates).not.toBeMultiLineStringGeometry()

Passing Tests

This matcher should use core functions to test coordinate validity. Either two or three digit coordinates are allowed.

Values in Range

• 2D: [[[0, 1], [0, 2]], [[1, 0], [2, 0], [3, 0]]]

• 3D: [[[2, 20, 0], [4, 10, 0]], [[3, 0.0, 0], [6, -10, 0], [9, -20, 0]]]

• Mixed: [[[100.0, 0.0], [90, 0.0, 0]], [[100.0, 0.0, 0], [110, 5], [100.0, 11.33, 259]]]

• Single LineString: [[[180.0, 40.0], [180.0, 50.0], [170.0, 50.0], [170.0, 40.0], [180.0, 40.0]]]

• Antimeridian: [[[175, 0], [-175, 0]], [[-175, 0], [175, 0]]]

  • Note that both of these are only implied to cross the antimeridian due to proximity. The actual standard assumes these would span 350 degrees. Either way, they are valid coordinate arrays.

• Repeated and Redundant: [[[0, 0], [0, 0], [0, 0]], [[0, 0], [0, 0], [0, 0]]]

• Stressed: A 30 element array, each element being an array of 30 coordinates

  const testMultiLineString = {
      type: "MultiLineString",
      coordinates: <input>
  }

• Empty Coordinate

const testMultiLineString = {
    type: "MultiLineString",
    coordinates: [ ]
}

Foreign Properties Allowed

• ID (String and number input: 'Test 1', 1

const testMultiLineString = {
    type: "MultiLineString",
    id: <input>,
    coordinates: [[[25, 90], [-180, 0]]]
}

• Non alphanumeric ID
  ID Normally needs to be a letter or number, but because it is a foreign member on a geometry object, the GeoJSON standard takes no consideration about it.

const testMultiLineString1 = {
    type: "MultiLineString",
    id: null,
    coordinates: [[[25, 90], [-180, 0]]]
}

• Geometries

const testMultiLineString2 = {
    type: "MultiLineString",
    geometries: testMultiLineString1,
    coordinates: [[[-100.0, -15.0, 2000], [0, 0]]]
}

• Multiple

const testMultiLineString3 = {
    type: "MultiLineString",
    someRandomProp: true,
    geometries: testMultiLineString2,
    coordinates: [[[180, 10.2, -125], [-180, 90, 35000]]]
}

May Have Optional Bounding Box

• Logical
  • 2D: [-10.0, -10.0, 10.0, 10.0]
  • 3D: [-10.0, -10.0, 0, 10.0, 10.0, 200]

const testMultiLineString = {
    type: 'MultiLineString',
    coordinates: [[[0, 0], [-5, -5]]],
    bbox: <input>
}

• Illogical

const testMultiLineString = {
    type: 'MultiLineString',
    coordinates: [[[0, 0], [-5, -5]]],
    bbox: [-30.0, -30.0, -20.0, -20.0]
}

• Redundant

const testMultiLineString = {
    type: 'MultiLineString',
    coordinates: [[[0, 0], [-5, -5]]],
    bbox: [0, 0, 0, 0]
}

Failing Tests

Geometry Input Not an Object

Any of the following inputs to the matcher should fail:

• undefined
• null
• Booleans: true, false
• Numbers: 200, -200, Infinity, -Infinity, NaN
• Arrays:
  • [[[180, 10.2, -125], [-180, 90, 35000]]], [ ]
• Strings: '', 'Random Geometry', '[0, 0]', '[[[0, 0], [0, 0]]]'
• Stringified JSON:

  JSON.stringify({
    type: "MultiLineString",
    coordinates: [[[25, 90], [2, 2]]]
  })

Invalid Coordinates

• Each of the values from "Geometry Input Not an Object":

const testMultiLineString= {
    type: "MultiLineString",
    coordinates: [[[0, 0], <input>]]
}

Coordinates Out of Range

This only tests a handful of invalid coordinates to verify behavior. Detailed coordinate validation occurs in isValidCoordinate

Input:

• [[[181, 0], [0, 1], [1, 1], [1, 0], [181, 0]]]
• [[[0, 0], [0, 91], [1, 1], [1, 0], [0, 0]]]
• [[[0, 0], [0, 1], [-181, 1], [1, 0], [0, 0]]]
• [[[0, -181], [0, 1], [1, 1], [1, 0], [0, -181]]]
• [[[0, 0, 0, 0]]]

const testMultiLineString= {
    type: "MultiLineString",
    coordinates: <input>
}

Single Coordinates

• The each polygon linestring array in coordinates must have two or more positions.

const testMultiLineString= {
    type: "MultiLineString",
    coordinates: [[[0, 0]]]
}

Type Value Incorrect

Input:

• Each of the values from "Geometry Input Not an Object", plus
• 'Point', 'MultiPoint', 'LineString', 'Polygon', 'MultiPolygon', and 'GeometryCollection', or
• 'MULTILINESTRING', 'multilinestring'

const testMultiLineString = {
    type: <input>,
    coordinates: [[[0, 0], [1, 1, 0]]]
}

Contains Prohibited Properties

Geometry

const testMultiLineString = {
    type: "MultiLineString",
    coordinates: [[[0, 0], [1, 1, 0]]],
    geometry: {
        type: "Point",
        coordinates: [102.0, 0.5]
    }
}

Properties

const testMultiLineString = {
    type: "MultiLineString",
    coordinates: [[[0, 0], [1, 1, 0]]],
    properties: {
        prop1: true
    }
}

Features

const testPolygon = {
    type: "Polygon",
    coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]],
    features: [{
        type: "Feature",
        geometry: {
            type: "Point",
            coordinates: [102.0, 0.5]
            },
        properties: {
           prop0: "value0"
        }
    }]
}

Missing Required Properties

• No Type

const testMultiLineString = {
    coordinates: [[[0, 0], [1, 1, 0]]]
}

• No Coordinates

const testMultiLineString = {
    type: "MultiLineString"
}

Coordinates is an Array of Null Arrays

• Test for 1x, 2x, 3x
• No Type

const testMultiLineString = {
    type: "MultiLineString",
    coordinates: [[<arrays>]]
}

Invalid Bounding Box

• null
• undefined
• []
• Missing Element: [-10.0, -10.0, 10.0]
• Out of Range Element: [-10.0, -10.0, 190.0, 10.0]
• South Greater than North: [-10.0, 10.0, 10.0, -10]
• Bad altitude: [-10.0, -10.0, 0, 10, 10.0, '200']

const testPoint = {
    type: 'MultiLineString',
    coordinates: [[[0, 0], [-5, -5]]],
    bbox: <input>
}

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0-beta.9 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[M-Scott-Lassiter]

Reopening to add coverage to validate optional bounding boxes.

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0-beta.14 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀