Implementation:TobikoData Sqlmesh Common Types

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_UI, Types
Last Updated	2026-02-07 20:00 GMT

Overview

TypeScript type definitions for common UI concepts including branded types, sizing, and layout primitives.

Description

This module provides TypeScript type definitions used throughout the SQLMesh web UI. It includes a branded type system for creating distinct string types that prevent accidental mixing (using unique symbol branding), BrandedRecord for type-safe record objects, and common UI type unions for Size (seven variants from 2xs to 2xl), Side (left/right/both), Shape (square/round/pill), Position (top/right/bottom/left/center/start/end), HeadlineLevel (1-6), and LayoutDirection (vertical/horizontal/both). The Callback type provides a generic function signature for event handlers.

Usage

Import these types in any component or utility that needs type safety for UI properties. Use Branded types when you need to ensure string values of different semantic meanings cannot be accidentally mixed (e.g., ModelFQN vs ModelName). Use Size, Shape, and Side types for component prop definitions to ensure consistency across the component library.

Code Reference

Source Location

• Repository: TobikoData_Sqlmesh
• File: web/common/src/types.ts

Type Definitions

// Branded type system
export declare const __brand: unique symbol
export type Brand<B> = { [__brand]: B }
export type Branded<T, B> = T & Brand<B>
export type BrandedString = string & Brand<string>
export type BrandedRecord<K extends BrandedString, V> = Record<K, V> & {
  readonly __recordKeyBrand: K
}

// Callback type
export type Callback<T = unknown> = (data?: T) => void

// UI dimension and layout types
export type Size = '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' | '2xl'
export type HeadlineLevel = 1 | 2 | 3 | 4 | 5 | 6
export type Side = 'left' | 'right' | 'both'
export type LayoutDirection = 'vertical' | 'horizontal' | 'both'
export type Shape = 'square' | 'round' | 'pill'
export type Position = 'top' | 'right' | 'bottom' | 'left' | 'center' | 'start' | 'end'

Import

import type { Size, Shape, Side, Branded, BrandedRecord } from '@sqlmesh-common/types'

Type Catalog

Branded Types

Type	Description	Usage
Branded<T, B>	Adds brand B to type T	Creating distinct string types
BrandedString	Branded string constraint	Generic branded string parameter
BrandedRecord<K, V>	Type-safe branded record	Preventing Record type mixing

UI Types

Type	Values	Description
Size	'xs' | 's' | 'm' | 'l' | 'xl' | '2xl'	Component sizing variants
Shape	'round' | 'pill'	Border radius styling
Side	'right' | 'both'	Horizontal positioning
Position	'right' | 'bottom' | 'left' | 'center' | 'start' | 'end'	General positioning
LayoutDirection	'horizontal' | 'both'	Layout axis
HeadlineLevel	2 | 3 | 4 | 5 | 6	HTML heading levels

Function Types

Type	Signature	Description
Callback<T>	(data?: T) => void	Generic callback function

Usage Examples

// Branded types for domain modeling
type ModelFQN = Branded<string, 'ModelFQN'>
type ModelName = Branded<string, 'ModelName'>

const fqn = 'catalog.schema.model' as ModelFQN
const name = 'model' as ModelName

// TypeScript error - types are incompatible
// const mixed: ModelFQN = name

// BrandedRecord prevents mixing
type FQNMap = BrandedRecord<ModelFQN, ModelData>
type NameMap = BrandedRecord<ModelName, ModelData>

const fqnMap: FQNMap = {} as FQNMap
// TypeScript error - different record brands
// const nameMap: NameMap = fqnMap

// Component props with UI types
interface ButtonProps {
  size?: Size
  shape?: Shape
}

const button: ButtonProps = {
  size: 'm',
  shape: 'round'
}

// Callback usage
interface DataLoaderProps {
  onSuccess?: Callback<DataResult>
  onError?: Callback<Error>
}

const loader: DataLoaderProps = {
  onSuccess: (result) => console.log(result),
  onError: (error) => console.error(error)
}

// Position types
interface TooltipConfig {
  side: Side
  position: Position
}

const tooltip: TooltipConfig = {
  side: 'left',
  position: 'top'
}

Design Principles

Branded Types

The branded type system prevents common errors where strings with different semantic meanings are accidentally mixed. The unique symbol approach ensures compile-time type safety without runtime overhead.

Size Consistency

The Size type provides seven standard sizes used consistently across Button, Badge, Input, and other components, ensuring visual harmony throughout the UI.

Type Safety

All types are strict unions with exhaustive checking, preventing invalid values at compile time rather than runtime.

Related Pages

• Environment:TobikoData_Sqlmesh_Web_UI_Stack