Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/trailblazer/trailblazer-macro


https://github.com/trailblazer/trailblazer-macro

Last synced: 5 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Trailblazer Macro

All common Macro's for Trailblazer::Operation, will come here



## TODO

Describe the following Macros:

- Nested

- Rescue

- Wrap



## Table of Contents

- [Model Macro](#model-macro)

- [Policy Macro](#policy-macro)

  * [Policy::Pundit - Macro](#policy--pundit---macro)

    + [Policy::Pundit - API](#policy--pundit---api)

    + [Policy::Pundit - Name](#policy--pundit---name)

    + [Policy::Pundit - Dependency Injection](#policy--pundit---dependency-injection)

  * [Policy::Guard - Macro](#policy--guard---macro)

    + [Policy::Guard - API](#policy--guard---api)

    + [Policy::Guard - Callable](#policy--guard---callable)

    + [Policy::Guard - Instance Method](#policy--guard---instance-method)

    + [Policy::Guard - Name](#policy--guard---name)

    + [Policy::Guard - Dependency Injection](#policy--guard---dependency-injection)

    + [Policy::Guard - Position](#policy--guard---position)



## Model Macro

Trailblazer also has a convenient Macro to handle model creation and basic finding by id. The Model macro literally does what our model! step did.



```ruby

class Song::Create < Trailblazer::Operation

  step Policy::Guard( :authorize! )

  step Model( Song, :new )

end

```



Note that Model is not designed for complex query logic - should you need that, you might want to use [Trailblazer Finder][trailblazer_finder_link] or simply write your own customized step.



Due to a lot of requests, we have adjusted the `:find_by` method so you can specify a key to find by.

```ruby

class Song::Create < Trailblazer::Operation

  step Policy::Guard( :authorize! )

  step Model( Song, :find_by, :title )

end

```

Not specifying the third parameter in the Model Macro for `:find_by`, will result in defaulting it back to `:id`.



[trailblazer-finder-link]: https://github.com/trailblazer/trailblazer-finder/



## Policy Macro

An optional Policy Macro for Trailblazer Operations that blocks unauthorized users from running the operation.



You can abort running an operation using a policy. "Pundit-style" policy classes define the rules.

```ruby

class Comment::Policy

  def initialize(user, comment)

    @user, @comment = user, comment

  end



  def create?

    @user.admin?

  end

end

```



The rule is enabled via the ::policy call.

```ruby

class Comment::Create < Trailblazer::Operation

  step Policy( Comment::Policy, :create? )

end

```



The policy is evaluated in #setup!, raises an exception if false and suppresses running #process.



### Policy::Pundit - Macro

The Policy::Pundit Macro allows using Pundit-compatible policy classes in an operation.



A Pundit policy has various rule methods and a special constructor that receives the current user and the current model.

```ruby

class MyPolicy

  def initialize(user, model)

    @user, @model = user, model

  end



  def create?

    @user == Module && @model.id.nil?

  end



  def new?

    @user == Class

  end

end

```



In pundit policies, it is a convention to have access to those objects at runtime and build rules on top of those.



You can plug this policy into your pipe at any point. However, this must be inserted after the "model" skill is available.

```ruby

class Create < Trailblazer::Operation

  step Model( Song, :new )

  step Policy::Pundit( MyPolicy, :create? )

  # ...

end

```



Note that you don’t have to create the model via the Model macro - you can use any logic you want. The Pundit macro will grab the model from ["model"], though.



This policy will only pass when the operation is invoked as follows.

```ruby

Create.( {}, "current_user" => User.find(1) )

```



Any other call will cause a policy breach and stop the pipe from executing after the Policy::Pundit step.



#### Policy::Pundit - API

Add your polices using the Policy::Pundit macro. It accepts the policy class name, and the rule method to call.

```ruby

class Create < Trailblazer::Operation

  step Model( Song, :new )

  step Policy::Pundit( MyPolicy, :create? )

  # ...

end

```



The step will create the policy instance automatically for you and passes the "model" and the "current_user" skill into the policies constructor. Just make sure those dependencies are available before the step is executed.



If the policy returns falsey, it deviates to the left track.



After running the Pundit step, its result is readable from the Result object.

```ruby

result = Create.({}, "current_user" => Module)

result["result.policy.default"].success? #=> true

result["result.policy.default"]["policy"] #=> #

```



Note that the actual policy instance is available via ["result.policy.#{name}"]["policy"] to be reinvoked with other rules (e.g. in the view layer).



#### Policy::Pundit - Name

You can add any number of Pundit policies to your pipe. Make sure to use name: to name them, though.

```ruby

class Create < Trailblazer::Operation

  step Model( Song, :new )

  step Policy::Pundit( MyPolicy, :create?, name: "after_model" )

  # ...

end

```



The result will be stored in "result.policy.#{name}"

```ruby

result = Create.({}, "current_user" => Module)

result["result.policy.after_model"].success? #=> true

```



#### Policy::Pundit - Dependency Injection

Override a configured policy using dependency injection.

```ruby

Create.({},

  "current_user"        => Module,

  "policy.default.eval" => Trailblazer::Operation::Policy::Pundit.build(AnotherPolicy, :create?)

)

```

You can inject it using "policy.#{name}.eval". It can be any object responding to call.



### Policy::Guard - Macro

A guard is a step that helps you evaluating a condition and writing the result. If the condition was evaluated as falsey, the pipe won’t be further processed and a policy breach is reported in Result["result.policy.default"].



```ruby

class Create < Trailblazer::Operation

  step Policy::Guard( ->(options, params:, **) { params[:pass] } )

  step :process



  def process(*)

    self["x"] = true

  end

end

```



The only way to make the above operation invoke the second step :process is as follows.

```ruby

result = Create.({ pass: true })

result["x"] #=> true

```



Any other input will result in an abortion of the pipe after the guard.

```ruby

result = Create.()

result["x"] #=> nil

result["result.policy.default"].success? #=> false

```



#### Policy::Guard - API

The Policy::Guard macro helps you inserting your guard logic. If not defined, it will be evaluated where you insert it.

```ruby

class Create < Trailblazer::Operation

  step Policy::Guard( ->(options, params:, **) { params[:pass] } )

  # ...

end

```

The options object is passed into the guard and allows you to read and inspect data like params or current_user. Please use kw args.



#### Policy::Guard - Callable

As always, the guard can also be a Callable-marked object.

```ruby

class MyGuard

  include Uber::Callable



  def call(options, params:, **)

    params[:pass]

  end

end

```



Insert the object instance via the Policy::Guard macro.

```ruby

class Create < Trailblazer::Operation

  step Policy::Guard( MyGuard.new )

  # ...

end

```



#### Policy::Guard - Instance Method

As always, you may also use an instance method to implement a guard.

```ruby

class Create < Trailblazer::Operation

  step Policy::Guard( :pass? )



  def pass?(options, params:, **)

    params[:pass]

  end

  # ...

end

```



#### Policy::Guard - Name

The guard name defaults to default and can be set via name:. This allows having multiple guards.

```ruby

class Create < Trailblazer::Operation

  step Policy::Guard( ->(options, current_user:, **) { current_user }, name: :user )

  # ...

end

```



The result will sit in result.policy.#{name}.

```ruby

result = Create.({}, "current_user" => true)

result["result.policy.user"].success? #=> true

```



#### Policy::Guard - Dependency Injection

Instead of using the configured guard, you can inject any callable object that returns a Result object. Do so by overriding the policy.#{name}.eval path when calling the operation.

```ruby

Create.({},

  "current_user"        => Module,

  "policy.default.eval" => Trailblazer::Operation::Policy::Guard.build(->(options) { false })

)

```

An easy way to let Trailblazer build a compatible object for you is using Guard.build.



This is helpful to override a certain policy for testing, or to invoke it with special rights, e.g. for an admin.



#### Policy::Guard - Position

You may specify a position.

```ruby

class Create < Trailblazer::Operation

  step :model!

  step Policy::Guard( :authorize! ), before: :model!

end

```



Resulting in the guard inserted before model!, even though it was added at a later point.

```ruby

puts Create["pipetree"].inspect(style: :rows) #=>

 # 0 ========================>operation.new

 # 1 ==================>policy.default.eval

 # 2 ===============================>model!

```

This is helpful if you maintain modules for operations with generic steps.