typelizer 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57cc88a8063ebe9f00e0558f3dbd59aca579b5e191bdce38d3f8ca9b0451acee
-  data.tar.gz: 32cb1941e3ece707061fd7f2b1e6287710a0f9e2e8f8fc4d56b7f39fe444a7f6
+  metadata.gz: a0b21f5f78121c64717aa08d6556efbddc0b0b80a3ec6f272d63f699133fff12
+  data.tar.gz: d8df7c3542950c82e6b25d3f9c39ea808aded01fab0e5b5eaada3801a99031a3
 SHA512:
-  metadata.gz: a9fb264406d6ea58bc1b7cc7e875bef11e08cf8f758786f0f63e4d110db5b0e39832615167068baea973a5cf5236f76cac537ce1cfd3f21abd3def162a33edd2
-  data.tar.gz: 74a8a3552d25fff6c5dee5837d42dc6f257d097944874ade9aee247d432ff7d85303ebb9a6e60ae000bb8634c2a47e4be2e52dc5f4b08d49bd06963473a19b43
+  metadata.gz: cc42979e0f00e3aec338fdd4cf3848639ba12a2019293a46e864e908a1dfd8f2f2258ef62d07ed15ec3da66ca7ad740907ac63c6e04f9aae29f18db0eae46584
+  data.tar.gz: c9504167e013d6aeff1208207b4531f012fe942018e72368296d2a676fb04460ece7b0582a5ef297cf6c037e071ea0868e39c4632765030bdb014fe9a49884ea

data/CHANGELOG.md

@@ -7,6 +7,45 @@ 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
+
+- Use DSL hooks instead of TracePoint for `typelize` method. ([@skryukov])
+
+### Fixed
+
+- Apply sorting and quote style configs consistently to all generated files. ([@jonmarkgo], [@skryukov])
+- Fix fingerprint calculations to include all config options. ([@skryukov])
+
 ## [0.6.0] - 2026-01-14
 
 ### Added
@@ -347,7 +386,9 @@ 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.6.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
 [0.5.5]: https://github.com/skryukov/typelizer/compare/v0.5.4...v0.5.5

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

@@ -19,6 +19,41 @@ module Typelizer
 
   DEFAULT_TYPES_GLOBAL = %w[Array Date Record File FileList].freeze
 
+  # Config keys that affect generated file content and must be included in fingerprints.
+  # When adding a new config, add it here if it affects output, or to CONFIGS_NOT_AFFECTING_OUTPUT.
+  CONFIGS_AFFECTING_OUTPUT = %i[
+    types_import_path
+    types_global
+    prefer_double_quotes
+    comments
+    verbatim_module_syntax
+    imports_sort_order
+    properties_sort_order
+  ].freeze
+
+  # Subset of CONFIGS_AFFECTING_OUTPUT that specifically affect index.ts output.
+  CONFIGS_AFFECTING_INDEX_OUTPUT = %i[
+    verbatim_module_syntax
+    prefer_double_quotes
+    imports_sort_order
+  ].freeze
+
+  # Config keys that don't affect file content (runtime behavior, or effects captured via properties).
+  CONFIGS_NOT_AFFECTING_OUTPUT = %i[
+    serializer_name_mapper
+    serializer_model_mapper
+    properties_transformer
+    model_plugin
+    serializer_plugin
+    plugin_configs
+    type_mapping
+    null_strategy
+    output_dir
+    inheritance_strategy
+    associations_strategy
+    reject_class
+  ].freeze
+
   Config = Struct.new(
     :serializer_name_mapper,
     :serializer_model_mapper,
@@ -36,6 +71,7 @@ module Typelizer
     :verbatim_module_syntax,
     :inheritance_strategy,
     :associations_strategy,
+    :reject_class,
     :comments,
     :prefer_double_quotes,
     keyword_init: true
@@ -71,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/dsl/hooks/alba.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module DSL
+    module Hooks
+      module Alba
+        include Methods
+        extend Builder
+
+        hook :attribute, :association, :one, :has_one
+        hook :nested_attribute, :nested, :meta
+        hook :many, :has_many, multi: true
+        hook_method_added
+      end
+    end
+  end
+end

data/lib/typelizer/dsl/hooks/ams.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module DSL
+    module Hooks
+      module AMS
+        include Methods
+        extend Builder
+
+        hook :attribute, :has_one, :belongs_to
+        hook :has_many, multi: true
+      end
+    end
+  end
+end

data/lib/typelizer/dsl/hooks/oj_serializers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module DSL
+    module Hooks
+      module OjSerializers
+        include Methods
+        extend Builder
+
+        hook :attribute, :has_one, :belongs_to, :flat_one
+        hook :has_many, multi: true
+      end
+    end
+  end
+end

data/lib/typelizer/dsl/hooks/panko.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module DSL
+    module Hooks
+      module Panko
+        include Methods
+        extend Builder
+
+        hook :has_one
+        hook :has_many, multi: true
+        hook_method_added
+      end
+    end
+  end
+end

data/lib/typelizer/dsl/hooks.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module DSL
+    module Hooks
+      def self.install(base)
+        # Always install hooks to capture multi associations.
+        # The hooks only record data to a Set, so overhead is minimal.
+        if defined?(::Alba::Resource) && base.ancestors.include?(::Alba::Resource)
+          require_relative "hooks/alba"
+          base.singleton_class.prepend(Alba)
+        elsif defined?(::ActiveModel::Serializer) && base.ancestors.include?(::ActiveModel::Serializer)
+          require_relative "hooks/ams"
+          base.singleton_class.prepend(AMS)
+        elsif defined?(::Oj::Serializer) && base.ancestors.include?(::Oj::Serializer)
+          require_relative "hooks/oj_serializers"
+          base.singleton_class.prepend(OjSerializers)
+        elsif defined?(::Panko::Serializer) && base.ancestors.include?(::Panko::Serializer)
+          require_relative "hooks/panko"
+          base.singleton_class.prepend(Panko)
+        end
+      end
+
+      # Shared methods available to all hook modules
+      module Methods
+        private
+
+        def consume_keyless_type(name)
+          return unless keyless_type
+
+          type, attrs = keyless_type
+          typelize(name => [type, attrs])
+          self.keyless_type = nil
+        end
+
+        def record_multi(name)
+          _own_typelizer_multi_attributes << name.to_sym
+        end
+      end
+
+      # DSL for defining hooks with less boilerplate
+      module Builder
+        def hook(*methods, multi: false)
+          methods.each do |method|
+            define_method(method) do |name = nil, *args, **kwargs, &block|
+              if name
+                record_multi(name) if multi
+                consume_keyless_type(name)
+              end
+              super(name, *args, **kwargs, &block)
+            end
+          end
+        end
+
+        def hook_method_added
+          define_method(:method_added) do |method_name|
+            consume_keyless_type(method_name)
+            super(method_name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/typelizer/dsl.rb

@@ -1,3 +1,6 @@
+require "set"
+require_relative "dsl/hooks"
+
 module Typelizer
   module DSL
     # typelize_from Model
@@ -6,11 +9,13 @@ module Typelizer
     def self.included(base)
       Typelizer.base_classes << base.to_s if base.name
       base.extend(ClassMethods)
+      Hooks.install(base)
     end
 
     def self.extended(base)
       Typelizer.base_classes << base.to_s if base.name
       base.extend(ClassMethods)
+      Hooks.install(base)
     end
 
     module ClassMethods
@@ -49,6 +54,21 @@ module Typelizer
 
       attr_accessor :keyless_type
 
+      # Returns union of own + ancestors' multi attributes
+      def _typelizer_multi_attributes
+        result = @_typelizer_multi_attributes || Set.new
+        if superclass.respond_to?(:_typelizer_multi_attributes)
+          superclass._typelizer_multi_attributes | result
+        else
+          result
+        end
+      end
+
+      # Returns own Set (initializing if needed) for writing
+      def _own_typelizer_multi_attributes
+        @_typelizer_multi_attributes ||= Set.new
+      end
+
       def typelize_meta(**attributes)
         assign_type_information(:_typelizer_meta_attributes, attributes)
       end

data/lib/typelizer/generator.rb

@@ -9,83 +9,12 @@ module Typelizer
     def call(force: false)
       return [] unless Typelizer.enabled?
 
-      # plugin scan per run cache
-      @scan_plugin_cache = {}
-
-      read_serializers
-      serializers = target_serializers
-
-      # For each writer, build a dedicated WriterContext. The context holds that writer's
-      # configuration and resolves the effective Config for every Interface (per serializer)
-      # by merging global, writer, and per-serializer (DSL) overrides
       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 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
-
-    def read_serializers(files = nil)
-      files ||= Typelizer.dirs.flat_map { |dir| Dir["#{dir}/**/*.rb"] }
-      files.each do |file|
-        trace = TracePoint.new(:call) do |tp|
-          next unless typelized_class?(tp.self)
-
-          serializer_plugin = build_scan_plugin_for(tp.self)
-          next unless serializer_plugin
-
-          if tp.callee_id.in?(serializer_plugin.methods_to_typelize)
-            type, attrs = tp.self.keyless_type
-            name = tp.binding.local_variable_get(:name) if tp.binding.local_variable_defined?(:name)
-            tp.self.typelize(**serializer_plugin.typelize_method_transform(method: tp.callee_id, binding: tp.binding, name: name, type: type, attrs: attrs || {}))
-            tp.self.keyless_type = nil
-          end
-        end
-
-        trace.enable
-        require file
-        trace.disable
-      end
-    end
-
-    def typelized_class?(klass)
-      klass.is_a?(Class) && klass.respond_to?(:typelizer_config)
-    rescue
-      false
-    end
-
-    # Builds a minimal plugin instance used only during scan time for TracePoint
-    def build_scan_plugin_for(serializer_klass)
-      return @scan_plugin_cache[serializer_klass] if @scan_plugin_cache&.key?(serializer_klass)
-
-      base = Typelizer.configuration.writer_config(:default)
-      local_configuration = serializer_klass.typelizer_config.to_h.slice(:serializer_plugin, :plugin_configs)
-      cfg = base.with_overrides(**local_configuration)
-
-      @scan_plugin_cache[serializer_klass] = cfg.serializer_plugin.new(
-        serializer: serializer_klass,
-        config: cfg,
-        context: Typelizer::ScanContext
-      )
-    rescue NameError
-      nil
     end
   end
 end

data/lib/typelizer/interface.rb

@@ -25,7 +25,7 @@ module Typelizer
 
     def name
       if inline?
-        Renderer.call("inline_type.ts.erb", properties: properties).strip
+        Renderer.call("inline_type.ts.erb", properties: properties, sort_order: config.properties_sort_order).strip
       else
         config.serializer_name_mapper.call(serializer).tr_s(":", "")
       end
@@ -141,12 +141,15 @@ module Typelizer
     end
 
     def fingerprint
-      if trait_interfaces.empty?
-        "<#{self.class.name} #{name} properties=[#{properties_to_print.map(&:fingerprint).join(", ")}]>"
-      else
-        traits_fingerprint = trait_interfaces.map { |t| "#{t.name}=[#{t.properties.map(&:fingerprint).join(", ")}]" }.join(", ")
-        "<#{self.class.name} #{name} properties=[#{properties_to_print.map(&:fingerprint).join(", ")}] traits=[#{traits_fingerprint}]>"
-      end
+      [
+        name,
+        properties_to_print.map(&:fingerprint),
+        parent_interface&.name,
+        root_key,
+        meta_fields.map(&:fingerprint),
+        trait_interfaces.map { |t| [t.name, t.properties.map(&:fingerprint)] },
+        CONFIGS_AFFECTING_OUTPUT.map { |key| config.public_send(key) }
+      ].inspect
     end
 
     def quote(str)
@@ -168,18 +171,58 @@ module Typelizer
     end
 
     def infer_types(props, hash_name = :_typelizer_attributes)
+      dsl_attrs = serializer.respond_to?(hash_name) ? serializer.public_send(hash_name) : {}
+      multi_attrs = serializer.respond_to?(:_typelizer_multi_attributes) ? serializer._typelizer_multi_attributes : Set.new
+
       props.map do |prop|
-        if serializer.respond_to?(hash_name)
-          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
+        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) }
+      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_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
+
+    def apply_multi_flag(prop, multi_attrs)
+      return prop unless multi_attrs.include?(prop.column_name.to_sym)
+
+      prop.with(multi: true)
+    end
 
-        model_plugin.infer_types(prop)
+    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