toBeGeometryCollection

[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 "GeometryCollection". All geometries within the "geometries" array must be valid GeoJSON geometry objects. Any non-conforming values should fail.

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

However, the "geometries" property MAY have an empty array ([ ]) as a valid value. It MAY NOT have an array of empty objects as a value.

A GeoJSON object with type "GeometryCollection" is a Geometry object. A GeometryCollection has a member with the name "geometries". The value of "geometries" is an array. Each element of this array is a GeoJSON Geometry object. It is possible for this array to be empty.

Unlike the other geometry types described above, a GeometryCollection can be a heterogeneous composition of smaller Geometry objects. For example, a Geometry object in the shape of a lowercase roman "i" can be composed of one point and one LineString.

GeometryCollections have a different syntax from single type Geometry objects (Point, LineString, and Polygon) and homogeneously typed multipart Geometry objects (MultiPoint, MultiLineString, and MultiPolygon) but have no different semantics. Although a GeometryCollection object has no "coordinates" member, it does have coordinates: the coordinates of all its parts belong to the collection. The "geometries" member of a GeometryCollection describes the parts of this composition. Implementations SHOULD NOT apply any additional semantics to the "geometries" array.

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

GeometryCollections MAY have as one of their geometries another GeometryCollection. This is recommended against by the spec, but not prohibited.

To maximize interoperability, implementations SHOULD avoid nested GeometryCollections. Furthermore, GeometryCollections composed of a single part or a number of parts of a single type SHOULD be avoided when that single part or a single object of multipart type (MultiPoint, MultiLineString, or MultiPolygon) could be used instead.

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

The GeometryCollection object should have a "type" and a "geometries" 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 "coordinates" member. If present, it should be treated as 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 GeometryCollection Examples

{
    "type": "GeometryCollection",
    "geometries": [{
        "type": "Point",
        "coordinates": [100.0, 0.0]
    }, {
        "type": "LineString",
        "coordinates": [
            [101.0, 0.0],
            [102.0, 1.0]
        ]
    }, {
        "type": "Polygon",
        "coordinates": [
            [
                [102.0, 2.0],
                [103.0, 2.0],
                [103.0, 3.0],
                [102.0, 3.0],
                [102.0, 2.0]
            ]
        ]
    }, {
        "type": "Point",
        "coordinates": [150.0, 73.0]
    }]
}

An empty coordinates

{
    "type": "GeometryCollection",
    "geometries": [ ]
}

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 geometryCollection = {
    type: 'GeometryCollection',
    geometries: [{
        "type": 'Point',
        "coordinates": [100.0, 0.0]
    }, {
        type: 'LineString',
        coordinates: [
            [101.0, 0.0],
            [102.0, 1.0]
        ]
    }, {
        type: 'Polygon',
        coordinates: [
            [
                [102.0, 2.0],
                [103.0, 2.0],
                [103.0, 3.0],
                [102.0, 3.0],
                [102.0, 2.0]
            ]
        ]
    }, {
        type: 'Point',
        coordinates: [150.0, 73.0]
    }]
}

expect(geometryCollection).toBeGeometryCollection()

expect(geometryCollection.geometries).not.toBeMultiPolygonGeometry()
expect(geometryCollection.geometries[1]).not.toBeMultiPolygonGeometry()

Passing Tests

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

Values in Range

• Contains 1 or 10 elements of a single type of each of the six geometries
• Contains 1 element of each of all six geometries
• Contains 10 elements of each of all six geometries
• Contains another geometry collection
• Contains multiple nested geometry collections

Empty Geometries

const testGeometryCollection = {
    type: "GeometryCollection",
    geometries: [ ]
}

Foreign Properties Allowed

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

const testGeometryCollection = {
    type: "GeometryCollection",
    id: <input>,
    geometries: ...
}

• Multiple

const testGeometryCollection = {
    type: "GeometryCollection",
    someRandomProp: true,
    geometries: [{
        type: "Point",
        coordinates: [5, 15]
    }],
    otherProp: [5, 15]
}

Nested GeometryCollections

const testGeometryCollection = {
    type: "GeometryCollection",
    geometries: [{
        type: "GeometryCollection",
        geometries: [{
            type: "GeometryCollection",
            geometries: [{
                type: "Point",
                coordinates: [5, 15]
            }]
        }, {
            type: "Point",
            coordinates: [10, 20]
        }]
    }, {
        type: "Point",
        coordinates: [20, 25]
    }]
}

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 testGeometryCollection = {
    type: 'GeometryCollection',
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0]
    }],
    bbox: <input>
}

• Illogical

const testGeometryCollection = {
    type: 'GeometryCollection',
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0]
    }],
    bbox: [-30.0, -30.0, -20.0, -20.0]
}

• Redundant

const testGeometryCollection = {
    type: 'GeometryCollection',
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0]
    }],
    bbox: [0, 0, 0, 0]
}

Coordinates Treated as Foreign Member

• Input: [0, 0], false, {}, 2, 'Coordinate String'

const testGeometryCollection = {
    type: 'GeometryCollection',
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0]
    }],
    coordinates: <input>
}

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:
  • [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
  • [1, 1]
• Strings: '', 'Random Geometry', '[0, 0]'
• Stringified JSON:

  JSON.stringify({
    "type": "GeometryCollection",
    "geometries": [{
        "type": "Point",
        "coordinates": [100.0, 0.0]
    }]
  })

Invalid Geometries

Should fail when "geometries":

• Is a single bad element of each geometry
• Is a good geometry of each element mixed with a bad geometry

Type Value Incorrect

Input:

• Each of the values from "Geometry Input Not an Object", plus
• 'Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', and 'MultiPolygon', or
• 'GEOMETRYCOLLECTION', 'geometrycollection'

{
    type: <input>,
    geometries: [{
        "type": "Point",
        "coordinates": [-180, 90, 2000]
    }]
}

Contains Prohibited Properties

Geometry

const testGeometryCollection = {
    type: "GeometryCollection",
    geometries: [{
        "type": "Point",
        "coordinates": [180, -90, 2000]
    }],
    geometry: {
        type: "Point",
        coordinates: [102.0, 0.5]
    }
}

Properties

const testGeometryCollection = {
    type: "GeometryCollection",
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0, -2000]
    }],
    properties: {
        prop1: true
    }
}

Features

const testGeometryCollection = {
    type: "GeometryCollection",
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0]
    }],
    features: [{
        type: "Feature",
        geometry: {
            type: "Point",
            coordinates: [102.0, 0.5]
            },
        properties: {
           prop0: "value0"
        }
    }]
}

Missing Required Properties

• No Type

const testGeometryCollection = {
    geometries: [{
        "type": "Point",
        "coordinates": [0, 0]
    }]
}

• No Geometries

const testGeometryCollection = {
    type: "GeometryCollection"
}

Geometries is an Array or Object of Null Arrays/Objects

• Inputs:
  • [[]]
  • [[], []]
  • [{}, {}]
  • {}

const testGeometryCollection = {
    type: "GeometryCollection",
    geometries: <input>
}

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 testGeometryCollection = {
    type: 'GeometryCollection',
    geometries: [
                    {
                        type: 'Point',
                        coordinates: [180, -90, 2000]
                    }
                ],
    bbox: <input>
}

[M-Scott-Lassiter]

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

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 📦🚀