fix(ts): return undefined for empty/incomplete string columns (#1469)

CommanderStorm · web-flow · commit fc7ff6c92e00 · 2026-07-23T13:47:40.000Z
Split from #1462. - `decodeString` now returns `undefined` for empty columns, and the dictionary/FSST decoders throw a named error when a column's companion streams are incomplete instead of constructing a half-built vector. - `propertyDecoder` keeps its existing `null` contract via `?? null`. Adds coverage for the empty/incomplete cases
diff --git a/ts/src/decoding/propertyDecoder.ts b/ts/src/decoding/propertyDecoder.ts
@@ -36,7 +36,7 @@ export function decodePropertyColumn(
     numStreams: number,
     numFeatures: number,
     propertyColumnNames?: Set<string>,
-): Vector | Vector[] {
+): Vector | Vector[] | null {
     if (columnMetadata.type === "scalarType") {
         if (propertyColumnNames && !propertyColumnNames.has(columnMetadata.name)) {
             skipColumn(numStreams, data, offset);
@@ -68,7 +68,7 @@ function decodeScalarPropertyColumn(
     column: ScalarColumn,
     columnMetadata: Column,
 ) {
-    let nullabilityBuffer: BitVector = null;
+    let nullabilityBuffer: BitVector | undefined;
     if (numStreams === 0) {
         return null;
     }
@@ -91,7 +91,7 @@ function decodeScalarPropertyColumn(
         case ScalarType.STRING: {
             // In embedded format: numStreams includes nullability stream if column is nullable
             const stringDataStreams = columnMetadata.nullable ? numStreams - 1 : numStreams;
-            return decodeString(columnMetadata.name, data, offset, stringDataStreams, nullabilityBuffer);
+            return decodeString(columnMetadata.name, data, offset, stringDataStreams, nullabilityBuffer) ?? null;
         }
         case ScalarType.BOOLEAN:
             return decodeBooleanColumn(data, offset, columnMetadata, numFeatures, sizeOrNullabilityBuffer);
diff --git a/ts/src/decoding/stringDecoder.spec.ts b/ts/src/decoding/stringDecoder.spec.ts
@@ -13,9 +13,10 @@ import {
 import { StringFlatVector } from "../vector/flat/stringFlatVector";
 import { StringDictionaryVector } from "../vector/dictionary/stringDictionaryVector";
 import { StringFsstDictionaryVector } from "../vector/fsst-dictionary/stringFsstDictionaryVector";
-import { ScalarType } from "../metadata/tileset/tilesetMetadata";
+import { type Column, ColumnScope, ScalarType } from "../metadata/tileset/tilesetMetadata";
 import { PhysicalStreamType } from "../metadata/tile/physicalStreamType";
 import { LengthType } from "../metadata/tile/lengthType";
+import { DictionaryType } from "../metadata/tile/dictionaryType";
 
 describe("decodeString - Plain String Decoder", () => {
     it("should decode plain strings with simple ASCII values", () => {
@@ -175,20 +176,20 @@ describe("decodeString - FSST Dictionary Decoder (Basic Coverage)", () => {
 });
 
 describe("decodeString - Empty Column Edge Cases", () => {
-    it("should handle empty column with numStreams = 0 (returns null)", () => {
+    it("should handle empty column with numStreams = 0 (returns undefined)", () => {
         const fullStream = new Uint8Array([]);
         const offset = new IntWrapper(0);
         const result = decodeString("testColumn", fullStream, offset, 0);
-        expect(result).toBeNull();
+        expect(result).toBeUndefined();
     });
 
-    it("should handle column with all zero-length streams (returns null)", () => {
+    it("should handle column with all zero-length streams (returns undefined)", () => {
         const emptyStream = createStream(PhysicalStreamType.LENGTH, new Uint8Array([]), {
             logical: { lengthType: LengthType.VAR_BINARY },
         });
         const offset = new IntWrapper(0);
         const result = decodeString("testColumn", emptyStream, offset, 1);
-        expect(result).toBeNull();
+        expect(result).toBeUndefined();
     });
 
     it("should handle single value plain string column", () => {
@@ -210,6 +211,28 @@ describe("decodeString - Empty Column Edge Cases", () => {
     });
 });
 
+describe("decodeString - incomplete column streams throw", () => {
+    it("throws when an FSST symbol table is present but its companion streams are missing", () => {
+        const symbolTableOnly = createStream(PhysicalStreamType.DATA, new Uint8Array([1, 2, 3]), {
+            logical: { dictionaryType: DictionaryType.FSST },
+        });
+        const offset = new IntWrapper(0);
+        expect(() => decodeString("fsstColumn", symbolTableOnly, offset, 1)).toThrow(
+            'Incomplete FSST dictionary string column "fsstColumn"',
+        );
+    });
+
+    it("throws when a dictionary stream is present but offsets/lengths are missing", () => {
+        const dictionaryDataOnly = createStream(PhysicalStreamType.DATA, new Uint8Array([1, 2, 3]), {
+            logical: { dictionaryType: DictionaryType.SINGLE },
+        });
+        const offset = new IntWrapper(0);
+        expect(() => decodeString("dictColumn", dictionaryDataOnly, offset, 1)).toThrow(
+            'Incomplete dictionary string column "dictColumn"',
+        );
+    });
+});
+
 describe("decodeString - Integration Tests", () => {
     it("should correctly track offset through multiple streams", () => {
         const strings = ["hello", "world"];
@@ -503,6 +526,46 @@ describe("decodeSharedDictionary", () => {
             }).toThrow("Currently only scalar string fields are implemented for a struct.");
         });
 
+        it("should throw when the column is not a complex (struct) column", () => {
+            const { lengthStream, dataStream } = encodeSharedDictionary(["value"]);
+            const complete = concatenateBuffers(lengthStream, dataStream);
+            const scalarColumn: Column = {
+                name: "notAStruct",
+                nullable: false,
+                columnScope: ColumnScope.FEATURE,
+                type: "scalarType",
+                scalarType: { longID: false, type: "physicalType", physicalType: ScalarType.STRING },
+            };
+
+            expect(() => {
+                decodeSharedDictionary(complete, new IntWrapper(0), scalarColumn);
+            }).toThrow("Shared dictionary column notAStruct must be a complex (struct) column.");
+        });
+
+        it("should throw when the shared dictionary offsets are missing", () => {
+            // Only the dictionary data stream is present, so the dictionary offset buffer is never decoded.
+            const { dataStream } = encodeSharedDictionary(["value"]);
+            const columnMetadata = createColumnMetadataForStruct("incomplete:", [{ name: "field1" }]);
+
+            expect(() => {
+                decodeSharedDictionary(dataStream, new IntWrapper(0), columnMetadata);
+            }).toThrow('Incomplete shared dictionary for column "incomplete:"');
+        });
+
+        it("should throw when an FSST shared dictionary is missing its symbol offsets", () => {
+            // Provide the dictionary length + data and the FSST symbol table, but omit the symbol length stream
+            // so the symbol offset buffer is never decoded.
+            const { lengthStream, dataStream, symbolDataStream } = encodeSharedDictionary(["value"], { useFsst: true });
+            if (!symbolDataStream) throw new Error("test setup: expected an FSST symbol data stream");
+            const fieldStreams = encodeStructField([0], [true]);
+            const complete = concatenateBuffers(lengthStream, symbolDataStream, dataStream, fieldStreams);
+            const columnMetadata = createColumnMetadataForStruct("fsst:", [{ name: "value" }]);
+
+            expect(() => {
+                decodeSharedDictionary(complete, new IntWrapper(0), columnMetadata);
+            }).toThrow('Incomplete shared FSST dictionary for column "fsst:value"');
+        });
+
         it("should throw error for mismatched nullability and numStreams", () => {
             const dictionaryStrings = ["value"];
             const { lengthStream, dataStream } = encodeSharedDictionary(dictionaryStrings);
diff --git a/ts/src/decoding/stringDecoder.ts b/ts/src/decoding/stringDecoder.ts
@@ -22,15 +22,15 @@ export function decodeString(
     offset: IntWrapper,
     numStreams: number,
     bitVector?: BitVector,
-): Vector {
-    let dictionaryLengthStream: Uint32Array = null;
-    let offsetStream: Uint32Array = null;
-    let dictionaryStream: Uint8Array = null;
-    let symbolLengthStream: Uint32Array = null;
-    let symbolTableStream: Uint8Array = null;
-    let nullabilityBuffer: BitVector = bitVector ?? null;
-    let plainLengthStream: Uint32Array = null;
-    let plainDataStream: Uint8Array = null;
+): Vector | undefined {
+    let dictionaryLengthStream: Uint32Array | undefined;
+    let offsetStream: Uint32Array | undefined;
+    let dictionaryStream: Uint8Array | undefined;
+    let symbolLengthStream: Uint32Array | undefined;
+    let symbolTableStream: Uint8Array | undefined;
+    let nullabilityBuffer: BitVector | undefined = bitVector;
+    let plainLengthStream: Uint32Array | undefined;
+    let plainDataStream: Uint8Array | undefined;
 
     for (let i = 0; i < numStreams; i++) {
         const streamMetadata = decodeStreamMetadata(data, offset);
@@ -91,15 +91,18 @@ export function decodeString(
 
 function decodeFsstDictionaryVector(
     name: string,
-    symbolTableStream: Uint8Array | null,
-    offsetStream: Uint32Array | null,
-    dictionaryLengthStream: Uint32Array | null,
-    dictionaryStream: Uint8Array | null,
-    symbolLengthStream: Uint32Array | null,
-    nullabilityBuffer: BitVector | null,
-): Vector | null {
+    symbolTableStream: Uint8Array | undefined,
+    offsetStream: Uint32Array | undefined,
+    dictionaryLengthStream: Uint32Array | undefined,
+    dictionaryStream: Uint8Array | undefined,
+    symbolLengthStream: Uint32Array | undefined,
+    nullabilityBuffer: BitVector | undefined,
+): Vector | undefined {
     if (!symbolTableStream) {
-        return null;
+        return undefined;
+    }
+    if (!offsetStream || !dictionaryLengthStream || !dictionaryStream || !symbolLengthStream) {
+        throw new Error(`Incomplete FSST dictionary string column "${name}"`);
     }
     return new StringFsstDictionaryVector(
         name,
@@ -114,13 +117,16 @@ function decodeFsstDictionaryVector(
 
 function decodeDictionaryVector(
     name: string,
-    dictionaryStream: Uint8Array | null,
-    offsetStream: Uint32Array | null,
-    dictionaryLengthStream: Uint32Array | null,
-    nullabilityBuffer: BitVector | null,
-): Vector | null {
+    dictionaryStream: Uint8Array | undefined,
+    offsetStream: Uint32Array | undefined,
+    dictionaryLengthStream: Uint32Array | undefined,
+    nullabilityBuffer: BitVector | undefined,
+): Vector | undefined {
     if (!dictionaryStream) {
-        return null;
+        return undefined;
+    }
+    if (!offsetStream || !dictionaryLengthStream) {
+        throw new Error(`Incomplete dictionary string column "${name}"`);
     }
     return nullabilityBuffer
         ? new StringDictionaryVector(name, offsetStream, dictionaryLengthStream, dictionaryStream, nullabilityBuffer)
@@ -129,13 +135,13 @@ function decodeDictionaryVector(
 
 function decodePlainStringVector(
     name: string,
-    plainLengthStream: Uint32Array | null,
-    plainDataStream: Uint8Array | null,
-    offsetStream: Uint32Array | null,
-    nullabilityBuffer: BitVector | null,
-): Vector | null {
+    plainLengthStream: Uint32Array | undefined,
+    plainDataStream: Uint8Array | undefined,
+    offsetStream: Uint32Array | undefined,
+    nullabilityBuffer: BitVector | undefined,
+): Vector | undefined {
     if (!plainLengthStream || !plainDataStream) {
-        return null;
+        return undefined;
     }
 
     if (offsetStream) {
@@ -174,10 +180,10 @@ export function decodeSharedDictionary(
     column: Column,
     propertyColumnNames?: Set<string>,
 ): Vector[] {
-    let dictionaryOffsetBuffer: Uint32Array = null;
-    let dictionaryBuffer: Uint8Array = null;
-    let symbolOffsetBuffer: Uint32Array = null;
-    let symbolTableBuffer: Uint8Array = null;
+    let dictionaryOffsetBuffer: Uint32Array | undefined;
+    let dictionaryBuffer: Uint8Array | undefined;
+    let symbolOffsetBuffer: Uint32Array | undefined;
+    let symbolTableBuffer: Uint8Array | undefined;
 
     let dictionaryStreamDecoded = false;
     while (!dictionaryStreamDecoded) {
@@ -205,6 +211,12 @@ export function decodeSharedDictionary(
         }
     }
 
+    if (column.type !== "complexType") {
+        throw new Error(`Shared dictionary column ${column.name} must be a complex (struct) column.`);
+    }
+    if (!dictionaryOffsetBuffer || !dictionaryBuffer) {
+        throw new Error(`Incomplete shared dictionary for column "${column.name}"`);
+    }
     const childFields = column.complexType.children;
     const stringDictionaryVectors = [];
     /** Shared by every FSST child-column vector in this SharedDict and populated on first access. */
@@ -255,24 +267,29 @@ export function decodeSharedDictionary(
             presentStreamBitVector,
         );
 
-        stringDictionaryVectors[i++] = symbolTableBuffer
-            ? new StringFsstDictionaryVector(
-                  columnName,
-                  offsetStream,
-                  dictionaryOffsetBuffer,
-                  dictionaryBuffer,
-                  symbolOffsetBuffer,
-                  symbolTableBuffer,
-                  presentStreamBitVector,
-                  sharedDictionaryCache,
-              )
-            : new StringDictionaryVector(
-                  columnName,
-                  offsetStream,
-                  dictionaryOffsetBuffer,
-                  dictionaryBuffer,
-                  presentStreamBitVector,
-              );
+        if (symbolTableBuffer) {
+            if (!symbolOffsetBuffer) {
+                throw new Error(`Incomplete shared FSST dictionary for column "${columnName}"`);
+            }
+            stringDictionaryVectors[i++] = new StringFsstDictionaryVector(
+                columnName,
+                offsetStream,
+                dictionaryOffsetBuffer,
+                dictionaryBuffer,
+                symbolOffsetBuffer,
+                symbolTableBuffer,
+                presentStreamBitVector,
+                sharedDictionaryCache,
+            );
+        } else {
+            stringDictionaryVectors[i++] = new StringDictionaryVector(
+                columnName,
+                offsetStream,
+                dictionaryOffsetBuffer,
+                dictionaryBuffer,
+                presentStreamBitVector,
+            );
+        }
     }
 
     return stringDictionaryVectors;
diff --git a/ts/src/vector/featureTable.spec.ts b/ts/src/vector/featureTable.spec.ts
@@ -0,0 +1,28 @@
+import { describe, it, expect } from "vitest";
+import FeatureTable from "./featureTable";
+import type Vector from "./vector";
+import { encodePointGeometryVector } from "../encoding/constGeometryVectorEncoder";
+
+const geometryVector = encodePointGeometryVector(1, 2);
+const propertyVector = (name: string): Vector => ({ name }) as unknown as Vector;
+
+describe("FeatureTable", () => {
+    it("throws when constructed without a layer name", () => {
+        expect(() => new FeatureTable("", geometryVector)).toThrow("Missing layer name");
+    });
+
+    it("returns an empty array when no property vectors are provided", () => {
+        const table = new FeatureTable("layer", geometryVector);
+        expect(table.propertyVectors).toEqual([]);
+    });
+
+    it("looks up property vectors by name and returns undefined for unknown names", () => {
+        const a = propertyVector("a");
+        const b = propertyVector("b");
+        const table = new FeatureTable("layer", geometryVector, undefined, [a, b]);
+
+        expect(table.getPropertyVector("a")).toBe(a);
+        expect(table.getPropertyVector("b")).toBe(b);
+        expect(table.getPropertyVector("missing")).toBeUndefined();
+    });
+});
diff --git a/ts/src/vector/featureTable.ts b/ts/src/vector/featureTable.ts
@@ -8,13 +8,13 @@ import { Int32ConstVector } from "./constant/int32ConstVector";
 import type { GpuVector } from "./geometry/gpuVector";
 
 export interface Feature {
-    id: number | bigint;
+    id: number | bigint | undefined;
     geometry: Geometry;
     properties: { [key: string]: unknown };
 }
 
 export default class FeatureTable {
-    private propertyVectorsMap: Map<string, Vector>;
+    private propertyVectorsMap?: Map<string, Vector>;
 
     constructor(
         private readonly _name: string,
@@ -32,7 +32,7 @@ export default class FeatureTable {
         return this._name;
     }
 
-    get idVector(): IdVector {
+    get idVector(): IdVector | undefined {
         return this._idVector;
     }
 
@@ -41,12 +41,12 @@ export default class FeatureTable {
     }
 
     get propertyVectors(): Vector[] {
-        return this._propertyVectors;
+        return this._propertyVectors ?? [];
     }
 
-    getPropertyVector(name: string): Vector {
+    getPropertyVector(name: string): Vector | undefined {
         if (!this.propertyVectorsMap) {
-            this.propertyVectorsMap = new Map(this._propertyVectors.map((vector) => [vector.name, vector]));
+            this.propertyVectorsMap = new Map(this.propertyVectors.map((vector) => [vector.name, vector]));
         }
 
         return this.propertyVectorsMap.get(name);
@@ -68,10 +68,12 @@ export default class FeatureTable {
         const geometries = this.geometryVector.getGeometries();
 
         for (let i = 0; i < this.numFeatures; i++) {
-            let id;
+            let id: number | bigint | undefined;
             if (this.idVector) {
                 const idValue = this.idVector.getValue(i);
-                id = this.containsMaxSafeIntegerValues(this.idVector) && idValue !== null ? Number(idValue) : idValue;
+                if (idValue !== null) {
+                    id = this.containsMaxSafeIntegerValues(this.idVector) ? Number(idValue) : idValue;
+                }
             }
             const geometry = {
                 coordinates: geometries[i],
diff --git a/ts/src/vector/fsst-dictionary/stringFsstDictionaryVector.ts b/ts/src/vector/fsst-dictionary/stringFsstDictionaryVector.ts
