toBeFeature

[M-Scott-Lassiter]

Description

This is a building block matcher. Features contain Geometry objects and additional properties. We need a way to reliably test that they have been formatted appropriately.

This matcher tests that an object is a valid feature with any geometry type. Any non-conforming values should fail.

• It must have a "type" member equal to 'Feature'
• It must have a "geometry" member with either an object of one of the valid seven geometry types, or the value null
• It must have a "properties" member, but this may be null or an empty object ({}).
• If it has an optional "id" member, it must be either a number (except NaN) or string.

A Feature object represents a spatially bounded thing. Every Feature object is a GeoJSON object no matter where it occurs in a GeoJSON text.

• A Feature object has a "type" member with the value "Feature".
• A Feature object has a member with the name "geometry". The value of the geometry member SHALL be either a Geometry object as defined above or, in the case that the Feature is unlocated, a JSON null value.
• If a Feature has a commonly used identifier, that identifier SHOULD be included as a member of the Feature object with the name "id", and the value of this member is either a JSON string or number.
• A Feature object has a member with the name "properties". The value of the properties member is an object (any JSON object or a JSON null value).

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

Feature objects are prohibited from having a "coordinates", "geometries", 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

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.

Valid GeoJSON Feature Examples

{
    "type": "Feature",
    "bbox": [-10.0, -10.0, 10.0, 10.0],
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-10.0, -10.0],
                [10.0, -10.0],
                [10.0, 10.0],
                [-10.0, -10.0]
            ]
        ]
    },
    "properties": {
        "prop0": "value0",
        "prop1": {
            "this": "that"
        }
    }
}

An empty geometry and properties

{
    "type": "Feature",
    "geometry": null,
    "properties": null
}

{
    "type": "Feature",
    "geometry": null,
    "properties": {}
}

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

This matcher will have an optional argument (geometryType) that can check the geometry is a specific type:

expect(testFeature).toBeFeature(geometryType)

Omitting the type will check for any valid geometry.

const testFeature = {
    "type": "Feature",
    "bbox": [-10.0, -10.0, 10.0, 10.0],
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-10.0, -10.0],
                [10.0, -10.0],
                [10.0, 10.0],
                [-10.0, -10.0]
            ]
        ]
    },
    "properties": {
        "prop0": "value0",
        "prop1": {
            "this": "that"
        }
    }
}
const multiPoint = {
    type: "MultiPoint",
    coordinates: [
        [101.0, 0.0],
        [102.0, 1.0]
    ]
}

expect(testFeature).toBeFeature()
expect(testFeature).toBeFeature('Polygon')

expect(multiPoint).not.toBeFeature()
expect(testFeature).not.toBeFeature('LineString')
expect(testFeature.geometry).not.toBeFeature('Polygon')

Passing Tests

This matcher should use core functions to test coordinate validity.

Values in Range

• A Feature containing each of the seven geometry types
  • With no optional argument (i.e. .toBeFeature())
  • Optional argument specifying the type (i.e. .toBeFeature('Point'))

Geometry May Be a Null Value

const testFeature = {
    type: 'Feature',
    geometry: null,
    properties: {
        prop1: 'Some Prop'
    }
}

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 testFeature = {
    type: 'Feature',
    bbox: <input>,
    geometry: {
        "type": "Polygon",
        "coordinates": [
            [
                [-10.0, -10.0],
                [10.0, -10.0],
                [10.0, 10.0],
                [-10.0, -10.0]
            ]
        ]
    },
    properties: null
}

• Illogical

const testFeature = {
    type: 'Feature',
    bbox: [-30.0, -30.0, -20.0, -20.0],
    geometry: {
        "type": "Polygon",
        "coordinates": [
            [
                [-10.0, -10.0],
                [10.0, -10.0],
                [10.0, 10.0],
                [-10.0, -10.0]
            ]
        ]
    },
    properties: null
}

• Redundant

const testFeature = {
    type: 'Feature',
    bbox: [0, 0, 0, 0],
    geometry: null,
    properties: null
}

Properties May Be a Null Value or Empty Object

const testFeature = {
    type: 'Feature',
    geometry: null,
    properties: null
}

const testFeature = {
    type: 'Feature',
    geometry: null,
    properties: {}
}

Optional ID Must Be String or Number

• Strings: 'ABCD', 'Test 1', '1', '', '[[[180, 10.2, -125], [-180, 90, 35000]]], [{}]'
• Numbers: 0, 200, -200, Infinity, -Infinity,

const testFeature = {
    type: 'Feature',
    id: <input>,
    geometry: null,
    properties: null
}

Foreign Properties Allowed

• Single

const testFeature = {
    type: 'Feature',
    geometry: null,
    properties: null,
    foreign: true
}

• Multiple

const testFeature = {
    type: 'Feature',
    id: '#1',
    geometry: null,
    properties: null,
    foreign1: true,
    foreign2: 33
}

• Foreign property that would normally be a valid GeoJSON object

const multiPoint = {
    type: 'MultiPoint',
    coordinates: [
        [101.0, 0.0],
        [102.0, 1.0]
    ]
}

const testFeature = {
    type: 'Feature',
    geometry: multiPoint,
    properties: null,
    geometryDuplicate: multiPoint,
    Geometry: [] // Note captitalized 'G'
}

Failing Tests

Feature 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: [25, 35, 45000], [ ]
• Strings: '', 'Random Feature'
• Stringified JSON:

  JSON.stringify({
    type: 'Feature',
    geometry: null,
    properties: null
  })

Invalid Geometry

• A Feature containing an invalid version of each of the seven geometry types
  • With no optional argument (i.e. .toBeFeature())
  • Optional argument specifying the type (i.e. .toBeFeature('Point'))

Type Value Incorrect

Input:

• Each of the values from "Feature Input Not an Object", plus
• 'Point', 'MultiPoint', 'LineString', 'MultiLineString' 'Polygon', 'MultiPolygon', and 'GeometryCollection', or
• 'FEATURE', 'feature'

const testFeature = {
    type: <input>,
    geometry: null,
    properties: null
}

Invalid Bounding Box

Input:

• 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 testFeature = {
    type: 'Feature',
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    },
    properties: null,
    bbox: <input>
}

Non-alphanumeric ID

Input:

• undefined
• null
• Booleans: true, false
• Numbers: NaN
• Arrays: [25, 35, 45000], [ ]
• Objects: {prop: 1}, { }

const testFeature = {
    type: 'Feature',
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    },
    properties: null,
    id: <input>
}

Contains Prohibited Properties

Coordinates

const testFeature = {
    type: 'Feature',
    coordinates: [[0, 0], [1, 1, 0]],
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    },
    properties: null
}

Geometries

const testFeature = {
    type: 'Feature',
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    },
    properties: null,
    geometries: [
        {
            type: 'Point',
            coordinates: [102.0, 0.5]
        }, {
            type: 'Point',
            coordinates: [122.0, -10.25]
        }
    ]
}

Features

const testFeature = {
    type: 'Feature',
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    },
    properties: null,
    features: [{
        type: 'Feature',
        geometry: {
            type: 'Point',
            coordinates: [0, 0]
            },
        properties: {
           prop0: 'value0'
        }
    }],
    id: 33
}

Missing Required Properties

• No Type

const testFeature = {
    properties: null,
    geometry: {
        type: 'Point',
        coordinates: [102.0, 0.5]
    }
}

• No Geometry

const testFeature = {
    type: 'Feature',
    properties: null
}

• No Properties

const testFeature = {
    type: 'Feature',
    geometry: null
}

Geometry contained in an array

• Each of the values from "Feature Input Not an Object" except null, plus
• Single Element

const testFeature = {
    type: 'Feature',
    properties: null,
    geometry: [{
        type: 'Point',
        coordinates: [102.0, 0.5]
    }]
}

• Multiple Elements

const testFeature = {
    type: 'Feature',
    properties: null,
    geometry: [{
        type: 'Point',
        coordinates: [102.0, 0.5]
    }, {
        type: 'Point',
        coordinates: [122.0, -10.25]
    }]
}

If Not Null, Properties Must be an Object

• Each of the values from "Feature Input Not an Object" except null

[M-Scott-Lassiter]

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

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