JS refactor

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vector-tile-spec"]
+	path = vector-tile-spec
+	url = https://github.com/mapbox/vector-tile-spec.git

.npmignore

@@ -1 +1,2 @@
-_reserve
+.DS_Store
+node_modules

API.md

@@ -0,0 +1,82 @@
+# create
+
+Create a tile fixture from a protocol buffer schema object representing the
+Mapbox Vector Tile schema.
+
+**Parameters**
+
+-   `object` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the json schema object to generate against the Mapbox Vector Tile Specification protocol (see src/ for examples)
+-   `json`  
+
+**Examples**
+
+```javascript
+const mvtf = require('@mapbox/mvt-fixtures');
+
+const fixture = {
+  layers: [
+    {
+      version: 2,
+      name: 'hello',
+      features: [
+        {
+          id: 1,
+          tags: [],
+          type: 1,
+          geometry: [ 9, 50, 34 ]
+        }
+      ],
+      keys: {},
+      values: {},
+      extent: 4096
+    }
+  ]
+}
+
+const buffer = mvtf.create(fixture);
+```
+
+Returns **[Buffer](https://nodejs.org/api/buffer.html)** buffer - a protocol buffer representing a Mapbox Vector Tile
+
+# each
+
+Loops through all fixtures and provides the fixture object from get()
+
+**Parameters**
+
+-   `function` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a synchronously running function to execute on each fixture
+-   `fn`  
+
+**Examples**
+
+```javascript
+const mvtf = require('mvt-fixtures');
+const assert = require('assert');
+
+mvtf.each(function(fixture) {
+  assert.ok(Buffer.isBuffer(fixture.buffer), 'is a buffer');
+});
+```
+
+# get
+
+Get a fixture by name
+
+**Parameters**
+
+-   `id` **([String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)\|[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** the id of the fixture as specified in [FIXTURES.md](FIXTURES.md)
+
+**Examples**
+
+```javascript
+const mvtf = require('mvt-fixtures');
+
+const fixture = mvtf.get('001');
+console.log(fixture.id); // => '001'
+console.log(fixture.description); // => ...
+console.log(fixture.specification_reference); // => url to Mapbox Vector Tile specification reference
+console.log(fixture.buffer); // => Buffer object
+console.log(fixture.json); // => json representation of the fixture
+```
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** fixture - a fixture object

CHANGELOG.md

@@ -1,8 +1,9 @@
-## 2.1.0 (release candidate 1)
+## 2.1.0 (work in progress)
 
 - Rename project to `mvt-fixtures`
 - Break fixtures into `valid` and `invalid` directories
 - Match version with that of the Mapbox Vector Tile Specification
+- Fixtures only include descriptions and no names, are now ordered by numerical id
 - Include more valid fixtures: TODO
 
 ## 1.0.0
@@ -11,4 +12,4 @@
 
 ## 0.0.1
 
-- first
+- first

FIXTURES.md

@@ -0,0 +1,5 @@
+id|description|valid v1|valid v2
+---|---|---|---
+001|A vector tile without any layers, which essentially results in a completely empty buffer. - [link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L75)|true|true
+002|A single layer with a single point feature that has no id field. According to the specification, "A feature MAY contain an id field. If a feature has an id field, the value of the id SHOULD be unique among the features of the parent layer." - [link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/README.md#42-features)|true|true
+003|A single point feature with a missing geometry type. From the spec, "A feature MUST contain a type field as described in the Geometry Types section." - [link](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L41) - recommended error handling `recoverable`|false|false

README.md

@@ -2,78 +2,109 @@
 
 [![Build Status](https://travis-ci.org/mapbox/mvt-fixtures.svg?branch=master)](https://travis-ci.org/mapbox/mvt-fixtures)
 
-A [`require()`able](#require-fixtures) suite of [valid](#valid-fixtures) & [invalid](#invalid-fixtures) vector tile fixtures for testing [Mapbox Vector Tile](https://github.com/mapbox/vector-tile-spec) decoding. *Previously called `evilmvt` but eventually `happymvt` prevailed.*
+A `require()`able suite of valid and invalid vector tile fixtures for testing [Mapbox Vector Tile](https://github.com/mapbox/vector-tile-spec) encoders and decoders. You can view a list of all fixtures at [FIXTURES.md](FIXTURES.md).
 
-All fixtures are included in the `/fixtures` directory. They are named to be as descriptive as possible, but the tables below gives us more space to describe the underlying data.
+# Usage
 
-**Version**: The version of `mvt-fixtures` stays in sync with the version of the Mapbox Vector Tile Specification. For instance `[email protected]` references the Mapbox `[email protected]`, reserving the patch versions for any unexpected bug fixes in this project.
+mvt-fixtures can be used in two distinct ways
 
-# Usage
+1. **javascript interface**: use the javascript interface to generate fixtures on the fly
+1. **raw fixtures** use the raw fixtures directly via the /fixtures directory.
+
+The Javascript API is recommended if you are working in Javascript or Node.js. The raw fixtures are provided for those using this outside of a Javascript application. The recommended workflow is to have your encoder or decoder loop through every fixture and either expect to successfully decode/encode valid fixtures, or fail to decode/encode invalid fixtures. When new fixtures are added to this repository, you simply need to update the version of the module (or your submodule) to get the new fixtures and re-run tests.
+
+**Validity:** each fixture includes information about whether they are valid according to the specification versions and possible error outcomes if they are invalid. If any of the fixtures are invalid, they must include an `error` field describing how to recover (or not) from the error. These can be found in the `validity` field of the fixture and info.json files. The following checks:
 
-### `require('@mapbox/mvt-fixtures')`
+* `v1` (Boolean): is this fixture valid according to Version 1.x of the Mapbox Vector Tile spec
+* `v2` (Boolean): is this fixture valid according to Version 2.x of the Mapbox Vector Tile spec
+* `error` (String): describes if the encoder/decoder should recover from this error or stop completely. THis is only present if the fixture is invalid according to one or more spec revisions. Values are
+  * `recoverable`: should the encoder/decoder continue move on and continue its work? For instance, if invalid geometry is found, can the encoder safely move to the next feature?
+  * `fatal`: the encoder should completely stop its process
 
-Install
+### Javascript usage
 
+Check out the full Javascript interface over at [API.md](API.md)
+
+```shell
+npm install @mapbox/mvt-fixtures --save-dev
 ```
-npm install @mapbox/mvt-fixtures --save
+
+```javascript
+const mvtf = require('@mapbox/mvt-fixtures');
+const decoder = require('your-mvt-decoder');
+
+mvtf.each(function(fixture) {
+  let output = decoder(fixture.buffer);
+  assert.equal(output.layers.length, fixture.json.layers.length, 'expected number of layers');
+  // ... more tests
+});
 ```
 
-You can require the fixtures directly from the `evilmvt` module using the name of the fixture.
+### Non-JS interface
+
+You can access all of the fixtures and their metadata in the /fixtures directory. You can download this repository and get them manually, or use this repository as a submodule. Each fixture is named by the directory /fixtures/{name} and has the following files:
+
+1. tile.mvt - the protocol buffer that represents (or intentionally breaks) the Mapbox Vector Tile specification
+1. tile.json - a JSON representation of the tile and its properties
+1. info.json - information about the fixture including `name`, `description`, and `specification_reference`.
+
+# Develop
+
+### Adding a new fixture
+
+All fixtures have a source file in the /src directory. This file is a module that exports an object with the following parameters:
 
 ```javascript
-var fixtures = require('@mapbox/mvt-fixtures').fixtures;
-var buffer = fixtures.invalid['Tags-nonexistant-values'];
-// do something with bufer
+module.exports = function(schema) {
+  return {
+    description: 'DESCRIPTION',
+    specification_reference: 'SPECIFICATION_URL',
+    validity: {
+      v1: true,
+      v2: false,
+      error: 'ERROR_TYPE'
+    },
+    json: {...},
+    manipulate: function(buffer) {
+      // function to further manipulate the buffer
+      return buffer;
+    }
+  }
+};
 ```
 
-### Vendor or Submodule
-
-Alternatively, you can [download the repository](https://github.com/mapbox/evilmvt/archive/master.zip) and use the fixtures manually, OR include this repository as a [Git Submodule](https://github.com/blog/2104-working-with-submodules).
-
-# Invalid fixtures `fixtures/invalid`
-
-Fixture name | Description
----|---
-`Feature-missing-GeomType.mvt` | The `Feature` message is missing a [`GeomType`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L41) message.
-`Feature-multiple-geometries.mvt` | The `Feature` message as multiple [`geometry`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L46) fields encoded, when there should only be one.
-`Feature-no-geometry.mvt` | The `Feature` message has no [`geometry`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L46).
-`Feature-odd_number_tags.mvt` | Only has a single [`tag`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L38) where multiples of 2 are required.
-`Feature-unknown_field_type.mvt` | Has a field value of `10`, which is [not listed as an enum](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L8-L13) and therefore invalid.
-`GeomType-type.mvt` | The tag for GeomType is `10`, which is invalid.
-`Key-mistyped_uint32.mvt` | Has a [`key`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L63) property incorrectly encoded as a type `std::uint32_t`. | n/a
-`Layer-extent-mistyped_string.mvt` | Layer [`extent`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L70) is incorrectly encoded as a type `std::string`.
-`Layer-extent-none.mvt` | Missing the [`extent`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L70) type
-`Layer-name-duplicates.mvt` | Includes two layer [`name`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L57)s with the same value: "layer_name".
-`Layer-name-mistyped_uint32.mvt` | Has a layer name incorrectly encoded as `std::uint32_t`.
-`Layer-name-none.mvt` | Does not include a layer name.
-`Layer-name-none-version1.mvt` | Same as above, but version 1 tile.
-`Layer-no-features.mvt` | Layer has no repeated [`Features`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L60) tags.
-`Layer-unknow_value_type.mvt` | Includes a Layer value tag of `20`, which is not defined in the spec.
-`Layer-invalid-version.mvt` | Layer version is `99`, which is invalid according to the specification.
-`Layer-version-mistyped_string.mvt` | Layer version is incorrectly typed as a `std::string`.
-`Layer-version-none.mvt` | Layer does not have a [`version`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L55) property.
-`Tags-nonexistant-values.mvt` | Feature has [`tags`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L38) that point to non-existent [`Keys`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L63) and [`Values`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) in the layer.
-`Tile-unknown-tag.mvt` | Tile message has an unknown tag value. The only accepted tag value here is `3`, but this tile encodes a `Feature` with the tag value of `10`.
-`Value-no-fields.mvt` | includes a [`Value`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) without any fields encoded within it.
-`Value-string-mistyped_int64.mvt` | A Layer value property is listed as "string" but encoded as `std::int64_t`.
-`Value-unknown-field-type.mvt` | The [`Value`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) has a field with an [unknown type](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L17-L28).
-
-# Valid fixtures `fixtures/valid`
-
-Fixture name | Description
----|---
-`Feature-single-linestring.mvt` | Single layer with a valid [linestring geometry](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#4353-example-linestring) from the spec docs.
-`Feature-single-multilinestring.mvt` | Single layer with a valid [multilinestring geometry](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#4354-example-multi-linestring) from the spec docs.
-`Feature-single-multipoint.mvt` | Single layer with a valid [multipoint geometry](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#4352-example-multi-point) from the spec docs.
-`Feature-single-point.mvt` | Single layer with a valid [point geometry](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#4351-example-point) from the spec docs.
-`Feature-single-polygon.mvt` | Single layer with a valid [polygon geometry](https://github.com/mapbox/vector-tile-spec/tree/master/2.1#4355-example-polygon) from the spec docs.
-`Feature-unknown-GeomType.mvt` | Single geometry with [`UNKNOWN` type](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L9). This is considered "valid" in the lens of the specification. Encoders/decoders can choose to use or throw on this goemetry type.
-`Value-multiple-fields.mvt` | The [`Value`](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) message has two different string entries.
-`Value-single-bool-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `bool` type and a single Point feature.
-`Value-single-double-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `double` type and a single Point feature.
-`Value-single-float-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `float` type and a single Point feature.
-`Value-single-int64-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `int64` type and a single Point feature.
-`Value-single-sint64-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `sint64` type and a single Point feature.
-`Value-single-string-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `string` type and a single Point feature.
-`Value-single-uint64-point.mvt` | Single [Value](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L66) with `uint64` type and a single Point feature.
-`Values-all.mvt` | A buffer with all possible [`Value` types](https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto#L17-L28) encoded in the layer and single Feature.
+A new fixture can be created by running the command, which will auto-increment the ID:
+
+```shell
+npm run new
+# New file created: /src/003.js.
+```
+
+### Building fixtures
+
+To rebuild all of the raw fixtures (including the tile.mvt, tile.json, and info.json files) in /fixtures you can run:
+
+```
+npm run build
+```
+
+### Building docs
+
+Documentation takes two forms...
+
+1. Javascript API docs in API.md
+1. Fixture reference in FIXTURES.md
+
+These can be generated by running:
+
+```
+npm run docs
+```
+
+### Running tests
+
+All tests can be run with:
+
+```
+npm test
+```