activemodel_object_info 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80913d0545f39b6b56ea20826e6c5da37c3fbec7645f988c5439f85f6ac2eedc
-  data.tar.gz: 8f839ed3448156219e6c4da35c9eb69d9eb7d4dca97ef48f1c89b937ea2a782e
+  metadata.gz: f0aebeaaaa8f81c3ee9b2107286f9cfa30ebbd6981ae8da0284bd71537f51a75
+  data.tar.gz: 042ee4576749af306512a90eee1cb3c50c3cacbb786204c9ae6af3a7f5cbd6e6
 SHA512:
-  metadata.gz: a8c1005c3e1887dd377deb8ab79d1d9bad079dea09ac81e24ff484e59efdb44c3e3c6c7ba4741237954d944f0b5780ff00f9e7530ebe465c603eedc9f0aeb5a1
-  data.tar.gz: 5bd16bc43f2c13b58bfa037ee6505777d80a97d455b7744d75f32cd928348a1d2d0e0cc638acc0070662b42792f83972c365ccd00c81860980f05196afc6bd32
+  metadata.gz: 401ebe7b53349260c17f509a4d61391f67880da739ed55ef386af77732d85341a5b27d59e905aed27b70990745a5608b45ed62e231965fe87e16caeae16fcc2b
+  data.tar.gz: bc40adcb1e297058f46b5c172cf28b68ebdab7693dfd57bead07bd9593509cf6c7372c99b9fcb3af12ace198880e92da737116d117e1345645e6dfb7e0cb1884

data/.rubocop.yml

@@ -39,6 +39,7 @@ Metrics/ModuleLength:
   Max: 600
 Metrics/PerceivedComplexity:
   Max: 50
+
 Metrics/CyclomaticComplexity:
   Max: 50
 

data/CHANGELOG

@@ -1,6 +1,12 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.4.1] - 2026-07-28
+### Added
+- **Base**: Added support for nested output of associated objects via `includes` option.
+- **Base**: Added support for contextual formats via `context` parameter and `INSTANCE_INFO_#{CONTEXT}` constants.
+- **DeletedOperation**: Added `restore` and `restore!` methods to undelete soft-deleted records.
+
 ## [0.4.0] - 2026-07-28
 ### Fixed
 - Fixed Ruby 3.x keyword arguments compatibility issue for `instance_info` method, while keeping 100% backward compatibility for existing usages.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    activemodel_object_info (0.4.0)
+    activemodel_object_info (0.4.1)
       activesupport
 
 GEM

data/README.md

@@ -33,7 +33,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'activemodel-object-info', '~> 0.4.0'
+gem 'activemodel-object-info', '~> 0.4.1'
 ```
 
 And then execute:
@@ -65,6 +65,11 @@ class User < ApplicationRecord
       { name: :virtual_field, type: :abstract, filter: ->(*) { "#{id}-#{name}" } } # Virtual field
     ]
   }.freeze
+
+  # Define contextual output configuration (Must be named INSTANCE_INFO_{CONTEXT})
+  INSTANCE_INFO_DETAIL = {
+    only: [:id, :name, :email, :phone]
+  }.freeze
 end
 ```
 
@@ -73,13 +78,31 @@ end
 ```ruby
 user = User.first
 
-# Use the default INSTANCE_INFO constant
+# 1. Use the default INSTANCE_INFO constant
 user.instance_info 
 # => { id: 1, user_name: "John", status: "Active", created_at: "2026-07-28", virtual_field: "1-John" }
 
-# Override at runtime (Supports Ruby 2.x Hash and Ruby 3.x Keyword Arguments)
+# 2. Contextual output: Pass `context` to automatically use the corresponding INSTANCE_INFO_{CONTEXT} constant
+user.instance_info(context: :detail)
+# => { id: 1, name: "John", email: "a@b.com", phone: "12345" }
+
+# 3. Override at runtime (Supports Ruby 2.x Hash and Ruby 3.x Keyword Arguments)
 user.instance_info(only: [:id, :name])
 # => { id: 1, name: "John" }
+
+# 4. Nested output for Associations (includes)
+user.instance_info(
+  only: [:id, :name],
+  includes: {
+    profile: { only: [:avatar_url, :bio] },     # Single instance (has_one / belongs_to)
+    roles: { only: [:role_name] }               # Collection (has_many)
+  }
+)
+# => { 
+#      id: 1, name: "John", 
+#      profile: { avatar_url: "...", bio: "..." }, 
+#      roles: [{ role_name: "admin" }, { role_name: "editor" }] 
+#    }
 ```
 
 ### 2. Migration Macros (TableDefinition)
@@ -152,6 +175,13 @@ user.soft_delete(user_id: current_user.id, refresh_updated: true)
 
 # 4. Strict Soft Delete (raises exception on failure):
 user.soft_delete!(user_id: current_user.id)
+
+# 5. Restore soft-deleted record (Undelete):
+# This resets the `deleted` flag to 0 and clears `deleted_by` and `deleted_at`
+user.restore
+
+# 6. Restore and refresh updated_at with user_id:
+user.restore(user_id: current_user.id, refresh_updated: true)
 ```
 
 ## Development & Testing

data/README.zh-CN.md

@@ -33,7 +33,7 @@
 将以下代码添加到你项目中的 Gemfile 里：
 
 ```ruby
-gem 'activemodel-object-info', '~> 0.4.0'
+gem 'activemodel-object-info', '~> 0.4.1'
 ```
 
 然后执行依赖安装：
@@ -54,7 +54,7 @@ $ bundle install
 class User < ApplicationRecord
   include ActivemodelObjectInfo::Base
 
-  # 定义默认的输出配置选项
+  # 默认的输出配置选项
   INSTANCE_INFO = {
     only: [:id, :name, :status, :created_at],
     attributes: [
@@ -65,6 +65,11 @@ class User < ApplicationRecord
       { name: :virtual_field, type: :abstract, filter: ->(*) { "#{id}-#{name}" } } # 根据其他字段合成的虚拟字段
     ]
   }.freeze
+  
+  # 自定义场景输出配置（名称格式必须为 INSTANCE_INFO_场景名）
+  INSTANCE_INFO_DETAIL = {
+    only: [:id, :name, :email, :phone]
+  }.freeze
 end
 ```
 
@@ -73,13 +78,31 @@ end
 ```ruby
 user = User.first
 
-# 不传参时，默认使用模型中的 INSTANCE_INFO 常量配置
+# 1. 不传参时，默认使用模型中的 INSTANCE_INFO 常量配置
 user.instance_info 
 # => { id: 1, user_name: "John", status: "活跃", created_at: "2026-07-28", virtual_field: "1-John" }
 
-# 运行时覆盖配置（完美兼容 Ruby 2.x 的 Hash 传参和 Ruby 3.x 的关键字参数）
+# 2. 场景化输出：通过 context 参数指定场景，自动读取对应的 INSTANCE_INFO_DETAIL 常量
+user.instance_info(context: :detail)
+# => { id: 1, name: "John", email: "a@b.com", phone: "12345" }
+
+# 3. 运行时覆盖配置（完美兼容 Ruby 2.x 的 Hash 传参和 Ruby 3.x 的关键字参数）
 user.instance_info(only: [:id, :name])
 # => { id: 1, name: "John" }
+
+# 4. 嵌套输出关联对象 (Associations)
+user.instance_info(
+  only: [:id, :name],
+  includes: {
+    profile: { only: [:avatar_url, :bio] },     # has_one / belongs_to 单实例
+    roles: { only: [:role_name] }               # has_many 集合实例
+  }
+)
+# => { 
+#      id: 1, name: "John", 
+#      profile: { avatar_url: "...", bio: "..." }, 
+#      roles: [{ role_name: "admin" }, { role_name: "editor" }] 
+#    }
 ```
 
 ### 2. 数据库迁移宏 (TableDefinition)
@@ -150,6 +173,13 @@ user.soft_delete(user_id: current_user.id, refresh_updated: true)
 
 # 4. 强校验软删除 (底层调用 save!，失败时抛出异常):
 user.soft_delete!(user_id: current_user.id)
+
+# 5. 恢复已软删除的数据 (撤销软删除)：
+# 此操作会将 deleted 标记重置为 0，并清空 deleted_by 和 deleted_at
+user.restore
+
+# 6. 恢复并同时记录更新人与更新时间：
+user.restore(user_id: current_user.id, refresh_updated: true)
 ```
 
 ## 开发与测试

data/activemodel_object_info.gemspec

@@ -41,6 +41,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'yard'
   spec.metadata = {
-    'rubygems_mfa_required' => 'false',
+    'rubygems_mfa_required' => 'true',
   }
 end

data/lib/activemodel_object_info/base.rb

@@ -32,6 +32,7 @@ module ActivemodelObjectInfo
   # @author shiner527 <shiner527@hotmail.com>
   #
   # [Changelog]
+  #   [2026-07-28] 支持关联对象嵌套输出 (includes) 与场景化输出配置 (context) (shiner527)
   #   [2026-07-28] 补充完整 YARD 文档及核心注释，重构 instance_info 签名以兼容 Ruby 3.x 关键字参数 (shiner527)
   #   [2021-04-19] 创建基础模块，提供 instance_info 数据格式化输出功能 (shiner527)
   #
@@ -56,11 +57,13 @@ module ActivemodelObjectInfo
     #
     # @param [Hash] options_hash 设置选项（传统位置参数 Hash），如果传入将被与 keyword_options 合并
     # @param [Hash] keyword_options 设置选项（Ruby 3 关键字参数）
+    # @option keyword_options [Symbol, String] :context 场景上下文名称。如果提供，将优先读取 "INSTANCE_INFO_#{context.upcase}" 常量。
     # @option keyword_options [Array<Symbol, Hash>] :attributes 具体每一项输出的设置数组。每个元素既可以是标识符实例也可以是一个散列实例。
     #  如果是标识符实例，则表示输出该属性。如果是一个散列实例，则按照散列中的设定值去生成对应的内容。
     # @option keyword_options [Array<Symbol>] :only 给出具体可以用来输出的字段属性名数组。
     # @option keyword_options [Array<Symbol>] :except 给出需要被排除输出的字段属性名数组。
     # @option keyword_options [String, Symbol] :datetime_format 全局的时间格式设置。
+    # @option keyword_options [Hash] :includes 需要嵌套输出的关联对象配置（如 { profile: { only: [:avatar] } }）。
     #
     # @return [Hash] 返回的处理过的该对象的信息散列。
     #
@@ -68,8 +71,18 @@ module ActivemodelObjectInfo
       # 合并传统参数与关键字参数，完美兼容 Ruby 2.x 的 Hash 传参和 Ruby 3.x 的 **kwargs 传参
       options = (options_hash || {}).merge(keyword_options)
 
-      # 尝试获取当前类上配置的 INSTANCE_INFO 常量作为默认选项
-      options = "#{self.class}::INSTANCE_INFO".safe_constantize || {} if options.blank?
+      # 尝试获取当前类上配置的常量作为默认选项
+      # 优先级：传入的参数 options > 场景常量 INSTANCE_INFO_#{CONTEXT} > 默认常量 INSTANCE_INFO
+      if options.blank? || (options.keys.map(&:to_sym) == [:context] && options[:context].present?)
+        context_name = options[:context].to_s.upcase
+
+        # 尝试寻找带场景的常量
+        context_constant_name = "#{self.class}::INSTANCE_INFO_#{context_name}"
+        options = context_constant_name.safe_constantize if context_name.present?
+
+        # 如果带场景的常量不存在，或者没传场景，降级寻找默认常量
+        options ||= "#{self.class}::INSTANCE_INFO".safe_constantize || {}
+      end
 
       # 将 options 的 key 转为 symbol，避免传入字符串 key 导致匹配不到
       options = options.deep_symbolize_keys
@@ -159,8 +172,40 @@ module ActivemodelObjectInfo
         end
       end
 
-      # 统一将结果第一层的键名转化为 Symbol 格式并返回
+      # 统一将结果第一层的键名转化为 Symbol 格式
       result.symbolize_keys!
+
+      # 5. 处理嵌套关联对象 (includes)
+      format_associations!(result, options)
+
+      result
+    end
+
+    private
+
+    # 处理并格式化嵌套关联对象
+    # @param [Hash] result 当前实例的输出结果散列
+    # @param [Hash] options 包含 :includes 配置的选项散列
+    def format_associations!(result, options)
+      return unless options[:includes].present? && options[:includes].is_a?(::Hash)
+
+      options[:includes].each do |association_name, assoc_options|
+        assoc_options = {} unless assoc_options.is_a?(::Hash)
+
+        # 安全获取关联对象
+        next unless respond_to?(association_name)
+
+        assoc_obj = __send__(association_name)
+
+        # 遍历处理关联对象
+        if assoc_obj.respond_to?(:map)
+          result[association_name.to_sym] = assoc_obj.map do |item|
+            item.respond_to?(:instance_info) ? item.instance_info(**assoc_options) : item
+          end
+        elsif assoc_obj.present?
+          result[association_name.to_sym] = assoc_obj.respond_to?(:instance_info) ? assoc_obj.instance_info(**assoc_options) : assoc_obj
+        end
+      end
     end
   end
 end

data/lib/activemodel_object_info/deleted_operation.rb

@@ -30,11 +30,14 @@ module ActivemodelObjectInfo
   # 核心重要方法：
   # - {#soft_delete}：执行软删除并调用 save 更新数据。
   # - {#soft_delete!}：执行软删除并调用 save! 更新数据（抛出异常）。
+  # - {#restore}：恢复已软删除的数据。
+  # - {#restore!}：强制恢复已软删除的数据（抛出异常）。
   # - {#delete_block}：底层通用的删除字段赋值逻辑块。
   #
   # @author shiner527 <shiner527@hotmail.com>
   #
   # [Changelog]
+  #   [2026-07-28] 新增 restore 与 restore! 方法以支持软删除数据恢复 (shiner527)
   #   [2026-07-28] 补充完整 YARD 文档、行内注释，清理尾随空格 (shiner527)
   #   [2021-04-19] 创建基础模块，提供软删除与作用域注入功能 (shiner527)
   #
@@ -97,6 +100,43 @@ module ActivemodelObjectInfo
 
         save!(touch: opts[:refresh_updated])
       end
+
+      # 6. 底层的恢复逻辑块 (给实例对象的内存属性赋值，清除删除标记)
+      define_method(:restore_block) do |**options|
+        options[:refresh_updated] = options[:refresh_updated].nil? ? false : options[:refresh_updated]
+
+        updated_by_field = (options[:updated_by_field] || 'updated_by').to_sym
+        deleted_by_field = (options[:deleted_by_field] || 'deleted_by').to_sym
+        deleted_at_field = (options[:deleted_at_field] || 'deleted_at').to_sym
+
+        # 核心：恢复状态为有效标记值
+        __send__("#{deleted_field}=", deleted_value_valid)
+
+        # 审计：清除删除人、删除时间，根据配置选择性地设置恢复操作的更新人
+        __send__("#{deleted_by_field}=", nil) if respond_to?(deleted_by_field)
+        __send__("#{deleted_at_field}=", nil) if respond_to?(deleted_at_field)
+        __send__("#{updated_by_field}=", options[:user_id]) if respond_to?(updated_by_field) && options[:user_id].present? && options[:refresh_updated]
+      end
+
+      # 7. 暴露的常规软删除恢复方法
+      define_method(:restore) do |**options|
+        opts = options.deep_symbolize_keys
+        return unless respond_to?(deleted_field)
+
+        restore_block(**opts)
+
+        save(touch: opts[:refresh_updated])
+      end
+
+      # 8. 暴露的强校验软删除恢复方法
+      define_method(:restore!) do |**options|
+        opts = options.deep_symbolize_keys
+        return unless respond_to?(deleted_field)
+
+        restore_block(**opts)
+
+        save!(touch: opts[:refresh_updated])
+      end
     end
   end
 end

data/lib/activemodel_object_info/version.rb

@@ -2,6 +2,6 @@
 
 module ActivemodelObjectInfo
   module Version
-    VERSION = '0.4.0'
+    VERSION = '0.4.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activemodel_object_info
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - shiner
@@ -170,7 +170,7 @@ homepage: https://github.com/shiner527/activemodel-object-info
 licenses:
 - MIT
 metadata:
-  rubygems_mfa_required: 'false'
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: