toBePointGeometry

[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 "Point". 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.

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 "Point", the "coordinates" member is a single position.
https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.2

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 Point Geometry Examples

A two dimensional of point:

{
    "type": "Point",
    "coordinates": [100.0, 0.0]
}

A three dimensional of point:

{
    "type": "Point",
    "coordinates": [100.0, 0.0, 2000]
}

An empty coordinate

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

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

{
    "type": "GeometryCollection",
    "geometries": [{
        "type": "Point",
        "coordinates": [100.0, 0.0]
    }, {
        "type": "LineString",
        "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 point1 = {
    type: "Point",
    coordinates: [100.0, 0.0]
}
const point2 = {
    type: "Point",
    coordinates: [100.0, 0.0, 2000]
}
const point3 = {
    type: "LineString",
    coordinates: [
        [101.0, 0.0],
        [102.0, 1.0]
    ]
}

expect(point1).toBePointGeometry()
expect(point2).toBePointGeometry()

expect(point3).not.toBePointGeometry()
expect([22, -34.549, 22]).not.toBePointGeometry()
expect({coordinates: [100.0, 0.0]}).not.toBePointGeometry()

Passing Tests

This matcher does not test coordinate validity. Either two or three digit coordinates are allowed.

Values in Range

• 2D Point

const testPoint = {
    type: "Point",
    coordinates: [25, 10.2]
}

• 3D Point

const testPoint = {
    type: "Point",
    coordinates: [-100.0, -15.0, 2000]
}

• Empty Coordinate

const testPoint = {
    type: "Point",
    coordinates: [ ]
}

Foreign Properties Allowed

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

const testPoint = {
    type: "Point",
    id: <input>,
    coordinates: [25, 90]
}

• 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 testPoint1 = {
    type: "Point",
    id: null,
    coordinates: [25, 90]
}

• Geometries

const testPoint2 = {
    type: "Point",
    geometries: testPoint1,
    coordinates: [-100.0, -15.0, 2000]
}

• Multiple

const testPoint3 = {
    type: "Point",
    someRandomProp: true,
    geometries: testPoint2,
    coordinates: [180, 10.2, -125]
}

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

• Illogical

const testPoint = {
    type: 'Point',
    bbox: [-30.0, -30.0, -20.0, -20.0],
    coordinates: [0, 0]
}

• Redundant

const testPoint = {
    type: 'Point',
    bbox: [0, 0, 0, 0],
    coordinates: [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: [{ coordinates: [0, 0] }]
• Strings: '', 'Random Geometry', '[0, 0]', '[[0, 0], [0, 0]]'
• Stringified JSON:

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

Invalid Coordinates

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

const testPoint = {
    type: "Point",
    coordinates: <input>
}

Coordinates Out of Range

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

Input: [181, 91], [181, -91], [-181, 91, 0], [-181, -91, 200], [0, 0, 0, 0]

const testPoint = {
    type: "Point",
    coordinates: <input>
}

Type Value Incorrect

Input:

• Each of the values from "Geometry Input Not an Object", plus
• 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', 'MultiPolygon', and 'GeometryCollection', or
• 'POINT', 'point'

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

Contains Prohibited Properties

Geometry

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

Properties

const testPoint = {
    type: "Point",
    coordinates: [0, 0],
    properties: {
        prop1: true
    }
}

Features

const testPoint = {
    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 testPoint = {
    coordinates: [0, 0]
}

• No Coordinates

const testPoint = {
    type: "Point"
}

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: 'Point',
    coordinates: [0, 0],
    bbox: <input>
}

[M-Scott-Lassiter]

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

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