@osmix/change

@osmix/change is the change-management companion to @osmix/core. It builds, inspects, and applies OpenStreetMap changesets on top of Osm datasets, giving you tools to deduplicate entities, reconcile overlaps, generate stats, and orchestrate merge pipelines.

Highlights

• Construct repeatable OsmChangesets that track creates, modifies, and deletes with origin metadata and per-entity refs.
• Augmented diffs: Automatically captures both old and new entity states for modifications and deletions, following the Overpass API Augmented Diffs format.
• Deduplicate coincident nodes or overlapping ways, replace references, and optionally create intersection points where geometry meets.
• Generate summary stats and OSC-friendly XML fragments so downstream systems can audit each change step.
• Run merge(base, patch, options) to execute the full dedupe/merge workflow with a single call.
• Export lightweight utilities for measuring distances, pruning duplicate refs, and deciding when ways should connect.

Installation

pnpm add @osmix/change

Application code can import these APIs from the osmix facade. Install the granular package directly when building a lower-level package integration.

Usage

Build and apply a changeset

import { OsmChangeset, applyChangesetToOsm, changeStatsSummary, fromPbf } from "osmix";

const base = await fromPbf(monacoPbf);
const patch = await fromPbf(patchPbf);

const changeset = new OsmChangeset(base);
changeset.deduplicateNodes(base.nodes);
changeset.deduplicateWays(base.ways);
changeset.generateDirectChanges(patch);

console.log(changeStatsSummary(changeset.stats));

const merged = applyChangesetToOsm(changeset);
console.log(merged.id);

OsmChangeset keeps track of creates/modifies/deletes per entity type. Call the helpers (deduplicateNodes, deduplicateWays, generateDirectChanges, createIntersectionsForWays, etc.) in whatever order your workflow requires, then use applyChangesetToOsm() to produce a new Osm instance with the edits applied.

Run the bundled merge pipeline

import { merge } from "osmix";

const combined = await merge(base, patch, {
  directMerge: true,
  deduplicateNodes: true,
  deduplicateWays: true,
  createIntersections: true,
});
console.log(combined.id);

merge wraps a sequence of changesets that deduplicate each dataset, optionally create intersections, and (when directMerge is true) generate modifications that reconcile the patch into the base. All options default to false, so you can enable only the stages you need.

API

OsmChangeset

Tracks and orchestrates changes against a base Osm dataset.

Schematic constructor signature:

constructor(base: Osm)

Core methods

• deduplicateNodes(nodes: Nodes): Check a set of nodes (usually from the base or patch) for duplicates against the base dataset. Deletes duplicates and maps their IDs to the surviving node.
• deduplicateWays(ways: Ways): Check a set of ways for geometric duplicates. Deletes duplicates and preserves the one with more tags/metadata.
• generateDirectChanges(patch: Osm): Merge a patch dataset into the changeset. Handles creates and updates.
• createIntersectionsForWays(ways: Ways): Checks provided ways for intersections with existing ways in the base dataset. Splits ways and inserts nodes where they cross.
• applyNodeReplacementsToWays(replacementMap): Updates way references based on a map of replaced node IDs (generated by deduplicateNodes).
• applyNodeReplacementsToRelations(replacementMap): Updates relation members based on replaced node IDs.

merge(base: Osm, patch: Osm, options)

High-level pipeline to merge patch into base. Returns a new Osm instance.

Options:

• directMerge (boolean): Apply creates/updates from patch.
• deduplicateNodes (boolean): Run node deduplication.
• deduplicateWays (boolean): Run way deduplication.
• createIntersections (boolean): Split intersecting ways.

applyChangesetToOsm(changeset: OsmChangeset): Osm

Applies all pending changes in the changeset to produce a new Osm instance. The original base is immutable.

Augmented Diffs

By default, all OsmChange records include an oldEntity field for modifications and deletions, capturing the entity's state before the change. This follows the Overpass API Augmented Diffs format.

import { OsmChangeset } from "osmix";

const changeset = new OsmChangeset(base);
changeset.generateDirectChanges(patch);

// Access the old and new state for a modified entity
const wayChange = changeset.wayChanges[wayId];
if (wayChange) {
  console.log("Old tags:", wayChange.oldEntity?.tags);
  console.log("New tags:", wayChange.entity.tags);
}

generateOscChanges(changeset, options?)

Generates OSC (OSM Change) XML format from a changeset.

import { generateOscChanges, OsmChangeset } from "osmix";

const changeset = new OsmChangeset(base);

// Generate standard OSC for API uploads (default)
const osc = generateOscChanges(changeset);

// Generate augmented diff with old/new sections
const augmentedOsc = generateOscChanges(changeset, { augmented: true });
console.log(osc.length, augmentedOsc.length);

Options:

• augmented (boolean, default: false): When true, modifications include <old> and <new> sections, and deletions include <old> sections with the full entity data.

Related Packages

• @osmix/core – Typed-array index powering the change operations.
• @osmix/pbf – Streaming helpers used to read and write .osm.pbf data.
• @osmix/json – JSON entity adapters that pair with change workflows.
• Osmix Merge app – Browser UI built on top of the change pipeline.

Environment and limitations

• Requires runtimes compatible with @osmix/core (Node 20+, Bun, or modern browsers) since the same typed-array data structures are used.
• Deduplication helpers assume datasets store dense node blocks and rely on spatial indexes built via Osm.buildIndexes().
• Intersections are generated only for highway/footway-style features; polygonal ways are ignored.

Development

• pnpm run test packages/change
• pnpm run lint packages/change
• pnpm run typecheck packages/change

Run pnpm run check at the repo root before publishing to ensure formatting, lint, and type coverage.