27 |
27 |
28 |
29 | ## Features
30 |
31 | - Automatic TypeScript interface generation
32 | - Support for multiple serializer libraries (`Alba`, `ActiveModel::Serializer`, `Oj::Serializer`, `Panko::Serializer`)
33 | - File watching and automatic regeneration in development
34 |
35 | ## Installation
36 |
37 | To install Typelizer, add the following line to your `Gemfile` and run `bundle install`:
38 |
39 | ```ruby
40 | gem "typelizer"
41 | ```
42 |
43 | ## Usage
44 |
45 | ### Basic Setup
46 |
47 | Include the Typelizer DSL in your serializers:
48 |
49 | ```ruby
50 | class ApplicationResource
51 | include Alba::Resource
52 | include Typelizer::DSL
53 |
54 | # For Alba, we recommend using the `helper` method instead of `include`.
55 | # See the documentation: https://github.com/okuramasafumi/alba/blob/main/README.md#helper
56 | # helper Typelizer::DSL
57 | end
58 |
59 | class PostResource < ApplicationResource
60 | attributes :id, :title, :body
61 |
62 | has_one :author, serializer: AuthorResource
63 | end
64 |
65 | class AuthorResource < ApplicationResource
66 | # specify the model to infer types from (optional)
67 | typelize_from User
68 |
69 | attributes :id, :name
70 | end
71 | ```
72 |
73 | Typelizer will automatically generate TypeScript interfaces based on your serializer definitions using information from your models.
74 |
75 | ### Manual Typing
76 |
77 | You can manually specify TypeScript types in your serializers:
78 |
79 | ```ruby
80 | class PostResource < ApplicationResource
81 | attributes :id, :title, :body, :published_at
82 |
83 | typelize "string"
84 | attribute :author_name do |post|
85 | post.author.name
86 | end
87 |
88 | typelize :string, nullable: true, comment: "Author's avatar URL"
89 | attribute :avatar do
90 | "https://example.com/avatar.png" if active?
91 | end
92 | end
93 | ```
94 |
95 | `typelize` can be used with a Hash to specify multiple types at once.
96 |
97 | ```ruby
98 | class PostResource < ApplicationResource
99 | attributes :id, :title, :body, :published_at
100 |
101 | attribute :author_name do |post|
102 | post.author.name
103 | end
104 |
105 | typelize author_name: :string, published_at: :string
106 | end
107 | ```
108 |
109 | You can also specify more complex type definitions using a lower-level API:
110 |
111 | ```ruby
112 | typelize attribute_name: ["string", "Date", optional: true, nullable: true, multi: true, enum: %w[foo bar], comment: "Attribute description", deprecated: "Use `another_attribute` instead"]
113 | ```
114 |
115 | ### TypeScript Integration
116 |
117 | Typelizer generates TypeScript interfaces in the specified output directory:
118 |
119 | ```typescript
120 | // app/javascript/types/serializers/Post.ts
121 | export interface Post {
122 | id: number;
123 | title: string;
124 | category?: "news" | "article" | "blog" | null;
125 | body: string;
126 | published_at: string | null;
127 | author_name: string;
128 | }
129 | ```
130 |
131 | All generated interfaces are automatically imported in a single file:
132 |
133 | ```typescript
134 | // app/javascript/types/serializers/index.ts
135 | export * from "./post";
136 | export * from "./author";
137 | ```
138 |
139 | We recommend importing this file in a central location:
140 |
141 | ```typescript
142 | // app/javascript/types/index.ts
143 | import "@/types/serializers";
144 | // Custom types can be added here
145 | // ...
146 | ```
147 |
148 | With such a setup, you can import all generated interfaces in your TypeScript files:
149 |
150 | ```typescript
151 | import { Post } from "@/types";
152 | ```
153 |
154 | This setup also allows you to use custom types in your serializers:
155 |
156 | ```ruby
157 | class PostWithMetaResource < ApplicationResource
158 | attributes :id, :title
159 | typelize "PostMeta"
160 | attribute :meta do |post|
161 | { likes: post.likes, comments: post.comments }
162 | end
163 | end
164 | ```
165 |
166 | ```typescript
167 | // app/javascript/types/serializers/PostWithMeta.ts
168 |
169 | import { PostMeta } from "@/types";
170 |
171 | export interface Post {
172 | id: number;
173 | title: string;
174 | meta: PostMeta;
175 | }
176 | ```
177 |
178 | The `"@/types"` import path is configurable:
179 |
180 | ```ruby
181 | Typelizer.configure do |config|
182 | config.types_import_path = "@/types";
183 | end
184 | ```
185 |
186 | See the [Configuration](#configuration) section for more options.
187 |
188 | ### Manual Generation
189 |
190 | To manually generate TypeScript interfaces use one of the following commands:
191 |
192 | ```bash
193 | # Generate new interfaces
194 | rails typelizer:generate
195 |
196 | # Clean output directory and regenerate all interfaces
197 | rails typelizer:generate:refresh
198 | ````
199 |
200 | ### Automatic Generation in Development
201 |
202 | When [Listen](https://github.com/guard/listen) is installed, Typelizer automatically watches for changes and regenerates interfaces in development mode. You can disable this behavior:
203 |
204 | ```ruby
205 | Typelizer.listen = false
206 | ```
207 |
208 | ### Disabling Typelizer
209 |
210 | Sometimes we want to use Typelizer only with manual generation. To disable Typelizer during development, we can set `DISABLE_TYPELIZER` environment variable to `true`. This doesn't affect manual generation.
211 |
212 | ## Configuration
213 |
214 | ### Global Configuration
215 |
216 | Typelizer provides several global configuration options:
217 |
218 | ```ruby
219 | # Directories to search for serializers:
220 | Typelizer.dirs = [Rails.root.join("app", "resources"), Rails.root.join("app", "serializers")]
221 | # Reject specific classes from being typelized:
222 | Typelizer.reject_class = ->(serializer:) { false }
223 | # Logger for debugging:
224 | Typelizer.logger = Logger.new($stdout, level: :info)
225 | # Force enable or disable file watching with Listen:
226 | Typelizer.listen = nil
227 | ```
228 |
229 | ### Config Options
230 |
231 | `Typelizer::Config` offers fine-grained control over the gem's behavior. Here's a list of available options:
232 |
233 | ```ruby
234 | Typelizer.configure do |config|
235 | # Determines how serializer names are mapped to TypeScript interface names
236 | config.serializer_name_mapper = ->(serializer) { ... }
237 |
238 | # Maps serializers to their corresponding model classes
239 | config.serializer_model_mapper = ->(serializer) { ... }
240 |
241 | # Custom transformation for generated properties
242 | config.properties_transformer = ->(properties) { ... }
243 |
244 | # Plugin for model type inference (default: ModelPlugins::Auto)
245 | config.model_plugin = Typelizer::ModelPlugins::Auto
246 |
247 | # Plugin for serializer parsing (default: SerializerPlugins::Auto)
248 | config.serializer_plugin = Typelizer::SerializerPlugins::Auto
249 |
250 | # Additional configurations for specific plugins
251 | config.plugin_configs = { alba: { ts_mapper: {...} } }
252 |
253 | # Custom DB to TypeScript type mapping
254 | config.type_mapping = config.type_mapping.merge(jsonb: "RecordYou may have mistyped the address or the page may have moved.
63 |If you are the application owner check the logs for more information.
65 |Maybe you tried to change something you didn't have access to.
63 |If you are the application owner check the logs for more information.
65 |If you are the application owner check the logs for more information.
64 |