Type Safety

TableCraft is built on Drizzle ORM, which means you get excellent type safety out of the box. However, raw SQL strings can be a weak point. We provide a set of helpers to maintain type safety even when doing complex SQL operations.

The Rule of Thumb:

• Good: Using ${schema.table.column} inside sql tags.

• Bad: Writing column names as plain strings.

Available Helpers

Import these from @tablecraft/engine.

caseWhen

Generates a CASE WHEN statement safely.

import { caseWhen } from '@tablecraft/engine';
import { sql } from 'drizzle-orm';

// ❌ Risky: Raw SQL string
.computed('status', sql`CASE WHEN ${s.users.role} = 'admin' THEN 1 ELSE 0 END`)

// ✅ Type-Safe: Compiler checks column and types
.computed('status', caseWhen(s.users.role, {
  'admin': 1,
  'user': 0
}, 0)) // Fallback to 0

column

coalesce

concat

dateTrunc

ago

Best Practices

1. Prefer Helpers: Always check if a helper exists before writing raw SQL.

2. Use Drizzle Columns: Inside sql tags, always interpolate Drizzle column objects (${s.users.name}) instead of writing string names ("name").

3. Validate Configs: If you are dynamically generating configs, use validateConfig to catch errors early.

Frontend Type Safety

Generated Types

The @tablecraft/codegen package generates fully-typed interfaces from your API metadata:

// Generated from API metadata
export interface ProductsRow extends Record<string, unknown> {
  id: number;
  name: string;
  price: number;
  metadata: Record<string, unknown>;
}

export type ProductsColumn = 'id' | 'name' | 'price' | 'metadata';

Type-Safe Hidden Columns

Use the hiddenColumns helper with generated *Column types for compile-time safety:

import { DataTable, hiddenColumns } from '@tablecraft/table';
import type { ProductsRow, ProductsColumn } from './generated';

<DataTable<ProductsRow>
  adapter={adapter}
  hiddenColumns={hiddenColumns<ProductsColumn>(['id', 'metadata'])}
/>

The hiddenColumns helper catches typos and invalid column names at compile time, not runtime.