typelizer 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c5a98a49d5f7a6f040da23ce1ff5c7b8453a758c0daae251788189be0fc874
-  data.tar.gz: f0b023ec773a121a30d5ee587118dad4c30b36f33309e34e4d07fb77b32a93fd
+  metadata.gz: d00f7bda8328c5148fe2bb6053d27066dd128fd834432c92d39417c3bbdc9405
+  data.tar.gz: 8b7fc9baa4b646cd91965b1316d9c9dcb22867a5bc8b65407c3fa36bbff9d85c
 SHA512:
-  metadata.gz: 6c4b5d39763829b212109356ac5f81967cbcd2340562bddf6bb116cd98d18e209e42f0d694d7fdb62241c661849591e75728250eb856929b68cdbdb4d54fd03a
-  data.tar.gz: 66635cbafdbc3babb70f92dd2a73b924954f7e7b3f22623397ef53c99d62f8c62c3daea754634833dd3909cdaaa4e03f6aa114c1d7156202aa8274ee2a77cc2e
+  metadata.gz: 9174cd537b757ea89f7a886c1443e12a78f16b269bc16ccb2e49866128c47471df83e55c32cc60ef7148ea4e8cd15d5cc1552f907dad903931c043af97ab6bc2
+  data.tar.gz: f4d59939214975e140d1a9db3cdc8c5bd9a3278baf6f59d686af7434499917ae30581fcb2a2681c1e106372fcda819250a47f5ba61a4844819dac660f8dea93a

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.2.0] - 2024-11-26
+
+## Added
+
+- Add support for enum attributes declared using `ActiveRecord::Enum` or explicitly in serializers ([@envek])
+- Add support for comments in generated TypeScript interfaces ([@envek])
+- Add TypeScript verbatim module syntax support through `verbatim_module_syntax` config option ([@patvice])
+- Add `typelizer:generate:refresh` command to clean output directory and regenerate all interfaces ([@patvice])
+- Allow disabling Typelizer in Rails development with `DISABLE_TYPELIZER` environment variable to `true` ([@okuramasafumi])
+
+## Fixes
+
+- Do not override `Typelizer.dirs` in the railtie initializer ([@patvice])
+- Do not raise on empty nested serializers ([@skryukov])
+- Attribute options merging in inherited serializers ([@envek])
+- Allow recursive type definition ([@okuramasafumi])
+
 ## [0.1.5] - 2024-10-07
 
 ## Fixed
@@ -58,10 +75,13 @@ and this project adheres to [Semantic Versioning].
 - Initial release ([@skryukov])
 
 [@davidrunger]: https://github.com/davidrunger
-[@okuramasafumi]: https://github.com/@okuramasafumi
+[@envek]: https://github.com/envek
+[@okuramasafumi]: https://github.com/okuramasafumi
+[@patvice]: https://github.com/patvice
 [@skryukov]: https://github.com/skryukov
 
-[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.1.5...HEAD
+[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/skryukov/typelizer/compare/v0.1.5...v0.2.0
 [0.1.5]: https://github.com/skryukov/typelizer/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/skryukov/typelizer/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/skryukov/typelizer/compare/v0.1.2...v0.1.3

data/README.md

@@ -14,6 +14,7 @@ Typelizer is a Ruby gem that automatically generates TypeScript interfaces from
   - [TypeScript Integration](#typescript-integration)
   - [Manual Generation](#manual-generation)
   - [Automatic Generation in Development](#automatic-generation-in-development)
+  - [Disabling Typelizer](#disabling-typelizer)
 - [Configuration](#configuration)
   - [Global Configuration](#global-configuration)
   - [Config Options](#config-options)
@@ -79,9 +80,34 @@ class PostResource < ApplicationResource
   attribute :author_name do |post|
     post.author.name
   end
+
+  typelize :string, nullable: true, comment: "Author's avatar URL"
+  attribute :avatar do
+    "https://example.com/avatar.png" if active?
+  end
 end
 ```
 
+`typelize` can be used with a Hash to specify multiple types at once.
+
+```ruby
+class PostResource < ApplicationResource
+  attributes :id, :title, :body, :published_at
+
+  attribute :author_name do |post|
+    post.author.name
+  end
+
+  typelize author_name: :string, published_at: :string
+end
+```
+
+You can also specify more complex type definitions using a lower-level API:
+
+```ruby
+typelize attribute_name: ["string", "Date", optional: true, nullable: true, multi: true, enum: %w[foo bar], comment: "Attribute description"]
+```
+
 ### TypeScript Integration
 
 Typelizer generates TypeScript interfaces in the specified output directory:
@@ -91,6 +117,7 @@ Typelizer generates TypeScript interfaces in the specified output directory:
 export interface Post {
   id: number;
   title: string;
+  category?: "news" | "article" | "blog" | null;
   body: string;
   published_at: string | null;
   author_name: string;
@@ -156,11 +183,15 @@ See the [Configuration](#configuration) section for more options.
 
 ### Manual Generation
 
-To manually generate TypeScript interfaces:
+To manually generate TypeScript interfaces use one of the following commands:
 
-```
-$ rails typelizer:generate
-```
+```bash
+# Generate new interfaces
+rails typelizer:generate
+
+# Clean output directory and regenerate all interfaces
+rails typelizer:generate:refresh
+````
 
 ### Automatic Generation in Development
 
@@ -170,6 +201,10 @@ When [Listen](https://github.com/guard/listen) is installed, Typelizer automatic
 Typelizer.listen = false
 ```
 
+### Disabling Typelizer
+
+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.
+
 ## Configuration
 
 ### Global Configuration
@@ -227,6 +262,14 @@ Typelizer.configure do |config|
   # List of type names that should be considered global in TypeScript
   # (i.e. not prefixed with the import path)
   config.types_global << %w[Array Date Record File FileList]
+
+  # Support TypeScript's Verbatim module syntax option (default: false)
+  # Will change imports and exports of types from default to support this syntax option
+  config.verbatim_module_syntax = false
+
+  # Support comments in generated TypeScript interfaces (default: false)
+  # Will add comments to the generated interfaces
+  config.comments = false
 end
 ```
 

data/lib/tasks/generate.rake

@@ -1,14 +1,27 @@
 namespace :typelizer do
   desc "Generate TypeScript interfaces from serializers"
   task generate: :environment do
+    benchmark do
+      Typelizer::Generator.call
+    end
+  end
+
+  desc "Removes all files in output folder and refreshs all generate TypeScript interfaces from serializers"
+  task "generate:refresh": :environment do
+    benchmark do
+      Typelizer::Generator.call(force: true)
+    end
+  end
+
+  def benchmark(&block)
     require "benchmark"
 
-    ENV["TYPELIZER"] = "true"
+    ENV["DISABLE_TYPELIZER"] = "false"
 
     puts "Generating TypeScript interfaces..."
     serializers = []
     time = Benchmark.realtime do
-      serializers = Typelizer::Generator.call
+      serializers = block.call
     end
 
     puts "Finished in #{time} seconds"

data/lib/typelizer/config.rb

@@ -24,6 +24,8 @@ module Typelizer
     :output_dir,
     :types_import_path,
     :types_global,
+    :verbatim_module_syntax,
+    :comments,
     keyword_init: true
   ) do
     class << self
@@ -45,13 +47,15 @@ module Typelizer
 
           type_mapping: TYPE_MAPPING,
           null_strategy: :nullable,
+          comments: false,
 
           output_dir: js_root.join("types/serializers"),
 
           types_import_path: "@/types",
           types_global: %w[Array Date Record File FileList],
 
-          properties_transformer: nil
+          properties_transformer: nil,
+          verbatim_module_syntax: false
         )
       end
 
@@ -70,7 +74,6 @@ module Typelizer
 
       def method_missing(method, *args, &block)
         return Typelizer.send(method, *args, &block) if Typelizer.respond_to?(method)
-
         instance.send(method, *args, &block)
       end
     end

data/lib/typelizer/dsl.rb

@@ -64,9 +64,11 @@ module Typelizer
 
         unless respond_to?(attribute_name)
           define_singleton_method(attribute_name) do
-            result = instance_variable_get(instance_variable)
+            result = instance_variable_get(instance_variable) || {}
             if superclass.respond_to?(attribute_name)
-              result.merge(superclass.send(attribute_name))
+              result.merge(superclass.send(attribute_name)) do |key, currentdef, supervaldef|
+                supervaldef.merge(currentdef)
+              end
             else
               result
             end

data/lib/typelizer/generator.rb

@@ -2,8 +2,8 @@
 
 module Typelizer
   class Generator
-    def self.call
-      new.call
+    def self.call(**args)
+      new.call(**args)
     end
 
     def initialize(config = Typelizer::Config)
@@ -16,14 +16,18 @@ module Typelizer
     def call(force: false)
       return unless Typelizer.enabled?
 
-      read_serializers
-
-      interfaces = target_serializers.map(&:typelizer_interface).reject(&:empty?)
       writer.call(interfaces, force: force)
 
       interfaces
     end
 
+    def interfaces
+      @interfaces ||= begin
+        read_serializers
+        target_serializers.map(&:typelizer_interface).reject(&:empty?)
+      end
+    end
+
     private
 
     def target_serializers

data/lib/typelizer/interface.rb

@@ -66,7 +66,7 @@ module Typelizer
         .uniq
         .reject { |type| global_type?(type) }
 
-      (custom_type_imports + serializer_types).uniq
+      (custom_type_imports + serializer_types).uniq - Array(self_type_name)
     end
 
     def inspect
@@ -75,6 +75,10 @@ module Typelizer
 
     private
 
+    def self_type_name
+      serializer.name.match(/(\w+::)?(\w+)(Serializer|Resource)/)[2]
+    end
+
     def extract_typescript_types(type)
       type.split(/[<>\[\],\s|]+/)
     end
@@ -87,7 +91,12 @@ module Typelizer
       props.map do |prop|
         if serializer.respond_to?(hash_name)
           dsl_type = serializer.public_send(hash_name)[prop.name.to_sym]
-          next Property.new(prop.to_h.merge(dsl_type)) if dsl_type&.any?
+          if dsl_type&.any?
+            next Property.new(prop.to_h.merge(dsl_type)).tap do |property|
+              property.comment ||= model_plugin.comment_for(property) if config.comments && property.comment != false
+              property.enum ||= model_plugin.enum_for(property) if property.enum != false
+            end
+          end
         end
 
         model_plugin.infer_types(prop)

data/lib/typelizer/model_plugins/active_record.rb

@@ -2,14 +2,14 @@ module Typelizer
   module ModelPlugins
     class ActiveRecord
       def initialize(model_class:, config:)
-        @columns_hash = model_class&.columns_hash || {}
+        @model_class = model_class
         @config = config
       end
 
-      attr_reader :columns_hash, :config
+      attr_reader :model_class, :config
 
       def infer_types(prop)
-        column = columns_hash[prop.column_name.to_s]
+        column = model_class&.columns_hash&.dig(prop.column_name.to_s)
         return prop unless column
 
         prop.multi = !!column.try(:array)
@@ -26,9 +26,25 @@ module Typelizer
         end
 
         prop.type = @config.type_mapping[column.type]
+        prop.comment = comment_for(prop)
+        prop.enum = enum_for(prop)
+        prop.type = :string if prop.enum # Ignore underlying column type for enums
 
         prop
       end
+
+      def comment_for(prop)
+        column = model_class&.columns_hash&.dig(prop.column_name.to_s)
+        return nil unless column
+
+        prop.comment = column.comment
+      end
+
+      def enum_for(prop)
+        return unless model_class&.defined_enums&.key?(prop.column_name.to_s)
+
+        prop.enum = model_class.defined_enums[prop.column_name.to_s].keys
+      end
     end
   end
 end

data/lib/typelizer/model_plugins/poro.rb

@@ -8,6 +8,14 @@ module Typelizer
       def infer_types(prop)
         prop
       end
+
+      def comment_for(prop)
+        nil
+      end
+
+      def enum_for(prop)
+        nil
+      end
     end
   end
 end

data/lib/typelizer/property.rb

@@ -1,7 +1,7 @@
 module Typelizer
   Property = Struct.new(
     :name, :type, :optional, :nullable,
-    :multi, :column_name,
+    :multi, :column_name, :comment, :enum,
     keyword_init: true
   ) do
     def inspect
@@ -20,6 +20,8 @@ module Typelizer
     private
 
     def type_name
+      return enum.map { |v| v.to_s.inspect }.join(" | ") if enum
+
       type.respond_to?(:name) ? type.name : type || "unknown"
     end
   end

data/lib/typelizer/railtie.rb

@@ -6,10 +6,12 @@ module Typelizer
 
     initializer "typelizer.configure" do
       Typelizer.configure do |c|
-        c.dirs = [
-          Rails.root.join("app", "resources"),
-          Rails.root.join("app", "serializers")
-        ]
+        if c.dirs.empty?
+          c.dirs = [
+            Rails.root.join("app", "resources"),
+            Rails.root.join("app", "serializers")
+          ]
+        end
       end
     end
 

data/lib/typelizer/templates/index.ts.erb

@@ -1,3 +1,7 @@
 <%- interfaces.each do |interface| -%>
+<%- if interface.config.verbatim_module_syntax -%>
+export type { <%= interface.name %> } from './<%= interface.filename %>'
+<%- else -%>
 export type { default as <%= interface.name %> } from './<%= interface.filename %>'
 <%- end -%>
+<%- end -%>

data/lib/typelizer/templates/interface.ts.erb

@@ -18,9 +18,14 @@ type <%= interface.name %> = {
 <%- else -%>
 type <%= interface.name %> = {
 <%- interface.properties.each do |property| -%>
+<%= indent("/** #{property.comment.split("\n").map(&:strip).join("\n * ")} */\n") if interface.config.comments && property.comment -%>
 <%= indent(property) %>;
 <%- end -%>
 }
 <%- end -%>
 
+<%-if interface.config.verbatim_module_syntax -%>
+export type { <%= interface.name %> };
+<%- else -%>
 export default <%= interface.name %>;
+<%- end -%>

data/lib/typelizer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typelizer
-  VERSION = "0.1.5"
+  VERSION = "0.2.0"
 end

data/lib/typelizer.rb

@@ -26,7 +26,9 @@ require "logger"
 module Typelizer
   class << self
     def enabled?
-      ENV["RAILS_ENV"] == "development" || ENV["RACK_ENV"] == "development" || ENV["TYPELIZER"] == "true"
+      return false if ENV["DISABLE_TYPELIZER"] == "true" || ENV["DISABLE_TYPELIZER"] == "1"
+
+      ENV["RAILS_ENV"] == "development" || ENV["RACK_ENV"] == "development" || ENV["DISABLE_TYPELIZER"] == "false"
     end
 
     attr_accessor :dirs

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typelizer
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2024-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -82,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
 summary: A TypeScript type generator for Ruby serializers.