README

This package generates TypeScript definitions for Laravel Eloquent models using spatie/laravel-typescript-transformer.

Installation

Install via Composer:

composer require isgarrido/laravel-model-typescript-transformer

Update your config/typescript-transformer.php config file by...

Appending ModelTypeScriptCollector to the collectors array.
Appending ModelTransformer to the transformers array.

    'collectors' => [
        // ...
        IsGarrido\LaravelModelTypescriptTransformer\ModelTypeScriptCollector::class,
    ],
    'transformers' => [
        // Etc....
        IsGarrido\LaravelModelTypescriptTransformer\ModelTransformer::class,
    ],

Type Mapping Configuration

This package uses the type mapping defined in the spatie/laravel-typescript-transformer config file (config/typescript-transformer.php). Specifically, it looks for the default_type_replacements array to determine how PHP/DB types are mapped to TypeScript types.

For example:

'default_type_replacements' => [
    DateTime::class => 'string',
    DateTimeImmutable::class => 'string',
    Carbon\CarbonInterface::class => 'string',
    Carbon\CarbonImmutable::class => 'string',
    Carbon\Carbon::class => 'string',
    'tinyint' => 'number',
    'smallint' => 'number',
    'mediumint' => 'number',
    'int' => 'number',
    'bigint' => 'number',
    'integer' => 'number',
    'float' => 'number',
    'double' => 'number',
    'decimal' => 'number',
],

If a type or cast is found in this array, it will be used for the TypeScript definition. If not, the package falls back to its built-in mapping or uses unknown /* type */ as a fallback.

You can customize type replacements by editing the default_type_replacements array in your config file.

Usage

Generate TypeScript definitions by running:

php artisan typescript:generate

How it works

Identifying Properties

The ModelTransformer identifies the properties of the given Model by looking at the columns in the database table, and then filters columns out based on the $hidden and $visible properties of the model.

Mapping Database Types to TypeScript Types

Property types are determined by first checking the default_type_replacements config. If no mapping is found, the following built-in mappings are used:

Typescript Type	Database Type
string	uuid, string, text, varchar, character varying, date, datetime, timestamp, timestamp without time zone, bpchar, timestamptz, time, bytea, blob
number	integer, bigint, int2, int4, int8, float, double, decimal, float8, numeric
boolean	boolean, bool

Note: Unknown column types will be mapped to unknown and are followed by a comment stating the db type. You can override this behavior by adding your own mapping to the config file.

Nullable Types

If a column is nullable, the TypeScript type will be suffixed with | null.

Example

Let's look at a simple of example of a user model in a PostgreSQL database.

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL ,
    password VARCHAR(255),
    active BOOLEAN NOT NULL,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

The User model might look like this:

class User extends Model
{
    protected $hidden = ['password'];
}

Will generate the following TypeScript definition:

declare namespace App.Models {
  export interface User {
    id: number
    name: string
    email: string
    active: boolean
    created_at: string | null
    updated_at: string | null
  }
}

Limitations

This package has some limitations.

Take a look at the issues to see what's missing.

Development

Setup

git clone git@github.com:isgarrido/laravel-model-typescript-transfomer.git

cd laravel-model-typescript-transformer

composer install

Running Tests

composer test

Publishing new Versions

To publish a new version of the package, you need to create a new tag and push it to the repository.

git tag vx.x.x
git push origin vx.x.x

Go to Packagist and click on "Update" to update the package.

isgarrido / laravel-model-typescript-transfomer

Maintainers

Details