@superrouteca/smap 0.0.0-stage → 1.0.0

package/dist/smap-client.mjs

@@ -0,0 +1,308 @@
+/* Generated by tools/sync-js.sh from the sMap repository (see SOURCE.json). Do not edit. */
+var smapClientModule = { exports: {} };
+(function (module, exports, define) {
+/*! sMap JS client 1.0.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*
+ * Runs wherever `fetch` exists: browsers, Node.js 18+, workers; elsewhere (mini programs, older runtimes) pass your
+ * own `fetch`. UMD: `window.SMapClient`, `require('smap-client')`, or an AMD module.
+ *
+ *   const client = new SMapClient({ baseUrl: 'https://tile.srsr.ca', getToken: () => myServer.mapToken() });
+ *   const keyed = new SMapClient({ baseUrl: 'https://tile.srsr.ca', apiKey: 'smk_…' });   // or a map key
+ *   const tile = await client.tile('basemap', 12, 1143, 1493);   // Uint8Array (vector tile)
+ *   const style = await client.style('light', 'en');             // style document
+ *
+ * Every request goes to the nearest node that answers (asked of baseUrl, remembered for an hour) and moves to the
+ * next one when a node fails.
+ */
+(function (root, factory) {
+  if (typeof define === 'function' && define.amd) { define([], factory); }
+  else if (typeof module === 'object' && module.exports) { module.exports = factory(); }
+  else { root.SMapClient = factory(); }
+}(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  var VERSION = '1.0.1';
+  var NODE_TTL = 3600 * 1000;          // the measured order
+  var KNOWN_TTL = 30 * 86400 * 1000;   // the last node list received, used when none can be read
+
+  function unique(list) {
+    var seen = {};
+    return list.filter(function (u) { if (!u || seen[u]) { return false; } seen[u] = true; return true; });
+  }
+  var memory = {};
+
+  function store() {
+    try {
+      if (typeof localStorage !== 'undefined') { localStorage.getItem('smap'); return localStorage; }
+    } catch (e) { /* storage unavailable */ }
+    return { getItem: function (k) { return memory[k] || null; }, setItem: function (k, v) { memory[k] = v; } };
+  }
+
+  function decodeBase64Url(s) {
+    s = s.replace(/-/g, '+').replace(/_/g, '/');
+    while (s.length % 4) { s += '='; }
+    if (typeof atob === 'function') { return atob(s); }
+    return Buffer.from(s, 'base64').toString('binary');
+  }
+
+  /** Seconds since 1970 when a token expires; 0 when it cannot be read. */
+  function tokenExpiry(token) {
+    try { return JSON.parse(decodeBase64Url(String(token).split('.')[1])).exp || 0; } catch (e) { return 0; }
+  }
+
+  function SMapError(message, status, url) {
+    var e = new Error(message);
+    e.name = 'SMapError';
+    e.status = status || 0;
+    e.url = url || '';
+    return e;
+  }
+
+  /**
+   * @param {Object} options
+   * @param {string} options.baseUrl                   the public sMap address (e.g. https://tile.srsr.ca)
+   * @param {string} [options.token]                   a map token; or
+   * @param {function(): (string|Promise<string>)} [options.getToken]  called at start and before each token expires
+   * @param {string} [options.apiKey]                  a map key (`smk_…`); with a token both are sent (token first)
+   * @param {string[]} [options.nodes]                 node URLs known in advance (used while baseUrl is down)
+   * @param {boolean} [options.nearest=true]           read from the nearest node
+   * @param {function} [options.fetch]                 a fetch implementation (default: the global one)
+   * @param {number} [options.timeoutMs=15000]         per request
+   */
+  function SMapClient(options) {
+    if (!(this instanceof SMapClient)) { return new SMapClient(options); }
+    options = options || {};
+    if (!options.baseUrl) { throw SMapError('sMap: baseUrl is required'); }
+    this.baseUrl = String(options.baseUrl).replace(/\/$/, '');
+    this._fetch = options.fetch || (typeof fetch === 'function' ? fetch.bind(typeof self !== 'undefined' ? self : globalThis) : null);
+    if (!this._fetch) { throw SMapError('sMap: no fetch available; pass options.fetch'); }
+    this._token = options.token || null;
+    this._getToken = options.getToken || null;
+    this._apiKey = options.apiKey || null;
+    this._nearest = options.nearest !== false;
+    this._seeds = (options.nodes || []).map(function (u) { return String(u).replace(/\/$/, ''); });
+    this._timeout = options.timeoutMs || 15000;
+    this._nodes = null;      // ordered: nearest first
+    this._picking = null;
+    this._tokening = null;
+  }
+
+  SMapClient.version = VERSION;
+  SMapClient.tokenExpiry = tokenExpiry;
+
+  SMapClient.prototype._timed = function (url, init, ms) {
+    var ctrl = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    var timer = ctrl ? setTimeout(function () { ctrl.abort(); }, ms) : null;
+    init = init || {};
+    if (ctrl) { init.signal = ctrl.signal; }
+    return this._fetch(url, init).then(function (res) { clearTimeout(timer); return res; }, function (e) { clearTimeout(timer); throw e; });
+  };
+
+  /** The token to send now, asking getToken again two minutes before it expires. */
+  SMapClient.prototype.token = function () {
+    var self = this;
+    var exp = this._token ? tokenExpiry(this._token) : 0;
+    var fresh = this._token && (!exp || exp - Date.now() / 1000 > 120);
+    if (fresh || !this._getToken) { return Promise.resolve(this._token); }
+    if (!this._tokening) {
+      this._tokening = Promise.resolve(this._getToken()).then(function (t) {
+        self._token = t;
+        self._tokening = null;
+        return t;
+      }, function (e) { self._tokening = null; throw e; });
+    }
+    return this._tokening;
+  };
+
+  /**
+   * The nodes in the order they are tried: nearest first, then the others; baseUrl alone when nearest is off or the
+   * list cannot be read.
+   *
+   * @returns {Promise<string[]>}
+   */
+  SMapClient.prototype.nodes = function () {
+    var self = this;
+    if (this._nodes) { return Promise.resolve(this._nodes); }
+    if (!this._nearest) { this._nodes = [this.baseUrl]; return Promise.resolve(this._nodes); }
+    if (this._picking) { return this._picking; }
+    var key = 'smap.nodes:' + this.baseUrl;
+    var storage = store();
+    var saved = null;
+    try { saved = JSON.parse(storage.getItem(key) || 'null'); } catch (e) { saved = null; }
+    if (saved && saved.urls && saved.urls.length && Date.now() - saved.at < NODE_TTL) {
+      this._nodes = saved.urls;
+      return Promise.resolve(this._nodes);
+    }
+    // Every node this client knows of: the kept list (30 days), the seed list, then baseUrl.
+    var kept = saved && saved.known && Date.now() - (saved.knownAt || 0) < KNOWN_TTL ? saved.known : [];
+    var known = unique([this.baseUrl].concat(this._seeds, kept));
+    this._picking = this._discover(known)
+      .then(function (list) {
+        var urls = list || unique(self._seeds.concat(kept));
+        if (urls.length === 0) { return { order: [self.baseUrl], known: null }; }
+        return self._measure(urls).then(function (order) { return { order: order, known: list }; });
+      })
+      .then(function (r) {
+        self._nodes = r.order;
+        self._picking = null;
+        // An order is remembered for the hour only when a node list was read; a guess made while nothing answered
+        // is tried again by the next client instead of being kept.
+        var record = { urls: r.known ? r.order : [], at: r.known ? Date.now() : 0, known: r.known || kept, knownAt: r.known ? Date.now() : (saved && saved.knownAt) || 0 };
+        try { storage.setItem(key, JSON.stringify(record)); } catch (e) { /* ignore */ }
+        return r.order;
+      });
+    return this._picking;
+  };
+
+  /** Asks each node in turn for the node list (any node answers the whole list); null when none answers. */
+  SMapClient.prototype._discover = function (candidates) {
+    var self = this;
+    function ask(i) {
+      if (i >= candidates.length) { return Promise.resolve(null); }
+      return self._timed(candidates[i] + '/v1/nodes', {}, 2000)
+        .then(function (res) { return res.ok ? res.json() : null; })
+        .then(function (body) {
+          var urls = ((body && body.nodes) || []).map(function (n) { return String(n.url).replace(/\/$/, ''); });
+          return urls.length ? urls : ask(i + 1);
+        }, function () { return ask(i + 1); });
+    }
+    return ask(0);
+  };
+
+  /** Times one small request to each node: fastest first, silent ones after, baseUrl last when not listed. */
+  SMapClient.prototype._measure = function (urls) {
+    var self = this;
+    return Promise.all(urls.map(function (url) {
+      var t0 = Date.now();
+      return self._timed(url + '/v1/ping', { cache: 'no-store' }, 1500)
+        .then(function (res) { return { url: url, ms: res.ok ? Date.now() - t0 : Infinity }; }, function () { return { url: url, ms: Infinity }; });
+    })).then(function (timed) {
+      timed.sort(function (a, b) { return a.ms - b.ms; });
+      var order = timed.map(function (t) { return t.url; });
+      if (order.indexOf(self.baseUrl) < 0) { order.push(self.baseUrl); }
+      return order;
+    });
+  };
+
+  /** Forgets the chosen node order, so the next request measures again. */
+  SMapClient.prototype.resetNodes = function () {
+    this._nodes = null;
+    var key = 'smap.nodes:' + this.baseUrl;
+    try {
+      var saved = JSON.parse(store().getItem(key) || 'null');
+      // The kept node list survives a reset; only the measured order is forgotten.
+      store().setItem(key, JSON.stringify(saved ? { urls: [], at: 0, known: saved.known, knownAt: saved.knownAt } : null));
+    } catch (e) { /* ignore */ }
+  };
+
+  /**
+   * GET `path` from the nearest node that answers, with the token; a node that fails (network error, 5xx) is moved
+   * to the end and the next one is tried. 4xx answers are final.
+   *
+   * @param {string} path      starting with /
+   * @param {Object} [headers]
+   * @returns {Promise<Response>}
+   */
+  SMapClient.prototype.request = function (path, headers) {
+    var self = this;
+    return Promise.all([this.nodes(), this.token()]).then(function (r) {
+      var nodes = r[0].slice();
+      var token = r[1];
+      var last = null;
+      function attempt(i) {
+        if (i >= nodes.length) { throw last || SMapError('sMap: no node answered', 0, path); }
+        var h = {};
+        for (var k in (headers || {})) { if (Object.prototype.hasOwnProperty.call(headers, k)) { h[k] = headers[k]; } }
+        if (token) { h.Authorization = 'Bearer ' + token; }
+        if (self._apiKey) { h['X-SMap-Key'] = self._apiKey; }
+        var url = nodes[i] + path;
+        return self._timed(url, { headers: h }, self._timeout).then(function (res) {
+          if (res.status >= 500) {
+            last = SMapError('sMap: HTTP ' + res.status, res.status, url);
+            self._demote(nodes[i]);
+            return attempt(i + 1);
+          }
+          if (!res.ok && res.status !== 206) {
+            return res.text().then(function (text) { throw SMapError('sMap: ' + (text || ('HTTP ' + res.status)), res.status, url); });
+          }
+          return res;
+        }, function (e) {
+          last = SMapError('sMap: ' + (e && e.message ? e.message : 'network error'), 0, url);
+          self._demote(nodes[i]);
+          return attempt(i + 1);
+        });
+      }
+      return attempt(0);
+    });
+  };
+
+  SMapClient.prototype._demote = function (url) {
+    if (!this._nodes || this._nodes.length < 2) { return; }
+    var i = this._nodes.indexOf(url);
+    if (i >= 0) { this._nodes.splice(i, 1); this._nodes.push(url); }
+  };
+
+  function bytes(res) { return res.arrayBuffer().then(function (b) { return new Uint8Array(b); }); }
+
+  // A map key also goes in the query of styles and TileJSON: the service carries it into their tile URLs, so a
+  // renderer given the document reads its tiles with the key.
+  SMapClient.prototype._withKey = function (path) {
+    if (!this._apiKey) { return path; }
+    return path + (path.indexOf('?') >= 0 ? '&' : '?') + 'key=' + encodeURIComponent(this._apiKey);
+  };
+
+  /**
+   * A style document ('light', 'white', 'grayscale', 'dark', 'black') with labels in `language`.
+   * Its tile URLs point at the node that answered.
+   */
+  SMapClient.prototype.style = function (flavor, language) {
+    var q = language ? '?lang=' + encodeURIComponent(language) : '';
+    return this.request(this._withKey('/v1/styles/' + encodeURIComponent(flavor || 'light') + q)).then(function (r) { return r.json(); });
+  };
+
+  /** TileJSON of a source (bounds, zooms, layers, tile URL template). */
+  SMapClient.prototype.tileJSON = function (source) {
+    return this.request(this._withKey('/v1/tiles/' + encodeURIComponent(source || 'basemap'))).then(function (r) { return r.json(); });
+  };
+
+  /** One vector tile as bytes; null where the source has no tile (204 / 404). */
+  SMapClient.prototype.tile = function (source, z, x, y) {
+    var path = '/v1/tiles/' + encodeURIComponent(source) + '/' + (z | 0) + '/' + (x | 0) + '/' + (y | 0);
+    return this.request(path).then(function (r) { return r.status === 204 ? null : bytes(r); }, function (e) {
+      if (e && e.status === 404) { return null; }
+      throw e;
+    });
+  };
+
+  /** Raw bytes `[start, end]` (inclusive) of a source's archive, where your access allows raw reads. */
+  SMapClient.prototype.range = function (source, start, end) {
+    return this.request('/' + encodeURIComponent(source) + '.pmtiles', { Range: 'bytes=' + start + '-' + end }).then(bytes);
+  };
+
+  /** A font glyph range (`0-255.pbf` style), for renderers that load fonts themselves. */
+  SMapClient.prototype.glyphs = function (fontstack, range) {
+    return this.request('/v1/fonts/' + encodeURIComponent(fontstack) + '/' + range + '.pbf').then(bytes);
+  };
+
+  /**
+   * Headers and URL rewriting for a renderer that fetches by itself: returns the URL unchanged plus the
+   * Authorization (and map key) headers to add for sMap URLs; none for any other host.
+   */
+  SMapClient.prototype.authorize = function (url) {
+    var self = this;
+    return this.token().then(function (token) {
+      var ours = url.indexOf(self.baseUrl) === 0 || self._seeds.concat(self._nodes || []).some(function (n) { return url.indexOf(n) === 0; });
+      var headers = {};
+      if (ours && token) { headers.Authorization = 'Bearer ' + token; }
+      if (ours && self._apiKey) { headers['X-SMap-Key'] = self._apiKey; }
+      return { url: url, headers: headers };
+    });
+  };
+
+  return SMapClient;
+}));
+
+}).call(typeof globalThis !== 'undefined' ? globalThis : undefined, smapClientModule, smapClientModule.exports, undefined);
+var SMapClient = smapClientModule.exports;
+export { SMapClient };
+export default SMapClient;