mapricot 0.1.1 → 0.3.0

package/README.md

@@ -1,31 +1,27 @@
 # Mapricot for JavaScript and TypeScript
 
-The official JavaScript client for the [Mapricot API](https://mapricot.com/): address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every month.
+The official JavaScript client for the [Mapricot API](https://mapricot.com/): address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every 30 days.
 
 ```sh
 npm install mapricot
 ```
 
-It uses the built-in `fetch`, so it has no dependencies and runs in Node.js 20 and later, Deno (as `npm:mapricot`), Bun, Cloudflare Workers, and browsers. Types are included.
+It uses the built-in `fetch`, so it has no dependencies and runs in Node.js 20 and later, Deno (as `npm:mapricot`), Bun, Cloudflare Workers, and browsers as old as Chrome 66, Firefox 57, and Safari 12.1. Types are included.
 
 ## Quick start
 
-Create a server key in the [dashboard](https://app.mapricot.com/) and set it as `MAPRICOT_KEY`:
-
-```sh
-export MAPRICOT_KEY="mapricot_sk_…"
-```
+Create a server key in the [dashboard](https://app.mapricot.com/) and pass it to the client. Keep it out of your source code, for example by reading it from an environment variable as here.
 
 ```js
 import { Mapricot } from "mapricot";
 
-const client = new Mapricot();
+const client = new Mapricot({ apiKey: process.env.MAPRICOT_KEY });
 
 const { results } = await client.search("128 SW 3rd Ave, Portland", { limit: 1 });
 console.log(results[0].label, results[0].lat, results[0].lon);
 ```
 
-Pass the key yourself with `new Mapricot({ apiKey: "mapricot_sk_…" })`. In a web page, use a browser key, which works only from the origins you allow, and keep server keys on your server.
+In a web page, use a browser key, which works only from the origins you allow, and keep server keys on your server.
 
 ## Methods
 
@@ -50,7 +46,15 @@ const { routes } = await client.route([{ lat: 45.5189, lon: -122.6793 }, { lat:
 console.log(routes[0].durationSeconds);
 ```
 
-A route's `polyline` is encoded with six decimal places. Decode it with precision 6, as [decoding a route polyline](https://mapricot.com/docs/polyline/) shows.
+To cancel a request, such as an autocomplete request for text that has since changed, pass an `AbortSignal` as `signal` to any method. The request then rejects with an `AbortError`:
+
+```js
+const controller = new AbortController();
+const request = client.autocomplete("1005 W Burn", { signal: controller.signal });
+controller.abort();
+```
+
+A route's `polyline` is encoded with six decimal places. Decode it with precision 6, as [decoding a route polyline](https://mapricot.com/guides/polyline-decoder/) shows.
 
 If your app shows results, show the credits in each response's `attribution`.
 

package/dist/index.d.ts

@@ -73,25 +73,28 @@ export interface Point {
     lat: number;
     lon: number;
 }
-export interface SearchOptions {
+export interface RequestOptions {
+    /** Cancels the request, such as one for text that has since changed. */
+    signal?: AbortSignal;
+}
+export interface SearchOptions extends RequestOptions {
     focus?: Point;
     country?: string | string[];
     limit?: number;
     lang?: string;
 }
-export interface ReverseOptions {
+export interface ReverseOptions extends RequestOptions {
     limit?: number;
     lang?: string;
 }
-export interface NearbyOptions {
+export interface NearbyOptions extends RequestOptions {
     category?: string | string[];
     radius?: number;
     limit?: number;
     lang?: string;
 }
 export interface ClientOptions {
-    /** Defaults to the MAPRICOT_KEY environment variable. */
-    apiKey?: string;
+    apiKey: string;
     baseUrl?: string;
     /** Milliseconds per attempt. */
     timeout?: number;
@@ -106,25 +109,25 @@ export declare class MapricotError extends Error {
 }
 export declare class Mapricot {
     #private;
-    constructor(options?: ClientOptions);
+    constructor(options: ClientOptions);
     /** Find addresses and places matching free text. */
-    search(q: string, options?: SearchOptions): Promise<Places>;
+    search(q: string, { signal, ...options }?: SearchOptions): Promise<Places>;
     /** Suggest addresses and places as someone types. */
-    autocomplete(q: string, options?: SearchOptions): Promise<Places>;
+    autocomplete(q: string, { signal, ...options }?: SearchOptions): Promise<Places>;
     /** Find the address nearest a coordinate, or the area around it. */
-    reverse(lat: number, lon: number, options?: ReverseOptions): Promise<Places>;
+    reverse(lat: number, lon: number, { signal, ...options }?: ReverseOptions): Promise<Places>;
     /** List places around a coordinate, optionally by category. */
-    nearby(lat: number, lon: number, options?: NearbyOptions): Promise<Places>;
+    nearby(lat: number, lon: number, { signal, ...options }?: NearbyOptions): Promise<Places>;
     /** Look up one place by its Mapricot ID. */
-    place(id: string, options?: {
+    place(id: string, { signal, ...options }?: RequestOptions & {
         lang?: string;
     }): Promise<PlaceResult>;
     /** Find a route through 2 to 20 waypoints. */
-    route(waypoints: Point[], options?: {
+    route(waypoints: Point[], { signal, ...options }?: RequestOptions & {
         mode?: "drive" | "walk" | "bicycle";
     }): Promise<Routes>;
     /** Approximate location of a public IP address. */
-    ip(address: string): Promise<IpLocation>;
+    ip(address: string, { signal }?: RequestOptions): Promise<IpLocation>;
     /** The key's account. Not billed, so it checks a key for free. */
-    account(): Promise<Account>;
+    account({ signal }?: RequestOptions): Promise<Account>;
 }

package/dist/index.js

@@ -1,7 +1,16 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Mapricot_instances, _Mapricot_apiKey, _Mapricot_baseUrl, _Mapricot_timeout, _Mapricot_maxRetries, _Mapricot_request;
 export class MapricotError extends Error {
-    status;
-    code;
-    requestId;
     constructor(status, code, message, requestId) {
         super(message);
         this.name = "MapricotError";
@@ -11,78 +20,92 @@ export class MapricotError extends Error {
     }
 }
 export class Mapricot {
-    #apiKey;
-    #baseUrl;
-    #timeout;
-    #maxRetries;
-    constructor(options = {}) {
-        const apiKey = options.apiKey ?? globalThis.process?.env?.MAPRICOT_KEY;
-        if (!apiKey)
-            throw new Error("Pass apiKey or set MAPRICOT_KEY.");
-        this.#apiKey = apiKey;
-        this.#baseUrl = options.baseUrl ?? "https://api.mapricot.com";
-        this.#timeout = options.timeout ?? 30_000;
-        this.#maxRetries = options.maxRetries ?? 2;
+    constructor(options) {
+        var _a, _b, _c;
+        _Mapricot_instances.add(this);
+        _Mapricot_apiKey.set(this, void 0);
+        _Mapricot_baseUrl.set(this, void 0);
+        _Mapricot_timeout.set(this, void 0);
+        _Mapricot_maxRetries.set(this, void 0);
+        if (!(options === null || options === void 0 ? void 0 : options.apiKey))
+            throw new Error("Pass apiKey, a Mapricot key.");
+        __classPrivateFieldSet(this, _Mapricot_apiKey, options.apiKey, "f");
+        __classPrivateFieldSet(this, _Mapricot_baseUrl, (_a = options.baseUrl) !== null && _a !== void 0 ? _a : "https://api.mapricot.com", "f");
+        __classPrivateFieldSet(this, _Mapricot_timeout, (_b = options.timeout) !== null && _b !== void 0 ? _b : 30000, "f");
+        __classPrivateFieldSet(this, _Mapricot_maxRetries, (_c = options.maxRetries) !== null && _c !== void 0 ? _c : 2, "f");
     }
     /** Find addresses and places matching free text. */
-    search(q, options = {}) {
-        return this.#request("GET", "/v1/search", { q, ...options });
+    search(q, { signal, ...options } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/v1/search", { q, ...options }, signal);
     }
     /** Suggest addresses and places as someone types. */
-    autocomplete(q, options = {}) {
-        return this.#request("GET", "/v1/autocomplete", { q, ...options });
+    autocomplete(q, { signal, ...options } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/v1/autocomplete", { q, ...options }, signal);
     }
     /** Find the address nearest a coordinate, or the area around it. */
-    reverse(lat, lon, options = {}) {
-        return this.#request("GET", "/v1/reverse", { lat, lon, ...options });
+    reverse(lat, lon, { signal, ...options } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/v1/reverse", { lat, lon, ...options }, signal);
     }
     /** List places around a coordinate, optionally by category. */
-    nearby(lat, lon, options = {}) {
-        return this.#request("GET", "/v1/nearby", { lat, lon, ...options });
+    nearby(lat, lon, { signal, ...options } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/v1/nearby", { lat, lon, ...options }, signal);
     }
     /** Look up one place by its Mapricot ID. */
-    place(id, options = {}) {
-        return this.#request("GET", `/v1/places/${encodeURIComponent(id)}`, options);
+    place(id, { signal, ...options } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", `/v1/places/${encodeURIComponent(id)}`, options, signal);
     }
     /** Find a route through 2 to 20 waypoints. */
-    route(waypoints, options = {}) {
-        return this.#request("POST", "/v1/route", {}, { waypoints, ...options });
+    route(waypoints, { signal, ...options } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "POST", "/v1/route", {}, signal, { waypoints, ...options });
     }
     /** Approximate location of a public IP address. */
-    ip(address) {
-        return this.#request("GET", `/v1/ip/${encodeURIComponent(address)}`, {});
+    ip(address, { signal } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", `/v1/ip/${encodeURIComponent(address)}`, {}, signal);
     }
     /** The key's account. Not billed, so it checks a key for free. */
-    account() {
-        return this.#request("GET", "/v1/account", {});
+    account({ signal } = {}) {
+        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/v1/account", {}, signal);
     }
-    async #request(method, path, params, body) {
-        const url = new URL(path, this.#baseUrl);
-        for (const [name, value] of Object.entries(params)) {
-            if (value === undefined)
-                continue;
-            url.searchParams.set(name, format(value));
-        }
-        const headers = { Authorization: `Bearer ${this.#apiKey}` };
-        if (body)
-            headers["Content-Type"] = "application/json";
-        for (let attempt = 0;; attempt++) {
-            const response = await fetch(url, {
-                method,
-                headers,
-                body: body && JSON.stringify(body),
-                signal: AbortSignal.timeout(this.#timeout),
-            });
+}
+_Mapricot_apiKey = new WeakMap(), _Mapricot_baseUrl = new WeakMap(), _Mapricot_timeout = new WeakMap(), _Mapricot_maxRetries = new WeakMap(), _Mapricot_instances = new WeakSet(), _Mapricot_request = async function _Mapricot_request(method, path, params, signal, body) {
+    const url = new URL(path, __classPrivateFieldGet(this, _Mapricot_baseUrl, "f"));
+    for (const [name, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        url.searchParams.set(name, format(value));
+    }
+    const headers = { Authorization: `Bearer ${__classPrivateFieldGet(this, _Mapricot_apiKey, "f")}` };
+    if (body)
+        headers["Content-Type"] = "application/json";
+    for (let attempt = 0;; attempt++) {
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+            throw abortReason(signal);
+        // AbortSignal.timeout and AbortSignal.any would do this, but are missing from browsers before 2022 and 2024.
+        const controller = new AbortController();
+        const cancel = () => controller.abort(abortReason(signal));
+        const timer = setTimeout(() => controller.abort(new DOMException("The request timed out.", "TimeoutError")), __classPrivateFieldGet(this, _Mapricot_timeout, "f"));
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", cancel);
+        let error;
+        try {
+            const response = await fetch(url, { method, headers, body: body && JSON.stringify(body), signal: controller.signal });
             if (response.ok)
                 return (await response.json());
-            const error = await errorFrom(response);
-            if (attempt < this.#maxRetries && retryable(error)) {
-                await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
-                continue;
-            }
-            throw error;
+            error = await errorFrom(response);
+        }
+        finally {
+            clearTimeout(timer);
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", cancel);
+        }
+        if (attempt < __classPrivateFieldGet(this, _Mapricot_maxRetries, "f") && retryable(error)) {
+            await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
+            continue;
         }
+        throw error;
     }
+};
+function abortReason(signal) {
+    var _a;
+    return (_a = signal.reason) !== null && _a !== void 0 ? _a : new DOMException("The request was cancelled.", "AbortError");
 }
 function format(value) {
     if (Array.isArray(value))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapricot",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Official client for the Mapricot API: geocoding, places, routing, and IP geolocation.",
   "keywords": [
     "geocoding",