You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds documentation for the Params extension to the extensions guide,
including:
- Overview of input validation with dry-schema
- Installation and setup instructions
- Basic usage examples showing success and failure cases
- Schema class usage for reusing schemas across operations
- Integration with custom methods via operate_on
- Schema inheritance behavior
Copy file name to clipboardExpand all lines: docsite/source/extensions.html.md
+139Lines changed: 139 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -169,3 +169,142 @@ end
169
169
```
170
170
171
171
⚠️ Warning: The `:requires_new` option for nested transactions is not yet fully supported.
172
+
173
+
### Params
174
+
175
+
The `Params` extension adds input validation support to your operations using [dry-validation](https://dry-rb.org/gems/dry-validation/). When an operation is called, the input will be automatically validated against the defined rules before the operation logic executes. If validation fails, the operation returns a `Failure` with detailed error information without executing the operation body.
176
+
177
+
Make sure you have dry-validation installed:
178
+
179
+
```ruby
180
+
gem "dry-validation"
181
+
```
182
+
183
+
Require and include the extension in your operation class, then define validation rules using the `params` class method:
184
+
185
+
```ruby
186
+
require"dry/operation/extensions/params"
187
+
188
+
classCreateUser < Dry::Operation
189
+
includeDry::Operation::Extensions::Params
190
+
191
+
params do
192
+
required(:name).filled(:string)
193
+
required(:email).filled(:string)
194
+
optional(:age).maybe(:integer)
195
+
end
196
+
197
+
defcall(input)
198
+
user = step create_user(input)
199
+
step notify(user)
200
+
user
201
+
end
202
+
203
+
# ...
204
+
end
205
+
```
206
+
207
+
When validation succeeds, the operation receives the validated and coerced input:
208
+
209
+
```ruby
210
+
result =CreateUser.new.call(name:"Alice", email:"[email protected]", age:"25")
211
+
# => Success(user) with age coerced to integer 25
212
+
```
213
+
214
+
When validation fails, the operation returns a `Failure` tagged with `:invalid_params` and the validation errors, without executing any of the operation's steps:
215
+
216
+
```ruby
217
+
result =CreateUser.new.call(name:"", email:"invalid")
218
+
# => Failure[:invalid_params, {name: ["must be filled"]}]
219
+
```
220
+
221
+
#### Using params classes
222
+
223
+
You can also pass a pre-defined params class to `params` instead of a block, which is useful for reusing validation rules across multiple operations:
For more complex validation scenarios, use the `contract` method which provides access to the full dry-validation contract API, including custom rules:
262
+
263
+
```ruby
264
+
classCreateUser < Dry::Operation
265
+
includeDry::Operation::Extensions::Params
266
+
267
+
contract do
268
+
params do
269
+
required(:name).filled(:string)
270
+
required(:age).filled(:integer)
271
+
end
272
+
273
+
rule(:age) do
274
+
key.failure("must be 18 or older") if value <18
275
+
end
276
+
end
277
+
278
+
defcall(input)
279
+
# ...
280
+
end
281
+
end
282
+
```
283
+
284
+
#### Custom wrapped methods
285
+
286
+
The `params` extension works seamlessly with custom wrapped methods when using `.operate_on`:
287
+
288
+
```ruby
289
+
classProcessData < Dry::Operation
290
+
includeDry::Operation::Extensions::Params
291
+
292
+
operate_on :process, :transform
293
+
294
+
params do
295
+
required(:value).filled(:string)
296
+
end
297
+
298
+
defprocess(input)
299
+
input[:value].upcase
300
+
end
301
+
302
+
deftransform(input)
303
+
input[:value].downcase
304
+
end
305
+
end
306
+
```
307
+
308
+
#### Inheritance
309
+
310
+
Params classes are inherited by subclasses, allowing you to build operation hierarchies with shared validation rules.
0 commit comments