[uploadChangeset] add onProgress callback

Author: k-yle

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- [uploadChangeset] add an `onProgress` callback, so that apps can show a progress bar while uploading
 - [uploadChangeset] compress changesets with gzip before uploading (if JS's [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) is available natively)
 
 ## 3.2.0 (2025-07-27)

examples/uploadChangeset.md

@@ -115,3 +115,18 @@ await uploadChangeset(changesetTags, diff, {
   },
 });
 ```
+
+### onProgress
+
+`onProgress` is a callback function which is called whenever the upload progress changes.
+It is called with an object parameter:
+
+```js
+{
+    phase: "upload",
+    step: 20,
+    total: 35,
+}
+```
+
+`step` is a number from `0` to `total` which could be used to render a progress bar.

src/api/changesets/uploadChangeset.ts

@@ -17,6 +17,8 @@ export interface UploadChunkInfo {
   changesetTotal: number;
 }
 
+export type UploadPhase = "upload" | "merge_conflicts";
+
 /** @internal */
 export function compress(input: string) {
   // check if it's supported
@@ -37,6 +39,16 @@ export interface UploadOptions {
    */
   onChunk?(info: UploadChunkInfo): Tags;
 
+  /**
+   * Optional, if you want status updates during the upload process,
+   * this callback is invoked whenever the progress updates.
+   */
+  onProgress?(progress: {
+    phase: UploadPhase;
+    step: number;
+    total: number;
+  }): void;
+
   /** by default, uploads are compressed with gzip. set to `false` to disable */
   disableCompression?: boolean;
 }
@@ -52,6 +64,7 @@ export async function uploadChangeset(
 ): Promise<number> {
   const {
     onChunk,
+    onProgress,
     disableCompression,
     //
     ...fetchOptions
@@ -85,6 +98,8 @@ export async function uploadChangeset(
     // if the user didn't include a `created_by` tag, we'll add one.
     tagsForChunk["created_by"] ||= `osm-api-js ${version}`;
 
+    onProgress?.({ phase: "upload", step: index + 1, total: chunks.length });
+
     const csId = +(await osmFetch<string>("/0.6/changeset/create", undefined, {
       ...fetchOptions,
       method: "PUT",