typelizer 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 819c25a9bfc5dd74c3b7c77045bb5f5ef968f518f8a8d228502badb6936ea50d
-  data.tar.gz: c8d8d9affec2d6eb07cf1e58942fe46009fad2782c57689218b8357a85c227f0
+  metadata.gz: a0b21f5f78121c64717aa08d6556efbddc0b0b80a3ec6f272d63f699133fff12
+  data.tar.gz: d8df7c3542950c82e6b25d3f9c39ea808aded01fab0e5b5eaada3801a99031a3
 SHA512:
-  metadata.gz: b4b39192ff398bb25c6b537fcb5c73893de40d82f14a09a254e4ef8317a08232819c3285b7e6806938f1c7058f895d0100b03884574158bbaa2e329982518683
-  data.tar.gz: 8971c5a2cc78992fd38dc101e7b2fc1eaefe82ad756f828bca4416a4a6ed54d1ff25eace61fd80cd293cca3dc66b6b6c24706a0fa45156fb275eb9bfe4976c46
+  metadata.gz: cc42979e0f00e3aec338fdd4cf3848639ba12a2019293a46e864e908a1dfd8f2f2258ef62d07ed15ec3da66ca7ad740907ac63c6e04f9aae29f18db0eae46584
+  data.tar.gz: c9504167e013d6aeff1208207b4531f012fe942018e72368296d2a676fb04460ece7b0582a5ef297cf6c037e071ea0868e39c4632765030bdb014fe9a49884ea

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-02-19
+
+### Added
+
+- OpenAPI schema generation from serializers, supporting both OpenAPI 3.0 and 3.1. ([@skryukov])
+
+  ```ruby
+  # Get all schemas as a hash
+  Typelizer.openapi_schemas
+  # => { "Post" => { type: :object, properties: { ... }, required: [...] }, ... }
+
+  # OpenAPI 3.1 output
+  Typelizer.openapi_schemas(openapi_version: "3.1")
+  ```
+
+  Column types are automatically mapped to OpenAPI types with proper formats (`integer`, `int64`, `uuid`, `date-time`, etc.).
+  Enums, nullable fields, arrays, deprecated flags, and `$ref` associations are all handled automatically.
+
+- Type inference for delegated attributes (`delegate :name, to: :user`). Typelizer now tracks `delegate` calls on ActiveRecord models and resolves types from the target association's model, including support for `prefix` and `allow_nil` options. ([@skryukov])
+
+- Reference other serializers in `typelize` method by passing the class directly. ([@skryukov])
+
+- Per-writer `reject_class` configuration. Each writer can now define its own `reject_class` filter, enabling scoped output (e.g., only V1 serializers for a V1 writer). ([@skryukov])
+
+### Fixed
+
+- `typelize` DSL metadata (optional, comment, type overrides) now correctly applies to renamed attributes (e.g., via `key:`, `alias_name`, `value_from`). Previously, metadata was looked up only by `column_name`, missing attributes where the output name differs. ([@skryukov])
+
 ## [0.7.0] - 2026-01-15
 
 ### Changed
@@ -358,7 +386,8 @@ and this project adheres to [Semantic Versioning].
 [@prog-supdex]: https://github.com/prog-supdex
 [@ventsislaf]: https://github.com/ventsislaf
 
-[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/skryukov/typelizer/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/skryukov/typelizer/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/skryukov/typelizer/compare/v0.5.6...v0.6.0
 [0.5.6]: https://github.com/skryukov/typelizer/compare/v0.5.5...v0.5.6

data/README.md

@@ -16,6 +16,7 @@ Typelizer generates TypeScript types from your Ruby serializers. It supports mul
   - [Manual Generation](#manual-generation)
   - [Automatic Generation in Development](#automatic-generation-in-development)
   - [Disabling Typelizer](#disabling-typelizer)
+- [OpenAPI Schema Generation](#openapi-schema-generation)
 - [Configuration](#configuration)
   - [Global Configuration](#simple-configuration)
   - [Writers (multiple outputs)](#defining-multiple-writers)
@@ -128,6 +129,26 @@ class PostResource < ApplicationResource
 end
 ```
 
+You can reference other serializers directly by passing the class. Typelizer resolves the class to its generated type name automatically:
+
+```ruby
+class PostResource < ApplicationResource
+  attributes :id, :title
+
+  # Reference another serializer — resolves to its generated TypeScript type
+  typelize reviewer: [AuthorResource, {optional: true, nullable: true}]
+  attribute :reviewer do |post|
+    post.reviewer
+  end
+
+  # Self-reference works too
+  typelize previous_post: PostResource
+  attribute :previous_post do |post|
+    post.previous_post
+  end
+end
+```
+
 For more complex type definitions, use the full API:
 
 ```ruby
@@ -310,6 +331,60 @@ Typelizer.listen = false
 
 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.
 
+## OpenAPI Schema Generation
+
+Typelizer can generate [OpenAPI](https://swagger.io/specification/) component schemas from your serializers. This is useful for documenting your API or integrating with tools like [rswag](https://github.com/rswag/rswag).
+
+Get all schemas as a hash:
+
+```ruby
+Typelizer.openapi_schemas
+# => {
+#   "Post" => {
+#     type: :object,
+#     properties: {
+#       id: { type: :integer },
+#       title: { type: :string },
+#       published_at: { type: :string, format: :"date-time", nullable: true }
+#     },
+#     required: [:id, :title]
+#   },
+#   "Author" => { ... }
+# }
+```
+
+By default, schemas are generated for OpenAPI 3.0. Pass `openapi_version: "3.1"` for OpenAPI 3.1 output (e.g., `type: [:string, :null]` instead of `nullable: true`):
+
+```ruby
+Typelizer.openapi_schemas(openapi_version: "3.1")
+```
+
+Generate a schema for a single interface:
+
+```ruby
+interfaces = Typelizer.interfaces
+post_interface = interfaces.find { |i| i.name == "Post" }
+Typelizer::OpenAPI.schema_for(post_interface)
+Typelizer::OpenAPI.schema_for(post_interface, openapi_version: "3.1")
+```
+
+Column types are mapped to OpenAPI types automatically:
+
+| Column type | OpenAPI type | Format |
+|---|---|---|
+| `integer` | `integer` | |
+| `bigint` | `integer` | `int64` |
+| `float` | `number` | `float` |
+| `decimal` | `number` | `double` |
+| `boolean` | `boolean` | |
+| `string`, `text`, `citext` | `string` | |
+| `uuid` | `string` | `uuid` |
+| `date` | `string` | `date` |
+| `datetime` | `string` | `date-time` |
+| `time` | `string` | `time` |
+
+Enums, nullable fields, arrays, deprecated flags, and `$ref` associations are all handled automatically.
+
 ## Configuration
 
 Typelizer provides several global configuration options:

data/lib/tasks/generate.rake

@@ -19,13 +19,13 @@ namespace :typelizer do
     ENV["DISABLE_TYPELIZER"] = "false"
 
     puts "Generating TypeScript interfaces..."
-    serializers = []
     time = Benchmark.realtime do
-      serializers = block.call
+      block.call
     end
 
+    interfaces = Typelizer.interfaces
     puts "Finished in #{time} seconds"
-    puts "Found #{serializers.size} serializers:"
-    puts serializers.map { |s| "\t#{s.name}" }.join("\n")
+    puts "Found #{interfaces.size} serializers:"
+    puts interfaces.map { |i| "\t#{i.name}" }.join("\n")
   end
 end

data/lib/typelizer/config.rb

@@ -51,6 +51,7 @@ module Typelizer
     output_dir
     inheritance_strategy
     associations_strategy
+    reject_class
   ].freeze
 
   Config = Struct.new(
@@ -70,6 +71,7 @@ module Typelizer
     :verbatim_module_syntax,
     :inheritance_strategy,
     :associations_strategy,
+    :reject_class,
     :comments,
     :prefer_double_quotes,
     keyword_init: true
@@ -105,6 +107,7 @@ module Typelizer
         null_strategy: :nullable,
         inheritance_strategy: :none,
         associations_strategy: :database,
+        reject_class: ->(serializer:) { false },
         comments: false,
         prefer_double_quotes: false,
 

data/lib/typelizer/configuration.rb

@@ -18,12 +18,11 @@ module Typelizer
   class Configuration
     DEFAULT_WRITER_NAME = :default
 
-    attr_accessor :dirs, :reject_class, :listen
+    attr_accessor :dirs, :listen
     attr_reader :writers, :global_settings
 
     def initialize
       @dirs = []
-      @reject_class = ->(serializer:) { false }
       @listen = nil
 
       default = Config.build

data/lib/typelizer/delegate_tracker.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module DelegateTracker
+    @registry = {} # { Class => { method_name => { to:, allow_nil:, original: } } }
+
+    class << self
+      attr_reader :registry
+
+      def [](klass, method)
+        registry.dig(klass, method)
+      end
+    end
+
+    module Hook
+      def delegate(*methods, to:, allow_nil: nil, prefix: nil, **)
+        super.tap do
+          next unless is_a?(Class) && defined?(ActiveRecord::Base) && self < ActiveRecord::Base
+
+          method_prefix = if prefix == true
+            "#{to}_"
+          else
+            prefix ? "#{prefix}_" : ""
+          end
+          methods.each do |m|
+            (DelegateTracker.registry[self] ||= {})[:"#{method_prefix}#{m}"] = {to: to, allow_nil: !!allow_nil, original: m.to_sym}
+          end
+        end
+      end
+    end
+  end
+end
+
+Module.prepend(Typelizer::DelegateTracker::Hook) if Typelizer.enabled?

data/lib/typelizer/generator.rb

@@ -9,37 +9,12 @@ module Typelizer
     def call(force: false)
       return [] unless Typelizer.enabled?
 
-      load_serializers
-      serializers = target_serializers
-
       Typelizer.configuration.writers.each do |writer_name, writer_config|
-        context = WriterContext.new(writer_name: writer_name)
-        interfaces = serializers.map { |klass| context.interface_for(klass) }
+        interfaces = Typelizer.interfaces(writer_name: writer_name)
+        raise ArgumentError, "No serializers found. Please ensure all your serializers include Typelizer::DSL." if interfaces.empty?
 
         Writer.new(writer_config).call(interfaces, force: force)
       end
-
-      serializers
-    end
-
-    private
-
-    def load_serializers
-      Typelizer.dirs.flat_map { |dir| Dir["#{dir}/**/*.rb"] }.each do |file|
-        require file
-      end
-    end
-
-    def target_serializers
-      base_classes = Typelizer.base_classes.filter_map do |base_class|
-        Object.const_get(base_class) if Object.const_defined?(base_class)
-      end.tap do |base_classes|
-        raise ArgumentError, "Please ensure all your serializers include Typelizer::DSL." if base_classes.none?
-      end
-
-      (base_classes + base_classes.flat_map(&:descendants)).uniq
-        .reject { |serializer| Typelizer.reject_class.call(serializer: serializer) }
-        .sort_by(&:name)
     end
   end
 end

data/lib/typelizer/interface.rb

@@ -175,7 +175,7 @@ module Typelizer
       multi_attrs = serializer.respond_to?(:_typelizer_multi_attributes) ? serializer._typelizer_multi_attributes : Set.new
 
       props.map do |prop|
-        has_dsl = dsl_attrs[prop.column_name.to_sym]&.any?
+        has_dsl = dsl_attrs_for(prop, dsl_attrs)&.any?
 
         prop
           .then { |p| apply_dsl_type(p, dsl_attrs) }
@@ -185,13 +185,30 @@ module Typelizer
       end
     end
 
+    def dsl_attrs_for(prop, dsl_attrs)
+      dsl_attrs[prop.column_name.to_sym] || dsl_attrs[prop.name.to_sym]
+    end
+
     def apply_dsl_type(prop, dsl_attrs)
-      dsl_type = dsl_attrs[prop.column_name.to_sym]
+      dsl_type = dsl_attrs_for(prop, dsl_attrs)
       return prop unless dsl_type&.any?
 
+      dsl_type = resolve_class_type(dsl_type)
       prop.with(**dsl_type)
     end
 
+    def resolve_class_type(attrs)
+      type = attrs[:type]
+      return attrs unless type.is_a?(String) || type.is_a?(Symbol)
+
+      klass = Object.const_get(type.to_s)
+      return attrs unless klass.respond_to?(:typelizer_config)
+
+      attrs.merge(type: context.interface_for(klass))
+    rescue NameError
+      attrs
+    end
+
     def apply_model_inference(prop)
       model_plugin.infer_types(prop)
     end

data/lib/typelizer/model_plugins/active_record.rb

@@ -12,6 +12,7 @@ module Typelizer
         infer_types_for_association(prop) ||
           infer_types_for_column(prop) ||
           infer_types_for_association_ids(prop) ||
+          infer_types_for_delegate(prop) ||
           infer_types_for_attribute(prop)
 
         prop
@@ -66,6 +67,7 @@ module Typelizer
         column = model_class&.columns_hash&.dig(prop.column_name.to_s)
         return nil unless column
 
+        prop.column_type = column.type
         prop.multi = !!column.try(:array)
         case config.null_strategy
         when :nullable
@@ -100,6 +102,25 @@ module Typelizer
         prop
       end
 
+      def infer_types_for_delegate(prop)
+        return nil unless model_class
+
+        info = DelegateTracker[model_class, prop.column_name.to_sym]
+        return nil unless info
+
+        assoc = model_class.reflect_on_association(info[:to])
+        return nil unless assoc
+
+        target = assoc.klass
+        col = target.columns_hash[info[:original].to_s]
+        return nil unless col
+
+        prop.type = @config.type_mapping[col.type]
+        prop.multi = !!col.try(:array)
+        prop.nullable = col.null || info[:allow_nil]
+        prop
+      end
+
       def infer_types_for_attribute(prop)
         return nil unless model_class.respond_to?(:attribute_types)
 
@@ -111,9 +132,11 @@ module Typelizer
         end
 
         if attribute_type_obj.respond_to?(:subtype)
+          prop.column_type = attribute_type_obj.subtype.type
           prop.type = @config.type_mapping[attribute_type_obj.subtype.type]
           prop.multi = true
         elsif attribute_type_obj.respond_to?(:type)
+          prop.column_type = attribute_type_obj.type
           prop.type = @config.type_mapping[attribute_type_obj.type]
         end
 

data/lib/typelizer/openapi.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Typelizer
+  class OpenAPI
+    SUPPORTED_VERSIONS = ["3.0", "3.1"].freeze
+    OPENAPI_TYPES = %i[integer number string boolean object array null].freeze
+
+    COLUMN_TYPE_MAP = {
+      integer: {type: :integer},
+      bigint: {type: :integer, format: :int64},
+      decimal: {type: :number, format: :double},
+      float: {type: :number, format: :float},
+      boolean: {type: :boolean},
+      string: {type: :string},
+      text: {type: :string},
+      citext: {type: :string},
+      uuid: {type: :string, format: :uuid},
+      date: {type: :string, format: :date},
+      datetime: {type: :string, format: :"date-time"},
+      time: {type: :string, format: :time},
+      json: {type: :object},
+      jsonb: {type: :object},
+      binary: {type: :string, format: :binary},
+      inet: {type: :string},
+      cidr: {type: :string}
+    }.freeze
+
+    def self.schema_for(interface, openapi_version: "3.0")
+      raise ArgumentError, "Unsupported openapi_version: #{openapi_version}. Must be one of: #{SUPPORTED_VERSIONS.join(", ")}" unless SUPPORTED_VERSIONS.include?(openapi_version.to_s)
+
+      required_props = interface.properties.reject(&:optional).map(&:name)
+      schema = {
+        type: :object,
+        properties: interface.properties.to_h { |prop| [prop.name, property_schema(prop, openapi_version: openapi_version)] }
+      }
+      schema[:required] = required_props if required_props.any?
+      schema
+    end
+
+    def self.property_schema(property, openapi_version: "3.0")
+      raise ArgumentError, "Unsupported openapi_version: #{openapi_version}. Must be one of: #{SUPPORTED_VERSIONS.join(", ")}" unless SUPPORTED_VERSIONS.include?(openapi_version.to_s)
+
+      definition = base_type(property)
+      ref = definition.delete("$ref")
+
+      definition = if ref
+        ref_schema(ref, property, openapi_version: openapi_version)
+      else
+        inline_schema(definition, property, openapi_version: openapi_version)
+      end
+
+      if property.multi
+        definition = {type: :array, items: definition}
+        if property.nullable
+          if openapi_version.to_s >= "3.1"
+            definition[:type] = [:array, :null]
+          else
+            definition[:nullable] = true
+          end
+        end
+      end
+
+      definition
+    end
+
+    def self.ref_schema(ref, property, openapi_version:)
+      has_siblings = property.nullable || property.comment.is_a?(String) || property.deprecated
+      ref_obj = {"$ref" => ref}
+
+      if openapi_version.to_s >= "3.1"
+        definition = property.nullable ? {oneOf: [ref_obj, {type: :null}]} : ref_obj
+      else
+        # In 3.0, $ref must stand alone — use allOf wrapper when siblings are needed
+        definition = has_siblings ? {allOf: [ref_obj]} : ref_obj
+        definition[:nullable] = true if property.nullable
+      end
+
+      definition[:description] = property.comment if property.comment.is_a?(String)
+      definition[:deprecated] = true if property.deprecated
+      definition
+    end
+
+    def self.inline_schema(definition, property, openapi_version:)
+      # For multi properties, nullable is applied to the array container in property_schema
+      unless property.multi
+        if property.nullable
+          if openapi_version.to_s >= "3.1"
+            definition[:type] = [definition[:type], :null]
+          else
+            definition[:nullable] = true
+          end
+        end
+      end
+      definition[:description] = property.comment if property.comment.is_a?(String)
+      if property.enum.is_a?(Array)
+        items_nullable = !property.multi && property.nullable
+        definition[:enum] = (items_nullable && !property.enum.include?(nil)) ? property.enum + [nil] : property.enum
+      end
+      definition[:deprecated] = true if property.deprecated
+      definition
+    end
+    private_class_method :ref_schema, :inline_schema
+
+    def self.base_type(property)
+      if property.type.respond_to?(:properties)
+        {"$ref" => "#/components/schemas/#{property.type.name}"}
+      elsif property.column_type && COLUMN_TYPE_MAP.key?(property.column_type)
+        result = COLUMN_TYPE_MAP[property.column_type].dup
+        result[:type] = :string if property.enum
+        result
+      elsif property.type.is_a?(String) && !OPENAPI_TYPES.include?(property.type.to_sym)
+        {"$ref" => "#/components/schemas/#{property.type}"}
+      else
+        type = property.type.to_s.to_sym
+        if OPENAPI_TYPES.include?(type)
+          {type: type}
+        else
+          {type: :object}
+        end
+      end
+    end
+    private_class_method :base_type
+  end
+end

data/lib/typelizer/property.rb

@@ -1,7 +1,7 @@
 module Typelizer
   Property = Struct.new(
     :name, :type, :optional, :nullable,
-    :multi, :column_name, :comment, :enum, :enum_type_name, :deprecated,
+    :multi, :column_name, :column_type, :comment, :enum, :enum_type_name, :deprecated,
     :with_traits,
     keyword_init: true
   ) do
@@ -52,7 +52,8 @@ module Typelizer
     def fingerprint
       # Use array format for consistent output across Ruby versions
       # (Hash#inspect format changed in Ruby 3.4)
-      to_h.merge(type: UnionTypeSorter.sort(type_name(sort_order: :alphabetical), :alphabetical))
+      # Exclude fields that do not affect generated TypeScript output
+      to_h.except(:column_type).merge(type: UnionTypeSorter.sort(type_name(sort_order: :alphabetical), :alphabetical))
         .to_a.inspect
     end
 

data/lib/typelizer/serializer_plugins/alba/trait_interface.rb

@@ -34,7 +34,7 @@ module Typelizer
       def infer_types(props, typelizes)
         props.map do |prop|
           # First check for typelize DSL in the trait
-          dsl_type = typelizes[prop.column_name.to_sym]
+          dsl_type = typelizes[prop.column_name.to_sym] || typelizes[prop.name.to_sym]
           if dsl_type&.any?
             next prop.with(**dsl_type).tap do |property|
               property.comment ||= model_plugin.comment_for(property) if config.comments && property.comment != false

data/lib/typelizer/version.rb

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

data/lib/typelizer.rb

@@ -16,6 +16,7 @@ require_relative "typelizer/import_sorter"
 require_relative "typelizer/interface"
 require_relative "typelizer/renderer"
 require_relative "typelizer/writer"
+require_relative "typelizer/openapi"
 require_relative "typelizer/generator"
 require_relative "typelizer/type_parser"
 require_relative "typelizer/dsl"
@@ -62,8 +63,35 @@ module Typelizer
       yield configuration
     end
 
+    def interfaces(writer_name: nil)
+      load_serializers
+      context = WriterContext.new(writer_name: writer_name)
+      target_serializers(context.writer_config.reject_class)
+        .map { |klass| context.interface_for(klass) }
+        .reject(&:empty?)
+    end
+
+    def openapi_schemas(writer_name: nil, openapi_version: "3.0")
+      interfaces(writer_name: writer_name).to_h { |i| [i.name, OpenAPI.schema_for(i, openapi_version: openapi_version)] }
+    end
+
     private
 
+    def load_serializers
+      dirs.flat_map { |dir| Dir["#{dir}/**/*.rb"] }.each { |file| require file }
+    end
+
+    def target_serializers(reject_class)
+      resolved = base_classes.filter_map do |base_class|
+        Object.const_get(base_class) if Object.const_defined?(base_class)
+      end
+      raise ArgumentError, "No serializers found. Please ensure all your serializers include Typelizer::DSL." if base_classes.any? && resolved.none?
+
+      (resolved + resolved.flat_map(&:descendants)).uniq
+        .reject { |serializer| reject_class.call(serializer: serializer) }
+        .sort_by(&:name)
+    end
+
     attr_writer :base_classes
   end
 
@@ -72,3 +100,5 @@ module Typelizer
 
   self.base_classes = Set.new
 end
+
+require_relative "typelizer/delegate_tracker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typelizer
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov
@@ -51,6 +51,7 @@ files:
 - lib/typelizer/config.rb
 - lib/typelizer/configuration.rb
 - lib/typelizer/contexts/writer_context.rb
+- lib/typelizer/delegate_tracker.rb
 - lib/typelizer/dsl.rb
 - lib/typelizer/dsl/hooks.rb
 - lib/typelizer/dsl/hooks/alba.rb
@@ -64,6 +65,7 @@ files:
 - lib/typelizer/model_plugins/active_record.rb
 - lib/typelizer/model_plugins/auto.rb
 - lib/typelizer/model_plugins/poro.rb
+- lib/typelizer/openapi.rb
 - lib/typelizer/property.rb
 - lib/typelizer/property_sorter.rb
 - lib/typelizer/railtie.rb