sparrow-entity 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c81bf422456d0aaabbefd6090a4a14cde0b6f1fa4ab105d8ae21d05ee13991e2
-  data.tar.gz: 4c19e1e71ea244e0bb1846fd73e1f78cdd6667ec3cbf0ad606f4448a39ec0bea
+  metadata.gz: be3bce43bdbd1c4380323c6ad8e4fcdbfe88d029fbfa2a5fad1301a209e7446e
+  data.tar.gz: d22a24207c474a06d218432a22e7ced31e3d5b2c1c3629326a242d66757f3069
 SHA512:
-  metadata.gz: b68d92f8b4c753e8f78f25b3bb71bceb33bcc10099117620c83c819c06d5fa600e858b4b271f7757cd3070a4e9df1a217de54a30f88352f6f32710776053d731
-  data.tar.gz: 040f115320bf3623aaac8c37a8efad04226abb40dbee7c51390f709b839203fb2ad338e64a2b8400d45a0f7d959f3a6608c673bee8a7c82538d1998a12cfc48c
+  metadata.gz: 6b37e180508398470f90083690b52a02066e49af868a7a74d6fc27122defd39a5ae137e54081193319ed16ddf6a59da447212e7a7563d53163fc7d0914a4783b
+  data.tar.gz: 85174be39093adb300d35779f0d04de33315e7aee9c952e0ca631a631bce151974ddce5c4faed3c0266e3cc3ba3400572ff679f866e2234042b7b293c4ca67c9

data/.rubocop.yml

@@ -78,3 +78,5 @@ Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: consistent_comma
 Style/TrailingCommaInArrayLiteral:
   EnforcedStyleForMultiline: consistent_comma
+Style/RedundantConstantBase:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-ruby-2.6.8
+ruby-2.7.7

data/Gemfile.lock

@@ -1,84 +1,111 @@
 PATH
   remote: .
   specs:
-    sparrow-entity (0.1.4)
+    sparrow-entity (0.3.0)
       activemodel
-      activemodel_object_info (~> 0.2.0)
+      activemodel_object_info (>= 0.4.2)
       activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.1.4.4)
-      activesupport (= 6.1.4.4)
-    activemodel_object_info (0.2.0)
+    activemodel (7.1.6)
+      activesupport (= 7.1.6)
+    activemodel_object_info (0.4.2)
       activesupport
-    activesupport (6.1.4.4)
+    activesupport (7.1.6)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
       concurrent-ruby (~> 1.0, >= 1.0.2)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
       minitest (>= 5.1)
+      mutex_m
+      securerandom (>= 0.3)
       tzinfo (~> 2.0)
-      zeitwerk (~> 2.3)
-    ast (2.4.2)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (4.1.2)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
-    diff-lcs (1.5.0)
-    docile (1.4.0)
-    i18n (1.8.11)
+    concurrent-ruby (1.3.8)
+    connection_pool (2.5.5)
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    drb (2.2.3)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    method_source (1.0.0)
-    minitest (5.15.0)
-    parallel (1.21.0)
-    parser (3.0.3.2)
+    io-console (0.8.2)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    method_source (1.1.0)
+    minitest (5.26.1)
+    mutex_m (0.3.0)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
-    pry (0.14.1)
+      racc
+    prism (1.9.0)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rainbow (3.0.0)
-    rake (13.0.6)
-    regexp_parser (2.2.0)
-    rexml (3.2.5)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.1)
+      reline (>= 0.6.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.3)
-    rubocop (1.24.0)
-      parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.15.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.15.1)
-      parser (>= 3.0.1.1)
-    ruby-progressbar (1.11.0)
-    simplecov (0.21.2)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    securerandom (0.3.2)
+    simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.12.3)
-    simplecov_json_formatter (0.1.3)
-    tzinfo (2.0.4)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.1.0)
-    webrick (1.7.0)
-    yard (0.9.27)
-      webrick (~> 1.7.0)
-    zeitwerk (2.5.3)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    yard (0.9.45)
 
 PLATFORMS
-  ruby
+  arm64-darwin-21
+  arm64-darwin-22
 
 DEPENDENCIES
   bundler
@@ -91,4 +118,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   1.17.3
+   2.4.10

data/README.ja.md

@@ -0,0 +1,256 @@
+# 🐦 Sparrow Entity
+
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+[![Gem Version](https://badge.fury.io/rb/sparrow-entity.svg)](https://rubygems.org/gems/sparrow-entity)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 📖 目次
+- [🌟 概要](#-概要)
+- [✨ 主な機能](#-主な機能)
+- [📦 インストール](#-インストール)
+- [💻 使い方ガイド](#-使い方ガイド)
+  - [1. 基本的なエンティティの定義](#1-基本的なエンティティの定義)
+  - [2. 自動型変換](#2-自動型変換)
+  - [3. 真偽値（Boolean）フィールド](#3-真偽値booleanフィールド)
+  - [4. デフォルト値](#4-デフォルト値)
+  - [5. ActiveModel の統合（バリデーションとコールバック）](#5-activemodel-の統合バリデーションとコールバック)
+  - [6. シリアライズ](#6-シリアライズ)
+- [🚀 Rails 統合とジェネレーター](#-rails-統合とジェネレーター)
+- [📝 ライセンス](#-ライセンス)
+
+---
+
+## 🌟 概要
+
+**Sparrow Entity** は、データベースに依存しないデータに対して、ORMライクなエンティティモデリングを提供する軽量な Ruby Gem です。
+
+現代のアーキテクチャ、特にマイクロサービスでは、ローカルデータベースではなく外部 API、メッセージキュー、または gRPC サービスから大量のデータを取得して処理することがよくあります。このようなシナリオでは、背後にデータベーステーブルが存在しないため、`ActiveRecord::Base` を使用することができません。**Sparrow** はこのギャップを完全に埋め、使い慣れた ActiveModel の利便性を保ちながら、構造化され強力に型付けされたエンティティオブジェクト（強化された PORO）を定義できるようにします。
+
+## ✨ 主な機能
+
+*   **🛠 ORMライクな操作感**：ActiveRecord と同じように属性と型を定義できます。
+*   **🗂 自動型変換**：代入された値を定義済みの型（例：`String`、`Integer`、`Date`、`Sparrow::Boolean`）に自動的に変換します。
+*   **⚙️ デフォルト値**：初期化時の値が空または無効な場合に備えて、属性にデフォルトのフォールバック値を設定できます。
+*   **🛤 ActiveModel 統合**：コールバック、バリデーション、Dirty トラッキング、翻訳（I18n）を標準でサポートしています。
+*   **🚀 Rails ジェネレーター**：組み込みの Rails ジェネレーター CLI を使用して、エンティティクラスを瞬時に生成できます。
+*   **📦 シリアライズ**：`activemodel_object_info` を組み込みでサポートし、エンティティを Hash や JSON に簡単にシリアライズできます。
+
+## 📦 インストール
+
+アプリケーションの `Gemfile` に以下の行を追加します：
+
+```ruby
+gem 'sparrow-entity', require: 'sparrow'
+```
+
+その後、以下のコマンドを実行します：
+
+```bash
+$ bundle install
+```
+
+または、以下のようにグローバルにインストールすることもできます：
+
+```bash
+$ gem install sparrow-entity
+```
+
+## 💻 使い方ガイド
+
+### 1. 基本的なエンティティの定義
+
+独自のエンティティを作成するには、単に `Sparrow::Base` を継承します。想定される Ruby の型とともにフィールドを定義できます。
+
+```ruby
+require 'sparrow' # Rails プロジェクトでは省略可能
+
+#
+# 外部の User サービスから取得したユーザーエンティティを表す
+#
+# [Changelog]
+# - 1.0.0: Initial release
+#
+class UserEntity < Sparrow::Base
+  field :id, Integer
+  field :family_name, String
+  field :given_name, String
+  field :birthday, Date
+  field :nationality, String
+
+  #
+  # ユーザーのフルネームをフォーマットして返す
+  #
+  # @since 1.0.0
+  # @param [Hash] options フォーマットのオプション
+  # @option options [Symbol] :last 姓を最後に配置するかどうか
+  # @option options [String] :separator 姓名を結合する文字列
+  # @return [String] フォーマットされたフルネーム
+  #
+  def full_name(options = {})
+    last = options[:last] || :given
+    separator = options[:separator] || ' '
+    
+    val = [family_name, given_name]
+    val.reverse! if last == :family
+    val.join(separator)
+  end
+end
+
+user = UserEntity.new(id: 1, family_name: 'Doe', given_name: 'John')
+puts user.full_name(last: :family) # => "John Doe"
+```
+
+### 2. 自動型変換
+
+Sparrow は、代入された値を定義された型に自動的に変換しようと試みます。
+
+```ruby
+user = UserEntity.new
+user.id = "42"          # 文字列として代入
+user.birthday = "2023-10-01" # 文字列として代入
+
+puts user.id.class       # => Integer (42)
+puts user.birthday.class # => Date (<Date: 2023-10-01 ...>)
+```
+
+### 3. 真偽値（Boolean）フィールド
+
+真偽値のロジックを扱うために、Sparrow は `Sparrow::Boolean` を提供しています。これは `.present?` のチェックや明示的な真偽値の等価性に基づいて、truthy な値と falsey な値を適切に処理します。
+
+```ruby
+class SettingsEntity < Sparrow::Base
+  field :notifications_enabled, Sparrow::Boolean
+end
+
+settings = SettingsEntity.new
+puts settings.notifications_enabled.inspect # => nil
+
+settings.notifications_enabled = 'yes'
+puts settings.notifications_enabled         # => true
+
+settings.notifications_enabled = ''
+puts settings.notifications_enabled         # => false
+```
+
+### 4. デフォルト値
+
+`default:` オプションを提供することができます。代入された値が空または無効な場合、このデフォルト値にフォールバックします。
+
+```ruby
+class TaskEntity < Sparrow::Base
+  field :status, String, default: 'pending'
+  field :retry_count, Integer, default: 0
+end
+
+task = TaskEntity.new
+puts task.status      # => "pending"
+puts task.retry_count # => 0
+
+task.status = 'in_progress'
+puts task.status      # => "in_progress"
+```
+
+### 5. ActiveModel の統合（バリデーションとコールバック）
+
+Sparrow は `ActiveModel` モジュールをインクルードしているため、バリデーションやコールバック（`before_validation`、`after_initialize` など）をそのまま使用できます。
+
+```ruby
+class OrderEntity < Sparrow::Base
+  field :order_no, String
+  field :amount, Float
+  field :state, String, default: 'created'
+
+  validates :order_no, presence: true
+  validates :amount, numericality: { greater_than: 0 }
+
+  before_validation :generate_order_no, if: -> { order_no.blank? }
+
+  private
+
+  #
+  # 存在しない場合にランダムな注文番号を生成する
+  #
+  # @since 1.0.0
+  # @return [String] 生成された注文番号
+  #
+  def generate_order_no
+    self.order_no = "ORD-#{Time.now.to_i}"
+  end
+end
+
+order = OrderEntity.new(amount: 150.50)
+order.valid? # => true
+puts order.order_no # => "ORD-1698765432"
+```
+
+### 6. シリアライズ
+
+Sparrow は `activemodel_object_info`（v0.4.2+）を使用して、エンティティを Hash や JSON 形式に簡単にダンプできるようにサポートします。強力なコンテキスト設定、ホワイトリスト/ブラックリスト、カスタム Lambda フィルターなどの機能を提供します。
+
+```ruby
+class ProductEntity < Sparrow::Base
+  field :sku, String
+  field :price, Float
+  field :stock, Integer, default: 0
+
+  # デフォルトの出力設定を定義
+  INSTANCE_INFO = {
+    only: [:sku, :price],
+    attributes: [
+      :sku,
+      { name: :price, type: :abstract, filter: ->(v) { "$#{format('%.2f', v)}" } }
+    ]
+  }.freeze
+
+  # コンテキスト固有の出力設定を定義
+  INSTANCE_INFO_DETAIL = {
+    only: [:sku, :price, :stock]
+  }.freeze
+end
+
+product = ProductEntity.new(sku: 'MAC-M2-001', price: 1299.9)
+
+# 標準的な属性の Hash
+puts product.attributes 
+# => { sku: "MAC-M2-001", price: 1299.9, stock: 0 }
+
+# 1. デフォルトで INSTANCE_INFO 定数を使用
+puts product.instance_info
+# => { sku: "MAC-M2-001", price: "$1299.90" }
+
+# 2. コンテキスト出力：`context` を渡すことで INSTANCE_INFO_DETAIL を自動的に使用
+puts product.instance_info(context: :detail)
+# => { sku: "MAC-M2-001", price: 1299.9, stock: 0 }
+
+# 3. 実行時の上書き
+puts product.instance_info(only: [:sku])
+# => { sku: "MAC-M2-001" }
+
+# 4. 特定のフィールドを除外 (except)
+puts product.instance_info(context: :detail, except: [:price])
+# => { sku: "MAC-M2-001", stock: 0 }
+```
+
+## 🚀 Rails 統合とジェネレーター
+
+Ruby on Rails を使用している場合、`sparrow-entity` ファイルは自動的にロードされます。
+
+組み込みのジェネレーターを使用して、エンティティクラスの雛形をすばやく作成できます：
+
+```bash
+$ rails g sparrow:entity Post::Reply
+```
+
+これにより、`app/entities/post/reply.rb` が生成されます：
+
+```ruby
+module Post
+  class Reply < Sparrow::Base
+  end
+end
+```
+
+## 📝 ライセンス
+
+この Gem は [MIT ライセンス](https://opensource.org/licenses/MIT) の条件の下でオープンソースとして利用可能です。

data/README.md

@@ -1,152 +1,256 @@
-# Sparrow
+# 🐦 Sparrow Entity
 
-Sparrow 用来快速实现在一个 Ruby 项目中引入实体处理非数据库可以映射的项目。特别是对于拆分为微服务的项目来说，由于大量数据基于其他服务获取到，而并不是直接来源于数据库，所以不能使用基于 **ActiveRecord::Base** 这样的类来处理具体数据实例。而 Sparrow 就提供了类似 ORM 式的使用方法来处理这些对象类。
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
 
-## 安装
+[![Gem Version](https://badge.fury.io/rb/sparrow-entity.svg)](https://rubygems.org/gems/sparrow-entity)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-在你的项目中的 Gemfile 文件添加如下一行即可。建议保持最新版本以获取功能齐全的体验。
+## 📖 Table of Contents
+- [🌟 Introduction](#-introduction)
+- [✨ Features](#-features)
+- [📦 Installation](#-installation)
+- [💻 Usage Guide](#-usage-guide)
+  - [1. Basic Entity Definition](#1-basic-entity-definition)
+  - [2. Automatic Type Casting](#2-automatic-type-casting)
+  - [3. Boolean Fields](#3-boolean-fields)
+  - [4. Default Values](#4-default-values)
+  - [5. ActiveModel Integrations (Validations & Callbacks)](#5-activemodel-integrations-validations--callbacks)
+  - [6. Serialization](#6-serialization)
+- [🚀 Rails Integration & Generator](#-rails-integration--generator)
+- [📝 License](#-license)
+
+---
+
+## 🌟 Introduction
+
+**Sparrow Entity** is a lightweight Ruby gem designed to provide ORM-like entity modeling for non-database-backed data. 
+
+In modern architectures, especially microservices, applications often consume vast amounts of data from external APIs, message queues, or gRPC services rather than local databases. In these scenarios, `ActiveRecord::Base` cannot be used since there is no underlying database table. **Sparrow** perfectly fills this gap by allowing you to define structured, strongly-typed Entity objects (Plain Old Ruby Objects on steroids) with all the familiar ActiveModel conveniences.
+
+## ✨ Features
+
+*   **🛠 ORM-like Experience**: Define attributes and types just like you would in ActiveRecord.
+*   **🗂 Automatic Type Casting**: Automatically converts assigned values to defined types (e.g., `String`, `Integer`, `Date`, `Sparrow::Boolean`).
+*   **⚙️ Default Values**: Set default fallback values for attributes when initialization is blank or invalid.
+*   **🛤 ActiveModel Integration**: Supports callbacks, validations, dirty tracking, and translations out of the box.
+*   **🚀 Rails Generator**: Instantly generate entity classes using the built-in Rails generator CLI.
+*   **📦 Serialization**: Built-in support for `activemodel_object_info` to easily serialize entities into Hashes/JSON.
+
+## 📦 Installation
+
+Add this line to your application's `Gemfile`:
 
 ```ruby
 gem 'sparrow-entity', require: 'sparrow'
 ```
 
-之后在你的项目文件夹下执行命令安装。
+Then execute:
 
-  $ bundle
+```bash
+$ bundle install
+```
 
-或者也可以直接使用 gem 命令全局安装。
+Or install it globally via:
 
-  $ gem install sparrow-entity
+```bash
+$ gem install sparrow-entity
+```
 
-## 使用
+## 💻 Usage Guide
 
-### 一般的使用方法
+### 1. Basic Entity Definition
 
-安装之后尽可以在需要的时候随意创建自己的实体类，只要继承该 gem 提供的基础类即可。需要注意的是，如果你是在单纯的 Ruby 项目下使用，记得在使用前引入相关文件，比如：
+To create your own entity, simply inherit from `Sparrow::Base`. You can define fields with their expected Ruby types.
 
 ```ruby
-# 使用本 gem 引入。如果是 Rails 项目则可省略。
-require 'sparrow'
-
-# 定义一个继承自 gem 基本实体类的自定义实体类
-class MyEntity < Sparrow::Base
-  # 定义相关的属性和类型
+require 'sparrow' # Not required in Rails
+
+#
+# Represents a User entity fetched from an external User Service
+#
+# [Changelog]
+# - 1.0.0: Initial release
+#
+class UserEntity < Sparrow::Base
   field :id, Integer
   field :family_name, String
   field :given_name, String
-  field :gender, Integer
   field :birthday, Date
   field :nationality, String
-  # 也可以给与属性默认值，如果属性值本身无效时获取该属性会返回默认值
-  field :status, String, default: 'good'
 
-  # 定义具体的实例方法可以在之后使用
-  def full_name(last: :given, seperator: ' ')
+  #
+  # Format and return the full name of the user
+  #
+  # @since 1.0.0
+  # @param [Hash] options formatting options
+  # @option options [Symbol] :last whether to place family name last or first
+  # @option options [String] :separator string used to join names
+  # @return [String] the formatted full name
+  #
+  def full_name(options = {})
+    last = options[:last] || :given
+    separator = options[:separator] || ' '
+    
     val = [family_name, given_name]
     val.reverse! if last == :family
-    val.join(seperator)
+    val.join(separator)
   end
 end
+
+user = UserEntity.new(id: 1, family_name: 'Doe', given_name: 'John')
+puts user.full_name(last: :family) # => "John Doe"
 ```
 
-这样定义的一个类就具有了唯一标示 **id**，姓氏 **family_name**，名字 **given_name**，性别 **gender**，出生日期 **birthday** 和国籍 **nationality** 这几个属性，并且会在赋值和获取对应属性值时尝试自动将该属性设置转换为对应的数据类型。举例来说，比如给出一个可以被解析的日期字符串并赋值给出生日期属性，那么获取该属性值时会自动转化成定义属性时设定的 **Date** 类型的日期：
+### 2. Automatic Type Casting
+
+Sparrow will attempt to coerce assigned values into the defined types automatically.
 
 ```ruby
-me = MyEntity.new(birthday: '2022-01-01')
-me.birthday
-# => <Date 2022年1月1日> 实例对象
+user = UserEntity.new
+user.id = "42"          # Assigned as a String
+user.birthday = "2023-10-01" # Assigned as a String
+
+puts user.id.class       # => Integer (42)
+puts user.birthday.class # => Date (<Date: 2023-10-01 ...>)
 ```
 
-### 布尔型属性
+### 3. Boolean Fields
 
-当需要定义一个属性字段为布尔型时，可以使用本 gem 内置的 `Sparrow::Boolean` 作为类型定义即可。当赋予 **true** 值或者等价于（即使用 `present?` 判断为真）其值时被赋予真值，否则被赋予假值。同样的，如果没有对其进行赋值，则获取该字段属性会返回 **nil** 空值。
+For boolean logic, Sparrow provides `Sparrow::Boolean`. It handles truthy and falsey values gracefully based on `.present?` checks or explicit boolean equivalents.
 
 ```ruby
-class OtherEntity < Sparrow::Base
-  field :married, Sparrow::Boolean
+class SettingsEntity < Sparrow::Base
+  field :notifications_enabled, Sparrow::Boolean
 end
 
-obj = OtherEntity.new
-obj.married
-# => nil
-
-obj.married = true
-obj.married
-# => true
+settings = SettingsEntity.new
+puts settings.notifications_enabled.inspect # => nil
 
-obj.married = ''
-obj.married
-# => false
+settings.notifications_enabled = 'yes'
+puts settings.notifications_enabled         # => true
 
-obj.married = 'yes'
-obj.married
-# => true
+settings.notifications_enabled = ''
+puts settings.notifications_enabled         # => false
 ```
 
-### 赋值
+### 4. Default Values
 
-上例中也展示了为实体类的实例进行属性赋值的方式之一，即创建时指定属性名对应的值。当然也可以在创建后分别给属性赋值。
+You can provide a `default:` option. If the assigned value is empty or invalid, it will fallback to this default value.
 
 ```ruby
-me.family_name = '张'
-me.last_name = '三'
-me.full_name(seperator: '')
-# => "张三" 
+class TaskEntity < Sparrow::Base
+  field :status, String, default: 'pending'
+  field :retry_count, Integer, default: 0
+end
+
+task = TaskEntity.new
+puts task.status      # => "pending"
+puts task.retry_count # => 0
+
+task.status = 'in_progress'
+puts task.status      # => "in_progress"
 ```
 
-### 默认属性值
+### 5. ActiveModel Integrations (Validations & Callbacks)
 
-在定义属性的时候可以跟着 `default` 命名参数给出默认值。当属性值为空或者无效时，获取属性的时候会返回默认值。
+Because Sparrow includes `ActiveModel` modules, you can use validations and callbacks (`before_validation`, `after_initialize`, etc.) out of the box.
 
 ```ruby
-me.status
-# => "good"
-me.status = 'bad'
-me.status
-# => "bad"
+class OrderEntity < Sparrow::Base
+  field :order_no, String
+  field :amount, Float
+  field :state, String, default: 'created'
+
+  validates :order_no, presence: true
+  validates :amount, numericality: { greater_than: 0 }
+
+  before_validation :generate_order_no, if: -> { order_no.blank? }
+
+  private
+
+  #
+  # Generate a random order number if not present
+  #
+  # @since 1.0.0
+  # @return [String] the generated order number
+  #
+  def generate_order_no
+    self.order_no = "ORD-#{Time.now.to_i}"
+  end
+end
+
+order = OrderEntity.new(amount: 150.50)
+order.valid? # => true
+puts order.order_no # => "ORD-1698765432"
 ```
 
-### 基于 Rails 项目的使用方法
+### 6. Serialization
 
-如果你的项目是一个基于 Rails 框架的项目，那么在创建自己的实体时并不需要特别声明引入该 gem 对应的文件，因为 Rails 框架已经替你做好了一切。
+Sparrow leverages `activemodel_object_info` (v0.4.2+) to easily dump entities into Hashes or JSON formats, offering powerful contextual formatting, whitelisting/blacklisting, and custom lambdas.
 
-另外，使用 Rails 框架的项目还可以利用本 gem 提供的生成器(Generator)来方便快速生成一个新的实体类。
+```ruby
+class ProductEntity < Sparrow::Base
+  field :sku, String
+  field :price, Float
+  field :stock, Integer, default: 0
+
+  # Define default output configuration
+  INSTANCE_INFO = {
+    only: [:sku, :price],
+    attributes: [
+      :sku,
+      { name: :price, type: :abstract, filter: ->(v) { "$#{format('%.2f', v)}" } }
+    ]
+  }.freeze
+
+  # Define contextual output configuration
+  INSTANCE_INFO_DETAIL = {
+    only: [:sku, :price, :stock]
+  }.freeze
+end
 
-  $ rails g sparrow:entity Post::Replay
+product = ProductEntity.new(sku: 'MAC-M2-001', price: 1299.9)
 
-使用命令 Rails 生成器命令 `sparrow:entity` 会在你的项目根文件夹的 `app/entities` 路径下生成 `post/reply.rb` 的文件，文件也自动创建了好了继承类。
+# Standard attributes hash
+puts product.attributes 
+# => { sku: "MAC-M2-001", price: 1299.9, stock: 0 }
 
-```ruby
-module Post
-  class Reply < Sparrow::Base
-  end
-end
+# 1. Uses default INSTANCE_INFO constant
+puts product.instance_info
+# => { sku: "MAC-M2-001", price: "$1299.90" }
+
+# 2. Contextual output: Pass `context` to use INSTANCE_INFO_DETAIL
+puts product.instance_info(context: :detail)
+# => { sku: "MAC-M2-001", price: 1299.9, stock: 0 }
+
+# 3. Override at runtime
+puts product.instance_info(only: [:sku])
+# => { sku: "MAC-M2-001" }
+
+# 4. Exclude specific fields (except)
+puts product.instance_info(context: :detail, except: [:price])
+# => { sku: "MAC-M2-001", stock: 0 }
 ```
 
-之后可以根据自己的需要修改生成的框架类的命名空间或者类的名称。
+## 🚀 Rails Integration & Generator
 
-### 内置的属性方法
+If you are using Ruby on Rails, `sparrow-entity` files will be automatically required.
 
-除了常规的 `attributes` 和 `attribute_names` 方法分别获取属性名和值的键值对以及属性名的数组外，本 gem 还内置了 [activemodel_object_info](https://rubygems.org/gems/activemodel_object_info) 这个 gem 辅助生成属性和值的键值对散列。具体用法请参考相关 gem 的说明文档。
+You can use the built-in generator to quickly scaffold entity classes:
 
-```ruby
-OUTPUT = { 
-  attributes: [
-    { name: :full_name, type: :method },
-    { name: :sex, as: :gender, type: :abstract, filter: ->(v) { v == 1 ? 'Male' : 'Female' } },
-  ],
-}.freeze
-
-me.instance_info(OUTPUT)
-# => { full_name: "张三", sex: "Male" }
+```bash
+$ rails g sparrow:entity Post::Reply
 ```
 
-## 面向开发者
-
-内置 Rake 命令包括了控制台开启命令 `rake c` 或者 `rake console` 即可开启控制台模式。
+This will generate `app/entities/post/reply.rb`:
 
-默认的 Rake 命令为单元测试命令，等同于 `bundle exec rspec` 命令的效果。
+```ruby
+module Post
+  class Reply < Sparrow::Base
+  end
+end
+```
 
-## License
+## 📝 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/README.zh-CN.md

@@ -0,0 +1,256 @@
+# 🐦 Sparrow Entity
+
+[English](./README.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+[![Gem Version](https://badge.fury.io/rb/sparrow-entity.svg)](https://rubygems.org/gems/sparrow-entity)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 📖 目录
+- [🌟 简介](#-简介)
+- [✨ 特性](#-特性)
+- [📦 安装](#-安装)
+- [💻 使用指南](#-使用指南)
+  - [1. 基础实体定义](#1-基础实体定义)
+  - [2. 自动类型转换](#2-自动类型转换)
+  - [3. 布尔类型字段](#3-布尔类型字段)
+  - [4. 默认值](#4-默认值)
+  - [5. ActiveModel 集成（验证与回调）](#5-activemodel-集成验证与回调)
+  - [6. 序列化能力](#6-序列化能力)
+- [🚀 Rails 集成与生成器](#-rails-集成与生成器)
+- [📝 许可协议](#-许可协议)
+
+---
+
+## 🌟 简介
+
+**Sparrow Entity** 是一个轻量级的 Ruby Gem，旨在为非数据库支持的数据提供类似 ORM 的实体建模能力。
+
+在现代系统架构（尤其是微服务架构）中，应用程序往往需要从外部 API、消息队列或 gRPC 服务中获取并处理大量数据，而不是直接读取本地数据库。在这些场景下，由于没有底层数据库表，我们无法使用 `ActiveRecord::Base`。**Sparrow** 完美地填补了这一空白，允许您定义结构化、强类型的实体对象（强化版的普通 Ruby 对象），并保留所有大家熟悉的 ActiveModel 优势。
+
+## ✨ 特性
+
+*   **🛠 类似 ORM 的体验**：像在 ActiveRecord 中一样定义属性和类型。
+*   **🗂 自动类型转换**：自动将赋的值转换为预期的类型（例如 `String`、`Integer`、`Date`、`Sparrow::Boolean` 等）。
+*   **⚙️ 默认值**：当初始化值为空或无效时，支持为属性设置默认回退值。
+*   **🛤 ActiveModel 集成**：开箱即用地支持回调（Callbacks）、验证（Validations）、脏数据追踪（Dirty Tracking）和国际化（I18n）。
+*   **🚀 Rails 生成器**：使用内置的 Rails 生成器 CLI 可以一键生成实体类。
+*   **📦 序列化能力**：内置支持 `activemodel_object_info`，可轻松将实体序列化为 Hash/JSON。
+
+## 📦 安装
+
+在您应用的 `Gemfile` 中添加以下代码：
+
+```ruby
+gem 'sparrow-entity', require: 'sparrow'
+```
+
+然后执行安装：
+
+```bash
+$ bundle install
+```
+
+或者使用全局安装命令：
+
+```bash
+$ gem install sparrow-entity
+```
+
+## 💻 使用指南
+
+### 1. 基础实体定义
+
+要创建您自己的实体，只需继承 `Sparrow::Base`。您可以定义字段并指定预期的 Ruby 类型。
+
+```ruby
+require 'sparrow' # 在 Rails 项目中可省略
+
+#
+# 表示从外部用户服务获取的用户实体
+#
+# [Changelog]
+# - 1.0.0: Initial release
+#
+class UserEntity < Sparrow::Base
+  field :id, Integer
+  field :family_name, String
+  field :given_name, String
+  field :birthday, Date
+  field :nationality, String
+
+  #
+  # 格式化并返回用户的全名
+  #
+  # @since 1.0.0
+  # @param [Hash] options 格式化选项
+  # @option options [Symbol] :last 是否将姓氏放在最后
+  # @option options [String] :separator 用于连接姓和名的字符串
+  # @return [String] 格式化后的全名
+  #
+  def full_name(options = {})
+    last = options[:last] || :given
+    separator = options[:separator] || ' '
+    
+    val = [family_name, given_name]
+    val.reverse! if last == :family
+    val.join(separator)
+  end
+end
+
+user = UserEntity.new(id: 1, family_name: 'Doe', given_name: 'John')
+puts user.full_name(last: :family) # => "John Doe"
+```
+
+### 2. 自动类型转换
+
+Sparrow 会尝试自动将赋值转换为定义好的类型。
+
+```ruby
+user = UserEntity.new
+user.id = "42"          # 以字符串形式赋值
+user.birthday = "2023-10-01" # 以字符串形式赋值
+
+puts user.id.class       # => Integer (42)
+puts user.birthday.class # => Date (<Date: 2023-10-01 ...>)
+```
+
+### 3. 布尔类型字段
+
+针对布尔逻辑，Sparrow 提供了 `Sparrow::Boolean` 类型。它可以根据 `.present?` 检查或明确的布尔等效值，优雅地处理真值和假值。
+
+```ruby
+class SettingsEntity < Sparrow::Base
+  field :notifications_enabled, Sparrow::Boolean
+end
+
+settings = SettingsEntity.new
+puts settings.notifications_enabled.inspect # => nil
+
+settings.notifications_enabled = 'yes'
+puts settings.notifications_enabled         # => true
+
+settings.notifications_enabled = ''
+puts settings.notifications_enabled         # => false
+```
+
+### 4. 默认值
+
+您可以提供一个 `default:` 选项。如果赋的值为空或无效，则将退回到此默认值。
+
+```ruby
+class TaskEntity < Sparrow::Base
+  field :status, String, default: 'pending'
+  field :retry_count, Integer, default: 0
+end
+
+task = TaskEntity.new
+puts task.status      # => "pending"
+puts task.retry_count # => 0
+
+task.status = 'in_progress'
+puts task.status      # => "in_progress"
+```
+
+### 5. ActiveModel 集成（验证与回调）
+
+由于 Sparrow 引入了 `ActiveModel` 的相关模块，您可以直接使用验证和回调（如 `before_validation`, `after_initialize` 等）。
+
+```ruby
+class OrderEntity < Sparrow::Base
+  field :order_no, String
+  field :amount, Float
+  field :state, String, default: 'created'
+
+  validates :order_no, presence: true
+  validates :amount, numericality: { greater_than: 0 }
+
+  before_validation :generate_order_no, if: -> { order_no.blank? }
+
+  private
+
+  #
+  # 如果不存在则生成随机的订单号
+  #
+  # @since 1.0.0
+  # @return [String] 生成的订单号
+  #
+  def generate_order_no
+    self.order_no = "ORD-#{Time.now.to_i}"
+  end
+end
+
+order = OrderEntity.new(amount: 150.50)
+order.valid? # => true
+puts order.order_no # => "ORD-1698765432"
+```
+
+### 6. 序列化能力
+
+Sparrow 利用 `activemodel_object_info`（v0.4.2+）帮助您轻松地将实体对象转储为 Hash 或 JSON 格式，并提供强大的上下文配置、白名单/黑名单以及自定义 Lambda 过滤等功能。
+
+```ruby
+class ProductEntity < Sparrow::Base
+  field :sku, String
+  field :price, Float
+  field :stock, Integer, default: 0
+
+  # 定义默认输出配置
+  INSTANCE_INFO = {
+    only: [:sku, :price],
+    attributes: [
+      :sku,
+      { name: :price, type: :abstract, filter: ->(v) { "$#{format('%.2f', v)}" } }
+    ]
+  }.freeze
+
+  # 定义特定上下文输出配置
+  INSTANCE_INFO_DETAIL = {
+    only: [:sku, :price, :stock]
+  }.freeze
+end
+
+product = ProductEntity.new(sku: 'MAC-M2-001', price: 1299.9)
+
+# 标准的属性 Hash
+puts product.attributes 
+# => { sku: "MAC-M2-001", price: 1299.9, stock: 0 }
+
+# 1. 默认使用 INSTANCE_INFO 常量
+puts product.instance_info
+# => { sku: "MAC-M2-001", price: "$1299.90" }
+
+# 2. 上下文输出：通过传入 `context` 自动使用 INSTANCE_INFO_DETAIL
+puts product.instance_info(context: :detail)
+# => { sku: "MAC-M2-001", price: 1299.9, stock: 0 }
+
+# 3. 运行时覆盖
+puts product.instance_info(only: [:sku])
+# => { sku: "MAC-M2-001" }
+
+# 4. 排除特定字段 (except)
+puts product.instance_info(context: :detail, except: [:price])
+# => { sku: "MAC-M2-001", stock: 0 }
+```
+
+## 🚀 Rails 集成与生成器
+
+如果您正在使用 Ruby on Rails 框架，`sparrow-entity` 会被自动加载。
+
+您可以使用内置生成器快速搭建实体类的基础代码：
+
+```bash
+$ rails g sparrow:entity Post::Reply
+```
+
+这将在 `app/entities/post/reply.rb` 中生成以下代码：
+
+```ruby
+module Post
+  class Reply < Sparrow::Base
+  end
+end
+```
+
+## 📝 许可协议
+
+此 Gem 遵循 [MIT 许可协议](https://opensource.org/licenses/MIT) 作为开源软件发布。

data/lib/sparrow/version.rb

@@ -2,7 +2,7 @@
 
 module Sparrow
   # 当前版本号
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
   # 当前综述
   SUMMARY = 'Provide an easy approach to build entity object for data that can not be reflected to database tables.'
   # 当前详述

data/sparrow.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |spec|
   spec.description   = Sparrow::DESCRIPTION
   spec.homepage      = 'https://github.com/shiner527/sparrow'
   spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.7.7'
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
@@ -39,7 +40,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'activemodel'
-  spec.add_dependency 'activemodel_object_info', '>= 0.3.0'
+  spec.add_dependency 'activemodel_object_info', '>= 0.4.2'
   spec.add_dependency 'activesupport'
 
   spec.add_development_dependency 'bundler'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sparrow-entity
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - shiner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-20 00:00:00.000000000 Z
+date: 2026-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.2
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -170,7 +170,9 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- README.ja.md
 - README.md
+- README.zh-CN.md
 - Rakefile
 - bin/console
 - bin/setup
@@ -202,7 +204,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.7
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="