active_model_changeset 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cefb407d3ed0ef238cfe72db0118edd34df60fe0e13867352e5ad026902fea99
+  data.tar.gz: a27f98c0cd8689b3113a5832202ae33cd5b7ce24bea46ae7d4f4c3ec425eca48
+SHA512:
+  metadata.gz: c0d78b6ec0377ff24afd5d375eb3f8cb496a8e9846a444d7795d4a40ce36061c6b2b5badd56b2a8c5e6534e5af1756b5ea287afc6694d7ccfe931721c7303b55
+  data.tar.gz: 27dc75a6b380a90bc125666957e5c5e89009d5c42dfeb4be2ca987176acdb68ff66f619ad728c8361481ad0b5e933d5d6f375949f25d045507167f3e9b4340e7

data/.yardopts

@@ -0,0 +1,13 @@
+--readme README.md
+--title "ActiveModelChangeset Documentation"
+--charset utf-8
+--markup markdown
+--output-dir doc
+--protected
+--no-private
+--hide-void-return
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+Todas as mudanças notáveis deste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
+e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-16
+
+### Adicionado
+
+- **Classe `ActiveModelChangeset::Base`** - Classe base para criar changesets
+- **Type-casting** via `ActiveModel::Attributes`
+- **Validações** via `ActiveModel::Validations`
+- **Normalização declarativa** com opção `normalize:` no atributo
+  - `:strip` - Remove espaços no início e fim
+  - `:squish` - Remove espaços extras
+  - `:downcase` - Converte para minúsculas
+  - `:upcase` - Converte para maiúsculas
+  - `:blank_to_nil` - Converte strings vazias para nil
+- **Whitelist automática** - Apenas atributos declarados são aceitos
+- **Detecção de mudanças**
+  - `#changed?` - Verifica se há mudanças
+  - `#changes` - Retorna hash com mudanças `{ attr: [old, new] }`
+  - `#attributes_for_update` - Retorna hash com atributos alterados
+- **Aplicação de mudanças**
+  - `#apply` - Aplica mudanças se válido, retorna boolean
+  - `#apply!` - Aplica mudanças ou levanta exceção
+- **Suporte a ActionController::Parameters** via `to_unsafe_h`
+- **Compatível com POROs** (Plain Old Ruby Objects)
+- **Alias `Changeset`** para retrocompatibilidade
+- **Documentação YARD** completa
+- **Suite de testes** com 59 exemplos e 93%+ de cobertura
+- **GitHub Actions** para CI/CD
+- **SimpleCov** para relatórios de cobertura

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"active_model_changeset" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["alef.oliveira@siedos.com.br"](mailto:"alef.oliveira@siedos.com.br").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alef ojeda de Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+# ActiveModelChangeset
+
+[![Gem Version](https://badge.fury.io/rb/active_model_changeset.svg)](https://badge.fury.io/rb/active_model_changeset)
+[![Ruby](https://github.com/nemuba/active_model_changeset/workflows/Ruby/badge.svg)](https://github.com/nemuba/active_model_changeset/actions)
+[![Coverage](https://img.shields.io/badge/coverage-93%25-brightgreen)](https://github.com/nemuba/active_model_changeset)
+
+Uma gem utilitária para Ruby on Rails que fornece **changesets tipados, validados e com semântica de patch** para operações de criação e atualização de modelos.
+
+## O Problema
+
+Em aplicações Rails, é comum enfrentar desafios ao lidar com parâmetros de entrada:
+
+- Receber parâmetros brutos de controllers ou APIs
+- Aplicar type-casting e normalização de forma consistente
+- Validar dados antes de persistir
+- Calcular apenas os atributos que realmente mudaram
+- Aplicar mudanças ao modelo de forma segura e previsível
+
+O `ActiveModelChangeset` resolve todos esses problemas com uma abstração única e testável.
+
+## Principais Características
+
+| Característica | Descrição |
+|----------------|-----------|
+| 🔄 **Type-casting consistente** | Utiliza `ActiveModel::Attributes` para conversão de tipos |
+| 🛡️ **Whitelist automática** | Apenas atributos declarados são aceitos |
+| ✨ **Normalização declarativa** | Suporte a `strip`, `squish`, `downcase`, etc. |
+| 📊 **Cálculo de diff** | Compara estado atual com novo estado |
+| 🎯 **Patch semantics** | Gera hash somente com atributos alterados |
+| ✅ **Validações integradas** | Compatível com `ActiveModel::Validations` |
+| 📦 **Independente de ActiveRecord** | Funciona com POROs (Plain Old Ruby Objects) |
+
+## Instalação
+
+Adicione ao seu Gemfile:
+
+```ruby
+gem 'active_model_changeset'
+```
+
+E execute:
+
+```bash
+bundle install
+```
+
+Ou instale diretamente:
+
+```bash
+gem install active_model_changeset
+```
+
+## Como Usar
+
+### Exemplo Básico
+
+```ruby
+class UserChangeset < ActiveModelChangeset::Base
+  attribute :name, :string, normalize: :squish
+  attribute :email, :string, normalize: [:strip, :downcase]
+  attribute :age, :integer
+
+  # Validações
+  validates :name, presence: true
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  validates :age, numericality: { greater_than: 0 }, allow_nil: true
+end
+```
+
+### Criação de Registros
+
+```ruby
+changeset = UserChangeset.new(User.new, {
+  name: "  João Silva  ",
+  email: "JOAO@EXAMPLE.COM",
+  age: "30"
+})
+
+if changeset.valid?
+  user = User.create!(changeset.attributes_for_update)
+  # => { name: "João Silva", email: "joao@example.com", age: 30 }
+end
+```
+
+### Atualização de Registros (Patch Semantics)
+
+```ruby
+user = User.find(1)
+# => #<User name: "João Silva", email: "joao@example.com", age: 30>
+
+changeset = UserChangeset.new(user, { name: "João Santos", age: "30" })
+
+changeset.changed?
+# => true
+
+changeset.changes
+# => { name: ["João Silva", "João Santos"] }  # age não mudou, então não está incluído
+
+if changeset.valid?
+  user.update!(changeset.attributes_for_update)
+end
+```
+
+### Verificando Mudanças
+
+```ruby
+changeset = UserChangeset.new(user, { name: "Novo Nome" })
+
+changeset.changed?  # => true
+
+changeset.changes          # => { name: ["Nome Antigo", "Novo Nome"] }
+changeset.attributes_for_update  # => { name: "Novo Nome" }
+```
+
+### Normalizadores Disponíveis
+
+| Normalizador | Descrição |
+|--------------|----------|
+| `:strip` | Remove espaços no início e fim da string |
+| `:squish` | Remove espaços extras internos e externos |
+| `:downcase` | Converte para minúsculas |
+| `:upcase` | Converte para maiúsculas |
+| `:blank_to_nil` | Converte strings vazias ou com apenas espaços para `nil` |
+
+```ruby
+class ProductChangeset < ActiveModelChangeset::Base
+  attribute :name, :string, normalize: [:strip, :squish]
+  attribute :sku, :string, normalize: :upcase
+  attribute :description, :string, normalize: :blank_to_nil
+end
+```
+
+### Métodos `#apply` e `#apply!`
+
+Para simplificar o fluxo de atualização:
+
+```ruby
+changeset = UserChangeset.new(user, params)
+
+# Retorna true/false
+if changeset.apply
+  redirect_to user_path(user)
+else
+  render :edit
+end
+
+# Ou levanta exceção
+begin
+  changeset.apply!
+rescue ActiveModel::ValidationError => e
+  # Tratar erro de validação do changeset
+rescue ActiveRecord::RecordInvalid => e
+  # Tratar erro de validação do modelo
+end
+```
+
+## API Reference
+
+### Métodos de Classe
+
+| Método | Descrição |
+|--------|----------|
+| `.model(klass)` | Define a classe do modelo associada |
+| `.attribute(name, type, normalize:)` | Declara um atributo com tipo e normalização opcional |
+| `.normalizers` | Retorna hash de normalizadores configurados |
+| `.declared_attribute_names` | Retorna array de nomes de atributos declarados |
+
+### Métodos de Instância
+
+| Método | Descrição |
+|--------|----------|
+| `#record` | Retorna o registro/modelo sendo modificado |
+| `#raw_input` | Retorna os parâmetros de entrada originais (frozen) |
+| `#changed?` | Retorna `true` se houver atributos alterados |
+| `#changes` | Retorna hash `{ attr: [old, new] }` com mudanças |
+| `#attributes_for_update(include_nil:)` | Retorna hash com atributos alterados |
+| `#apply` | Aplica mudanças se válido, retorna `true/false` |
+| `#apply!` | Aplica mudanças ou levanta exceção |
+
+## Casos de Uso
+
+### Em Controllers
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    changeset = UserChangeset.new(User.new, user_params)
+
+    if changeset.valid?
+      @user = User.create!(changeset.attributes_for_update)
+      render json: @user, status: :created
+    else
+      render json: { errors: changeset.errors }, status: :unprocessable_entity
+    end
+  end
+
+  def update
+    @user = User.find(params[:id])
+    changeset = UserChangeset.new(@user, user_params)
+
+    if changeset.valid? && changeset.changed?
+      @user.update!(changeset.attributes_for_update)
+    end
+
+    render json: @user
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email, :age)
+  end
+end
+```
+
+### Em Service Objects
+
+```ruby
+class UpdateUserService
+  def initialize(user, params)
+    @user = user
+    @changeset = UserChangeset.new(user, params)
+  end
+
+  def call
+    return failure(@changeset.errors) unless @changeset.valid?
+    return success(@user) unless @changeset.changed?
+
+    @user.update!(@changeset.attributes_for_update)
+    success(@user)
+  rescue ActiveRecord::RecordInvalid => e
+    failure(e.record.errors)
+  end
+
+  private
+
+  def success(user) = { success: true, user: user }
+  def failure(errors) = { success: false, errors: errors }
+end
+```
+
+## Desenvolvimento
+
+Após clonar o repositório, execute:
+
+```bash
+bin/setup
+```
+
+Para rodar os testes:
+
+```bash
+bundle exec rspec
+```
+
+Para rodar os testes com cobertura:
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```
+
+Para rodar o RuboCop:
+
+```bash
+bundle exec rubocop
+```
+
+Para gerar a documentação:
+
+```bash
+bundle exec yard doc
+bundle exec yard server --reload
+```
+
+Para abrir um console interativo:
+
+```bash
+bin/console
+```
+
+### Publicação
+
+1. Atualize o número da versão em `lib/active_model_changeset/version.rb`
+2. Execute `bundle exec rake release` para:
+   - Criar uma tag git para a versão
+   - Fazer push dos commits e da tag
+   - Publicar o arquivo `.gem` no [rubygems.org](https://rubygems.org)
+
+## Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Faça um fork do projeto
+2. Crie sua feature branch (`git checkout -b feature/minha-feature`)
+3. Commit suas mudanças (`git commit -am 'Adiciona nova feature'`)
+4. Faça push para a branch (`git push origin feature/minha-feature`)
+5. Abra um Pull Request
+
+Este projeto segue o [Código de Conduta](CODE_OF_CONDUCT.md). Ao participar, espera-se que você siga estas diretrizes.
+
+## Licença
+
+Esta gem está disponível como código aberto sob os termos da [Licença MIT](LICENSE.txt).
+
+## Código de Conduta
+
+Todos os participantes do projeto ActiveModelChangeset devem seguir o [Código de Conduta](CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# YARD Documentation
+begin
+  require "yard"
+
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = ["--output-dir", "doc", "--readme", "README.md"]
+  end
+rescue LoadError
+  desc "YARD não disponível"
+  task :yard do
+    puts "YARD não está instalado. Execute: bundle install"
+  end
+end
+
+task default: %i[spec rubocop]

data/lib/active_model_changeset/base.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module ActiveModelChangeset
+  # Base é a classe principal que encapsula a lógica de validação, normalização
+  # e cálculo de diferenças para operações de criação e atualização de modelos.
+  #
+  # Ela combina type-casting via ActiveModel::Attributes, normalização declarativa,
+  # validações e semântica de patch em uma única classe reutilizável.
+  #
+  # @example Definindo um changeset
+  #   class UserChangeset < ActiveModelChangeset::Base
+  #     model User
+  #
+  #     attribute :name, :string, normalize: [:strip, :squish]
+  #     attribute :email, :string, normalize: [:strip, :downcase]
+  #     attribute :age, :integer
+  #
+  #     validates :name, presence: true
+  #     validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  #   end
+  #
+  # @example Usando para atualização
+  #   user = User.find(1)
+  #   changeset = UserChangeset.new(user, params)
+  #
+  #   if changeset.valid? && changeset.changes.any?
+  #     user.update!(changeset.attributes_for_update)
+  #   end
+  #
+  # @see https://api.rubyonrails.org/classes/ActiveModel/Attributes.html
+  # @see https://api.rubyonrails.org/classes/ActiveModel/Validations.html
+  # :rubocop:disable Metrics/ClassLength
+  class Base
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Validations
+
+    # Funções de normalização disponíveis para uso com a opção `normalize:`
+    #
+    # @example
+    #   attribute :name, :string, normalize: [:strip, :squish]
+    #
+    NORMALIZER_FUNCS = {
+      strip: ->(v) { v.is_a?(String) ? v.strip : v },
+      squish: ->(v) { v.is_a?(String) ? v.squish : v },
+      downcase: ->(v) { v.is_a?(String) ? v.downcase : v },
+      upcase: ->(v) { v.is_a?(String) ? v.upcase : v },
+      blank_to_nil: ->(v) { v.respond_to?(:blank?) && v.blank? ? nil : v }
+    }.freeze
+
+    class << self
+      # Define ou retorna a classe do modelo associada ao changeset.
+      #
+      # @param klass [Class, nil] a classe do modelo (ex: User, Post)
+      # @return [Class, nil] a classe do modelo configurada
+      #
+      # @example
+      #   class UserChangeset < ActiveModelChangeset::Base
+      #     model User
+      #   end
+      #
+      def model(klass = nil)
+        if klass
+          @model_class = klass
+        else
+          @model_class
+        end
+      end
+
+      # Declara um atributo no changeset com suporte a normalização.
+      #
+      # Estende o método `attribute` do ActiveModel::Attributes para
+      # suportar a opção `normalize:` que aplica transformações ao valor.
+      #
+      # @param name [Symbol] nome do atributo
+      # @param type [Symbol] tipo do atributo (:string, :integer, :boolean, etc.)
+      # @param options [Hash] opções adicionais
+      # @option options [Symbol, Array<Symbol>] :normalize normalizadores a aplicar
+      #
+      # @example
+      #   attribute :email, :string, normalize: [:strip, :downcase]
+      #   attribute :name, :string, normalize: :squish
+      #
+      # @return [void]
+      #
+      def attribute(name, type = :string, **options)
+        normalize = options.delete(:normalize)
+        super
+        normalizers[name.to_sym] = Array(normalize).compact.map(&:to_sym) if normalize
+      end
+
+      # Retorna o hash de normalizadores configurados por atributo.
+      #
+      # @return [Hash{Symbol => Array<Symbol>}] mapa de atributo para lista de normalizadores
+      #
+      def normalizers
+        @normalizers ||= {}
+      end
+
+      # Retorna os nomes dos atributos declarados no changeset.
+      #
+      # @return [Array<Symbol>] lista de nomes de atributos
+      #
+      def declared_attribute_names
+        attribute_types.keys.map(&:to_sym)
+      end
+    end
+
+    # @return [Object] o registro/modelo sendo modificado
+    attr_reader :record
+
+    # @return [Hash] os parâmetros de entrada originais (antes de processamento)
+    attr_reader :raw_input
+
+    # Inicializa um novo changeset.
+    #
+    # @param record [Object] o registro existente para comparação (pode ser nil para criação)
+    # @param input [Hash, ActionController::Parameters] os parâmetros de entrada
+    #
+    # @example Atualização
+    #   user = User.find(1)
+    #   changeset = UserChangeset.new(user, { name: "Novo Nome" })
+    #
+    # @example Criação (record vazio)
+    #   changeset = UserChangeset.new(User.new, params)
+    #
+    def initialize(record, input = {})
+      @record = record
+      @raw_input = input.dup.freeze
+      super(extract_declared_attributes(input))
+      normalize_attributes!
+    end
+
+    # Retorna os atributos que foram alterados, prontos para update.
+    #
+    # Apenas atributos que diferem do registro original são incluídos.
+    # Por padrão, valores nil são excluídos do resultado.
+    #
+    # @param include_nil [Boolean] se true, inclui atributos com valor nil
+    # @return [Hash{Symbol => Object}] hash com atributos alterados
+    #
+    # @example
+    #   changeset.attributes_for_update
+    #   # => { name: "João Santos" }
+    #
+    #   changeset.attributes_for_update(include_nil: true)
+    #   # => { name: "João Santos", bio: nil }
+    #
+    def attributes_for_update(include_nil: false)
+      self.class.declared_attribute_names.each_with_object({}) do |name, hash|
+        next unless changed_attribute?(name)
+
+        value = public_send(name)
+        next if !include_nil && value.nil?
+
+        hash[name] = value
+      end
+    end
+
+    # Retorna um hash com as mudanças no formato { atributo: [valor_antigo, valor_novo] }.
+    #
+    # Similar ao `ActiveModel::Dirty#changes`, mas calcula a diferença
+    # entre o changeset e o registro original.
+    #
+    # @return [Hash{Symbol => Array}] hash de mudanças
+    #
+    # @example
+    #   changeset.changes
+    #   # => { name: ["João Silva", "João Santos"] }
+    #
+    def changes
+      self.class.declared_attribute_names.each_with_object({}) do |name, hash|
+        next unless changed_attribute?(name)
+
+        hash[name] = [record_value(name), public_send(name)]
+      end
+    end
+
+    # Verifica se há alguma mudança no changeset.
+    #
+    # @return [Boolean] true se houver pelo menos um atributo alterado
+    #
+    def changed?
+      self.class.declared_attribute_names.any? { |name| changed_attribute?(name) }
+    end
+
+    # Aplica as mudanças ao registro se o changeset for válido.
+    #
+    # @return [Boolean] true se a atualização foi bem-sucedida, false caso contrário
+    #
+    # @example
+    #   if changeset.apply
+    #     redirect_to user_path
+    #   else
+    #     render :edit
+    #   end
+    #
+    def apply
+      return false unless valid?
+
+      record.update(attributes_for_update)
+    end
+
+    # Aplica as mudanças ao registro, levantando exceção se inválido.
+    #
+    # @raise [ActiveModel::ValidationError] se o changeset for inválido
+    # @raise [ActiveRecord::RecordInvalid] se o update! falhar
+    # @return [Boolean] true se a atualização foi bem-sucedida
+    #
+    # @example
+    #   begin
+    #     changeset.apply!
+    #   rescue ActiveModel::ValidationError => e
+    #     # tratar erro de validação do changeset
+    #   rescue ActiveRecord::RecordInvalid => e
+    #     # tratar erro de validação do modelo
+    #   end
+    #
+    def apply!
+      raise ActiveModel::ValidationError, self unless valid?
+
+      record.update!(attributes_for_update)
+    end
+
+    private
+
+    # Aplica os normalizadores configurados a cada atributo.
+    #
+    # @return [void]
+    #
+    def normalize_attributes!
+      self.class.normalizers.each do |attr, normalizer_keys|
+        value = public_send(attr)
+        normalized_value = apply_normalizers(value, normalizer_keys)
+        public_send("#{attr}=", normalized_value)
+      end
+    end
+
+    # Aplica uma lista de normalizadores a um valor.
+    #
+    # @param value [Object] o valor a ser normalizado
+    # @param normalizer_keys [Array<Symbol>] lista de chaves de normalizadores
+    # @return [Object] o valor normalizado
+    #
+    def apply_normalizers(value, normalizer_keys)
+      normalizer_keys.reduce(value) do |val, key|
+        fn = NORMALIZER_FUNCS[key]
+        fn ? fn.call(val) : val
+      end
+    end
+
+    # Extrai apenas os atributos declarados do input.
+    #
+    # Funciona como whitelist automática, aceitando apenas atributos
+    # explicitamente declarados no changeset.
+    #
+    # @param input [Hash, ActionController::Parameters] parâmetros de entrada
+    # @return [Hash{Symbol => Object}] hash filtrado com apenas atributos declarados
+    #
+    def extract_declared_attributes(input)
+      hash = convert_to_hash(input)
+      declared = self.class.declared_attribute_names
+
+      hash.each_with_object({}) do |(key, value), acc|
+        key_sym = safe_to_sym(key)
+        acc[key_sym] = value if key_sym && declared.include?(key_sym)
+      end
+    end
+
+    # Converte o input para hash de forma segura.
+    #
+    # Suporta ActionController::Parameters (to_unsafe_h) e objetos
+    # que respondem a to_h.
+    #
+    # @param input [Object] o objeto a ser convertido
+    # @return [Hash] o hash resultante
+    #
+    def convert_to_hash(input)
+      if input.respond_to?(:to_unsafe_h)
+        input.to_unsafe_h
+      elsif input.respond_to?(:to_h)
+        input.to_h
+      else
+        {}
+      end
+    end
+
+    # Converte uma chave para Symbol de forma segura.
+    #
+    # @param key [Object] a chave a ser convertida
+    # @return [Symbol, nil] o symbol ou nil se a conversão falhar
+    #
+    def safe_to_sym(key)
+      key.to_sym
+    rescue StandardError
+      nil
+    end
+
+    # Verifica se um atributo específico foi alterado.
+    #
+    # @param name [Symbol] nome do atributo
+    # @return [Boolean] true se o valor no changeset difere do registro
+    #
+    def changed_attribute?(name)
+      record_value(name) != public_send(name)
+    end
+
+    # Obtém o valor atual de um atributo no registro.
+    #
+    # @param name [Symbol] nome do atributo
+    # @return [Object, nil] o valor do atributo ou nil se não existir
+    #
+    def record_value(name)
+      return unless record.respond_to?(name)
+
+      record.public_send(name)
+    end
+  end
+end

data/lib/active_model_changeset/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module ActiveModelChangeset
+  class Railtie < Rails::Railtie
+    initializer "active_model_changeset.require" do
+      # Nada a fazer; manter vazio evita efeitos colaterais
+    end
+  end
+end

data/lib/active_model_changeset/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveModelChangeset
+  VERSION = "0.1.0"
+end

data/lib/active_model_changeset.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_model"
+require_relative "active_model_changeset/version"
+require_relative "active_model_changeset/base"
+
+# Railtie opcional: só carregue se estiver em Rails
+begin
+  require_relative "active_model_changeset/railtie"
+rescue LoadError
+  # sem Rails, ok
+end
+
+module ActiveModelChangeset
+  # Alias para retrocompatibilidade
+  # @deprecated Use {ActiveModelChangeset::Base} ao invés
+  Changeset = Base
+end

data/sig/active_model_changeset.rbs

@@ -0,0 +1,4 @@
+module ActiveModelChangeset
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: active_model_changeset
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alef ojeda de Oliveira
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-01-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: |
+  ActiveModelChangeset provides a lightweight changeset abstraction for Ruby on Rails
+  applications. It combines type casting, attribute normalization, validation and
+  diff calculation into a single object, enabling safe and explicit create/update
+  operations with patch semantics.
+
+  The gem is designed for service objects and APIs, allowing developers to whitelist
+  attributes, apply transformations, validate input and update models using only
+  changed values, without relying on ActiveRecord callbacks or controllers.
+email:
+- nemubatubag@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/active_model_changeset.rb
+- lib/active_model_changeset/base.rb
+- lib/active_model_changeset/railtie.rb
+- lib/active_model_changeset/version.rb
+- sig/active_model_changeset.rbs
+homepage: https://github.com/nemuba/active_model_changeset
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nemuba/active_model_changeset
+  source_code_uri: https://github.com/nemuba/active_model_changeset.git
+  changelog_uri: https://github.com/nemuba/active_model_changeset/CHANGELOG.md
+  documentation_uri: https://github.com/nemuba/active_model_changeset/doc/index.html
+  yard.run: yri, yard
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Typed, validated changesets for ActiveModel with patch semantics
+test_files: []