Epic: ArcGIS REST JS v5

[patrickarlt]

This issue is for discussing what should be included in ArcGIS REST JS v5 which be our next major version and breaking change opportunity.

There are a few things that we have already discussed:

• Node and browser support bumps Version and browser support updates #1187
• TypeScript 5 Version and browser support updates #1187
• Switch to Vitest for testing Version and browser support updates #1187 this seems to be the path that most teams inside Esri are going.

Currently that would be it. However I want to throw out a few more ideas:

• Move most request and fetch options to separate requestOptions (option flags used in our internal request function) and fetchOptions (options passed to the internal call to fetch). The only things I would keep would at the top level would be authentication and params. This would mean our main options interface looks like this:

  {
    params: any; // any additional params to append to the request
    authentication: IAuthenticationManager | string; // auth manager or access token
    requestOptions: { // additional options for our intenal request method
      hideToken: boolean; // put the token param in the header for GET requests
      suppressWarnings: boolean // silence all internal console warnings from REST JS 
      portal: string; // used internall by some requests to construct URLs, will override the portal set in thi authentication option
    };
    /** 
     * anything you can pass to the options for fetch 
     * https://developer.mozilla.org/en-US/docs/Web/API/RequestInit 
     * REST JS may override or ignore these as it sees fit. REST JS
     * currently modifies the headers and credentials options.
     **/
    fetchOptions: RequestInit 
  
  }

  This would make it so that we can easily copy options around inside higher level methods where we make multiple internal calls to different endpoints like createApiKey()
• Remove rawResponse as per discussion in Update typings for functions that wrap request() to return Response when using rawResponse #821 this might mean that some user might be disappointed like in solveRoute throws error when used with rawResponse #1045 (comment) because you wouldn't be able to access response headers. Could we solve this by appending headers to the responses?
• Support only Node 22+. This means we can ditch all the complexity with node-fetch and the extra packages and finally assume that a standard fetch exists everywhere. Maintenance on 18 ends in April 2025 (this year) and maintenance on 20 ends April 2026 so this might be a controversial move.

[patrickarlt]

Here is a summary of some of recent discussions and thoughts on v5.

• Move most request and fetch options to separate requestOptions (option flags used in our internal request function) and fetchOptions (options passed to the internal call to fetch). The only things I would keep would at the top level would be authentication and params. This would mean our main options interface looks like this:

  {
    params: any; // any additional params to append to the request
    authentication: IAuthenticationManager | string; // auth manager or access token
    requestOptions: { // additional options for our intenal request method
      hideToken: boolean; // put the token param in the header for GET requests
      suppressWarnings: boolean // silence all internal console warnings from REST JS 
      portal: string; // used internally by some requests to construct URLs, will override the portal set in thi authentication option
    };
    /** 
     * anything you can pass to the options for fetch 
     * https://developer.mozilla.org/en-US/docs/Web/API/RequestInit 
     * REST JS may override or ignore these as it sees fit. REST JS
     * currently modifies the headers and credentials options.
     **/
    fetchOptions: RequestInit 
  
  }

  This would make it so that we can easily copy options around inside higher level methods where we make multiple internal calls to different endpoints like createApiKey()

  This should also be backward compatible with 4.x.x. Given the time it took to do this 3>4 transitions we need an on ramp so internal teams can update to 5 and then slowly remove all the deprecation messages and then we can remove the support code at v6.

• Remove rawResponse as per discussion in Update typings for functions that wrap request() to return Response when using rawResponse #821 this might mean that some user might be disappointed like in solveRoute throws error when used with rawResponse #1045 (comment) because you wouldn't be able to access response headers. We still need to discuss a way to expose request headers in all responses at v5. This might be easy for request() but not for complex methods that call multiple requests internally.

• Support only Node 22+. This means we can ditch all the complexity with node-fetch and the extra packages and finally assume that a standard fetch exists everywhere. Maintenance on 18 ends in April 2025 (this year) and maintenance on 20 ends April 2026 so this seems like a perfectly fine move.

• Bump our engines configuration to Node 24+.

• Bump all our tests to use lts/* in all our action matrixes.

• Bump our TypeScript compile target to 2020 which is pretty broadly supported https://caniuse.com/?search=es2020 and gives us globalThis and native chaining with ?.. We can also use structuredClone()

We have also discussed flat out removing or changing some things when we move to v5. These are mostly less frequently used features which shouldn't have too much impact:

• Remove withOptions()
• Remove pkce:false in ArcGISIdentityManager.beginOauth2(). This has a been true in v4 as the default and false provides no benefit.
• Remove the setDefaultRequestOptions() and getDefaultRequestOptions() functions in favor of reading from a globalThis.arcgisRestJsConfig object that we call Object.freeze() in when the first request is made.
• Remove the @esri/arcgis-rest-auth package this was deprecated in 3.0.0.
• Remove the @esri/arcgis-rest-fetch package because we will be native fetch
• Remove the @esri/arcgis-rest-form-data package because we will be native fetch
• Remove the rawResponse option options because it is generally too difficult to implement across all our methods. We should still allow rawResponse but only on request() not on any of our other methods. For methods where getting the Response object might be useful we should simply add new methods to handle those cases according too Update typings for functions that wrap request() to return Response when using rawResponse #821 and solveRoute throws error when used with rawResponse #1045 (comment)

Additionally I would like to make a few additional changes to the build and release process:

• Switch to changesets for managing our release process. This is widely used by lots of monorepo projects and would replace a huge number of our dependencies including @commitlint/*, @semantic-release/* and multi-semantic-release. We have started using internally for some of our projects with great success and I think it would be even more productive since we can leverage the changeset bot and action to automate everything.
• Switch from ultra-runner and npm-run-all to turbo. We also started using this recently for a new project and I really like it.

I think that both of these should improve our build and release process significantly and reduce our overall dependency count.