Skip to content

Commit

Permalink
feat: add Typescript support for the matchers
Browse files Browse the repository at this point in the history
Added a `index.d.ts` file and referenced it in the `package.json`. Included build files for this
project, and instructions in README, CONTRIBUTING, and the PR template for how to ensure future
definitions get included.

Resolves: #42
  • Loading branch information
M-Scott-Lassiter committed Jun 9, 2022
1 parent 397d8ef commit 602c33b
Show file tree
Hide file tree
Showing 17 changed files with 261 additions and 15 deletions.
5 changes: 3 additions & 2 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ Please check if your PR fulfills the following requirements:
- <u>Create Matcher Function</u>
- [ ] Create a matcher function under `src/matchers/<category>`
- [ ] Register the matcher in `src/matchers.js`
- [ ] Add a verification test to `matchers.test.js`
- [ ] Add the matcher to the `.cz-config.js` list (alphabetical order under the `coordinateMatchers` variable)
- [ ] Add a verification test to `tests/matchers.test.js`
- [ ] Add the matcher to `src/index.d.ts`
- [ ] Add the matcher to the `.cz-config.js` list (alphabetical order under the `allMatchers` variable)
- [ ] Document the matcher using JSDoc. Refer to the issue. Include good and bad examples.
- [ ] Create a test for the matcher under `tests/<category>`
- [ ] Verify all tests pass and have 100% coverage
Expand Down
1 change: 0 additions & 1 deletion .lintstagedrc
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
{
"**/*.{js,ts}": ["npm run lint"],
"**/*.{js,jsx,ts,tsx,json,html,css,scss,md,yml}": ["npm run format"]
}
6 changes: 4 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ After installing, you should [run the build script](#building) to verify everyth
- `setup`: contains the scripts that install the matchers into the Jest runtime
- `core.js` and `matchers.js`: export a single object containing their categories as object members, each with their respective functions
- `typedefinitions.js`: documents the project's JSDoc type definitions and contains no actual code
- `index.d.ts`: Typescript definitions for the matchers
- `tests`: the Jest scripts used to verify the matchers work as designed

`package.json` contains entry points for `core.js`, `matchers.js`, and each of the loading scripts in `setup`.
Expand Down Expand Up @@ -188,8 +189,9 @@ npm run tableofcontents
- <u>Create Matcher Function</u>
- [ ] Create a matcher function under `src/matchers/<category>`
- [ ] Register the matcher in `src/matchers.js`
- [ ] Add a verification test to `matchers.test.js`
- [ ] Add the matcher to the `.cz-config.js` list (alphabetical order under the `coordinateMatchers` variable)
- [ ] Add a verification test to `tests/matchers.test.js`
- [ ] Add the matcher to `src/index.d.ts`
- [ ] Add the matcher to the `.cz-config.js` list (alphabetical order under the `allMatchers` variable)
- [ ] Document the matcher using JSDoc. Refer to the issue. Include good and bad examples.
- [ ] Create a test for the matcher under `tests/<category>`
- [ ] Verify all tests pass and have 100% coverage
Expand Down
21 changes: 21 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
- [Getting Started](#getting-started)
- [Install as a Dependency](#install-as-a-dependency)
- [Configure Jest](#configure-jest)
- [Configure Typescript](#configure-typescript)
- [Matchers](#matchers)
- [Coordiantes](#coordiantes)
- [Bounding Boxes](#bounding-boxes)
Expand Down Expand Up @@ -114,6 +115,26 @@ or add a key to your `package.json`:
}
```

## Configure Typescript

If your editor does not recognize the custom `Jest-GeoJSON` matchers, add a `global.d.ts` file to your project with:

```typescript
import 'jest-geojson'
```

Then add a `files` key in your `tsconfig.json`:

```json
{
"compilerOptions": {
...
},
...
"files": ["global.d.ts"]
}
```

# Matchers

`Jest-GeoJSON` organizes matchers by categories. Most correspond to the expected input type passed to `expect()`. For example, the Coordinates matchers expect a coordinate array, and geometry matchers expect a GeoJSON geometry object.
Expand Down
4 changes: 2 additions & 2 deletions docs/Matchers.Functional.html
Original file line number Diff line number Diff line change
Expand Up @@ -337,8 +337,8 @@ <h4 class="name" id=".toBeValidGeoJSON">
<a href="matchers_functional_toBeValidGeoJSON.js.html"
>matchers/functional/toBeValidGeoJSON.js</a
>,
<a href="matchers_functional_toBeValidGeoJSON.js.html#line93"
>line 93</a
<a href="matchers_functional_toBeValidGeoJSON.js.html#line92"
>line 92</a
>
</li>
</ul>
Expand Down
4 changes: 2 additions & 2 deletions docs/Matchers.Geometries.html
Original file line number Diff line number Diff line change
Expand Up @@ -371,7 +371,7 @@ <h4 class="name" id=".toBeAnyGeometry">
<div class="description usertext">
Verifies an object meets validity requirements for one of the six basic
GeoJSON geometry types: Point, MultiPoint, LineString, MultiLineString,
Polygon, MultiPolygon, GeometryCollection
Polygon, MultiPolygon, GeometryCollection.
</div>

<h5>Examples</h5>
Expand Down Expand Up @@ -491,7 +491,7 @@ <h4 class="name" id=".toBeGeometryCollection">
Verifies an object is a valid GeoJSON GeometryCollection. This object
requires a 'type' property that must equal "GeometryCollection", and a
'geometries' property that contains an array of GeoJSON Geometry objects
(Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon) The
(Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon). The
geometries may be an empty array, but may not be an array of empty arrays or
objects. Foreign members are allowed with the exception of 'geometry',
'properties', or 'features'. If present, bounding boxes must be valid.
Expand Down
20 changes: 20 additions & 0 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -406,6 +406,9 @@ <h3></h3>
>
</li>
<li><a href="#configure-jest">Configure Jest</a></li>
<li>
<a href="#configure-typescript">Configure Typescript</a>
</li>
</ul>
</li>
<li>
Expand Down Expand Up @@ -508,6 +511,23 @@ <h2>Configure Jest</h2>
&quot;setupFilesAfterEnv&quot;: [&quot;jest-geojson/setup/all&quot;]
}
}
</code></pre>
<h2>Configure Typescript</h2>
<p>
If your editor does not recognize the custom
<code>Jest-GeoJSON</code> matchers, add a <code>global.d.ts</code> file to
your project with:
</p>
<pre class="prettyprint source lang-typescript"><code>import 'jest-geojson'
</code></pre>
<p>Then add a <code>files</code> key in your <code>tsconfig.json</code>:</p>
<pre class="prettyprint source lang-json"><code>{
&quot;compilerOptions&quot;: {
...
},
...
&quot;files&quot;: [&quot;global.d.ts&quot;]
}
</code></pre>
<h1>Matchers</h1>
<p>
Expand Down
1 change: 0 additions & 1 deletion docs/matchers_functional_toBeValidGeoJSON.js.html
Original file line number Diff line number Diff line change
Expand Up @@ -302,7 +302,6 @@ <h1 class="page-title">matchers/functional/toBeValidGeoJSON.js</h1>
* This tests an object to see if it meets validation criteria for any of the seven GeoJSON
* Geometry types, Features, or FeatureCollections.
*
*
* @memberof Matchers.Functional
* @see https://github.com/M-Scott-Lassiter/jest-geojson/issues/26
* @param {object} geoObject Any GeoJSON Geometry, Feature, or FeatureCollection object
Expand Down
2 changes: 1 addition & 1 deletion docs/matchers_geometries_toBeAnyGeometry.js.html
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,7 @@ <h1 class="page-title">matchers/geometries/toBeAnyGeometry.js</h1>
// eslint-disable-next-line jsdoc/require-returns
/**
* Verifies an object meets validity requirements for one of the six basic GeoJSON geometry types:
* Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection
* Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection.
*
* @memberof Matchers.Geometries
* @see https://github.com/M-Scott-Lassiter/jest-geojson/issues/15
Expand Down
2 changes: 1 addition & 1 deletion docs/matchers_geometries_toBeGeometryCollection.js.html
Original file line number Diff line number Diff line change
Expand Up @@ -301,7 +301,7 @@ <h1 class="page-title">matchers/geometries/toBeGeometryCollection.js</h1>
/**
* Verifies an object is a valid GeoJSON GeometryCollection. This object requires a
* 'type' property that must equal "GeometryCollection", and a 'geometries' property that contains
* an array of GeoJSON Geometry objects (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon)
* an array of GeoJSON Geometry objects (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon).
*
* The geometries may be an empty array, but may not be an array of empty arrays or objects.
*
Expand Down
1 change: 1 addition & 0 deletions global.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
import 'jest-geojson'
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
"./setup/functional": "./src/setup/functional.js",
"./setup/geometries": "./src/setup/geometries.js"
},
"types": "src/index.d.ts",
"repository": {
"type": "git",
"url": "https://github.com/M-Scott-Lassiter/jest-geojson.git"
Expand Down
199 changes: 199 additions & 0 deletions src/index.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
/// <reference types="jest" />

declare global {
namespace jest {
interface Matchers<R> {
// Bounding Boxes

/**
* Verifies a two dimensional bounding box meets WGS-84 and GeoJSON validity requirements.
*/
isValid2DBoundingBox<E = number[]>(): R

/**
* Verifies a three dimensional bounding box meets WGS-84 and GeoJSON validity requirements.
*/
isValid3DBoundingBox<E = number[]>(): R

/**
* Verifies a two or three dimensional bounding box meets WGS-84 and GeoJSON validity requirements.
*/
isValidBoundingBox<E = number[]>(): R

// Coordinates

/**
* Verifies a two element coordinate meets WGS-84 and GeoJSON validity requirements.
*/
isValid2DCoordinate<E = number[]>(): R

/**
* Verifies a three element coordinate meets WGS-84 and GeoJSON validity requirements.
*/
isValid3DCoordinate<E = number[]>(): R

/**
* Verifies a two or three element coordinate meets WGS-84 and GeoJSON validity requirements.
*/
isValidCoordinate<E = number[]>(): R

// Feature Collections

/**
* Verifies an object is a valid GeoJSON FeatureCollection. This object requires a "type" member that must
* equal 'FeatureCollection', and a "features" member that contains either a valid GeoJSON Feature
* or an empty array.
*
* Foreign members are allowed with the exception of 'coordinates', 'geometries', 'geometry', or 'properties'.
* If present, bounding boxes must be valid.
*/
toBeFeatureCollection<E = Object>(): R

// Features

/**
* Verifies an object is a valid GeoJSON Feature. This object requires a "type" member that must
* equal 'Feature', a "geometry" member that contains either one of the seven valid GeoJSON
* geometry objects or an empty array, and a "properties" member that is either an object of any
* composition or null.
*
* Foreign members are allowed with the exception of 'coordinates', 'geometries', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBeFeature<E = Object>(): R

/**
* Checks if a GeoJSON Feature has an ID. Passes if the Feature object has any ID (no argument provided), or
* if the ID exactly matches the optional argument (single string, number, or RegExp provided), or any value
* within an array of any combination of strings, numbers, or RegExp.
*
* The test fails if the object does not have an ID, or if it has an ID that does not match the SearchID.
*/
toHaveID<E = Object>(
SearchID: string | number | RegExp | (string | number | RegExp)[]
): R

/**
* Checks if a GeoJSON Feature has a numeric ID. Passes if the Feature object has any numeric ID (no argument provided), or
* if the ID exactly matches the optional argument (single number or RegExp provided), or any value
* within an array of any combination of numbers or RegExp.
*
* The test fails if the object does not have an ID, or if it has an ID that does not match the SearchID.
*
* Passing a string type to SearchID will not pass the test, even if the ID exactly matches.
*/
toHaveNumericID<E = Object>(SearchID: number | RegExp | (number | RegExp)[]): R

/**
* Checks if a GeoJSON Feature has a string ID. Passes if the Feature object has any string ID (no argument provided), or
* if the ID exactly matches the optional argument (single string or RegExp provided), or any value
* within an array of any combination of strings or RegExp.
*
* The test fails if the object does not have an ID, or if it has an ID that does not match the SearchID.
*
* Passing a number type to SearchID will not pass the test, even if the ID exactly matches.
*/
toHaveStringID<E = Object>(SearchID: string | RegExp | (string | RegExp)[]): R

// Functional

/**
* This tests an object to see if it meets validation criteria for any of the seven GeoJSON
* Geometry types, Features, or FeatureCollections.
*/
toBeValidGeoJSON<E = Object>(): R

// Geometries

/**
* Verifies an object meets validity requirements for one of the six basic GeoJSON geometry types:
* Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection.
*/
toBeAnyGeometry<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON GeometryCollection. This object requires a
* 'type' property that must equal "GeometryCollection", and a 'geometries' property that contains
* an array of GeoJSON Geometry objects (Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon).
*
* The geometries may be an empty array, but may not be an array of empty arrays or objects.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBeGeometryCollection<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON LineString Geometry. This geometry requires a
* 'type' property that must equal "LineString", and a 'coordinates' property that contains
* an array of two or more valid WGS-84 GeoJSON coordinate(s). The coordinates may be an empty array,
* but may not be an array of empty arrays.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBeLineStringGeometry<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON MultiLineString Geometry. This geometry requires a
* 'type' property that must equal "MultiLineString", and a 'coordinates' property that contains
* an array of linestring arrays (i.e. each linestring array containing at least two or more valid
* WGS-84 GeoJSON coordinates).
*
* The coordinates may be an empty array, but may not be an array of empty arrays.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBeMultiLineStringGeometry<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON MultiPoint Geometry. This geometry requires a
* 'type' property that must equal "MultiPoint", and a 'coordinates' property that contains
* an array of valid WGS-84 GeoJSON coordinate(s). The coordinates may be an empty array.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBeMultiPointGeometry<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON MultiPolygon Geometry. This geometry requires a
* 'type' property that must equal "MultiPolygon", and a 'coordinates' property that contains
* an array of polygon coordinate arrays. Each coordinate array must contain at least four valid
* WGS-84 GeoJSON coordinates, and the final coordinate must equal the first.
*
* The coordinates may be an empty array, but may not be an array of empty arrays.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBeMultiPolygonGeometry<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON Point Geometry. This geometry requires a
* 'type' property that must equal "Point", and a 'coordinates' property that contains
* a single valid WGS-84 GeoJSON coordinate. The coordinates may be an empty array.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBePointGeometry<E = Object>(): R

/**
* Verifies an object is a valid GeoJSON Polygon Geometry. This geometry requires a
* 'type' property that must equal "Polygon", and a 'coordinates' property that contains
* an array of linestring arrays. Each point array must contain at least four valid
* WGS-84 GeoJSON coordinates, and the final coordinate must equal the first.
*
* The coordinates may be an empty array, but may not be an array of empty arrays.
*
* Foreign members are allowed with the exception of 'geometry', 'properties', or 'features'.
* If present, bounding boxes must be valid.
*/
toBePolygonGeometry<E = Object>(): R
}
}
}

export {}
1 change: 0 additions & 1 deletion src/matchers/functional/toBeValidGeoJSON.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ const { validGeoJSON } = require('../../core/utilities/validGeoJSON')
* This tests an object to see if it meets validation criteria for any of the seven GeoJSON
* Geometry types, Features, or FeatureCollections.
*
*
* @memberof Matchers.Functional
* @see https://github.com/M-Scott-Lassiter/jest-geojson/issues/26
* @param {object} geoObject Any GeoJSON Geometry, Feature, or FeatureCollection object
Expand Down
2 changes: 1 addition & 1 deletion src/matchers/geometries/toBeAnyGeometry.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ const { anyGeometry } = require('../../core/geometries/anyGeometry')
// eslint-disable-next-line jsdoc/require-returns
/**
* Verifies an object meets validity requirements for one of the six basic GeoJSON geometry types:
* Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection
* Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection.
*
* @memberof Matchers.Geometries
* @see https://github.com/M-Scott-Lassiter/jest-geojson/issues/15
Expand Down
Loading

0 comments on commit 602c33b

Please sign in to comment.