Add properties_sort_order configuration

Author: skryukov

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+### Added
+
+- New `properties_sort_order` configuration option for consistent property ordering in generated TypeScript interfaces. ([@skryukov])
+
+  ```ruby
+  Typelizer.configure do |config|
+    # Sort properties alphabetically with 'id' first
+    config.properties_sort_order = :id_first_alphabetical
+  end
+  ```
+
+  Available options:
+  - `:none` (default) - preserve serializer definition order
+  - `:alphabetical` - sort properties A-Z (case-insensitive)
+  - `:id_first_alphabetical` - place `id` first, then sort remaining A-Z
+  - `Proc` - custom sorting logic
+
+  ```ruby
+  # Custom sorting example
+  config.properties_sort_order = ->(props) {
+    priority = %w[id uuid type]
+    props.sort_by { |p| [priority.index(p.name) || 999, p.name] }
+  }
+  ```
+
 ## [0.5.4] - 2025-12-08
 
 ### Added

README.md

@@ -486,6 +486,13 @@ Typelizer.configure do |config|
   # Custom transformation for generated properties
   config.properties_transformer = ->(properties) { ... }
 
+  # Strategy for ordering properties in generated TypeScript interfaces
+  # :none - preserve serializer definition order (default)
+  # :alphabetical - sort properties A-Z (case-insensitive)
+  # :id_first_alphabetical - place 'id' first, then sort remaining A-Z
+  # Proc - custom sorting function receiving array of Property objects
+  config.properties_sort_order = :none
+
   # Plugin for model type inference (default: ModelPlugins::Auto)
   config.model_plugin = Typelizer::ModelPlugins::Auto
 

lib/typelizer.rb

@@ -11,6 +11,7 @@
 
 require_relative "typelizer/contexts/writer_context"
 require_relative "typelizer/contexts/scan_context"
+require_relative "typelizer/property_sorter"
 require_relative "typelizer/interface"
 require_relative "typelizer/renderer"
 require_relative "typelizer/writer"

lib/typelizer/config.rb

@@ -23,6 +23,7 @@ module Typelizer
     :serializer_name_mapper,
     :serializer_model_mapper,
     :properties_transformer,
+    :properties_sort_order,
     :model_plugin,
     :serializer_plugin,
     :plugin_configs,
@@ -77,6 +78,7 @@ def self.defaults
         types_import_path: "@/types",
         types_global: DEFAULT_TYPES_GLOBAL,
         properties_transformer: nil,
+        properties_sort_order: :none,
         verbatim_module_syntax: false
       }
     end

lib/typelizer/interface.rb

@@ -48,7 +48,7 @@ def meta_fields
         props = serializer_plugin.meta_fields || []
         props = infer_types(props, :_typelizer_meta_attributes)
         props = config.properties_transformer.call(props) if config.properties_transformer
-        props
+        PropertySorter.sort(props, config.properties_sort_order)
       end
     end
 
@@ -63,7 +63,7 @@ def properties
         props = serializer_plugin.properties
         props = infer_types(props)
         props = config.properties_transformer.call(props) if config.properties_transformer
-        props
+        PropertySorter.sort(props, config.properties_sort_order)
       end
     end
 

lib/typelizer/property_sorter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Typelizer
+  module PropertySorter
+    def self.sort(props, sort_order)
+      case sort_order
+      when :none, nil
+        props
+      when :alphabetical
+        props.sort_by { |p| p.name.to_s.downcase }
+      when :id_first_alphabetical
+        props.sort_by { |p| [(p.name.to_s.downcase == "id") ? 0 : 1, p.name.to_s.downcase] }
+      when Proc
+        result = sort_order.call(props)
+        result.is_a?(Array) ? result : props
+      else
+        props
+      end
+    rescue => e
+      Typelizer.logger.warn("PropertySorter error: #{e.message}, preserving original order")
+      props
+    end
+  end
+end

lib/typelizer/serializer_plugins/alba/trait_interface.rb

@@ -24,7 +24,8 @@ def name
       def properties
         @properties ||= begin
           props, typelizes = plugin.trait_properties(trait_name)
-          infer_types(props, typelizes)
+          props = infer_types(props, typelizes)
+          PropertySorter.sort(props, config.properties_sort_order)
         end
       end
 

spec/__snapshots__/AlbaSorted.ts.snap

@@ -0,0 +1,15 @@
+// Typelizer digest f8e75a4b9244dcdf1ea5cd6d19a22b4f
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type AlbaSorted = {
+  /** Unique identifier */
+  id: string;
+  active: boolean;
+  created_at: string;
+  email: string;
+  name: string;
+  username: string;
+}
+
+export default AlbaSorted;

spec/__snapshots__/AmsSorted.ts.snap

@@ -0,0 +1,15 @@
+// Typelizer digest a36bbfd40b96d00529cd6cafcf56d333
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type AmsSorted = {
+  /** Unique identifier */
+  id: string;
+  active: boolean;
+  created_at: string;
+  email: string;
+  name: string;
+  username: string;
+}
+
+export default AmsSorted;

spec/__snapshots__/OjSerializersSorted.ts.snap

@@ -0,0 +1,15 @@
+// Typelizer digest d263b621499bd3c11087ff72062a6e6d
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+type OjSerializersSorted = {
+  /** Unique identifier */
+  id: string;
+  active: boolean;
+  created_at: string;
+  email: string;
+  name: string;
+  username: string;
+}
+
+export default OjSerializersSorted;