@osmix/core 0.0.2 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @osmix/core
 
+## 0.1.1
+
+### Patch Changes
+
+- d4f4b1f: Add content hashing for quick `isEqual`s checks of two similar `Osm` indexes. Typically used for checking post-merge.
+
+## 0.1.0
+
+### Minor Changes
+
+- 29ed376: Routing: make graph transferable
+
+### Patch Changes
+
+- 803c05c: Merge app style cleanup
+- cbe4273: Osm index storage and reload
+- ff40416: Refactor main `osmix` lib external APIs
+
+## 0.0.6
+
+### Patch Changes
+
+- 3846a0c: Integrate geographic spatial indexing libraries
+- cdab4db: Add router
+- Updated dependencies [0cd8a2e]
+  - @osmix/shared@0.0.6
+
+## 0.0.5
+
+### Patch Changes
+
+- a33a280: Create an easy way to estimate bytes required for a given OSM size
+- edbb26b: Handle more Relation types
+- 69a36bd: Switch Nodes coordinate storage to Int32Array
+- Updated dependencies [bb629cf]
+- Updated dependencies [edbb26b]
+- Updated dependencies [69a36bd]
+  - @osmix/shared@0.0.5
+
+## 0.0.4
+
+### Patch Changes
+
+- d001d9a: Refactor to align around new main external API
+- 4303c40: Refactor core Osmix index to prepare for future work
+- Updated dependencies [572cbd8]
+- Updated dependencies [d001d9a]
+  - @osmix/shared@0.0.4
+
+## 0.0.3
+
+### Patch Changes
+
+- b4a3ff2: Improve Relation handling and display
+- c0193dd: Import GeoJSON into Osmix
+- Updated dependencies [b4a3ff2]
+  - @osmix/shared@0.0.3
+  - @osmix/json@0.0.3
+  - @osmix/pbf@0.0.2
+
 ## 0.0.2
 
 ### Patch Changes

package/README.md

@@ -1,160 +1,171 @@
 # @osmix/core
 
-@osmix/core wraps the `Osmix` index: a typed-array OpenStreetMap engine that reads `.osm.pbf` streams, builds spatial indexes, and emits JSON, PBF, or raster tiles without leaving modern JavaScript runtimes.
+In-memory OSM entity storage with spatial indexing. Provides core data structures for efficiently storing and querying OpenStreetMap nodes, ways, and relations.
 
 ## Highlights
 
-- Ingest `.osm.pbf` sources into node, way, and relation stores backed by transferable typed arrays using readers from [`@osmix/pbf`](../pbf/README.md).
-- Run fast bounding-box searches with KDBush/Flatbush and convert matches straight to GeoJSON.
-- Trim extracts, write new PBF buffers, or stream entities to downstream tooling with [`@osmix/json`](../json/README.md) or [`@osmix/pbf`](../pbf/README.md).
-- Pair with [`@osmix/change`](../change/README.md) when you need deduplication, intersection, or merge pipelines.
-- Ship fully indexed datasets across workers via `transferables()` + `Osmix.from`.
+- **Memory-efficient**: Typed arrays and microdegree coordinates (`Int32Array`) minimize memory while maintaining precision.
+- **Spatial indexing**: KDBush (points) and Flatbush (bboxes) for fast geographic queries. Supports bbox and radius searches via geokdbush/geoflatbush.
+- **Worker-ready**: Serialize to `ArrayBuffer`/`SharedArrayBuffer` for zero-copy transfer via `transferables()`.
+- **Tag search**: Reverse-index lookup for fast entity searches by tag key.
+- **Streaming**: Iterate entities or sorted-by-ID without materializing full arrays.
 
 ## Installation
 
 ```sh
-npm install @osmix/core
+bun add @osmix/core
 ```
 
 ## Usage
 
-### Load a PBF in one call
+### Loading PBF files
 
-```ts
-import { Osmix } from "@osmix/core"
-import { readFile } from "node:fs/promises"
+`@osmix/core` provides the in-memory data structures. To parse `.osm.pbf` files, use the high-level `osmix` package:
 
-const osm = await Osmix.fromPbf(readFile("example.osm.pbf"))
+```ts
+import { fromPbf } from "osmix"
 
+const osm = await fromPbf(Bun.file("./monaco.pbf").stream())
 console.log(osm.nodes.size, osm.ways.size, osm.relations.size)
 ```
 
-`fromPbf` accepts `ArrayBufferLike`, async (iterable) chunks, or Web `ReadableStream` inputs.
+### Building data directly
 
-### Stream with progress and extraction
-
-Pass a logger or set one later to receive throttled progress messages. Provide `extractBbox` to keep only features intersecting the desired bounds while parsing.
+For synthetic data or tests, instantiate `Osm` directly and call `buildIndexes()` / `buildSpatialIndexes()` before querying:
 
 ```ts
-import { Osmix } from "@osmix/core"
-import { createReadStream } from "node:fs"
+import { Osm } from "@osmix/core"
 
-const osm = new Osmix({ id: "planet-seattle" })
-osm.setLogger((message) => console.log(message))
+const osm = new Osm({ id: "fixture" })
 
-await osm.readPbf(createReadStream("planet.osm.pbf"), {
-	extractBbox: [-122.5, 47.45, -122.2, 47.75],
+osm.nodes.addNode({
+	id: 1,
+	lon: -122.4,
+	lat: 47.6,
+	tags: { amenity: "cafe" },
 })
-```
 
-### Build synthetic fixtures
-
-When generating test data, insert entities directly and call `buildIndexes()` before querying.
+osm.ways.addWay({
+	id: 10,
+	refs: [1],
+	tags: { highway: "service" },
+})
 
-```ts
-const osm = new Osmix({ id: "fixture" })
-osm.nodes.addNode({ id: 1, lon: -0.1, lat: 51.5, tags: { amenity: "cafe" } })
-osm.ways.addWay({ id: 10, refs: [1], tags: { highway: "service" } })
 osm.buildIndexes()
+osm.buildSpatialIndexes()
 ```
 
-## Query the index
-
-- `osm.get("node", 123)` or `osm.getById("n123")` fetches specific entities.
-- `osm.nodes.sorted()` / `osm.ways.sorted()` iterate ids in ascending order.
-- `osm.getEntityGeoJson(entity)` returns a GeoJSON feature with coordinates resolved from the
-  indexed nodes.
-
-Spatial lookups emit compact typed arrays that can be transferred across Web Workers and used directly in `Deck.gl`:
+### Querying entities
 
 ```ts
-const bbox = [-122.34, 47.57, -122.30, 47.61]
-const { ids, positions } = osm.getNodesInBbox(bbox)
-
-const { ids: wayIds, positions: wayCoords, startIndices } = osm.getWaysInBbox(bbox)
-```
+// Get by ID
+const node = osm.nodes.getById(123)
+const way = osm.ways.get({ id: 456 })
 
-`positions` stores `[lon, lat]` pairs; `startIndices` splits `wayCoords` into per-way sequences.
-
-## Extract and export data
+// Iterate all entities
+for (const node of osm.nodes) {
+	console.log(node.id, node.lon, node.lat)
+}
 
-```ts
-const downtown = osm.extract([-122.35, 47.60, -122.32, 47.62])
+// Iterate sorted by ID (useful for PBF export)
+for (const way of osm.ways.sorted()) {
+	console.log(way.id, way.refs)
+}
 
-const entityStream = downtown.toEntityStream() // header + entities
-const pbfStream = downtown.toPbfStream() // Uint8Array chunks
-const pbfBuffer = await downtown.toPbfBuffer()
+// Search by tag key
+const highways = osm.ways.search("highway")
+const cafes = osm.nodes.search("amenity", "cafe")
 ```
 
-`extract` returns a new, fully indexed `Osmix` instance with the header bbox updated.
-
-## Changesets and merging
-
-Change orchestration now lives in the dedicated [`@osmix/change`](../change/README.md) package. Install it alongside
-`@osmix/core` when you want to deduplicate entities, generate direct merges, or script intersection creation:
+### Spatial queries
 
 ```ts
-import { Osmix } from "@osmix/core"
-import { merge, OsmixChangeset } from "@osmix/change"
-import { readFile } from "node:fs/promises"
+// Bounding box query
+const bbox: [number, number, number, number] = [-122.34, 47.57, -122.30, 47.61]
+const { ids, positions } = osm.nodes.withinBbox(bbox)
+const { ids: wayIds, positions: wayCoords, startIndices } = osm.ways.withinBbox(bbox)
 
-const base = await Osmix.fromPbf(readFile("base.osm.pbf"))
-const patch = await Osmix.fromPbf(readFile("patch.osm.pbf"))
+// Radius query (uses great-circle distance)
+const nearbyIndexes = osm.nodes.findIndexesWithinRadius(-122.4, 47.6, 10) // 10km
 
-const changeset = new OsmixChangeset(base)
-changeset.deduplicateWays(base.ways)
+// Get entities from indexes
+const nearbyNodes = nearbyIndexes.map((i) => osm.nodes.getByIndex(i))
 
-const merged = await merge(base, patch, { directMerge: true })
+// Ways/relations use Flatbush for bounding-box intersection
+const intersectingWays = osm.ways.intersects(bbox)
+const nearestWays = osm.ways.neighbors(-122.4, 47.6, 5, 10) // 5 results, 10km max
 ```
 
-Refer to the [`@osmix/change` README](../change/README.md) for the full API surface.
-
-## Transfer between threads
-
-Typed arrays keep the index transferable.
+### Transferring between workers
 
 ```ts
-// main thread
-const payload = osm.transferables()
-const buffers = []
-const collect = (value: unknown) => {
-	if (value instanceof ArrayBuffer) buffers.push(value)
-	else if (ArrayBuffer.isView(value)) buffers.push(value.buffer)
-	else if (Array.isArray(value)) value.forEach(collect)
-	else if (value && typeof value === "object")
-		Object.values(value).forEach(collect)
-	return buffers
-}
-
-worker.postMessage(payload, { transfer: collect(payload) })
+// In the main thread
+const transferables = osm.transferables()
+worker.postMessage(transferables, Object.values(transferables).filter(ArrayBuffer.isView))
 
-// worker
-import { Osmix } from "@osmix/core"
-
-self.addEventListener("message", ({ data }) => {
-	const osm = Osmix.from(data)
-	// ready for queries immediately
-})
+// In the worker
+const osm = new Osm(transferables)
+// Index is already built, ready for queries
 ```
 
-## API overview
-
-- `Osmix` – ingest PBF sources, build indexes, query entities, extract subsets, and emit JSON/PBF.
-- `Nodes` / `Ways` / `Relations` – typed-array backed stores exposed for advanced workflows.
-- `OsmixRasterTile` – rasterize indexed data into tile-sized buffers with lon/lat helpers.
-- Utilities – `throttle`, plus the shared type definitions used across the package.
-- Changesets and merge helpers now live in [`@osmix/change`](../change/README.md).
-
-## Environment and limitations
-
-- Requires runtimes with Web Streams, `TextEncoder`/`TextDecoder`, and zlib-compatible `CompressionStream`/`DecompressionStream` support (Bun, Node 20+, modern browsers).
-- `readPbf` expects dense-node blocks; PBFs that omit dense encodings are currently unsupported.
-- Filtering during ingest depends on node membership; emit nodes, then ways, then relations when supplying custom entity generators.
+## API
+
+### Classes
+
+| Class | Description |
+|-------|-------------|
+| `Osm` | Main container with nodes, ways, relations, and shared string table |
+| `Nodes` | Node storage with KDBush spatial index |
+| `Ways` | Way storage with Flatbush spatial index |
+| `Relations` | Relation storage with Flatbush spatial index |
+| `StringTable` | Deduplicated UTF-8 string storage for tags |
+| `Tags` | Bidirectional tag storage (entity→tags, key→entities) |
+
+### Osm Methods
+
+| Method | Description |
+|--------|-------------|
+| `buildIndexes()` | Finalize ID, tag, and entity indexes after adding data |
+| `buildSpatialIndexes()` | Build spatial indexes for all entity types |
+| `bbox()` | Get bounding box of all entities |
+| `info()` | Get summary info (id, bbox, header, stats) |
+| `transferables()` | Get serializable buffers for worker transfer |
+| `isReady()` | Check if all indexes are built |
+
+### Entity Collection Methods
+
+| Method | Description |
+|--------|-------------|
+| `getById(id)` | Get entity by OSM ID |
+| `get({ id } \| { index })` | Get by ID or internal index |
+| `getByIndex(index)` | Get by internal array index |
+| `search(key, value?)` | Find entities with tag key (and optional value) |
+| `withinBbox(bbox)` | Get entities within bounding box |
+| `findIndexesWithinRadius(lon, lat, km)` | Find nearby entities (nodes) |
+| `intersects(bbox)` | Find intersecting entities (ways/relations) |
+| `neighbors(lon, lat, max, maxKm)` | Find nearest entities (ways/relations) |
+| `sorted()` | Iterator over entities sorted by ID |
+
+## Environment and Limitations
+
+- Requires Web Streams, `TextEncoder`/`TextDecoder`, `CompressionStream`/`DecompressionStream` (Bun, Node 20+, modern browsers).
+- Uses ES2024 resizable `ArrayBuffer` and growable `SharedArrayBuffer` when available.
+- Coordinates stored as `Int32Array` microdegrees (1e-7 degree precision, ~1cm at equator); converted to degrees at API boundaries.
+
+## Related Packages
+
+- [`osmix`](../osmix/README.md) — High-level API for loading PBF files and worker orchestration.
+- [`@osmix/pbf`](../pbf/README.md) — Low-level PBF parsing and serialization.
+- [`@osmix/json`](../json/README.md) — JSON entity conversion.
+- [`@osmix/geojson`](../geojson/README.md) — Convert entities to GeoJSON features.
+- [`@osmix/change`](../change/README.md) — Changeset generation, deduplication, and merge.
 
 ## Development
 
-- `bun run test packages/core`
-- `bun run lint packages/core`
-- `bun run typecheck packages/core`
+```sh
+bun run test packages/core
+bun run typecheck packages/core
+bun run lint packages/core
+```
 
-Run `bun run check` at the repo root before publishing to ensure formatting, lint, and type coverage.
+Run `bun run check` at the repo root before publishing.

package/dist/src/entities.d.ts

@@ -1,26 +1,120 @@
-import type { OsmEntity, OsmEntityType, OsmTags } from "@osmix/json";
-import { type IdOrIndex, Ids, type IdsTransferables } from "./ids";
-import type StringTable from "./stringtable";
-import { Tags, type TagsTransferables } from "./tags";
-export interface EntitiesTransferables extends IdsTransferables, TagsTransferables {
+/**
+ * Base class for OSM entity collections.
+ *
+ * Provides common ID and tag storage, streaming iteration, and sorted access.
+ * Subclasses implement entity-specific storage and spatial indexing.
+ *
+ * @module
+ */
+import type { GeoBbox2D, OsmEntity, OsmEntityType, OsmTags } from "@osmix/shared/types";
+import type { IdOrIndex, Ids, IdsTransferables } from "./ids";
+import type { Tags, TagsTransferables } from "./tags";
+import type { BufferType } from "./typed-arrays";
+import type { ContentHasher } from "./utils";
+/**
+ * Serializable representation of an Entities collection for worker transfer.
+ * Combines ID and tag transferables; subclasses add entity-specific data.
+ */
+export interface EntitiesTransferables<T extends BufferType = BufferType> extends IdsTransferables<T>, TagsTransferables<T> {
 }
+/**
+ * Abstract base for typed entity collections.
+ *
+ * Lifecycle:
+ * 1. **Ingest**: `addEntity()` (no lookups).
+ * 2. **Finalize**: `buildIndex()`.
+ * 3. **Query**: Lookups and iteration enabled.
+ */
 export declare abstract class Entities<T extends OsmEntity> {
+    /** The type of entity stored in this collection ("node", "way", or "relation"). */
     indexType: OsmEntityType;
-    stringTable: StringTable;
+    /** ID storage and lookup */
     ids: Ids;
+    /** Tag storage and search */
     tags: Tags;
-    private indexBuilt;
-    constructor(indexType: OsmEntityType, stringTable: StringTable, ids?: Ids, tags?: Tags);
-    get isReady(): boolean;
+    /** Whether buildIndex() has been called */
+    protected indexBuilt: boolean;
+    /**
+     * Create a new Entities collection.
+     * @param indexType - The entity type ("node", "way", or "relation").
+     * @param ids - The ID storage instance.
+     * @param tags - The tag storage instance.
+     */
+    constructor(indexType: OsmEntityType, ids: Ids, tags: Tags);
+    /**
+     * Get transferable objects for passing to another thread.
+     */
+    transferables(): EntitiesTransferables;
+    /**
+     * Check if the index is built and ready for use.
+     */
+    isReady(): boolean;
+    /** Number of entities in this collection. */
     get size(): number;
+    /**
+     * Compact entity-specific typed arrays.
+     * Called by `buildIndex()` after ID and tag indexes are built.
+     * @abstract
+     */
     abstract buildEntityIndex(): void;
+    /**
+     * Finalize indexes.
+     * Must be called after adding entities and before querying.
+     */
     buildIndex(): void;
+    /**
+     * Get the bounding box of an entity.
+     * @param idOrIndex - Entity identifier (by ID or internal index).
+     * @returns Geographic bounding box [minLon, minLat, maxLon, maxLat].
+     * @abstract
+     */
+    abstract getEntityBbox(idOrIndex: IdOrIndex): GeoBbox2D;
+    /**
+     * Reconstruct a full entity object from index data.
+     * @param index - Internal array index.
+     * @param id - OSM entity ID.
+     * @param tags - Optional pre-fetched tags.
+     * @returns The complete entity object.
+     * @abstract
+     */
     abstract getFullEntity(index: number, id: number, tags?: OsmTags): T;
+    /**
+     * Add an entity to the index. Tags can be provided as an array of keys and values, or as an object.
+     */
+    addEntity(id: number, tags: number[], values: number[]): number;
+    addEntity(id: number, tags: OsmTags): number;
+    /**
+     * Get an entity by ID or index.
+     */
     get(idOrIndex: IdOrIndex): T | null;
+    /**
+     * Get an entity by index.
+     */
     getByIndex(index: number): T;
+    /**
+     * Get multiple entities by their indexes.
+     */
     getEntitiesByIndex(indexes: number[]): T[];
+    /**
+     * Iterate over all entities in the index.
+     */
     [Symbol.iterator](): Generator<T>;
+    /**
+     * Get an entity by ID.
+     */
     getById(id: number): T | null;
+    /**
+     * Iterate over entities sorted by ID.
+     */
     sorted(): Generator<T>;
+    /**
+     * Search for entities with a specific tag key and optional value.
+     */
+    search(key: string, val?: string): T[];
+    /**
+     * Update a ContentHasher with this entity collection's base data (IDs and tags).
+     * Subclasses should override to add entity-specific data.
+     */
+    updateHash(hasher: ContentHasher): ContentHasher;
 }
 //# sourceMappingURL=entities.d.ts.map

package/dist/src/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/entities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,KAAK,SAAS,EAAE,GAAG,EAAE,KAAK,gBAAgB,EAAE,MAAM,OAAO,CAAA;AAClE,OAAO,KAAK,WAAW,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,KAAK,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAErD,MAAM,WAAW,qBAChB,SAAQ,gBAAgB,EACvB,iBAAiB;CAAG;AAEtB,8BAAsB,QAAQ,CAAC,CAAC,SAAS,SAAS;IACjD,SAAS,EAAE,aAAa,CAAA;IACxB,WAAW,EAAE,WAAW,CAAA;IACxB,GAAG,EAAE,GAAG,CAAA;IACR,IAAI,EAAE,IAAI,CAAA;IAEV,OAAO,CAAC,UAAU,CAAQ;gBAGzB,SAAS,EAAE,aAAa,EACxB,WAAW,EAAE,WAAW,EACxB,GAAG,CAAC,EAAE,GAAG,EACT,IAAI,CAAC,EAAE,IAAI;IAQZ,IAAI,OAAO,YAEV;IAED,IAAI,IAAI,WAEP;IAED,QAAQ,CAAC,gBAAgB,IAAI,IAAI;IAEjC,UAAU;IASV,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,CAAC;IAEpE,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,CAAC,GAAG,IAAI;IAMnC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC;IAQ5B,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE;IAUzC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC;IAMlC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAO5B,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC;CAOvB"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/entities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,SAAS,EACT,SAAS,EACT,aAAa,EACb,OAAO,EACP,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAA;AAC7D,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,CACvE,SAAQ,gBAAgB,CAAC,CAAC,CAAC,EAC1B,iBAAiB,CAAC,CAAC,CAAC;CAAG;AAEzB;;;;;;;GAOG;AACH,8BAAsB,QAAQ,CAAC,CAAC,SAAS,SAAS;IACjD,mFAAmF;IACnF,SAAS,EAAE,aAAa,CAAA;IACxB,4BAA4B;IAC5B,GAAG,EAAE,GAAG,CAAA;IACR,6BAA6B;IAC7B,IAAI,EAAE,IAAI,CAAA;IAEV,2CAA2C;IAC3C,SAAS,CAAC,UAAU,UAAQ;IAE5B;;;;;OAKG;gBACS,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI;IAM1D;;OAEG;IACH,aAAa,IAAI,qBAAqB;IAOtC;;OAEG;IACH,OAAO;IAIP,6CAA6C;IAC7C,IAAI,IAAI,WAEP;IAED;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,IAAI,IAAI;IAEjC;;;OAGG;IACH,UAAU;IAUV;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS;IAEvD;;;;;;;OAOG;IACH,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,CAAC;IAEpE;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM;IAC/D,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM;IAa5C;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,CAAC,GAAG,IAAI;IAMnC;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC;IAQ5B;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE;IAU1C;;OAEG;IACF,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC;IAMlC;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAO7B;;OAEG;IACF,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC;IAQvB;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAStC;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa;CAGhD"}

package/dist/src/entities.js

@@ -1,40 +1,102 @@
-import { Ids } from "./ids";
-import { Tags } from "./tags";
+/**
+ * Base class for OSM entity collections.
+ *
+ * Provides common ID and tag storage, streaming iteration, and sorted access.
+ * Subclasses implement entity-specific storage and spatial indexing.
+ *
+ * @module
+ */
+/**
+ * Abstract base for typed entity collections.
+ *
+ * Lifecycle:
+ * 1. **Ingest**: `addEntity()` (no lookups).
+ * 2. **Finalize**: `buildIndex()`.
+ * 3. **Query**: Lookups and iteration enabled.
+ */
 export class Entities {
+    /** The type of entity stored in this collection ("node", "way", or "relation"). */
     indexType;
-    stringTable;
+    /** ID storage and lookup */
     ids;
+    /** Tag storage and search */
     tags;
+    /** Whether buildIndex() has been called */
     indexBuilt = false;
-    constructor(indexType, stringTable, ids, tags) {
-        this.stringTable = stringTable;
+    /**
+     * Create a new Entities collection.
+     * @param indexType - The entity type ("node", "way", or "relation").
+     * @param ids - The ID storage instance.
+     * @param tags - The tag storage instance.
+     */
+    constructor(indexType, ids, tags) {
         this.indexType = indexType;
-        this.ids = ids ?? new Ids();
-        this.tags = tags ?? new Tags(stringTable);
+        this.ids = ids;
+        this.tags = tags;
     }
-    get isReady() {
-        return this.ids.isReady && this.tags.isReady && this.indexBuilt;
+    /**
+     * Get transferable objects for passing to another thread.
+     */
+    transferables() {
+        return {
+            ...this.ids.transferables(),
+            ...this.tags.transferables(),
+        };
     }
+    /**
+     * Check if the index is built and ready for use.
+     */
+    isReady() {
+        return this.ids.isReady() && this.tags.isReady() && this.indexBuilt;
+    }
+    /** Number of entities in this collection. */
     get size() {
         return this.ids.size;
     }
+    /**
+     * Finalize indexes.
+     * Must be called after adding entities and before querying.
+     */
     buildIndex() {
-        console.time(`${this.indexType}Index.finish`);
+        if (this.indexBuilt)
+            return;
+        console.time(`${this.indexType}Index.buildIndex`);
         this.ids.buildIndex();
         this.tags.buildIndex();
         this.buildEntityIndex();
         this.indexBuilt = true;
-        console.timeEnd(`${this.indexType}Index.finish`);
+        console.timeEnd(`${this.indexType}Index.buildIndex`);
+    }
+    addEntity(id, tags, values) {
+        const entityIndex = this.ids.add(id);
+        if (Array.isArray(tags)) {
+            if (values === undefined)
+                throw Error("Values are required when tags is an array");
+            this.tags.addTagKeysAndValues(entityIndex, tags, values);
+        }
+        else {
+            this.tags.addTags(entityIndex, tags);
+        }
+        return entityIndex;
     }
+    /**
+     * Get an entity by ID or index.
+     */
     get(idOrIndex) {
         const [index, id] = this.ids.idOrIndex(idOrIndex);
         if (index === -1)
             return null;
         return this.getFullEntity(index, id, this.tags.getTags(index));
     }
+    /**
+     * Get an entity by index.
+     */
     getByIndex(index) {
         return this.getFullEntity(index, this.ids.at(index), this.tags.getTags(index));
     }
+    /**
+     * Get multiple entities by their indexes.
+     */
     getEntitiesByIndex(indexes) {
         const entities = [];
         for (const index of indexes) {
@@ -46,17 +108,26 @@ export class Entities {
         }
         return entities;
     }
+    /**
+     * Iterate over all entities in the index.
+     */
     *[Symbol.iterator]() {
         for (let i = 0; i < this.size; i++) {
             yield this.getFullEntity(i, this.ids.at(i), this.tags.getTags(i));
         }
     }
+    /**
+     * Get an entity by ID.
+     */
     getById(id) {
         const index = this.ids.getIndexFromId(id);
         if (index !== -1)
             return this.getFullEntity(index, id, this.tags.getTags(index));
         return null;
     }
+    /**
+     * Iterate over entities sorted by ID.
+     */
     *sorted() {
         for (const id of this.ids.sorted) {
             const index = this.ids.getIndexFromId(id);
@@ -65,5 +136,24 @@ export class Entities {
             yield this.getFullEntity(index, id, this.tags.getTags(index));
         }
     }
+    /**
+     * Search for entities with a specific tag key and optional value.
+     */
+    search(key, val) {
+        const keyIndex = this.tags.find(key);
+        const entities = this.tags
+            .hasKey(keyIndex)
+            .map((index) => this.getByIndex(index));
+        if (val === undefined)
+            return entities;
+        return entities.filter((entity) => entity.tags?.[key] === val);
+    }
+    /**
+     * Update a ContentHasher with this entity collection's base data (IDs and tags).
+     * Subclasses should override to add entity-specific data.
+     */
+    updateHash(hasher) {
+        return this.ids.updateHash(this.tags.updateHash(hasher));
+    }
 }
 //# sourceMappingURL=entities.js.map