@maptiler/client 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/.github/pull_request_template.md +11 -0
  2. package/.github/workflows/format-lint.yml +24 -0
  3. package/CHANGELOG.md +25 -0
  4. package/dist/maptiler-client.cjs +388 -306
  5. package/dist/maptiler-client.cjs.map +1 -1
  6. package/dist/maptiler-client.d.ts +270 -100
  7. package/dist/maptiler-client.min.mjs +1 -1
  8. package/dist/maptiler-client.mjs +380 -294
  9. package/dist/maptiler-client.mjs.map +1 -1
  10. package/package.json +7 -5
  11. package/readme.md +133 -1
  12. package/rollup.config.js +3 -3
  13. package/dist/maptiler-client.umd.js +0 -1541
  14. package/dist/maptiler-client.umd.js.map +0 -1
  15. package/dist/maptiler-client.umd.min.js +0 -1
  16. package/examples/test-browser-es.html +0 -103
  17. package/examples/test-browser-umd.html +0 -90
  18. package/examples/test-node.js +0 -52
  19. package/src/callFetch.ts +0 -18
  20. package/src/config.ts +0 -68
  21. package/src/defaults.ts +0 -11
  22. package/src/demProfiler/getElevation.ts +0 -46
  23. package/src/demProfiler/index.ts +0 -240
  24. package/src/demProfiler/tileCover.ts +0 -96
  25. package/src/geometry/area.ts +0 -96
  26. package/src/geometry/distance.ts +0 -45
  27. package/src/geometry/index.ts +0 -3
  28. package/src/geometry/util.ts +0 -34
  29. package/src/index.ts +0 -114
  30. package/src/language.ts +0 -87
  31. package/src/mapstyle.ts +0 -968
  32. package/src/services/ServiceError.ts +0 -13
  33. package/src/services/coordinates.ts +0 -263
  34. package/src/services/data.ts +0 -63
  35. package/src/services/geocoding.ts +0 -461
  36. package/src/services/geolocation.ts +0 -139
  37. package/src/services/simplify.ts +0 -87
  38. package/src/services/staticMaps.ts +0 -463
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maptiler/client",
3
- "version": "1.7.0",
3
+ "version": "1.8.0",
4
4
  "description": "Javascript & Typescript wrapper to MapTiler Cloud API",
5
5
  "module": "dist/maptiler-client.mjs",
6
6
  "types": "dist/maptiler-client.d.ts",
@@ -35,12 +35,14 @@
35
35
  "build": "rm -rf dist/*; NODE_ENV=production rollup -c",
36
36
  "dev": "rm -rf dist/*; NODE_ENV=development rollup -c -w",
37
37
  "devserve": "rm -rf dist/*; NODE_ENV=development rollup -c -w & serve && fg",
38
- "format": "prettier --write \"src/**/*.{js,ts,tsx}\"",
39
- "lint": "eslint --fix \"src/**/*.{js,ts}\"",
38
+ "format:fix": "prettier --write \"src/**/*.{js,ts,tsx}\"",
39
+ "format": "prettier -c \"src/**/*.{js,ts,tsx}\"",
40
+ "lint:fix": "eslint --fix \"src/**/*.{js,ts}\"",
41
+ "lint": "eslint \"src/**/*.{js,ts}\"",
40
42
  "docmd": "rm -rf docsmd/*; typedoc --readme none --plugin typedoc-plugin-markdown --out docsmd src/index.ts",
41
43
  "dochtml": "rm -rf docs/*; typedoc; cp -r images docs/",
42
44
  "doc": "npm run docmd; npm run dochtml",
43
- "prepare": "npm run format; npm run lint; npm run test; npm run build",
45
+ "prepare": "npm run format:fix && npm run lint:fix && npm run test && npm run build",
44
46
  "test:prod": "vitest test --run",
45
47
  "test:dev": "vitest test --watch",
46
48
  "test": ""
@@ -74,6 +76,6 @@
74
76
  "dependencies": {
75
77
  "@rollup/pluginutils": "^5.0.5",
76
78
  "@types/geojson": "^7946.0.10",
77
- "web-merc-projection": "^1.3.2"
79
+ "quick-lru": "^7.0.0"
78
80
  }
79
81
  }
package/readme.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <a href="https://docs.maptiler.com/client-js/">offcial page →</a><br>
2
+ <a href="https://docs.maptiler.com/client-js/">official page →</a><br>
3
3
  <img src="images/maptiler-client-logo.svg" width="400px">
4
4
  </p>
5
5
 
@@ -24,6 +24,7 @@ The **MapTiler Client JS** exposes a number of handy functions that wrap API cal
24
24
  - [Coordidinate systems search and tranform](#-coordinates)
25
25
  - [User data fetching as GeoJSON](#-data)
26
26
  - [Static maps of all sorts](#%EF%B8%8F-static-maps)
27
+ - [Elevation lookup with batch features](#-elevation)
27
28
 
28
29
  ## Why?
29
30
 
@@ -58,6 +59,8 @@ import {
58
59
  coordinates,
59
60
  data,
60
61
  staticMaps,
62
+ elevation,
63
+ math,
61
64
  } from '@maptiler/client';
62
65
  ```
63
66
 
@@ -327,6 +330,135 @@ And voila!
327
330
 
328
331
  Read more about bounded static maps on our official [API documentation](https://docs.maptiler.com/cloud/api/static-maps/#auto-fitted-image).
329
332
 
333
+ ## 🏔️ Elevation
334
+ With the elevation API, it's possible to get the elevation in metter from any location. It's possible lookup and compute elevation for a single location, to provide a batch of points, from a GeoJSON LineString or from a GeoJSON MultiLineString!
335
+
336
+ > ℹ️ Under the hood, the elevation API is fueled by MapTiler Cloud's **RGB Terrain** raster tileset, which is a composite of many high-resolution DEMs from all over the world, currated and processed by our geodata team! The same dataset is also fueling our SDK's elevation (3D terrain) and the hillshading we use in many of our styles.
337
+
338
+ > 📣 Note for **TypeScript** users: internaly, the elevation feature relies on some *GeoJSON* types definitions that can be found in this NPM package: `@types/geojson`. Namely `LineString`, `MultiLineString` and `Position`. It may improve your developer experience to also use these types.
339
+
340
+ Let's see how to use it:
341
+
342
+ ### At a single location
343
+ ```ts
344
+ // Not mandatory, but it's to explain where the type comes from:
345
+ import { Position } from "geojson";
346
+
347
+ const montBlancPeak: Position = [6.864884, 45.832743];
348
+ const elevatedPosition = await maptilerClient.elevation.at(montBlancPeak);
349
+ ```
350
+ The returned value is also a *GeoJSON* `Position` array, but with three elements: `[lng, lat, elevation]`.
351
+
352
+ Read more about elevation lookup for a single location in our [official documentation](https://docs.maptiler.com/client-js/elevation/#at).
353
+
354
+ ### Batch mode
355
+ ```ts
356
+ // Not mandatory, but it's to explain where the type comes from:
357
+ import { Position } from "geojson";
358
+
359
+ const peaks: Position[] = [
360
+ [6.864884, 45.832743], // Mont Blanc, Alps
361
+ [86.9250, 27.9881], // Mount Everest, Himalayas
362
+ [-70.0109, -32.6532], // Aconcagua, Andes
363
+ [-151.0064, 63.0695], // Denali, Alaska
364
+ [37.3556, -3.0674], // Mount Kilimanjaro
365
+ [42.4453, 43.3499], // Mount Elbrus, Caucasus
366
+ [137.1595, -4.0784], // Puncak Jaya, Sudirman Range
367
+ [-140.4055, 60.5672], // Mount Logan, Saint Elias Mountains
368
+ [138.73111, 35.358055], // Mount Fuji
369
+ ];
370
+
371
+ const elevatedPeaks = await maptilerClient.elevation.batch(peaks);
372
+ ```
373
+
374
+ Read more about elevation lookup for a batch of locations in our [official documentation](https://docs.maptiler.com/client-js/elevation/#batch).
375
+
376
+ ### From a GeoJSON LineString
377
+ In the *GeoJSON* LineString case, it clones the entire structure and the positions arrays of the clone will contain three element: `[lng, lat, elevation]`. The original LineString is not mutated nor pointed at.
378
+
379
+ ```ts
380
+ // Not mandatory, but it's to explain where the type comes from:
381
+ import { LineString } from "geojson";
382
+
383
+
384
+ const someLineString: LineString = {
385
+ type: "LineString",
386
+ coordinates: [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]]
387
+ };
388
+
389
+ const someElevatedLineString = await maptilerClient.elevation.fromLineString(someLineString);
390
+ // someElevatedLineString is also of type LineString
391
+ ```
392
+
393
+ Read more about elevation lookup for a `LineString` in our [official documentation](https://docs.maptiler.com/client-js/elevation/#linestring).
394
+
395
+ ### From a GeoJSON MultiLineString
396
+ In the *GeoJSON* MultiLineString case, it clones the entire structure and the positions arrays of the clone will contain three element: `[lng, lat, elevation]`. The original MultiLineString is not mutated nor pointed at.
397
+
398
+ ```ts
399
+ // Not mandatory, but it's to explain where the type comes from:
400
+ import { MultiLineString } from "geojson";
401
+
402
+
403
+ const someMultiLineString: MultiLineString = {
404
+ type: "LineString",
405
+ coordinates: [
406
+ [[6.864884, 45.832743], [86.9250, 27.9881], [-70.0109, -32.6532]],
407
+ [[-151.0064, 63.0695], [37.3556, -3.0674], [42.4453, 43.3499]],
408
+ [[137.1595, -4.0784], [-140.4055, 60.5672], [138.73111, 35.358055]],
409
+ ]
410
+ };
411
+
412
+ const someElevatedMultiLineString = await maptilerClient.elevation.fromMultiLineString(someMultiLineString);
413
+ // someElevatedMultiLineString is also of type MultiLineString
414
+ ```
415
+
416
+ Read more about elevation lookup for a `MultiLineString` in our [official documentation](https://docs.maptiler.com/client-js/elevation/#multilinestring).
417
+
418
+ ### Caching
419
+ In order to increase performance while reducing unnecessary elevation data fetching, the elevation tiles are cached. This is particularly important for the LineString and MultiLineString lookups because GeoJSON data are likely to come from a recorded or planned route, where position points are very close to one another.
420
+
421
+ ## 🧮 Math
422
+ Some operations can be fairly repetitive: WGS84 to Mercator, WGS84 to *zxy* tile index, distance between two points with Haversine formula, etc. As a result, we have decided to expose a `math` package providing the most recurent feature, so that, just like us at MapTiler, you no longer need to copy-paste the same function from your previous project!
423
+
424
+ The `math` package differs from the others in the sense that it does not call the MapTiler Cloud API, instead it operates fully on the machine it's running on.
425
+
426
+ Here are some examples:
427
+
428
+ ```ts
429
+ // Not mandatory, but it's to explain where the type comes from:
430
+ import { Position } from "geojson";
431
+
432
+ // Some constants
433
+ const earthRadius = maptilerClient.math.EARTH_RADIUS;
434
+ const earthCircumference = maptilerClient.math.EARTH_CIRCUMFERENCE;
435
+
436
+ const montBlancPeakWgs84: Position = [6.864884, 45.832743];
437
+
438
+ // From WGS84 to Mercator
439
+ const montBlancPeakMerc = maptilerClient.math.wgs84ToMercator(montBlancPeakWgs84); // also of type Position
440
+
441
+ // From Mercator to WGS84
442
+ const montBlancPeakWgs84Again = maptilerClient.math.mercatorToWgs84(montBlancPeakMerc);
443
+
444
+ // A great-circle distance in meter:
445
+ const from: Position = /* ... */;
446
+ const to: Position = /* ... */;
447
+ const distance = maptilerClient.math.haversineDistanceWgs84(from, to);
448
+
449
+ // Full distance of a route made of many positions
450
+ const route: Position[] = /* ... */;
451
+ const totalDistance = maptilerClient.math.haversineCumulatedDistanceWgs84(route);
452
+
453
+ // Lon lat to tile index, given a zoom level. An [x, y] array is returned
454
+ const tileXY = maptilerClient.math.wgs84ToTileIndex(montBlancPeakWgs84, 14);
455
+ // Possible to have floating point tile indices with a third argument to `false`
456
+
457
+ // and many more!
458
+ ```
459
+
460
+ Please find out more about the math package in our [official documentation](https://docs.maptiler.com/client-js/math):
461
+
330
462
  # From NodeJS
331
463
  NodeJS includes a stable `fetch()` function only from its version *18*, and this client does not contain a polyfill. If the `fetch()` function exists (browser or Node >= 18) then it is going to be resolved automatically, Yet, a custom `fetch()` function can be provided to the `config` object for Node < 18.
332
464
 
package/rollup.config.js CHANGED
@@ -25,7 +25,7 @@ const bundles = [
25
25
  watch: {
26
26
  include: "src/**"
27
27
  },
28
- external: ["web-merc-projection"]
28
+ external: ["web-merc-projection", "quick-lru"]
29
29
  },
30
30
 
31
31
  // CJS module, not minified + sourcemap
@@ -48,7 +48,7 @@ const bundles = [
48
48
  watch: {
49
49
  include: "src/**"
50
50
  },
51
- external: ["web-merc-projection"]
51
+ external: ["web-merc-projection", "quick-lru"]
52
52
  },
53
53
 
54
54
  // UMD module, not minified
@@ -106,7 +106,7 @@ if (process.env.NODE_ENV === "production") {
106
106
  }
107
107
  ],
108
108
  input: "src/index.ts",
109
- external: ["web-merc-projection"],
109
+ external: ["web-merc-projection", "quick-lru"],
110
110
  },
111
111
  {
112
112
  plugins: [