@osmix/core 0.0.2 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @osmix/core
 
+## 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/core/src/entities.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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";
+/**
+ * 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;
+    /** ID storage and lookup */
+    ids: Ids;
+    /** Tag storage and search */
+    tags: Tags;
+    /** 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[];
+}
+//# sourceMappingURL=entities.d.ts.map

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

@@ -0,0 +1 @@
+{"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;AAEhD;;;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;CAQtC"}

package/dist/core/src/entities.js

@@ -0,0 +1,152 @@
+/**
+ * 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;
+    /** ID storage and lookup */
+    ids;
+    /** Tag storage and search */
+    tags;
+    /** Whether buildIndex() has been called */
+    indexBuilt = false;
+    /**
+     * 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;
+        this.tags = tags;
+    }
+    /**
+     * 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() {
+        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.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) {
+            const entity = this.getByIndex(index);
+            if (entity)
+                entities.push(entity);
+            else
+                throw Error(`Entity not found at index ${index}`);
+        }
+        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);
+            if (index === -1)
+                throw Error(`Entity not found at id ${id}`);
+            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);
+    }
+}
+//# sourceMappingURL=entities.js.map

package/dist/core/src/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/entities.ts"],"names":[],"mappings":"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"}