Class: Knuckles::Pipeline

Inherits:
Object
  • Object
show all
Defined in:
lib/knuckles/pipeline.rb

Overview

The ‘Pipeline` is used to transform a collection of objects into a serialized result. A pipeline reduces a collection of objects through a set of stages, passing the result of each stage on to the next. This means that each stage can act in isolation and can compose with new custom stages. Additionally, stages are idividually instrumented for performance monitoring.

The ‘Pipeline` class provides a set of default stages but can be overridden on initialization. Note that after initialization, the stages are frozen to prevent unpredictable mutation.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(stages: default_stages) ⇒ Pipeline

Creates a new instance of ‘Knuckles::Pipeline`, optionally with custom stages.

Examples:

Create a default pipeline


Knuckles::Pipeline.new

Create a customized pipeline without any caching


Knuckles::Pipeline.new(stages: [
  Knuckles::Stages::Renderer,
  Knuckles::Stages::Combiner,
  Knuckles::Stages::Dumper
])

Parameters:

  • [Array] (Hash) —

    a customizable set of options



34
35
36
 
# File 'lib/knuckles/pipeline.rb', line 34

def initialize(stages: default_stages)
  @stages = stages.freeze
end

Instance Attribute Details

#stages ⇒ Object (readonly)

Returns the value of attribute stages.



15
16
17
 
# File 'lib/knuckles/pipeline.rb', line 15

def stages
  @stages
end

Instance Method Details

#call(objects, options) ⇒ String

Push a collection of objects through the stages of the pipeline. In normal usage this will render the objects out to a JSON structure.

Examples:

Basic pipeline rendering


pipeline = Knuckles::Pipeline.new
pipeline.call([tag_a, tag_b]) #=> '{"tags":[{"id":1},{"id":2}]}'

Parameters:

  • objects (Enumerable) —

    A collection of objects (models) to be serialized and processed.

  • options (Hash) —

    The ‘call` method doesn’t use any options itself, they are forwarded on to each stage. See the documentation for specific stages for the options they accept.

Returns:

  • (String) —

    The final result as transformed by the pipeline, typically a JSON string.



79
80
81
82
83
84
85
86
87
 
# File 'lib/knuckles/pipeline.rb', line 79

def call(objects, options)
  prepared = prepare(objects)

  stages.reduce(prepared) do |results, stage|
    instrument("knuckles.stage", stage: stage.name) do
      stage.call(results, options)
    end
  end
end

#default_stages ⇒ Object

Provides default stage modules in the intended order. These are the stages that are used if nothing is passed during initialization. The defaults are defined as a method to make overriding with a subclass easy.

Examples:

Override ‘default_stages` within a subclass


class CustomPipeline < Knuckles::Pipeline
  def default_stages
    [Knuckles::Stages::Renderer,
     Knuckles::Stages::Combiner,
     Knuckles::Stages::Dumper]
  end
end


52
53
54
55
56
57
58
59
60
 
# File 'lib/knuckles/pipeline.rb', line 52

def default_stages
  [Knuckles::Stages::Fetcher,
   Knuckles::Stages::Hydrator,
   Knuckles::Stages::Renderer,
   Knuckles::Stages::Writer,
   Knuckles::Stages::Enhancer,
   Knuckles::Stages::Combiner,
   Knuckles::Stages::Dumper]
end

#prepare(objects) ⇒ Array[Hash]

Convert a collection of objects into a collection of hashes that enclose the object. The resulting hashes are populated with the keys and default values necessary for use with the standard pipeline stages.

Examples:

Prepare a single object


pipeline.prepare([model]) #=> [{object: model, key: nil,
                                cached?: false, result: nil}]

Parameters:

  • objects (Enumerable) —

    A collection of objects to prepare

Returns:

  • (Array[Hash]) —

    An array of hashes, each with the keys ‘:object`, `:key`, `:cached?`, and `:result`.



103
104
105
106
107
 
# File 'lib/knuckles/pipeline.rb', line 103

def prepare(objects)
  objects.map do |object|
    {object: object, key: nil, cached?: false, result: nil}
  end
end