Treat strings as literal types in array declarations

Author: skryukov

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+### 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

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

lib/typelizer/dsl.rb

@@ -87,8 +87,7 @@ def assign_type_information(attribute_name, attributes)
         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 @@ def ensure_type_store(attribute_name)
           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

lib/typelizer/serializer_plugins/alba/block_attribute_collector.rb

@@ -111,17 +111,7 @@ def respond_to_missing?(method_name, include_private = false)
       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

lib/typelizer/type_parser.rb

@@ -10,6 +10,17 @@ module TypeParser
     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 @@ def shortcut?(type_def)
       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)

spec/app/app/serializers/alba/class_ref_serializer.rb

@@ -20,11 +20,11 @@ class ClassRefSerializer < BaseSerializer
 
     # Test: typelize with union of two serializer classes generates anyOf in OpenAPI
     attributes :commentable
-    typelize commentable: ["Alba::UserSerializer", "Alba::CommentSerializer"]
+    typelize commentable: "Alba::UserSerializer | Alba::CommentSerializer"
 
-    # Test: typelize with mixed string and class constant in union
+    # Test: typelize with mixed class constants in union
     attributes :mixed_ref
-    typelize mixed_ref: ["Alba::UserSerializer", CommentSerializer]
+    typelize mixed_ref: [UserSerializer, CommentSerializer]
 
     # Test: nullable array of refs — nullable applies to array, not items
     attributes :contributors

spec/app/app/serializers/alba/custom_types_serializer.rb

@@ -63,7 +63,7 @@ class CustomTypesSerializer < BaseSerializer
     end
 
     # Keyless array typelize (union from array)
-    typelize ["string", "number"]
+    typelize [:string, :number]
 
     attribute :tag do |user|
       "important"

spec/app/app/serializers/alba/union_sorted_serializer.rb

@@ -9,13 +9,13 @@ class UnionSortedSerializer < BaseSerializer
     typelize_from ::User
 
     # Union type with multiple types - should be sorted alphabetically
-    typelize sections: ["ZebraSection", "AlphaSection", "BetaSection"]
+    typelize sections: [:ZebraSection, :AlphaSection, :BetaSection]
     attribute :sections do |user|
       []
     end
 
     # Union type in an array - should be sorted inside Array<>
-    typelize items: ["TypeZ", "TypeA", "TypeM", multi: true]
+    typelize items: [:TypeZ, :TypeA, :TypeM, multi: true]
     attribute :items do |user|
       []
     end

spec/app/app/serializers/ams/class_ref_serializer.rb

@@ -20,11 +20,11 @@ class ClassRefSerializer < BaseSerializer
 
     # Test: typelize with union of two serializer classes generates anyOf in OpenAPI
     attribute :commentable
-    typelize commentable: ["Ams::UserSerializer", "Ams::CommentSerializer"]
+    typelize commentable: "Ams::UserSerializer | Ams::CommentSerializer"
 
-    # Test: typelize with mixed string and class constant in union
+    # Test: typelize with mixed class constants in union
     attribute :mixed_ref
-    typelize mixed_ref: ["Ams::UserSerializer", CommentSerializer]
+    typelize mixed_ref: [UserSerializer, CommentSerializer]
 
     # Test: nullable array of refs — nullable applies to array, not items
     attribute :contributors

spec/app/app/serializers/ams/custom_types_serializer.rb

@@ -30,7 +30,7 @@ class CustomTypesSerializer < BaseSerializer
     typelize kind: "'user' | null"
     attribute :kind
 
-    typelize ["string", "number"]
+    typelize [:string, :number]
     attribute :tag
   end
 end