v4: several breaking changes for changeset APIs to be consistent with...

...the OSM API's new json endpoints.

Author: k-yle

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 4.0.0 (----------)
+
+- 💥 BREAKING CHANGE: `uploadChangeset` now returns a object instead of a single changeset ID. This is because:
+  1. the function supports chunking uploads into multiple changesets if it exceeds the limit of 10,000 features per changeset.
+  2. For each feature that was created, the response now includes a mapping between the temporary ID used by the uploader, and the permanent ID allocated by the server.
+- 💥 BREAKING CHANGE: The type defintions for `Changeset` have been changed to mark several properties as optional. (see [#14](https://github.com/osmlab/osm-api-js/issues/14))
+- 💥 BREAKING CHANGE: `Changeset.created_at`, `Changeset.closed_at`, and `ChangesetComment.date` are now a `string`, not a `Date`. This makes it more consistent with the XML format, and easier to serialise to JSON.
+- 💥 BREAKING CHANGE: `ChangesetComment.uid` is now a `number`, not a `string`. This matches the behaviour of OSM's new json API.
+- 💥 BREAKING CHANGE: `Changeset.discussion` has been renamed to `Changeset.comments`. This matches the behaviour of OSM's new json API.
+
 ## 3.3.0 (2025-09-18)
 
 - [uploadChangeset] add an `onProgress` callback, so that apps can show a progress bar while uploading

examples/uploadChangeset.md

@@ -26,12 +26,17 @@ await uploadChangeset(
 
 Response:
 
-```json
-12345
+```jsonc
+{
+  // 12345 is the changeset number
+  "12345": {
+    // the contents of this object is the diff result.
+    // - for created features, this object allows you to map the temporary ID used by the uploader, to the permananet ID that the server allocated to this feature.
+    // - for updated & deleted features, it includes the new version number
+  },
+}
 ```
 
-(changeset number)
-
 ## Detailed Examples
 
 ### Updating existing features

src/api/_rawResponse.d.ts

@@ -1,24 +1,5 @@
 import type { Feature, FeatureCollection, Point } from "geojson";
-import type {
-  Changeset,
-  ChangesetComment,
-  OsmFeatureType,
-  OsmNote,
-} from "../types";
-
-/** @internal */
-export type RawChangeset = Omit<
-  Changeset,
-  "discussion" | "created_at" | "closed_at"
-> & {
-  created_at: string;
-  closed_at?: string;
-  comments?: (Omit<ChangesetComment, "date" | "uid"> & {
-    /** ISO Date */
-    date: string;
-    uid: number;
-  })[];
-};
+import type { OsmFeatureType, OsmNote } from "../types";
 
 /** @internal */
 export type RawNotesSearch = FeatureCollection<

src/api/changesets/__tests__/uploadChangeset.test.ts

@@ -236,7 +236,7 @@ describe("uploadChangeset", () => {
       { comment: "added a building" },
       { create: [], modify: [], delete: [] }
     );
-    expect(output).toBe(1);
+    expect(output).toStrictEqual({ 1: { diffResult: {} } });
 
     expect(osmFetch).toHaveBeenCalledTimes(3);
     expect(osmFetch).toHaveBeenNthCalledWith(
@@ -277,7 +277,56 @@ describe("uploadChangeset", () => {
       );
     }
 
-    expect(output).toBe(1);
+    expect(output).toStrictEqual({
+      // create nodes first.
+      1: {
+        diffResult: {
+          node: {
+            "-10": { newId: 2, newVersion: 1 },
+            "-11": { newId: 1, newVersion: 1 },
+            "-2": { newId: 5, newVersion: 1 },
+            "-7": { newId: 6, newVersion: 1 },
+            "-8": { newId: 4, newVersion: 1 },
+            "-9": { newId: 3, newVersion: 1 },
+          },
+        },
+      },
+      // create nodes then ways then relations next
+      2: {
+        diffResult: {
+          node: {
+            "-100": { newId: 10, newVersion: 1 },
+            "-4": { newId: 9, newVersion: 1 },
+            "-5": { newId: 8, newVersion: 1 },
+            "-6": { newId: 7, newVersion: 1 },
+          },
+          relation: { "-300000": { newId: 1, newVersion: 1 } },
+          way: { "-3": { newId: 1, newVersion: 1 } },
+        },
+      },
+      // modify and delete next (any order)
+      3: {
+        diffResult: {
+          node: {
+            1: { newId: 1, newVersion: 2 },
+            2: { newId: 2, newVersion: 3 },
+          },
+          relation: {
+            2: { newId: 2, newVersion: 22 },
+            3: { newId: 3, newVersion: 2 },
+            4: { newId: 4, newVersion: 2 },
+          },
+          way: { 2: { newId: 2, newVersion: 2 } },
+        },
+      },
+      // delete last
+      4: {
+        diffResult: {
+          relation: { 1: { newId: 1, newVersion: 11 } },
+          way: { 1: { newId: 1, newVersion: 3 } },
+        },
+      },
+    });
   });
 
   it("splits changesets into chunks and suports a custom tag function", async () => {
@@ -311,7 +360,9 @@ describe("uploadChangeset", () => {
       );
     }
 
-    expect(output).toBe(1);
+    // don't need to assert the output, since it's the same
+    // as the previous test case.
+    expect(Object.keys(output).map(Number)).toStrictEqual([1, 2, 3, 4]);
   });
 
   // end of tests

src/api/changesets/createChangesetComment.ts

@@ -1,15 +1,13 @@
 import type { Changeset } from "../../types";
 import { type FetchOptions, osmFetch } from "../_osmFetch";
-import type { RawChangeset } from "../_rawResponse";
-import { mapRawChangeset } from "./getChangesets";
 
 /** Add a comment to a changeset. The changeset must be closed. */
 export async function createChangesetComment(
   changesetId: number,
   commentText: string,
   options?: FetchOptions
 ): Promise<Changeset> {
-  const result = await osmFetch<{ changeset: RawChangeset }>(
+  const result = await osmFetch<{ changeset: Changeset }>(
     `/0.6/changeset/${changesetId}/comment.json`,
     undefined,
     {
@@ -22,5 +20,5 @@ export async function createChangesetComment(
       },
     }
   );
-  return mapRawChangeset(result.changeset);
+  return result.changeset;
 }

src/api/changesets/getChangesets.ts

@@ -1,22 +1,5 @@
 import type { BBox, Changeset } from "../../types";
 import { type FetchOptions, osmFetch } from "../_osmFetch";
-import type { RawChangeset } from "../_rawResponse";
-
-/** @internal */
-export const mapRawChangeset = ({
-  comments,
-  ...raw
-}: RawChangeset): Changeset => ({
-  ...raw,
-  created_at: new Date(raw.created_at),
-  closed_at: raw.closed_at ? new Date(raw.closed_at) : undefined!,
-
-  discussion: comments?.map((comment) => ({
-    ...comment,
-    date: new Date(comment.date),
-    uid: `${comment.uid}`,
-  })),
-});
 
 // does not extend BasicFilters for historical reasons
 export type ListChangesetOptions = {
@@ -57,7 +40,7 @@ export async function listChangesets(
 ): Promise<Changeset[]> {
   const { only, ...otherQueries } = query;
 
-  const raw = await osmFetch<{ changesets: RawChangeset[] }>(
+  const raw = await osmFetch<{ changesets: Changeset[] }>(
     "/0.6/changesets.json",
     {
       ...(only && { [only]: true }),
@@ -66,7 +49,7 @@ export async function listChangesets(
     options
   );
 
-  return raw.changesets.map(mapRawChangeset);
+  return raw.changesets;
 }
 
 /** get a single changeset */
@@ -76,11 +59,11 @@ export async function getChangeset(
   includeDiscussion = true,
   options?: FetchOptions
 ): Promise<Changeset> {
-  const raw = await osmFetch<{ changeset: RawChangeset }>(
+  const raw = await osmFetch<{ changeset: Changeset }>(
     `/0.6/changeset/${id}.json`,
     includeDiscussion ? { include_discussion: 1 } : {},
     options
   );
 
-  return mapRawChangeset(raw.changeset);
+  return raw.changeset;
 }

src/api/changesets/uploadChangeset.ts

@@ -1,6 +1,7 @@
-import type { OsmChange, Tags } from "../../types";
+import type { OsmChange, OsmFeatureType, Tags } from "../../types";
 import { type FetchOptions, osmFetch } from "../_osmFetch";
 import { version } from "../../../package.json";
+import type { RawUploadResponse } from "../_rawResponse";
 import {
   createChangesetMetaXml,
   createOsmChangeXml,
@@ -19,6 +20,20 @@ export interface UploadChunkInfo {
 
 export type UploadPhase = "upload" | "merge_conflicts";
 
+/** Can include multiple changeset IDs if the upload was chunked. */
+export interface UploadResult {
+  [changesetId: number]: {
+    diffResult: {
+      [Type in OsmFeatureType]?: {
+        [oldId: number]: {
+          newId: number;
+          newVersion: number;
+        };
+      };
+    };
+  };
+}
+
 /** @internal */
 export function compress(input: string) {
   // check if it's supported
@@ -61,7 +76,7 @@ export async function uploadChangeset(
   tags: Tags,
   diff: OsmChange,
   options?: FetchOptions & UploadOptions
-): Promise<number> {
+): Promise<UploadResult> {
   const {
     onChunk,
     onProgress,
@@ -71,10 +86,10 @@ export async function uploadChangeset(
   } = options || {};
 
   const chunks = chunkOsmChange(diff);
-  const csIds: number[] = [];
-
   const featureCount = getOsmChangeSize(diff);
 
+  const result: UploadResult = {};
+
   for (const [index, chunk] of chunks.entries()) {
     let tagsForChunk = tags;
 
@@ -114,23 +129,41 @@ export async function uploadChangeset(
 
     const compressed = !disableCompression && (await compress(osmChangeXml));
 
-    await osmFetch(`/0.6/changeset/${csId}/upload`, undefined, {
-      ...fetchOptions,
-      method: "POST",
-      body: compressed || osmChangeXml,
-      headers: {
-        ...fetchOptions.headers,
-        ...(compressed && { "Content-Encoding": "gzip" }),
-        "content-type": "application/xml; charset=utf-8",
-      },
-    });
+    const idMap = await osmFetch<RawUploadResponse>(
+      `/0.6/changeset/${csId}/upload`,
+      undefined,
+      {
+        ...fetchOptions,
+        method: "POST",
+        body: compressed || osmChangeXml,
+        headers: {
+          ...fetchOptions.headers,
+          ...(compressed && { "Content-Encoding": "gzip" }),
+          "content-type": "application/xml; charset=utf-8",
+        },
+      }
+    );
+
+    // convert the XML format into a more concise JSON format
+    result[csId] = { diffResult: {} };
+    for (const _type in idMap.diffResult[0]) {
+      if (_type === "$") continue;
+      const type = <OsmFeatureType>_type;
+      const items = idMap.diffResult[0][type] || [];
+      for (const item of items) {
+        result[csId].diffResult[type] ||= {};
+        result[csId].diffResult[type][item.$.old_id] = {
+          newId: +item.$.new_id,
+          newVersion: +item.$.new_version,
+        };
+      }
+    }
 
     await osmFetch(`/0.6/changeset/${csId}/close`, undefined, {
       ...fetchOptions,
       method: "PUT",
     });
-    csIds.push(csId);
   }
 
-  return csIds[0]; // TODO:(semver breaking) return an array of IDs
+  return result;
 }

src/api/dwg/hideChangesetComment.ts

@@ -1,18 +1,16 @@
 import type { Changeset } from "../../types";
 import { type FetchOptions, osmFetch } from "../_osmFetch";
-import type { RawChangeset } from "../_rawResponse";
-import { mapRawChangeset } from "../changesets";
 
 /** DWG only */
 export async function hideChangesetComment(
   changesetCommentId: number,
   action?: "hide" | "unhide",
   options?: FetchOptions
 ): Promise<Changeset> {
-  const result = await osmFetch<{ changeset: RawChangeset }>(
+  const result = await osmFetch<{ changeset: Changeset }>(
     `/0.6/changeset_comments/${changesetCommentId}/visibility.json`,
     {},
     { ...options, method: action === "unhide" ? "POST" : "DELETE" }
   );
-  return mapRawChangeset(result.changeset);
+  return result.changeset;
 }