@carto/api-client 0.5.13 → 0.5.15-alpha.raster-0

package/src/fetch-map/vec-expr-evaluator.ts

@@ -0,0 +1,386 @@
+import jsep from 'jsep';
+
+/**
+ * Create vector expresion evaluator.
+ *
+ * Used to calculate vector expressions, such as `(band_1 * 3) + band_2/2`,
+ * where `band_1` and `band_2` are arrays or typed arrays.
+ *
+ * Note that all vector operations are element-wise, in paricular `band_1 * band_2`
+ * is not "mathematical" dot or cross product, but just element-wise multiplication.
+ *
+ * Based on:
+ * - Copyright (c) 2013 Stephen Oney, http://jsep.from.so/, MIT License
+ * - Copyright (c) 2023 Don McCurdy, https://github.com/donmccurdy/expression-eval, MIT License
+ */
+export function createVecExprEvaluator(
+  expression: string | jsep.Expression
+): VecExprEvaluator | null {
+  try {
+    const parsed = compile(expression);
+    const evalFun = (context: Record<string, VecExprResult>) =>
+      evaluate(parsed, context);
+    evalFun.symbols = getSymbols(parsed);
+    return evalFun as VecExprEvaluator;
+  } catch {
+    return null;
+  }
+}
+
+export function evaluateVecExpr(
+  expression: string | jsep.Expression,
+  context: Record<string, VecExprResult>
+) {
+  try {
+    return createVecExprEvaluator(expression)?.(context);
+  } catch {
+    return null;
+  }
+}
+
+export enum ErrorCode {
+  InvalidSyntax,
+  UnknownIdentifier,
+}
+
+export type ValidationResult = {
+  valid: boolean;
+  errorCode?: ErrorCode;
+  errorMessage?: string;
+};
+
+export function validateVecExprSyntax(
+  expression: string | jsep.Expression,
+  context: Record<string, unknown>
+): ValidationResult {
+  let parsed: jsep.Expression;
+  try {
+    parsed = compile(expression);
+  } catch (e: any) {
+    return {
+      valid: false,
+      errorCode: ErrorCode.InvalidSyntax,
+      errorMessage: e && 'message' in e ? String(e.message) : String(e),
+    };
+  }
+  return validate(parsed, context);
+}
+
+export function createValidationContext(
+  validSymbols: string[]
+): Record<string, unknown> {
+  return validSymbols.reduce(
+    (acc, symbol) => {
+      acc[symbol] = 1;
+      return acc;
+    },
+    {} as Record<string, unknown>
+  );
+}
+
+export type VecExprVecLike =
+  | number[]
+  | Float32Array
+  | Float64Array
+  | Uint8Array
+  | Int8Array
+  | Int32Array
+  | Uint32Array
+  | Uint16Array
+  | Int16Array;
+
+export type VecExprResult = number | VecExprVecLike;
+
+export type VecExprEvaluator = {
+  (context: object): VecExprResult;
+
+  symbols?: string[];
+};
+
+function createResultArray(
+  typeTemplate: VecExprVecLike,
+  length: number = typeTemplate.length
+): number[] {
+  return new Array(length);
+}
+
+function isVecLike(a: unknown): a is number[] {
+  return Array.isArray(a) || ArrayBuffer.isView(a);
+}
+
+const createBinopVec =
+  (scalarBinOp: (a: number, b: number) => number) =>
+  (left: number[], right: number[]) => {
+    const length = Math.min(left.length, right.length);
+    const r = createResultArray(left, length);
+    for (let i = 0; i < length; i++) {
+      r[i] = scalarBinOp(left[i], right[i]);
+    }
+    return r;
+  };
+
+const createBinopVecNum =
+  (scalarBinOp: (a: number, b: number) => number) =>
+  (left: number[], right: number) => {
+    const length = left.length;
+    const r = createResultArray(left, length);
+    for (let i = 0; i < length; i++) {
+      r[i] = scalarBinOp(left[i], right);
+    }
+    return r;
+  };
+
+// number vec op
+const createBinopNumVec =
+  (scalarBinOp: (a: number, b: number) => number) =>
+  (left: number, right: number[]) => {
+    const length = right.length;
+    const r = createResultArray(right, length);
+    for (let i = 0; i < length; i++) {
+      r[i] = scalarBinOp(left, right[i]);
+    }
+    return r;
+  };
+
+const createUnopVec = (scalarUnop: (a: number) => number) => (a: number[]) => {
+  const length = a.length;
+  const r = createResultArray(a, length);
+  for (let i = 0; i < length; i++) {
+    r[i] = scalarUnop(a[i]);
+  }
+  return r;
+};
+
+function mapDictValues<V, NewV>(dict: Record<string, V>, fun: (v: V) => NewV) {
+  return Object.keys(dict).reduce(
+    (acc, key) => {
+      acc[key] = fun(dict[key]);
+      return acc;
+    },
+    {} as Record<string, NewV>
+  );
+}
+
+const binopsNum: Record<string, (a: number, b: number) => number> = {
+  '||': (a: number, b: number) => a || b,
+  '&&': (a: number, b: number) => a && b,
+  '|': (a: number, b: number) => a | b,
+  '^': (a: number, b: number) => a ^ b,
+  '&': (a: number, b: number) => a & b,
+  '==': (a: number, b: number) => Number(a == b),
+  '!=': (a: number, b: number) => Number(a != b),
+  '===': (a: number, b: number) => Number(a === b),
+  '!==': (a: number, b: number) => Number(a !== b),
+  '<': (a: number, b: number) => Number(a < b),
+  '>': (a: number, b: number) => Number(a > b),
+  '<=': (a: number, b: number) => Number(a <= b),
+  '>=': (a: number, b: number) => Number(a >= b),
+  '<<': (a: number, b: number) => a << b,
+  '>>': (a: number, b: number) => a >> b,
+  '>>>': (a: number, b: number) => a >>> b,
+  '+': (a: number, b: number) => a + b,
+  '-': (a: number, b: number) => a - b,
+  '*': (a: number, b: number) => a * b,
+  '/': (a: number, b: number) => a / b,
+  '%': (a: number, b: number) => a % b,
+};
+
+const unopsNum: Record<string, (a: number) => number> = {
+  '-': (a: number) => -a,
+  '+': (a: number) => +a,
+  '~': (a: number) => ~a,
+  '!': (a: number) => Number(!a),
+};
+
+const binopsVector = mapDictValues(binopsNum, createBinopVec) as Record<
+  string,
+  Binop
+>;
+const binopsNumVec = mapDictValues(binopsNum, createBinopNumVec) as Record<
+  string,
+  Binop
+>;
+const binopsVecNum = mapDictValues(binopsNum, createBinopVecNum) as Record<
+  string,
+  Binop
+>;
+
+const unopsVector = mapDictValues(unopsNum, createUnopVec) as Record<
+  string,
+  UnOp
+>;
+
+type UnOp = (a: VecExprResult) => VecExprResult;
+type Binop = (a: VecExprResult, b: VecExprResult) => VecExprResult;
+
+function getBinop(
+  operator: string,
+  left: VecExprResult,
+  right: VecExprResult
+): Binop {
+  const isLeftVec = isVecLike(left);
+  const isRightVec = isVecLike(right);
+  if (isLeftVec && isRightVec) {
+    return binopsVector[operator];
+  } else if (isLeftVec) {
+    return binopsVecNum[operator];
+  } else if (isRightVec) {
+    return binopsNumVec[operator];
+  } else {
+    return binopsNum[operator] as Binop;
+  }
+}
+
+type AnyExpression =
+  | jsep.ArrayExpression
+  | jsep.BinaryExpression
+  | jsep.MemberExpression
+  | jsep.CallExpression
+  | jsep.ConditionalExpression
+  | jsep.Identifier
+  | jsep.Literal
+  | jsep.ThisExpression
+  | jsep.UnaryExpression;
+
+export function evaluate(
+  _node: jsep.Expression,
+  context: Record<string, VecExprResult>
+): VecExprResult {
+  const node = _node as AnyExpression;
+
+  switch (node.type) {
+    case 'BinaryExpression': {
+      const left = evaluate(node.left, context);
+      const right = evaluate(node.right, context);
+      const binopFun = getBinop(node.operator, left, right);
+
+      return binopFun(left, right);
+    }
+
+    case 'ConditionalExpression': {
+      const val = evaluate(node.test, context);
+      if (isVecLike(val)) {
+        const length = val.length;
+        const consequentVal = evaluate(node.consequent, context);
+        const alternateVal = evaluate(node.alternate, context);
+        const r = createResultArray(val);
+        for (let i = 0; i < length; i++) {
+          const entryVal = val[i] ? consequentVal : alternateVal;
+          r[i] = isVecLike(entryVal)
+            ? (entryVal[i] ?? NaN)
+            : (entryVal as number);
+        }
+        return r;
+      } else {
+        return val
+          ? evaluate(node.consequent, context)
+          : evaluate(node.alternate, context);
+      }
+    }
+
+    case 'Identifier':
+      return context[node.name];
+
+    case 'Literal':
+      return node.value as number;
+
+    case 'UnaryExpression': {
+      const val = evaluate(node.argument, context);
+      const unopFun = isVecLike(val)
+        ? unopsVector[node.operator]
+        : (unopsNum[node.operator] as UnOp);
+      return unopFun(val);
+    }
+
+    default:
+      return undefined as unknown as VecExprResult;
+  }
+}
+
+const validResult = {valid: true};
+
+function visit(_node: jsep.Expression, visitor: (node: AnyExpression) => void) {
+  const node = _node as AnyExpression;
+
+  visitor(node);
+  switch (node.type) {
+    case 'BinaryExpression': {
+      visit(node.left, visitor);
+      visit(node.right, visitor);
+      break;
+    }
+
+    case 'ConditionalExpression': {
+      visit(node.test, visitor);
+      visit(node.consequent, visitor);
+      visit(node.alternate, visitor);
+      break;
+    }
+
+    case 'UnaryExpression': {
+      visit(node.argument, visitor);
+      break;
+    }
+  }
+}
+
+const supportedExpressionTypes = [
+  'BinaryExpression',
+  'UnaryExpression',
+  'ConditionalExpression',
+  'LogicalExpression',
+  'Identifier',
+  'Literal',
+];
+
+function validate(_node: jsep.Expression, context: object): ValidationResult {
+  const node = _node as AnyExpression;
+
+  const errors: ValidationResult[] = [];
+
+  visit(node, (node) => {
+    if (!supportedExpressionTypes.includes(node.type)) {
+      errors.push({
+        valid: false,
+        errorCode: ErrorCode.InvalidSyntax,
+        errorMessage: `Not allowed`,
+      });
+      return;
+    }
+    if (node.type === 'Identifier') {
+      if (!Object.prototype.hasOwnProperty.call(context, node.name)) {
+        return errors.push({
+          valid: false,
+          errorCode: ErrorCode.UnknownIdentifier,
+          errorMessage: `"${node.name}" not found`,
+        });
+      }
+    }
+    if (node.type === 'Literal') {
+      // we actually support only numbers
+      if (typeof node.value !== 'number') {
+        return errors.push({
+          valid: false,
+          errorCode: ErrorCode.InvalidSyntax,
+          errorMessage: `Only number literals are supported`,
+        });
+      }
+    }
+  });
+  return errors.length ? errors[0] : validResult;
+}
+
+function getSymbols(node: jsep.Expression): string[] {
+  const symbols = new Set<string>();
+
+  visit(node, (node) => {
+    if (node.type === 'Identifier') {
+      symbols.add(node.name);
+    }
+  });
+  return Array.from(symbols);
+}
+
+export function compile(expression: string | jsep.Expression) {
+  return jsep(expression);
+}

package/src/index.ts

@@ -2,7 +2,18 @@ export * from './client.js';
 export * from './constants.js';
 export * from './deck/index.js';
 export * from './fetch-map/index.js';
-export type {LayerDescriptor, LayerType} from './fetch-map/index.js';
+export type {
+  LayerDescriptor,
+  LayerType,
+  _getRasterTileLayerStyleProps,
+} from './fetch-map/index.js';
+export {
+  createVecExprEvaluator as _createVecExprEvaluator,
+  evaluateVecExpr as _evaluateVecExpr,
+  validateVecExprSyntax as _validateVecExprSyntax,
+  type VecExprResult as _VecExprResult,
+  ErrorCode as _ErrorCode,
+} from './fetch-map/vec-expr-evaluator.js';
 export * from './filters.js';
 export * from './geo.js';
 export * from './sources/index.js';

package/src/sources/h3-tileset-source.ts

@@ -34,6 +34,7 @@ export const h3TilesetSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'h3',
+        spatialDataBounds: result.bounds,
       }),
     })
   ) as Promise<H3TilesetSourceResponse>;

package/src/sources/quadbin-tileset-source.ts

@@ -34,6 +34,7 @@ export const quadbinTilesetSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'quadbin',
+        spatialDataBounds: result.bounds,
       }),
     })
   ) as Promise<QuadbinTilesetSourceResponse>;

package/src/sources/raster-source.ts

@@ -43,6 +43,7 @@ export const rasterSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn: 'quadbin',
         spatialDataType: 'quadbin',
+        spatialDataBounds: result.bounds,
         rasterMetadata: result.raster_metadata!,
       }),
     })

package/src/sources/vector-tileset-source.ts

@@ -35,6 +35,7 @@ export const vectorTilesetSource = async function (
         tileFormat: getTileFormat(result),
         spatialDataColumn,
         spatialDataType: 'geo',
+        spatialDataBounds: result.bounds,
       }),
     })
   ) as Promise<VectorTilesetSourceResponse>;

package/src/widget-sources/types.ts

@@ -1,3 +1,4 @@
+import type {BBox} from 'geojson';
 import type {
   SpatialFilterPolyfillMode,
   TileResolution,
@@ -206,6 +207,9 @@ export interface TimeSeriesRequestOptions extends BaseRequestOptions {
   splitByCategoryValues?: string[];
 }
 
+/** @experimental */
+export type ExtentRequestOptions = BaseRequestOptions;
+
 /******************************************************************************
  * WIDGET API RESPONSES
  */
@@ -256,3 +260,6 @@ export type TimeSeriesResponse = {
 
 /** Response from {@link WidgetRemoteSource#getHistogram}. */
 export type HistogramResponse = number[];
+
+/** @experimental */
+export type ExtentResponse = {bbox: BBox};

package/src/widget-sources/widget-remote-source.ts

@@ -2,6 +2,8 @@ import {executeModel, type ModelSource} from '../models/index.js';
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentRequestOptions,
+  ExtentResponse,
   FeaturesRequestOptions,
   FeaturesResponse,
   FormulaRequestOptions,
@@ -24,6 +26,8 @@ import type {Filters} from '../types.js';
 import {AggregationTypes, ApiVersion} from '../constants.js';
 import {getApplicableFilters} from '../filters.js';
 import {OTHERS_CATEGORY_NAME} from './constants.js';
+import {requestWithParameters} from '../api/request-with-parameters.js';
+import type {APIErrorContext} from '../api/carto-api-error.js';
 
 export type WidgetRemoteSourceProps = WidgetSourceProps;
 
@@ -389,4 +393,64 @@ export abstract class WidgetRemoteSource<
       categories: res.metadata?.categories,
     }));
   }
+
+  /** @experimental */
+  async getExtent(options: ExtentRequestOptions = {}): Promise<ExtentResponse> {
+    const {signal, filters = this.props.filters, filterOwner} = options;
+
+    const {
+      type,
+      data,
+      apiBaseUrl,
+      apiVersion,
+      connectionName,
+      spatialDataColumn,
+      spatialDataType,
+      queryParameters,
+    } = this.getModelSource(filters, filterOwner);
+
+    assert(apiVersion === ApiVersion.V3, 'Stats API requires CARTO 3+');
+
+    let url: string;
+
+    const parameters: Record<string, unknown> = {filters, spatialDataType};
+
+    if (type === 'query') {
+      url = `${apiBaseUrl}/${apiVersion}/stats/${connectionName}/${spatialDataColumn}`;
+      parameters.q = data;
+      parameters.queryParameters = queryParameters;
+    } else {
+      url = `${apiBaseUrl}/${apiVersion}/stats/${connectionName}/${data}/${spatialDataColumn}`;
+    }
+
+    const headers = {
+      Authorization: `Bearer ${this.props.accessToken}`,
+      ...this.props.headers,
+    };
+
+    const errorContext: APIErrorContext = {
+      requestType: 'Tile stats',
+      connection: connectionName,
+      type: type,
+    };
+
+    type StatsResponse = {
+      extent: {
+        xmin: number;
+        ymin: number;
+        xmax: number;
+        ymax: number;
+      };
+    };
+
+    return requestWithParameters<StatsResponse>({
+      baseUrl: url,
+      headers,
+      signal,
+      errorContext,
+      parameters,
+    }).then(({extent: {xmin, ymin, xmax, ymax}}) => ({
+      bbox: [xmin, ymin, xmax, ymax],
+    }));
+  }
 }

package/src/widget-sources/widget-source.ts

@@ -1,6 +1,8 @@
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentRequestOptions,
+  ExtentResponse,
   FeaturesRequestOptions,
   FeaturesResponse,
   FormulaRequestOptions,
@@ -124,4 +126,7 @@ export abstract class WidgetSource<
   abstract getTimeSeries(
     options: TimeSeriesRequestOptions
   ): Promise<TimeSeriesResponse>;
+
+  /** @experimental */
+  abstract getExtent(options?: ExtentRequestOptions): Promise<ExtentResponse>;
 }

package/src/widget-sources/widget-tileset-source-impl.ts

@@ -2,6 +2,7 @@
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentResponse,
   FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
@@ -390,6 +391,11 @@ export class WidgetTilesetSourceImpl extends WidgetSource<WidgetTilesetSourcePro
     };
   }
 
+  /** @experimental */
+  async getExtent(): Promise<ExtentResponse> {
+    return Promise.reject(new Error('not implemented'));
+  }
+
   /****************************************************************************
    * INTERNAL
    */

package/src/widget-sources/widget-tileset-source.ts

@@ -1,6 +1,7 @@
 import type {
   CategoryRequestOptions,
   CategoryResponse,
+  ExtentResponse,
   FeaturesResponse,
   FormulaRequestOptions,
   FormulaResponse,
@@ -17,7 +18,7 @@ import type {
 } from './types.js';
 import type {SpatialFilter, Tile} from '../types.js';
 import type {TileFeatureExtractOptions} from '../filters/index.js';
-import type {FeatureCollection} from 'geojson';
+import type {BBox, FeatureCollection} from 'geojson';
 import {WidgetSource, type WidgetSourceProps} from './widget-source.js';
 import {Method} from '../workers/constants.js';
 import type {WorkerRequest, WorkerResponse} from '../workers/types.js';
@@ -29,6 +30,10 @@ export type WidgetTilesetSourceProps = WidgetSourceProps &
   Omit<TilesetSourceOptions, 'filters'> & {
     tileFormat: TileFormat;
     spatialDataType: SpatialDataType;
+    /**
+     * Extent of spatial data, typically from TileJSON. Does not include filters.
+     */
+    spatialDataBounds: BBox;
   };
 
 export type WidgetTilesetSourceResult = {widgetSource: WidgetTilesetSource};
@@ -320,4 +325,11 @@ export class WidgetTilesetSource<
   }: RangeRequestOptions): Promise<RangeResponse> {
     return this._executeWorkerMethod(Method.GET_RANGE, [options], signal);
   }
+
+  /** @experimental */
+  async getExtent(): Promise<ExtentResponse> {
+    return Promise.resolve({
+      bbox: this.props.spatialDataBounds,
+    });
+  }
 }