perf(ts): cache decoded FSST shared dictionaries (#1512)

## Summary

MLT `SharedDict` columns store strings for multiple child property
columns in one dictionary corpus. When the corpus is FSST-compressed,
the TypeScript decoder exposes each child as a separate
`StringFsstDictionaryVector`.

Previously, the first access to each vector decoded the complete shared
FSST corpus again. Consumers such as MapLibre GL JS may access several
of these vectors while materializing properties for styles, filters, or
`queryRenderedFeatures()`.

This PR:

- Adds a benchmark for ordinary and shared FSST dictionary access.
- Creates one lazy decoded-dictionary cache per `SharedDict`.
- Shares that cache only between the vectors belonging to that group.
- Keeps ordinary FSST vectors on their existing direct decoding path.
- Ties the cache lifetime to the vectors and tile without a module-level
`WeakMap`.
- Tests that two vectors from one FSST `SharedDict` call `decodeFsst()`
only once.

#1505 makes this optimization slightly less relevant by preventing some
oversized shared-dictionary groups with little actual value overlap, but
beneficial `SharedDict` groups remain.

## Benchmark

The benchmark uses the real FSST dictionary from `14_8299_10748.mlt`,
which does not contain a `SharedDict`, to construct controlled
cold-access scenarios.

`xlarge.mlt` contains a real shared FSST dictionary, but reusing its
vectors would warm the cache after the first iteration. Re-decoding the
entire 5.4 MB tile for every iteration would make full-tile decoding
dominate the cache overhead being measured.

Node 24.11.1 results, averaging the mean latency from two runs:

| Cold access | Before | After | Result |
| --- | ---: | ---: | ---: |
| One ordinary FSST vector | 0.4117 ms | 0.4057 ms | No regression |
| Two ordinary FSST vectors | 0.8146 ms | 0.8192 ms | No regression |
| Two vectors from one `SharedDict` | 0.8048 ms | 0.4132 ms | 1.95×
faster |
| Five vectors from one `SharedDict` | 1.9826 ms | 0.4123 ms | 4.81×
faster |


## AI notice

This PR was developed with assistance from OpenAI Codex.

Author: candux

ts/src/decoding/stringDecoder.ts

@@ -11,7 +11,10 @@ import { decodeUnsignedInt32Stream, decodeLengthStreamToOffsetBuffer } from "./i
 import { type Column, ScalarType } from "../metadata/tileset/tilesetMetadata";
 import { decodeVarintInt32 } from "./integerDecodingUtils";
 import { decodeBooleanRle, skipColumn } from "./decodingUtils";
-import { StringFsstDictionaryVector } from "../vector/fsst-dictionary/stringFsstDictionaryVector";
+import {
+    type FsstDictionaryCache,
+    StringFsstDictionaryVector,
+} from "../vector/fsst-dictionary/stringFsstDictionaryVector";
 
 export function decodeString(
     name: string,
@@ -204,6 +207,8 @@ export function decodeSharedDictionary(
 
     const childFields = column.complexType.children;
     const stringDictionaryVectors = [];
+    /** Shared by every FSST child-column vector in this SharedDict and populated on first access. */
+    const sharedDictionaryCache: FsstDictionaryCache | undefined = symbolTableBuffer ? {} : undefined;
     let i = 0;
     for (const childField of childFields) {
         const numStreams = decodeVarintInt32(data, offset, 1)[0];
@@ -259,6 +264,7 @@ export function decodeSharedDictionary(
                   symbolOffsetBuffer,
                   symbolTableBuffer,
                   presentStreamBitVector,
+                  sharedDictionaryCache,
               )
             : new StringDictionaryVector(
                   columnName,

ts/src/vector/fsst-dictionary/stringFsstDictionaryVector.bench.ts

@@ -0,0 +1,95 @@
+import { readFileSync } from "node:fs";
+import { bench, describe } from "vitest";
+import decodeTile from "../../mltDecoder";
+import type BitVector from "../flat/bitVector";
+import { type FsstDictionaryCache, StringFsstDictionaryVector } from "./stringFsstDictionaryVector";
+
+type FsstVectorData = {
+    indexBuffer: Uint32Array;
+    offsetBuffer: Uint32Array;
+    dataBuffer: Uint8Array;
+    symbolOffsetBuffer: Uint32Array;
+    symbolTableBuffer: Uint8Array;
+    nullabilityBuffer: BitVector;
+};
+
+describe("cold FSST dictionary access", () => {
+    const tileData = readFileSync(new URL("../../../../test/expected/tag0x01/omt/14_8299_10748.mlt", import.meta.url));
+    const featureTable = decodeTile(new Uint8Array(tileData.buffer, tileData.byteOffset, tileData.byteLength)).find(
+        (table) => table.name === "poi",
+    );
+    const dictionaryVector = featureTable?.propertyVectors.find((vector) => vector?.name === "name");
+    if (!(dictionaryVector instanceof StringFsstDictionaryVector)) {
+        throw new Error("FSST cache benchmark dictionary poi.name not found");
+    }
+
+    // Access internal buffers to construct cold vectors around the same production dictionary.
+    const vectorData = dictionaryVector as unknown as FsstVectorData;
+    const valueIndex = Array.from({ length: dictionaryVector.size }, (_, index) => index).find((index) =>
+        dictionaryVector.has(index),
+    );
+    if (valueIndex === undefined) throw new Error("FSST cache benchmark dictionary contains no values");
+
+    let decodedLengthChecksum = 0;
+    const createVector = (dataBuffer: Uint8Array, sharedDictionaryCache?: FsstDictionaryCache) =>
+        new StringFsstDictionaryVector(
+            "name",
+            vectorData.indexBuffer,
+            vectorData.offsetBuffer,
+            dataBuffer,
+            vectorData.symbolOffsetBuffer,
+            vectorData.symbolTableBuffer,
+            vectorData.nullabilityBuffer,
+            sharedDictionaryCache,
+        );
+
+    bench(
+        "one ordinary FSST vector",
+        () => {
+            // A fresh buffer keeps every benchmark iteration cold.
+            const vector = createVector(vectorData.dataBuffer.slice());
+            decodedLengthChecksum = (decodedLengthChecksum + (vector.getValue(valueIndex)?.length ?? 0)) | 0;
+        },
+        { warmupTime: 500, time: 5_000 },
+    );
+
+    bench(
+        "two ordinary FSST vectors",
+        () => {
+            // Ordinary vectors do not receive a SharedDict cache, so both decode independently.
+            for (let i = 0; i < 2; i++) {
+                const vector = createVector(vectorData.dataBuffer.slice());
+                decodedLengthChecksum = (decodedLengthChecksum + (vector.getValue(valueIndex)?.length ?? 0)) | 0;
+            }
+        },
+        { warmupTime: 500, time: 5_000 },
+    );
+
+    bench(
+        "two vectors from one SharedDict",
+        () => {
+            // Vectors from one SharedDict receive the same cache, so the second reuses the first decoded dictionary.
+            const sharedData = vectorData.dataBuffer.slice();
+            const sharedDictionaryCache: FsstDictionaryCache = {};
+            for (let i = 0; i < 2; i++) {
+                const vector = createVector(sharedData, sharedDictionaryCache);
+                decodedLengthChecksum = (decodedLengthChecksum + (vector.getValue(valueIndex)?.length ?? 0)) | 0;
+            }
+        },
+        { warmupTime: 500, time: 5_000 },
+    );
+
+    bench(
+        "five vectors from one SharedDict",
+        () => {
+            // Vectors from one SharedDict receive the same cache, so four reuse the first decoded dictionary.
+            const sharedData = vectorData.dataBuffer.slice();
+            const sharedDictionaryCache: FsstDictionaryCache = {};
+            for (let i = 0; i < 5; i++) {
+                const vector = createVector(sharedData, sharedDictionaryCache);
+                decodedLengthChecksum = (decodedLengthChecksum + (vector.getValue(valueIndex)?.length ?? 0)) | 0;
+            }
+        },
+        { warmupTime: 500, time: 5_000 },
+    );
+});

ts/src/vector/fsst-dictionary/stringFsstDictionaryVector.ts

@@ -3,6 +3,12 @@ import type BitVector from "../flat/bitVector";
 import { decodeFsst } from "../../decoding/fsstDecoder";
 import { decodeString } from "../../decoding/decodingUtils";
 
+/** Mutable cache shared by the FSST child columns of one SharedDict. */
+export type FsstDictionaryCache = {
+    /** Undefined until one member of the SharedDict group decodes the dictionary on first access. */
+    decodedDictionary?: Uint8Array;
+};
+
 export class StringFsstDictionaryVector extends VariableSizeVector<Uint8Array, string> {
     // TODO: extend from StringVector
     private symbolLengthBuffer: Uint32Array;
@@ -16,18 +22,21 @@ export class StringFsstDictionaryVector extends VariableSizeVector<Uint8Array, s
         private readonly symbolOffsetBuffer: Uint32Array,
         private readonly symbolTableBuffer: Uint8Array,
         nullabilityBuffer: BitVector,
+        /** Cache shared by the FSST child columns of one SharedDict. */
+        private readonly sharedDictionaryCache?: FsstDictionaryCache,
     ) {
         super(name, offsetBuffer, dictionaryBuffer, nullabilityBuffer ?? indexBuffer.length);
     }
 
     protected getValueFromBuffer(index: number): string {
         if (this.decodedDictionary == null) {
-            if (this.symbolLengthBuffer == null) {
-                // TODO: change FsstEncoder to take offsets instead of length to get rid of this conversion
-                this.symbolLengthBuffer = this.offsetToLengthBuffer(this.symbolOffsetBuffer);
+            this.decodedDictionary = this.sharedDictionaryCache?.decodedDictionary;
+            if (this.decodedDictionary == null) {
+                this.decodedDictionary = this.decodeDictionary();
+                if (this.sharedDictionaryCache) {
+                    this.sharedDictionaryCache.decodedDictionary = this.decodedDictionary;
+                }
             }
-
-            this.decodedDictionary = decodeFsst(this.symbolTableBuffer, this.symbolLengthBuffer, this.dataBuffer);
         }
 
         const offset = this.indexBuffer[index];
@@ -36,6 +45,13 @@ export class StringFsstDictionaryVector extends VariableSizeVector<Uint8Array, s
         return decodeString(this.decodedDictionary, start, end);
     }
 
+    private decodeDictionary(): Uint8Array {
+        if (this.symbolLengthBuffer == null) {
+            this.symbolLengthBuffer = this.offsetToLengthBuffer(this.symbolOffsetBuffer);
+        }
+        return decodeFsst(this.symbolTableBuffer, this.symbolLengthBuffer, this.dataBuffer);
+    }
+
     // TODO: get rid of that conversion
     private offsetToLengthBuffer(offsetBuffer: Uint32Array): Uint32Array {
         const lengthBuffer = new Uint32Array(offsetBuffer.length - 1);