Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 9 additions & 4 deletions examples/uploadChangeset.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
41 changes: 18 additions & 23 deletions src/__tests__/__snapshots__/e2e.test.ts.snap
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand Down
21 changes: 1 addition & 20 deletions src/api/_rawResponse.d.ts
Original file line number Diff line number Diff line change
@@ -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<
Expand Down
57 changes: 54 additions & 3 deletions src/api/changesets/__tests__/uploadChangeset.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -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 () => {
Expand Down Expand Up @@ -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
Expand Down
6 changes: 2 additions & 4 deletions src/api/changesets/createChangesetComment.ts
Original file line number Diff line number Diff line change
@@ -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,
{
Expand All @@ -22,5 +20,5 @@ export async function createChangesetComment(
},
}
);
return mapRawChangeset(result.changeset);
return result.changeset;
}
25 changes: 4 additions & 21 deletions src/api/changesets/getChangesets.ts
Original file line number Diff line number Diff line change
@@ -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 = {
Expand Down Expand Up @@ -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 }),
Expand All @@ -66,7 +49,7 @@ export async function listChangesets(
options
);

return raw.changesets.map(mapRawChangeset);
return raw.changesets;
}

/** get a single changeset */
Expand All @@ -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;
}
Loading