Merge pull request #11 from darkskyapp/client

6.1.0: execute in browser and in Node.JS

README.md

@@ -1,62 +1,62 @@
 tz-lookup
 =========
+This is a little Javascript library that allows you to look up the time zone of
+a location given its latitude and longitude. It works in both the browser and
+in Node.JS, and is very fast and lightweight (~121KB) given what it does. We
+use it in production for [The Dark Sky API][1].
 
-This is a little module that allows you to look up the current time zone of a
-location, given it's latitude and longitude. I wrote it because the existing
-Node module that does this (`tzwhere`) was far too slow to be useful in a
-production setting. This module attempts to ameliorate that.
+[1]: https://darksky.net/dev/
 
 Usage
 -----
-
 To install:
 
     npm install tz-lookup
 
-To use:
+Node.JS usage:
+
+```javascript
+var tzlookup = require("tz-lookup");
+console.log(tzlookup(42.7235, -73.6931)); // prints "America/New_York"
+```
 
-    > var tz = require("tz-lookup");
-    > console.log(tz(42.7235, -73.6931));
-    "America/New_York"
+Browser usage:
+
+```html
+<script src="tz.js"></script>
+<script>
+alert(tzlookup(42.7235, -73.6931)); // alerts "America/New_York"
+</script>
+```
 
 **Please take note of the following:**
 
 *   The exported function call will throw an error if the latitude or longitude
     provided are NaN or out of bounds. Otherwise, it will never throw an error
     and will always return an IANA timezone database string. (Barring bugs.)
-*   The exported function call is synchronous. Previous versions of this module
-    were asynchronous, due to the timezone database being too large to
-    conveniently fit in memory. Thanks to very careful data compression, this
-    is no longer the case.
-*   The timezones returned by this module are approximate: since the timezone
-    database is so large, lossy compression is necessary for fast lookups. In
-    particular, the compression used may be of insufficient resolution for
-    several very small timezones and favors country timezones over GMT offsets
-    (and so may exaggerate the distance of territorial waters). However, the
-    level of accuracy should be adequate for most purposes. (For example, this
-    module is used by the [Dark Sky API][1] for global timezone lookups.)
 
-If you find a real-world case where this module's accuracy is inadequate,
-please open an issue (or, better yet, submit a pull request with a failing
-test) and I'll see what I can do to increase the accuracy for you.
-
-[1]: https://darksky.net/dev/
+*   The timezones returned by this module are approximate: since the timezone
+    database is so large, lossy compression is necessary for a small footprint
+    and fast lookups. Expect errors near timezone borders far away from
+    populated areas. However, for most use-cases, this module's accuracy should
+    be adequate.
+
+    If you find a real-world case where this module's accuracy is inadequate,
+    please open an issue (or, better yet, submit a pull request with a failing
+    test) and I'll see what I can do to increase the accuracy for you.
 
 Sources
 -------
-
 Versions prior to 6.0.7 used timezone data from Eric Muller's excellent [TZ
 timezone maps][2]. As of 6.0.7, we now use timezone data from @evansiroky's
-also-excellent [timezone-boundary-builder][3]. To regenerate the compressed
-database, simply run `rebuild.sh`. The timezone database was last updated on
-8 Mar 2017.
+also-excellent [timezone-boundary-builder][3]. To regenerate the library,
+simply run `rebuild.sh`. The timezone database was last updated on 8 Mar 2017.
 
 [2]: http://efele.net/maps/tz/
 [3]: https://github.com/evansiroky/timezone-boundary-builder/
 
 License
 -------
-
 To the extent possible by law, The Dark Sky Company, LLC has [waived all
 copyright and related or neighboring rights][cc0] to this library.
 

pack.js

@@ -2,7 +2,7 @@
 const width = 49152;
 const height = 24576;
 const fs = require("fs");
-const index = require("./tz");
+const index = require("./tz.json");
 
 function read(pathname, offset, buffer) {
   const fd = fs.openSync(pathname, "r");
@@ -180,27 +180,33 @@ function pack(root) {
     }
   }
 
-  const buffer = Buffer.allocUnsafe((48 * 24 + (list.length - 1) * 2 * 2) * 2);
-  let off = 0;
+  let string = "";
   for(let i = 0; i < list.length; i++) {
     const a = list[i];
     for(let j = 0; j < a.length; j++) {
       const b = a[j];
-      buffer.writeUIntBE(
-        Array.isArray(b)?
-          (b.index - a.index - 1):
-          65536 - index.length + b,
-        off,
-        2
-      );
-      off += 2;
+
+      let x;
+      if(Array.isArray(b)) {
+        x = b.index - a.index - 1;
+        if(x < 0 || x + index.length >= 3136) {
+          throw new Error("cannot pack in the current format");
+        }
+      }
+      else {
+        x = 3136 - index.length + b;
+      }
+
+      string += String.fromCharCode(Math.floor(x / 56) + 35, (x % 56) + 35);
     }
   }
-  if(off !== buffer.length) {
-    throw new Error("eep");
-  }
 
-  return buffer;
+  return string;
 }
 
-fs.writeFileSync("tz.bin", pack(coarse()));
+console.log(
+  "%s",
+  fs.readFileSync("tz_template.js", "utf8").
+    replace(/__TZDATA__/, () => JSON.stringify(pack(coarse()))).
+    replace(/__TZLIST__/, () => JSON.stringify(index))
+);

package.json

@@ -1,7 +1,8 @@
 {
   "name": "tz-lookup",
-  "version": "6.0.7",
+  "version": "6.1.0",
   "description": "fast time zone lookup",
+  "main": "tz.js",
   "keywords": [
     "tz",
     "timezone",
@@ -16,8 +17,8 @@
     "url": "git://github.com/darkskyapp/tz-lookup.git"
   },
   "devDependencies": {
-    "chai": "*",
-    "mocha": "*"
+    "mocha": "*",
+    "uglify-js": "*"
   },
   "scripts": {
     "test": "mocha"

rebuild.sh

@@ -43,5 +43,5 @@ ogr2ogr -f GeoJSON ne_10m_populated_places_simple.json ne_10m_populated_places_s
 rm -rf ne_10m_populated_places_simple.README.html ne_10m_populated_places_simple.VERSION.txt ne_10m_populated_places_simple.dbf ne_10m_populated_places_simple.prj ne_10m_populated_places_simple.shp ne_10m_populated_places_simple.shx ne_10m_populated_places_simple.zip
 
 # repack tz_world_mp and ne_10m_urban_areas into a compressed image
-node pack
-rm -rf ne_10m_populated_places_simple.json ne_10m_urban_areas.pbm tz_a.pgm tz_b.pgm tz_c.pgm tz_d.pgm tz_e.pgm tz_f.pgm tz_g.pgm tz_h.pgm
+node pack | ./node_modules/.bin/uglifyjs -mc >tz.js
+rm -rf ne_10m_populated_places_simple.json ne_10m_urban_areas.pbm tz.json tz_a.pgm tz_b.pgm tz_c.pgm tz_d.pgm tz_e.pgm tz_f.pgm tz_g.pgm tz_h.pgm

test.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>TZLookup Tests</title>
+    <link rel="stylesheet" media="all" href="https://cdnjs.cloudflare.com/ajax/libs/mocha/3.2.0/mocha.min.css">
+  </head>
+  <body>
+    <div id="mocha"></div>
+    <div id="messages"></div>
+    <div id="fixtures"></div>
+
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/3.2.0/mocha.min.js"></script>
+    <script>mocha.setup("bdd");</script>
+
+    <script src="tz.js"></script>
+    <script src="test.js"></script>
+
+    <script>mocha.run();</script>
+  </body>
+</html>