@loaders.gl/loader-utils 4.3.0-alpha.1 → 4.3.0-alpha.3

package/src/lib/sources/tile-source.ts

@@ -2,15 +2,36 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-// import type {DataSourceProps} from './data-source';
-// import {DataSource} from './data-source';
+import type {DataSourceProps} from './data-source';
+import {DataSource} from './data-source';
 
 /**
- * Normalized capabilities of an Image service
+ * Props for a TileSource
+ */
+export type TileSourceProps = DataSourceProps;
+
+/**
+ * MapTileSource - data sources that allow data to be queried by (geospatial) extents
+ * @note
+ * - If geospatial, bounding box is expected to be in web mercator coordinates
+ */
+export interface TileSource<
+  PropsT extends TileSourceProps = TileSourceProps,
+  MetadataT extends TileSourceMetadata = TileSourceMetadata
+> extends DataSource<PropsT> {
+  // extends DataSource {
+  getMetadata(): Promise<MetadataT>;
+  /** Flat parameters */
+  getTile(parameters: GetTileParameters): Promise<unknown | null>;
+  /** deck.gl compatibility: TileLayer and MTVLayer */
+  getTileData(parameters: GetTileDataParameters): Promise<unknown | null>;
+}
+
+// HELPER TYPES
+
+/**
+ * Normalized capabilities of an tile service
  * Sources are expected to normalize the response to capabilities
- * @example
- *  A WMS service would normalize the response to the WMS `GetCapabilities` data structure extracted from WMS XML response
- *  into an TileSourceMetadata.
  */
 export type TileSourceMetadata = {
   format?: string;
@@ -53,7 +74,7 @@ export type TileSourceLayer = {
 };
 
 /**
- * Generic parameters for requesting an image from an image source
+ * Generic parameters for requesting an tile from an tile source
  */
 export type GetTileParameters = {
   /** bounding box of the requested map image */
@@ -62,46 +83,33 @@ export type GetTileParameters = {
   x: number;
   /** tile y coordinate */
   y: number;
-  /** Coordinate reference system for the image (not the bounding box) */
+  /** Coordinate reference system for the tile */
   crs?: string;
   /** Layers to render */
   layers?: string | string[];
   /** Styling */
   styles?: unknown;
-  /** requested format for the return image */
+  /** requested format for the return image (in case of bitmap tiles) */
   format?: 'image/png';
 };
 
-export type TileLoadParameters = {
+/** deck.gl compatibility: parameters for TileSource.getTileData() */
+export type GetTileDataParameters = {
+  /** Tile index */
   index: {x: number; y: number; z: number};
   id: string;
+  /** Bounding Box */
   bbox: TileBoundingBox;
+  /** Zoom level */
   zoom?: number;
   url?: string | null;
   signal?: AbortSignal;
   userData?: Record<string, any>;
 };
 
-/** deck.gl compatible bounding box */
+/** deck.gl compatibility: bounding box */
 export type TileBoundingBox = NonGeoBoundingBox | GeoBoundingBox;
+/** deck.gl compatibility: bounding box */
 export type GeoBoundingBox = {west: number; north: number; east: number; south: number};
+/** deck.gl compatibility: bounding box */
 export type NonGeoBoundingBox = {left: number; top: number; right: number; bottom: number};
-
-/**
- * Props for a TileSource
- */
-export type TileSourceProps = {}; // DataSourceProps;
-
-/**
- * MapTileSource - data sources that allow data to be queried by (geospatial) extents
- * @note
- * - If geospatial, bounding box is expected to be in web mercator coordinates
- */
-export interface TileSource<MetadataT extends TileSourceMetadata> {
-  // extends DataSource {
-  getMetadata(): Promise<MetadataT>;
-  /** Flat parameters */
-  getTile(parameters: GetTileParameters): Promise<unknown | null>;
-  /** deck.gl style parameters */
-  getTileData?(parameters: TileLoadParameters): Promise<unknown | null>;
-}

package/src/lib/sources/utils/utils.ts

@@ -29,7 +29,7 @@ export function getFetchFunction(options?: LoaderOptions) {
   return (url) => fetch(url);
 }
 
-export function mergeImageServiceProps<Props extends {loadOptions?: any}>(
+export function mergeImageSourceLoaderProps<Props extends {loadOptions?: any}>(
   props: Props
 ): Required<Props> {
   // @ts-expect-error

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

@@ -0,0 +1,74 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Schema, GeoJSONTable, BinaryFeatureCollection} from '@loaders.gl/schema';
+import type {DataSourceProps} from './data-source';
+import {DataSource} from './data-source';
+
+export type VectorSourceProps = DataSourceProps;
+
+/**
+ * VectorSource - data sources that allow features to be queried by (geospatial) extents
+ * @note
+ * - If geospatial, bounding box is expected to be in web mercator coordinates
+ */
+export abstract class VectorSource<
+  PropsT extends VectorSourceProps = VectorSourceProps
+> extends DataSource<PropsT> {
+  static type: string = 'template';
+  static testURL = (url: string): boolean => false;
+
+  abstract getSchema(): Promise<Schema>;
+  abstract getMetadata(options: {formatSpecificMetadata?: boolean}): Promise<VectorSourceMetadata>;
+  abstract getFeatures(
+    parameters: GetFeaturesParameters
+  ): Promise<GeoJSONTable | BinaryFeatureCollection>;
+}
+
+// PARAMETER TYPES
+
+/**
+ * Normalized capabilities of an Image service
+ * @example
+ *  The WMSSourceLoader will normalize the response to the WMS `GetCapabilities`
+ *  data structure extracted from WMS XML response into an VectorSourceMetadata.
+ */
+export type VectorSourceMetadata = {
+  name: string;
+  title?: string;
+  abstract?: string;
+  keywords: string[];
+  layers: VectorSourceLayer[];
+  /**
+   * Attempts to preserve the original format specific metadata from the underlying source,
+   * May be an approximate representation
+   */
+  formatSpecificMetadata?: Record<string, any>;
+};
+
+/** Description of one data layer in the image source */
+export type VectorSourceLayer = {
+  /** Name of this layer */
+  name?: string;
+  /** Human readable title of this layer */
+  title?: string;
+  /** Coordinate systems supported by this layer */
+  crs?: string[];
+  /** layer limits in unspecified CRS:84-like lng/lat, for quick access w/o CRS calculations. */
+  boundingBox?: [min: [x: number, y: number], max: [x: number, y: number]];
+  /** Sub layers of this layer */
+  layers?: VectorSourceLayer[];
+};
+
+/** Generic parameters for requesting an image from an image source */
+export type GetFeaturesParameters = {
+  /** Layers to render */
+  layers: string | string[];
+  /** bounding box on the map (only return features within this bbox) */
+  boundingBox: [min: [x: number, y: number], max: [x: number, y: number]];
+  /** crs for the returned features (not the bounding box) */
+  crs?: string;
+  /** @deprecated requested format for the return image */
+  format?: 'geojson' | 'binary';
+};

package/src/lib/sources/vector-tile-source.ts

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {TileSource, TileSourceProps, TileSourceMetadata} from './tile-source';
-import type {GetTileParameters} from './tile-source';
+import type {Schema, Feature, BinaryFeatureCollection} from '@loaders.gl/schema';
+import {TileSource, TileSourceProps, TileSourceMetadata, GetTileParameters} from './tile-source';
+import type {GetTileDataParameters} from './tile-source';
 
 export type VectorTile = unknown;
 
@@ -13,7 +14,13 @@ export type VectorTileSourceProps = TileSourceProps;
  * VectorTileSource - data sources that allow data to be queried by (geospatial) tile
  * @note If geospatial, bounding box is expected to be in web mercator coordinates
  */
-export interface VectorTileSource<MetadataT extends TileSourceMetadata = TileSourceMetadata>
-  extends TileSource<MetadataT> {
+export interface VectorTileSource<
+  PropsT extends VectorTileSourceProps = VectorTileSourceProps,
+  MetadataT extends TileSourceMetadata = TileSourceMetadata
+> extends TileSource<PropsT, MetadataT> {
+  getSchema(): Promise<Schema>;
   getVectorTile(parameters: GetTileParameters): Promise<VectorTile | null>;
+  getTileData(
+    parameters: GetTileDataParameters
+  ): Promise<Feature[] | BinaryFeatureCollection | null>;
 }

package/src/source-types.ts

@@ -0,0 +1,49 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {DataSource, DataSourceProps} from './lib/sources/data-source';
+
+/**
+ * A `Source` contains metadata and a factory method for creating instances of a specific `DataSource`.
+ * It allows a list of `Source` objects to be passed to methods
+ * @example
+ *  `createDataSource(... , [MVTSource, PMTilesSource, ...])
+ */
+export interface Source<
+  DataSourceT extends DataSource = DataSource,
+  DataSourcePropsT extends DataSourceProps = any
+> {
+  /** Type of source created by this service */
+  source?: DataSourceT;
+  /** Type of props used when creating sources */
+  props?: DataSourcePropsT;
+
+  /** Name of the service */
+  name: string;
+  id: string;
+  /** Module containing the service */
+  module: string;
+  /** Version of the loaders.gl package containing this service. */
+  version: string;
+  /** URL extensions that this service uses */
+  extensions: string[];
+  /** MIME extensions that this service uses */
+  mimeTypes: string[];
+  /** Default options */
+  options: DataSourcePropsT;
+
+  /** Type string identifying this service, e.g. 'wms' */
+  type: string;
+  /** Can source be created from a URL */
+  fromUrl: boolean;
+  /** Can source be created from a Blob or File */
+  fromBlob: boolean;
+
+  /** Check if a URL can support this service */
+  testURL: (url: string) => boolean;
+  /** Test data */
+  testData?: (data: Blob) => boolean;
+  /** Create a source  */
+  createDataSource(data: string | Blob, props: DataSourcePropsT): DataSourceT;
+}

package/dist/service-types.d.ts

@@ -1,10 +0,0 @@
-import type { ImageSource, ImageSourceProps } from "./lib/sources/image-source.js";
-/** Export interface source */
-export interface Service<SourceT = ImageSource, SourcePropsT = ImageSourceProps> {
-    source?: SourceT;
-    props?: SourcePropsT;
-    type: string;
-    testURL: (url: string) => boolean;
-    create(props: SourcePropsT): SourceT;
-}
-//# sourceMappingURL=service-types.d.ts.map

package/dist/service-types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"service-types.d.ts","sourceRoot":"","sources":["../src/service-types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,WAAW,EAAE,gBAAgB,EAAC,sCAAmC;AAE9E,8BAA8B;AAC9B,MAAM,WAAW,OAAO,CAAC,OAAO,GAAG,WAAW,EAAE,YAAY,GAAG,gBAAgB;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;CACtC"}

package/src/service-types.ts

@@ -1,14 +0,0 @@
-// loaders.gl
-// SPDX-License-Identifier: MIT
-// Copyright (c) vis.gl contributors
-
-import type {ImageSource, ImageSourceProps} from './lib/sources/image-source';
-
-/** Export interface source */
-export interface Service<SourceT = ImageSource, SourcePropsT = ImageSourceProps> {
-  source?: SourceT;
-  props?: SourcePropsT;
-  type: string;
-  testURL: (url: string) => boolean;
-  create(props: SourcePropsT): SourceT;
-}