@carto/api-client 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,7 +1,7 @@
 # CHANGELOG
 
-## 0.0
+## 0.2
 
-### 0.0.1 (UNRELEASED)
+### 0.2.0
 
 - Initial release

package/README.md

@@ -17,8 +17,6 @@ npm install --save @carto/api-client
 
 ## Documentation
 
-WORK IN PROGRESS.
-
 ### Fetching data
 
 Import `vectorTableSource`, `vectorQuerySource`, and other data source functions
@@ -27,25 +25,23 @@ from the `@carto/api-client` package. These are drop-in replacements for the equ
 ```javascript
 import { vectorTableSource } from '@carto/api-client';
 
-const data = vectorTableSource({
+const data = await vectorTableSource({
   accessToken: '••••',
   connectionName: 'carto_dw',
   tableName: 'carto-demo-data.demo_tables.retail_stores'
 });
 
-const { widgetSource } = await data;
-
 // → {name: string; value: number}[]
-const categories = await widgetSource.getCategories({
+const categories = await data.widgetSource.getCategories({
   column: 'store_type',
   operation: 'count',
 });
 
 // → {value: number}
-const formula = await widgetSource.getFormula({operation: 'count'});
+const formula = await data.widgetSource.getFormula({operation: 'count'});
 
 // → {totalCount: number; rows: Record<string, number | string>[]}
-const table = await widgetSource.getTable({
+const table = await data.widgetSource.getTable({
   columns: ['a', 'b', 'c'],
   sortBy: ['a'],
   rowsPerPage: 20
@@ -62,7 +58,7 @@ property to the source factory function.
 ```javascript
 import {vectorTableSource} from '@carto/api-client';
 
-const data = vectorTableSource({
+const data = await vectorTableSource({
   accessToken: '••••',
   connectionName: 'carto_dw',
   tableName: 'carto-demo-data.demo_tables.retail_stores',
@@ -79,7 +75,7 @@ results should not be affected by a filter that the widget itself created.
 
 ```javascript
 // → {name: string; value: number}[]
-const categories = await widgetSource.getCategories({
+const categories = await data.widgetSource.getCategories({
   filterOwner: 'widget-id',
   column: 'store_type',
   operation: 'count',
@@ -92,7 +88,7 @@ To filter the widget source to a spatial region, pass a `spatialFilter` paramete
 
 ```javascript
 // → {name: string; value: number}[]
-const categories = await widgetSource.getCategories({
+const categories = await data.widgetSource.getCategories({
   column: 'store_type',
   operation: 'count',
   spatialFilter: {
@@ -114,22 +110,10 @@ To create a spatial filter from the current [deck.gl `viewState`](https://deck.g
 
 ```javascript
 import {WebMercatorViewport} from '@deck.gl/core';
+import {createViewportSpatialFilter} from '@carto/api-client';
 
-function createViewStatePolygon(viewState) {
-  const viewport = new WebMercatorViewport(viewState);
-  return {
-    type: 'Polygon',
-    coordinates: [
-      [
-        viewport.unproject([0, 0]),
-        viewport.unproject([viewport.width, 0]),
-        viewport.unproject([viewport.width, viewport.height]),
-        viewport.unproject([0, viewport.height]),
-        viewport.unproject([0, 0]),
-      ],
-    ],
-  };
-}
+const viewport = new WebMercatorViewport(viewState);
+const spatialFilter = createViewportSpatialFilter(viewport.getBounds());
 ```
 
 ### Specifying columns to fetch

package/build/api-client.cjs

@@ -1,3 +1,15 @@
+var bboxClip = require('@turf/bbox-clip');
+var bboxPolygon = require('@turf/bbox-polygon');
+var union = require('@turf/union');
+var invariant = require('@turf/invariant');
+var helpers = require('@turf/helpers');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var bboxClip__default = /*#__PURE__*/_interopDefaultLegacy(bboxClip);
+var bboxPolygon__default = /*#__PURE__*/_interopDefaultLegacy(bboxPolygon);
+var union__default = /*#__PURE__*/_interopDefaultLegacy(union);
+
 /**
  * @internal
  * @internalRemarks Source: @carto/react-core
@@ -207,6 +219,129 @@ function getFilter(filters, _ref4) {
   return null;
 }
 
+/**
+ * Returns a {@link SpatialFilter} for a given viewport, typically obtained
+ * from deck.gl's `viewport.getBounds()` method ([west, south, east, north]).
+ * If the viewport covers the entire world (to some margin of error in Web
+ * Mercator space), `undefined` is returned instead.
+ *
+ * If the viewport extends beyond longitude range [-180, +180], the polygon
+ * may be reformatted for compatibility with CARTO APIs.
+ */
+function createViewportSpatialFilter(viewport) {
+  if (_isGlobalViewport(viewport)) {
+    return;
+  }
+  return createPolygonSpatialFilter(bboxPolygon__default["default"](viewport).geometry);
+}
+/**
+ * Returns a {@link SpatialFilter} for a given {@link Polygon} or
+ * {@link MultiPolygon}. If the polygon(s) extend outside longitude
+ * range [-180, +180], the result may be reformatted for compatibility
+ * with CARTO APIs.
+ */
+function createPolygonSpatialFilter(spatialFilter) {
+  return spatialFilter && _normalizeGeometry(spatialFilter) || undefined;
+}
+/**
+ * Check if a viewport is large enough to represent a global coverage.
+ * In this case the spatial filter parameter for widget calculation is removed.
+ *
+ * @internalRemarks Source: @carto/react-core
+ */
+function _isGlobalViewport(viewport) {
+  const [minx, miny, maxx, maxy] = viewport;
+  return maxx - minx > 179.5 * 2 && maxy - miny > 85.05 * 2;
+}
+/**
+ * Normalized a geometry, coming from a mask or a viewport. The parts
+ * spanning outside longitude range [-180, +180] are clipped and "folded"
+ * back to the valid range and unioned to the polygons inide that range.
+ *
+ * It results in a Polygon or MultiPolygon strictly inside the validity range.
+ *
+ * @internalRemarks Source: @carto/react-core
+ */
+function _normalizeGeometry(geometry) {
+  const WORLD = [-180, -90, +180, +90];
+  const worldClip = _clean(bboxClip__default["default"](geometry, WORLD).geometry);
+  const geometryTxWest = _tx(geometry, 360);
+  const geometryTxEast = _tx(geometry, -360);
+  let result = worldClip;
+  if (result && geometryTxWest) {
+    const worldWestClip = _clean(bboxClip__default["default"](geometryTxWest, WORLD).geometry);
+    if (worldWestClip) {
+      const collection = helpers.featureCollection([helpers.feature(result), helpers.feature(worldWestClip)]);
+      const merged = union__default["default"](collection);
+      result = merged ? _clean(merged.geometry) : result;
+    }
+  }
+  if (result && geometryTxEast) {
+    const worldEastClip = _clean(bboxClip__default["default"](geometryTxEast, WORLD).geometry);
+    if (worldEastClip) {
+      const collection = helpers.featureCollection([helpers.feature(result), helpers.feature(worldEastClip)]);
+      const merged = union__default["default"](collection);
+      result = merged ? _clean(merged.geometry) : result;
+    }
+  }
+  return result;
+}
+/** @internalRemarks Source: @carto/react-core */
+function _cleanPolygonCoords(cc) {
+  const coords = cc.filter(c => c.length > 0);
+  return coords.length > 0 ? coords : null;
+}
+/** @internalRemarks Source: @carto/react-core */
+function _cleanMultiPolygonCoords(ccc) {
+  const coords = ccc.map(_cleanPolygonCoords).filter(cc => cc);
+  return coords.length > 0 ? coords : null;
+}
+/** @internalRemarks Source: @carto/react-core */
+function _clean(geometry) {
+  if (!geometry) {
+    return null;
+  }
+  if (_isPolygon(geometry)) {
+    const coords = _cleanPolygonCoords(geometry.coordinates);
+    return coords ? helpers.polygon(coords).geometry : null;
+  }
+  if (_isMultiPolygon(geometry)) {
+    const coords = _cleanMultiPolygonCoords(geometry.coordinates);
+    return coords ? helpers.multiPolygon(coords).geometry : null;
+  }
+  return null;
+}
+/** @internalRemarks Source: @carto/react-core */
+function _txContourCoords(cc, distance) {
+  return cc.map(c => [c[0] + distance, c[1]]);
+}
+/** @internalRemarks Source: @carto/react-core */
+function _txPolygonCoords(ccc, distance) {
+  return ccc.map(cc => _txContourCoords(cc, distance));
+}
+/** @internalRemarks Source: @carto/react-core */
+function _txMultiPolygonCoords(cccc, distance) {
+  return cccc.map(ccc => _txPolygonCoords(ccc, distance));
+}
+/** @internalRemarks Source: @carto/react-core */
+function _tx(geometry, distance) {
+  if (geometry && invariant.getType(geometry) === 'Polygon') {
+    const coords = _txPolygonCoords(geometry.coordinates, distance);
+    return helpers.polygon(coords).geometry;
+  } else if (geometry && invariant.getType(geometry) === 'MultiPolygon') {
+    const coords = _txMultiPolygonCoords(geometry.coordinates, distance);
+    return helpers.multiPolygon(coords).geometry;
+  } else {
+    return null;
+  }
+}
+function _isPolygon(geometry) {
+  return invariant.getType(geometry) === 'Polygon';
+}
+function _isMultiPolygon(geometry) {
+  return invariant.getType(geometry) === 'MultiPolygon';
+}
+
 /******************************************************************************
  * DEFAULTS
  */
@@ -842,14 +977,13 @@ class WidgetTableSource extends WidgetBaseSource {
   }
 }
 
-// loaders.gl
-const isObject = x => x !== null && typeof x === 'object';
-const isPureObject = x => isObject(x) && x.constructor === {}.constructor;
-
 const DEFAULT_TILE_RESOLUTION = 0.5;
 const DEFAULT_AGGREGATION_RES_LEVEL_H3 = 4;
 const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;
 
+const isObject = x => x !== null && typeof x === 'object';
+const isPureObject = x => isObject(x) && x.constructor === {}.constructor;
+
 /**
  *
  * Custom error for reported errors in CARTO Maps API.
@@ -857,7 +991,7 @@ const DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN = 6;
  *
  */
 class CartoAPIError extends Error {
-  constructor(error, errorContext, response) {
+  constructor(error, errorContext, response, responseJson) {
     let responseString = 'Failed to connect';
     if (response) {
       responseString = 'Server returned: ';
@@ -883,6 +1017,7 @@ class CartoAPIError extends Error {
     super(message);
     this.name = 'CartoAPIError';
     this.response = response;
+    this.responseJson = responseJson;
     this.error = error;
     this.errorContext = errorContext;
   }
@@ -897,15 +1032,8 @@ function formatErrorKey(key) {
 const DEFAULT_API_BASE_URL = 'https://gcp-us-east1.api.carto.com';
 const DEFAULT_CLIENT = 'deck-gl-carto';
 const V3_MINOR_VERSION = '3.4';
-const MAX_GET_LENGTH = 8192;
-const DEFAULT_PARAMETERS = {
-  v: V3_MINOR_VERSION,
-  deckglVersion: "0.1.0"
-};
-const DEFAULT_HEADERS = {
-  Accept: 'application/json',
-  'Content-Type': 'application/json'
-};
+// Fastly default limit is 8192; leave some padding.
+const DEFAULT_MAX_LENGTH_URL = 7000;
 
 function joinPath(...args) {
   return args.map(part => part.endsWith('/') ? part.slice(0, -1) : part).join('/');
@@ -922,36 +1050,42 @@ function buildSourceUrl({
 }
 
 /**
- * Simple encode parameter
+ * Parameters added to all requests issued with `requestWithParameters()`.
+ * These parameters override parameters already in the base URL, but not
+ * user-provided parameters.
  */
-function encodeParameter(name, value) {
-  if (isPureObject(value) || Array.isArray(value)) {
-    return `${name}=${encodeURIComponent(JSON.stringify(value))}`;
-  }
-  return `${name}=${encodeURIComponent(value)}`;
-}
+const DEFAULT_PARAMETERS = {
+  v: V3_MINOR_VERSION,
+  deckglVersion: "0.2.0"
+};
+const DEFAULT_HEADERS = {
+  Accept: 'application/json',
+  'Content-Type': 'application/json'
+};
 const REQUEST_CACHE = new Map();
 async function requestWithParameters({
   baseUrl,
-  parameters,
-  headers: customHeaders,
-  errorContext
+  parameters = {},
+  headers: customHeaders = {},
+  errorContext,
+  maxLengthURL = DEFAULT_MAX_LENGTH_URL
 }) {
   parameters = {
     ...DEFAULT_PARAMETERS,
     ...parameters
   };
-  const key = createCacheKey(baseUrl, parameters || {}, customHeaders || {});
+  baseUrl = excludeURLParameters(baseUrl, Object.keys(parameters));
+  const key = createCacheKey(baseUrl, parameters, customHeaders);
   if (REQUEST_CACHE.has(key)) {
     return REQUEST_CACHE.get(key);
   }
-  const url = parameters ? createURLWithParameters(baseUrl, parameters) : baseUrl;
+  const url = createURLWithParameters(baseUrl, parameters);
   const headers = {
     ...DEFAULT_HEADERS,
     ...customHeaders
   };
   /* global fetch */
-  const fetchPromise = url.length > MAX_GET_LENGTH ? fetch(baseUrl, {
+  const fetchPromise = url.length > maxLengthURL ? fetch(baseUrl, {
     method: 'POST',
     body: JSON.stringify(parameters),
     headers
@@ -959,17 +1093,19 @@ async function requestWithParameters({
     headers
   });
   let response;
+  let responseJson;
   const jsonPromise = fetchPromise.then(_response => {
     response = _response;
     return response.json();
   }).then(json => {
+    responseJson = json;
     if (!response || !response.ok) {
       throw new Error(json.error);
     }
     return json;
   }).catch(error => {
     REQUEST_CACHE.delete(key);
-    throw new CartoAPIError(error, errorContext, response);
+    throw new CartoAPIError(error, errorContext, response, responseJson);
   });
   REQUEST_CACHE.set(key, jsonPromise);
   return jsonPromise;
@@ -983,9 +1119,33 @@ function createCacheKey(baseUrl, parameters, headers) {
     headers: headerEntries
   });
 }
-function createURLWithParameters(baseUrl, parameters) {
-  const encodedParameters = Object.entries(parameters).map(([key, value]) => encodeParameter(key, value));
-  return `${baseUrl}?${encodedParameters.join('&')}`;
+/**
+ * Appends query string parameters to a URL. Existing URL parameters are kept,
+ * unless there is a conflict, in which case the new parameters override
+ * those already in the URL.
+ */
+function createURLWithParameters(baseUrlString, parameters) {
+  const baseUrl = new URL(baseUrlString);
+  for (const [key, value] of Object.entries(parameters)) {
+    if (isPureObject(value) || Array.isArray(value)) {
+      baseUrl.searchParams.set(key, JSON.stringify(value));
+    } else {
+      baseUrl.searchParams.set(key, value.toString());
+    }
+  }
+  return baseUrl.toString();
+}
+/**
+ * Deletes query string parameters from a URL.
+ */
+function excludeURLParameters(baseUrlString, parameters) {
+  const baseUrl = new URL(baseUrlString);
+  for (const param of parameters) {
+    if (baseUrl.searchParams.has(param)) {
+      baseUrl.searchParams.delete(param);
+    }
+  }
+  return baseUrl.toString();
 }
 
 /* eslint-disable camelcase */
@@ -993,7 +1153,8 @@ const SOURCE_DEFAULTS = {
   apiBaseUrl: DEFAULT_API_BASE_URL,
   clientId: DEFAULT_CLIENT,
   format: 'tilejson',
-  headers: {}
+  headers: {},
+  maxLengthURL: DEFAULT_MAX_LENGTH_URL
 };
 async function baseSource(endpoint, options, urlParameters) {
   const {
@@ -1016,6 +1177,7 @@ async function baseSource(endpoint, options, urlParameters) {
   const baseUrl = buildSourceUrl(mergedOptions);
   const {
     clientId,
+    maxLengthURL,
     format
   } = mergedOptions;
   const headers = {
@@ -1036,7 +1198,8 @@ async function baseSource(endpoint, options, urlParameters) {
     baseUrl,
     parameters,
     headers,
-    errorContext
+    errorContext,
+    maxLengthURL
   });
   const dataUrl = mapInstantiation[format].url[0];
   if (cache) {
@@ -1047,7 +1210,8 @@ async function baseSource(endpoint, options, urlParameters) {
     const json = await requestWithParameters({
       baseUrl: dataUrl,
       headers,
-      errorContext
+      errorContext,
+      maxLengthURL
     });
     if (accessToken) {
       json.accessToken = accessToken;
@@ -1057,7 +1221,8 @@ async function baseSource(endpoint, options, urlParameters) {
   return await requestWithParameters({
     baseUrl: dataUrl,
     headers,
-    errorContext
+    errorContext,
+    maxLengthURL
   });
 }
 
@@ -1066,13 +1231,11 @@ const boundaryQuerySource = async function (options) {
     columns,
     filters,
     tilesetTableName,
-    matchingColumn = 'id',
     propertiesSqlQuery,
     queryParameters
   } = options;
   const urlParameters = {
     tilesetTableName,
-    matchingColumn,
     propertiesSqlQuery
   };
   if (columns) {
@@ -1092,12 +1255,10 @@ const boundaryTableSource = async function (options) {
     filters,
     tilesetTableName,
     columns,
-    matchingColumn = 'id',
     propertiesTableName
   } = options;
   const urlParameters = {
     tilesetTableName,
-    matchingColumn,
     propertiesTableName
   };
   if (columns) {
@@ -1116,7 +1277,8 @@ const h3QuerySource$1 = async function (options) {
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_H3,
     sqlQuery,
     spatialDataColumn = 'h3',
-    queryParameters
+    queryParameters,
+    filters
   } = options;
   const urlParameters = {
     aggregationExp,
@@ -1130,6 +1292,9 @@ const h3QuerySource$1 = async function (options) {
   if (queryParameters) {
     urlParameters.queryParameters = queryParameters;
   }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
   return baseSource('query', options, urlParameters);
 };
 
@@ -1139,7 +1304,8 @@ const h3TableSource$1 = async function (options) {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_H3,
     spatialDataColumn = 'h3',
-    tableName
+    tableName,
+    filters
   } = options;
   const urlParameters = {
     aggregationExp,
@@ -1150,6 +1316,9 @@ const h3TableSource$1 = async function (options) {
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
   }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
   return baseSource('table', options, urlParameters);
 };
 
@@ -1165,11 +1334,15 @@ const h3TilesetSource = async function (options) {
 
 const rasterSource = async function (options) {
   const {
-    tableName
+    tableName,
+    filters
   } = options;
   const urlParameters = {
     name: tableName
   };
+  if (filters) {
+    urlParameters.filters = filters;
+  }
   return baseSource('raster', options, urlParameters);
 };
 
@@ -1180,7 +1353,8 @@ const quadbinQuerySource$1 = async function (options) {
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
     sqlQuery,
     spatialDataColumn = 'quadbin',
-    queryParameters
+    queryParameters,
+    filters
   } = options;
   const urlParameters = {
     aggregationExp,
@@ -1194,6 +1368,9 @@ const quadbinQuerySource$1 = async function (options) {
   if (queryParameters) {
     urlParameters.queryParameters = queryParameters;
   }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
   return baseSource('query', options, urlParameters);
 };
 
@@ -1203,7 +1380,8 @@ const quadbinTableSource$1 = async function (options) {
     aggregationExp,
     aggregationResLevel = DEFAULT_AGGREGATION_RES_LEVEL_QUADBIN,
     spatialDataColumn = 'quadbin',
-    tableName
+    tableName,
+    filters
   } = options;
   const urlParameters = {
     aggregationExp,
@@ -1214,6 +1392,9 @@ const quadbinTableSource$1 = async function (options) {
   if (aggregationResLevel) {
     urlParameters.aggregationResLevel = String(aggregationResLevel);
   }
+  if (filters) {
+    urlParameters.filters = filters;
+  }
   return baseSource('table', options, urlParameters);
 };
 
@@ -1403,6 +1584,8 @@ exports.WidgetQuerySource = WidgetQuerySource;
 exports.WidgetTableSource = WidgetTableSource;
 exports.addFilter = addFilter;
 exports.clearFilters = clearFilters;
+exports.createPolygonSpatialFilter = createPolygonSpatialFilter;
+exports.createViewportSpatialFilter = createViewportSpatialFilter;
 exports.getClient = getClient;
 exports.getFilter = getFilter;
 exports.h3QuerySource = h3QuerySource;