Operators
Operators implement named operations that are not part of a resource's CRUD lifecycle. They are useful for state transitions, data processing, imports, notifications, and workflows involving more than one model.
module MyEngine
class TicketOperator
def initialize(ticket:, actor:)
@ticket = ticket
@actor = actor
end
def close!
Ticket.transaction do
ticket.update!(status: :closed)
ticket.record_activity!(
actor: actor,
code: :ticket_closed
)
end
ticket
end
def reopen!
Ticket.transaction do
ticket.update!(status: :open)
ticket.record_activity!(
actor: actor,
code: :ticket_reopened
)
end
ticket
end
private
attr_reader :actor, :ticket
end
end
Operators live under app/operators:
app/operators/my_engine/ticket_operator.rb
Public Method Names
Use explicit operation names instead of a generic call or operate method when one operator provides several actions:
operator.close!
operator.reopen!
operator.assign!(owner: user)
operator.notify_owner!
Use ! for operations that raise when they cannot complete, following the convention used by Active Record persistence methods. Predicates should describe the decision they answer:
operator.closable?
operator.assignable_to?(user)
validate is appropriate when the class and input make the operation clear, for example UserOperator#validate for a dataset of users. Use a more specific name such as validate_closure! when the operator has several validation workflows. Multiple explicit methods can share one operator; a generic call or operate entry point is not required.
Construction
Pass the already scoped resource and the dependencies required by the operation:
TicketOperator.new(
ticket: ticket,
actor: current_user
)
When a controller needs a resource, resolve it through the account-scoped resource service. Passing a record instead of an unscoped ID prevents the operator from duplicating tenant resolution.
Operators do not inherit from Lesli::ApplicationLesliService. The service base provides CRUD state such as query, resource, errors, and successful?; those concepts are not part of an operator's contract. Keep an operator as a plain Ruby object until repeated behavior demonstrates the need for a smaller shared abstraction. Services and operators are both application objects, but their responsibilities differ; sharing a purpose does not require sharing a superclass.
Validating a Dataset
An operator can validate input before a later import without persisting it. This example reuses the model's validations and returns errors by row:
module MyEngine
class UserOperator
def initialize(account:)
@account = account
end
def validate(rows)
rows.each_with_index.filter_map do |attributes, index|
user = @account.users.new(attributes)
next if user.valid?
{ row: index + 1, errors: user.errors.full_messages }
end
end
end
end
errors = MyEngine::UserOperator.new(account: current_user.account).validate(rows)
Here rows is an array of permitted attribute hashes, and account is a Core account. An empty array means no validation errors were found. This performs model validation only; database constraints still apply when records are persisted. Do not put this batch operation in UserService or in a controller.
UserOperator.validate(rows) is also a valid Ruby API if the operation is implemented as a stateless class method. Prefer an instance when it needs an account, actor, or collaborators, as above. Keep the chosen API explicit and consistent; no dispatcher or method registry is needed.
Operators define their own clear return value and expected failures. They do not automatically provide result, successful?, or the service response contract. Let unexpected errors propagate; handle expected failures at the calling service or controller boundary.
Using an Operator from a Service
A service can invoke an operator when a CRUD operation requires additional domain work. The service owns the transaction because it coordinates the full deletion workflow:
def destroy
Ticket.transaction do
operator.cancel_pending_tasks!
operator.remove_from_calendar!
resource.destroy!
end
self
rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotDestroyed => exception
error(exception.record.errors.full_messages.to_sentence)
self
end
private
def operator
@operator ||= TicketOperator.new(
ticket: resource,
actor: current_user
)
end
Use destroy! for Lesli models that support soft deletion. It follows the model lifecycle and sets deleted_at; it must not be used as a substitute for a business action such as closing the ticket.
Using an Operator from a Controller
A custom, non-CRUD route may resolve the resource through its service and then invoke the operator directly:
def close
service = TicketService.new(current_user, query).find(id: params[:id])
return respond_with_not_found unless service.found?
ticket = TicketOperator.new(
ticket: service.result,
actor: current_user
).close!
respond_with_lesli(
turbo: stream_notification_success("Ticket closed"),
json: ticket
)
end
The controller owns the HTTP response, while the operator owns the complete close transaction.
When to Split an Operator
Begin with one operator per resource. Extract a separate operator only when:
- One operation becomes a substantial independent workflow.
- It requires collaborators unrelated to the other resource operations.
- The class is difficult to understand because it has too many responsibilities.
For example, close!, reopen!, and assign! can remain in TicketOperator, while a complex import can become TicketImportOperator.
Last Update: 2026/11/16