refactor(ts): construct Column/Field as discriminated unions (#1468)

CommanderStorm · web-flow · commit ec6808dab4ce · 2026-07-01T22:27:02.000+02:00
Split from #1462: build Column/Field as immutable discriminated-union literals (adds ColumnWithoutName) instead of `{} as Column` plus mutation.
diff --git a/ts/src/decoding/decodingTestUtils.ts b/ts/src/decoding/decodingTestUtils.ts
@@ -5,7 +5,7 @@ import { DictionaryType } from "../metadata/tile/dictionaryType";
 import { LengthType } from "../metadata/tile/lengthType";
 import { OffsetType } from "../metadata/tile/offsetType";
 import IntWrapper from "./intWrapper";
-import { type Column, type Field, ComplexType, ScalarType } from "../metadata/tileset/tilesetMetadata";
+import { type Column, type Field, ColumnScope, ComplexType, ScalarType } from "../metadata/tileset/tilesetMetadata";
 import { encodeBooleanRle, encodeStrings, createStringLengths } from "../encoding/encodingUtils";
 import { encodeVarintInt32Value, encodeVarintInt32 } from "../encoding/integerEncodingUtils";
 import type { RleEncodedStreamMetadata, StreamMetadata } from "../metadata/tile/streamMetadataDecoder";
@@ -74,6 +74,7 @@ export function createColumnMetadataForStruct(
     return {
         name: columnName,
         nullable: false,
+        columnScope: ColumnScope.FEATURE,
         complexType: {
             physicalType: ComplexType.STRUCT,
             children,
diff --git a/ts/src/metadata/tileset/embeddedTilesetMetadataDecoder.spec.ts b/ts/src/metadata/tileset/embeddedTilesetMetadataDecoder.spec.ts
@@ -228,6 +228,19 @@ describe("embeddedTilesetMetadataDecoder", () => {
             }).toThrow("Missing layer name");
         });
 
+        it("should throw for an unsupported column type code", () => {
+            const buffer = concatenateBuffers(
+                encodeFieldName("layer"),
+                encodeTypeCode(4096),
+                encodeChildCount(1),
+                encodeTypeCode(5), // 5 is not a valid column type code
+            );
+
+            expect(() => {
+                decodeEmbeddedTileSetMetadata(buffer, new IntWrapper(0));
+            }).toThrow("Unsupported column type code 5");
+        });
+
         it("should decode logical ID metadata with implicit id column name", () => {
             const typeCode = 3;
             const buffer = concatenateBuffers(
diff --git a/ts/src/metadata/tileset/embeddedTilesetMetadataDecoder.ts b/ts/src/metadata/tileset/embeddedTilesetMetadataDecoder.ts
@@ -29,13 +29,11 @@ function decodeString(src: Uint8Array, offset: IntWrapper): string {
  * Used when decoding Field metadata which has the same format as Column.
  */
 function columnToField(column: Column): Field {
-    return {
-        name: column.name,
-        nullable: column.nullable,
-        scalarField: column.scalarType,
-        complexField: column.complexType,
-        type: column.type === "scalarType" ? "scalarField" : "complexField",
-    };
+    const name = column.name;
+    const nullable = column.nullable;
+    return column.type === "scalarType"
+        ? { type: "scalarField", scalarField: column.scalarType, name, nullable }
+        : { type: "complexField", complexField: column.complexType, name, nullable };
 }
 
 /**
@@ -44,21 +42,20 @@ function columnToField(column: Column): Field {
 export function decodeField(src: Uint8Array, offset: IntWrapper): Field {
     const typeCode = decodeVarintInt32(src, offset, 1)[0] >>> 0;
 
-    if (typeCode < 10 || typeCode > 30) {
+    const base = typeCode >= 10 ? decodeColumnType(typeCode) : null;
+    if (!base) {
         throw new Error(`Unsupported field type code ${typeCode}. Supported: ${SUPPORTED_FIELD_TYPES}`);
     }
 
-    const column = decodeColumnType(typeCode);
+    // Field type codes (10-30) always carry an explicit name.
+    const column: Column = { ...base, name: decodeString(src, offset) };
 
-    if (columnTypeHasName(typeCode)) {
-        column.name = decodeString(src, offset);
-    }
-
-    if (columnTypeHasChildren(typeCode)) {
+    if (column.type === "complexType" && columnTypeHasChildren(typeCode)) {
+        const complexCol = column.complexType;
         const childCount = decodeVarintInt32(src, offset, 1)[0] >>> 0;
-        column.complexType.children = new Array(childCount);
+        complexCol.children = new Array(childCount);
         for (let i = 0; i < childCount; i++) {
-            column.complexType.children[i] = decodeField(src, offset);
+            complexCol.children[i] = decodeField(src, offset);
         }
     }
 
@@ -70,24 +67,26 @@ export function decodeField(src: Uint8Array, offset: IntWrapper): Field {
  */
 function decodeColumn(src: Uint8Array, offset: IntWrapper): Column {
     const typeCode = decodeVarintInt32(src, offset, 1)[0] >>> 0;
-    const column = decodeColumnType(typeCode);
+    const base = decodeColumnType(typeCode);
 
-    if (!column) {
+    if (!base) {
         throw new Error(`Unsupported column type code ${typeCode}. Supported: ${SUPPORTED_COLUMN_TYPES}`);
     }
 
+    let name: string;
     if (columnTypeHasName(typeCode)) {
-        column.name = decodeString(src, offset);
+        name = decodeString(src, offset);
+    } else if (typeCode <= 3) {
+        name = "id";
+    } else if (typeCode === 4) {
+        name = "geometry";
     } else {
-        // ID and GEOMETRY columns have implicit names
-        if (typeCode >= 0 && typeCode <= 3) {
-            column.name = "id";
-        } else if (typeCode === 4) {
-            column.name = "geometry";
-        }
+        throw new Error(`Unsupported column type code ${typeCode}. Supported: ${SUPPORTED_COLUMN_TYPES}`);
     }
 
-    if (columnTypeHasChildren(typeCode)) {
+    const column: Column = { ...base, name };
+
+    if (column.type === "complexType" && columnTypeHasChildren(typeCode)) {
         // Only STRUCT (typeCode 30) has children
         const childCount = decodeVarintInt32(src, offset, 1)[0] >>> 0;
         const complexCol = column.complexType;
diff --git a/ts/src/metadata/tileset/tilesetMetadata.ts b/ts/src/metadata/tileset/tilesetMetadata.ts
@@ -31,63 +31,66 @@ export const LogicalComplexType = {
     RANGE_MAP: 1,
 } as const;
 
-export interface TileSetMetadata {
-    version?: number | null;
+export type TileSetMetadata = {
+    version?: number;
     featureTables: FeatureTableSchema[];
-    name?: string | null;
-    description?: string | null;
-    attribution?: string | null;
-    minZoom?: number | null;
-    maxZoom?: number | null;
+    name?: string;
+    description?: string;
+    attribution?: string;
+    minZoom?: number;
+    maxZoom?: number;
     bounds: number[];
     center: number[];
-}
+};
 
-export interface FeatureTableSchema {
-    name?: string | null;
+export type FeatureTableSchema = {
+    name: string;
     columns: Column[];
-}
+};
 
-export interface Column {
-    name?: string | null;
-    nullable?: boolean | null;
-    columnScope?: number | null;
-    scalarType?: ScalarColumn | null;
-    complexType?: ComplexColumn | null;
-    type?: "scalarType" | "complexType";
-}
+export type Column = {
+    name: string;
+    nullable: boolean;
+    columnScope: number;
+} & (
+    | { type: "scalarType"; scalarType: ScalarColumn; complexType?: undefined }
+    | { type: "complexType"; complexType: ComplexColumn; scalarType?: undefined }
+);
 
-export interface ScalarColumn {
-    longID?: boolean | null;
-    physicalType?: number | null;
-    logicalType?: number | null;
+/** `Omit` that distributes over the union members of {@link Column}, preserving the `type` discriminant. */
+export type ColumnWithoutName = Column extends infer C ? (C extends Column ? Omit<C, "name"> : never) : never;
+
+export type ScalarColumn = {
+    longID: boolean;
+    physicalType?: number;
+    logicalType?: number;
     type?: "physicalType" | "logicalType";
-}
+};
 
-export interface ComplexColumn {
-    physicalType?: number | null;
-    logicalType?: number | null;
+export type ComplexColumn = {
+    physicalType?: number;
+    logicalType?: number;
     children: Field[];
     type?: "physicalType" | "logicalType";
-}
+};
 
-export interface Field {
-    name?: string | null;
-    nullable?: boolean | null;
-    scalarField?: ScalarField | null;
-    complexField?: ComplexField | null;
-    type?: "scalarField" | "complexField";
-}
+export type Field = {
+    name?: string;
+    nullable?: boolean;
+} & (
+    | { type: "scalarField"; scalarField: ScalarField; complexField?: undefined }
+    | { type: "complexField"; complexField: ComplexField; scalarField?: undefined }
+);
 
-export interface ScalarField {
-    physicalType?: number | null;
-    logicalType?: number | null;
+export type ScalarField = {
+    physicalType?: number;
+    logicalType?: number;
     type?: "physicalType" | "logicalType";
-}
+};
 
-export interface ComplexField {
-    physicalType?: number | null;
-    logicalType?: number | null;
+export type ComplexField = {
+    physicalType?: number;
+    logicalType?: number;
     children: Field[];
     type?: "physicalType" | "logicalType";
-}
+};
diff --git a/ts/src/metadata/tileset/typeMap.spec.ts b/ts/src/metadata/tileset/typeMap.spec.ts
@@ -27,6 +27,55 @@ describe("typeMap helpers", () => {
         }
     });
 
+    it("should decode the GEOMETRY type code as a non-nullable complex column", () => {
+        expect(decodeColumnType(4)).toMatchObject({
+            nullable: false,
+            type: "complexType",
+            complexType: { type: "physicalType", physicalType: ComplexType.GEOMETRY },
+        });
+    });
+
+    it("should decode the STRUCT type code as a non-nullable complex column", () => {
+        expect(decodeColumnType(30)).toMatchObject({
+            nullable: false,
+            type: "complexType",
+            complexType: { type: "physicalType", physicalType: ComplexType.STRUCT },
+        });
+    });
+
+    it("should decode scalar type codes with the nullable flag in the low bit", () => {
+        const cases: Array<{ even: number; physicalType: number }> = [
+            { even: 10, physicalType: ScalarType.BOOLEAN },
+            { even: 12, physicalType: ScalarType.INT_8 },
+            { even: 14, physicalType: ScalarType.UINT_8 },
+            { even: 16, physicalType: ScalarType.INT_32 },
+            { even: 18, physicalType: ScalarType.UINT_32 },
+            { even: 20, physicalType: ScalarType.INT_64 },
+            { even: 22, physicalType: ScalarType.UINT_64 },
+            { even: 24, physicalType: ScalarType.FLOAT },
+            { even: 26, physicalType: ScalarType.DOUBLE },
+            { even: 28, physicalType: ScalarType.STRING },
+        ];
+
+        for (const { even, physicalType } of cases) {
+            expect(decodeColumnType(even)).toMatchObject({
+                nullable: false,
+                type: "scalarType",
+                scalarType: { type: "physicalType", physicalType },
+            });
+            expect(decodeColumnType(even + 1)).toMatchObject({
+                nullable: true,
+                type: "scalarType",
+                scalarType: { type: "physicalType", physicalType },
+            });
+        }
+    });
+
+    it("should return null for unsupported type codes", () => {
+        expect(decodeColumnType(5)).toBeNull();
+        expect(decodeColumnType(99)).toBeNull();
+    });
+
     it("should return false for physical scalar columns even when column is named id", () => {
         const physicalIdNamedColumn = {
             name: "id",
diff --git a/ts/src/metadata/tileset/typeMap.ts b/ts/src/metadata/tileset/typeMap.ts
