mu-action 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +48 -0
- data/README.md +307 -32
- data/lib/mu/action/context.rb +36 -0
- data/lib/mu/action/failure_error.rb +30 -0
- data/lib/mu/action/failures.rb +149 -0
- data/lib/mu/action/hooks.rb +157 -0
- data/lib/mu/action/metadata.rb +123 -0
- data/lib/mu/action/result.rb +38 -0
- data/lib/mu/action/version.rb +1 -1
- data/lib/mu/action.rb +92 -351
- metadata +10 -5
- data/sig/mu/action.rbs +0 -159
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 981390b1d576ff6abd5018a1d2e110fbdea7ad13fcf4c3d6bb37050510cdd2a5
|
|
4
|
+
data.tar.gz: 206acaac3c6e02f3af8677adfc9363c26042f07a208f2ce2d07ff5398e516776
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 789112014861aa15bf4e2ff88b92aeceec577b458766fe5fc4b3e4a99da80e3769a783e79e5b8894caa9e9e23be272b4ad5e77b54cc4588d9032312789f59bfd
|
|
7
|
+
data.tar.gz: 51c1e5d164ef6a5f5296cc3e4f22371295cb0860ac5e3f427af7303714c93942659b07fadeb26099edc311b6a916f3b09817e56bcda0ed69f834714b6629ccdc
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,53 @@
|
|
|
1
1
|
## [Unreleased]
|
|
2
2
|
|
|
3
|
+
## [0.4.0] - 2026-11-16
|
|
4
|
+
|
|
5
|
+
### Breaking
|
|
6
|
+
- `call` must return the `Success(...)` it built, or call `Failure(...)`; so must an around hook, which can also return the result of the chain. Anything else raises a `TypeError`. A raw value used to be returned as the result, without the `result` type being checked, and the last expression of an around hook replaced the result. To use another action's value, write `Success(Other.call!(...))`.
|
|
7
|
+
- A `Failure` of another action returned from `call` becomes the failure of the action, as with `call!`: around hooks see an exception, `after` hooks are skipped and the declared failures are checked. It used to be returned as it was.
|
|
8
|
+
- The context is inherited by an action called directly by a running action, and no longer by a thread or a fiber started by it: pass `context:` explicitly to an action that runs in another thread or fiber. In 0.3.0 a long-lived thread first started inside an action, such as a thread pool worker, kept that action's context for all the work it did later.
|
|
9
|
+
- Declaring a prop named `meta` or `context` raises an `ArgumentError`. In 0.3.0 such a prop was silently replaced the first time the action was instantiated.
|
|
10
|
+
- `record_props` raises an `ArgumentError` when its first argument is not `true` or `false`, and an action raises one when it is called if `record_props` names something that is not one of its props. `record_props :email` used to record every prop, and a misspelled name in `except:` left the prop recorded.
|
|
11
|
+
- An around block that takes one parameter receives the chain, as an around method does. It used to receive the action. An around block that takes no parameter raises an `ArgumentError`, since it could not call the chain.
|
|
12
|
+
- `failure :code, from: OtherAction` declares a detail named `from`; it no longer also takes the failures of `OtherAction`. Write `failure from: OtherAction` on its own.
|
|
13
|
+
- Results are immutable. `Success` and `Failure` are frozen and have no writer: `result.value = …`, `result.meta = …`, `result.error = …`, `result.details = …` and `result[:value] = …` no longer exist, nor does the hash-style reader `result[:value]`. The contents of `meta` and `details` can still change.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
- The message of the `FailureError` raised by `call!` or `run!` names the action and the keys of the details, as in `CreateUser failed: invalid (details: errors)`. It was the error alone. The values of the details are not shown.
|
|
17
|
+
- An action class gets twelve class methods and no other: `call`, `call!`, `result`, `before`, `after`, `around`, `before_hooks`, `after_hooks`, `around_hooks`, `failure`, `failures` and `record_props`. The README documents them. The undocumented `own_failures`, `failure_sources`, `failure_lineage`, `declares_failures?` and `props_recording` are gone, and a class method of an action with one of those names, or named `register_hook`, no longer replaces part of the library.
|
|
18
|
+
- `before`, `after`, `around`, `failure` and `record_props` return `nil`. They returned internal lists.
|
|
19
|
+
- `before_hooks`, `after_hooks` and `around_hooks` return a new list each time, for inspection: changing it does not change the hooks that run.
|
|
20
|
+
- Hooks, failure checks and metadata recording no longer add methods to an action. An action gets seven methods from `Mu::Action` (`meta`, `context`, `Success`, `Failure`, `run`, `run!` and the private `initialize_meta`); the README documents them, and each can be overridden with `super`. A method of an action named `with_hooks`, `check_failure` or `resolve_method`, for example, no longer replaces part of the library.
|
|
21
|
+
- A subclass follows its parent class. A hook, a declared failure or a `record_props` choice added to a class after one of its subclasses was defined now applies to that subclass; each used to be copied when the subclass was defined. A parent's hooks always run before those of its subclasses.
|
|
22
|
+
- Literal 1.9 or later is required; 1.7 and 1.8 are no longer supported. CI only tested 1.9, and on 1.7 a prop default could not read `context`.
|
|
23
|
+
- The `meta` and `context` props are declared when `Mu::Action` is included, before the action's own props. They were added the first time the class was instantiated.
|
|
24
|
+
- The library is split into one file per feature under `lib/mu/action/`. The internal modules `Initializer`, `MetaPropAdder`, `HookPropagator` and `FailureChecking` are replaced by `Context`, `Metadata`, `Hooks` and `Failures`. Like every constant of `Mu::Action`, these names come before top-level constants inside action classes; the README lists them.
|
|
25
|
+
- The README documents the order in which hooks run, and that after hooks only run when the action succeeds.
|
|
26
|
+
- The README warns that a broad `rescue` in `call` catches the error `Failure` raises, and shows how to let it through.
|
|
27
|
+
- The README's section on result types is rewritten as "Typed Results": a domain object as the result, the error a wrong type raises, and results that may be `nil`.
|
|
28
|
+
- The specs run in random order, and `bin/ci` and CI ignore focused examples.
|
|
29
|
+
- `bin/test_readme_examples` reports a failing example with its line in the README and the code of its block, and `bin/console` loads the classes of the README examples.
|
|
30
|
+
- `bin/check` is renamed `bin/ci`. It runs the checks on every supported Ruby version, using asdf, and `bin/ci --current` runs them on the current Ruby only.
|
|
31
|
+
- Development dependencies updated, including json 3, prism 2, erb 6 and rdoc 8. Steep and RBS stay at 2.0 and 4.1, the last versions that support Ruby 3.2.
|
|
32
|
+
- Development now follows agent skills in `.agents/skills` (commits, pull requests, changelog, dependencies, releases, reviews), and `AGENTS.md` is the single guide; `CLAUDE.md` points to it.
|
|
33
|
+
|
|
34
|
+
### Removed
|
|
35
|
+
- The RBS signatures are no longer shipped in the gem. An application could not load them: they refer to Literal declarations that exist nowhere, and they did not describe the class methods of an action. They stay in the repository for the library's own type check.
|
|
36
|
+
- Guard, its RSpec and RuboCop plugins, and the local Steep plugin (`lib/guard/steep.rb`) from the development tooling.
|
|
37
|
+
|
|
38
|
+
### Fixed
|
|
39
|
+
- `run!` on an action called from another one is treated as `call!` is: the failure is checked against the failures the outer action declares and kept in `meta[:cause]`. It used to become the outer action's failure unchecked. `run!` now goes through `run`, and raises a `FailureError` that carries the `Failure`.
|
|
40
|
+
- A failure detail can be named `from`, as in `failure :invalid_transition, from: Symbol, to: Symbol`. It was taken as a `from:` action, and the first such failure raised `NoMethodError`.
|
|
41
|
+
- `failure from:` raises an `ArgumentError` for anything that is not an action class, and actions that name each other in `from:` no longer overflow the stack.
|
|
42
|
+
- A top-level `Configuration` constant is no longer hidden inside action classes: the `Mu::Action::Configuration` module is gone.
|
|
43
|
+
- A prop default can read `context`. It used to get `nil` or the context depending on the order in which the classes were defined and called.
|
|
44
|
+
- The metadata of an action is initialized once. It was initialized twice for a class that includes `Mu::Action` directly.
|
|
45
|
+
- `record_props` accepts prop names given as strings. They were ignored, so `record_props except: %w[password]` recorded the password.
|
|
46
|
+
- A subclass with no props of its own runs its parent's `initialize`.
|
|
47
|
+
- A `meta:` hash passed by a caller is no longer modified by an `after_initialize` method.
|
|
48
|
+
- `around { |chain| chain.call }` no longer skips the around hooks declared after it. The block received the action, so `chain.call` ran the action directly.
|
|
49
|
+
- Around hooks accept lambdas that take one parameter, and methods with keyword parameters.
|
|
50
|
+
|
|
3
51
|
## [0.3.0] - 2026-11-14
|
|
4
52
|
|
|
5
53
|
### Breaking
|
data/README.md
CHANGED
|
@@ -66,6 +66,31 @@ A `Success` result contains the `value` returned by the interactor, while a `Fai
|
|
|
66
66
|
|
|
67
67
|
A failure will return immediately.
|
|
68
68
|
|
|
69
|
+
A result is immutable: it is frozen and has no writer, so a `Success` cannot be turned into another one after the fact. The `meta` and `details` hashes it holds are not frozen.
|
|
70
|
+
|
|
71
|
+
`call` must return the `Success(...)` it built, or call `Failure(...)`. Anything else raises a `TypeError`, so a branch that forgets its `Success` cannot pass for a result:
|
|
72
|
+
|
|
73
|
+
```ruby
|
|
74
|
+
class Forgetful
|
|
75
|
+
include Mu::Action
|
|
76
|
+
|
|
77
|
+
def call = 42
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
error =
|
|
81
|
+
begin
|
|
82
|
+
Forgetful.call
|
|
83
|
+
rescue TypeError => e
|
|
84
|
+
e
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
assert error.message.include?("call returned 42. It must return Success(...), or call Failure(...)")
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
To use the value of another interactor, wrap it: `Success(Other.call!(...))`. Returning the `Failure` of another interactor works like `call!`: it becomes the failure of this one.
|
|
91
|
+
|
|
92
|
+
Inside an action class, the constants of `Mu::Action` come before top-level constants with the same name: `Result`, `Success`, `Failure`, `FailureError`, `Context`, `Metadata`, `Hooks`, `Failures`, `ClassMethods`, `VERSION` and `CONTEXT_KEY`. If your application has its own `Result` or `Context` class, for example, write `::Result` or `::Context` inside an action.
|
|
93
|
+
|
|
69
94
|
### Calling Interactors
|
|
70
95
|
|
|
71
96
|
Interactors can be called in two ways:
|
|
@@ -81,12 +106,27 @@ in Mu::Action::Failure(error:)
|
|
|
81
106
|
puts "Failed: #{error}"
|
|
82
107
|
end
|
|
83
108
|
|
|
84
|
-
# Returns the value on success, raises
|
|
109
|
+
# Returns the value on success, raises a Mu::Action::FailureError on failure
|
|
85
110
|
user = CreateUser.call!(email: "jane@example.com", name: "Jane")
|
|
86
111
|
assert user.name == "Jane"
|
|
87
112
|
assert user.email == "jane@example.com"
|
|
88
113
|
```
|
|
89
114
|
|
|
115
|
+
The error raised by `call!` has the `error` and the `details` of the failure, and the `Failure` itself as `failure`. Its message names the interactor, the error and the keys of the details. The values of the details are left out, as they may not belong in a log.
|
|
116
|
+
|
|
117
|
+
```ruby
|
|
118
|
+
error =
|
|
119
|
+
begin
|
|
120
|
+
CreateUser.call!(email: "existing@example.com", name: "Jane")
|
|
121
|
+
rescue Mu::Action::FailureError => e
|
|
122
|
+
e
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
assert error.error == :user_exists
|
|
126
|
+
assert error.failure.meta[:class] == CreateUser
|
|
127
|
+
assert error.message == "CreateUser failed: user_exists"
|
|
128
|
+
```
|
|
129
|
+
|
|
90
130
|
### Hooks
|
|
91
131
|
|
|
92
132
|
Add cross-cutting concerns with before, after, and around hooks:
|
|
@@ -157,47 +197,114 @@ class ProcessPayment
|
|
|
157
197
|
end
|
|
158
198
|
```
|
|
159
199
|
|
|
160
|
-
|
|
200
|
+
An around hook takes the chain, or the action and the chain, whether it is a block or a method: `around { |chain| ... }` works like `def wrap_in_transaction(chain)`, and a method can take `(action, chain)` like the block above. A method can also take no argument and use `yield`.
|
|
161
201
|
|
|
162
|
-
|
|
202
|
+
An around hook returns the result of the chain. It can also return its own `Success(...)`, to replace the result or to skip the call; anything else raises a `TypeError`.
|
|
163
203
|
|
|
164
|
-
|
|
204
|
+
Hooks run in this order: the before hooks, then the around hooks wrapped around `call`, then the after hooks. Hooks of one kind run in the order they were declared, and the first around hook declared is the outermost.
|
|
165
205
|
|
|
166
206
|
```ruby
|
|
167
|
-
class
|
|
207
|
+
class Traced
|
|
168
208
|
include Mu::Action
|
|
169
209
|
|
|
170
|
-
|
|
210
|
+
STEPS = []
|
|
211
|
+
|
|
212
|
+
before { STEPS << :before }
|
|
213
|
+
around { |chain| STEPS << :around_start; chain.call.tap { STEPS << :around_end } }
|
|
214
|
+
after { STEPS << :after }
|
|
215
|
+
|
|
216
|
+
def call = Success(STEPS << :call)
|
|
217
|
+
end
|
|
218
|
+
|
|
219
|
+
Traced.call
|
|
220
|
+
assert Traced::STEPS == %i[before around_start call around_end after]
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
The before and after hooks run outside the around hooks: a transaction opened by an around hook covers `call`, not what the before and after hooks do.
|
|
224
|
+
|
|
225
|
+
When the interactor fails or raises, in a before hook, in `call` or in an around hook, everything that would follow is skipped. In particular, the after hooks only run when the interactor succeeds.
|
|
226
|
+
|
|
227
|
+
### Typed Results
|
|
228
|
+
|
|
229
|
+
`result` declares the type of the value an interactor returns. `Success` then only accepts a value of that type:
|
|
230
|
+
|
|
231
|
+
```ruby
|
|
232
|
+
Quote = Data.define(:amount, :currency)
|
|
233
|
+
|
|
234
|
+
class PriceQuote
|
|
235
|
+
include Mu::Action
|
|
236
|
+
|
|
237
|
+
result Quote
|
|
238
|
+
|
|
239
|
+
prop :quantity, Integer
|
|
171
240
|
|
|
172
241
|
def call
|
|
173
|
-
|
|
242
|
+
Failure(:out_of_stock) if @quantity > 100
|
|
243
|
+
Success(Quote.new(amount: @quantity * 250, currency: "CAD"))
|
|
174
244
|
end
|
|
175
245
|
end
|
|
176
246
|
|
|
177
|
-
|
|
178
|
-
assert
|
|
247
|
+
quote = PriceQuote.call!(quantity: 4)
|
|
248
|
+
assert quote.amount == 1000
|
|
179
249
|
```
|
|
180
250
|
|
|
181
|
-
|
|
251
|
+
A value of another type is a bug in the interactor, not a failure. `Success` raises a `Literal::TypeError`, which `call` does not turn into a `Failure`:
|
|
182
252
|
|
|
183
253
|
```ruby
|
|
184
|
-
class
|
|
254
|
+
class Careless
|
|
185
255
|
include Mu::Action
|
|
186
256
|
|
|
187
|
-
|
|
188
|
-
prop :value, _Integer(1..6), :positional
|
|
189
|
-
end
|
|
257
|
+
result Quote
|
|
190
258
|
|
|
191
|
-
def call
|
|
192
|
-
|
|
259
|
+
def call = Success(1000)
|
|
260
|
+
end
|
|
261
|
+
|
|
262
|
+
error =
|
|
263
|
+
begin
|
|
264
|
+
Careless.call
|
|
265
|
+
rescue Literal::TypeError => e
|
|
266
|
+
e
|
|
193
267
|
end
|
|
268
|
+
|
|
269
|
+
assert error.message.include?("Expected: Quote")
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
The type can be any [Literal type](https://literal.fun/docs/built-in-types.html), such as a range of integers, or a value that may be `nil`:
|
|
273
|
+
|
|
274
|
+
```ruby
|
|
275
|
+
class RollDice
|
|
276
|
+
include Mu::Action
|
|
277
|
+
|
|
278
|
+
result _Integer(1..6)
|
|
279
|
+
|
|
280
|
+
def call = Success(rand(1..6))
|
|
194
281
|
end
|
|
195
282
|
|
|
196
|
-
|
|
197
|
-
|
|
283
|
+
class FindNickname
|
|
284
|
+
include Mu::Action
|
|
285
|
+
|
|
286
|
+
result _Nilable(String)
|
|
287
|
+
|
|
288
|
+
prop :name, String
|
|
289
|
+
|
|
290
|
+
def call = Success({ "Robert" => "Bob" }[@name])
|
|
291
|
+
end
|
|
292
|
+
|
|
293
|
+
assert (1..6).cover?(RollDice.call!)
|
|
294
|
+
assert FindNickname.call!(name: "Robert") == "Bob"
|
|
295
|
+
assert FindNickname.call!(name: "Jane").nil?
|
|
198
296
|
```
|
|
199
297
|
|
|
200
|
-
|
|
298
|
+
Without `result`, an interactor accepts any value, `nil` included.
|
|
299
|
+
|
|
300
|
+
`result` also gives the interactor its own `Success` class, so a `case` can match the success of one interactor in particular:
|
|
301
|
+
|
|
302
|
+
```ruby
|
|
303
|
+
case PriceQuote.call(quantity: 4)
|
|
304
|
+
in PriceQuote::Success(value: Quote(amount:))
|
|
305
|
+
assert amount == 1000
|
|
306
|
+
end
|
|
307
|
+
```
|
|
201
308
|
|
|
202
309
|
### Failures
|
|
203
310
|
|
|
@@ -221,6 +328,29 @@ in Mu::Action::Failure(error: :invalid, details: { errors: })
|
|
|
221
328
|
end
|
|
222
329
|
```
|
|
223
330
|
|
|
331
|
+
`Failure` stops the interactor by raising a `Mu::Action::FailureError`, which is a `StandardError`. A `rescue StandardError`, or a bare `rescue`, around it therefore catches the failure along with real errors. When `call` rescues broadly, let the failures through first:
|
|
332
|
+
|
|
333
|
+
```ruby
|
|
334
|
+
class Charge
|
|
335
|
+
include Mu::Action
|
|
336
|
+
|
|
337
|
+
prop :amount, Integer
|
|
338
|
+
|
|
339
|
+
def call
|
|
340
|
+
Failure(:invalid_amount) unless @amount.positive?
|
|
341
|
+
Success(@amount)
|
|
342
|
+
rescue Mu::Action::FailureError
|
|
343
|
+
raise
|
|
344
|
+
rescue StandardError => e
|
|
345
|
+
Failure(:charge_failed, message: e.message)
|
|
346
|
+
end
|
|
347
|
+
end
|
|
348
|
+
|
|
349
|
+
assert Charge.call(amount: 0).error == :invalid_amount
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
Without the first `rescue`, this interactor would fail with `:charge_failed` in both cases.
|
|
353
|
+
|
|
224
354
|
An interactor can declare the failures it returns, with the types of their details. Once it declares any, an undeclared failure or a detail of the wrong type raises an `ArgumentError`. Interactors without declarations accept any failure.
|
|
225
355
|
|
|
226
356
|
```ruby
|
|
@@ -274,6 +404,8 @@ assert result.meta[:cause].meta[:class] == PublishArticle
|
|
|
274
404
|
|
|
275
405
|
Because the inner failure is raised as an exception, around hooks such as transactions see it and can roll back.
|
|
276
406
|
|
|
407
|
+
`failure from:` takes one interactor class or several, and goes on its own line. With an error code, every keyword is a detail, including one named `from`: `failure :invalid_transition, from: Symbol, to: Symbol`.
|
|
408
|
+
|
|
277
409
|
### Metadata Tracking
|
|
278
410
|
|
|
279
411
|
Every interactor automatically tracks metadata including class information and property values:
|
|
@@ -304,6 +436,105 @@ end
|
|
|
304
436
|
assert SignIn.call(email: "jane@example.com", password: "secret").meta[:props] == { email: "jane@example.com" }
|
|
305
437
|
```
|
|
306
438
|
|
|
439
|
+
A subclass inherits the choice. Every name must be a prop of the interactor: one that is not raises an `ArgumentError` when the interactor is called, so a misspelled name cannot leave a secret recorded.
|
|
440
|
+
|
|
441
|
+
### The Methods of an Interactor
|
|
442
|
+
|
|
443
|
+
Including `Mu::Action` gives an interactor these methods and no other. Hooks, failure checks and metadata recording run from outside it, so every other method name is yours.
|
|
444
|
+
|
|
445
|
+
- `call`: yours to implement. It returns `Success(...)` or calls `Failure(...)`.
|
|
446
|
+
- `Success(value = nil)`: builds the result of the interactor.
|
|
447
|
+
- `Failure(error, **details)`: checks the failure against the declared ones, then raises, so that nothing after it runs.
|
|
448
|
+
- `meta`: the metadata hash, which the result carries.
|
|
449
|
+
- `context`: what the caller passed as `context:`, or the context of the calling interactor.
|
|
450
|
+
- `run`: runs the interactor and returns its result, a `Success` or a `Failure`. It sets the context and runs the hooks around `call`. `MyAction.call(...)` is `MyAction.new(...).run`.
|
|
451
|
+
- `run!`: calls `run` and returns its `Success`, or raises a `Mu::Action::FailureError` that carries the `Failure`. `MyAction.call!(...)` is `MyAction.new(...).run!.value`.
|
|
452
|
+
- `initialize_meta` (private): fills in `meta` when the interactor is built.
|
|
453
|
+
|
|
454
|
+
Each of them can be overridden, with `super` for the original behavior:
|
|
455
|
+
|
|
456
|
+
```ruby
|
|
457
|
+
class Import
|
|
458
|
+
include Mu::Action
|
|
459
|
+
|
|
460
|
+
prop :rows, Integer
|
|
461
|
+
|
|
462
|
+
# A default context, when the caller gives none.
|
|
463
|
+
def context = super || { actor: "system" }
|
|
464
|
+
|
|
465
|
+
# A detail added to every failure.
|
|
466
|
+
def Failure(error, **details) = super(error, **details, rows: @rows)
|
|
467
|
+
|
|
468
|
+
def call
|
|
469
|
+
Failure(:empty) if @rows.zero?
|
|
470
|
+
Success(@rows)
|
|
471
|
+
end
|
|
472
|
+
|
|
473
|
+
private
|
|
474
|
+
|
|
475
|
+
# Something else than the props in the metadata.
|
|
476
|
+
def initialize_meta
|
|
477
|
+
super
|
|
478
|
+
meta[:props] = { rows: "#{@rows} rows" }
|
|
479
|
+
end
|
|
480
|
+
end
|
|
481
|
+
|
|
482
|
+
result = Import.call(rows: 0)
|
|
483
|
+
|
|
484
|
+
assert result.details == { rows: 0 }
|
|
485
|
+
assert result.meta[:context] == { actor: "system" }
|
|
486
|
+
assert result.meta[:props] == { rows: "0 rows" }
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
Two rules apply to an override. `meta` must return the same hash on every call, because hooks write to it and the result shares it. `Success` must return what `super` built, because `call` has to return the result of its own interactor.
|
|
490
|
+
|
|
491
|
+
The class of an interactor gets these methods, and no other:
|
|
492
|
+
|
|
493
|
+
- `call(...)` and `call!(...)`: build the interactor and run it.
|
|
494
|
+
- `result(type)`: the type of the value of its `Success`.
|
|
495
|
+
- `before`, `after`, `around`: register hooks.
|
|
496
|
+
- `before_hooks`, `after_hooks`, `around_hooks`: list the hooks of the class, those of its parent class first. Each hook is a block or the name of a method. These lists are for inspection: changing what they return does not change the hooks that run.
|
|
497
|
+
- `failure`: declares failures.
|
|
498
|
+
- `failures`: the declared failures, with the types of their details.
|
|
499
|
+
- `record_props`: chooses the props recorded in the metadata.
|
|
500
|
+
|
|
501
|
+
```ruby
|
|
502
|
+
class Audited
|
|
503
|
+
include Mu::Action
|
|
504
|
+
|
|
505
|
+
before :check_access
|
|
506
|
+
after { meta[:audited] = true }
|
|
507
|
+
|
|
508
|
+
def call = Success(:done)
|
|
509
|
+
|
|
510
|
+
private
|
|
511
|
+
|
|
512
|
+
def check_access = nil
|
|
513
|
+
end
|
|
514
|
+
|
|
515
|
+
assert Audited.before_hooks == [:check_access]
|
|
516
|
+
assert Audited.after_hooks.size == 1
|
|
517
|
+
assert Audited.around_hooks.empty?
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
### Subclasses
|
|
521
|
+
|
|
522
|
+
A subclass has the hooks of its parent class, followed by its own. It also has its parent's declared failures, and its `record_props` choice unless it makes its own. These follow the parent: a hook added to a parent class applies to its subclasses whenever it is added.
|
|
523
|
+
|
|
524
|
+
```ruby
|
|
525
|
+
class ApplicationAction
|
|
526
|
+
include Mu::Action
|
|
527
|
+
end
|
|
528
|
+
|
|
529
|
+
class Publish < ApplicationAction
|
|
530
|
+
def call = Success(meta[:checked])
|
|
531
|
+
end
|
|
532
|
+
|
|
533
|
+
ApplicationAction.before { meta[:checked] = true }
|
|
534
|
+
|
|
535
|
+
assert Publish.call! == true
|
|
536
|
+
```
|
|
537
|
+
|
|
307
538
|
### Context
|
|
308
539
|
|
|
309
540
|
Information about who is calling and from where, such as the actor, the account or the channel, goes in `context` rather than in props. It's available in hooks and in `call`, and it's recorded in `meta[:context]`. It can be any object.
|
|
@@ -327,10 +558,49 @@ assert result.meta[:archived_by] == "jane"
|
|
|
327
558
|
|
|
328
559
|
Interactors called by another one inherit its context, so a hook in a nested interactor sees the same actor. Pass `context:` explicitly to override it.
|
|
329
560
|
|
|
561
|
+
The context follows the call stack: an interactor inherits it when it is called directly by an interactor that is running. A thread or a fiber started by an interactor does not inherit it, so hand it over explicitly:
|
|
562
|
+
|
|
563
|
+
```ruby
|
|
564
|
+
class WhoIsActing
|
|
565
|
+
include Mu::Action
|
|
566
|
+
|
|
567
|
+
def call = Success(context && context[:actor])
|
|
568
|
+
end
|
|
569
|
+
|
|
570
|
+
class ActInBackground
|
|
571
|
+
include Mu::Action
|
|
572
|
+
|
|
573
|
+
def call
|
|
574
|
+
inherited = Thread.new { WhoIsActing.call! }.value
|
|
575
|
+
handed_over = Thread.new { WhoIsActing.call!(context:) }.value
|
|
576
|
+
Success([inherited, handed_over])
|
|
577
|
+
end
|
|
578
|
+
end
|
|
579
|
+
|
|
580
|
+
assert ActInBackground.call!(context: { actor: "jane" }) == [nil, "jane"]
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
`context` and `meta` are reserved prop names: declaring a prop with one of them raises an `ArgumentError`. The context is set before the other props, so a prop default can read it:
|
|
584
|
+
|
|
585
|
+
```ruby
|
|
586
|
+
class Greet
|
|
587
|
+
include Mu::Action
|
|
588
|
+
|
|
589
|
+
prop :locale, Symbol, default: -> { context ? context[:locale] : :en }
|
|
590
|
+
|
|
591
|
+
def call = Success(@locale == :fr ? "Bonjour" : "Hello")
|
|
592
|
+
end
|
|
593
|
+
|
|
594
|
+
assert Greet.call!(context: { locale: :fr }) == "Bonjour"
|
|
595
|
+
assert Greet.call! == "Hello"
|
|
596
|
+
```
|
|
597
|
+
|
|
330
598
|
## Differences from the Interactor Gem
|
|
331
599
|
|
|
332
600
|
The main difference and the motivation for creating `Mu::Action` is to separate the context into inputs, an output, and metadata. This allows for a more structured approach to handling business logic, making it easier to reason about the flow of data and the state of the application.
|
|
333
601
|
|
|
602
|
+
Hooks are also ordered differently: in Interactor, the around hooks wrap the before and after hooks, while here the before and after hooks run outside the around hooks.
|
|
603
|
+
|
|
334
604
|
## Development
|
|
335
605
|
|
|
336
606
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run the tests with:
|
|
@@ -339,21 +609,27 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
|
|
|
339
609
|
bundle exec rspec
|
|
340
610
|
```
|
|
341
611
|
|
|
342
|
-
You can also run `bin/console` for an interactive prompt to experiment with the gem.
|
|
612
|
+
You can also run `bin/console` for an interactive prompt to experiment with the gem. The classes of the examples in this README are loaded in it.
|
|
343
613
|
|
|
344
614
|
To install this gem onto your local machine, run `bundle exec rake install`.
|
|
345
615
|
|
|
346
|
-
### Running
|
|
616
|
+
### Running the Checks
|
|
617
|
+
|
|
618
|
+
`bin/ci` runs RuboCop, RSpec, Steep and the README examples. It runs them on every supported Ruby version, switching between them with [asdf](https://asdf-vm.com), and installs missing gems from the lockfile.
|
|
347
619
|
|
|
348
620
|
```bash
|
|
349
|
-
# Run
|
|
350
|
-
|
|
621
|
+
# Run every check on each supported Ruby version
|
|
622
|
+
bin/ci
|
|
351
623
|
|
|
352
|
-
# Run
|
|
353
|
-
|
|
624
|
+
# Run every check on some Ruby versions only
|
|
625
|
+
bin/ci 3.2 4.0
|
|
626
|
+
|
|
627
|
+
# Run every check on the current Ruby only (no asdf needed)
|
|
628
|
+
bin/ci --current
|
|
354
629
|
|
|
355
|
-
# Run
|
|
356
|
-
bundle exec
|
|
630
|
+
# Run the tests or the linter alone
|
|
631
|
+
bundle exec rspec
|
|
632
|
+
bundle exec rubocop
|
|
357
633
|
```
|
|
358
634
|
|
|
359
635
|
## Contributing
|
|
@@ -365,11 +641,10 @@ When contributing:
|
|
|
365
641
|
1. Fork the repository
|
|
366
642
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
367
643
|
3. Write tests for your changes
|
|
368
|
-
4. Ensure all
|
|
369
|
-
5.
|
|
370
|
-
6.
|
|
371
|
-
7.
|
|
372
|
-
8. Create a new Pull Request
|
|
644
|
+
4. Ensure all checks pass (`bin/ci`)
|
|
645
|
+
5. Commit your changes (`git commit -am 'Add some feature'`)
|
|
646
|
+
6. Push to the branch (`git push origin my-new-feature`)
|
|
647
|
+
7. Create a new Pull Request
|
|
373
648
|
|
|
374
649
|
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/budu/mu-action/blob/main/CODE_OF_CONDUCT.md).
|
|
375
650
|
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Mu
|
|
4
|
+
module Action
|
|
5
|
+
# Fiber-local key holding the context of the running action.
|
|
6
|
+
CONTEXT_KEY = :mu_action_context
|
|
7
|
+
|
|
8
|
+
# The context of an action: what its caller says about who is calling and
|
|
9
|
+
# from where. An action called by another one inherits its context.
|
|
10
|
+
#
|
|
11
|
+
# The context of the running action is kept in a fiber-local variable, so
|
|
12
|
+
# it follows the call stack and nothing else: a thread or a fiber started
|
|
13
|
+
# by an action does not see it. Storage that new threads inherit would
|
|
14
|
+
# give a thread pool worker the context of whichever action happened to
|
|
15
|
+
# start it, for all the work it does later.
|
|
16
|
+
#
|
|
17
|
+
# @api private Applications use what this module adds to action classes,
|
|
18
|
+
# never the module itself.
|
|
19
|
+
module Context
|
|
20
|
+
def self.install(base)
|
|
21
|
+
# The context defaults to the one of the action that is running, if any.
|
|
22
|
+
base.prop :context, base._Nilable(base._Any), default: -> { Thread.current[CONTEXT_KEY] }
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
# Runs the block with the context of the action as the one that the
|
|
26
|
+
# actions it calls inherit.
|
|
27
|
+
def self.with(action)
|
|
28
|
+
previous = Thread.current[CONTEXT_KEY]
|
|
29
|
+
Thread.current[CONTEXT_KEY] = action.context
|
|
30
|
+
yield
|
|
31
|
+
ensure
|
|
32
|
+
Thread.current[CONTEXT_KEY] = previous
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
end
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Mu
|
|
4
|
+
module Action
|
|
5
|
+
# Exception class for action failures. Carries the error code and its
|
|
6
|
+
# details. When raised by +call!+ or +run!+, it also carries the Failure
|
|
7
|
+
# result, and its message names the action.
|
|
8
|
+
class FailureError < StandardError
|
|
9
|
+
attr_reader :error, :details, :failure
|
|
10
|
+
|
|
11
|
+
def initialize(error, details: {}, failure: nil)
|
|
12
|
+
@error = error
|
|
13
|
+
@details = details
|
|
14
|
+
@failure = failure
|
|
15
|
+
super(summary)
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
private
|
|
19
|
+
|
|
20
|
+
# "CreateUser failed: invalid (details: errors)". The details are named
|
|
21
|
+
# and not shown: their values may not belong in a log.
|
|
22
|
+
def summary
|
|
23
|
+
text = error.to_s
|
|
24
|
+
action = failure&.meta&.[](:class)
|
|
25
|
+
text = "#{action.name} failed: #{text}" if action.is_a?(Module) && action.name
|
|
26
|
+
details.empty? ? text : "#{text} (details: #{details.keys.join(", ")})"
|
|
27
|
+
end
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
end
|