Skip to content

Commit 79d6cd5

Browse files
SyatiSyati
committed
Update README to enhance feature descriptions and examples for API parameter validation and form objects
1 parent 7bf8127 commit 79d6cd5

File tree

2 files changed

+73
-81
lines changed

2 files changed

+73
-81
lines changed

‎README.md‎

Lines changed: 37 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,82 @@
11
# StructuredParams
22

3-
StructuredParams is a Ruby gem that provides type-safe parameter validation and casting for Rails applications. It extends ActiveModel's type system to handle nested objects and arrays with automatic Strong Parameters integration.
4-
53
English | [日本語](README_ja.md)
64

7-
## Features
5+
**Type-safe API parameter validation and form objects for Rails**
6+
7+
StructuredParams solves these challenges:
8+
9+
- **API endpoints**: Type checking, validation, and automatic casting of request parameters
10+
- **Form objects**: Validation and conversion of complex form inputs to models
11+
12+
Built on ActiveModel, making nested objects and arrays easy to handle.
813

9-
- **Type-safe parameter validation** using ActiveModel::Type
10-
- **Nested object support** with automatic casting
11-
- **Array handling** for both primitive types and nested objects
12-
- **Strong Parameters integration** with automatic permit lists
13-
- **ActiveModel compatibility** with validations and serialization
14-
- **Form object pattern support** with Rails form helpers integration
15-
- **Enhanced error handling** with flat and structured formats
16-
- **RBS type definitions** for better development experience
14+
## Key Features
15+
16+
- ✅ **API Parameter Validation** - Type-safe request validation
17+
- ✅ **Form Objects** - Encapsulate complex form logic
18+
- ✅ **Nested Structure Support** - Automatic casting for objects and arrays
19+
- ✅ **Strong Parameters Integration** - Auto-generate permit lists
20+
- ✅ **ActiveModel Compatible** - Support for validations, serialization, and other standard features
21+
- ✅ **RBS Type Definitions** - Type-safe development experience
1722

1823
## Quick Start
1924

2025
```ruby
21-
# 1. Install the gem
26+
# Installation
2227
gem 'structured_params'
2328

24-
# 2. Register types in initializer
29+
# Initialize
2530
StructuredParams.register_types
31+
```
32+
33+
### 1. API Parameter Validation
2634

27-
# 3. Define parameter classes
35+
```ruby
2836
class UserParams < StructuredParams::Params
2937
attribute :name, :string
3038
attribute :age, :integer
31-
attribute :address, :object, value_class: AddressParams
32-
attribute :hobbies, :array, value_class: HobbyParams
3339

3440
validates :name, presence: true
3541
validates :age, numericality: { greater_than: 0 }
3642
end
3743

38-
# 4. Use in controllers (API)
44+
# Use in API controller
3945
def create
40-
user_params = UserParams.new(params)
46+
permitted = UserParams.permit(params, require: false)
47+
user_params = UserParams.new(permitted)
4148

4249
if user_params.valid?
4350
User.create!(user_params.attributes)
4451
else
45-
render json: { errors: user_params.errors.to_hash(false, structured: true) }
52+
render json: { errors: user_params.errors }, status: :unprocessable_entity
4653
end
4754
end
55+
```
4856

49-
# 5. Use as Form Objects (View Integration)
57+
### 2. Form Object
5058

51-
# Define a Form Object class
59+
```ruby
5260
class UserRegistrationForm < StructuredParams::Params
5361
attribute :name, :string
5462
attribute :email, :string
55-
attribute :password, :string
63+
attribute :terms_accepted, :boolean
5664

57-
validates :name, presence: true
58-
validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
65+
validates :name, :email, presence: true
66+
validates :terms_accepted, acceptance: true
5967
end
6068

61-
# Use in controllers
69+
# Use in controller
6270
def create
63-
@form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
71+
form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
6472

65-
if @form.valid?
66-
User.create!(@form.attributes)
67-
redirect_to user_path
73+
if form.valid?
74+
User.create!(form.attributes)
75+
redirect_to root_path
6876
else
6977
render :new
7078
end
7179
end
72-
73-
# Use in views
74-
<%= form_with model: @form, url: users_path do |f| %>
75-
<%= f.text_field :name %>
76-
<%= f.email_field :email %>
77-
<%= f.password_field :password %>
78-
<% end %>
7980
```
8081

8182
## Documentation
@@ -84,15 +85,10 @@ end
8485
- **[Basic Usage](docs/basic-usage.md)** - Parameter classes, nested objects, and arrays
8586
- **[Validation](docs/validation.md)** - Using ActiveModel validations with nested structures
8687
- **[Strong Parameters](docs/strong-parameters.md)** - Automatic permit list generation
87-
- **[Form Objects](docs/form-objects.md)** - Using as form objects with Rails form helpers
8888
- **[Error Handling](docs/error-handling.md)** - Flat and structured error formats
8989
- **[Serialization](docs/serialization.md)** - Converting parameters to hashes and JSON
9090
- **[Gem Comparison](docs/comparison.md)** - Comparison with typed_params, dry-validation, and reform
91-
- **[Contributing Guide](CONTRIBUTING.md)** - Developer setup and guidelines
92-
93-
## For Developers
9491

95-
If you're interested in contributing to this project, please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, RBS generation, testing guidelines, and more.
9692

9793
## Contributing
9894

‎README_ja.md‎

Lines changed: 36 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,82 @@
11
# StructuredParams
22

3-
StructuredParams は、Rails アプリケーションでタイプセーフなパラメータバリデーションとキャストを提供する Ruby gem です。ActiveModel の型システムを拡張して、ネストしたオブジェクトや配列を自動的な Strong Parameters 統合と共に処理します。
4-
53
[English](README.md) | 日本語
64

7-
## 特徴
5+
**Rails で型安全な API パラメータバリデーションとフォームオブジェクトを実現する gem**
6+
7+
StructuredParams は、以下の課題を解決します：
8+
9+
- **API エンドポイント**: リクエストパラメータの型チェック・バリデーション・自動キャスト
10+
- **フォームオブジェクト**: 複雑なフォーム入力の検証とモデルへの変換
11+
12+
ActiveModel をベースに、ネストしたオブジェクトや配列も簡単に扱えます。
813

9-
- **ActiveModel::Type を使用したタイプセーフなパラメータバリデーション**
10-
- **自動キャストによるネストオブジェクトサポート**
11-
- **プリミティブ型とネストオブジェクトの両方に対応した配列処理**
12-
- **自動 permit リスト生成による Strong Parameters 統合**
13-
- **バリデーションとシリアライゼーションを含む ActiveModel 互換性**
14-
- **Rails フォームヘルパーと統合された Form Object パターンのサポート**
15-
- **フラットと構造化フォーマットによる拡張エラーハンドリング**
16-
- **より良い開発体験のための RBS 型定義**
14+
## 主な特徴
15+
16+
- ✅ **API パラメータバリデーション** - 型安全なリクエスト検証
17+
- ✅ **フォームオブジェクト** - 複雑なフォームロジックのカプセル化
18+
- ✅ **ネスト構造対応** - オブジェクトや配列を自動キャスト
19+
- ✅ **Strong Parameters 統合** - permit リストを自動生成
20+
- ✅ **ActiveModel 互換** - バリデーション、シリアライゼーションなど標準機能をサポート
21+
- ✅ **RBS 型定義** - 型安全な開発体験
1722

1823
## クイックスタート
1924

2025
```ruby
21-
# 1. gem をインストール
26+
# インストール
2227
gem 'structured_params'
2328

24-
# 2. イニシャライザで型を登録
29+
# 初期化
2530
StructuredParams.register_types
31+
```
32+
33+
### 1. API パラメータバリデーション
2634

27-
# 3. パラメータクラスを定義
35+
```ruby
2836
class UserParams < StructuredParams::Params
2937
attribute :name, :string
3038
attribute :age, :integer
31-
attribute :address, :object, value_class: AddressParams
32-
attribute :hobbies, :array, value_class: HobbyParams
3339

3440
validates :name, presence: true
3541
validates :age, numericality: { greater_than: 0 }
3642
end
3743

38-
# 4. コントローラーで使用（API向け）
44+
# API コントローラーで使用
3945
def create
40-
user_params = UserParams.new(params)
46+
permitted = UserParams.permit(params, require: false)
47+
user_params = UserParams.new(permitted)
4148

4249
if user_params.valid?
4350
User.create!(user_params.attributes)
4451
else
45-
render json: { errors: user_params.errors.to_hash(false, structured: true) }
52+
render json: { errors: user_params.errors }, status: :unprocessable_entity
4653
end
4754
end
55+
```
4856

49-
# 5. Form Object として使用（View統合）
57+
### 2. フォームオブジェクト
5058

51-
# Form Object クラスを定義
59+
```ruby
5260
class UserRegistrationForm < StructuredParams::Params
5361
attribute :name, :string
5462
attribute :email, :string
55-
attribute :password, :string
63+
attribute :terms_accepted, :boolean
5664

57-
validates :name, presence: true
58-
validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
65+
validates :name, :email, presence: true
66+
validates :terms_accepted, acceptance: true
5967
end
6068

6169
# コントローラーで使用
6270
def create
63-
@form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
71+
form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
6472

65-
if @form.valid?
66-
User.create!(@form.attributes)
67-
redirect_to user_path
73+
if form.valid?
74+
User.create!(form.attributes)
75+
redirect_to root_path
6876
else
6977
render :new
7078
end
7179
end
72-
73-
# View で使用
74-
<%= form_with model: @form, url: users_path do |f| %>
75-
<%= f.text_field :name %>
76-
<%= f.email_field :email %>
77-
<%= f.password_field :password %>
78-
<% end %>
7980
```
8081

8182
## ドキュメント
@@ -84,15 +85,10 @@ end
8485
- **[基本的な使用方法](docs/basic-usage.md)** - パラメータクラス、ネストオブジェクト、配列
8586
- **[バリデーション](docs/validation.md)** - ネスト構造でのActiveModelバリデーション使用
8687
- **[Strong Parameters](docs/strong-parameters.md)** - 自動permit リスト生成
87-
- **[Form Object](docs/form-objects.md)** - Rails フォームヘルパーとの Form Object としての使用
8888
- **[エラーハンドリング](docs/error-handling.md)** - フラットと構造化エラーフォーマット
8989
- **[シリアライゼーション](docs/serialization.md)** - パラメータのハッシュとJSON変換
9090
- **[Gem比較](docs/comparison.md)** - typed_params、dry-validation、reformとの比較
91-
- **[コントリビューションガイド](CONTRIBUTING.md)** - 開発者向けセットアップとガイドライン
92-
93-
## 開発者向け
9491

95-
プロジェクトへの貢献に興味がある方は、[CONTRIBUTING.md](CONTRIBUTING.md) をご覧ください。開発環境のセットアップ、RBS型定義の生成方法、テストの実行方法などが記載されています。
9692

9793
## コントリビューション
9894

0 commit comments

Comments
 (0)