perf(ts): optimize full FSST dictionary decoding (#1499)

## Summary

Optimizes full FSST dictionary decoding without changing decoder
behavior.

The previous implementation accumulated decoded bytes in a JavaScript
number array and then copied them into a `Uint8Array`. The new
implementation:

1. Scans the compressed data to calculate the decoded size.
2. Allocates an exact-size `Uint8Array`.
3. Decodes directly into that array.

FSST decoding has a significant absolute cost only for unusually large
dictionaries. For typical dictionaries the cost is already very small,
but this change improves performance across every tested dictionary
size.

This PR intentionally covers only full dictionary decoding, which
benefits the current MapLibre GL JS access pattern.

## Benchmarks

The benchmark uses three complete MLT fixtures with typical, large, and
xlarge FSST dictionaries. Results were measured with Node 24.11.1.

| Dictionary | Compressed | Decoded | Before | After | Speedup |
| --- | ---: | ---: | ---: | ---: | ---: |
| Typical | 4,670 B | 8,712 B | 0.0543 ms | 0.0273 ms | 1.99× |
| Large | 46,300 B | 78,929 B | 1.4007 ms | 0.4116 ms | 3.40× |
| xlarge | 4,545,692 B | 8,360,752 B | 144.85 ms | 32.42 ms | 4.47× |

Run the benchmark with:

```sh
cd ts
npm ci
npm run bench:fsst
```

The xlarge fixture is an OpenStreetMap-derived tile. Its provenance and
license are documented alongside the fixture.

## AI assistance
This PR was developed with assistance from OpenAI Codex. The
implementation was reviewed, benchmarked, and tested by me.

Author: candux

test/fixtures/osm/README.md

@@ -0,0 +1,5 @@
+# OpenStreetMap fixtures
+
+`xlarge.mlt` is tile `4/8/5` from an OpenStreetMap-derived hiking tileset. It is included to benchmark an unusually large shared FSST dictionary.
+
+The fixture contains information from [OpenStreetMap](https://www.openstreetmap.org/copyright), which is available under the [Open Data Commons Open Database License](https://opendatacommons.org/licenses/odbl/).

test/fixtures/osm/xlarge.mlt

@@ -41,4 +41,4 @@ test: install
 
 # Run benchmark
 bench: install
-    echo "TODO: Add js benchmark command"
+    npm run bench

ts/mod.just

@@ -15,6 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "bench": "vitest bench --run src",
     "test": "vitest run --coverage --coverage.reportOnFailure",
     "lint": "eslint",
     "format": "biome format --write ./src",

ts/package.json

@@ -0,0 +1,74 @@
+import { readFileSync } from "node:fs";
+import { bench, describe } from "vitest";
+import decodeTile from "../mltDecoder";
+import { StringFsstDictionaryVector } from "../vector/fsst-dictionary/stringFsstDictionaryVector";
+import { decodeFsst } from "./fsstDecoder";
+
+type FsstDictionary = {
+    symbols: Uint8Array;
+    symbolLengths: Uint32Array;
+    compressed: Uint8Array;
+    decodedLength: number;
+};
+
+let checksum = 0;
+
+function loadDictionary(tilePath: string, tableName: string, columnName: string): FsstDictionary {
+    const tileData = readFileSync(new URL(tilePath, import.meta.url));
+    const featureTable = decodeTile(new Uint8Array(tileData.buffer, tileData.byteOffset, tileData.byteLength)).find(
+        (table) => table.name === tableName,
+    );
+    const dictionaryVector = featureTable?.propertyVectors.find((vector) => vector?.name === columnName);
+    if (!(dictionaryVector instanceof StringFsstDictionaryVector)) {
+        throw new Error(`FSST benchmark dictionary ${tableName}.${columnName} not found`);
+    }
+    // Access internal buffers so this benchmark isolates decodeFsst instead of measuring cached vector access.
+    const {
+        dataBuffer: compressed,
+        symbolOffsetBuffer: symbolOffsets,
+        symbolTableBuffer: symbols,
+        offsetBuffer,
+    } = dictionaryVector as unknown as {
+        dataBuffer: Uint8Array;
+        symbolOffsetBuffer: Uint32Array;
+        symbolTableBuffer: Uint8Array;
+        offsetBuffer: Uint32Array;
+    };
+    const symbolLengths = new Uint32Array(symbolOffsets.length - 1);
+    for (let i = 0; i < symbolLengths.length; i++) {
+        symbolLengths[i] = symbolOffsets[i + 1] - symbolOffsets[i];
+    }
+    return {
+        symbols,
+        symbolLengths,
+        compressed,
+        decodedLength: offsetBuffer[offsetBuffer.length - 1],
+    };
+}
+
+function consume(decoded: Uint8Array): void {
+    checksum = (checksum + decoded[0] + decoded[decoded.length >> 1] + decoded[decoded.length - 1]) | 0;
+}
+
+describe("decode whole FSST dictionary", () => {
+    const typical = loadDictionary("../../../test/expected/tag0x01/amazon_here/5_16_10.mlt", "pois", "name");
+    bench(
+        `typical: ${typical.compressed.length} compressed bytes to ${typical.decodedLength} decoded bytes`,
+        () => consume(decodeFsst(typical.symbols, typical.symbolLengths, typical.compressed)),
+        { warmupTime: 500, time: 5_000 },
+    );
+
+    const large = loadDictionary("../../../test/expected/tag0x01/omt/14_8299_10748.mlt", "poi", "name");
+    bench(
+        `large: ${large.compressed.length} compressed bytes to ${large.decodedLength} decoded bytes`,
+        () => consume(decodeFsst(large.symbols, large.symbolLengths, large.compressed)),
+        { warmupTime: 500, time: 5_000 },
+    );
+
+    const xlarge = loadDictionary("../../../test/fixtures/osm/xlarge.mlt", "hiking", "name");
+    bench(
+        `xlarge: ${xlarge.compressed.length} compressed bytes to ${xlarge.decodedLength} decoded bytes`,
+        () => consume(decodeFsst(xlarge.symbols, xlarge.symbolLengths, xlarge.compressed)),
+        { warmupTime: 500, time: 5_000 },
+    );
+});

ts/src/decoding/fsstDecoder.bench.ts

@@ -42,6 +42,14 @@ describe("decodeFsst", () => {
             expect(new TextDecoder().decode(decoded)).toBe(inputString);
         });
 
+        it("should handle consecutive escaped bytes", () => {
+            const symbols = new Uint8Array([65]);
+            const symbolLengths = new Uint32Array([1]);
+            const encoded = new Uint8Array([255, 1, 255, 2, 0, 255, 3]);
+
+            expect(decodeFsst(symbols, symbolLengths, encoded)).toEqual(new Uint8Array([1, 2, 65, 3]));
+        });
+
         it("should handle string with all matching symbols", () => {
             const inputString = "AAAA";
             const originalBytes = textEncoder.encode(inputString);

ts/src/decoding/fsstDecoder.spec.ts

@@ -1,3 +1,25 @@
+/**
+ * Calculates the exact output size before decoding. This allows one final
+ * `Uint8Array` allocation and avoids growing a JavaScript number array and
+ * copying it into a typed array afterward. Traversing the compressed data
+ * twice is always worthwhile here because it avoids those larger temporary
+ * allocations.
+ */
+function getDecodedLength(symbolLengths: Uint32Array, compressedData: Uint8Array): number {
+    let decodedLength = 0;
+    for (let i = 0; i < compressedData.length; i++) {
+        const symbolIndex = compressedData[i];
+        if (symbolIndex === 255) {
+            decodedLength++;
+            i++; // Skip the literal byte following the escape marker.
+        } else {
+            decodedLength += symbolLengths[symbolIndex];
+        }
+    }
+
+    return decodedLength;
+}
+
 /**
  * Decode FSST compressed data
  *
@@ -6,26 +28,28 @@
  * @param compressedData    FSST Compressed data, where each entry is an index to the symbols array
  * @returns                 Decoded data as Uint8Array
  */
-//TODO: improve -> quick and dirty implementation
 export function decodeFsst(symbols: Uint8Array, symbolLengths: Uint32Array, compressedData: Uint8Array): Uint8Array {
-    //TODO: use typed array directly
-    const decodedData: number[] = [];
-    const symbolOffsets: number[] = new Array(symbolLengths.length).fill(0);
+    const symbolOffsets = new Uint32Array(symbolLengths.length);
 
     for (let i = 1; i < symbolLengths.length; i++) {
         symbolOffsets[i] = symbolOffsets[i - 1] + symbolLengths[i - 1];
     }
 
+    const decodedData = new Uint8Array(getDecodedLength(symbolLengths, compressedData));
+    let decodedOffset = 0;
     for (let i = 0; i < compressedData.length; i++) {
-        if (compressedData[i] === 255) {
-            decodedData.push(compressedData[++i]);
+        const symbolIndex = compressedData[i];
+        if (symbolIndex === 255) {
+            i++;
+            decodedData[decodedOffset++] = compressedData[i];
         } else {
-            const symbolLength = symbolLengths[compressedData[i]];
-            const symbolOffset = symbolOffsets[compressedData[i]];
-            for (let j = 0; j < symbolLength; j++) {
-                decodedData.push(symbols[symbolOffset + j]);
+            let symbolLength = symbolLengths[symbolIndex];
+            let symbolOffset = symbolOffsets[symbolIndex];
+            while (symbolLength-- > 0) {
+                decodedData[decodedOffset++] = symbols[symbolOffset++];
             }
         }
     }
-    return new Uint8Array(decodedData);
+
+    return decodedData;
 }

ts/src/decoding/fsstDecoder.ts

@@ -23,5 +23,6 @@
   "exclude": [
     "node_modules",
     "**/*.spec.ts",
+    "**/*.bench.ts",
   ]
 }