@nextgis/geocoder 1.16.8 → 1.18.3

package/lib/index.d.ts

@@ -6,25 +6,77 @@
  */
 
 import CancelablePromise from '@nextgis/cancelable-promise';
+import type { FeatureItem } from '@nextgis/ngw-connector';
+import type { FetchNgwItemsOptions } from '@nextgis/ngw-kit';
 import { GeoJsonObject } from 'geojson';
 import { LngLatBoundsArray } from '@nextgis/utils';
 import NgwConnector from '@nextgis/ngw-connector';
-import { ResourceStoreItem } from '@nextgis/ngw-connector';
+import type { NgwConnectorOptions } from '@nextgis/ngw-connector';
+import type { ResourceItem } from '@nextgis/ngw-connector';
 
+/**
+ * Represents the base class for a geocoder.
+ * This abstract class provides the basic methods that every geocoder should implement.
+ *
+ * @template O - The type of options that can be passed to the geocoder.
+ */
 declare abstract class BaseGeocoder<O extends Record<string, any> = Record<string, any>> {
     constructor(options?: O);
+    /**
+     * Search method to retrieve geocoding results.
+     *
+     * @abstract
+     * @param {string} query - The search string to geocode.
+     * @yields {AsyncGenerator<SearchItem>} - An async generator that yields search results.
+     */
     abstract search(query: string): AsyncGenerator<SearchItem>;
+    /**
+     * Method to retrieve detailed result for a specific search item.
+     *
+     * @abstract
+     * @param {SearchItem} item - The search item to get detailed result for.
+     * @returns {CancelablePromise<any>} - A promise that resolves to the detailed result.
+     */
     abstract result(item: SearchItem): CancelablePromise<any>;
+    /**
+     * Optional method to abort any ongoing geocoding requests.
+     *
+     * @abstract
+     */
     abstract abort?(): void;
 }
 
+/**
+ * Abstract base class representing a search provider.
+ * It builds upon the BaseGeocoder functionalities with provider-specific properties.
+ * @template O - Options type which extends BaseProviderOptions.
+ */
 export declare abstract class BaseProvider<O extends BaseProviderOptions = BaseProviderOptions> extends BaseGeocoder<O> {
+    /**
+     * URL endpoint for the search service.
+     * This is where queries will be sent to obtain search results.
+     */
     searchUrl?: string;
+    /**
+     * Label to represent the provider.
+     * Useful for user interfaces to display the source of search results.
+     */
     label?: string;
 }
 
+/**
+ * Options for initializing a basic search provider.
+ */
 export declare interface BaseProviderOptions {
+    /**
+     * URL endpoint for the search service.
+     * This is where queries will be sent to obtain search results.
+     */
     searchUrl?: string;
+    /**
+     * Label to represent the provider.
+     * This could be used for user interfaces to display the source of search results.
+     */
     label?: string;
 }
 
@@ -38,31 +90,54 @@ export declare class Geocoder extends BaseGeocoder<GeocoderOptions> {
     result(item: SearchItem): CancelablePromise<any>;
 }
 
+/**
+ * Defines the options for creating a Geocoder instance.
+ */
 export declare interface GeocoderOptions {
+    /**
+     * An array of providers to be used for geocoding.
+     */
     providers: BaseProvider[];
 }
 
 export declare class NgwProvider extends BaseProvider<NgwProviderOptions> {
+    static limit: number;
     caseInsensitive: boolean;
-    searchUrl: string;
     searchResources: SearchResource[];
     private connector;
-    private requests;
+    private _abortControllers;
     constructor(options: NgwProviderOptions);
     abort(): void;
-    search(like: string): AsyncGenerator<NgwSearchItem, void, unknown>;
+    search(query: string): AsyncGenerator<NgwSearchItem, void, unknown>;
     result(item: NgwSearchItem): CancelablePromise<ResultItem>;
-    _items(entries: ResourceStoreItem[]): NgwSearchItem[];
+    private _makeSignal;
+    private _items;
 }
 
+/**
+ * Options required to initialize an NGW provider.
+ */
 declare interface NgwProviderOptions extends BaseProviderOptions {
+    /** Connector instance for NGW. If not provided, will be created internally */
     connector?: NgwConnector;
+    /** List of NGW resources to search within */
     searchResources: SearchResource[];
+    /** Options for the internal NgwConnector (if one needs to be created) */
+    connectorOptions?: NgwConnectorOptions;
 }
 
+/**
+ * Extends the basic search item with NGW-specific properties.
+ */
 declare interface NgwSearchItem extends SearchItem {
+    /** ID of the NGW resource */
     resourceId: number;
+    /** ID of the feature in the NGW resource */
     featureId: number;
+    /** The specific feature item from NGW */
+    item: FeatureItem;
+    /** The NGW resource item */
+    resourceItem: ResourceItem;
 }
 
 export declare class NominatimProvider extends BaseProvider {
@@ -74,26 +149,74 @@ export declare class NominatimProvider extends BaseProvider {
     result(model: SearchItem): CancelablePromise<ResultItem>;
 }
 
+/**
+ * Defines the structure for a rendered search item.
+ */
+declare interface RenderSearchItem {
+    /** The specific feature item */
+    item: FeatureItem;
+    /** The NGW resource item */
+    resourceItem: ResourceItem;
+}
+
 export declare interface ResultItem {
+    /**
+     * Display text of the result item.
+     */
     text: string;
+    /**
+     * Bounding box of the result item in [west, south, east, north] format.
+     */
     extent: LngLatBoundsArray;
+    /**
+     * Optional GeoJSON geometry associated with this result item.
+     */
     geom?: GeoJsonObject;
 }
 
 export declare interface SearchItem {
+    /**
+     * A dynamic property bucket for the `SearchItem`.
+     */
     [prop: string]: any;
+    /**
+     * An optional unique identifier for the search result.
+     */
     _id?: number | string;
+    /**
+     * Display text of the search result.
+     */
     text: string;
+    /**
+     * The original query string that resulted in this search result.
+     */
     query: string;
+    /**
+     * An optional bounding box of the search result in [west, south, east, north] format.
+     */
     extent?: LngLatBoundsArray;
+    /**
+     * The provider that sourced this search result.
+     */
     provider?: BaseProvider;
+    /**
+     * Optional GeoJSON geometry associated with this search result.
+     */
     geom?: GeoJsonObject;
+    /**
+     * An optional function that can be called to retrieve detailed result for this search item.
+     */
     result?: () => CancelablePromise<ResultItem>;
 }
 
-declare interface SearchResource {
-    id: number;
-    limit?: number;
+/**
+ * Options for searching within a NGW resource.
+ */
+declare interface SearchResource extends FetchNgwItemsOptions {
+    /** The search method used ('ilike' is case-insensitive) */
+    searchMethod?: 'ilike' | 'like';
+    /** Custom rendering function for search results */
+    renderSearch?: (item: RenderSearchItem) => string | HTMLElement;
 }
 
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextgis/geocoder",
-  "version": "1.16.8",
+  "version": "1.18.3",
   "description": "",
   "main": "index.js",
   "module": "lib/geocoder.esm-bundler.js",
@@ -8,15 +8,16 @@
   "jsdelivr": "lib/geocoder.global.prod.js",
   "types": "lib/index.d.ts",
   "dependencies": {
-    "@nextgis/cancelable-promise": "^1.16.8",
-    "@nextgis/ngw-connector": "^1.16.8",
-    "@nextgis/utils": "^1.16.8",
+    "@nextgis/cancelable-promise": "^1.18.3",
+    "@nextgis/ngw-connector": "^1.18.3",
+    "@nextgis/ngw-kit": "^1.18.3",
+    "@nextgis/utils": "^1.17.0",
     "@types/events": "^3.0.0",
     "@types/geojson": "^7946.0.8",
     "events": "^3.3.0"
   },
   "devDependencies": {
-    "@nextgis/build-tools": "^1.16.8"
+    "@nextgis/build-tools": "^1.17.0"
   },
   "buildOptions": {
     "name": "Geocoder",
@@ -52,5 +53,5 @@
   "bugs": {
     "url": "https://github.com/nextgis/nextgis_frontend/issues"
   },
-  "gitHead": "e156aa6d884f1987e3f84649284d5f0c70d713a5"
+  "gitHead": "2e9e5b8f6125faab208899bb4581392721af04cd"
 }