typelizer 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 391ff3345874135d72e3875c60aff109ebfd8ce98b0766e51dd1d2a8909e2af9
-  data.tar.gz: 1a3c12dad42402fc5485f3124660e2376db4f8dec7b36d016a8d48a33d568fa0
+  metadata.gz: ed3e7b6339e4a79168c10afd541bba9ea8c509b00f689465df037501327ac6e2
+  data.tar.gz: a7f079a7ad377d1f2754cc1efcb98a7bc0e8af11c3910e8f56b648090ddb7f46
 SHA512:
-  metadata.gz: 6111652d2f134f20fa6450c1eccaf592a1bade20e0325b49b43a55628e9ac4f7eab1dfbfad09df0aa28893ae898571ccb486d92aa79f23cce682ab3d0c61b8d4
-  data.tar.gz: 1b73e070ce4dc50cc87d1a589a286afffcca8f42f596a6172e9b236e9911c72b45ea391d8e7b20ac8321eb83bb488f871c48d67e2a5ece6672530e0e897a6689
+  metadata.gz: 7687ff8e061c46e11f56421684a5629a823debc4d76ac3018e3ab7ac960416a05088662372b38bb4029a650ba6d81c74fbccb49d9821d7864f86023fdddd819e
+  data.tar.gz: 860d8dc24a04302c2e70d30a4ef6811f595ee4e55788ab47d6966c10a405370dc756419b06e15b343b00fc38d495897e706d5be5a5fb1816b9a0da3315c009ce

data/CHANGELOG.md

@@ -5,7 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog],
 and this project adheres to [Semantic Versioning].
 
-## [Unreleased]
+## [0.4.0] - 2025-05-03
+
+### Added 
+
+- Support for `panko_serializer` gem ([@PedroAugustoRamalhoDuarte], [@skryukov])
+- Mark `has_one` and `belongs_to` association as nullable. ([@skryukov])
+
+  By default, `has_one` associations are marked as nullable in TypeScript interfaces.
+  `belongs_to` associations are marked as nullable if the database column is nullable.
+  Use the new `config.associations_strategy = :active_record` configuration option to mark associations as nullable based on the `required`/`optional` options.  
+  You can also use the type hint `typelize latest_post: {nullable: false}` in the serializer to override the defaults.
+
+- Support inherited typelization. ([@skryukov])
+
+  Set `config.inheritance_strategy = :inheritance` to make Typelizer respect the inheritance hierarchy of serializers:
+
+  ```ruby
+    class AdminSerializer < UserSerializer
+      attributes :admin_level
+    end
+  ```
+  
+  ```typescript
+    // app/javascript/types/serializers/Admin.ts
+    import { User } from "@/types";
+    
+    export type Admin = User & {
+      admin_level: number;
+    }
+  ```
+  
+### Fixed
+
+- Alba: always use strings for keys in properties. ([@skryukov])
+  This change will fire update of all hashes for Alba serializers, but it's necessary to support inheritance strategy.
 
 ## [0.3.0] - 2025-02-28
 
@@ -116,7 +150,8 @@ and this project adheres to [Semantic Versioning].
 [@patvice]: https://github.com/patvice
 [@skryukov]: https://github.com/skryukov
 
-[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/skryukov/typelizer/compare/v0.3.0...v0.4.0
 [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

data/README.md

@@ -29,7 +29,7 @@ Typelizer is a Ruby gem that automatically generates TypeScript interfaces from
 ## Features
 
 - Automatic TypeScript interface generation
-- Support for multiple serializer libraries (`Alba`, `ActiveModel::Serializer`, `Oj::Serializer`)
+- Support for multiple serializer libraries (`Alba`, `ActiveModel::Serializer`, `Oj::Serializer`, `Panko::Serializer`)
 - File watching and automatic regeneration in development
 
 ## Installation
@@ -50,6 +50,10 @@ Include the Typelizer DSL in your serializers:
 class ApplicationResource
   include Alba::Resource
   include Typelizer::DSL
+
+  # For Alba, we recommend using the `helper` method instead of `include`.
+  # See the documentation: https://github.com/okuramasafumi/alba/blob/main/README.md#helper
+  # helper Typelizer::DSL
 end
 
 class PostResource < ApplicationResource
@@ -252,6 +256,16 @@ Typelizer.configure do |config|
   # Strategy for handling null values (:nullable, :optional, or :nullable_and_optional)
   config.null_strategy = :nullable
 
+  # Strategy for handling serializer inheritance (:none, :inheritance)
+  # :none - lists all attributes of the serializer in the type
+  # :inheritance - extends the type from the parent serializer
+  config.inheritance_strategy = :none
+
+  # Strategy for handling `has_one` and `belongs_to` associations nullability (:database, :active_record)
+  # :database - uses the database column nullability
+  # :active_record - uses the `required` / `optional` association options
+  config.associations_strategy = :database
+
   # Directory where TypeScript interfaces will be generated
   config.output_dir = Rails.root.join("app/javascript/types/serializers")
 

data/lib/typelizer/config.rb

@@ -25,6 +25,8 @@ module Typelizer
     :types_import_path,
     :types_global,
     :verbatim_module_syntax,
+    :inheritance_strategy,
+    :associations_strategy,
     :comments,
     keyword_init: true
   ) do
@@ -47,6 +49,8 @@ module Typelizer
 
           type_mapping: TYPE_MAPPING,
           null_strategy: :nullable,
+          inheritance_strategy: :none,
+          associations_strategy: :database,
           comments: false,
 
           output_dir: js_root.join("types/serializers"),

data/lib/typelizer/interface.rb

@@ -17,7 +17,7 @@ module Typelizer
 
     def name
       if inline?
-        Renderer.new("inline_type.ts.erb").call(properties: properties).strip
+        Renderer.call("inline_type.ts.erb", properties: properties).strip
       else
         config.serializer_name_mapper.call(serializer).tr_s(":", "")
       end
@@ -53,20 +53,46 @@ module Typelizer
       end
     end
 
+    def overwritten_properties
+      return [] unless parent_interface
+
+      @overwritten_properties ||= parent_interface.properties - properties
+    end
+
+    def own_properties
+      @own_properties ||= properties - (parent_interface&.properties || [])
+    end
+
+    def properties_to_print
+      parent_interface ? own_properties : properties
+    end
+
+    def parent_interface
+      return if config.inheritance_strategy == :none
+      return unless serializer.superclass.respond_to?(:typelizer_interface)
+
+      interface = serializer.superclass.typelizer_interface
+      return if interface.empty?
+
+      interface
+    end
+
     def imports
-      association_serializers, attribute_types = properties.filter_map(&:type)
-        .uniq
-        .partition { |type| type.is_a?(Interface) }
+      @imports ||= begin
+        association_serializers, attribute_types = properties_to_print.filter_map(&:type)
+          .uniq
+          .partition { |type| type.is_a?(Interface) }
 
-      serializer_types = association_serializers
-        .filter_map { |interface| interface.name if interface.name != name && !interface.inline? }
+        serializer_types = association_serializers
+          .filter_map { |interface| interface.name if interface.name != name && !interface.inline? }
 
-      custom_type_imports = attribute_types
-        .flat_map { |type| extract_typescript_types(type.to_s) }
-        .uniq
-        .reject { |type| global_type?(type) }
+        custom_type_imports = attribute_types
+          .flat_map { |type| extract_typescript_types(type.to_s) }
+          .uniq
+          .reject { |type| global_type?(type) }
 
-      (custom_type_imports + serializer_types).uniq - Array(self_type_name)
+        (custom_type_imports + serializer_types + Array(parent_interface&.name)).uniq - Array(self_type_name)
+      end
     end
 
     def inspect
@@ -74,7 +100,7 @@ module Typelizer
     end
 
     def fingerprint
-      "<#{self.class.name} #{name} properties=[#{properties.map(&:fingerprint).join(", ")}]>"
+      "<#{self.class.name} #{name} properties=[#{properties_to_print.map(&:fingerprint).join(", ")}]>"
     end
 
     private

data/lib/typelizer/model_plugins/active_record.rb

@@ -9,6 +9,30 @@ module Typelizer
       attr_reader :model_class, :config
 
       def infer_types(prop)
+        if (association = model_class&.reflect_on_association(prop.column_name.to_sym))
+          case association.macro
+          when :belongs_to
+            foreign_key = association.foreign_key
+            column = model_class&.columns_hash&.dig(foreign_key.to_s)
+            if config.associations_strategy == :database
+              prop.nullable = column.null if column
+            elsif config.associations_strategy == :active_record
+              prop.nullable = !association.options[:required] || association.options[:optional]
+            else
+              raise "Unknown associations strategy: #{config.associations_strategy}"
+            end
+          when :has_one
+            if config.associations_strategy == :database
+              prop.nullable = true
+            elsif config.associations_strategy == :active_record
+              prop.nullable = !association.options[:required]
+            else
+              raise "Unknown associations strategy: #{config.associations_strategy}"
+            end
+          end
+          return prop
+        end
+
         column = model_class&.columns_hash&.dig(prop.column_name.to_s)
         return prop unless column
 

data/lib/typelizer/model_plugins/poro.rb

@@ -1,7 +1,7 @@
 module Typelizer
   module ModelPlugins
     class Poro
-      # We don't care about intialization
+      # We don't care about initialization
       def initialize(...)
       end
 

data/lib/typelizer/property.rb

@@ -9,6 +9,12 @@ module Typelizer
       "<#{self.class.name} #{props}>"
     end
 
+    def eql?(other)
+      return false unless other.is_a?(self.class)
+
+      fingerprint == other.fingerprint
+    end
+
     def to_s
       type_str = type_name
       type_str = "Array<#{type_str}>" if multi

data/lib/typelizer/renderer.rb

@@ -4,6 +4,10 @@ require "erb"
 
 module Typelizer
   class Renderer
+    def self.call(template, **context)
+      new(template).call(**context)
+    end
+
     def initialize(template)
       @erb = ERB.new(File.read(File.join(File.dirname(__FILE__), "templates/#{template}")), trim_mode: "-")
     end
@@ -24,5 +28,9 @@ module Typelizer
       spaces = " " * multiplier
       content.to_s.each_line.map { |line| line.blank? ? line : "#{spaces}#{line}" }.join
     end
+
+    def render(template, **context)
+      Renderer.call(template, **context)
+    end
   end
 end

data/lib/typelizer/serializer_plugins/alba.rb

@@ -13,7 +13,7 @@ module Typelizer
 
       def properties
         serializer._attributes.map do |name, attr|
-          build_property(name, attr)
+          build_property(name.is_a?(Symbol) ? name.name : name, attr)
         end
       end
 

data/lib/typelizer/serializer_plugins/auto.rb

@@ -13,6 +13,8 @@ module Typelizer
             Alba
           elsif defined?(ActiveModel::Serializer) && serializer.ancestors.include?(ActiveModel::Serializer)
             AMS
+          elsif defined?(::Panko::Serializer) && serializer.ancestors.include?(::Panko::Serializer)
+            Panko
           else
             raise "Can't guess serializer plugin for #{serializer}. " \
                     "Please specify it with `config.serializer_plugin`."

data/lib/typelizer/serializer_plugins/panko.rb

@@ -0,0 +1,63 @@
+require_relative "base"
+
+module Typelizer
+  module SerializerPlugins
+    class Panko < Base
+      def methods_to_typelize
+        [:has_many, :has_one, :attributes, :method_added]
+      end
+
+      def properties
+        descriptor = serializer.new.instance_variable_get(:@descriptor)
+        attributes = descriptor.attributes
+        methods_attributes = descriptor.method_fields
+        has_many_associations = descriptor.has_many_associations
+        has_one_associations = descriptor.has_one_associations
+
+        attributes.map do |att|
+          attribute_property(att)
+        end + methods_attributes.map do |att|
+          attribute_property(att)
+        end + has_many_associations.map do |assoc|
+          association_property(assoc, multi: true)
+        end + has_one_associations.map do |assoc|
+          association_property(assoc, multi: false)
+        end
+      end
+
+      def typelize_method_transform(method:, name:, binding:, type:, attrs:)
+        if method == :method_added && binding.local_variable_defined?(:method)
+          name = binding.local_variable_get(:method)
+        end
+
+        super
+      end
+
+      private
+
+      def attribute_property(att)
+        Property.new(
+          name: att.alias_name || att.name,
+          optional: false,
+          nullable: false,
+          multi: false,
+          column_name: att.name
+        )
+      end
+
+      def association_property(assoc, multi: false)
+        key = assoc.name_str
+        serializer = assoc.descriptor.type
+        type = serializer ? Interface.new(serializer: serializer) : nil
+        Property.new(
+          name: key,
+          type: type,
+          optional: false,
+          nullable: false,
+          multi: multi,
+          column_name: key
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+<%
+comment = ""
+comment += property.comment.to_s if interface.config.comments
+if property.deprecated
+  comment += "\n@deprecated #{property.deprecated.is_a?(String) ? property.deprecated : ''}"
+end
+-%>
+<%= indent("/** #{comment.strip.split("\n").map(&:strip).join("\n * ")} */\n") unless comment.empty? -%>

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

@@ -0,0 +1 @@
+<%= interface.overwritten_properties.any? ? "Omit<" : "" %><%= interface.parent_interface.name %><%= "['#{interface.parent_interface.root_key}']" if interface.parent_interface.root_key %><%= interface.overwritten_properties.any? ? ", " + interface.overwritten_properties.map { |pr| "'#{pr.name}'" }.join(' | ') + ">" : ""%>

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

@@ -1,34 +1,28 @@
-<%- if interface.imports.any? -%>
+<% if interface.imports.any? -%>
 import type {<%= interface.imports.join(", ") %>} from '<%= interface.config.types_import_path %>'
-<%- end -%>
+<% end -%>
 
-<%- if interface.root_key -%>
-type <%= interface.name %>Data = {
-<%- interface.properties.each do |property| -%>
+type <%= interface.name %><%= "Data" if interface.root_key %> = <%=
+render("inheritance.ts.erb", interface: interface).strip if interface.parent_interface
+-%>
+<% unless interface.parent_interface && interface.properties_to_print.empty? -%>
+<%= " & " if interface.parent_interface %>{
+<% interface.properties_to_print.each do |property| -%>
+<%= render("comment.ts.erb", interface: interface, property: property) -%>
 <%= indent(property) %>;
-<%- end -%>
+<% end -%>
 }
-
-type <%= interface.name %> = {
-  <%= interface.root_key %>: <%= interface.name %>Data;
-<%- interface.meta_fields&.each do |property| -%>
-<%= indent(property) %>;
-<%- end -%>
-}
-<%- else -%>
+<% end %><% if interface.root_key %>
 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(interface.root_key) %>: <%= interface.name %>Data;
+<% interface.meta_fields&.each do |property| -%>
 <%= indent(property) %>;
-<%- end -%>
+<% end -%>
 }
-<%- end -%>
+<% end -%>
 
-<%-if interface.config.verbatim_module_syntax -%>
+<% if interface.config.verbatim_module_syntax -%>
 export type { <%= interface.name %> };
-<%- else -%>
+<% else -%>
 export default <%= interface.name %>;
-<%- end -%>
+<% end -%>

data/lib/typelizer/version.rb

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

data/lib/typelizer.rb

@@ -14,6 +14,7 @@ require_relative "typelizer/serializer_plugins/auto"
 require_relative "typelizer/serializer_plugins/oj_serializers"
 require_relative "typelizer/serializer_plugins/alba"
 require_relative "typelizer/serializer_plugins/ams"
+require_relative "typelizer/serializer_plugins/panko"
 
 require_relative "typelizer/model_plugins/active_record"
 require_relative "typelizer/model_plugins/poro"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: typelizer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov
 bindir: bin
 cert_chain: []
-date: 2025-02-28 00:00:00.000000000 Z
+date: 2025-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -50,8 +50,11 @@ files:
 - lib/typelizer/serializer_plugins/auto.rb
 - lib/typelizer/serializer_plugins/base.rb
 - lib/typelizer/serializer_plugins/oj_serializers.rb
+- lib/typelizer/serializer_plugins/panko.rb
+- lib/typelizer/templates/comment.ts.erb
 - lib/typelizer/templates/fingerprint.ts.erb
 - lib/typelizer/templates/index.ts.erb
+- lib/typelizer/templates/inheritance.ts.erb
 - lib/typelizer/templates/inline_type.ts.erb
 - lib/typelizer/templates/interface.ts.erb
 - lib/typelizer/version.rb