> For the complete documentation index, see [llms.txt](https://jacksonkasi.gitbook.io/tablecraft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jacksonkasi.gitbook.io/tablecraft/features/codegen.md).

# Type Generation

The `@tablecraft/codegen` package generates TypeScript types from your TableCraft API metadata, providing full type safety for your frontend code.

## Installation

{% tabs %}
{% tab title="pnpm" %}

```bash
# Install as dev dependency
pnpm add -D @tablecraft/codegen

# Or use directly with npx
npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated
```

{% endtab %}

{% tab title="npx" %}

```bash
# Use directly with npx
npx @tablecraft/codegen --url http://localhost:5000/engine --out ./src/generated
```

{% endtab %}
{% endtabs %}

## Usage

### Basic Usage

```bash
npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated
```

This will:

1. Fetch metadata from all tables via `/_tables` endpoint
2. Generate TypeScript interfaces for each table
3. Create typed adapter factory functions

### Options

| Option     | Alias | Description                                               | Required |
| ---------- | ----- | --------------------------------------------------------- | -------- |
| `--url`    | `-u`  | Base URL of your TableCraft API                           | Yes      |
| `--out`    | `-o`  | Output directory for generated files                      | Yes      |
| `--tables` | `-t`  | Specific tables to generate (default: all)                | No       |
| `--header` | `-H`  | Custom headers (e.g., `-H "Authorization: Bearer token"`) | No       |

### Examples

{% tabs %}
{% tab title="Generate All" %}

```bash
npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated
```

{% endtab %}

{% tab title="Specific Tables" %}

```bash
npx @tablecraft/codegen --url http://localhost:3000/api/engine --out ./src/generated --tables users orders
```

{% endtab %}

{% tab title="Authenticated" %}

```bash
# With a Bearer Token
npx @tablecraft/codegen --url https://api.example.com/engine --out ./src/generated -H "Authorization: Bearer token"

# With a Session Cookie
npx @tablecraft/codegen --url https://api.example.com/engine --out ./src/generated -H "Cookie: session_id=your_cookie_value"

# With multiple headers
npx @tablecraft/codegen --url https://api.example.com/engine --out ./src/generated -H "Authorization: Bearer token" -H "x-tenant-id: acme"
```

{% endtab %}
{% endtabs %}

## Generated Files

```
src/generated/
├── index.ts          # Re-exports all types
├── users.ts          # UsersRow, UsersFilters, createUsersAdapter
├── orders.ts         # OrdersRow, OrdersFilters, createOrdersAdapter
├── products.ts       # ProductsRow, ProductsFilters, createProductsAdapter
└── package.json      # Package configuration
```

## Generated Types

{% tabs %}
{% tab title="Row Interface" %}
Each table generates a Row interface with all column types:

```typescript
export interface UsersRow extends Record<string, unknown> {
  id: number;
  email: string;
  role: string;
  isActive: boolean;
  createdAt: string | null;
}
```

{% endtab %}

{% tab title="Column Type" %}
Union type of all column names for type-safe operations:

```typescript
export type UsersColumn = 'id' | 'email' | 'role' | 'isActive' | 'createdAt';
```

Use with `hiddenColumns` for type safety:

```typescript
import { hiddenColumns } from '@tablecraft/table';
import type { UsersColumn } from './generated';

// Type-safe hidden columns
hiddenColumns<UsersColumn>(['id', 'createdAt']);
```

{% endtab %}

{% tab title="Filters Interface" %}
Filter types with operator unions:

```typescript
export interface UsersFilters {
  id?: { operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between'; value: number | [number, number] };
  email?: { operator: 'eq' | 'contains' | 'startsWith' | 'endsWith'; value: string };
  isActive?: { operator: 'eq' | 'neq'; value: boolean };
}
```

{% endtab %}

{% tab title="Adapter Factory" %}
Typed adapter factory functions:

```typescript
export function createUsersAdapter(options: {
  baseUrl: string;
  headers?: Record<string, string>;
}): DataAdapter<UsersRow>
```

{% endtab %}
{% endtabs %}

## Using Generated Types

### With DataTable

```typescript
import { DataTable, hiddenColumns } from '@tablecraft/table';
import { createOrdersAdapter, type OrdersRow, type OrdersColumn } from './generated';

function OrdersPage() {
  const adapter = createOrdersAdapter({
    baseUrl: '/api/engine',
  });

  return (
    <DataTable<OrdersRow>
      adapter={adapter}
      hiddenColumns={hiddenColumns<OrdersColumn>(['id', 'tenantId'])}
    />
  );
}
```

### Type-Safe Hidden Columns

The `hiddenColumns` helper function provides compile-time type checking:

```typescript
import { hiddenColumns } from '@tablecraft/table';
import type { ProductsColumn } from './generated';

// ✅ Valid - type-checked
hiddenColumns<ProductsColumn>(['id', 'metadata']);

// ❌ Error - 'invalidColumn' is not assignable to ProductsColumn
hiddenColumns<ProductsColumn>(['invalidColumn']);
```

### With Custom Adapter

```typescript
import { createTableCraftAdapter } from '@tablecraft/table';
import type { UsersRow, UsersFilters } from './generated';

const adapter = createTableCraftAdapter<UsersRow>({
  baseUrl: '/api/engine',
  table: 'users',
});
```

## Benefits

<table data-view="cards"><thead><tr><th>Benefit</th><th>Description</th></tr></thead><tbody><tr><td>Autocomplete</td><td>Column names and filter operators appear in your IDE.</td></tr><tr><td>Type Checking</td><td>Catch errors like typos or invalid types at compile time.</td></tr><tr><td>Refactoring</td><td>Rename columns safely across the entire codebase.</td></tr><tr><td>Documentation</td><td>Generated types serve as always-up-to-date documentation.</td></tr></tbody></table>

## CI/CD Integration

Add to your `package.json` to ensure types are always fresh before building:

```json
{
  "scripts": {
    "codegen": "tablecraft-codegen --url $API_URL --out ./src/generated",
    "prebuild": "pnpm codegen"
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://jacksonkasi.gitbook.io/tablecraft/features/codegen.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.