typelizer 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52c5a98a49d5f7a6f040da23ce1ff5c7b8453a758c0daae251788189be0fc874
-  data.tar.gz: f0b023ec773a121a30d5ee587118dad4c30b36f33309e34e4d07fb77b32a93fd
+  metadata.gz: 391ff3345874135d72e3875c60aff109ebfd8ce98b0766e51dd1d2a8909e2af9
+  data.tar.gz: 1a3c12dad42402fc5485f3124660e2376db4f8dec7b36d016a8d48a33d568fa0
 SHA512:
-  metadata.gz: 6c4b5d39763829b212109356ac5f81967cbcd2340562bddf6bb116cd98d18e209e42f0d694d7fdb62241c661849591e75728250eb856929b68cdbdb4d54fd03a
-  data.tar.gz: 66635cbafdbc3babb70f92dd2a73b924954f7e7b3f22623397ef53c99d62f8c62c3daea754634833dd3909cdaaa4e03f6aa114c1d7156202aa8274ee2a77cc2e
+  metadata.gz: 6111652d2f134f20fa6450c1eccaf592a1bade20e0325b49b43a55628e9ac4f7eab1dfbfad09df0aa28893ae898571ccb486d92aa79f23cce682ab3d0c61b8d4
+  data.tar.gz: 1b73e070ce4dc50cc87d1a589a286afffcca8f42f596a6172e9b236e9911c72b45ea391d8e7b20ac8321eb83bb488f871c48d67e2a5ece6672530e0e897a6689

data/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-02-28
+
+### Added
+
+- Support transform keys. ([@patvice], [@skryukov])
+
+  Typelizer now respects `transform_keys`/`key_transform` configurations for all plugins.
+
+- Support typing method def in Alba. ([@patvice])
+
+  The `typelize` helper now can be used before a method definition:
+
+  ```ruby
+  class UserResource < ApplicationResource
+    attributes :id, :name, :email, :chars_in_name
+
+    typelize :number
+    def chars_in_name(obj)
+      obj.name.chars.count
+    end
+  end
+  ```
+
+- Support for deprecated attributes. ([@Envek])
+
+  They will be marked as deprecated using JSDoc [`@deprecated` tag](https://jsdoc.app/tags-deprecated) in TypeScript interface comments.
+
+  In ActiveModel::Serializer attributes `deprecated` option is recognized.
+
+  For other serializers, you can use `deprecated` option of `typelize` method.
+
+### Fixed
+
+- Ignore `nil` values on fingerprint calculation. ([@Envek])
+
+## [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])
+- Allow to get interfaces without generating TypeScript files ([@Envek])
+
+## Fixed
+
+- 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 +111,14 @@ 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.3.0...HEAD
+[0.3.0]: https://github.com/skryukov/typelizer/compare/v0.2.0...v0.3.0
+[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", deprecated: "Use `another_attribute` instead"]
+```
+
 ### 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,15 +66,23 @@ 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
       "<#{self.class.name} #{name} properties=#{properties.inspect}>"
     end
 
+    def fingerprint
+      "<#{self.class.name} #{name} properties=[#{properties.map(&:fingerprint).join(", ")}]>"
+    end
+
     private
 
+    def self_type_name
+      serializer.name.match(/(\w+::)?(\w+)(Serializer|Resource)/)[2]
+    end
+
     def extract_typescript_types(type)
       type.split(/[<>\[\],\s|]+/)
     end
@@ -86,8 +94,13 @@ module Typelizer
     def infer_types(props, hash_name = :_typelizer_attributes)
       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?
+          dsl_type = serializer.public_send(hash_name)[prop.column_name.to_sym]
+          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, :deprecated,
     keyword_init: true
   ) do
     def inspect
@@ -17,9 +17,16 @@ module Typelizer
       "#{name}#{"?" if optional}: #{type_str}"
     end
 
+    def fingerprint
+      props = to_h.merge(type: type_name).reject { |_, v| v.nil? }.map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+      "<#{self.class.name} #{props}>"
+    end
+
     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/serializer_plugins/alba.rb

@@ -22,19 +22,31 @@ module Typelizer
           :association, :one, :has_one,
           :many, :has_many,
           :attributes, :attribute,
+          :method_added,
           :nested_attribute, :nested,
           :meta
         ]
       end
 
       def typelize_method_transform(method:, name:, binding:, type:, attrs:)
-        return {name => [type, attrs.merge(multi: true)]} if [:many, :has_many].include?(method)
+        if method == :method_added && binding.local_variable_defined?(:method_name)
+          name = binding.local_variable_get(:method_name)
+        end
+
+        if [:many, :has_many].include?(method)
+          return {name => [type, attrs.merge(multi: true)]}
+        end
 
         super
       end
 
       def root_key
-        serializer.new({}).send(:_key)
+        root = serializer.new({}).send(:_key)
+        if !root.nil? && has_transform_key?(serializer) && should_transform_root_key?(serializer)
+          fetch_key(serializer, root)
+        else
+          root
+        end
       end
 
       def meta_fields
@@ -51,6 +63,12 @@ module Typelizer
       private
 
       def build_property(name, attr, **options)
+        column_name = name
+
+        if has_transform_key?(serializer)
+          name = fetch_key(serializer, name)
+        end
+
         case attr
         when Symbol
           Property.new(
@@ -59,7 +77,7 @@ module Typelizer
             optional: false,
             nullable: false,
             multi: false,
-            column_name: name,
+            column_name: column_name,
             **options
           )
         when Proc
@@ -69,7 +87,7 @@ module Typelizer
             optional: false,
             nullable: false,
             multi: false,
-            column_name: nil,
+            column_name: column_name,
             **options
           )
         when ::Alba::Association
@@ -80,7 +98,7 @@ module Typelizer
             optional: false,
             nullable: false,
             multi: false, # we override this in typelize_method_transform
-            column_name: name,
+            column_name: column_name,
             **options
           )
         when ::Alba::TypedAttribute
@@ -91,7 +109,7 @@ module Typelizer
             # not sure if that's a good default tbh
             nullable: !alba_type.instance_variable_get(:@auto_convert),
             multi: false,
-            column_name: name,
+            column_name: column_name,
             **ts_mapper[alba_type.name.to_s],
             **options
           )
@@ -102,7 +120,7 @@ module Typelizer
             optional: false,
             nullable: false,
             multi: false,
-            column_name: nil,
+            column_name: column_name,
             **options
           )
         when ::Alba::ConditionalAttribute
@@ -112,6 +130,18 @@ module Typelizer
         end
       end
 
+      def has_transform_key?(serializer)
+        serializer._transform_type != :none
+      end
+
+      def should_transform_root_key?(serializer)
+        serializer._transforming_root_key
+      end
+
+      def fetch_key(serializer, key)
+        ::Alba.transform_key(key, transform_type: serializer._transform_type)
+      end
+
       private
 
       def ts_mapper

data/lib/typelizer/serializer_plugins/ams.rb

@@ -19,11 +19,13 @@ module Typelizer
       def properties
         serializer._attributes_data.merge(serializer._reflections).flat_map do |key, association|
           type = association.options[:serializer] ? Interface.new(serializer: association.options[:serializer]) : nil
+          adapter = ActiveModelSerializers::Adapter.configured_adapter
           Property.new(
-            name: key.to_s,
+            name: adapter.transform_key_casing!(key.to_s, association.options),
             type: type,
             optional: association.options.key?(:if) || association.options.key?(:unless),
             multi: association.respond_to?(:collection?) && association.collection?,
+            deprecated: (association.options[:deprecated] if association.options.key?(:deprecated)),
             column_name: association.name.to_s
           )
         end

data/lib/typelizer/serializer_plugins/oj_serializers.rb

@@ -11,7 +11,11 @@ module Typelizer
       end
 
       def properties
-        serializer._attributes
+        transform_keys = serializer.try(:_transform_keys)
+        attributes = serializer._attributes
+        attributes = attributes.transform_keys(&transform_keys) if transform_keys
+
+        attributes
           .flat_map do |key, options|
             if options[:association] == :flat
               Interface.new(serializer: options.fetch(:serializer)).properties

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,17 @@ type <%= interface.name %> = {
 <%- else -%>
 type <%= interface.name %> = {
 <%- interface.properties.each do |property| -%>
+<%- comment = "" -%>
+<%- comment += property.comment.to_s if interface.config.comments -%>
+<%- comment += "\n@deprecated #{property.deprecated.is_a?(String) ? property.deprecated : ''}" if property.deprecated -%>
+<%= indent("/** #{comment.strip.split("\n").map(&:strip).join("\n * ")} */\n") unless comment.empty? -%>
 <%= 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.3.0"
 end

data/lib/typelizer/writer.rb

@@ -32,7 +32,7 @@ module Typelizer
     end
 
     def write_interface(interface)
-      write_file("#{interface.filename}.ts", interface.inspect) do
+      write_file("#{interface.filename}.ts", interface.fingerprint) do
         render_template("interface.ts.erb", interface: interface)
       end
     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,13 @@
 --- !ruby/object:Gem::Specification
 name: typelizer
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-07 00:00:00.000000000 Z
+date: 2025-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -67,7 +66,6 @@ metadata:
   homepage_uri: https://github.com/skryukov/typelizer
   source_code_uri: https://github.com/skryukov/typelizer
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -82,8 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A TypeScript type generator for Ruby serializers.
 test_files: []