TypeScript Generation

Purpose and Scope

This page documents the make:ts command, which generates TypeScript type definitions from database models defined in db.json. This command produces type-safe TypeScript interfaces for frontend applications that consume the GraphQL API, ensuring type consistency between backend models and frontend code.

For information about generating PHP model classes, see Model Generation. For information about the database schema format, see Database Schema (db.json).

Sources: bin/light1-24

---

TypeScript Generation Architecture

The TypeScript generation system reads the database schema from db.json and produces TypeScript interface definitions that mirror the structure of PHP models. This enables frontend applications to have compile-time type checking when working with data from the GraphQL API.

Sources: bin/light1-24 db.json1-676

---

Command Registration

The MakeTsCommand is registered in the CLI application alongside other code generation commands:

The command is registered at bin/light21 and imported from Light\Command\MakeTsCommand at bin/light10 The CLI application provides a unified interface for all code generation operations.

Sources: bin/light1-24

---

Database Schema to TypeScript Type Mapping

The type generation system maps MySQL column types defined in db.json to TypeScript types. This mapping ensures semantic equivalence between database schemas and TypeScript interfaces.

Type Mapping Table

MySQL Type	TypeScript Type	Notes
int, tinyint	number	Both signed and unsigned integers map to number
varchar, text	string	All string types map to string
date, datetime	string	ISO 8601 date strings
json	any or specific interface	Can be typed as any or a custom interface
unsigned attribute	n/a	TypeScript number has no unsigned distinction
nullable columns	type | null	Adds null to the union type

Generated TypeScript Interface Structure

For each table in db.json, the generator creates a TypeScript interface with:

• Interface name matching the table name
• Properties corresponding to each column
• Optional properties for nullable columns
• Type unions for nullable fields

Sources: db.json1-676

---

Example: User Model TypeScript Generation

The User table definition in db.json demonstrates the full range of type mapping scenarios:

Expected TypeScript Output Structure

Based on the User table schema at db.json3-138 the generated TypeScript would include:

• user_id: number - auto-increment primary key
• username: string - non-nullable varchar
• password: string - non-nullable varchar
• first_name: string - varchar with implicit nullability
• email: string - contact information
• status: number - tinyint unsigned with default 0
• language: string - varchar(5) for locale
• join_date: string - date field as ISO string
• setting: any - JSON field for user preferences
• credential: any - JSON field for WebAuthn data
• menu: any - JSON field for custom menu structure
• style: any - JSON field for UI preferences

Sources: db.json3-138

---

Type Generation Workflow

The TypeScript generation process follows a multi-stage pipeline:

Sources: bin/light1-24 db.json1-676

---

Complex Type Scenarios

JSON Column Handling

JSON columns in the database schema can be mapped in multiple ways:

Column	Schema Definition	Basic TypeScript	Enhanced TypeScript
setting	json at db.json85-86	setting: any	setting: UserSettings
credential	json at db.json93-94	credential: any	credential: WebAuthnCredential[]
menu	json at db.json120-121	menu: any	menu: MenuItem[]
style	json at db.json124-125	style: any	style: StyleConfig

The basic generation produces any types for JSON columns, while enhanced generation can create specific interfaces for known JSON structures.

Foreign Key Relationships

The type generator recognizes foreign key relationships defined in db.json and can optionally generate related entity properties:

The UserRole table at db.json180-230 defines a foreign key relationship to the User table. The generated TypeScript can include navigation properties for related entities.

Sources: db.json180-230 db.json218-229

---

Integration with Frontend GraphQL Clients

The generated TypeScript definitions provide compile-time type safety for GraphQL operations:

Frontend Usage Pattern

The generated types enable type-safe GraphQL queries:

1. Type Import: Frontend code imports generated interfaces
2. Query Typing: GraphQL query results are typed with generated interfaces
3. Compile-Time Validation: TypeScript compiler validates data access
4. IDE Support: Autocomplete and inline documentation from types

Sources: bin/light1-24 db.json1-676

---

Command Usage

The make:ts command is invoked through the CLI:

php bin/light make:ts [options]

The command reads from db.json in the project root and generates TypeScript definition files for all tables defined in the schema. The generated files maintain naming consistency with the PHP model classes for ease of mapping between backend and frontend code.

Sources: bin/light1-24

---

Type Safety Benefits

The TypeScript generation system provides several key benefits:

Benefit	Description
Compile-Time Checking	Catch type mismatches before runtime
IDE Integration	Full autocomplete and inline documentation
Refactoring Safety	Rename operations propagate through frontend code
API Contract	TypeScript definitions serve as API documentation
Version Synchronization	Regenerate types when schema changes

The generated TypeScript definitions act as a bridge between the database schema defined in db.json1-676 and frontend applications, ensuring that both sides of the API remain synchronized as the schema evolves.

Sources: db.json1-676 bin/light1-24