typelizer 0.11.0 → 0.13.0

data/lib/tasks/generate.rake

@@ -1,33 +1,68 @@
 namespace :typelizer do
   desc "Generate TypeScript interfaces from serializers"
-  task generate: :environment do
-    benchmark do
-      Typelizer::Generator.call
+  task types: :environment do
+    benchmark_types do
+      Typelizer::Generator.call(skip_check: true)
     end
   end
 
-  desc "Removes all files in output folder and refreshs all generate TypeScript interfaces from serializers"
-  task "generate:refresh": :environment do
-    benchmark do
-      Typelizer::Generator.call(force: true)
+  desc "Regenerate all TypeScript interfaces from serializers"
+  task "types:refresh": :environment do
+    benchmark_types do
+      Typelizer::Generator.call(force: true, skip_check: true)
     end
   end
 
-  def benchmark(&block)
-    require "benchmark"
-
-    ENV["DISABLE_TYPELIZER"] = "false"
+  desc "Generate TypeScript route helpers"
+  task routes: :environment do
+    benchmark_routes do
+      Typelizer::RouteGenerator.call(skip_check: true)
+    end
+  end
 
-    puts "Generating TypeScript interfaces..."
-    time = Benchmark.realtime do
-      block.call
+  desc "Regenerate all TypeScript route helpers"
+  task "routes:refresh": :environment do
+    benchmark_routes do
+      Typelizer::RouteGenerator.call(force: true, skip_check: true)
     end
+  end
+
+  desc "Generate all TypeScript files"
+  task generate: %i[types routes]
+
+  desc "Regenerate all TypeScript files"
+  task "generate:refresh": ["types:refresh", "routes:refresh"]
+
+  def benchmark_types(&block)
+    require "benchmark"
 
     interfaces = Typelizer.interfaces
-    raise ArgumentError, "No serializers found. Please ensure all your serializers include Typelizer::DSL." if interfaces.empty?
+    if interfaces.empty?
+      puts "No serializers found, skipping type generation."
+      return
+    end
+
+    puts "Generating TypeScript interfaces..."
+    time = Benchmark.realtime { block.call }
 
     puts "Finished in #{time} seconds"
     puts "Found #{interfaces.size} serializers:"
     puts interfaces.map { |i| "\t#{i.name}" }.join("\n")
   end
+
+  def benchmark_routes(&block)
+    require "benchmark"
+
+    config = Typelizer.configuration.routes
+    unless config.enabled
+      puts "Route generation is disabled, skipping."
+      return
+    end
+
+    puts "Generating TypeScript route helpers..."
+    time = Benchmark.realtime { block.call }
+
+    puts "Finished in #{time} seconds"
+    puts "Generated route helpers in #{config.output_dir}"
+  end
 end

data/lib/typelizer/config.rb

@@ -31,12 +31,17 @@ module Typelizer
     properties_sort_order
   ].freeze
 
-  # Subset of CONFIGS_AFFECTING_OUTPUT that specifically affect index.ts output.
-  CONFIGS_AFFECTING_INDEX_OUTPUT = %i[
+  # Config keys that affect only index.ts and Enums.ts (not per-interface .ts files).
+  CONFIGS_AFFECTING_INDEX_ONLY_OUTPUT = %i[
+    enum_runtime
+  ].freeze
+
+  # Config keys that affect index.ts output (superset: per-interface keys + index-only keys).
+  CONFIGS_AFFECTING_INDEX_OUTPUT = (%i[
     verbatim_module_syntax
     prefer_double_quotes
     imports_sort_order
-  ].freeze
+  ] + CONFIGS_AFFECTING_INDEX_ONLY_OUTPUT).freeze
 
   # Config keys that don't affect file content (runtime behavior, or effects captured via properties).
   CONFIGS_NOT_AFFECTING_OUTPUT = %i[
@@ -76,6 +81,7 @@ module Typelizer
     :reject_class,
     :comments,
     :prefer_double_quotes,
+    :enum_runtime,
     keyword_init: true
   )
 
@@ -114,6 +120,7 @@ module Typelizer
         reject_class: ->(serializer:) { false },
         comments: false,
         prefer_double_quotes: false,
+        enum_runtime: false,
 
         output_dir: -> { default_output_dir },
 

data/lib/typelizer/configuration.rb

@@ -21,6 +21,10 @@ module Typelizer
     attr_accessor :dirs, :listen
     attr_reader :writers, :global_settings
 
+    def routes
+      @routes ||= RouteConfig.build
+    end
+
     def initialize
       @dirs = []
       @listen = nil

data/lib/typelizer/dsl.rb

@@ -33,8 +33,6 @@ module Typelizer
 
       # save association of serializer to model
       def typelize_from(model)
-        return unless Typelizer.enabled?
-
         define_singleton_method(:_typelizer_model_name) { model }
       end
 
@@ -82,12 +80,13 @@ module Typelizer
       private
 
       def assign_type_information(attribute_name, attributes)
-        return unless Typelizer.enabled?
-
         attributes.each do |name, attrs|
           next unless name
 
-          store_type(attribute_name, name, TypeParser.parse_declaration(attrs))
+          clean_name, optional_from_key = TypeParser.parse_key(name)
+          parsed = TypeParser.apply_optional_key(TypeParser.parse_declaration(attrs), optional_from_key)
+
+          store_type(attribute_name, clean_name, parsed)
         end
       end
 
@@ -112,5 +111,15 @@ module Typelizer
         end
       end
     end
+
+    module Disabled
+      %i[typelize_from typelize typelize_meta].each do |name|
+        define_method(name) { |*, **| }
+      end
+    end
+
+    def self.disable!
+      ClassMethods.prepend(Disabled)
+    end
   end
 end

data/lib/typelizer/generator.rb

@@ -6,8 +6,8 @@ module Typelizer
       new.call(**args)
     end
 
-    def call(force: false)
-      return [] unless Typelizer.enabled?
+    def call(force: false, skip_check: false)
+      return [] unless skip_check || Typelizer.enabled?
 
       Typelizer.configuration.writers.each do |writer_name, writer_config|
         interfaces = Typelizer.interfaces(writer_name: writer_name)

data/lib/typelizer/interface.rb

@@ -64,7 +64,7 @@ module Typelizer
       @meta_fields ||= begin
         props = serializer_plugin.meta_fields || []
         props = infer_types(props, :_typelizer_meta_attributes)
-        props = config.properties_transformer.call(props) if config.properties_transformer
+        props = transform_properties(props)
         PropertySorter.sort(props, config.properties_sort_order)
       end
     end
@@ -88,7 +88,7 @@ module Typelizer
       @properties ||= begin
         props = serializer_plugin.properties
         props = infer_types(props)
-        props = config.properties_transformer.call(props) if config.properties_transformer
+        props = transform_properties(props)
         PropertySorter.sort(props, config.properties_sort_order)
       end
     end
@@ -125,7 +125,10 @@ module Typelizer
         # recursively including nested sub-properties
         all_properties = collect_all_properties(properties_to_print + trait_interfaces.flat_map(&:properties))
 
-        flat_types = all_properties.filter_map(&:type).flat_map { |t| Array(t) }.uniq
+        flat_types = all_properties.filter_map(&:type)
+          .flat_map { |t| Array(t) }
+          .reject { |t| t.is_a?(Shape) }
+          .uniq
         association_serializers, attribute_types = flat_types.partition { |type| type.is_a?(Interface) }
 
         serializer_types = association_serializers
@@ -136,13 +139,10 @@ module Typelizer
           .uniq
           .reject { |type| global_type?(type) }
 
-        # Collect trait types from properties with with_traits (skip self-references)
         trait_imports = all_properties.flat_map do |prop|
-          next [] unless prop.with_traits&.any? && prop.type.is_a?(Interface)
-          # Skip if the trait types are from the current interface (same file)
-          next [] if prop.type.name == name
+          next [] if prop.type.is_a?(Interface) && prop.type.name == name
 
-          prop.with_traits.map { |t| "#{prop.type.name}#{t.to_s.camelize}Trait" }
+          prop.trait_type_names
         end
 
         # Collect enum type names from properties
@@ -177,13 +177,15 @@ module Typelizer
 
     def collect_all_properties(props)
       props.flat_map do |prop|
-        if prop.nested_properties&.any?
-          [prop] + collect_all_properties(prop.nested_properties)
-        elsif prop.type.is_a?(Interface) && prop.type.inline?
-          [prop] + collect_all_properties(prop.type.properties)
-        else
-          [prop]
-        end
+        children = nested_properties_of(prop.type)
+        children ? [prop] + collect_all_properties(children) : [prop]
+      end
+    end
+
+    def nested_properties_of(type)
+      case type
+      when Shape then type.properties
+      when Interface then type.properties if type.inline?
       end
     end
 
@@ -204,7 +206,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_for(prop, dsl_attrs)&.any?
+        has_dsl = prop.lookup_in(dsl_attrs)&.any?
 
         prop
           .then { |p| apply_dsl_type(p, dsl_attrs) }
@@ -215,12 +217,8 @@ 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_for(prop, dsl_attrs)
+      dsl_type = prop.lookup_in(dsl_attrs)
       return prop unless dsl_type&.any?
 
       dsl_type = resolve_class_type(dsl_type)
@@ -235,11 +233,20 @@ module Typelizer
         resolve_union_class_types(attrs)
       when String, Symbol
         resolve_single_class_type(attrs)
+      when Shape
+        attrs.merge(type: resolve_shape(type))
       else
         attrs
       end
     end
 
+    def resolve_shape(shape)
+      shape.map_properties do |p|
+        resolved = resolve_class_type(type: p.type)
+        p.with(type: resolved[:type])
+      end
+    end
+
     def resolve_single_class_type(attrs)
       attrs.merge(type: resolve_type_part(attrs[:type]))
     end

data/lib/typelizer/listen.rb

@@ -11,7 +11,8 @@ module Typelizer
         &block
       )
         return if started
-        return unless Typelizer.enabled?
+        return if Typelizer.listen == false
+        return unless Typelizer.listen || Gem.loaded_specs["listen"]
 
         @block = block
         @generator = Typelizer::Generator.new
@@ -21,19 +22,25 @@ module Typelizer
 
         self.started = true
 
-        locales_dirs = Typelizer.dirs.filter(&:exist?).map { |path| File.expand_path(path) }
-
-        relative_paths = locales_dirs.map { |path| relative_path(path) }
+        watched_dirs = Typelizer.dirs.filter(&:exist?).map { |path| File.expand_path(path) }
 
+        relative_paths = watched_dirs.map { |path| relative_path(path) }
         debug("Watching #{relative_paths.inspect}")
 
-        listener(locales_dirs.map(&:to_s), options).start
+        listener(watched_dirs.map(&:to_s), options).start
         @generator.call if run_on_start
+
+        if Typelizer.configuration.routes.enabled
+          RouteGenerator.call if run_on_start
+          start_route_listener(options)
+        end
       end
 
+      private
+
       def relative_path(path)
-        root_path = defined?(Rails) ? Rails.root : Pathname.pwd
-        Pathname.new(path).relative_path_from(root_path).to_s
+        @root_path ||= defined?(Rails) ? Rails.root : Pathname.pwd
+        Pathname.new(path).relative_path_from(@root_path).to_s
       end
 
       def debug(message)
@@ -67,6 +74,18 @@ module Typelizer
           paths.any? { |path| change.start_with?(path) }
         end
       end
+
+      def start_route_listener(options)
+        config_dir = @root_path.join("config")
+        return unless config_dir.exist?
+
+        debug("Watching #{relative_path(config_dir)} for route changes")
+
+        ::Listen.to(config_dir.to_s, only: /routes/, **options) do |changed, added, removed|
+          debug("Routes changed: #{(changed + added + removed).map { |f| relative_path(f) }.inspect}")
+          RouteGenerator.call
+        end.start
+      end
     end
   end
 end

data/lib/typelizer/middleware.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Typelizer
+  class TypeGenerationError < StandardError; end
+
+  class Middleware
+    class << self
+      attr_accessor :instance
+    end
+
+    def initialize(app)
+      @app = app
+      @mutex = Mutex.new
+      @pending = true
+      self.class.instance = self
+    end
+
+    def call(env)
+      if @pending
+        @mutex.synchronize do
+          generate! if @pending
+        end
+      end
+      @app.call(env)
+    end
+
+    def mark_pending!
+      @pending = true
+    end
+
+    private
+
+    def generate!
+      Generator.new.call
+      RouteGenerator.call
+      @pending = false
+    rescue *db_error_classes => e
+      raise TypeGenerationError, "Typelizer could not generate types: #{e.message}\n" \
+        "Fix the database issue, then reload the page."
+    end
+
+    def db_error_classes
+      return [] unless defined?(ActiveRecord)
+
+      [
+        ActiveRecord::NoDatabaseError,
+        ActiveRecord::ConnectionNotEstablished,
+        ActiveRecord::StatementInvalid
+      ]
+    end
+  end
+end

data/lib/typelizer/model_plugins/active_record.rb

@@ -38,6 +38,7 @@ module Typelizer
       def columns_hash
         return nil unless model_class
         return nil if model_class.abstract_class?
+        return nil unless model_class.table_exists?
 
         model_class.columns_hash
       end
@@ -45,6 +46,7 @@ module Typelizer
       def attribute_types
         return nil unless model_class&.respond_to?(:attribute_types)
         return nil if model_class.abstract_class?
+        return nil unless model_class.table_exists?
 
         model_class.attribute_types
       end
@@ -126,6 +128,7 @@ module Typelizer
         return nil unless assoc
 
         target = assoc.klass
+        return nil unless target.table_exists?
         col = target.columns_hash[info[:original].to_s]
         return nil unless col
 

data/lib/typelizer/openapi.rb

@@ -32,13 +32,7 @@ module Typelizer
         validate_version!(openapi_version)
 
         type_mapping = interface.respond_to?(:config) ? interface.config.type_mapping : Typelizer.configuration.type_mapping
-        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, type_mapping: type_mapping)] }
-        }
-        schema[:required] = required_props if required_props.any?
-        schema
+        object_schema(interface.properties, openapi_version: openapi_version, type_mapping: type_mapping)
       end
 
       def property_schema(property, openapi_version: "3.0", type_mapping: Typelizer.configuration.type_mapping)
@@ -120,11 +114,10 @@ module Typelizer
       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_names = property.trait_type_names
+        return definition if trait_names.empty?
 
-        trait_refs = property.with_traits.map do |t|
-          {"$ref" => "#/components/schemas/#{property.type.name}#{t.to_s.camelize}Trait"}
-        end
+        trait_refs = trait_names.map { |name| {"$ref" => "#/components/schemas/#{name}"} }
 
         base_ref = definition.delete("$ref")
         if base_ref
@@ -173,14 +166,15 @@ module Typelizer
       end
 
       def base_type(property, openapi_version:, type_mapping:)
-        if property.type.respond_to?(:properties)
+        # Shape check must precede respond_to?(:properties) — Shape also responds to :properties.
+        if property.type.is_a?(Shape)
+          object_schema(property.type.properties, openapi_version: openapi_version, type_mapping: type_mapping)
+        elsif 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, type_mapping: type_mapping)
         elsif property.column_type && COLUMN_TYPE_MAP.key?(property.column_type) &&
             !type_mapping_overridden?(property, type_mapping)
           result = COLUMN_TYPE_MAP[property.column_type].dup
@@ -196,11 +190,11 @@ module Typelizer
         end
       end
 
-      def nested_schema(property, openapi_version:, type_mapping:)
-        required = property.nested_properties.reject(&:optional).map(&:name)
+      def object_schema(properties, openapi_version:, type_mapping:)
+        required = properties.reject(&:optional).map(&:name)
         schema = {
           type: :object,
-          properties: property.nested_properties.to_h { |p| [p.name, property_schema(p, openapi_version: openapi_version, type_mapping: type_mapping)] }
+          properties: properties.to_h { |p| [p.name, property_schema(p, openapi_version: openapi_version, type_mapping: type_mapping)] }
         }
         schema[:required] = required if required.any?
         schema

data/lib/typelizer/property.rb

@@ -2,13 +2,17 @@ module Typelizer
   Property = Struct.new(
     :name, :type, :optional, :nullable,
     :multi, :column_name, :column_type, :comment, :enum, :enum_type_name, :deprecated,
-    :with_traits, :nested_properties, :nested_typelizes,
+    :with_traits,
     keyword_init: true
   ) do
     def with(**attrs)
       dup.tap { |p| attrs.each { |k, v| p[k] = v } }
     end
 
+    def lookup_in(hash)
+      hash[column_name.to_sym] || hash[name.to_sym]
+    end
+
     def inspect
       props = to_h.merge(type: type_name).map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
       "<#{self.class.name} #{props}>"
@@ -25,6 +29,12 @@ module Typelizer
       render(sort_order: :none)
     end
 
+    def trait_type_names
+      return [] unless with_traits&.any? && type.is_a?(Interface)
+
+      with_traits.map { |t| "#{type.name}#{t.to_s.camelize}Trait" }
+    end
+
     # Renders the property as a TypeScript property string
     # @param sort_order [Symbol, Proc, nil] Sort order for union types (:none, :alphabetical, or Proc)
     # @param prefer_double_quotes [Boolean] Whether to use double quotes for string values
@@ -32,11 +42,8 @@ module Typelizer
     def render(sort_order: :none, prefer_double_quotes: false)
       type_str = type_name(sort_order: sort_order, prefer_double_quotes: prefer_double_quotes)
 
-      # Handle intersection types for traits
-      if with_traits&.any? && type.respond_to?(:name)
-        trait_types = with_traits.map { |t| "#{type.name}#{t.to_s.camelize}Trait" }
-        type_str = ([type_str] + trait_types).join(" & ")
-      end
+      trait_types = trait_type_names
+      type_str = ([type_str] + trait_types).join(" & ") if trait_types.any?
 
       type_str = "Array<#{type_str}>" if multi
 
@@ -51,14 +58,10 @@ module Typelizer
 
     def fingerprint
       # Use array format for consistent output across Ruby versions
-      # (Hash#inspect format changed in Ruby 3.4)
-      # 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)
+      # (Hash#inspect format changed in Ruby 3.4).
+      # column_type is excluded because it only informs inference, not output.
+      to_h.except(:column_type)
         .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
 
@@ -69,17 +72,36 @@ module Typelizer
     def enum_definition(sort_order: :none, prefer_double_quotes: false)
       return unless enum && enum_type_name
 
-      values = enum.map { |v| quote_string(v.to_s, prefer_double_quotes) }
-      values = values.sort_by(&:downcase) if sort_order == :alphabetical
+      values = sorted_enum_keys(sort_order).map { |k| quote_string(k, prefer_double_quotes) }
       "type #{enum_type_name} = #{values.join(" | ")}"
     end
 
+    # Generates a TypeScript runtime constant for named enums
+    # @param sort_order [Symbol, Proc, nil] Sort order for enum keys (:none, :alphabetical, or Proc)
+    # @param prefer_double_quotes [Boolean] Whether to use double quotes for string values
+    # @return [String, nil] The const like "const UserRole = { admin: 'admin', user: 'user' } as const"
+    def enum_runtime_definition(sort_order: :none, prefer_double_quotes: false)
+      return unless enum && enum_type_name
+
+      entries = sorted_enum_keys(sort_order).map { |k| "#{js_key(k, prefer_double_quotes)}: #{quote_string(k, prefer_double_quotes)}" }
+      "const #{enum_type_name} = { #{entries.join(", ")} } as const"
+    end
+
     private
 
+    def sorted_enum_keys(sort_order)
+      keys = enum.map(&:to_s)
+      (sort_order == :alphabetical) ? keys.sort_by(&:downcase) : keys
+    end
+
     def quote_string(str, prefer_double_quotes)
       prefer_double_quotes ? "\"#{str}\"" : "'#{str}'"
     end
 
+    def js_key(str, prefer_double_quotes)
+      str.match?(/\A[A-Za-z_$][\w$]*\z/) ? str : quote_string(str, prefer_double_quotes)
+    end
+
     # Returns the type name, optionally sorting union members
     # @param sort_order [Symbol, Proc, nil] Sort order for union types
     # @param prefer_double_quotes [Boolean] Whether to use double quotes for string values
@@ -89,21 +111,12 @@ module Typelizer
       return enum_type_name if enum_type_name
 
       if enum
-        # Sort enum values if alphabetical sorting is requested
-        enum_values = enum.map { |v| quote_string(v.to_s, prefer_double_quotes) }
-        enum_values = enum_values.sort_by(&:downcase) if sort_order == :alphabetical
-        return enum_values.join(" | ")
-      end
-
-      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}"
+        return sorted_enum_keys(sort_order).map { |k| quote_string(k, prefer_double_quotes) }.join(" | ")
       end
 
       case type
+      when Shape
+        type.render(sort_order: sort_order, prefer_double_quotes: prefer_double_quotes)
       when Array
         type.map { |t| t.respond_to?(:name) ? t.name : t.to_s }.join(" | ")
       else

data/lib/typelizer/railtie.rb

@@ -15,22 +15,25 @@ module Typelizer
       end
     end
 
-    initializer "typelizer.generate" do |app|
+    initializer "typelizer.configure_dsl" do
+      Typelizer::DSL.disable! unless Typelizer.enabled?
+    end
+
+    server do
       next unless Typelizer.enabled?
 
-      generator = Typelizer::Generator.new
+      require_relative "middleware"
+      Rails.application.config.app_middleware.use(Typelizer::Middleware)
 
-      if Typelizer.listen == true || Gem.loaded_specs["listen"] && Typelizer.listen != false
+      if Typelizer.listen == true || (Gem.loaded_specs["listen"] && Typelizer.listen != false)
         require_relative "listen"
-        app.config.after_initialize do
-          Typelizer::Listen.call do
-            Rails.application.reloader.reload!
-          end
+        Typelizer::Listen.call(run_on_start: false) do
+          Rails.application.reloader.reload!
         end
       end
 
-      app.config.to_prepare do
-        generator.call
+      Rails.application.config.to_prepare do
+        Typelizer::Middleware.instance&.mark_pending!
       end
     end
   end