Peer-to-peer OpenStreetMap database over hyperdb.
Experimental
Expect plenty of breaking changes -- semver will be respected. This isn't currently ready to be relied upon by other modules!
If you're interested in this project, leave an issue and share a bit about what you're building!
var hyperosm = require('hyperdb-osm')
var hyperdb = require('hyperdb')
var ram = require('random-access-memory')
var memdb = require('memdb')
var Geo = require('grid-point-store')
var db = hyperdb(ram, { valueEncoding: 'json' }))
var indexes = memdb()
var geo = Geo(memdb())
var osm = hyperosm({
db: db,
index: indexes,
pointstore: geo
})
var node = {
type: 'node',
lat: '-12.7',
lon: '1.3',
tags: { feature: 'water fountain' },
changeset: 'abcdef'
}
osm.create(node, function (err, node) {
console.log('created node with id', node.id)
var bbox = [[-13, -11], [1, 2]]
osm.query(bbox, function (err, elms) {
console.log(elms)
})
})
outputs
created node with id 78d06921416fe95b
[ { type: 'node',
lat: '-12.7',
lon: '1.3',
tags: { feature: 'water fountain' },
changeset: 'abcdef',
timestamp: '2017-12-16T00:15:55.238Z',
id: '78d06921416fe95b',
version: 'eAXxidJuq9PoqiDsyrLKfR4jME9hgYnGSozS7BKXUqbDH' } ]
var hyperosm = require('hyperdb-osm')
Expected opts
include:
db
: a hyperdb instanceindex
: a levelup instancepointstore
: a grid-point-store instance
Create the new OSM element element
and add it to the database. The resulting
element, populated with the id
and version
fields, is returned by the
callback cb
.
Fetch all of the newest OSM elements with the ID id
. In the case that multiple
peers modified an element prior to sync'ing with each other, there may be
multiple latest elements ("heads") for the ID.
Fetch a specific OSM element by its version string. Returns null
if not found,
otherwise the single element.
Update an existing element with ID id
to be the OSM element element
. The new
element should have all fields that the OSM element would have. The type
of
the element cannot be changed.
If the value of ID currently returns two or more elements, this new value will replace them all.
cb
is called with the new element, including id
and version
properties.
Marks the element id
as deleted. A deleted document can be get
and
getByVersion
'd like a normal document, and will always have the { deleted: true }
field set.
Deleted ways, nodes, and relations are all still returned by the query
API.
The nodes of a deleted are not included in the results.
Create and update many elements atomically. ops
is an array of objects
describing the elements to be added or updated.
{
type: 'put|del',
id: 'id',
value: { /* element */ }
}
If no id
field is set, the element is created, otherwise it is updated with
the element value
.
An operation type of 'put'
inserts a new element or modifies an existing one,
while a type of'del'
will mark the element as deleted.
Currently, doing a batch insert skips many validation checks in order to be as fast as possible.
TODO: accept opts.validate
or opts.strict
Retrieves all node
s, way
s, and relation
s touching the bounding box bbox
.
bbox
is expected to be of the format [[minLat, maxLat], [minLon, maxLon]]
.
Latitude runs between (-85, 85)
, and longitude between (-180, 180)
.
A callback parameter cb
is optional. If given, it will be called as
cb(err, elements)
. If not provided or set to null
, a Readable stream will be
returned that can be read from as elements are emitted. The distinction between
the two is that the callback will buffer all results before they are returned,
but the stream will emit results as they arrive, resulting in much less
buffering. This can make a large impact on memory use for queries on large
datasets.
The following algorithm is used to determine what OSM elements are returned:
- All nodes that are inside a given bounding box and any relations that reference them.
- All ways that reference at least one node that is inside a given bounding box, any relations that reference them (the ways), and any nodes outside the bounding box that the ways may reference.
- All relations that reference one of the nodes, ways or relations included due to the above rules. (This does not apply recursively; meaning that elements referenced by a relation are not returned by virtue of being in that relation.)
Fetch a list of all OSM elements belonging to the changeset id
.
A callback parameter cb
is optional. If given, it will be called as cb(err, results)
. If not provided or set to null
, a Readable stream will be returned
that can be read from as results are ready.
Objects of the following form are returned:
{
id: '...',
version: '...'
}
Fetch a list of all OSM ways and relations that refer to the element with ID
id
. For a node, this can be ways or relations. For a way or relation, this can
only be relations.
A callback parameter cb
is optional. If given, it will be called as cb(err, results)
. If not provided or set to null
, a Readable stream will be returned
that can be read from as results are ready.
Objects of the following form are returned:
{
id: '...',
version: '...'
}
Get all immediately previous versions of the element at version
.
In the simple case of one writer writing an element and then updating it,
A_1 <-- A_2
getPreviousHeads(A_2)
would return [A_2]
.
In a more complex case of two writers that both forked C_1
and then one wrote
a new head to merge them,
/-- C_2 <--\
C_1 <--- --- C4
\-- C_3 <--/
getPreviousHeads(C_4)
would return [C_2, C_3]
.
TODO: talk about forking data & forking architecture
If you had other modules that store data in a hyperdb, say hyperdb-media
and
hyperdb-maptiles
, you could combine these and this module together with a very
minimal amount of glue to create a simpler database interface for consumers:
var hyperdb = Hyperdb(...)
var osm = hyperosm(...)
var media = hypermedia(...)
var maptiles = hypertiles(...)
var db = {
osm: osm,
users: users,
media: media,
tiles: maptiles,
replicate: hyperdb.replicate.bind(hyperdb)
}
With npm installed, run
$ npm install hyperdb-osm
ISC