Implementation:TobikoData Sqlmesh Client Utils

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

Overview

Comprehensive utility library providing type checking, data transformation, and common operations for the SQLMesh web client.

Description

The Client_Utils module is a foundational utility library containing 40+ helper functions for the SQLMesh web UI. It provides type guards (isNil, isString, isNotNil), string utilities (truncate, toUniqueName), date formatting (toDate, toDateFormat), JSON parsing (parseJSON), array operations (includes, isArrayNotEmpty), debouncing (debounceSync), ID generation (uid, toID), and ratio calculations (toRatio).

Usage

Import and use these utilities throughout the SQLMesh web client for consistent type checking, data validation, and common operations. These functions are designed to be tree-shakeable and have no external dependencies.

Code Reference

Source Location

• Repository: TobikoData_Sqlmesh
• File: web/client/src/utils/index.ts

Signature

// Type Guards
export function isTrue(value: unknown): boolean
export function isFalse(value: unknown): boolean
export function isNil(value: unknown): value is undefined | null
export function isNotNil<T>(value: T | null | undefined): value is T
export function isString(value: unknown): value is string
export function isNumber(value: unknown): value is number
export function isStringEmpty(value: unknown): value is ''
export function isStringEmptyOrNil(value: unknown): value is undefined | null | ''
export function isArrayNotEmpty<T = any>(value: unknown): value is T[]
export function isObject(value: unknown): boolean

// String Utilities
export function ensureString(value: unknown): string
export function truncate(text: string, maxChars?: number, displayBefore?: number, delimiter?: string, displayAfter?: number): string
export function toUniqueName(prefix?: string, suffix?: string): string

// Date Utilities
export function toDate(value?: string | number): Date | undefined
export function toDateFormat(date?: Date, format?: string, isUTC?: boolean): string

// ID Generation
export function uid(): string
export function toID(...args: Array<string | undefined>): string

// Data Operations
export function parseJSON<T>(value: string | null): Optional<T>
export function toRatio(top?: number, bottom?: number, multiplier?: number): number
export function includes<T>(array: T[], value: T): boolean

// Function Utilities
export function debounceSync(fn: (...args: any) => void, delay?: number, immediate?: boolean): (...args: any) => void

Import

import { isNil, isNotNil, parseJSON, uid, truncate } from '@utils/index'

Function Categories

Type Guards

Function	Description
isTrue / isFalse	Strict boolean checks (===)
isNil / isNotNil	Check for null/undefined
isFalseOrNil	Combined check for false or nil
isString / isNumber	Type checking with type narrowing
isPrimitive	Check for string, number, or boolean
isStringEmpty	Check for empty string
isStringEmptyOrNil	Check for empty, null, or undefined string
isArrayNotEmpty	Check array has elements
isArrayEmpty	Check array is empty
isObject	Check plain object (not array/null/Date)
isObjectEmpty / isObjectNotEmpty	Check object has keys
isDate	Check Date instance

String Utilities

Function	Description
ensureString	Convert to string or return
isStringNotEmpty	Check non-empty trimmed string
truncate	Truncate string with ellipsis (supports middle truncation)
toUniqueName	Generate unique name with timestamp hex

Date Utilities

Function	Description
toDate	Parse string/number to Date object
toDateFormat	Format date to string (supports mm/dd/yyyy, yyyy-mm-dd, with time)

ID Generation

Function	Description
uid	Generate unique ID (timestamp + random)
toID	Join strings with __ delimiter

Data Operations

Function	Description
parseJSON	Safe JSON.parse with error handling
toRatio	Calculate percentage ratio (top/bottom * multiplier)
includes	Array.includes wrapper

Function Utilities

Function	Description
debounceSync	Debounce function calls with optional immediate execution

Usage Examples

import {
  isNil,
  isNotNil,
  isStringEmptyOrNil,
  parseJSON,
  uid,
  truncate,
  toDate,
  toDateFormat,
  toRatio,
  debounceSync
} from '@utils/index'

// Type guards
if (isNotNil(value)) {
  // TypeScript knows value is not null/undefined here
  console.log(value.toString())
}

if (isStringEmptyOrNil(text)) {
  return 'No text provided'
}

// JSON parsing
const data = parseJSON<{ name: string }>(localStorage.getItem('user'))
console.log(data?.name)

// ID generation
const uniqueId = uid() // "lq3x8a9k2b4c"
const compositeId = toID('user', '123', 'profile') // "user__123__profile"

// String truncation
truncate('very_long_filename.sql', 20, 5, '...', 3)
// "very_...sql"

// Date formatting
const date = toDate('2024-01-15')
toDateFormat(date, 'mm/dd/yyyy') // "01/15/2024"
toDateFormat(date, 'yyyy-mm-dd hh-mm-ss') // "2024-01-15 00:00:00"

// Ratio calculation
toRatio(75, 100) // 75
toRatio(3, 4, 100) // 75
toRatio(1, 3, 100) // 33.333...

// Debouncing
const debouncedSearch = debounceSync((query: string) => {
  console.log('Searching:', query)
}, 500)

// Calls only once after 500ms
debouncedSearch('a')
debouncedSearch('ab')
debouncedSearch('abc')

Implementation Notes

Type Safety

Many functions use TypeScript type predicates (e.g., value is string) to enable type narrowing in calling code.

Nil Checks

Uses == null pattern to check both null and undefined simultaneously:

function isNil(value: unknown): value is undefined | null {
  return value == null
}

Date Formatting

Supports UTC and local time formatting with padded numbers (01, 02, etc.).

Truncation

The truncate function supports middle truncation, showing characters from both start and end:

truncate('long_file_name.sql', 20, 5, '...', 3)
// "long_...sql"

Related Pages

• TobikoData_Sqlmesh_UseLocalStorage
• TobikoData_Sqlmesh_Editor_Context
• TobikoData_Sqlmesh_Api_Channels
• Environment:TobikoData_Sqlmesh_Web_UI_Stack