@osmix/core 0.0.2 → 0.0.6

package/dist/core/src/stringtable.js

@@ -0,0 +1,170 @@
+/**
+ * Deduplicated UTF-8 string storage.
+ *
+ * Strings are stored in a flat buffer and referenced by index.
+ * Supports fast deduplication (string→index) and lazy reconstruction (index→string).
+ *
+ * @module
+ */
+import { ResizeableTypedArray as RTA } from "./typed-arrays";
+/**
+ * Append-only deduplicated string table.
+ *
+ * Limits: Max string length 65,535 bytes.
+ * Rebuilds reverse index lazily after transfer.
+ */
+export default class StringTable {
+    /** UTF-8 encoder for string→bytes conversion */
+    enc = new TextEncoder();
+    /** UTF-8 decoder for bytes→string conversion */
+    dec = new TextDecoder(); // UTF-8
+    // ─── Serializable State ────────────────────────────────────────────────────
+    /** Concatenated UTF-8 bytes of all strings */
+    bytes;
+    /** Maps string index → byte offset in bytes array */
+    start;
+    /** Maps string index → byte length */
+    count;
+    // ─── Builder State (string → index) ────────────────────────────────────────
+    /** Forward lookup: string → index (populated during add) */
+    stringToIndex = new Map();
+    /** Whether the reverse index has been built (lazy after transfer) */
+    reverseIndexBuilt = false;
+    // ─── Retrieval Cache (index → string) ──────────────────────────────────────
+    /** Cache of decoded strings to avoid repeated UTF-8 decoding */
+    indexToString = new Map();
+    /**
+     * Create a new StringTable.
+     */
+    constructor(opts) {
+        this.bytes = opts?.bytes
+            ? RTA.from(Uint8Array, opts.bytes)
+            : new RTA(Uint8Array);
+        this.start = opts?.start
+            ? RTA.from(Uint32Array, opts.start)
+            : new RTA(Uint32Array);
+        this.count = opts?.count
+            ? RTA.from(Uint16Array, opts.count)
+            : new RTA(Uint16Array);
+    }
+    /**
+     * Get transferable objects for passing to another thread.
+     */
+    transferables() {
+        return {
+            bytes: this.bytes.array.buffer,
+            start: this.start.array.buffer,
+            count: this.count.array.buffer,
+        };
+    }
+    /**
+     * Add a string to the table and return its index.
+     */
+    add(str) {
+        const existingIndex = this.stringToIndex.get(str);
+        if (existingIndex !== undefined)
+            return existingIndex;
+        const startIndex = this.start.length;
+        const encoded = this.enc.encode(str);
+        this.start.push(this.bytes.length);
+        this.bytes.pushMany(encoded);
+        this.count.push(encoded.length);
+        this.stringToIndex.set(str, startIndex);
+        return startIndex;
+    }
+    /**
+     * Decode all the strings in a primitive block and add them to the string table.
+     * Return a mapping of block index -> string table index
+     */
+    createBlockIndexMap(blockStringtable) {
+        const index = new Uint32Array(blockStringtable.length);
+        for (let i = 0; i < blockStringtable.length; i++) {
+            const bytesString = blockStringtable[i];
+            const str = this.dec.decode(bytesString);
+            const existingIndex = this.stringToIndex.get(str);
+            if (existingIndex !== undefined) {
+                index[i] = existingIndex;
+                continue;
+            }
+            index[i] = this.add(str);
+        }
+        return index;
+    }
+    /**
+     * Get a string by its index.
+     * Caches results to avoid repeated UTF-8 decoding.
+     */
+    get(index) {
+        const string = this.indexToString.get(index);
+        if (string)
+            return string;
+        const bytes = this.getBytes(index);
+        const tempBuffer = new ArrayBuffer(bytes.byteLength);
+        const tempBytes = new Uint8Array(tempBuffer);
+        tempBytes.set(bytes);
+        const decoded = this.dec.decode(tempBytes);
+        this.indexToString.set(index, decoded);
+        return decoded;
+    }
+    /**
+     * Get the raw UTF-8 bytes of a string.
+     * Returns a subarray view (not a copy).
+     */
+    getBytes(index) {
+        if (index < 0 || index >= this.length)
+            throw Error(`String index out of range: ${index}`);
+        const start = this.start.at(index);
+        const count = this.count.at(index);
+        return this.bytes.array.subarray(start, start + count);
+    }
+    /** Number of strings in the table. */
+    get length() {
+        return this.start.length;
+    }
+    /**
+     * Finalize the string table by compacting internal arrays.
+     *
+     * This releases unused buffer capacity and marks the reverse index as built
+     * (since all strings were added before this call).
+     */
+    buildIndex() {
+        this.bytes.compact();
+        this.start.compact();
+        this.count.compact();
+        this.reverseIndexBuilt = true;
+    }
+    /**
+     * Convert the string table to an OSM PBF string table.
+     */
+    toOsmPbfStringTable() {
+        const stringTable = [];
+        for (let i = 0; i < this.length; i++) {
+            stringTable.push(this.getBytes(i));
+        }
+        return stringTable;
+    }
+    /**
+     * Lazily build the reverse index (string → index).
+     * Decodes all strings once to populate the lookup map.
+     */
+    ensureReverseIndex() {
+        if (this.reverseIndexBuilt)
+            return;
+        // Decode all strings and populate the forward lookup map
+        for (let i = 0; i < this.length; i++) {
+            this.stringToIndex.set(this.get(i), i);
+        }
+        this.reverseIndexBuilt = true;
+    }
+    /**
+     * Find the index of a string.
+     */
+    find(str) {
+        const existing = this.stringToIndex.get(str);
+        if (existing !== undefined)
+            return existing;
+        this.ensureReverseIndex();
+        return this.stringToIndex.get(str) ?? -1;
+    }
+}
+//# sourceMappingURL=stringtable.js.map

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

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

package/dist/core/src/tags.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Tag storage and lookup.
+ *
+ * Stores key=value pairs using string table indices. Supports:
+ * 1. **Entity → Tags**: Retrieve tags for a given entity.
+ * 2. **Key → Entities**: Find entities with a specific tag key.
+ *
+ * @module
+ */
+import type { OsmTags } from "@osmix/shared/types";
+import StringTable from "./stringtable";
+import { type BufferType } from "./typed-arrays";
+/**
+ * Serializable state for worker transfer.
+ */
+export interface TagsTransferables<T extends BufferType = BufferType> {
+    /** Maps entity index → start position in tagKeys/tagVals. */
+    tagStart: T;
+    /** Maps entity index → number of tags. */
+    tagCount: T;
+    /** Flattened tag key indices. */
+    tagKeys: T;
+    /** Flattened tag value indices. */
+    tagVals: T;
+    /** Flattened entity indices for reverse key lookup. */
+    keyEntities: T;
+    /** Maps key index → start position in keyEntities. */
+    keyIndexStart: T;
+    /** Maps key index → count of entities with that key. */
+    keyIndexCount: T;
+}
+/**
+ * Bidirectional tag storage.
+ *
+ * Limits: Max 255 tags per entity.
+ * Note: String indices reference a shared `StringTable`.
+ */
+export declare class Tags {
+    /** Reference to the shared string table for key/value storage */
+    private stringTable;
+    /** Maps entity index → start position in tagKeys/tagVals */
+    private tagStart;
+    /** Maps entity index → number of tags (max 255) */
+    private tagCount;
+    /** All tag key string indices, concatenated */
+    private tagKeys;
+    /** All tag value string indices, concatenated (parallel to tagKeys) */
+    private tagVals;
+    /**
+     * Flattened array of entity indices that have each tag key.
+     * Indexed via keyIndexStart and keyIndexCount.
+     */
+    private keyEntities;
+    /** Maps key string index → start position in keyEntities */
+    private keyIndexStart;
+    /** Maps key string index → count of entities with that key */
+    private keyIndexCount;
+    /**
+     * Temporary map used during ingestion to collect entity indices per key.
+     * Converted to flat arrays during buildIndex() and then cleared.
+     */
+    private keyEntityIndexBuilder;
+    /** Whether buildIndex() has been called */
+    private indexBuilt;
+    /**
+     * Create a new Tags index.
+     */
+    constructor(stringTable: StringTable, transferables?: TagsTransferables);
+    /**
+     * Add tags to an entity.
+     */
+    addTags(index: number, tags?: OsmTags): [number[], number[]];
+    /**
+     * Add tags to an entity using key and value indexes.
+     */
+    addTagKeysAndValues(index: number, keys: number[], values: number[]): void;
+    /**
+     * Finalize the tag index.
+     *
+     * Compacts arrays and builds the reverse key→entity index.
+     * Must be called before `hasKey()`.
+     */
+    buildIndex(): void;
+    /**
+     * Check if the index is built and ready for use.
+     */
+    isReady(): boolean;
+    /**
+     * Get the number of tags for an entity.
+     */
+    cardinality(index: number): number;
+    /**
+     * Get the tags for an entity.
+     */
+    getTags(index: number): OsmTags | undefined;
+    /**
+     * Get tags from key and value indexes.
+     */
+    getTagsFromIndices(keys: number[], values: number[]): OsmTags;
+    /**
+     * Find the index of a tag key.
+     */
+    find(key: string): number;
+    /**
+     * Get all entity indexes that have a specific tag key.
+     */
+    hasKey(keyIndex: number): number[];
+    /**
+     * Create a unique composite index for a key=value pair.
+     * Uses row-major indexing: `key * width + val`.
+     */
+    kvToIndex(key: number, val: number): number;
+    /**
+     * Get transferable objects for passing to another thread.
+     */
+    transferables(): TagsTransferables;
+    /**
+     * Get the approximate memory requirements for a given number of tags in bytes.
+     */
+    static getBytesRequired(count: number): number;
+    /**
+     * Reconstruct a Tags index from transferable objects.
+     */
+    static fromTransferables(stringTable: StringTable, transferables: TagsTransferables): Tags;
+}
+//# sourceMappingURL=tags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../../src/tags.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,WAAW,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,KAAK,UAAU,EAA+B,MAAM,gBAAgB,CAAA;AAE7E;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IACnE,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,CAAA;IACX,0CAA0C;IAC1C,QAAQ,EAAE,CAAC,CAAA;IACX,iCAAiC;IACjC,OAAO,EAAE,CAAC,CAAA;IACV,mCAAmC;IACnC,OAAO,EAAE,CAAC,CAAA;IAEV,uDAAuD;IACvD,WAAW,EAAE,CAAC,CAAA;IACd,sDAAsD;IACtD,aAAa,EAAE,CAAC,CAAA;IAChB,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAA;CAChB;AAED;;;;;GAKG;AACH,qBAAa,IAAI;IAChB,iEAAiE;IACjE,OAAO,CAAC,WAAW,CAAiC;IAGpD,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAkB;IAClC,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAiB;IACjC,+CAA+C;IAC/C,OAAO,CAAC,OAAO,CAAkB;IACjC,uEAAuE;IACvE,OAAO,CAAC,OAAO,CAAkB;IAGjC;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAkB;IAErC,4DAA4D;IAC5D,OAAO,CAAC,aAAa,CAAkB;IACvC,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAAkB;IAEvC;;;OAGG;IACH,OAAO,CAAC,qBAAqB,CAA8B;IAE3D,2CAA2C;IAC3C,OAAO,CAAC,UAAU,CAAQ;IAE1B;;OAEG;gBACS,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,iBAAiB;IAsBvE;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC;IAgB5D;;OAEG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;IAgBnE;;;;;OAKG;IACH,UAAU;IAoBV;;OAEG;IACH,OAAO;IAIP;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIlC;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAuB3C;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;IAY7D;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIzB;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAOlC;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAKlC;;OAEG;IACH,aAAa,IAAI,iBAAiB;IAYlC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM;IAOrC;;OAEG;IACH,MAAM,CAAC,iBAAiB,CACvB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,iBAAiB;CAMjC"}

package/dist/core/src/tags.js

@@ -0,0 +1,228 @@
+/**
+ * Tag storage and lookup.
+ *
+ * Stores key=value pairs using string table indices. Supports:
+ * 1. **Entity → Tags**: Retrieve tags for a given entity.
+ * 2. **Key → Entities**: Find entities with a specific tag key.
+ *
+ * @module
+ */
+import StringTable from "./stringtable";
+import { ResizeableTypedArray as RTA } from "./typed-arrays";
+/**
+ * Bidirectional tag storage.
+ *
+ * Limits: Max 255 tags per entity.
+ * Note: String indices reference a shared `StringTable`.
+ */
+export class Tags {
+    /** Reference to the shared string table for key/value storage */
+    stringTable = new StringTable();
+    // ─── Entity → Tag Lookup ───────────────────────────────────────────────────
+    /** Maps entity index → start position in tagKeys/tagVals */
+    tagStart;
+    /** Maps entity index → number of tags (max 255) */
+    tagCount;
+    /** All tag key string indices, concatenated */
+    tagKeys;
+    /** All tag value string indices, concatenated (parallel to tagKeys) */
+    tagVals;
+    // ─── Key → Entity Reverse Lookup ───────────────────────────────────────────
+    /**
+     * Flattened array of entity indices that have each tag key.
+     * Indexed via keyIndexStart and keyIndexCount.
+     */
+    keyEntities;
+    /** Maps key string index → start position in keyEntities */
+    keyIndexStart;
+    /** Maps key string index → count of entities with that key */
+    keyIndexCount;
+    /**
+     * Temporary map used during ingestion to collect entity indices per key.
+     * Converted to flat arrays during buildIndex() and then cleared.
+     */
+    keyEntityIndexBuilder = new Map();
+    /** Whether buildIndex() has been called */
+    indexBuilt = false;
+    /**
+     * Create a new Tags index.
+     */
+    constructor(stringTable, transferables) {
+        this.stringTable = stringTable;
+        if (transferables) {
+            this.tagStart = RTA.from(Uint32Array, transferables.tagStart);
+            this.tagCount = RTA.from(Uint8Array, transferables.tagCount);
+            this.tagKeys = RTA.from(Uint32Array, transferables.tagKeys);
+            this.tagVals = RTA.from(Uint32Array, transferables.tagVals);
+            this.keyEntities = RTA.from(Uint32Array, transferables.keyEntities);
+            this.keyIndexStart = RTA.from(Uint32Array, transferables.keyIndexStart);
+            this.keyIndexCount = RTA.from(Uint32Array, transferables.keyIndexCount);
+            this.indexBuilt = true;
+        }
+        else {
+            this.tagStart = new RTA(Uint32Array);
+            this.tagCount = new RTA(Uint8Array);
+            this.tagKeys = new RTA(Uint32Array);
+            this.tagVals = new RTA(Uint32Array);
+            this.keyEntities = new RTA(Uint32Array);
+            this.keyIndexStart = new RTA(Uint32Array);
+            this.keyIndexCount = new RTA(Uint32Array);
+        }
+    }
+    /**
+     * Add tags to an entity.
+     */
+    addTags(index, tags) {
+        const tagKeys = [];
+        const tagValues = [];
+        if (tags) {
+            for (const [key, value] of Object.entries(tags)) {
+                tagKeys.push(this.stringTable.add(key));
+                tagValues.push(this.stringTable.add(String(value)));
+            }
+        }
+        this.addTagKeysAndValues(index, tagKeys, tagValues);
+        return [tagKeys, tagValues];
+    }
+    /**
+     * Add tags to an entity using key and value indexes.
+     */
+    addTagKeysAndValues(index, keys, values) {
+        this.tagStart.set(index, this.tagKeys.length);
+        this.tagCount.set(index, keys.length);
+        this.tagKeys.pushMany(keys);
+        this.tagVals.pushMany(values);
+        keys.forEach((key) => {
+            const keyEntities = this.keyEntityIndexBuilder.get(key);
+            if (keyEntities) {
+                keyEntities.push(index);
+            }
+            else {
+                this.keyEntityIndexBuilder.set(key, [index]);
+            }
+        });
+    }
+    /**
+     * Finalize the tag index.
+     *
+     * Compacts arrays and builds the reverse key→entity index.
+     * Must be called before `hasKey()`.
+     */
+    buildIndex() {
+        this.tagStart.compact();
+        this.tagCount.compact();
+        this.tagKeys.compact();
+        this.tagVals.compact();
+        // Convert the builder map to flat arrays for the reverse index
+        for (const [keyIndex, entityIndexes] of this.keyEntityIndexBuilder) {
+            this.keyIndexStart.set(keyIndex, this.keyEntities.length);
+            this.keyIndexCount.set(keyIndex, entityIndexes.length);
+            this.keyEntities.pushMany(entityIndexes);
+        }
+        this.keyIndexStart.compact();
+        this.keyIndexCount.compact();
+        this.keyEntityIndexBuilder.clear();
+        this.indexBuilt = true;
+    }
+    /**
+     * Check if the index is built and ready for use.
+     */
+    isReady() {
+        return this.indexBuilt;
+    }
+    /**
+     * Get the number of tags for an entity.
+     */
+    cardinality(index) {
+        return this.tagCount.at(index) ?? 0;
+    }
+    /**
+     * Get the tags for an entity.
+     */
+    getTags(index) {
+        const tagCount = this.tagCount.at(index) ?? 0;
+        if (tagCount === 0)
+            return;
+        const tagStart = this.tagStart.at(index) ?? 0;
+        const tagKeyIndexes = this.tagKeys.array.slice(tagStart, tagStart + tagCount);
+        const tagValIndexes = this.tagVals.array.slice(tagStart, tagStart + tagCount);
+        const tags = {};
+        for (let i = 0; i < tagCount; i++) {
+            const keyIndex = tagKeyIndexes[i];
+            const valIndex = tagValIndexes[i];
+            if (keyIndex === undefined || valIndex === undefined)
+                throw Error("Tag key or value not found");
+            tags[this.stringTable.get(keyIndex)] = this.stringTable.get(valIndex);
+        }
+        return tags;
+    }
+    /**
+     * Get tags from key and value indexes.
+     */
+    getTagsFromIndices(keys, values) {
+        const tags = {};
+        for (let i = 0; i < keys.length; i++) {
+            const keyIndex = keys[i];
+            const valIndex = values[i];
+            if (keyIndex === undefined || valIndex === undefined)
+                throw Error("Tag key or value not found");
+            tags[this.stringTable.get(keyIndex)] = this.stringTable.get(valIndex);
+        }
+        return tags;
+    }
+    /**
+     * Find the index of a tag key.
+     */
+    find(key) {
+        return this.stringTable.find(key);
+    }
+    /**
+     * Get all entity indexes that have a specific tag key.
+     */
+    hasKey(keyIndex) {
+        if (keyIndex < 0)
+            return [];
+        const start = this.keyIndexStart.at(keyIndex) ?? 0;
+        const count = this.keyIndexCount.at(keyIndex) ?? 0;
+        return Array.from(this.keyEntities.array.subarray(start, start + count));
+    }
+    /**
+     * Create a unique composite index for a key=value pair.
+     * Uses row-major indexing: `key * width + val`.
+     */
+    kvToIndex(key, val) {
+        const width = this.stringTable.length;
+        return key * width + val;
+    }
+    /**
+     * Get transferable objects for passing to another thread.
+     */
+    transferables() {
+        return {
+            tagStart: this.tagStart.array.buffer,
+            tagCount: this.tagCount.array.buffer,
+            tagKeys: this.tagKeys.array.buffer,
+            tagVals: this.tagVals.array.buffer,
+            keyEntities: this.keyEntities.array.buffer,
+            keyIndexStart: this.keyIndexStart.array.buffer,
+            keyIndexCount: this.keyIndexCount.array.buffer,
+        };
+    }
+    /**
+     * Get the approximate memory requirements for a given number of tags in bytes.
+     */
+    static getBytesRequired(count) {
+        return (count * Uint32Array.BYTES_PER_ELEMENT + // tagStart
+            count * Uint8Array.BYTES_PER_ELEMENT // tagCount
+        );
+    }
+    /**
+     * Reconstruct a Tags index from transferable objects.
+     */
+    static fromTransferables(stringTable, transferables) {
+        const tagIndex = new Tags(stringTable, transferables);
+        tagIndex.indexBuilt = true;
+        return tagIndex;
+    }
+}
+//# sourceMappingURL=tags.js.map

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

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

package/dist/core/src/typed-arrays.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Resizable typed array utilities.
+ *
+ * Wraps typed arrays with automatic buffer expansion (ArrayList semantics).
+ * Uses SharedArrayBuffer (if available) for zero-copy worker transfer.
+ *
+ * @module
+ */
+/**
+ * Use SharedArrayBuffer if the runtime supports it, otherwise fall back to ArrayBuffer.
+ * SharedArrayBuffer enables zero-copy transfer between workers.
+ */
+export declare const BufferConstructor: SharedArrayBufferConstructor | ArrayBufferConstructor;
+/** The buffer type used by this runtime (SharedArrayBuffer or ArrayBuffer). */
+export type BufferType = InstanceType<typeof BufferConstructor>;
+/**
+ * Union of all standard typed array types.
+ * Generic over buffer type to preserve SharedArrayBuffer compatibility.
+ */
+export type TypedArray<B extends BufferType = BufferType> = Int8Array<B> | Uint8Array<B> | Uint8ClampedArray<B> | Int16Array<B> | Uint16Array<B> | Int32Array<B> | Uint32Array<B> | Float32Array<B> | Float64Array<B>;
+/**
+ * Constructor interface for typed arrays.
+ */
+export interface TypedArrayConstructor<T extends TypedArray<BufferType> = TypedArray<BufferType>> {
+    new (buffer: BufferType): T;
+    readonly BYTES_PER_ELEMENT: number;
+}
+/**
+ * Float64Array for storing OSM IDs.
+ *
+ * OSM IDs are 64-bit integers. JavaScript's number type (IEEE 754 double)
+ * can exactly represent integers up to 2^53, which covers all current OSM IDs.
+ * Float64Array allows typed array operations while maintaining precision.
+ */
+export declare const IdArrayType: Float64ArrayConstructor;
+/**
+ * Uint32Array for storing array indices.
+ *
+ * Internal indices into typed arrays never exceed 2^32 elements,
+ * so Uint32Array provides the best balance of range and memory efficiency.
+ */
+export declare const IndexArrayType: Uint32ArrayConstructor;
+/**
+ * Initial buffer size for ResizeableTypedArray.
+ * 1 MiB provides reasonable initial capacity while avoiding excessive memory allocation.
+ */
+export declare const DEFAULT_BUFFER_SIZE: number;
+/**
+ * Auto-expanding typed array wrapper.
+ *
+ * - `push()` appends elements, doubling buffer size as needed.
+ * - `compact()` shrinks buffer to fit data.
+ * - Supports growable SharedArrayBuffer and resizable ArrayBuffer.
+ */
+export declare class ResizeableTypedArray<TA extends TypedArray> {
+    /** The typed array constructor for this instance */
+    ArrayType: TypedArrayConstructor<TA>;
+    /** The current typed array view into the buffer */
+    array: TA;
+    /** Number of items actually stored (may be less than array.length) */
+    items: number;
+    /** The underlying ArrayBuffer or SharedArrayBuffer */
+    buffer: BufferType;
+    /** Current buffer size in bytes */
+    bufferSize: number;
+    /** Maximum byte length for growable buffers */
+    maxByteLength: number;
+    /** Buffer constructor (SharedArrayBuffer or ArrayBuffer) */
+    BC: SharedArrayBufferConstructor | ArrayBufferConstructor;
+    /**
+     * Reconstruct a ResizeableTypedArray from an existing buffer.
+     *
+     * Used after transferring buffers between workers. The resulting array
+     * is considered "compacted" with items = array.length.
+     *
+     * @param ArrayType - The typed array constructor.
+     * @param buffer - The existing buffer to wrap.
+     * @returns A new ResizeableTypedArray wrapping the buffer.
+     */
+    static from<TA extends TypedArray>(ArrayType: TypedArrayConstructor<TA>, buffer: BufferType): ResizeableTypedArray<TA>;
+    /**
+     * Create a new ResizeableTypedArray with an empty buffer.
+     *
+     * @param ArrayType - The typed array constructor (e.g., Float64Array).
+     * @param BC - Buffer constructor to use (defaults to SharedArrayBuffer if available).
+     */
+    constructor(ArrayType: TypedArrayConstructor<TA>, BC?: SharedArrayBufferConstructor | ArrayBufferConstructor);
+    /**
+     * Iterate over the array values.
+     */
+    [Symbol.iterator](): ArrayIterator<number>;
+    /**
+     * Double the buffer capacity.
+     * Uses in-place grow/resize if supported, otherwise allocates new buffer and copies.
+     */
+    expandArray(): void;
+    /**
+     * Get the value at an index. Handles negative indices.
+     */
+    at(index: number): number;
+    /**
+     * Get a slice of the array.
+     */
+    slice(start: number, end: number): Int8Array<ArrayBuffer> | Uint8Array<ArrayBuffer> | Uint8ClampedArray<ArrayBuffer> | Int16Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Int32Array<ArrayBuffer> | Uint32Array<ArrayBuffer> | Float32Array<ArrayBuffer> | Float64Array<ArrayBuffer>;
+    get length(): number;
+    /**
+     * Push a value to the end of the array.
+     */
+    push(value: number): number;
+    /**
+     * Set a value at a specific index. Expands array if needed.
+     */
+    set(index: number, value: number): void;
+    /**
+     * Push multiple values to the end of the array.
+     */
+    pushMany(values: number[] | TypedArray): void;
+    /**
+     * Shrink the buffer to exactly fit stored items.
+     * Buffer becomes fixed-length after compacting.
+     */
+    compact(): TA;
+}
+//# sourceMappingURL=typed-arrays.d.ts.map

package/dist/core/src/typed-arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-arrays.d.ts","sourceRoot":"","sources":["../../../src/typed-arrays.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,uDAGa,CAAA;AAE3C,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE/D;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IACrD,SAAS,CAAC,CAAC,CAAC,GACZ,UAAU,CAAC,CAAC,CAAC,GACb,iBAAiB,CAAC,CAAC,CAAC,GACpB,UAAU,CAAC,CAAC,CAAC,GACb,WAAW,CAAC,CAAC,CAAC,GACd,UAAU,CAAC,CAAC,CAAC,GACb,WAAW,CAAC,CAAC,CAAC,GACd,YAAY,CAAC,CAAC,CAAC,GACf,YAAY,CAAC,CAAC,CAAC,CAAA;AAElB;;GAEG;AACH,MAAM,WAAW,qBAAqB,CACrC,CAAC,SAAS,UAAU,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC,UAAU,CAAC;IAEzD,KAAK,MAAM,EAAE,UAAU,GAAG,CAAC,CAAA;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,yBAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,wBAAc,CAAA;AAEzC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAU,CAAA;AAE1C;;;;;;GAMG;AACH,qBAAa,oBAAoB,CAAC,EAAE,SAAS,UAAU;IACtD,oDAAoD;IACpD,SAAS,EAAE,qBAAqB,CAAC,EAAE,CAAC,CAAA;IACpC,mDAAmD;IACnD,KAAK,EAAE,EAAE,CAAA;IACT,sEAAsE;IACtE,KAAK,SAAI;IAET,sDAAsD;IACtD,MAAM,EAAE,UAAU,CAAA;IAClB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAA;IAErB,4DAA4D;IAC5D,EAAE,EAAE,4BAA4B,GAAG,sBAAsB,CAAA;IAEzD;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,UAAU,EAChC,SAAS,EAAE,qBAAqB,CAAC,EAAE,CAAC,EACpC,MAAM,EAAE,UAAU;IAYnB;;;;;OAKG;gBAEF,SAAS,EAAE,qBAAqB,CAAC,EAAE,CAAC,EACpC,EAAE,GACC,4BAA4B,GAC5B,sBAA0C;IAY9C;;OAEG;IACH,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC;IAI1C;;;OAGG;IACH,WAAW;IAwBX;;OAEG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IASzB;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;IAIhC,IAAI,MAAM,WAET;IAED;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAQ3B;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAShC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU;IAMtC;;;OAGG;IACH,OAAO;CAgBP"}