npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@radarlabs/s2

v0.0.5

Published

Node.js JavaScript and TypeScript bindings for the Google S2 geolocation library.

Downloads

513

Readme

CircleCI

Node.js JavaScript & TypeScript bindings for Google S2.

What is S2?

S2 is a library from Google for easily storing, indexing, and retrieving geographic locations.

Geographic regions can be indexed by S2 cell ids of various levels in a data store and then later retrieved by these ids for extremely quick geolocation lookups.

The Library

The goal of this library is to maintain Node.js TypeScript bindings for the latest version of Google's C++ S2 library.

Other JavaScript projects available on GitHub appear unmaintained.

The project has been built against Node's N-API, meaning that it's compatible across Node.js versions that support BigInt. This means that Node.js version 9 and below are unsupported.

As of today, the library is built and tested against Node.js 16, 18 and 20. The library has been in production use at Radar and has been built against OS X and Linux. Feel free to open an issue or PR if you'd like other platform support.

See test.sh for more details.

Usage

To install:

npm install @radarlabs/s2

To run tests (you'll need Docker):

./test.sh

S2 Cells can be generated from BigInt S2 IDs or string tokens:

const s2 = require('@radarlabs/s2');

const cell1 = new s2.CellId(9926595695177891840n);
console.log(cell1.token());
> 89c25a31

const cell2 = new s2.CellId('89c25a31');
console.log(cell2.id());
> 9926595695177891840n

To generate a covering for a given area:

const s2 = require('@radarlabs/s2');

# an array of lat/lng pairs representing a region (a part of Brooklyn, in this case)
const loopLLs = [[40.70113825399865,-73.99229764938354],[40.70113825399865,-73.98766279220581],[40.70382234072197,-73.98766279220581],[40.70382234072197,-73.99229764938354]];

# map to an array of normalized s2.LatLng
const s2LLs = loopLLs.map(([lat, lng]) => (new s2.LatLng(lat, lng)));

# generate s2 cells to cover this polygon
const s2level = 14;
const covering = s2.RegionCoverer.getCoveringTokens(s2LLs, { min: s2level, max: s2level });
covering.forEach(c => console.log(c));

> 89c25a31
> 89c25a33
> 89c25a35
> 89c25a37

# check if a point is contained inside this region
const point = new s2.CellId(new s2.LatLng(40.70248844447621, -73.98991584777832));
const pointAtLevel14 = point.parent(s2Level);
console.log(pointAtLevel14.token());
> 89c25a31

const coveringSet = new Set(covering);
console.log(coveringSet.contains(pointAtLevel14.token()));
> true

To generate a covering for a given radius around a point:

const s2 = require('@radarlabs/s2');

# make an S2 latlng object for downtown San Diego
const s2LatLong = new s2.LatLng(32.715651, -117.160542);

# set cell covering options so the biggest region is a 6 and smallest is a 13, and limit to 10 cells
const cellCoveringOptions = {min: 6, max: 13, max_cells: 10};

# get the cells (with the size range allowed) covering a 10,000 meter search radius centered on the given location
# Note that this call returns a CellUnion object instead of a list of tokens, which is useful for comparisons
const coveringCells = s2.RegionCoverer.getRadiusCovering(s2LatLong, 10000, cellCoveringOptions);
# For this example though, we'll loop over the cellIds within the CellUnion and get their tokens
console.log(coveringCells.cellIds().map((cellId) => cellId.token()));

> 80d94d
> 80d951
> 80d953
> 80d955
> 80d956c
> 80dbffc
> 80dc01
> 80deab
> 80dead
> 80deb2ac

# the "coveringCells" CellUnion is like the "coveringSet" from the previous example, so can be used directly without converting to a set
# test by checking a cell centered at our lat long
console.log(coveringCells.contains(new s2.CellId(s2LatLong)));
> true

Here's a visualization of the above set of covering cells. The center of the 10k radius is in downtown San Diego.

Check if a cell is contained in another:

const c1 = s2.CellId.fromToken('89c25a37')
const c2 = s2.CellId.fromToken('89c25')
c2.contains(c1)
> true
c1.contains(c2)
> false

If you'd like to see more functionality, feel free to open an issue or create a pull request.

More detailed usage can be found in the tests folder.

Versioning

The Node S2 is library is at its infancy, so APIs are likely to change. In order to help with versioning, we publish TypeScript bindings so that your compiler can check if anything has changed. To keep up with updates, see CHANGELOG.md

Resources