philosophal 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1bb80908d227d997cf25e816e00335f9c61328aa4eb285ee7c51632adfcc9cb
-  data.tar.gz: 56ca323ff898cb43b8604850e0ea94cd5b323c236d365a70ad8d36e9321bd01f
+  metadata.gz: d588fe0288b3b4d953de700a9218a607b4e7fc23d3946a8e34b4a1f90a7f1265
+  data.tar.gz: cf23c471421f8661992e575bfef9edb21e2a659962c0f54ec1618f0047b23b87
 SHA512:
-  metadata.gz: 2cf9f37bd111eb6ca5c021a5fefd0da9b7cf48e624adf5ac9d12c57f885315b327ae1539946744317fbd120623455b82fe5d9aa3186a0613d9cb72f2102785ec
-  data.tar.gz: 70f39c48ee39f045a7208e141b1cd56c7cff8f6871e17a855628d2b85007ee7fe850df89fa084615eb26585078a5f0b4e2623e45b1d0befb59c4a9f62af4ba3c
+  metadata.gz: ae95691e4be606dbca97f8c3a1e3ccf96b34a310b95a5f07567cc8e2c80f37491ae92e03ecc4d60cfc851c0147d8b63ea0b9bb4cc16f64b1c32e06b1fdb33ed4
+  data.tar.gz: 3db4c56bea72d05e0e7a2d75a65842d567e6f2c33f8a37ffcdf2a82374c404c6cc37ce3dec376e94f004b55d3dd6182de8a15518f962d7f70f7aa26effceeb39

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.0.0] - 2026-11-03
+
+- Add: new `track_changes:` option for `cprop`, which defines `prop_was` (the value at the last `changes_applied`) and `prop_changed?` (the value differs from it)
+- Add: `changes_applied` records the current values of the tracked properties as the reference
+- Add: `changed_properties` returns a hash of the tracked properties changed since the last `changes_applied`, with their new value
+- Add: RBS type signatures (`sig/`), shipped with the gem
+- Fix: **ArrayOf** and **HashOf** no longer accept `nil` or `false` entries of the wrong type without converting them
+- Fix: converting to **ArrayOf** or **HashOf** no longer modifies the given array or hash
+- Perf: the reader of a property without default is now a plain `attr_reader`
+- Perf: writers, and readers falling back to their default, no longer look up their property in the schema
+- Breaking: redeclaring in a subclass, with a default and `override: false`, a property no longer applies the subclass default or type (the parent methods are kept)
+- Perf: fewer lookups and allocations when converting, loading JSON, `to_json_hash`, `changes_applied` and `changed_properties`
+- Fix: `Properties::Schema` now defines `each`, so its Enumerable methods (`map`, `select`, `find`...) work and yield the properties
+
 ## [1.3.0] - 2026-10-19
 
 - Breaking: minimum required Ruby version is now **3.3** (was 3.1)

data/README.md

@@ -28,3 +28,42 @@ maxime.age = '40'
 puts maxime.inspect
 #<Person:0x00007da7088eed88 @first_name="maxime", @last_name="DÉSÉCOT", @age=40>
 ````
+
+### Tracking changes
+
+With `track_changes: true`, a property also gets `<name>_was` and `<name>_changed?`.
+Call `changes_applied` once the object is in a known state (built, loaded, saved...):
+`<name>_was` returns the value at that moment, and `<name>_changed?` tells whether the value differs from it.
+
+```ruby
+class Article
+  extend Philosophal::Properties
+
+  cprop :title, String, track_changes: true
+end
+
+article = Article.new
+article.title = 'Draft'
+article.title_changed? # => true (no reference yet)
+article.changes_applied
+article.title_changed? # => false
+article.title = 'Review'
+article.title = 'Final'
+article.title_was      # => "Draft"
+article.title_changed? # => true
+article.title = 'Draft'
+article.title_changed? # => false
+```
+
+`changed_properties` returns the tracked properties that changed, with their new value:
+
+```ruby
+article.title = 'Final'
+article.changed_properties # => { title: "Final" }
+article.changes_applied
+article.changed_properties # => {}
+```
+
+Before the first `changes_applied`, the reference is "never assigned": every assigned property is changed.
+`<name>_was` returns the stored value, without falling back to the default.
+`json.load` does not call `changes_applied`: call it on the loaded objects if they must start unchanged.

data/lib/philosophal/convertor.rb

@@ -102,9 +102,9 @@ module Philosophal
           return false if obj.zero?
 
         elsif obj.is_a?(String)
-          obj_downcase = obj.downcase
-          return true if obj_downcase == 'true'
-          return false if obj_downcase == 'false'
+          # casecmp compares ASCII only, which is enough for 'true' and 'false', and allocates no string.
+          return true if obj.casecmp('true') == 0 # rubocop:disable Style/NumericPredicate
+          return false if obj.casecmp('false') == 0 # rubocop:disable Style/NumericPredicate
 
         end
         raise Philosophal::TypeError
@@ -120,11 +120,8 @@ module Philosophal
         subtype_convert_method = convert_method_for(subtype)
         raise Philosophal::TypeError unless subtype_convert_method
 
-        convert_to_array(obj).tap do |new_obj|
-          new_obj.map! do |item|
-            send(subtype_convert_method, item)
-          end
-        end
+        # map, not map!: Array#to_a returns the given array itself, which must not be modified.
+        convert_to_array(obj).map { |item| send(subtype_convert_method, item) }
       end
 
       def convert_to_hash_of(obj, subtype)
@@ -134,9 +131,9 @@ module Philosophal
         value_convert_method = convert_method_for(subtype[:value_type])
         raise Philosophal::TypeError unless value_convert_method
 
-        convert_to_hash(obj).tap do |new_obj|
-          new_obj.transform_keys! { |key| send(key_convert_method, key) }
-          new_obj.transform_values! { |value| send(value_convert_method, value) }
+        # A new hash is built: Hash#to_h returns the given hash itself, which must not be modified.
+        convert_to_hash(obj).to_h do |key, value|
+          [send(key_convert_method, key), send(value_convert_method, value)]
         end
       end
     end

data/lib/philosophal/loaders/json_loader.rb

@@ -46,12 +46,7 @@ module Philosophal
       end
 
       def setter_from_key(key)
-        real_key = @klass.philosophal_properties.json_names_h[key]
-        property = @klass.philosophal_properties[real_key]
-
-        return :"#{property.name}=" if property
-
-        :"#{key}="
+        @klass.philosophal_properties.json_setters[key] || :"#{key}="
       end
 
       def load_from_json(str)

data/lib/philosophal/properties/instance_methods.rb

@@ -26,7 +26,7 @@ module Philosophal
       alias cprop_inspect philosophal_inspect
 
       def philosophal_inspect_map
-        philosophal_values.to_h do |property|
+        self.class.philosophal_properties.to_h do |property|
           [
             property.name,
             send(property.name)
@@ -39,8 +39,28 @@ module Philosophal
         self.class.philosophal_properties.properties_index.values
       end
 
+      # Properties declared with track_changes: true whose value changed since the last changes_applied,
+      # with their new value.
+      def changed_properties
+        self.class.philosophal_properties.tracked.each_with_object({}) do |property, changes|
+          next unless send(property.changed_method_name)
+
+          changes[property.name] = send(property.name)
+        end
+      end
+
+      # Records the current values as the reference of the tracked properties: none of them is changed anymore.
+      # The values are duplicated, so modifying one in place is still seen as a change.
+      def changes_applied
+        self.class.philosophal_properties.tracked.each do |property|
+          instance_variable_set(property.was_variable_name, instance_variable_get(property.variable_name).dup)
+        end
+
+        self
+      end
+
       def to_json_hash
-        philosophal_values.select(&:json).to_h do |property|
+        self.class.philosophal_properties.json_properties.to_h do |property|
           [
             property.json_name,
             send(property.name)

data/lib/philosophal/properties/schema.rb

@@ -28,6 +28,14 @@ module Philosophal
         @properties_index.keys
       end
 
+      # Yields each property in declaration order; Enumerable builds on it.
+      def each(&)
+        return enum_for(:each) { @properties_index.size } unless block_given?
+
+        @properties_index.each_value(&)
+        self
+      end
+
       def <<(value)
         @mutex.synchronize do
           @properties_index[value.name] = value
@@ -57,10 +65,33 @@ module Philosophal
         end
       end
 
+      # Maps each JSON name to the writer of its property.
+      def json_setters
+        return @json_setters if defined?(@json_setters)
+
+        @json_setters = @properties_index.each_value.to_h do |property|
+          [property.json_name, property.writer_method_name]
+        end
+      end
+
+      # Properties declared with json: (exported by to_json_hash).
+      def json_properties
+        return @json_properties if defined?(@json_properties)
+
+        @json_properties = @properties_index.each_value.select(&:json)
+      end
+
+      # Properties declared with track_changes: true.
+      def tracked
+        return @tracked if defined?(@tracked)
+
+        @tracked = @properties_index.each_value.select(&:track_changes?)
+      end
+
       private
 
       def clear_caches
-        %i[@immutables @mutables @json_names_h].each do |cache|
+        %i[@immutables @mutables @json_names_h @json_setters @json_properties @tracked].each do |cache|
           remove_instance_variable(cache) if instance_variable_defined?(cache)
         end
       end

data/lib/philosophal/properties.rb

@@ -8,15 +8,16 @@ module Philosophal
 
     include Philosophal::Types
 
-    def cprop(name, type, default: nil, transform: nil, immutable: false, description: nil, json: false, override: true)
-      __check_philosophal_options__(name, transform:, immutable:, override:, description:, json:)
+    def cprop(name, type, default: nil, transform: nil, immutable: false, description: nil, json: false, override: true,
+              track_changes: false)
+      __check_philosophal_options__(name, transform:, immutable:, override:, description:, json:, track_changes:)
 
       default.freeze unless default.is_a?(Proc)
       description&.freeze
       json = json.to_sym if json.is_a?(String)
 
       property = __philosophal_property_class__.new(
-        name:, type:, default:, transform:, immutable:, description:, json:, override:
+        name:, type:, default:, transform:, immutable:, description:, json:, override:, track_changes:
       )
 
       philosophal_properties << property
@@ -61,10 +62,20 @@ module Philosophal
     end
 
     def __define_philosophal_methods__(new_property)
+      __set_philosophal_property_constant__(new_property)
       code =	__generate_philosophal_methods__(new_property)
       __philosophal_extension__.module_eval(code)
     end
 
+    # The constant is replaced when the property is redeclared in the same class.
+    def __set_philosophal_property_constant__(property)
+      extension = __philosophal_extension__
+      constant_name = property.constant_name
+      extension.send(:remove_const, constant_name) if extension.const_defined?(constant_name, false)
+      extension.const_set(constant_name, property)
+      extension.private_constant(constant_name)
+    end
+
     def __philosophal_extension__
       @__philosophal_extension__ ||= Module.new { include Philosophal::Properties::InstanceMethods }
     end
@@ -86,17 +97,21 @@ module Philosophal
     end
 
     # Generated methods live in an included module, so a method defined in the class itself
-    # would hide them: it is removed to let the property override it.
+    # would hide them: it is removed to let the property override it. The method generated by a
+    # previous declaration of the property is removed too, so redefining it raises no warning.
     def __remove_philosophal_own_method__(method_name)
-      return unless method_defined?(method_name, false) || private_method_defined?(method_name, false)
+      [self, __philosophal_extension__].each do |owner|
+        next unless owner.method_defined?(method_name, false) || owner.private_method_defined?(method_name, false)
 
-      remove_method(method_name)
+        owner.remove_method(method_name)
+      end
     end
 
-    def __check_philosophal_options__(name, transform:, immutable:, override:, description:, json:)
+    def __check_philosophal_options__(name, transform:, immutable:, override:, description:, json:, track_changes:)
       __check_philosophal_transform_option__(name, transform)
       __check_philosophal_boolean_option__(:override, override)
       __check_philosophal_boolean_option__(:immutable, immutable)
+      __check_philosophal_boolean_option__(:track_changes, track_changes)
 
       if description && !description.is_a?(String)
         raise Philosophal::ArgumentError, 'description param must be a string.'

data/lib/philosophal/property.rb

@@ -2,7 +2,8 @@
 
 module Philosophal
   class Property
-    def initialize(name:, type:, default:, transform:, immutable:, description:, json:, override:)
+    def initialize(name:, type:, default:, transform:, immutable:, description:, json:, override:,
+                   track_changes: false)
       @name = name
       @type = type
       @default = default
@@ -11,9 +12,10 @@ module Philosophal
       @description = description
       @json = json
       @override = override
+      @track_changes = track_changes
     end
 
-    attr_reader :name, :type, :default, :transform, :immutable, :description, :json, :override
+    attr_reader :name, :type, :default, :transform, :immutable, :description, :json, :override, :track_changes
 
     def json_name
       return @json if @json.is_a?(Symbol)
@@ -40,18 +42,43 @@ module Philosophal
       @override
     end
 
+    def track_changes?
+      @track_changes
+    end
+
     def check_conversion(value)
       Philosophal.convert(self, value)
     end
 
+    # The Convertor method (and subtype) for the type, looked up once since the type never changes.
+    def convert_method
+      return @convert_method if defined?(@convert_method)
+
+      @convert_method = Philosophal::Convertor.convert_method_for(@type)
+    end
+
     def method_generators
       generators = {
         writer_method_name => immutable ? :generate_immutable_writer_method : :generate_writer_method,
-        reader_method_name => :generate_reader_method
+        reader_method_name => default? ? :generate_reader_method : :generate_plain_reader_method
       }
       generators[boolean_method_name] = :generate_boolean_method if type == Philosophal::Types::BooleanType::Instance
       generators[description_method_name] = :generate_description_method if description
-      generators
+      generators.merge(change_tracking_generators)
+    end
+
+    def change_tracking_generators
+      return {} unless track_changes?
+
+      { was_method_name => :generate_was_method, changed_method_name => :generate_changed_method }
+    end
+
+    # Private constant of the generated methods module holding this property, so the writers
+    # reach it without looking it up in the schema.
+    def constant_name
+      return @constant_name if defined? @constant_name
+
+      @constant_name = :"PHILOSOPHAL_PROPERTY_#{@name.name}"
     end
 
     def writer_method_name
@@ -63,7 +90,7 @@ module Philosophal
     def generate_writer_method(buffer)
       buffer << <<~RUBY
         def #{writer_method_name.name}(value)
-          @#{@name.name} = self.class.philosophal_properties[:#{@name.name}].check_conversion(value)
+          @#{@name.name} = #{constant_name}.check_conversion(value)
         rescue Philosophal::TypeError => error
           error.set_backtrace(caller(1))
           raise
@@ -75,7 +102,7 @@ module Philosophal
       buffer << <<~RUBY
         def #{writer_method_name.name}(value)
           raise FrozenError, "can't modify frozen variable @#{@name.name}" if defined?(@#{@name.name})
-          @#{@name.name} = self.class.philosophal_properties[:#{@name.name}].check_conversion(value).freeze
+          @#{@name.name} = #{constant_name}.check_conversion(value).freeze
         rescue Philosophal::TypeError => error
           error.set_backtrace(caller(1))
           raise
@@ -87,10 +114,23 @@ module Philosophal
       @name
     end
 
+    def variable_name
+      return @variable_name if defined? @variable_name
+
+      @variable_name = :"@#{@name.name}"
+    end
+
+    # Without a default the reader only returns the variable: attr_reader is the fastest form.
+    # The default is not looked up, so a subclass redeclaring the property with a default and
+    # override: false keeps this reader and does not get its default (not supported).
+    def generate_plain_reader_method(buffer)
+      buffer << "attr_reader :#{reader_method_name.name}\n"
+    end
+
     def generate_reader_method(buffer)
       buffer << <<~RUBY
         def #{reader_method_name.name}
-          @#{@name.name}.nil? ? self.class.philosophal_properties[:#{@name.name}].default_value : @#{@name.name}
+          @#{@name.name}.nil? ? #{constant_name}.default_value : @#{@name.name}
         end
       RUBY
     end
@@ -115,12 +155,48 @@ module Philosophal
       @description_method_name = :"#{@name.name}_description"
     end
 
-    # The description is read from the schema rather than written into the generated code,
+    def was_method_name
+      return @was_method_name if defined? @was_method_name
+
+      @was_method_name = :"#{@name.name}_was"
+    end
+
+    def was_variable_name
+      return @was_variable_name if defined? @was_variable_name
+
+      @was_variable_name = :"@__philosophal_#{@name.name}_was__"
+    end
+
+    # Returns the stored value at the last changes_applied (nil before), without falling back to the default.
+    def generate_was_method(buffer)
+      buffer << <<~RUBY
+        def #{was_method_name.name}
+          #{was_variable_name}
+        end
+      RUBY
+    end
+
+    def changed_method_name
+      return @changed_method_name if defined? @changed_method_name
+
+      @changed_method_name = :"#{@name.name}_changed?"
+    end
+
+    # True when the stored value differs from the one recorded at the last changes_applied.
+    def generate_changed_method(buffer)
+      buffer << <<~RUBY
+        def #{changed_method_name.name}
+          @#{@name.name} != #{was_variable_name}
+        end
+      RUBY
+    end
+
+    # The description is read from the property constant rather than written into the generated code,
     # so it is never evaluated as Ruby.
     def generate_description_method(buffer)
       buffer << <<~RUBY
         def #{description_method_name.name}
-          self.class.philosophal_properties[:#{@name.name}].description
+          #{constant_name}.description
         end
       RUBY
     end

data/lib/philosophal/transform.rb

@@ -10,7 +10,7 @@ module Philosophal
     end
 
     def self.self_method?(method)
-      method.to_s.end_with?('!')
+      method.end_with?('!')
     end
   end
 end

data/lib/philosophal/types/array_of_type.rb

@@ -22,7 +22,7 @@ module Philosophal
       end
 
       def ===(array)
-        array.is_a?(Array) && !array.find { |entry| !entry.is_a?(@subtype) }
+        array.is_a?(Array) && array.all?(@subtype)
       end
     end
   end

data/lib/philosophal/types/boolean_type.rb

@@ -8,7 +8,7 @@ module Philosophal
       TRUE_FALSE_SET = Set[true, false]
 
       def ===(value)
-        TRUE_FALSE_SET.include?(value)
+        true.equal?(value) || false.equal?(value)
       end
 
       freeze

data/lib/philosophal/types/hash_of_type.rb

@@ -22,9 +22,11 @@ module Philosophal
       end
 
       def ===(hash)
-        hash.is_a?(Hash) &&
-          !hash.keys.find { |key| !key.is_a?(@subtype[:key_type]) } &&
-          !hash.values.find { |value| !value.is_a?(@subtype[:value_type]) }
+        return false unless hash.is_a?(Hash)
+
+        key_type = @subtype[:key_type]
+        value_type = @subtype[:value_type]
+        hash.all? { |key, value| key.is_a?(key_type) && value.is_a?(value_type) }
       end
     end
   end

data/lib/philosophal.rb

@@ -22,14 +22,14 @@ module Philosophal
     # nil means "no value": it is neither converted nor transformed, so the reader falls back to the default.
     return if value.nil?
 
-    converted = property.type === value ? value : convert_to_type(property.type, value) # rubocop:disable Style/CaseEquality
+    converted = property.type === value ? value : convert_to_type(property, value) # rubocop:disable Style/CaseEquality
     return converted unless property.transform?
 
     Transform.make(property.transform, converted)
   end
 
-  def self.convert_to_type(type, value)
-    convert_method, subtype = Convertor.convert_method_for(type)
+  def self.convert_to_type(property, value)
+    convert_method, subtype = property.convert_method
     raise Philosophal::TypeError unless convert_method
 
     if subtype

data/sig/manifest.yaml

@@ -0,0 +1,5 @@
+dependencies:
+  - name: date
+  - name: json
+  - name: pathname
+  - name: time

data/sig/philosophal/convertor.rbs

@@ -0,0 +1,35 @@
+module Philosophal
+  class Convertor
+    METHOD_TYPE_MAP: Hash[untyped, Symbol]
+
+    def self.convert_method_for: (type_spec type) -> (Symbol | [Symbol?, untyped] | nil)
+
+    def self.convert_to_symbol: (untyped obj) -> Symbol
+
+    def self.convert_to_string: (untyped obj) -> String
+
+    def self.convert_to_integer: (untyped obj) -> Integer
+
+    def self.convert_to_float: (untyped obj) -> Float
+
+    def self.convert_to_array: (untyped obj) -> Array[untyped]
+
+    def self.convert_to_hash: (untyped obj) -> Hash[untyped, untyped]
+
+    def self.convert_to_time: (untyped obj) -> Time
+
+    def self.convert_to_date: (untyped obj) -> Date
+
+    def self.convert_to_date_time: (untyped obj) -> DateTime
+
+    def self.convert_to_any: [T] (T obj) -> T
+
+    def self.convert_to_boolean: (untyped obj) -> bool
+
+    def self.convert_to_pathname: (untyped obj) -> Pathname
+
+    def self.convert_to_array_of: (untyped obj, Module subtype) -> Array[untyped]
+
+    def self.convert_to_hash_of: (untyped obj, Types::HashOfType::subtype subtype) -> Hash[untyped, untyped]
+  end
+end

data/sig/philosophal/errors/argument_error.rbs

@@ -0,0 +1,4 @@
+module Philosophal
+  class ArgumentError < ::ArgumentError
+  end
+end

data/sig/philosophal/errors/type_error.rbs

@@ -0,0 +1,4 @@
+module Philosophal
+  class TypeError < ::TypeError
+  end
+end

data/sig/philosophal/loaders/errors.rbs

@@ -0,0 +1,6 @@
+module Philosophal
+  module Loaders
+    class LoadError < StandardError
+    end
+  end
+end

data/sig/philosophal/loaders/json_loader.rbs

@@ -0,0 +1,29 @@
+module Philosophal
+  module Loaders
+    class JsonLoader
+      @klass: untyped
+
+      def initialize: (Properties klass) -> void
+
+      # A Hash or a JSON object string returns one instance, an Array or a JSON array string returns a list,
+      # any other String is read as a path to a JSON file.
+      def load: (Hash[Symbol, untyped] json) -> untyped
+              | (Array[Hash[Symbol, untyped]] json) -> Array[untyped]
+              | (String json) -> untyped
+
+      private
+
+      def load_from_array: (Array[Hash[Symbol, untyped]] array) -> Array[untyped]
+
+      def load_from_hash: (Hash[Symbol, untyped] hash) -> untyped
+
+      def setter_from_key: (Symbol key) -> Symbol
+
+      def load_from_json: (String str) -> untyped
+
+      def load_from_json_collection: (String json) -> Array[untyped]
+
+      def load_from_path: (String path) -> untyped
+    end
+  end
+end

data/sig/philosophal/loaders.rbs

@@ -0,0 +1,4 @@
+module Philosophal
+  module Loaders
+  end
+end

data/sig/philosophal/properties/instance_methods.rbs

@@ -0,0 +1,26 @@
+module Philosophal
+  module Properties
+    # Included in the instances of the classes that declare properties.
+    module InstanceMethods
+      def cprop?: (String | Symbol property_name, untyped klass) -> bool
+
+      def philosophal_inspect: (?boolish light) -> String
+
+      alias cprop_inspect philosophal_inspect
+
+      def philosophal_inspect_map: () -> Hash[Symbol, untyped]
+
+      alias cprop_inspect_map philosophal_inspect_map
+
+      def philosophal_values: () -> Array[Property]
+
+      def changed_properties: () -> Hash[Symbol, untyped]
+
+      def changes_applied: () -> self
+
+      def to_json_hash: () -> Hash[Symbol, untyped]
+
+      def to_json: (*untyped _args) -> String
+    end
+  end
+end

data/sig/philosophal/properties/schema.rbs

@@ -0,0 +1,47 @@
+module Philosophal
+  module Properties
+    class Schema
+      include Enumerable[Property]
+
+      @properties_index: Hash[Symbol, Property]
+      @mutex: Thread::Mutex
+      @immutables: Hash[Symbol, Property]
+      @mutables: Hash[Symbol, Property]
+      @json_names_h: Hash[Symbol, Symbol]
+      @json_setters: Hash[Symbol, Symbol]
+      @json_properties: Array[Property]
+      @tracked: Array[Property]
+
+      def initialize: (?properties_index: Hash[Symbol, Property]) -> void
+
+      def initialize_copy: (Schema source) -> void
+
+      attr_reader properties_index: Hash[Symbol, Property]
+
+      def []: (Symbol? key) -> Property?
+
+      def keys: () -> Array[Symbol]
+
+      def each: () { (Property) -> void } -> self
+              | () -> Enumerator[Property, self]
+
+      def <<: (Property value) -> self
+
+      def immutables: () -> Hash[Symbol, Property]
+
+      def mutables: () -> Hash[Symbol, Property]
+
+      def json_names_h: () -> Hash[Symbol, Symbol]
+
+      def json_setters: () -> Hash[Symbol, Symbol]
+
+      def json_properties: () -> Array[Property]
+
+      def tracked: () -> Array[Property]
+
+      private
+
+      def clear_caches: () -> void
+    end
+  end
+end

data/sig/philosophal/properties.rbs

@@ -0,0 +1,59 @@
+module Philosophal
+  # Extended by the classes that declare properties.
+  module Properties : Module
+    include Philosophal::Types
+
+    @philosophal_properties: Schema
+    @philosophal_descriptions: Hash[Symbol, String]
+    @json: Loaders::JsonLoader
+    @__philosophal_extension__: Module
+
+    def cprop: (
+                 Symbol name,
+                 type_spec `type`,
+                 ?default: untyped,
+                 ?transform: transform?,
+                 ?immutable: bool,
+                 ?description: String?,
+                 ?json: bool | String | Symbol,
+                 ?override: bool,
+                 ?track_changes: bool
+               ) -> untyped
+
+    def philosophal_properties: () -> Schema
+
+    def philosophal_descriptions: () -> Hash[Symbol, String]
+
+    alias cprop_descriptions philosophal_descriptions
+
+    def json: () -> Loaders::JsonLoader
+
+    private
+
+    def __philosophal_property_class__: () -> singleton(Property)
+
+    def __define_philosophal_methods__: (Property new_property) -> untyped
+
+    def __set_philosophal_property_constant__: (Property property) -> void
+
+    def __philosophal_extension__: () -> Module
+
+    def __generate_philosophal_methods__: (Property new_property) -> String
+
+    def __remove_philosophal_own_method__: (Symbol method_name) -> void
+
+    def __check_philosophal_options__: (
+                                         Symbol name,
+                                         transform: untyped,
+                                         immutable: untyped,
+                                         override: untyped,
+                                         description: untyped,
+                                         json: untyped,
+                                         track_changes: untyped
+                                       ) -> void
+
+    def __check_philosophal_transform_option__: (Symbol name, untyped transform) -> void
+
+    def __check_philosophal_boolean_option__: (Symbol option_name, untyped value) -> void
+  end
+end

data/sig/philosophal/property.rbs

@@ -0,0 +1,98 @@
+module Philosophal
+  class Property
+    @writer_method_name: Symbol
+    @constant_name: Symbol
+    @boolean_method_name: Symbol
+    @description_method_name: Symbol
+    @was_method_name: Symbol
+    @changed_method_name: Symbol
+    @variable_name: Symbol
+    @was_variable_name: Symbol
+    @convert_method: Symbol | [Symbol?, untyped] | nil
+
+    def initialize: (
+                      name: Symbol,
+                      type: type_spec,
+                      default: untyped,
+                      transform: transform?,
+                      immutable: bool,
+                      description: String?,
+                      json: bool | Symbol,
+                      override: bool,
+                      ?track_changes: bool
+                    ) -> void
+
+    attr_reader name: Symbol
+
+    attr_reader type: type_spec
+
+    attr_reader default: untyped
+
+    attr_reader transform: transform?
+
+    attr_reader immutable: bool
+
+    attr_reader description: String?
+
+    attr_reader json: bool | Symbol
+
+    attr_reader override: bool
+
+    attr_reader track_changes: bool
+
+    def json_name: () -> Symbol
+
+    def default?: () -> bool
+
+    def default_value: () -> untyped
+
+    def transform?: () -> bool
+
+    def override?: () -> bool
+
+    def track_changes?: () -> bool
+
+    def check_conversion: (untyped value) -> untyped
+
+    def convert_method: () -> (Symbol | [Symbol?, untyped] | nil)
+
+    # Maps each method name to define to the generator that writes its code.
+    def method_generators: () -> Hash[Symbol, Symbol]
+
+    def change_tracking_generators: () -> Hash[Symbol, Symbol]
+
+    def constant_name: () -> Symbol
+
+    def writer_method_name: () -> Symbol
+
+    def generate_writer_method: (String buffer) -> String
+
+    def generate_immutable_writer_method: (String buffer) -> String
+
+    def reader_method_name: () -> Symbol
+
+    def variable_name: () -> Symbol
+
+    def generate_plain_reader_method: (String buffer) -> String
+
+    def generate_reader_method: (String buffer) -> String
+
+    def boolean_method_name: () -> Symbol
+
+    def generate_boolean_method: (String buffer) -> String
+
+    def description_method_name: () -> Symbol
+
+    def generate_description_method: (String buffer) -> String
+
+    def was_method_name: () -> Symbol
+
+    def was_variable_name: () -> Symbol
+
+    def generate_was_method: (String buffer) -> String
+
+    def changed_method_name: () -> Symbol
+
+    def generate_changed_method: (String buffer) -> String
+  end
+end

data/sig/philosophal/transform.rbs

@@ -0,0 +1,7 @@
+module Philosophal
+  class Transform
+    def self.make: (transform method, untyped value) -> untyped
+
+    def self.self_method?: (Symbol method) -> bool
+  end
+end

data/sig/philosophal/types/any_type.rbs

@@ -0,0 +1,9 @@
+module Philosophal
+  module Types
+    class AnyType
+      Instance: AnyType
+
+      def ===: (untyped _value) -> true
+    end
+  end
+end

data/sig/philosophal/types/array_of_type.rbs

@@ -0,0 +1,23 @@
+module Philosophal
+  module Types
+    class ArrayOfType
+      self.@memorization: Hash[Module, ArrayOfType]
+
+      def self.instance: (Module subtype) -> ArrayOfType
+
+      def self.memorization: () -> Hash[Module, ArrayOfType]
+
+      private
+
+      def self.new: (Module subtype) -> ArrayOfType
+
+      public
+
+      attr_reader subtype: Module
+
+      def initialize: (Module subtype) -> void
+
+      def ===: (untyped array) -> bool
+    end
+  end
+end

data/sig/philosophal/types/boolean_type.rbs

@@ -0,0 +1,11 @@
+module Philosophal
+  module Types
+    class BooleanType
+      Instance: BooleanType
+
+      TRUE_FALSE_SET: Set[bool]
+
+      def ===: (untyped value) -> bool
+    end
+  end
+end

data/sig/philosophal/types/hash_of_type.rbs

@@ -0,0 +1,25 @@
+module Philosophal
+  module Types
+    class HashOfType
+      type subtype = { key_type: Module, value_type: Module }
+
+      self.@memorization: Hash[[Module, Module], HashOfType]
+
+      def self.instance: (Module key_type, Module value_type) -> HashOfType
+
+      def self.memorization: () -> Hash[[Module, Module], HashOfType]
+
+      private
+
+      def self.new: (subtype subtype) -> HashOfType
+
+      public
+
+      attr_reader subtype: subtype
+
+      def initialize: (subtype subtype) -> void
+
+      def ===: (untyped hash) -> bool
+    end
+  end
+end

data/sig/philosophal/types.rbs

@@ -0,0 +1,11 @@
+module Philosophal
+  module Types
+    def _Any: () -> AnyType
+
+    def _Boolean: () -> BooleanType
+
+    def _ArrayOf: (Module subtype) -> ArrayOfType
+
+    def _HashOf: (Module key_type, Module value_type) -> HashOfType
+  end
+end

data/sig/philosophal.rbs

@@ -0,0 +1,12 @@
+module Philosophal
+  # A type accepted by cprop: a class (String, Integer, ...) or one of the Philosophal::Types helpers.
+  type type_spec = Module | Types::AnyType | Types::BooleanType | Types::ArrayOfType | Types::HashOfType
+
+  type transform = Symbol | ^(untyped) -> untyped
+
+  def self.convert: (Property property, untyped value) -> untyped
+
+  private
+
+  def self.convert_to_type: (Property property, untyped value) -> untyped
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philosophal
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Maxime Désécot
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -52,6 +52,24 @@ files:
 - lib/philosophal/types/array_of_type.rb
 - lib/philosophal/types/boolean_type.rb
 - lib/philosophal/types/hash_of_type.rb
+- sig/manifest.yaml
+- sig/philosophal.rbs
+- sig/philosophal/convertor.rbs
+- sig/philosophal/errors/argument_error.rbs
+- sig/philosophal/errors/type_error.rbs
+- sig/philosophal/loaders.rbs
+- sig/philosophal/loaders/errors.rbs
+- sig/philosophal/loaders/json_loader.rbs
+- sig/philosophal/properties.rbs
+- sig/philosophal/properties/instance_methods.rbs
+- sig/philosophal/properties/schema.rbs
+- sig/philosophal/property.rbs
+- sig/philosophal/transform.rbs
+- sig/philosophal/types.rbs
+- sig/philosophal/types/any_type.rbs
+- sig/philosophal/types/array_of_type.rbs
+- sig/philosophal/types/boolean_type.rbs
+- sig/philosophal/types/hash_of_type.rbs
 homepage: https://github.com/RaoH37/philosophal
 licenses:
 - GPL-3.0-only