Introduce rawRequest() to replace rawResponse

.changeset/polite-dragons-tap.md

@@ -0,0 +1,89 @@
+---
+"@esri/arcgis-rest-developer-credentials": major
+"@esri/arcgis-rest-basemap-sessions": major
+"@esri/arcgis-rest-feature-service": major
+"@esri/arcgis-rest-demographics": major
+"@esri/arcgis-rest-elevation": major
+"@esri/arcgis-rest-geocoding": major
+"@esri/arcgis-rest-request": major
+"@esri/arcgis-rest-routing": major
+"@esri/arcgis-rest-places": major
+"@esri/arcgis-rest-portal": major
+"@esri/arcgis-rest-auth": major
+---
+
+This release changes how HTTP responses are accessed and redefines top-level request options.
+
+## Summary
+
+This release introduces rawRequest() for direct HTTP response access and removes legacy request option patterns.
+
+- `request()` returns JSON only. Non-JSON `f` values are coerced to `json` with a warning.
+- `rawResponse` is no longer supported. Use `rawRequest()` instead.
+- `maxUrlLength` is no longer supported. Use requestFlags.ignoreMaxUrlLength with GET requests to avoid REST JS coercing the request to POST for large URLs.
+
+## Breaking changes
+
+- `request()` now only supports JSON payload handling by coercing `f=json`.
+
+  - If you pass `params.f` values like `text` or `html` to `request()`, the value is coerced to `json` and a warning is emitted.
+  - Use `rawRequest()` when you need custom response formats or direct access to the native Response.
+
+- `rawResponse` as an `IRequestOptions` property is no longer supported for `request()`.
+
+  - Previous pattern: `request(url, { rawResponse: true, ... })`
+  - New pattern: `rawRequest(url, options)`
+
+- `maxUrlLength` as an `IRequestOptions` property is no longer supported.
+  - Previous pattern: { maxUrlLength: 3000 }
+  - New pattern: { requestFlags: { ignoreMaxUrlLength: true } }
+
+## Why these changes were made
+
+- Improve options handling and remove legacy properties.
+- Make generic return types feasible.
+- Contain HTTP-related fetch options and ArcGIS request flags within their own respective objects for a clearer API surface.
+
+## Migration guide
+
+1. Replace request(..., { rawResponse: true, ...options }) with rawRequest(..., options).
+
+```ts
+// Before
+const response = await request(url, {
+  rawResponse: true,
+  params: { f: "pbf" }
+});
+const bytes = await response.arrayBuffer();
+
+// After
+const response = await rawRequest(url, { params: { f: "pbf" } });
+const bytes = await response.arrayBuffer();
+```
+
+2. If you need text/html/blob/pbf from an endpoint, switch from request() to rawRequest().
+
+```ts
+// Before
+const text = await request(url, { params: { f: "html" } });
+
+// After
+const response = await rawRequest(url, { params: { f: "html" } });
+const text = await response.text();
+```
+
+3. Move top-level maxUrlLength usage to requestFlags.ignoreMaxUrlLength.
+
+Before, you could specify a GET request, and it would return so long as the max URL length was < 2000 or < the user-specified `maxUrlLength`.
+Now, if the max URL length surpasses 2000, `request()` will change request method from GET to POST unless the user specifies `ignoreMaxUrlLength` true in `requestFlags.ignoreMaxUrlLength`.
+
+```ts
+// Before
+await request(url, { httpMethod: "GET", maxUrlLength: 5000 });
+
+// After
+await request(url, {
+  fetchOptions: { method: "GET" },
+  requestFlags: { ignoreMaxUrlLength: true }
+});
+```

package.json

@@ -65,7 +65,7 @@
     "@changesets/cli": "^2.29.8",
     "@eslint/compat": "^2.0.0",
     "@eslint/js": "^9.39.1",
-    "@playwright/test": "^1.56.1",
+    "@playwright/test": "^1.60.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.3.0",

packages/arcgis-rest-feature-service/src/createFeatureService.ts

@@ -172,16 +172,15 @@ export interface ICreateServiceResult {
  * });
  * ```
  *
- * @param requestOptions - Options for the request. NOTE: `rawResponse` is not supported by this operation.
+ * @param requestOptions - Options for the request.
  * @returns A Promise that resolves with service details once the service has been created
  */
 export function createFeatureService(
   requestOptions: ICreateServiceOptions
 ): Promise<ICreateServiceResult> {
   return determineOwner(requestOptions).then((owner) => {
     const options: ICreateServiceOptions = {
-      ...requestOptions,
-      rawResponse: false
+      ...requestOptions
     };
     const baseUrl = `${getPortalUrl(requestOptions)}/content/users/${owner}`;
     const folder =

packages/arcgis-rest-feature-service/src/query.ts

@@ -12,7 +12,8 @@ import {
   IExtent,
   ArcGISRequestError,
   ArcGISAuthError,
-  IRequestOptions
+  IRequestOptions,
+  rawRequest
 } from "@esri/arcgis-rest-request";
 
 import {
@@ -77,9 +78,7 @@ export interface IQueryFeaturesOptions extends ISharedQueryOptions {
   sqlFormat?: "none" | "standard" | "native";
   returnExceededLimitFeatures?: boolean;
   /**
-   * Response format. Defaults to "json"
-   * NOTE: for "pbf" you must also supply `rawResponse: true`
-   * and parse the response yourself using `response.arrayBuffer()`
+   * Response format. Defaults to "json".
    */
   f?: "json" | "geojson" | "pbf" | "pbf-as-geojson" | "pbf-as-arcgis";
   /**
@@ -134,7 +133,7 @@ export interface IQueryAllFeaturesOptions extends ISharedQueryOptions {
   returnExceededLimitFeatures?: true;
   /**
    * Response format. Defaults to "json"
-   * NOTE: for "pbf" you must also supply `rawResponse: true`
+   * NOTE: for "pbf" you must use the method `rawRequest()`
    * and parse the response yourself using `response.arrayBuffer()`
    */
   f?: "json" | "geojson" | "pbf-as-geojson" | "pbf-as-arcgis";
@@ -188,17 +187,16 @@ export function queryPbfAsGeoJSONOrArcGIS(
   // default pbf request to EPSG:4326 if requesting pbf-as-geojson to satisfy geojson crs standard
   const geoJSONSpatialReference =
     queryOptions.params.f === "pbf-as-geojson" ? { outSR: "4326" } : {};
-  // query with f=pbf and rawResponse:true on behalf of the user to fetch metadata with the pbf response
+  // query with f=pbf and rawRequest on behalf of the user to fetch metadata with the pbf response
   const customOptions = {
     ...queryOptions,
     params: {
       ...queryOptions.params,
       ...geoJSONSpatialReference,
       f: "pbf"
-    } as any,
-    rawResponse: true
+    } as any
   };
-  return request(`${cleanUrl(url)}/query`, customOptions).then(
+  return rawRequest(`${cleanUrl(url)}/query`, customOptions).then(
     async (response: any) => {
       // if pbf request to service returns a json format, there is an error
       if (response.headers.get("content-type")?.includes("application/json")) {
@@ -270,24 +268,22 @@ export function queryPbfAsGeoJSONOrArcGIS(
  * ```
  *
  * @param requestOptions - Options for the request
- * @returns A Promise that will resolve with the feature or the [response](https://developer.mozilla.org/en-US/docs/Web/API/Response) itself if `rawResponse: true` was passed in.
+ * @returns A Promise that resolves with the feature by default, or with the native Response when `rawResponse` is `true`.
  */
 export function getFeature(
   requestOptions: IGetFeatureOptions
-): Promise<IFeature> {
+): Promise<IFeature | Response> {
   const url = `${cleanUrl(requestOptions.url)}/${requestOptions.id}`;
 
   // default to a GET request
   const options: IGetFeatureOptions = {
     ...{ httpMethod: "GET" },
     ...requestOptions
   };
-  return request(url, options).then((response: any) => {
-    if (options.rawResponse) {
-      return response;
-    }
-    return response.feature;
-  });
+  if (options.rawResponse) {
+    return rawRequest(url, options);
+  }
+  return request(url, options).then((response: any) => response.feature);
 }
 
 /**
@@ -365,6 +361,11 @@ export function queryFeatures(
     queryOptions.params?.f === "pbf-as-arcgis"
   ) {
     return queryPbfAsGeoJSONOrArcGIS(requestOptions.url, queryOptions);
+  } else if (queryOptions.params?.f === "pbf") {
+    return rawRequest(
+      `${cleanUrl(requestOptions.url)}/query`,
+      queryOptions
+    ) as Promise<any>;
   }
   return request(`${cleanUrl(requestOptions.url)}/query`, queryOptions);
 }

packages/arcgis-rest-feature-service/test/addToServiceDefinition.test.ts

@@ -234,7 +234,9 @@ describe("add to feature service", () => {
           params: expect.objectContaining({
             addToDefinition: { layers: [layerDescriptionFail] }
           }),
-          httpMethod: "POST"
+          fetchOptions: expect.objectContaining({
+            method: "POST"
+          })
         })
       });
     });
@@ -258,7 +260,9 @@ describe("add to feature service", () => {
           params: expect.objectContaining({
             addToDefinition: { tables: [tableDescriptionFail] }
           }),
-          httpMethod: "POST"
+          fetchOptions: expect.objectContaining({
+            method: "POST"
+          })
         })
       });
     });
@@ -286,7 +290,9 @@ describe("add to feature service", () => {
               layers: [layerDescriptionFail]
             }
           }),
-          httpMethod: "POST"
+          fetchOptions: expect.objectContaining({
+            method: "POST"
+          })
         })
       });
     });

packages/arcgis-rest-feature-service/test/query.test.live.ts

@@ -447,8 +447,7 @@ describe("queryFeatures() and queryAllFeatures() live tests", () => {
           f: "pbf",
           where: "1=1",
           outFields: ["*"],
-          resultRecordCount: 1,
-          rawResponse: true
+          resultRecordCount: 1
         };
         const response = await queryFeatures(zipCodePointsPbfOptions);
         const arrBuffer = await (response as any).arrayBuffer();
@@ -489,8 +488,7 @@ describe("queryFeatures() and queryAllFeatures() live tests", () => {
           f: "pbf",
           where: "1=1",
           outFields: ["*"],
-          resultRecordCount: 1,
-          rawResponse: true
+          resultRecordCount: 1
         };
         const response = await queryFeatures(trailsLinesPbfOptions);
         const arrBuffer = await (response as any).arrayBuffer();
@@ -523,8 +521,7 @@ describe("queryFeatures() and queryAllFeatures() live tests", () => {
           f: "pbf",
           where: "1=1",
           outFields: ["*"],
-          resultRecordCount: 1,
-          rawResponse: true
+          resultRecordCount: 1
         };
         const response = await queryFeatures(parksPolygonsPbfOptions);
         const arrBuffer = await (response as any).arrayBuffer();

packages/arcgis-rest-feature-service/test/query.test.ts

@@ -1306,3 +1306,49 @@ describe("queryAllFeatures (custom pagination)", () => {
     }
   });
 });
+
+describe("queryFeatures(): pbf", () => {
+  afterEach(() => {
+    fetchMock.restore();
+  });
+
+  test("should return raw response for f=pbf without decoding", async () => {
+    const arrayBuffer = await readEnvironmentFileToArrayBuffer(
+      "./packages/arcgis-rest-feature-service/test/mocks/pbf/CRS4326/PBFPointResponseCRS4326.pbf"
+    );
+
+    fetchMock.once(
+      "*",
+      {
+        status: 200,
+        headers: { "content-type": "application/x-protobuf" },
+        body: arrayBuffer
+      },
+      { sendAsJson: false }
+    );
+
+    const requestOptions: IQueryFeaturesOptions = {
+      url: serviceUrl,
+      f: "pbf",
+      where: "1=1",
+      outFields: ["*"],
+      resultRecordCount: 1
+    };
+
+    const response: any = await queryFeatures(requestOptions);
+
+    expect(fetchMock.called()).toBeTruthy();
+    const [url, options] = fetchMock.lastCall("*");
+    expect(url).toBe(
+      `${serviceUrl}/query?f=pbf&where=1%3D1&outFields=*&resultRecordCount=1`
+    );
+    expect(options.method).toBe("GET");
+
+    // rawRequest path should return a Response-like object
+    expect(response.status).toBe(200);
+    expect(response.ok).toBe(true);
+
+    const rawBuffer = await response.arrayBuffer();
+    expect(rawBuffer.byteLength).toBeGreaterThan(0);
+  });
+});