{"id":15412600,"url":"https://github.com/elmassimo/types_from_serializers","last_synced_at":"2025-04-05T18:12:11.712Z","repository":{"id":45054052,"uuid":"512255207","full_name":"ElMassimo/types_from_serializers","owner":"ElMassimo","description":"✅ Generate TypeScript interfaces from your JSON serializers","archived":false,"fork":false,"pushed_at":"2024-08-23T16:00:17.000Z","size":414,"stargazers_count":102,"open_issues_count":1,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T17:11:15.590Z","etag":null,"topics":["activemodelserializers","codegen","oj","ruby","serializers","typescript"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElMassimo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-09T18:13:08.000Z","updated_at":"2025-03-21T05:58:48.000Z","dependencies_parsed_at":"2024-02-24T23:32:49.936Z","dependency_job_id":"8282c623-8c5d-41c9-95ff-8e4a5d6e0c98","html_url":"https://github.com/ElMassimo/types_from_serializers","commit_stats":{"total_commits":63,"total_committers":6,"mean_commits":10.5,"dds":0.09523809523809523,"last_synced_commit":"a48fb1a36e692ba1b9ead0db6971379a178ff1a8"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElMassimo%2Ftypes_from_serializers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElMassimo%2Ftypes_from_serializers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElMassimo%2Ftypes_from_serializers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElMassimo%2Ftypes_from_serializers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElMassimo","download_url":"https://codeload.github.com/ElMassimo/types_from_serializers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247378152,"owners_count":20929297,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activemodelserializers","codegen","oj","ruby","serializers","typescript"],"created_at":"2024-10-01T16:53:50.672Z","updated_at":"2025-04-05T18:12:11.675Z","avatar_url":"https://github.com/ElMassimo.png","language":"Ruby","readme":"\u003ch1 align=\"center\"\u003e\nTypes From Serializers\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/ElMassimo/types_from_serializers/actions\"\u003e\u003cimg alt=\"Build Status\" src=\"https://github.com/ElMassimo/types_from_serializers/workflows/build/badge.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://codeclimate.com/github/ElMassimo/types_from_serializers\"\u003e\u003cimg alt=\"Maintainability\" src=\"https://codeclimate.com/github/ElMassimo/types_from_serializers/badges/gpa.svg\"/\u003e\u003c/a\u003e\n\u003c!-- \u003ca href=\"https://codeclimate.com/github/ElMassimo/types_from_serializers\"\u003e\u003cimg alt=\"Test Coverage\" src=\"https://codeclimate.com/github/ElMassimo/types_from_serializers/badges/coverage.svg\"/\u003e\u003c/a\u003e --\u003e\n\u003ca href=\"https://rubygems.org/gems/types_from_serializers\"\u003e\u003cimg alt=\"Gem Version\" src=\"https://img.shields.io/gem/v/types_from_serializers.svg?colorB=e9573f\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/ElMassimo/types_from_serializers/blob/master/LICENSE.txt\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-MIT-428F7E.svg\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c/h1\u003e\n\n[oj]: https://github.com/ohler55/oj\n[oj_serializers]: https://github.com/ElMassimo/oj_serializers\n[ams]: https://github.com/rails-api/active_model_serializers\n[Rails]: https://github.com/rails/rails\n[Issues]: https://github.com/ElMassimo/types_from_serializers/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc\n[Discussions]: https://github.com/ElMassimo/types_from_serializers/discussions\n[TypeScript]: https://www.typescriptlang.org/\n[Vite Ruby]: https://github.com/ElMassimo/vite_ruby\n[vite-plugin-full-reload]: https://github.com/ElMassimo/vite-plugin-full-reload\n[base_serializers]: https://github.com/ElMassimo/types_from_serializers#base_serializers\n[config]: https://github.com/ElMassimo/types_from_serializers#configuration-%EF%B8%8F\n\nAutomatically generate TypeScript interfaces from your [JSON serializers][oj_serializers].\n\n_Currently, this library targets [`oj_serializers`][oj_serializers] and `ActiveRecord` in [Rails] applications_.\n\n## Demo 🎬\n\nFor a schema such as [this one](https://github.com/ElMassimo/types_from_serializers/blob/main/playground/vanilla/db/schema.rb):\n\n\u003cdetails\u003e\n  \u003csummary\u003eDB Schema\u003c/summary\u003e\n\n```ruby\n  create_table \"composers\", force: :cascade do |t|\n    t.text \"first_name\"\n    t.text \"last_name\"\n    t.datetime \"created_at\", precision: 6, null: false\n    t.datetime \"updated_at\", precision: 6, null: false\n  end\n\n  create_table \"songs\", force: :cascade do |t|\n    t.text \"title\"\n    t.integer \"composer_id\"\n    t.datetime \"created_at\", precision: 6, null: false\n    t.datetime \"updated_at\", precision: 6, null: false\n  end\n\n  create_table \"video_clips\", force: :cascade do |t|\n    t.text \"title\"\n    t.text \"youtube_id\"\n    t.integer \"song_id\"\n    t.integer \"composer_id\"\n    t.datetime \"created_at\", precision: 6, null: false\n    t.datetime \"updated_at\", precision: 6, null: false\n  end\n```\n\u003c/details\u003e\n\nand a serializer like the following:\n\n```ruby\nclass VideoSerializer \u003c BaseSerializer\n  object_as :video, model: :VideoClip\n\n  attributes :id, :created_at, :title, :youtube_id\n\n  type :string, optional: true\n  def youtube_url\n    \"https://www.youtube.com/watch?v=#{video.youtube_id}\" if video.youtube_id\n  end\n\n  has_one :song, serializer: SongSerializer\nend\n```\n\nit would generate a TypeScript interface like:\n\n```ts\nimport type Song from './Song'\n\nexport default interface Video {\n  id: number\n  createdAt: string | Date\n  title?: string\n  youtubeId?: string\n  youtubeUrl?: string\n  song: Song\n}\n```\n\n\u003e **Note**\n\u003e\n\u003e This is the default configuration, but you have [full control][config] over generation.\n\n\n## Why? 🤔\n\nIt's easy for the backend and the frontend to become out of sync.\nTraditionally, preventing bugs requires writing extensive integration tests.\n\n[TypeScript] is a great tool to catch this kind of bugs and mistakes, as it can\ndetect incorrect usages and missing fields, but writing types manually is\ncumbersome, and they can become stale over time, giving a false sense of confidence.\n\nThis library takes advantage of the declarative nature of serializer libraries\nsuch as [`active_model_serializers`][ams] and [`oj_serializers`][oj_serializers],\nextending them to allow embedding type information, as well as inferring types\nfrom the SQL schema when available.\n\nAs a result, it's posible to easily detect mismatches between the backend and\nthe frontend, as well as make the fields more discoverable and provide great\nautocompletion in the frontend, without having to manually write the types.\n\n## Features ⚡️\n\n- Start simple, no additional syntax required\n- Infers types from a related `ActiveRecord` model, using the SQL schema\n- Understands JS native types and how to map SQL columns: `string`, `boolean`, etc\n- Automatically types [associations](https://github.com/ElMassimo/oj_serializers#associations-dsl-), importing the generated types for the referenced serializers\n- Detects [conditional attributes](https://github.com/ElMassimo/oj_serializers#rendering-an-attribute-conditionally) and marks them as optional: `name?: string`\n- Fallback to a custom interface using `type_from`\n- Supports custom types and automatically adds the necessary imports\n\n\n## Installation 💿\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'types_from_serializers'\n```\n\nAnd then run:\n\n    $ bundle install\n\n## Usage 🚀\n\nTo get started, [create a `BaseSerializer`](https://github.com/ElMassimo/types_from_serializers/blob/main/playground/vanilla/app/serializers/base_serializer.rb) that extends [`Oj::Serializer`][oj_serializers], and include the `TypesFromSerializers::DSL` module.\n\n```ruby\n# app/serializers/base_serializer.rb\n\nclass BaseSerializer \u003c Oj::Serializer\n  include TypesFromSerializers::DSL\nend\n```\n\n\u003e **Note**\n\u003e\n\u003e You can customize this behavior using [`base_serializers`][base_serializers].\n\n\u003e **Warning**\n\u003e\n\u003e All serializers should extend one of the [`base_serializers`][base_serializers], or they won't be\ndetected.\n\n\n### SQL Attributes\n\nIn most cases, you'll want to let `TypesFromSerializers` infer the types from the [SQL schema](https://github.com/ElMassimo/types_from_serializers/blob/main/playground/vanilla/db/schema.rb).\n\nIf you are using `ActiveRecord`, the model related to the serializer will be inferred can be inferred from the serializer name:\n\n```ruby\nUserSerializer =\u003e User\n```\n\nIt can also be inferred from an [object alias](https://github.com/ElMassimo/oj_serializers#using-a-different-alias-for-the-internal-object) if provided:\n\n```ruby\nclass PersonSerializer \u003c BaseSerializer\n  object_as :user\n```\n\nIn cases where we want to use a different alias, you can provide the model name explicitly:\n\n```ruby\nclass PersonSerializer \u003c BaseSerializer\n  object_as :person, model: :User\n```\n\n### Model Attributes\n\nWhen you want to be more strict than the SQL schema, or for attributes that are methods in the model, you can use:\n\n```ruby\n  attributes(\n    name: {type: :string},\n    status: {type: :Status}, # a custom type in ~/types/Status.ts\n  )\n```\n\n### Serializer Attributes\n\nFor attributes defined in the serializer, use the `type` helper:\n\n```ruby\n  type :boolean\n  def suspended\n    user.status.suspended?\n  end\n```\n\n\u003e **Note**\n\u003e\n\u003e When specifying a type, [`attribute`](https://github.com/ElMassimo/oj_serializers#serializer_attributes) will be called automatically.\n\n### Fallback Attributes\n\nYou can also specify `types_from` to provide a TypeScript interface that should\nbe used to obtain the field types:\n\n```ruby\nclass LocationSerializer \u003c BaseSerializer\n  object_as :location, types_from: :GoogleMapsLocation\n\n  attributes(\n    :lat,\n    :lng,\n  )\nend\n```\n\n```ts\nimport GoogleMapsLocation from '~/types/GoogleMapsLocation'\n\nexport default interface Location {\n  lat: GoogleMapsLocation['lat']\n  lng: GoogleMapsLocation['lng']\n}\n```\n\n## Generation 📜\n\nTo get started, run `bin/rails s` to start the `Rails` development server.\n\n`TypesFromSerializers` will automatically register a `Rails` reloader, which\ndetects changes to serializer files, and will generate code on-demand only for\nthe modified files.\n\nIt can also detect when new serializer files are added, or removed, and update\nthe generated code accordingly.\n\n### Manually\n\nTo generate types manually, use the rake task:\n\n```\nbundle exec rake types_from_serializers:generate\n```\n\nor if you prefer to do it manually from the console:\n\n```ruby\nrequire \"types_from_serializers/generator\"\n\nTypesFromSerializers.generate(force: true)\n```\n\n### With [`vite-plugin-full-reload`][vite-plugin-full-reload] ⚡️\n\nWhen using _[Vite Ruby]_, you can add [`vite-plugin-full-reload`][vite-plugin-full-reload]\nto automatically reload the page when modifying serializers, causing the Rails\nreload process to be triggered, which is when generation occurs.\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport ruby from 'vite-plugin-ruby'\nimport reloadOnChange from 'vite-plugin-full-reload'\n\ndefineConfig({\n  plugins: [\n    ruby(),\n    reloadOnChange(['app/serializers/**/*.rb'], { delay: 200 }),\n  ],\n})\n```\n\nAs a result, when modifying a serializer and hitting save, the type for that\nserializer will be updated instantly!\n\n## Configuration ⚙️\n\nYou can configure generation in a Rails initializer:\n\n```ruby\n# config/initializers/types_from_serializers.rb\n\nif Rails.env.development?\n  TypesFromSerializers.config do |config|\n    config.name_from_serializer = -\u003e(name) { name }\n  end\nend\n```\n\n### `namespace`\n\n_Default:_ `nil`\n\nAllows to specify a TypeScript namespace and generate `.d.ts` to make types\navailable globally, avoiding the need to import types explicitly.\n\n### `base_serializers`\n\n_Default:_ `[\"BaseSerializer\"]`\n\nAllows you to specify the base serializers, that are used to detect other\nserializers in the app that you would like to generate interfaces for.\n\n### `serializers_dirs`\n\n_Default:_ `[\"app/serializers\"]`\n\nThe dirs where the serializer files are located.\n\n### `output_dir`\n\n_Default:_ `\"app/frontend/types/serializers\"`\n\nThe dir where the generated TypeScript interface files are placed.\n\n### `custom_types_dir`\n\n_Default:_ `\"app/frontend/types\"`\n\nThe dir where the custom types are placed.\n\n### `name_from_serializer`\n\n_Default:_ `-\u003e(name) { name.delete_suffix(\"Serializer\") }`\n\nA `Proc` that specifies how to convert the name of the serializer into the name\nof the generated TypeScript interface.\n\n### `global_types`\n\n_Default:_ `[\"Array\", \"Record\", \"Date\"]`\n\nTypes that don't need to be imported in TypeScript.\n\nYou can extend this list as needed if you are using global definitions.\n\n### `skip_serializer_if`\n\n_Default:_ `-\u003e(serializer) { false }`\n\nYou can provide a proc to avoid generating serializers.\n\nAlong with `base_serializers`, this provides more fine-grained control in cases\nwhere a single backend supports several frontends, allowing to generate types\nseparately.\n\n### `sql_to_typescript_type_mapping`\n\nSpecifies [how to map](https://github.com/ElMassimo/types_from_serializers/blob/main/types_from_serializers/lib/types_from_serializers/generator.rb#L297-L308) SQL column types to TypeScript native and custom types.\n\n```ruby\n# Example: You have response middleware that automatically converts date strings\n# into Date objects, and you want TypeScript to treat those fields as `Date`.\nconfig.sql_to_typescript_type_mapping.update(\n  date: :Date,\n  datetime: :Date,\n)\n\n# Example: You won't transform fields when receiving data in the frontend\n# (date fields are serialized to JSON as strings).\nconfig.sql_to_typescript_type_mapping.update(\n  date: :string,\n  datetime: :string,\n)\n\n# Example: You plan to introduce types slowly, and don't want to be strict with\n# untyped fields, so treat them as `any` instead of `unknown`.\nconfig.sql_to_typescript_type_mapping.default = :any\n```\n\n### `transform_keys`\n\n_Default:_ `-\u003e(key) { key.camelize(:lower).chomp(\"?\") }`\n\nYou can provide a proc to transform property names.\n\nThis library assumes that you will transform the casing client-side, but you can\ngenerate types preserving case by using `config.transform_keys = -\u003e(key) { key }`.\n\n## Contact ✉️\n\nPlease use [Issues] to report bugs you find, and [Discussions] to make feature requests or get help.\n\nDon't hesitate to _⭐️ star the project_ if you find it useful!\n\nUsing it in production? Always love to hear about it! 😃\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felmassimo%2Ftypes_from_serializers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felmassimo%2Ftypes_from_serializers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felmassimo%2Ftypes_from_serializers/lists"}