typelizer 0.9.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e0f1018fd5d37ab4171501db8961c7895e796f1f41bf292c773f6d39fa08832
-  data.tar.gz: 3ab825f73e774cb8d13bb61772c878501e25b42f7e1b3ad35ae2a7a6a31e2d32
+  metadata.gz: 6dbce7bf8d558500341875958f875183e18668765f812d1ef8110f51c521cc7d
+  data.tar.gz: c297302a9425f27f0491307d7597201430ddf94eff38d80cf0b0760f16186296
 SHA512:
-  metadata.gz: 31b6a138ee7ae3c95f173f2df1f2168469b285aeff266c350c27a95b51021fa2deeb43bea1f9b28a0f9a4114a6ff4af9f82e47e64f04dcf314c88dfa9d042936
-  data.tar.gz: ccd0cb33a718fedae63e46e83bc7495d6b3520d7bfe6b190e2021e98f0f986ed36ca970dd25a71acbcc9017fd1b4b7579fb2399cf6727c92c2a13a1f38d84d80
+  metadata.gz: 5509e82f421cc1f52411b073431a246134d5bdcfe53eb5f308554492da3f2dbc78c708cf45c89651a749d5ad2aa1e0a59c119287f0c0ce8af19a10e374d4efbb
+  data.tar.gz: 37ba94237e3992f96542f33ef4376db48a1c5397907d01fbd7a619102a412db58418e36822d46f522f2ebeb672922591a46cbb112e0be2103bf7119d241e2bbe

data/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-03-26
+
+### Added
+
+- Per-serializer `output_dir` override via `typelizer_config`. Interfaces are written to their configured directory while the shared `index.ts` barrel generates correct relative import paths. ([@skryukov])
+
+- `filename_mapper` configuration to decouple generated file paths from TypeScript type names. Useful for mirroring Ruby module namespaces as nested directories. ([@skryukov], [@rdavid1099])
+
+  ```ruby
+  Typelizer.configure do |config|
+    config.filename_mapper = ->(name) { name.gsub("::", "/") }
+  end
+  # Alba::UserSerializer → types/Alba/User.ts (type name stays AlbaUser)
+  ```
+
+### Fixed
+
+- Walk over inline association properties to determine imports. ([@skryukov])
+- Fix `config.type_mapping` override not applied to OpenAPI schema generation. ([@skryukov])
+- Fix key transformation for Alba traits. ([@skryukov])
+
+## [0.10.0] - 2026-03-02
+
+### Changed
+
+- **Breaking:** Arrays of strings in `typelize` now produce string literal unions (`'active' | 'inactive'`) instead of type reference unions. Use symbols for type references: `typelize status: [:string, :number]`. ([@skryukov])
+
 ## [0.9.3] - 2026-02-27
 
 ### Fixed
@@ -420,20 +447,23 @@ and this project adheres to [Semantic Versioning].
 
 [@davidrunger]: https://github.com/davidrunger
 [@Envek]: https://github.com/Envek
-[@jonmarkgo]: https://github.com/jonmarkgo
 [@hkamberovic]: https://github.com/hkamberovic
+[@jonmarkgo]: https://github.com/jonmarkgo
 [@kristinemcbride]: https://github.com/kristinemcbride
 [@nkriege]: https://github.com/nkriege
 [@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
+[@prog-supdex]: https://github.com/prog-supdex
+[@rdavid1099]: https://github.com/rdavid1099
 [@skryukov]: https://github.com/skryukov
 [@ventsislaf]: https://github.com/ventsislaf
 
-[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.9.3...HEAD
+[Unreleased]: https://github.com/skryukov/typelizer/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/skryukov/typelizer/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/skryukov/typelizer/compare/v0.9.3...v0.10.0
 [0.9.3]: https://github.com/skryukov/typelizer/compare/v0.9.2...v0.9.3
 [0.9.2]: https://github.com/skryukov/typelizer/compare/v0.9.1...v0.9.2
 [0.9.1]: https://github.com/skryukov/typelizer/compare/v0.9.0...v0.9.1

data/README.md

@@ -119,10 +119,10 @@ class PostResource < ApplicationResource
   typelize categories: "string?[]"      # optional array of strings (categories?: Array<string>)
 
   # Shortcuts can be combined with explicit options
-  typelize status: ["string?", nullable: true]  # optional and nullable
+  typelize status: [:string?, nullable: true]  # optional and nullable
 
   # Also works with keyless typelize
-  typelize "string?"
+  typelize :string?
   attribute :nickname do |user|
     user.nickname
   end
@@ -167,8 +167,8 @@ class PostResource < ApplicationResource
   typelize target: "UserResource | CommentResource"
   attribute :target
 
-  # String and class constant can be mixed
-  typelize item: ["Namespace::UserResource", CommentResource]
+  # Pipe-delimited string with namespaced serializer
+  typelize item: "Namespace::UserResource | CommentResource"
   attribute :item
 end
 ```
@@ -183,8 +183,8 @@ class PostResource < ApplicationResource
   typelize content: "TextBlock | ImageBlock"
   attribute :content
 
-  # Works with arrays too
-  typelize sections: ["TextBlock", "ImageBlock"]
+  # Works with arrays of symbols too
+  typelize sections: [:TextBlock, :ImageBlock]
   attribute :sections
 end
 ```
@@ -200,10 +200,39 @@ type Post = {
 }
 ```
 
+String arrays are treated as string literal unions — useful for enums and state machines:
+
+```ruby
+class PostResource < ApplicationResource
+  attributes :id, :title
+
+  # Array of strings — generates string literal union type
+  typelize status: ["draft", "published", "archived"]
+  attribute :status
+
+  # Works with Rails enums and state machines
+  typelize review_state: ReviewStateMachine.states.keys
+  attribute :review_state
+end
+```
+
+This generates:
+
+```typescript
+type Post = {
+  id: number;
+  title: string;
+  status: 'draft' | 'published' | 'archived';
+  review_state: 'pending' | 'approved' | 'rejected';
+}
+```
+
+> **Note:** In arrays, **strings** become string literal types (`'a'`), while **symbols** and **class constants** become type references (`A`). You can mix them: `[:number, "auto"]` produces `number | 'auto'`.
+
 For more complex type definitions, use the full API:
 
 ```ruby
-typelize attribute_name: ["string", "Date", optional: true, nullable: true, multi: true, enum: %w[foo bar], comment: "Attribute description", deprecated: "Use `another_attribute` instead"]
+typelize attribute_name: [:string, :Date, optional: true, nullable: true, multi: true, enum: %w[foo bar], comment: "Attribute description", deprecated: "Use `another_attribute` instead"]
 ```
 
 ### Alba Traits
@@ -599,6 +628,16 @@ class PostResource < ApplicationResource
 end
 ```
 
+You can also override `output_dir` per serializer to place its generated file in a different directory:
+
+```ruby
+class Admin::UserResource < ApplicationResource
+  typelizer_config do |c|
+    c.output_dir = Rails.root.join("app/javascript/types/admin")
+  end
+end
+```
+
 ### Option reference
 
 ```ruby
@@ -606,6 +645,13 @@ Typelizer.configure do |config|
   # Name to type mapping for serializer classes
   config.serializer_name_mapper = ->(serializer) { ... }
 
+  # Custom file path mapping (decouples filename from type name)
+  # Receives the mapped name (output of serializer_name_mapper) and returns a file path.
+  # When nil (default), filename is derived from the type name.
+  # Example: ->(name) { name.gsub("::", "/") }
+  #   Alba::UserSerializer → types/Alba/User.ts (type name stays AlbaUser)
+  config.filename_mapper = nil
+
   # Maps serializers to their corresponding model classes
   config.serializer_model_mapper = ->(serializer) { ... }
 

data/lib/typelizer/config.rb

@@ -41,6 +41,7 @@ module Typelizer
   # Config keys that don't affect file content (runtime behavior, or effects captured via properties).
   CONFIGS_NOT_AFFECTING_OUTPUT = %i[
     serializer_name_mapper
+    filename_mapper
     serializer_model_mapper
     properties_transformer
     model_plugin
@@ -56,6 +57,7 @@ module Typelizer
 
   Config = Struct.new(
     :serializer_name_mapper,
+    :filename_mapper,
     :serializer_model_mapper,
     :properties_transformer,
     :properties_sort_order,
@@ -95,6 +97,8 @@ module Typelizer
           name.sub(/(Serializer|Resource)\z/, "")
         end,
 
+        filename_mapper: nil,
+
         serializer_model_mapper: lambda do |serializer|
           base_class = serializer_name_mapper.call(serializer)
           Object.const_get(base_class) if Object.const_defined?(base_class)

data/lib/typelizer/dsl.rb

@@ -87,8 +87,7 @@ module Typelizer
         attributes.each do |name, attrs|
           next unless name
 
-          options = parse_type_declaration(attrs)
-          store_type(attribute_name, name, options)
+          store_type(attribute_name, name, TypeParser.parse_declaration(attrs))
         end
       end
 
@@ -112,26 +111,6 @@ module Typelizer
           end
         end
       end
-
-      def parse_type_declaration(attrs)
-        attrs = [attrs] if attrs && !attrs.is_a?(Array)
-        options = attrs.last.is_a?(Hash) ? attrs.pop : {}
-
-        if attrs.any?
-          parsed_types = attrs.map { |t| TypeParser.parse(t) }
-          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
-
-        options
-      end
     end
   end
 end

data/lib/typelizer/interface.rb

@@ -36,7 +36,20 @@ module Typelizer
     end
 
     def filename
-      name.gsub("::", "/")
+      if config.filename_mapper
+        config.filename_mapper.call(config.serializer_name_mapper.call(serializer))
+      else
+        name.gsub("::", "/")
+      end
+    end
+
+    def index_path(index_dir)
+      iface_dir = config.output_dir.to_s
+      if iface_dir != index_dir
+        Pathname.new(File.join(iface_dir, filename)).relative_path_from(Pathname.new(index_dir)).to_s
+      else
+        "./#{filename}"
+      end
     end
 
     def root_key
@@ -166,6 +179,8 @@ module Typelizer
       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

data/lib/typelizer/openapi.rb

@@ -31,21 +31,22 @@ module Typelizer
       def schema_for(interface, openapi_version: "3.0")
         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)] }
+          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
       end
 
-      def property_schema(property, openapi_version: "3.0")
+      def property_schema(property, openapi_version: "3.0", type_mapping: Typelizer.configuration.type_mapping)
         if property.type.is_a?(Array)
           return union_schema(property, openapi_version: openapi_version)
         end
 
-        definition = base_type(property, openapi_version: openapi_version)
+        definition = base_type(property, openapi_version: openapi_version, type_mapping: type_mapping)
         ref = definition.delete("$ref")
 
         definition = if ref
@@ -171,7 +172,7 @@ module Typelizer
         definition
       end
 
-      def base_type(property, openapi_version:)
+      def base_type(property, openapi_version:, type_mapping:)
         if property.type.respond_to?(:properties)
           if property.type.respond_to?(:inline?) && property.type.inline?
             schema_for(property.type, openapi_version: openapi_version)
@@ -179,8 +180,9 @@ module Typelizer
             {"$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)
+          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
           result[:type] = :string if property.enum
           result
@@ -194,16 +196,20 @@ module Typelizer
         end
       end
 
-      def nested_schema(property, openapi_version:)
+      def nested_schema(property, openapi_version:, type_mapping:)
         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)] }
+          properties: property.nested_properties.to_h { |p| [p.name, property_schema(p, openapi_version: openapi_version, type_mapping: type_mapping)] }
         }
         schema[:required] = required if required.any?
         schema
       end
 
+      def type_mapping_overridden?(property, type_mapping)
+        type_mapping[property.column_type] != TYPE_MAPPING[property.column_type]
+      end
+
       def v31?(openapi_version)
         openapi_version.to_s == "3.1"
       end

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

@@ -111,17 +111,7 @@ module Typelizer
       private
 
       def normalize_typelize(type_def, **options)
-        case type_def
-        when Array
-          # [:string, nullable: true] or ['string?', nullable: true]
-          type, *rest = type_def
-          opts = rest.first || {}
-          TypeParser.parse(type, **opts)
-        when Symbol, String
-          TypeParser.parse(type_def, **options)
-        else
-          options
-        end
+        TypeParser.parse_declaration(type_def, **options)
       end
     end
   end

data/lib/typelizer/serializer_plugins/alba.rb

@@ -61,11 +61,12 @@ module Typelizer
       def build_collected_property(name, attr)
         case attr
         when BlockAttributeCollector::BlockAssociation
+          prop_name = has_transform_key?(serializer) ? fetch_key(serializer, name) : name
           with_traits = Array(attr.with_traits) if attr.with_traits
           resource = attr.resource || infer_resource_from_name(name)
 
           Property.new(
-            name: name,
+            name: prop_name,
             type: resource ? context.interface_for(resource) : nil,
             optional: false,
             nullable: false,

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

@@ -5,8 +5,8 @@ export type { <%= ImportSorter.sort(enums.map(&:enum_type_name), imports_sort_or
 <%- interfaces.each do |interface| -%>
 <%- sorted_traits = ImportSorter.sort(interface.trait_interfaces.map(&:name), interface.config.imports_sort_order) -%>
 <%- if interface.config.verbatim_module_syntax -%>
-export type { <%= interface.name %><%= ", " + sorted_traits.join(", ") if sorted_traits.any? %> } from <%= interface.quote('./' + interface.filename) %>
+export type { <%= interface.name %><%= ", " + sorted_traits.join(", ") if sorted_traits.any? %> } from <%= interface.quote(interface.index_path(index_dir)) %>
 <%- else -%>
-export type { default as <%= interface.name %><%= ", " + sorted_traits.join(", ") if sorted_traits.any? %> } from <%= interface.quote('./' + interface.filename) %>
+export type { default as <%= interface.name %><%= ", " + sorted_traits.join(", ") if sorted_traits.any? %> } from <%= interface.quote(interface.index_path(index_dir)) %>
 <%- end -%>
 <%- end -%>

data/lib/typelizer/type_parser.rb

@@ -10,6 +10,17 @@ module Typelizer
     TYPE_PATTERN = /\A(.+?)(\?)?(\[\])?(\?)?\z/
 
     class << self
+      def parse_declaration(attrs, **options)
+        return options.merge(attrs) if attrs.is_a?(Hash)
+        return parse(attrs, **options) unless attrs.is_a?(Array)
+
+        options = attrs.last.merge(options) if attrs.last.is_a?(Hash)
+        types = attrs.reject { |t| t.is_a?(Hash) }
+        return options if types.empty?
+
+        parse((types.size == 1) ? types.first : types, **options)
+      end
+
       def parse(type_def, **options)
         return options if type_def.nil?
         return parse_array(type_def, **options) if type_def.is_a?(Array)
@@ -41,22 +52,28 @@ module Typelizer
       private
 
       def parse_array(type_defs, **options)
-        parsed = type_defs.map { |t| parse(t) }
-        types = parsed.flat_map { |p| Array(p[:type]) }
-
-        parsed.each do |p|
-          options[:optional] = true if p[:optional]
-          options[:multi] = true if p[:multi]
-          options[:nullable] = true if p[:nullable]
+        raise ArgumentError, "Empty array passed to typelize" if type_defs.empty?
+
+        types = []
+        type_defs.each do |t|
+          if t.is_a?(String)
+            types << :"'#{t}'"
+          else
+            parsed = parse(t)
+            types.concat(Array(parsed[:type]))
+            options[:optional] = true if parsed[:optional]
+            options[:multi] = true if parsed[:multi]
+            options[:nullable] = true if parsed[:nullable]
+          end
         end
 
         options[:nullable] = true if types.delete(:null)
+        wrap_type(types, **options)
+      end
 
-        if types.size == 1
-          {type: types.first}.merge(options)
-        else
-          {type: types}.merge(options)
-        end
+      def wrap_type(types, **options)
+        type = (types.size == 1) ? types.first : types
+        {type: type}.merge(options)
       end
 
       def parse_union(type_str, **options)

data/lib/typelizer/version.rb

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

data/lib/typelizer/writer.rb

@@ -12,7 +12,7 @@ module Typelizer
     end
 
     def call(interfaces, force:)
-      cleanup_output_dir if force
+      cleanup_output_dir(interfaces) if force
 
       valid_interfaces = interfaces.reject(&:empty?)
       return [] if valid_interfaces.empty?
@@ -27,7 +27,7 @@ module Typelizer
 
         written_files << write_index(valid_interfaces, enums: enums)
 
-        cleanup_stale_files(written_files) unless force
+        cleanup_stale_files(written_files, valid_interfaces) unless force
 
         Typelizer.logger.debug("Generated #{written_files.size} TypeScript files in #{config.output_dir}")
 
@@ -43,10 +43,10 @@ module Typelizer
 
     attr_reader :config, :template_cache
 
-    def cleanup_stale_files(written_files)
-      return unless File.directory?(config.output_dir)
+    def cleanup_stale_files(written_files, interfaces)
+      output_dirs = output_dirs_for(interfaces)
 
-      existing_files = Dir[File.join(config.output_dir, "**/*.ts")]
+      existing_files = output_dirs.flat_map { |dir| Dir[File.join(dir, "**/*.ts")] }
       stale_files = existing_files - written_files
 
       File.delete(*stale_files) unless stale_files.empty?
@@ -70,22 +70,23 @@ module Typelizer
       fingerprint = [
         enums.map(&:enum_type_name),
         interfaces.map { |i|
-          [i.name, i.filename, i.trait_interfaces.map(&:name), CONFIGS_AFFECTING_INDEX_OUTPUT.map { |key| i.config.public_send(key) }]
+          [i.name, i.filename, i.index_path(config.output_dir.to_s), i.trait_interfaces.map(&:name), CONFIGS_AFFECTING_INDEX_OUTPUT.map { |key| i.config.public_send(key) }]
         }
       ].inspect
       write_file("index.ts", fingerprint) do
-        render_template("index.ts.erb", interfaces: interfaces, enums: enums, imports_sort_order: config.imports_sort_order, prefer_double_quotes: config.prefer_double_quotes)
+        render_template("index.ts.erb", interfaces: interfaces, enums: enums, index_dir: config.output_dir.to_s, imports_sort_order: config.imports_sort_order, prefer_double_quotes: config.prefer_double_quotes)
       end
     end
 
     def write_interface(interface)
-      write_file("#{interface.filename}.ts", interface.fingerprint) do
+      output_dir = interface.config.output_dir
+      write_file("#{interface.filename}.ts", interface.fingerprint, output_dir: output_dir) do
         render_template("interface.ts.erb", interface: interface)
       end
     end
 
-    def write_file(filename, fingerprint)
-      output_file = File.join(config.output_dir, filename)
+    def write_file(filename, fingerprint, output_dir: config.output_dir)
+      output_file = File.join(output_dir, filename)
       existing_content = File.exist?(output_file) ? File.read(output_file) : nil
       digest = render_template("fingerprint.ts.erb", fingerprint: fingerprint)
 
@@ -104,8 +105,14 @@ module Typelizer
       template_cache[template].call(**context)
     end
 
-    def cleanup_output_dir
-      FileUtils.rm_rf(config.output_dir)
+    def cleanup_output_dir(interfaces)
+      output_dirs_for(interfaces).each { |dir| FileUtils.rm_rf(dir) }
+    end
+
+    def output_dirs_for(interfaces)
+      dirs = interfaces.filter_map { |i| i.config.output_dir.to_s unless i.empty? }
+      dirs << config.output_dir.to_s
+      dirs.uniq
     end
 
     def cleanup_partial_writes(partial_files)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typelizer
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 0.11.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov