Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@rclark
rclark committed Aug 8, 2015
1 parent 3846e8a commit 6b2a35f
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 78 deletions.
100 changes: 33 additions & 67 deletions api.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## [Cardboard(config)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L39-L598)
## [Cardboard(config)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L39-L643)


Cardboard client generator
Expand Down Expand Up @@ -32,7 +32,7 @@ Returns `cardboard` a cardboard client



## [cardboard](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L57-L59)
## [cardboard](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L57-L57)


A client configured to interact with a backend cardboard database
Expand All @@ -44,7 +44,7 @@ A client configured to interact with a backend cardboard database



### [bboxQuery(bbox, dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L472-L595)
### [bboxQuery(bbox, dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L517-L640)

Find GeoJSON features that intersect a bounding box

Expand All @@ -67,7 +67,7 @@ carboard.bboxQuery(bbox, 'my-dataset', function(err, collection) {



### [calculateDatasetInfo(dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L456-L458)
### [calculateDatasetInfo(dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L455-L457)

Calculate metadata about a dataset

Expand Down Expand Up @@ -99,7 +99,7 @@ cardboard.calculateDatasetInfo('my-dataset', function(err, metadata) {



### [createTable(tableName, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L235-L244)
### [createTable(tableName, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L234-L243)

Create a DynamoDB table with Cardboard's schema

Expand All @@ -126,7 +126,7 @@ cardboard.createTable('new-cardboard-table', function(err) {



### [del(primary, dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L165-L173)
### [del(primary, dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L164-L172)

Remove a single GeoJSON feature

Expand Down Expand Up @@ -170,7 +170,7 @@ cardboard.del('non-existent-feature', 'my-dataset', function(err, result) {



### [delDataset(dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L267-L279)
### [delDataset(dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L266-L278)

Remove an entire dataset

Expand All @@ -183,7 +183,7 @@ Remove an entire dataset



### [get(primary, dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L207-L218)
### [get(primary, dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L206-L217)

Retreive a single GeoJSON feature

Expand Down Expand Up @@ -227,7 +227,7 @@ cardboard.get('non-existent-feature', 'my-dataset', function(err, result) {



### [getDatasetInfo(dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L431-L433)
### [getDatasetInfo(dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L430-L432)

Get cached metadata about a dataset

Expand Down Expand Up @@ -259,7 +259,7 @@ cardboard.getDatasetInfo('my-dataset', function(err, metadata) {



### [list(dataset, pageOptions, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L325-L384)
### [list(dataset, pageOptions, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L324-L383)

List the GeoJSON features that belong to a particular dataset

Expand Down Expand Up @@ -315,7 +315,7 @@ cardboard.list('my-dataset', { maxFeatures: 10 }, function(err, collection) {
Returns `object` a readable stream


### [listDatasets(callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L396-L408)
### [listDatasets(callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L395-L407)

List datasets available in this database

Expand All @@ -336,7 +336,7 @@ cardboard.listDatasets(function(err, datasets) {



### [put(feature, dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/index.js#L118-L131)
### [put(feature, dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L117-L130)

Insert or update a single GeoJSON feature

Expand Down Expand Up @@ -407,7 +407,7 @@ cardboard.put(feature, 'my-dataset', function(err, result) {



## [cardboard.batch](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/batch.js#L17-L17)
## [cardboard.batch](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/batch.js#L19-L19)


A module for batch requests
Expand All @@ -419,7 +419,7 @@ A module for batch requests



### [put(collection, dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/batch.js#L27-L54)
### [put(collection, dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/batch.js#L29-L69)

Insert or update a set of GeoJSON features

Expand All @@ -433,7 +433,7 @@ Insert or update a set of GeoJSON features



### [remove(ids, dataset, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/batch.js#L64-L72)
### [remove(ids, dataset, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/batch.js#L79-L94)

Remove a set of features

Expand All @@ -448,10 +448,10 @@ Remove a set of features



## [metadata](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L10-L10)
## [cardboard.metadata](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L463-L463)


A client for interacting with the metadata for a dataset
A module for incremental metadata adjustments



Expand All @@ -460,85 +460,51 @@ A client for interacting with the metadata for a dataset



### [addFeature(feature, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L166-L177)
### [addFeature(dataset, feature, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L473-L475)

Given a GeoJSON feature, perform all required metadata updates. This operation **will** create a metadata record if one does not exist.
Incrementally update a dataset's metadata with a new feature. This operation **will** create a metadata record if one does not exist.

#### Parameters

* `feature` **`object`** a GeoJSON feature being added to the dataset
* `dataset` **`object`** the name of the dataset
* `feature` **`object`** a GeoJSON feature (or backend record) being added to the dataset
* `callback` **`function`** a function to handle the response





### [calculateInfo(callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L87-L120)

Find all features in a dataset and bring metadata record up-to-date

#### Parameters

* `callback` **`function`** a function to handle the response





### [deleteFeature(feature, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L202-L208)
### [deleteFeature(dataset, feature, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L499-L501)

Given a GeoJSON feature to remove, perform all required metadata updates. This operation **will not** create a metadata record if one does not exist. This operation **will not** shrink metadata bounds.

#### Parameters

* `feature` **`object`** a GeoJSON feature to remove from the dataset
* `dataset` **`object`** the name of the dataset
* `feature` **`object`** a GeoJSON feature (or backend record) to remove from the dataset
* `callback` **`function`** a function to handle the response





### [getFeatureInfo(feature)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L48-L58)

Return the details for a given GeoJSON feature

#### Parameters

* `feature` **`object`** a GeoJSON feature



Returns `object` an object describing the feature's size and extent


### [getInfo(callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L35-L41)

Return dataset metadata or an empty object

#### Parameters

* `callback` **`function`** a callback function to handle the response





### [updateFeature(from, to, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/metadata.js#L185-L195)
### [updateFeature(dataset, from, to, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/index.js#L487-L489)

Given before and after states of a GeoJSON feature, perform all required metadata adjustments. This operation **will not** create a metadata record if one does not exist.
Update a dataset's metadata with a change to a single feature. This operation **will not** create a metadata record if one does not exist.

#### Parameters

* `from` **`object`** a GeoJSON feature representing the state of the feature *before* the update
* `to` **`object`** a GeoJSON feature representing the state of the feature *after* the update
* `dataset` **`object`** the name of the dataset
* `from` **`object`** a GeoJSON feature (or backend record) representing the state of the feature *before* the update
* `to` **`object`** a GeoJSON feature (or backend record) representing the state of the feature *after* the update
* `callback` **`function`** a function to handle the response






## [utils](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/utils.js#L14-L14)
## [utils](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/utils.js#L14-L14)


A module containing internal utility functions
Expand All @@ -550,7 +516,7 @@ A module containing internal utility functions



### [idFromRecord(record)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/utils.js#L100-L104)
### [idFromRecord(record)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/utils.js#L100-L105)

Strips database-information from a DynamoDB record's id

Expand All @@ -563,7 +529,7 @@ Strips database-information from a DynamoDB record's id
Returns `string` id - the feature's identifier


### [resolveFeatures(dynamoRecords, callback)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/utils.js#L21-L45)
### [resolveFeatures(dynamoRecords, callback)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/utils.js#L21-L45)

Convert a set of backend records into a GeoJSON features

Expand All @@ -576,7 +542,7 @@ Convert a set of backend records into a GeoJSON features



### [toDatabaseRecord(feature, dataset)](https://github.com/mapbox/cardboard/blob/c364c347aa7d57b259fa74189d710b1b5bc62cee/lib/utils.js#L63-L93)
### [toDatabaseRecord(feature, dataset)](https://github.com/mapbox/cardboard/blob/3846e8a115ffa13012f05af5b9e62d4ea2f7ab4f/lib/utils.js#L63-L93)

Converts a single GeoJSON feature into backend format

Expand Down
34 changes: 23 additions & 11 deletions index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,8 @@ var Cardboard = module.exports = function(config) {
/**
* A client configured to interact with a backend cardboard database
*/
var cardboard = {
batch: require('./lib/batch')(config),
metadata: {}
};
var cardboard = {};
cardboard.batch = require('./lib/batch')(config);

/**
* Insert or update a single GeoJSON feature
Expand Down Expand Up @@ -458,38 +456,52 @@ var Cardboard = module.exports = function(config) {
Metadata(config.dyno, dataset).calculateInfo(callback);
};

/**
* A module for incremental metadata adjustments
* @name cardboard.metadata
*/
var metadata = {};

/**
* Incrementally update a dataset's metadata with a new feature. This operation **will** create a metadata record if one does not exist.
* @static
* @memberof cardboard.metadata
* @param {object} dataset - the name of the dataset
* @param {object} feature - a GeoJSON feature being added to the dataset
* @param {object} feature - a GeoJSON feature (or backend record) being added to the dataset
* @param {function} callback - a function to handle the response
*/
cardboard.metadata.addFeature = function(dataset, feature, callback) {
metadata.addFeature = function(dataset, feature, callback) {
Metadata(config.dyno, dataset).addFeature(feature, callback);
};

/**
*
* Update a dataset's metadata with a change to a single feature. This operation **will not** create a metadata record if one does not exist.
* @static
* @memberof cardboard.metadata
* @param {object} dataset - the name of the dataset
* @param {object} from - a GeoJSON feature representing the state of the feature *before* the update
* @param {object} to - a GeoJSON feature representing the state of the feature *after* the update
* @param {object} from - a GeoJSON feature (or backend record) representing the state of the feature *before* the update
* @param {object} to - a GeoJSON feature (or backend record) representing the state of the feature *after* the update
* @param {function} callback - a function to handle the response
*/
cardboard.metadata.updateFeature = function(dataset, from, to, callback) {
metadata.updateFeature = function(dataset, from, to, callback) {
Metadata(config.dyno, dataset).updateFeature(from, to, callback);
};

/**
* Given a GeoJSON feature to remove, perform all required metadata updates. This operation **will not** create a metadata record if one does not exist. This operation **will not** shrink metadata bounds.
* @static
* @memberof cardboard.metadata
* @param {object} dataset - the name of the dataset
* @param {object|number} feature - a GeoJSON feature to remove from the dataset or the size of the GeoJSON feature provided as a number
* @param {object} feature - a GeoJSON feature (or backend record) to remove from the dataset
* @param {function} callback - a function to handle the response
*/
cardboard.metadata.deleteFeature = function(dataset, feature, callback) {
metadata.deleteFeature = function(dataset, feature, callback) {
Metadata(config.dyno, dataset).deleteFeature(feature, callback);
};

cardboard.metadata = metadata;

/**
* Find GeoJSON features that intersect a bounding box
* @param {number[]} bbox - the bounding box as `[west, south, east, north]`
Expand Down
7 changes: 7 additions & 0 deletions lib/metadata.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* A client for interacting with the metadata for a dataset
* @private
*/
var metadata = {};
var recordId = metadata.recordId = 'metadata!' + dataset;
Expand All @@ -33,6 +34,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* Return dataset metadata or an empty object
* @private
* @param {function} callback - a callback function to handle the response
*/
metadata.getInfo = function(callback) {
Expand All @@ -44,6 +46,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* Return the details for a given GeoJSON feature
* @private
* @param {object} feature - a GeoJSON feature
* @returns {object} an object describing the feature's size and extent
*/
Expand Down Expand Up @@ -84,6 +87,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* Find all features in a dataset and bring metadata record up-to-date
* @private
* @param {function} callback - a function to handle the response
*/
metadata.calculateInfo = function(callback) {
Expand Down Expand Up @@ -162,6 +166,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* Given a GeoJSON feature, perform all required metadata updates. This operation **will** create a metadata record if one does not exist.
* @private
* @param {object} feature - a GeoJSON feature being added to the dataset, or the backend representation of a feature
* @param {function} callback - a function to handle the response
*/
Expand All @@ -183,6 +188,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* Given before and after states of a GeoJSON feature, perform all required metadata adjustments. This operation **will not** create a metadata record if one does not exist.
* @private
* @param {object} from - a GeoJSON feature representing the state of the feature *before* the update, or the backend representation of a feature
* @param {object} to - a GeoJSON feature representing the state of the feature *after* the update, or the backend representation of a feature
* @param {function} callback - a function to handle the response
Expand All @@ -203,6 +209,7 @@ var Metadata = module.exports = function(dyno, dataset) {

/**
* Given a GeoJSON feature to remove, perform all required metadata updates. This operation **will not** create a metadata record if one does not exist. This operation **will not** shrink metadata bounds.
* @private
* @param {object} feature - a GeoJSON feature to remove from the dataset, or the backend representation of a feature
* @param {function} callback - a function to handle the response
*/
Expand Down

0 comments on commit 6b2a35f

Please sign in to comment.