typelizer 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 819c25a9bfc5dd74c3b7c77045bb5f5ef968f518f8a8d228502badb6936ea50d
-  data.tar.gz: c8d8d9affec2d6eb07cf1e58942fe46009fad2782c57689218b8357a85c227f0
+  metadata.gz: d8a6cb6187a0670a589346d969c61a17ae0b9fd60a4e6926c74c2e72c9594130
+  data.tar.gz: 4ef1a1e6e728df5ab1d5198a0254cfa68e5e477da57fb9c3c6b7ae2f7efa945d
 SHA512:
-  metadata.gz: b4b39192ff398bb25c6b537fcb5c73893de40d82f14a09a254e4ef8317a08232819c3285b7e6806938f1c7058f895d0100b03884574158bbaa2e329982518683
-  data.tar.gz: 8971c5a2cc78992fd38dc101e7b2fc1eaefe82ad756f828bca4416a4a6ed54d1ff25eace61fd80cd293cca3dc66b6b6c24706a0fa45156fb275eb9bfe4976c46
+  metadata.gz: 56296749f1d5478e98457afac0d2e8599e360d5b7864d596772c825e9970471de8b1d0103ada0120b9adeddab2805e65976c496ce0963785dfd39ddc3dffae91
+  data.tar.gz: 25f8667ef0f54560e1c84e8d906b50abc55e01ea761dacff012657bc7d94f7127263166b81c4e317350ee89219f92a070aa042004f42cfad3a6482fe31a0c86f

data/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-02-26
+
+### Added
+
+- Alba: nested attributes (`nested` / `nested_attribute`) now generate inline nested TypeScript types with full type inference support, including within traits. ([@pgiblock])
+
+- OpenAPI: support for traits in schema generation. ([@skryukov])
+
+- Union types in `typelize` for polymorphic associations. Supports serializer class references, pipe-delimited strings, and plain TypeScript type names. ([@skryukov])
+
+  ```ruby
+  typelize commentable: [UserResource, CommentResource]
+  typelize approver: "AuthorResource | null"
+  typelize content: "TextBlock | ImageBlock"
+  ```
+
+### Fixed
+
+- OpenAPI: TypeScript-only types (`any`, `unknown`, `never`) and generic types (`Record<string, unknown>`, `Partial<T>`, etc.) no longer produce invalid `$ref` entries. They are mapped to `{type: :object}` instead. ([@skryukov])
+- OpenAPI: fix nullable arrays producing incorrect schemas. ([@skryukov])
+- Fix Typelizer not loading gracefully when required gems are missing at boot time. ([@skryukov])
+
+### Changed
+
+- **Internal:** Union types are now stored as arrays of symbols instead of pipe-delimited strings. This fixes import resolution for serializer classes inside unions and eliminates redundant string splitting/joining across the DSL, Interface, and OpenAPI layers. ([@skryukov])
+
+## [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
@@ -353,12 +407,15 @@ and this project adheres to [Semantic Versioning].
 [@NOX73]: https://github.com/NOX73
 [@okuramasafumi]: https://github.com/okuramasafumi
 [@patvice]: https://github.com/patvice
+[@pgiblock]: https://github.com/pgiblock
+[@prog-supdex]: https://github.com/prog-supdex
 [@PedroAugustoRamalhoDuarte]: https://github.com/PedroAugustoRamalhoDuarte
 [@skryukov]: https://github.com/skryukov
-[@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.9.0...HEAD
+[0.9.0]: https://github.com/skryukov/typelizer/compare/v0.8.0...v0.9.0
+[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,77 @@ 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
+```
+
+Union types are supported for polymorphic associations. You can use serializer class references, which resolve to their generated type names:
+
+```ruby
+class PostResource < ApplicationResource
+  attributes :id, :title
+
+  # Union of two serializers — resolves to generated type names
+  typelize commentable: [UserResource, CommentResource]
+  attribute :commentable
+
+  # Nullable union — extracts null and marks as nullable
+  typelize approver: "AuthorResource | null"
+  attribute :approver
+
+  # Pipe-delimited string with serializer names
+  typelize target: "UserResource | CommentResource"
+  attribute :target
+
+  # String and class constant can be mixed
+  typelize item: ["Namespace::UserResource", CommentResource]
+  attribute :item
+end
+```
+
+You can also use plain TypeScript type names for custom types that aren't backed by serializers:
+
+```ruby
+class PostResource < ApplicationResource
+  attributes :id, :title
+
+  # Plain type names — passed through as-is to TypeScript
+  typelize content: "TextBlock | ImageBlock"
+  attribute :content
+
+  # Works with arrays too
+  typelize sections: ["TextBlock", "ImageBlock"]
+  attribute :sections
+end
+```
+
+This generates:
+
+```typescript
+type Post = {
+  id: number;
+  title: string;
+  content: TextBlock | ImageBlock;
+  sections: TextBlock | ImageBlock;
+}
+```
+
 For more complex type definitions, use the full API:
 
 ```ruby
@@ -310,6 +382,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,15 @@ 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
+    raise ArgumentError, "No serializers found. Please ensure all your serializers include Typelizer::DSL." if interfaces.empty?
+
     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) && !ActiveRecord.autoload?(: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/dsl.rb

@@ -104,16 +104,16 @@ module Typelizer
           options = attrs.last.is_a?(Hash) ? attrs.pop : {}
 
           if attrs.any?
-            # Parse type shortcuts and merge options
             parsed_types = attrs.map { |t| TypeParser.parse(t) }
-            type_names = parsed_types.map { |p| p[:type] }
-            options[:type] = type_names.join(" | ")
-
-            # Merge modifier flags from all parsed types
+            all_types = parsed_types.flat_map { |p| Array(p[:type]) }
             parsed_types.each do |parsed|
               options[:optional] = true if parsed[:optional]
               options[:multi] = true if parsed[:multi]
+              options[:nullable] = true if parsed[:nullable]
             end
+            options[:nullable] = true if all_types.delete(:null)
+            # Unwrap single-element arrays: typelize field: ["string"] behaves like typelize field: "string"
+            options[:type] = (all_types.size == 1) ? all_types.first : all_types
           end
 
           instance_variable_get(instance_variable)[name.to_sym] ||= {}

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)
+        next 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

@@ -1,5 +1,9 @@
+require_relative "type_inference"
+
 module Typelizer
   class Interface
+    include TypeInference
+
     attr_reader :serializer, :context
 
     def initialize(serializer:, context:)
@@ -60,7 +64,7 @@ module Typelizer
 
     def enum_types
       @enum_types ||= begin
-        all_properties = properties + trait_interfaces.flat_map(&:properties)
+        all_properties = collect_all_properties(properties + trait_interfaces.flat_map(&:properties))
         all_properties
           .select(&:enum_definition)
           .uniq(&:enum_type_name)
@@ -104,12 +108,12 @@ module Typelizer
 
     def imports
       @imports ||= begin
-        # Include both main properties and trait properties for import collection
-        all_properties = properties_to_print + trait_interfaces.flat_map(&:properties)
+        # Include both main properties and trait properties for import collection,
+        # recursively including nested sub-properties
+        all_properties = collect_all_properties(properties_to_print + trait_interfaces.flat_map(&:properties))
 
-        association_serializers, attribute_types = all_properties.filter_map(&:type)
-          .uniq
-          .partition { |type| type.is_a?(Interface) }
+        flat_types = all_properties.filter_map(&:type).flat_map { |t| Array(t) }.uniq
+        association_serializers, attribute_types = flat_types.partition { |type| type.is_a?(Interface) }
 
         serializer_types = association_serializers
           .filter_map { |interface| interface.name if interface.name != name && !interface.inline? }
@@ -158,6 +162,16 @@ module Typelizer
 
     private
 
+    def collect_all_properties(props)
+      props.flat_map do |prop|
+        if prop.nested_properties&.any?
+          [prop] + collect_all_properties(prop.nested_properties)
+        else
+          [prop]
+        end
+      end
+    end
+
     def self_type_name
       serializer.name.match(/(\w+::)?(\w+)(Serializer|Resource)/)[2]
     end
@@ -175,54 +189,63 @@ 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) }
           .then { |p| has_dsl ? p : apply_model_inference(p) }
           .then { |p| apply_multi_flag(p, multi_attrs) }
           .then { |p| apply_metadata(p) }
+          .then { |p| infer_nested_property_types(p) }
       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 apply_model_inference(prop)
-      model_plugin.infer_types(prop)
-    end
+    def resolve_class_type(attrs)
+      type = attrs[:type]
 
-    def apply_multi_flag(prop, multi_attrs)
-      return prop unless multi_attrs.include?(prop.column_name.to_sym)
-
-      prop.with(multi: true)
-    end
-
-    def apply_metadata(prop)
-      prop.tap do |p|
-        p.comment ||= model_plugin.comment_for(p) if config.comments && p.comment != false
-        p.enum ||= model_plugin.enum_for(p) if p.enum != false
+      case type
+      when Array
+        resolve_union_class_types(attrs)
+      when String, Symbol
+        resolve_single_class_type(attrs)
+      else
+        attrs
       end
     end
 
-    def model_class
-      return serializer._typelizer_model_name if serializer.respond_to?(:_typelizer_model_name)
+    def resolve_single_class_type(attrs)
+      attrs.merge(type: resolve_type_part(attrs[:type]))
+    end
 
-      # Execute the `serializer_model_mapper` lambda in the context of the `config` object
-      # This giving a possibility to access other lambdas, for example, `serializer_name_mapper`
-      config.instance_exec(serializer, &config.serializer_model_mapper)
-    rescue NameError => e
-      Typelizer.logger.debug("model_mapper failed for serializer #{serializer.name}: #{e.class}: #{e.message}")
+    def resolve_union_class_types(attrs)
+      resolved = attrs[:type].map { |part| resolve_type_part(part) }
+      # Unwrap single-element arrays (e.g., after null extraction from ["Serializer", null])
+      attrs.merge(type: (resolved.size == 1) ? resolved.first : resolved)
+    end
 
-      nil
+    def resolve_type_part(part)
+      klass = Object.const_get(part.to_s)
+      klass.respond_to?(:typelizer_config) ? context.interface_for(klass) : part
+    rescue NameError
+      part
     end
 
-    def model_plugin
-      @model_plugin ||= config.model_plugin.new(model_class: model_class, config: config)
+    def apply_multi_flag(prop, multi_attrs)
+      return prop unless multi_attrs.include?(prop.column_name.to_sym)
+
+      prop.with(multi: true)
     end
   end
 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,214 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module OpenAPI
+    SUPPORTED_VERSIONS = ["3.0", "3.1"].freeze
+
+    OPENAPI_TYPES = %i[integer number string boolean object array null].freeze
+    TS_OBJECT_TYPES = %w[any unknown never Record Partial Pick Omit].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
+
+    class << self
+      def schema_for(interface, openapi_version: "3.0")
+        validate_version!(openapi_version)
+
+        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 property_schema(property, openapi_version: "3.0")
+        if property.type.is_a?(Array)
+          return union_schema(property, openapi_version: openapi_version)
+        end
+
+        definition = base_type(property, openapi_version: openapi_version)
+        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
+
+        definition = wrap_traits(definition, property, openapi_version: openapi_version)
+        wrap_multi(definition, property, openapi_version: openapi_version)
+      end
+
+      private
+
+      def ref_schema(ref, property, openapi_version:)
+        ref_obj = {"$ref" => ref}
+        item_nullable = !property.multi && property.nullable
+
+        if v31?(openapi_version)
+          definition = item_nullable ? {oneOf: [ref_obj, {type: :null}]} : ref_obj
+        else
+          needs_wrapper = item_nullable || (!property.multi && (property.comment.is_a?(String) || property.deprecated))
+          definition = needs_wrapper ? {allOf: [ref_obj]} : ref_obj
+          definition[:nullable] = true if item_nullable
+        end
+
+        apply_metadata(definition, property) unless property.multi
+        definition
+      end
+
+      def inline_schema(definition, property, openapi_version:)
+        unless property.multi
+          apply_nullable(definition, property, openapi_version: openapi_version)
+          apply_metadata(definition, property)
+        end
+        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
+      end
+
+      def union_schema(property, openapi_version:)
+        schemas = property.type.map { |part| union_member_schema(part) }
+
+        definition = {anyOf: schemas}
+
+        unless property.multi
+          apply_nullable(definition, property, openapi_version: openapi_version)
+          apply_metadata(definition, property)
+        end
+
+        wrap_multi(definition, property, openapi_version: openapi_version)
+      end
+
+      def union_member_schema(type)
+        if type.respond_to?(:properties)
+          {"$ref" => "#/components/schemas/#{type.name}"}
+        else
+          sym = type.to_sym
+          if OPENAPI_TYPES.include?(sym)
+            {type: sym}
+          elsif ts_only_type?(type.to_s)
+            {type: :object}
+          else
+            {"$ref" => "#/components/schemas/#{type}"}
+          end
+        end
+      end
+
+      def wrap_traits(definition, property, openapi_version:)
+        return definition unless property.respond_to?(:with_traits) && property.with_traits&.any? && property.type.respond_to?(:name)
+
+        trait_refs = property.with_traits.map do |t|
+          {"$ref" => "#/components/schemas/#{property.type.name}#{t.to_s.camelize}Trait"}
+        end
+
+        base_ref = definition.delete("$ref")
+        if base_ref
+          definition = {allOf: [{"$ref" => base_ref}] + trait_refs}
+        elsif definition[:oneOf]
+          non_null = definition[:oneOf].reject { |s| s[:type] == :null }
+          null_schemas = definition[:oneOf].select { |s| s[:type] == :null }
+          all_of = non_null + trait_refs
+          definition = null_schemas.any? ? {oneOf: [{allOf: all_of}, *null_schemas]} : {allOf: all_of}
+        elsif definition[:allOf]
+          definition[:allOf].concat(trait_refs)
+        else
+          raise ArgumentError, "Unexpected schema shape for traits on property #{property.name}: #{definition.inspect}"
+        end
+
+        definition[:nullable] = true if !v31?(openapi_version) && property.nullable
+        definition
+      end
+
+      def apply_metadata(definition, property)
+        definition[:description] = property.comment if property.comment.is_a?(String)
+        definition[:deprecated] = true if property.deprecated
+      end
+
+      def apply_nullable(definition, property, openapi_version:)
+        return unless property.nullable
+
+        if definition[:anyOf]
+          v31?(openapi_version) ? definition[:anyOf] << {type: :null} : definition[:nullable] = true
+        elsif definition[:type]
+          v31?(openapi_version) ? definition[:type] = [definition[:type], :null] : definition[:nullable] = true
+        end
+      end
+
+      def wrap_multi(definition, property, openapi_version:)
+        return definition unless property.multi
+
+        definition = {type: :array, items: definition}
+        apply_metadata(definition, property)
+        if property.nullable
+          v31?(openapi_version) ? definition[:type] = [:array, :null] : definition[:nullable] = true
+        end
+        definition
+      end
+
+      def base_type(property, openapi_version:)
+        if property.type.respond_to?(:properties)
+          if property.type.respond_to?(:inline?) && property.type.inline?
+            schema_for(property.type, openapi_version: openapi_version)
+          else
+            {"$ref" => "#/components/schemas/#{property.type.name}"}
+          end
+        elsif property.type.nil? && property.respond_to?(:nested_properties) && property.nested_properties&.any?
+          nested_schema(property, openapi_version: openapi_version)
+        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) || property.type.is_a?(Symbol)) && !OPENAPI_TYPES.include?(property.type.to_sym) && !ts_only_type?(property.type.to_s)
+          {"$ref" => "#/components/schemas/#{property.type}"}
+        else
+          type = property.type.to_s.to_sym
+          OPENAPI_TYPES.include?(type) ? {type: type} : {type: :object}
+        end
+      end
+
+      def nested_schema(property, openapi_version:)
+        required = property.nested_properties.reject(&:optional).map(&:name)
+        schema = {
+          type: :object,
+          properties: property.nested_properties.to_h { |p| [p.name, property_schema(p, openapi_version: openapi_version)] }
+        }
+        schema[:required] = required if required.any?
+        schema
+      end
+
+      def v31?(openapi_version)
+        openapi_version.to_s == "3.1"
+      end
+
+      def ts_only_type?(type_str)
+        type_str.start_with?("{") || type_str.include?("<") || TS_OBJECT_TYPES.include?(type_str)
+      end
+
+      def validate_version!(openapi_version)
+        raise ArgumentError, "Unsupported openapi_version: #{openapi_version}. Must be one of: #{SUPPORTED_VERSIONS.join(", ")}" unless SUPPORTED_VERSIONS.include?(openapi_version.to_s)
+      end
+    end
+  end
+end

data/lib/typelizer/property.rb

@@ -1,8 +1,8 @@
 module Typelizer
   Property = Struct.new(
     :name, :type, :optional, :nullable,
-    :multi, :column_name, :comment, :enum, :enum_type_name, :deprecated,
-    :with_traits,
+    :multi, :column_name, :column_type, :comment, :enum, :enum_type_name, :deprecated,
+    :with_traits, :nested_properties, :nested_typelizes,
     keyword_init: true
   ) do
     def with(**attrs)
@@ -52,7 +52,13 @@ 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.
+      # Exclude nested_properties/nested_typelizes from to_h to avoid changing
+      # fingerprints for properties that don't use them.
+      # nested_typelizes is excluded entirely as it only affects inference, not output.
+      to_h.except(:column_type, :nested_properties, :nested_typelizes)
+        .merge(type: UnionTypeSorter.sort(type_name(sort_order: :alphabetical), :alphabetical))
+        .then { |h| nested_properties&.any? ? h.merge(nested_properties: nested_properties.map(&:fingerprint)) : h }
         .to_a.inspect
     end
 
@@ -89,7 +95,20 @@ module Typelizer
         return enum_values.join(" | ")
       end
 
-      type.respond_to?(:name) ? type.name : type || "unknown"
+      if type.nil? && nested_properties&.any?
+        inner = nested_properties.map { |p|
+          rendered = p.render(sort_order: sort_order, prefer_double_quotes: prefer_double_quotes) + ";"
+          rendered.gsub(/^/, "  ")
+        }.join("\n")
+        return "{\n#{inner}\n}"
+      end
+
+      case type
+      when Array
+        type.map { |t| t.respond_to?(:name) ? t.name : t.to_s }.join(" | ")
+      else
+        type.respond_to?(:name) ? type.name : type&.to_s || "unknown"
+      end
     end
   end
 end

data/lib/typelizer/serializer_plugins/alba/{trait_attribute_collector.rb → block_attribute_collector.rb}

@@ -2,7 +2,7 @@
 
 module Typelizer
   module SerializerPlugins
-    class Alba::TraitAttributeCollector
+    class Alba::BlockAttributeCollector
       attr_reader :collected_attributes, :collected_typelizes
 
       def initialize
@@ -53,15 +53,26 @@ module Typelizer
         end
       end
 
-      # Simple struct to hold association info from traits
-      TraitAssociation = Struct.new(:name, :resource, :with_traits, :multi, :key, keyword_init: true)
+      # Simple struct to hold association info from blocks
+      BlockAssociation = Struct.new(:name, :resource, :with_traits, :multi, :key, keyword_init: true)
+
+      # Struct to hold nested attribute info captured within a block
+      BlockNestedAttribute = Struct.new(:name, :block, keyword_init: true)
+
+      def nested_attribute(name, **options, &block)
+        raise ArgumentError, "Block is required for nested_attribute" unless block
+
+        @collected_attributes[name] = BlockNestedAttribute.new(name: name, block: block)
+      end
+
+      alias_method :nested, :nested_attribute
 
       # Support association methods that might be used in traits
       def one(name, **options, &block)
         resource = options[:resource] || options[:serializer]
         with_traits = options[:with_traits]
         key = options[:key] || name
-        @collected_attributes[key] = TraitAssociation.new(
+        @collected_attributes[key] = BlockAssociation.new(
           name: name,
           resource: resource,
           with_traits: with_traits,
@@ -77,7 +88,7 @@ module Typelizer
         resource = options[:resource] || options[:serializer]
         with_traits = options[:with_traits]
         key = options[:key] || name
-        @collected_attributes[key] = TraitAssociation.new(
+        @collected_attributes[key] = BlockAssociation.new(
           name: name,
           resource: resource,
           with_traits: with_traits,

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

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
 
+require_relative "../../type_inference"
+
 module Typelizer
   module SerializerPlugins
     class Alba::TraitInterface
+      include TypeInference
+
       attr_reader :serializer, :trait_name, :context, :plugin
 
       def initialize(serializer:, trait_name:, context:, plugin:)
@@ -33,31 +37,13 @@ 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]
-          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
-              property.enum ||= model_plugin.enum_for(property) if property.enum != false
-            end
-          end
-
-          # Fall back to model plugin for type inference
-          model_plugin.infer_types(prop)
+          dsl_type = typelizes[prop.column_name.to_sym] || typelizes[prop.name.to_sym]
+          prop
+            .then { |p| dsl_type&.any? ? p.with(**dsl_type) : apply_model_inference(p) }
+            .then { |p| apply_metadata(p) }
+            .then { |p| infer_nested_property_types(p) }
         end
       end
-
-      def model_class
-        return serializer._typelizer_model_name if serializer.respond_to?(:_typelizer_model_name)
-
-        config.instance_exec(serializer, &config.serializer_model_mapper)
-      rescue NameError
-        nil
-      end
-
-      def model_plugin
-        @model_plugin ||= config.model_plugin.new(model_class: model_class, config: config)
-      end
     end
   end
 end

data/lib/typelizer/serializer_plugins/alba.rb

@@ -48,19 +48,19 @@ module Typelizer
         return [], {} unless trait_block
 
         # Create a collector to capture attributes defined in the trait block
-        collector = TraitAttributeCollector.new
+        collector = BlockAttributeCollector.new
         collector.instance_exec(&trait_block)
 
         props = collector.collected_attributes.map do |name, attr|
-          build_trait_property(name.is_a?(Symbol) ? name.name : name, attr)
+          build_collected_property(name.is_a?(Symbol) ? name.name : name, attr)
         end
 
         [props, collector.collected_typelizes]
       end
 
-      def build_trait_property(name, attr)
+      def build_collected_property(name, attr)
         case attr
-        when TraitAttributeCollector::TraitAssociation
+        when BlockAttributeCollector::BlockAssociation
           with_traits = Array(attr.with_traits) if attr.with_traits
           resource = attr.resource || infer_resource_from_name(name)
 
@@ -73,6 +73,19 @@ module Typelizer
             column_name: name,
             with_traits: with_traits
           )
+        when BlockAttributeCollector::BlockNestedAttribute
+          prop_name = has_transform_key?(serializer) ? fetch_key(serializer, name) : name
+          nested_props, nested_typelizes = collect_nested_block(attr.block)
+          Property.new(
+            name: prop_name,
+            type: nil,
+            optional: false,
+            nullable: false,
+            multi: false,
+            column_name: name,
+            nested_properties: nested_props,
+            nested_typelizes: nested_typelizes
+          )
         else
           build_property(name, attr)
         end
@@ -95,7 +108,7 @@ module Typelizer
       end
 
       def trait_interfaces
-        traits.map do |trait_name, _|
+        @trait_interfaces ||= traits.map do |trait_name, _|
           TraitInterface.new(
             serializer: serializer,
             trait_name: trait_name,
@@ -164,6 +177,8 @@ module Typelizer
             **options
           )
         when ::Alba::NestedAttribute
+          block = attr.instance_variable_get(:@block)
+          nested_props, nested_typelizes = collect_nested_block(block)
           Property.new(
             name: name,
             type: nil,
@@ -171,6 +186,8 @@ module Typelizer
             nullable: false,
             multi: false,
             column_name: column_name,
+            nested_properties: nested_props,
+            nested_typelizes: nested_typelizes,
             **options
           )
         when ::Alba::ConditionalAttribute
@@ -192,14 +209,24 @@ module Typelizer
         ::Alba.transform_key(key, transform_type: serializer._transform_type)
       end
 
-      private
-
       def ts_mapper
         config.plugin_configs.dig(:alba, :ts_mapper) || ALBA_TS_MAPPER
       end
+
+      def collect_nested_block(block)
+        collector = BlockAttributeCollector.new
+        collector.instance_exec(&block)
+
+        props = collector.collected_attributes.map do |attr_name, attr|
+          attr_name_str = attr_name.is_a?(Symbol) ? attr_name.name : attr_name
+          build_collected_property(attr_name_str, attr)
+        end
+
+        [props, collector.collected_typelizes]
+      end
     end
   end
 end
 
-require_relative "alba/trait_attribute_collector"
+require_relative "alba/block_attribute_collector"
 require_relative "alba/trait_interface"

data/lib/typelizer/type_inference.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module TypeInference
+    private
+
+    def apply_model_inference(prop)
+      model_plugin.infer_types(prop)
+    end
+
+    def apply_metadata(prop)
+      prop.tap do |p|
+        p.comment ||= model_plugin.comment_for(p) if config.comments && p.comment != false
+        p.enum ||= model_plugin.enum_for(p) if p.enum != false
+      end
+    end
+
+    def infer_nested_property_types(prop)
+      return prop unless prop.nested_properties&.any?
+
+      typelizes = prop.nested_typelizes || {}
+      inferred = prop.nested_properties.map do |sub_prop|
+        dsl_type = typelizes[sub_prop.column_name.to_sym] || typelizes[sub_prop.name.to_sym]
+        sub_prop
+          .then { |p| dsl_type&.any? ? p.with(**dsl_type) : apply_model_inference(p) }
+          .then { |p| apply_metadata(p) }
+          .then { |p| infer_nested_property_types(p) }
+      end
+
+      prop.with(nested_properties: inferred)
+    end
+
+    def model_class
+      return serializer._typelizer_model_name if serializer.respond_to?(:_typelizer_model_name)
+
+      config.instance_exec(serializer, &config.serializer_model_mapper)
+    rescue NameError => e
+      Typelizer.logger.debug("model_mapper failed for serializer #{serializer.name}: #{e.class}: #{e.message}")
+
+      nil
+    end
+
+    def model_plugin
+      @model_plugin ||= config.model_plugin.new(model_class: model_class, config: config)
+    end
+  end
+end

data/lib/typelizer/type_parser.rb

@@ -14,6 +14,8 @@ module Typelizer
         return options if type_def.nil?
 
         type_str = type_def.to_s
+        return parse_union(type_str, **options) if type_str.include?("|")
+
         match = TYPE_PATTERN.match(type_str)
 
         return {type: type_def}.merge(options) unless match
@@ -34,6 +36,18 @@ module Typelizer
         type_str = type_def.to_s
         type_str.end_with?("?", "[]")
       end
+
+      private
+
+      def parse_union(type_str, **options)
+        parts = type_str.split(/\s*\|\s*/)
+        options[:nullable] = true if parts.delete("null")
+        if parts.size == 1
+          parse(parts.first, **options)
+        else
+          {type: parts.map(&:to_sym)}.merge(options)
+        end
+      end
     end
   end
 end

data/lib/typelizer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typelizer
-  VERSION = "0.7.0"
+  VERSION = "0.9.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,45 @@ 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")
+      result = {}
+      interfaces(writer_name: writer_name).each do |i|
+        result[i.name] = OpenAPI.schema_for(i, openapi_version: openapi_version)
+        i.trait_interfaces.each do |trait|
+          result[trait.name] = OpenAPI.schema_for(trait, openapi_version: openapi_version)
+        end
+      end
+      result
+    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
+      if base_classes.any? && resolved.none?
+        logger.warn("Typelizer: No serializers found. Ensure your serializers include Typelizer::DSL.")
+        return []
+      end
+
+      (resolved + resolved.flat_map(&:descendants)).uniq
+        .reject { |serializer| reject_class.call(serializer: serializer) }
+        .sort_by(&:name)
+    end
+
     attr_writer :base_classes
   end
 
@@ -72,3 +110,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.9.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,13 +65,14 @@ 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
 - lib/typelizer/renderer.rb
 - lib/typelizer/serializer_config_layer.rb
 - lib/typelizer/serializer_plugins/alba.rb
-- lib/typelizer/serializer_plugins/alba/trait_attribute_collector.rb
+- lib/typelizer/serializer_plugins/alba/block_attribute_collector.rb
 - lib/typelizer/serializer_plugins/alba/trait_interface.rb
 - lib/typelizer/serializer_plugins/ams.rb
 - lib/typelizer/serializer_plugins/auto.rb
@@ -84,6 +86,7 @@ files:
 - lib/typelizer/templates/inheritance.ts.erb
 - lib/typelizer/templates/inline_type.ts.erb
 - lib/typelizer/templates/interface.ts.erb
+- lib/typelizer/type_inference.rb
 - lib/typelizer/type_parser.rb
 - lib/typelizer/union_type_sorter.rb
 - lib/typelizer/version.rb