Types From Serializers

Automatically generate TypeScript interfaces from your JSON serializers.

Currently, this library targets oj_serializers and ActiveRecord in Rails applications.

Demo 🎬

For a schema such as this one:

DB Schema

  create_table "composers", force: :cascade do |t|
    t.text "first_name"
    t.text "last_name"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

  create_table "songs", force: :cascade do |t|
    t.text "title"
    t.integer "composer_id"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

  create_table "video_clips", force: :cascade do |t|
    t.text "title"
    t.text "youtube_id"
    t.integer "song_id"
    t.integer "composer_id"
    t.datetime "created_at", precision: 6, null: false
    t.datetime "updated_at", precision: 6, null: false
  end

and a serializer like the following:

class VideoSerializer < BaseSerializer
  object_as :video, model: :VideoClip

  attributes :id, :created_at, :title, :youtube_id

  type :string, optional: true
  def youtube_url
    "https://www.youtube.com/watch?v=#{video.youtube_id}" if video.youtube_id
  end

  has_one :song, serializer: SongSerializer
end

it would generate a TypeScript interface like:

import type Song from './Song'

export default interface Video {
  id: number
  createdAt: string | Date
  title?: string
  youtubeId?: string
  youtubeUrl?: string
  song: Song
}

Note

This is the default configuration, but you have full control over generation.

Why? 🤔

It's easy for the backend and the frontend to become out of sync. Traditionally, preventing bugs requires writing extensive integration tests.

TypeScript is a great tool to catch this kind of bugs and mistakes, as it can detect incorrect usages and missing fields, but writing types manually is cumbersome, and they can become stale over time, giving a false sense of confidence.

This library takes advantage of the declarative nature of serializer libraries such as active_model_serializers and oj_serializers, extending them to allow embedding type information, as well as inferring types from the SQL schema when available.

As a result, it's posible to easily detect mismatches between the backend and the frontend, as well as make the fields more discoverable and provide great autocompletion in the frontend, without having to manually write the types.

Features ⚡️

Start simple, no additional syntax required
Infers types from a related ActiveRecord model, using the SQL schema
Understands JS native types and how to map SQL columns: string, boolean, etc
Automatically types associations, importing the generated types for the referenced serializers
Detects conditional attributes and marks them as optional: name?: string
Fallback to a custom interface using type_from
Supports custom types and automatically adds the necessary imports

Installation 💿

Add this line to your application's Gemfile:

gem 'types_from_serializers'

And then run:

$ bundle install

Usage 🚀

To get started, create a BaseSerializer that extends Oj::Serializer, and include the TypesFromSerializers::DSL module.

# app/serializers/base_serializer.rb

class BaseSerializer < Oj::Serializer
  include TypesFromSerializers::DSL
end

Note

You can customize this behavior using base_serializers.

Warning

All serializers should extend one of the base_serializers, or they won't be detected.

SQL Attributes

In most cases, you'll want to let TypesFromSerializers infer the types from the SQL schema.

If you are using ActiveRecord, the model related to the serializer will be inferred can be inferred from the serializer name:

UserSerializer => User

It can also be inferred from an object alias if provided:

class PersonSerializer < BaseSerializer
  object_as :user

In cases where we want to use a different alias, you can provide the model name explicitly:

class PersonSerializer < BaseSerializer
  object_as :person, model: :User

Model Attributes

When you want to be more strict than the SQL schema, or for attributes that are methods in the model, you can use:

  attributes(
    name: {type: :string},
    status: {type: :Status}, # a custom type in ~/types/Status.ts
  )

Serializer Attributes

For attributes defined in the serializer, use the type helper:

  type :boolean
  def suspended
    user.status.suspended?
  end

Note

When specifying a type, attribute will be called automatically.

Fallback Attributes

You can also specify types_from to provide a TypeScript interface that should be used to obtain the field types:

class LocationSerializer < BaseSerializer
  object_as :location, types_from: :GoogleMapsLocation

  attributes(
    :lat,
    :lng,
  )
end

import GoogleMapsLocation from '~/types/GoogleMapsLocation'

export default interface Location {
  lat: GoogleMapsLocation['lat']
  lng: GoogleMapsLocation['lng']
}

Generation 📜

To get started, run bin/rails s to start the Rails development server.

TypesFromSerializers will automatically register a Rails reloader, which detects changes to serializer files, and will generate code on-demand only for the modified files.

It can also detect when new serializer files are added, or removed, and update the generated code accordingly.

Manually

To generate types manually, use the rake task:

bundle exec rake types_from_serializers:generate

or if you prefer to do it manually from the console:

require "types_from_serializers/generator"

TypesFromSerializers.generate(force: true)

With `vite-plugin-full-reload` ⚡️

When using Vite Ruby, you can add vite-plugin-full-reload to automatically reload the page when modifying serializers, causing the Rails reload process to be triggered, which is when generation occurs.

// vite.config.ts
import { defineConfig } from 'vite'
import ruby from 'vite-plugin-ruby'
import reloadOnChange from 'vite-plugin-full-reload'

defineConfig({
  plugins: [
    ruby(),
    reloadOnChange(['app/serializers/**/*.rb'], { delay: 200 }),
  ],
})

As a result, when modifying a serializer and hitting save, the type for that serializer will be updated instantly!

Configuration ⚙️

You can configure generation in a Rails initializer:

# config/initializers/types_from_serializers.rb

if Rails.env.development?
  TypesFromSerializers.config do |config|
    config.name_from_serializer = ->(name) { name }
  end
end

`namespace`

Default: nil

Allows to specify a TypeScript namespace and generate .d.ts to make types available globally, avoiding the need to import types explicitly.

`base_serializers`

Default: ["BaseSerializer"]

Allows you to specify the base serializers, that are used to detect other serializers in the app that you would like to generate interfaces for.

`serializers_dirs`

Default: ["app/serializers"]

The dirs where the serializer files are located.

`output_dir`

Default: "app/frontend/types/serializers"

The dir where the generated TypeScript interface files are placed.

`custom_types_dir`

Default: "app/frontend/types"

The dir where the custom types are placed.

`name_from_serializer`

Default: ->(name) { name.delete_suffix("Serializer") }

A Proc that specifies how to convert the name of the serializer into the name of the generated TypeScript interface.

`global_types`

Default: ["Array", "Record", "Date"]

Types that don't need to be imported in TypeScript.

You can extend this list as needed if you are using global definitions.

`skip_serializer_if`

Default: ->(serializer) { false }

You can provide a proc to avoid generating serializers.

Along with base_serializers, this provides more fine-grained control in cases where a single backend supports several frontends, allowing to generate types separately.

`sql_to_typescript_type_mapping`

Specifies how to map SQL column types to TypeScript native and custom types.

# Example: You have response middleware that automatically converts date strings
# into Date objects, and you want TypeScript to treat those fields as `Date`.
config.sql_to_typescript_type_mapping.update(
  date: :Date,
  datetime: :Date,
)

# Example: You won't transform fields when receiving data in the frontend
# (date fields are serialized to JSON as strings).
config.sql_to_typescript_type_mapping.update(
  date: :string,
  datetime: :string,
)

# Example: You plan to introduce types slowly, and don't want to be strict with
# untyped fields, so treat them as `any` instead of `unknown`.
config.sql_to_typescript_type_mapping.default = :any

`transform_keys`

Default: ->(key) { key.camelize(:lower).chomp("?") }

You can provide a proc to transform property names.

This library assumes that you will transform the casing client-side, but you can generate types preserving case by using config.transform_keys = ->(key) { key }.

Contact ✉️

Please use Issues to report bugs you find, and Discussions to make feature requests or get help.

Don't hesitate to ⭐️ star the project if you find it useful!

Using it in production? Always love to hear about it! 😃

License

The gem is available as open source under the terms of the MIT License.

ElMassimo/types_from_serializers