@nextgis/ngw-connector 4.0.0-alpha.2 → 4.0.0-alpha.6

package/README.md

@@ -4,6 +4,15 @@
 
 A lightweight HTTP client optimized for use with [NextGIS Web](http://docs.nextgis.com/docs_ngweb_dev/doc/developer/toc.html) API.
 
+> [!IMPORTANT]
+> The typed `NgwConnector.route()` API requires declarations generated for your NextGIS Web deployment. Install `@nextgis/ngw-types-loader` and run it before using `route()`. The declarations depend on the components and extensions installed on that server.
+>
+> ```bash
+> npx @nextgis/ngw-types-loader https://your-ngw-server.com
+> ```
+>
+> See the [NGW Types Loader documentation](https://github.com/nextgis/nextgis_frontend/tree/master/packages/ngw-types-loader#readme) for detailed instructions.
+
 Make sure CORS is registered in the [NextGIS Web settings](https://docs.nextgis.com/docs_ngcom/source/CORS.html) to be able to send requests.
 
 ## Installation
@@ -48,34 +57,26 @@ npm install @nextgis/ngw-connector
 
 ## TypeScript Support
 
-If you plan to use this library in a TypeScript project, it's recommended to install TypeScript declaration files for NextGIS Web by using the `@nextgis/ngw-types-loader` tool.
-
-### Installing NGW Types
-
-Run the following command to download the latest TypeScript declaration files:
+`NgwConnector.route()` uses declarations generated by NextGIS Web itself. Install the loader as a development dependency:
 
 ```bash
-npx @nextgis/ngw-types-loader
+npm install --save-dev @nextgis/ngw-types-loader
 ```
 
-This will download the declaration file from the default NextGIS Web instance (`https://demo.nextgis.com`) and update your `tsconfig.json` to include it.
-
-If you are using a custom NextGIS Web deployment, you can specify the URL:
+Then generate types from the NextGIS Web deployment your application connects to:
 
 ```bash
-npx @nextgis/ngw-types-loader https://your-custom-ngw-url.com
+npx @nextgis/ngw-types-loader https://your-ngw-server.com
 ```
 
-After running the tool, ensure that your `tsconfig.json` includes the downloaded file:
+If the URL is omitted, the loader uses `https://demo.nextgis.com`:
 
-```json
-{
-  "include": [
-    "./nextgisweb.d.ts"
-  ]
-}
+```bash
+npx @nextgis/ngw-types-loader
 ```
 
+The declarations are installed as resolvable packages under `node_modules/@nextgisweb`; no `tsconfig.json` changes are required. Run the loader again after changing the NextGIS Web version, components, or extensions.
+
 For more details, refer to the [NGW Types Loader](https://www.npmjs.com/package/@nextgis/ngw-types-loader).
 
 ## Usage

package/lib/index.d.ts

@@ -1,120 +1,12 @@
-import { Routes } from '@nextgisweb/pyramid/type/route';
-import { CompositeRead, ResourceRead } from '@nextgisweb/resource/type/api';
 import Cache from '@nextgis/cache';
 import { EventEmitter } from 'events';
 import { FeatureProperties, DeepPartial } from '@nextgis/utils';
 import { LegendSymbol } from '@nextgisweb/render/type/api';
-import { GeoJsonObject, Geometry } from 'geojson';
+import { CompositeRead, SearchResponse, ResourceRead } from '@nextgisweb/resource/type/api';
+import { Geometry, GeoJsonObject } from 'geojson';
+import { Routes } from '@nextgisweb/pyramid/type/route';
 import { LegendSymbolsEnum } from '@nextgisweb/webmap/type/api';
 
-declare class LunkwillParam {
-    static VALUES: (string | null)[];
-    private value;
-    constructor();
-    update(value: string | null, cond?: boolean): void;
-    suggest(cond?: boolean): void;
-    require(cond?: boolean): void;
-    toHeaders(headers: Record<string, string>): void;
-}
-
-type RouteParameters = {
-    [K in keyof Routes]: Routes[K]['pathArr'] | [Routes[K]['pathObj']];
-};
-type RouteName = keyof Routes;
-type GetRouteParam<R extends RouteName> = (RouteParameters[R] & [
-    object
-])[0];
-type RequestMethod = keyof RouteMethods<RouteName>;
-type Method = RequestMethod | Uppercase<RequestMethod>;
-type CompositeFor<K extends keyof CompositeRead> = CompositeRead & Required<Pick<CompositeRead, K>>;
-type ResponseType = 'blob' | 'json';
-interface RouteRequestOptions<RT extends ResponseType = 'json', ReturnUrl extends boolean = false, Q = any, B = string | null | boolean | Record<string, any> | any[]> extends Omit<RequestInit, 'cache'> {
-    headers?: Record<string, string>;
-    cache?: boolean;
-    query?: Q;
-    json?: B;
-    /** Has lower priority than the json */
-    body?: string;
-    /**
-     * The type of data that the server will respond with.
-     * Can be either 'json' or 'blob'.
-     */
-    responseType?: RT;
-    /**
-     * @deprecated use {@link RequestInit.credential}
-     * Indicates whether to include credentials such as cookies, authentication headers,
-     * or TLS client certificates in cross-site Access-Control requests.
-     */
-    withCredentials?: boolean;
-    /**
-     * Name to use for caching the request.
-     */
-    cacheName?: string;
-    /**
-     * Properties to override default cache behavior.
-     */
-    cacheProps?: Record<string, unknown>;
-    lunkwill?: LunkwillParam;
-    lunkwillReturnUrl?: ReturnUrl;
-}
-interface GetRequestOptions<Q = any, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> extends Omit<RouteRequestOptions<RT, ReturnUrl, Q>, 'json' | 'body'> {
-    method?: 'GET';
-}
-interface RequestOptionsJSON<Q = any, B = string | null | boolean | Record<string, any> | any[], RT extends ResponseType = 'json', M extends Method = Method> extends Omit<RouteRequestOptions<RT, false, Q, B>, 'json' | 'body'> {
-    json: B;
-    method?: M;
-}
-interface RequestOptionsBody<Q = any, RT extends ResponseType = 'json', M extends Method = Method> extends Omit<RouteRequestOptions<RT, false, Q>, 'json' | 'body'> {
-    body: string;
-    method?: M;
-}
-type PutRequestOptions<Q = any, B = any, RT extends ResponseType = 'json'> = RequestOptionsJSON<Q, B, RT, 'PUT'> | RequestOptionsBody<Q, RT, 'PUT'>;
-type PostRequestOptions<Q = any, B = any, RT extends ResponseType = 'json'> = RequestOptionsJSON<Q, B, RT, 'POST'> | RequestOptionsBody<Q, RT, 'POST'>;
-type PatchRequestOptions<Q = any, B = any, RT extends ResponseType = 'json'> = RequestOptionsJSON<Q, B, RT, 'PATCH'> | RequestOptionsBody<Q, RT, 'PATCH'>;
-type DeleteRequestOptions<Q = any, RT extends ResponseType = 'json'> = RouteRequestOptions<RT, false, Q>;
-interface MethodRequestOptions<Q = any, B = any, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> {
-    get: GetRequestOptions<Q, RT, ReturnUrl>;
-    post: PostRequestOptions<Q, B, RT>;
-    put: PutRequestOptions<Q, B, RT>;
-    patch: PatchRequestOptions<Q, RT>;
-    delete: DeleteRequestOptions<Q, RT>;
-}
-type RequestOptionsByMethod<M extends RequestMethod, Q = any, B = any, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> = M extends keyof MethodRequestOptions ? MethodRequestOptions<Q, B, RT, ReturnUrl>[M] : never;
-type ApiRouteParams = Record<string, string>;
-interface LunkwillData {
-    status?: string;
-    delay_ms?: number;
-}
-type RouteResp<N extends RouteName, M extends RequestMethod> = N extends keyof Routes ? M extends keyof Routes[N] ? 'response' extends keyof Routes[N][M] ? Routes[N][M]['response'] : never : never : never;
-type RouteQuery<N extends RouteName, M extends RequestMethod> = N extends keyof Routes ? M extends keyof Routes[N] ? 'query' extends keyof Routes[N][M] ? Routes[N][M]['query'] : any : never : never;
-type RouteBody<N extends RouteName, M extends RequestMethod> = N extends keyof Routes ? M extends keyof Routes[N] ? 'body' extends keyof Routes[N][M] ? Routes[N][M]['body'] : any : never : never;
-type ToReturn<T = unknown, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> = ReturnUrl extends true ? string : RT extends 'blob' ? Blob : T;
-type HasRequiredKeys<T> = {
-    [P in keyof T]-?: object extends Pick<T, P> ? never : P;
-}[keyof T] extends never ? false : true;
-interface RouteMethods<N extends RouteName> {
-    url: HasRequiredKeys<RouteQuery<N, 'get'>> extends true ? (options: Pick<RequestOptionsByMethod<'get', RouteQuery<N, 'get'>>, 'query'>) => Promise<string> : (options?: Pick<RequestOptionsByMethod<'get', RouteQuery<N, 'get'>>, 'query'>) => Promise<string>;
-    get: HasRequiredKeys<RouteQuery<N, 'get'>> extends true ? <T = RouteResp<N, 'get'>, RT extends ResponseType = 'json', B extends boolean = false>(options: RequestOptionsByMethod<'get', RouteQuery<N, 'get'>, any, RT, B>) => Promise<ToReturn<T, RT, B>> : <T = RouteResp<N, 'get'>, B extends boolean = false, RT extends ResponseType = 'json'>(options?: RequestOptionsByMethod<'get', RouteQuery<N, 'get'>, any, RT, B>) => Promise<ToReturn<T, RT, B>>;
-    post: <T = RouteResp<N, 'post'>, RT extends ResponseType = 'json'>(options: RequestOptionsByMethod<'post', RouteQuery<N, 'post'>, RouteBody<N, 'post'>, RT>) => Promise<ToReturn<T, RT>>;
-    put: <T = RouteResp<N, 'put'>, RT extends ResponseType = 'json'>(options: RequestOptionsByMethod<'put', RouteQuery<N, 'put'>, RouteBody<N, 'put'>, RT>) => Promise<ToReturn<T, RT>>;
-    patch: <T = RouteResp<N, 'patch'>, RT extends ResponseType = 'json'>(options: RequestOptionsByMethod<'patch', RouteQuery<N, 'patch'>, RouteBody<N, 'patch'>, RT>) => Promise<ToReturn<T, RT>>;
-    delete: HasRequiredKeys<RouteQuery<N, 'delete'>> extends true ? <T = RouteResp<N, 'delete'>>(options: RequestOptionsByMethod<'delete', RouteQuery<N, 'delete'>>) => Promise<ToReturn<T>> : <T = RouteResp<N, 'delete'>>(options?: RequestOptionsByMethod<'delete', RouteQuery<N, 'delete'>>) => Promise<ToReturn<T>>;
-}
-type MethodAvailable<N extends RouteName, M extends RequestMethod> = M extends 'url' ? RouteMethods<N>['url'] : M extends keyof Routes[N] ? RouteMethods<N>[M] : never;
-type RouteResults<N extends RouteName> = {
-    [M in keyof RouteMethods<any>]: MethodAvailable<N, M>;
-};
-type KeysWithMethods<Methods extends RequestMethod[]> = {
-    [K in keyof Routes]: Methods extends (keyof Routes[K])[] ? K : never;
-}[keyof Routes];
-type PathKeys = any;
-type KeysWithPaths<P extends PathKeys> = {
-    [K in keyof Routes]: P extends Array<keyof Routes[K]['pathObj']> ? K : never;
-}[keyof Routes];
-type KeysWithMethodAndPath<M extends RequestMethod[], P extends PathKeys> = {
-    [K in keyof Routes]: K extends KeysWithMethods<M> ? K extends KeysWithPaths<P> ? K : never : never;
-}[keyof Routes];
-
 declare class AbortError extends Error {
     constructor(message?: string);
 }
@@ -665,7 +557,7 @@ interface BasemapWebmap {
 interface LookupTableResource {
     items: Record<string, string>;
 }
-type VectorFieldDatatype = 'STRING' | 'REAL' | 'DATE' | 'TIME' | 'DATETIME' | 'BIGINT' | 'INTEGER' | 'BOOLEAN';
+type VectorFieldDatatype = 'STRING' | 'REAL' | 'DATE' | 'TIME' | 'DATETIME' | 'BIGINT' | 'INTEGER' | 'BOOLEAN' | 'JSON';
 /** @deprecated - use {@link VectorFieldDatatype} instead */
 type ResourceItemDatatype = VectorFieldDatatype;
 interface FeatureLayerField {
@@ -681,7 +573,7 @@ interface FeatureLayerField {
 interface FeatureResource {
     fields: FeatureLayerField[];
 }
-type GeometryType = 'POINT' | 'LINESTRING' | 'POLYGON' | 'MULTIPOINT' | 'MULTILINESTRING' | 'MULTIPOLYGON' | 'POINTZ' | 'LINESTRINGZ' | 'POLYGONZ' | 'MULTIPOINTZ' | 'MULTILINESTRINGZ' | 'MULTIPOLYGONZ';
+type GeometryType = 'POINT' | 'LINESTRING' | 'POLYGON' | 'MULTIPOINT' | 'MULTILINESTRING' | 'MULTIPOLYGON' | 'POINTZ' | 'LINESTRINGZ' | 'POLYGONZ' | 'MULTIPOINTZ' | 'MULTILINESTRINGZ' | 'MULTIPOLYGONZ' | 'NONE';
 /** @deprecated use  VectorLayerRead from '@nextgisweb/resource/type/api' instead */
 interface VectorLayer {
     srs: {
@@ -857,7 +749,7 @@ interface GetRequestItemsResponseMap extends RequestItemKeys {
     'pyramid.route': PyramidRoute;
     'pyramid.settings': PyramidSettings;
     'resource.item': CompositeRead;
-    'resource.search': CompositeRead[];
+    'resource.search': CompositeRead[] | SearchResponse;
     'resource.child': any;
     'resource.collection': CompositeRead[];
     'file_upload.upload': FileUploadResp;
@@ -1131,6 +1023,114 @@ declare namespace errors {
   };
 }
 
+declare class LunkwillParam {
+    static VALUES: (string | null)[];
+    private value;
+    constructor();
+    update(value: string | null, cond?: boolean): void;
+    suggest(cond?: boolean): void;
+    require(cond?: boolean): void;
+    toHeaders(headers: Record<string, string>): void;
+}
+
+type RouteParameters = {
+    [K in keyof Routes]: Routes[K]['pathArr'] | [Routes[K]['pathObj']];
+};
+type RouteName = keyof Routes;
+type GetRouteParam<R extends RouteName> = (RouteParameters[R] & [
+    object
+])[0];
+type RequestMethod = keyof RouteMethods<RouteName>;
+type Method = RequestMethod | Uppercase<RequestMethod>;
+type CompositeFor<K extends keyof CompositeRead> = CompositeRead & Required<Pick<CompositeRead, K>>;
+type ResponseType = 'blob' | 'json';
+interface RouteRequestOptions<RT extends ResponseType = 'json', ReturnUrl extends boolean = false, Q = any, B = string | null | boolean | Record<string, any> | any[]> extends Omit<RequestInit, 'cache'> {
+    headers?: Record<string, string>;
+    cache?: boolean;
+    query?: Q;
+    json?: B;
+    /** Has lower priority than the json */
+    body?: string;
+    /**
+     * The type of data that the server will respond with.
+     * Can be either 'json' or 'blob'.
+     */
+    responseType?: RT;
+    /**
+     * @deprecated use {@link RequestInit.credential}
+     * Indicates whether to include credentials such as cookies, authentication headers,
+     * or TLS client certificates in cross-site Access-Control requests.
+     */
+    withCredentials?: boolean;
+    /**
+     * Name to use for caching the request.
+     */
+    cacheName?: string;
+    /**
+     * Properties to override default cache behavior.
+     */
+    cacheProps?: Record<string, unknown>;
+    lunkwill?: LunkwillParam;
+    lunkwillReturnUrl?: ReturnUrl;
+}
+interface GetRequestOptions<Q = any, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> extends Omit<RouteRequestOptions<RT, ReturnUrl, Q>, 'json' | 'body'> {
+    method?: 'GET';
+}
+interface RequestOptionsJSON<Q = any, B = string | null | boolean | Record<string, any> | any[], RT extends ResponseType = 'json', M extends Method = Method> extends Omit<RouteRequestOptions<RT, false, Q, B>, 'json' | 'body'> {
+    json: B;
+    method?: M;
+}
+interface RequestOptionsBody<Q = any, RT extends ResponseType = 'json', M extends Method = Method> extends Omit<RouteRequestOptions<RT, false, Q>, 'json' | 'body'> {
+    body: string;
+    method?: M;
+}
+type PutRequestOptions<Q = any, B = any, RT extends ResponseType = 'json'> = RequestOptionsJSON<Q, B, RT, 'PUT'> | RequestOptionsBody<Q, RT, 'PUT'>;
+type PostRequestOptions<Q = any, B = any, RT extends ResponseType = 'json'> = RequestOptionsJSON<Q, B, RT, 'POST'> | RequestOptionsBody<Q, RT, 'POST'>;
+type PatchRequestOptions<Q = any, B = any, RT extends ResponseType = 'json'> = RequestOptionsJSON<Q, B, RT, 'PATCH'> | RequestOptionsBody<Q, RT, 'PATCH'>;
+type DeleteRequestOptions<Q = any, RT extends ResponseType = 'json'> = RouteRequestOptions<RT, false, Q>;
+interface MethodRequestOptions<Q = any, B = any, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> {
+    get: GetRequestOptions<Q, RT, ReturnUrl>;
+    post: PostRequestOptions<Q, B, RT>;
+    put: PutRequestOptions<Q, B, RT>;
+    patch: PatchRequestOptions<Q, RT>;
+    delete: DeleteRequestOptions<Q, RT>;
+}
+type RequestOptionsByMethod<M extends RequestMethod, Q = any, B = any, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> = M extends keyof MethodRequestOptions ? MethodRequestOptions<Q, B, RT, ReturnUrl>[M] : never;
+type ApiRouteParams = Record<string, string>;
+interface LunkwillData {
+    status?: string;
+    delay_ms?: number;
+}
+type RouteResp<N extends RouteName, M extends RequestMethod> = N extends keyof Routes ? M extends keyof Routes[N] ? 'response' extends keyof Routes[N][M] ? Routes[N][M]['response'] : never : never : never;
+type RouteQuery<N extends RouteName, M extends RequestMethod> = N extends keyof Routes ? M extends keyof Routes[N] ? 'query' extends keyof Routes[N][M] ? Routes[N][M]['query'] : any : never : never;
+type RouteBody<N extends RouteName, M extends RequestMethod> = N extends keyof Routes ? M extends keyof Routes[N] ? 'body' extends keyof Routes[N][M] ? Routes[N][M]['body'] : any : never : never;
+type ToReturn<T = unknown, RT extends ResponseType = 'json', ReturnUrl extends boolean = false> = ReturnUrl extends true ? string : RT extends 'blob' ? Blob : T;
+type HasRequiredKeys<T> = {
+    [P in keyof T]-?: object extends Pick<T, P> ? never : P;
+}[keyof T] extends never ? false : true;
+interface RouteMethods<N extends RouteName> {
+    url: HasRequiredKeys<RouteQuery<N, 'get'>> extends true ? (options: Pick<RequestOptionsByMethod<'get', RouteQuery<N, 'get'>>, 'query'>) => Promise<string> : (options?: Pick<RequestOptionsByMethod<'get', RouteQuery<N, 'get'>>, 'query'>) => Promise<string>;
+    get: HasRequiredKeys<RouteQuery<N, 'get'>> extends true ? <T = RouteResp<N, 'get'>, RT extends ResponseType = 'json', B extends boolean = false>(options: RequestOptionsByMethod<'get', RouteQuery<N, 'get'>, any, RT, B>) => Promise<ToReturn<T, RT, B>> : <T = RouteResp<N, 'get'>, B extends boolean = false, RT extends ResponseType = 'json'>(options?: RequestOptionsByMethod<'get', RouteQuery<N, 'get'>, any, RT, B>) => Promise<ToReturn<T, RT, B>>;
+    post: <T = RouteResp<N, 'post'>, RT extends ResponseType = 'json'>(options: RequestOptionsByMethod<'post', RouteQuery<N, 'post'>, RouteBody<N, 'post'>, RT>) => Promise<ToReturn<T, RT>>;
+    put: <T = RouteResp<N, 'put'>, RT extends ResponseType = 'json'>(options: RequestOptionsByMethod<'put', RouteQuery<N, 'put'>, RouteBody<N, 'put'>, RT>) => Promise<ToReturn<T, RT>>;
+    patch: <T = RouteResp<N, 'patch'>, RT extends ResponseType = 'json'>(options: RequestOptionsByMethod<'patch', RouteQuery<N, 'patch'>, RouteBody<N, 'patch'>, RT>) => Promise<ToReturn<T, RT>>;
+    delete: HasRequiredKeys<RouteQuery<N, 'delete'>> extends true ? <T = RouteResp<N, 'delete'>>(options: RequestOptionsByMethod<'delete', RouteQuery<N, 'delete'>>) => Promise<ToReturn<T>> : <T = RouteResp<N, 'delete'>>(options?: RequestOptionsByMethod<'delete', RouteQuery<N, 'delete'>>) => Promise<ToReturn<T>>;
+}
+type MethodAvailable<N extends RouteName, M extends RequestMethod> = M extends 'url' ? RouteMethods<N>['url'] : M extends keyof Routes[N] ? RouteMethods<N>[M] : never;
+type RouteResults<N extends RouteName> = {
+    [M in keyof RouteMethods<any>]: MethodAvailable<N, M>;
+};
+type KeysWithMethods<Methods extends RequestMethod[]> = {
+    [K in keyof Routes]: Methods extends (keyof Routes[K])[] ? K : never;
+}[keyof Routes];
+type PathKeys = any;
+type KeysWithPaths<P extends PathKeys> = {
+    [K in keyof Routes]: P extends Array<keyof Routes[K]['pathObj']> ? K : never;
+}[keyof Routes];
+type KeysWithMethodAndPath<M extends RequestMethod[], P extends PathKeys> = {
+    [K in keyof Routes]: K extends KeysWithMethods<M> ? K extends KeysWithPaths<P> ? K : never : never;
+}[keyof Routes];
+
 declare class NgwConnector {
     options: NgwConnectorOptions;
     static errors: typeof errors;

package/lib/ngw-connector.cjs.js

@@ -1,4 +1,4 @@
-/** Bundle of @nextgis/ngw-connector; version: 4.0.0-alpha.2; author: NextGIS */
+/** Bundle of @nextgis/ngw-connector; version: 4.0.0-alpha.6; author: NextGIS */
 'use strict';
 
 var utils = require('@nextgis/utils');
@@ -69,7 +69,7 @@ async function apiRequest(opt) {
 }
 
 var pkg = {
-	version: "4.0.0-alpha.2"};
+	version: "4.0.0-alpha.6"};
 
 class AbortError extends Error {
   constructor(message = "AbortError") {
@@ -692,7 +692,7 @@ let ID = 0;
 let REQUEST_ID = 0;
 class NgwConnector {
   constructor(options) {
-    this.options = options;
+    __publicField$2(this, "options", options);
     __publicField$2(this, "id", ID++);
     __publicField$2(this, "emitter", new events.EventEmitter());
     __publicField$2(this, "user");
@@ -1116,14 +1116,15 @@ class ResourcesControl {
             ...query
           }
         }).then((resources) => {
-          if ((requestOptions == null ? void 0 : requestOptions.cache) && resources) {
-            for (const x of resources) {
+          const items2 = Array.isArray(resources) ? resources : resources.items;
+          if (requestOptions == null ? void 0 : requestOptions.cache) {
+            for (const x of items2) {
               this.cache.add("resource.item", Promise.resolve(x), {
                 id: x.resource.id
               });
             }
           }
-          return resources;
+          return items2;
         });
       }
       return items;