v4: several breaking changes for changeset APIs

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 4.0.0 (----------)
+
+- 💥 BREAKING CHANGE: `uploadChangeset` now returns an array of changeset IDs. This is because the function supports chunking uploads into multiple changesets if it exceeds the limit of 10,000 features per changeset.
+- 💥 BREAKING CHANGE: The type defintions for `Changeset` have been changed to mark several properties as optional. (see #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.
+
 - Add new options to the `OsmUserRole` string union.
 - Change `createChangesetComment` to return the changeset object instead of returning `undefined`.
 - Add 5 new functions that only administrators/moderators can use.

src/__tests__/__snapshots__/e2e.test.ts.snap

@@ -109,10 +109,9 @@ exports[`end to end tests > getCapabilities 1`] = `
 exports[`end to end tests > getChangeset (no discussion) 1`] = `
 {
   "changes_count": 10,
-  "closed_at": 2021-12-16T09:29:15.000Z,
+  "closed_at": "2021-12-16T09:29:15Z",
   "comments_count": 2,
-  "created_at": 2021-12-16T09:29:14.000Z,
-  "discussion": undefined,
+  "created_at": "2021-12-16T09:29:14Z",
   "id": 227200,
   "max_lat": -36.8801278,
   "max_lon": 174.7400986,
@@ -136,27 +135,27 @@ exports[`end to end tests > getChangeset (no discussion) 1`] = `
 exports[`end to end tests > getChangeset (with discussion) 1`] = `
 {
   "changes_count": 10,
-  "closed_at": 2021-12-16T09:29:15.000Z,
-  "comments_count": 2,
-  "created_at": 2021-12-16T09:29:14.000Z,
-  "discussion": [
+  "closed_at": "2021-12-16T09:29:15Z",
+  "comments": [
     {
-      "date": 2024-06-30T08:59:15.000Z,
+      "date": "2024-06-30T08:59:15Z",
       "id": 736,
       "text": "­",
-      "uid": "12248",
+      "uid": 12248,
       "user": "kylenz_testing",
       "visible": true,
     },
     {
-      "date": 2024-06-30T08:59:55.000Z,
+      "date": "2024-06-30T08:59:55Z",
       "id": 737,
       "text": "sup bro",
-      "uid": "12248",
+      "uid": 12248,
       "user": "kylenz_testing",
       "visible": true,
     },
   ],
+  "comments_count": 2,
+  "created_at": "2021-12-16T09:29:14Z",
   "id": 227200,
   "max_lat": -36.8801278,
   "max_lon": 174.7400986,
@@ -533,10 +532,9 @@ exports[`end to end tests > listChangesets 1`] = `
 [
   {
     "changes_count": 2,
-    "closed_at": 2022-09-10T11:47:14.000Z,
+    "closed_at": "2022-09-10T11:47:14Z",
     "comments_count": 0,
-    "created_at": 2022-09-10T11:47:13.000Z,
-    "discussion": undefined,
+    "created_at": "2022-09-10T11:47:13Z",
     "id": 243638,
     "max_lat": -36.8804862,
     "max_lon": 174.739748,
@@ -553,10 +551,9 @@ exports[`end to end tests > listChangesets 1`] = `
   },
   {
     "changes_count": 10,
-    "closed_at": 2022-09-10T11:30:13.000Z,
+    "closed_at": "2022-09-10T11:30:13Z",
     "comments_count": 0,
-    "created_at": 2022-09-10T11:30:12.000Z,
-    "discussion": undefined,
+    "created_at": "2022-09-10T11:30:12Z",
     "id": 243637,
     "max_lat": -36.8804809,
     "max_lon": 174.7397571,
@@ -576,10 +573,9 @@ exports[`end to end tests > listChangesets 1`] = `
   },
   {
     "changes_count": 10,
-    "closed_at": 2021-12-16T09:29:15.000Z,
+    "closed_at": "2021-12-16T09:29:15Z",
     "comments_count": 2,
-    "created_at": 2021-12-16T09:29:14.000Z,
-    "discussion": undefined,
+    "created_at": "2021-12-16T09:29:14Z",
     "id": 227200,
     "max_lat": -36.8801278,
     "max_lon": 174.7400986,
@@ -600,10 +596,9 @@ exports[`end to end tests > listChangesets 1`] = `
   },
   {
     "changes_count": 5,
-    "closed_at": 2021-12-16T08:43:07.000Z,
+    "closed_at": "2021-12-16T08:43:07Z",
     "comments_count": 0,
-    "created_at": 2021-12-16T08:43:06.000Z,
-    "discussion": undefined,
+    "created_at": "2021-12-16T08:43:06Z",
     "id": 227184,
     "max_lat": -36.8804809,
     "max_lon": 174.7397571,

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

@@ -53,7 +53,7 @@ describe("uploadChangeset", () => {
       { comment: "added a building" },
       { create: [], modify: [], delete: [] }
     );
-    expect(output).toBe(1);
+    expect(output).toStrictEqual([1]);
 
     expect(osmFetch).toHaveBeenCalledTimes(3);
     expect(osmFetch).toHaveBeenNthCalledWith(
@@ -94,7 +94,7 @@ describe("uploadChangeset", () => {
       );
     }
 
-    expect(output).toBe(1);
+    expect(output).toStrictEqual([1, 4, 7, 10]);
   });
 
   it("splits changesets into chunks and suports a custom tag function", async () => {
@@ -128,6 +128,6 @@ describe("uploadChangeset", () => {
       );
     }
 
-    expect(output).toBe(1);
+    expect(output).toStrictEqual([1, 4, 7, 10]);
   });
 });

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

@@ -33,7 +33,7 @@ export async function uploadChangeset(
      */
     onChunk?(info: UploadChunkInfo): Tags;
   }
-): Promise<number> {
+): Promise<number[]> {
   const chunks = chunkOsmChange(diff);
   const csIds: number[] = [];
 
@@ -91,5 +91,5 @@ export async function uploadChangeset(
     csIds.push(csId);
   }
 
-  return csIds[0]; // TODO:(semver breaking) return an array of IDs
+  return csIds;
 }

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;
 }

src/types/changesets.ts

@@ -5,40 +5,32 @@ export type ChangesetComment = {
   id: number;
   visible: boolean;
   user: string;
-  // TODO:(semver breaking) change to number
-  uid: string;
-  // TODO:(semver breaking) change to string
-  date: Date;
+  uid: number;
+  date: string;
   text: string;
 };
 
 export type Changeset = {
   id: number;
-  // TODO:(semver breaking) change to string
-  created_at: Date;
+  created_at: string;
   open: boolean;
   comments_count: number;
   changes_count: number;
-  /** property only exists if `open=false` */
-  // TODO:(semver breaking) mark as optional
-  closed_at: Date;
-  /** property only exists if `open=false` */
-  // TODO:(semver breaking) mark as optional
-  min_lat: number;
-  /** property only exists if `open=false` */
-  // TODO:(semver breaking) mark as optional
-  min_lon: number;
-  /** property only exists if `open=false` */
-  // TODO:(semver breaking) mark as optional
-  max_lat: number;
-  /** property only exists if `open=false` */
-  // TODO:(semver breaking) mark as optional
-  max_lon: number;
+  /** This property is missing if `open=true` */
+  closed_at?: string;
+  /** This property is missing if `open=true`, or if none of the edited features have geometry data (see #14) */
+  min_lat?: number;
+  /** This property is missing if `open=true`, or if none of the edited features have geometry data (see #14) */
+  min_lon?: number;
+  /** This property is missing if `open=true`, or if none of the edited features have geometry data (see #14) */
+  max_lat?: number;
+  /** This property is missing if `open=true`, or if none of the edited features have geometry data (see #14) */
+  max_lon?: number;
   uid: number;
   user: string;
   tags: Tags;
-  /** the `discussion` attribute is only included in the `getChangeset` API */
-  discussion?: ChangesetComment[];
+  /** the `comments` attribute is only included in the `getChangeset` API */
+  comments?: ChangesetComment[];
 };
 
 export type OsmChange = {