easy_flow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e3c51d7ce51a8a5b5d9f1209d8b621a21353082b1815cd3d5b567c7da7d2acc
+  data.tar.gz: 36fb74833ec6d3ee98e20c2d9fb5328a14cd160727f0854f3384fb6dee4e0559
+SHA512:
+  metadata.gz: 6c8720e19f2fa889ccaa3c2ddc8915d16951edf4620165009c5a32912d3d30199c0ec516cea28cca106028484b76cf8f648866dc30ea3c6258d1c0e36927738d
+  data.tar.gz: 5c12ab8931cd2ec76567c9ae5667849b88a64454664dd0dfb40d97ab21c583502edf3e2d9010011836c8de363eaef6d94236d52dd60fa078961c53420701b67a

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright tylercschneider
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,2 @@
+# easy_flow
+Guided, versioned, branching flows for Rails apps

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/models/easy_flow/admission.rb

@@ -0,0 +1,17 @@
+module EasyFlow
+  module Admission
+    def self.of(flow, permitted:)
+      raise NotPublished if flow.nil? || flow.live_definition.blank?
+      raise NotPermitted unless permitted && flow.available?
+
+      flow
+    end
+
+    def self.of_run(run, permitted: true)
+      raise Withdrawn if run.definition_version.withdrawn?
+      raise NotPermitted unless permitted && run.flow.available?
+
+      run
+    end
+  end
+end

data/app/models/easy_flow/application_record.rb

@@ -0,0 +1,5 @@
+module EasyFlow
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/easy_flow/asked.rb

@@ -0,0 +1,3 @@
+module EasyFlow
+  Asked = Data.define(:id, :text, :choices)
+end

data/app/models/easy_flow/canvas.rb

@@ -0,0 +1,165 @@
+module EasyFlow
+  class Canvas
+    def initialize(document, registry: EasyFlow.registry)
+      @document = document
+      @registry = registry
+    end
+
+    def to_h
+      { "nodes" => nodes, "edges" => edges, "palette" => palette, "violations" => violations }
+    end
+
+    private
+
+    def nodes
+      @document.nodes.map { |node| drawn_step(node) } + waiting.map { |gap| drawn_placeholder(gap) }
+    end
+
+    def drawn_step(node)
+      { "id" => node.id, "type" => node.type, "label" => label_for(node),
+        "config" => node.config, "ports" => [], "ends_here" => ends_here?(node), "begins_here" => begins_here?(node),
+        "loose" => loose?(node), "choices" => choices_for(node), "placeholder" => false, **placed[node.id] }
+    end
+
+    def drawn_placeholder(gap)
+      { "id" => gap[:id], "type" => "placeholder", "label" => gap[:on], "config" => {}, "ports" => [],
+        "ends_here" => false, "begins_here" => false, "loose" => false, "choices" => {},
+        "placeholder" => true, "from" => gap[:from], "on" => gap[:on], **placed[gap[:id]] }
+    end
+
+    def edges
+      drawn.edges.each_with_index.map do |edge, index|
+        { "id" => "#{edge.from}-#{edge.to}-#{index}", "source" => edge.from, "target" => edge.to, "label" => edge.on&.to_s,
+          "placeholder" => waiting.any? { |gap| gap[:id] == edge.to } }.merge(routing(edge, placed))
+      end
+    end
+
+    def placed
+      @placed ||= Layout.new(drawn).positions
+    end
+
+    def drawn
+      @drawn ||= Document.new(@document.to_h.merge(
+        "nodes" => Array(@document.to_h["nodes"]) + waiting.map { |gap| { "id" => gap[:id], "type" => "placeholder" } },
+        "edges" => Array(@document.to_h["edges"]) + waiting.map { |gap| { "from" => gap[:from], "to" => gap[:id], "on" => gap[:on] } }
+      ), registry: @registry)
+    end
+
+    def waiting
+      @waiting ||= @document.nodes.flat_map { |node| gaps_after(node) }
+    end
+
+    def gaps_after(node)
+      wired = @document.edges_from(node.id).map { |edge| edge.on.to_s }
+      results = digest.routing_values(node.id)
+      return [ { id: "#{node.id}--", from: node.id, on: nil } ] if results.empty? && leads_nowhere?(node)
+
+      results.reject { |value| wired.include?(value) }
+        .map { |value| { id: "#{node.id}--#{value}", from: node.id, on: value } }
+    end
+
+    def leads_nowhere?(node)
+      !ends_here?(node) && !loose?(node) && @document.edges_from(node.id).none?
+    end
+
+    def routing(edge, placed)
+      from = placed[edge.from]
+      to = placed[edge.to]
+      return { "leaves" => "bottom", "enters" => "top", "route" => "straight" } unless from && to
+
+      return alongside_routing(from, to) unless to["row"] > from["row"]
+
+      { "leaves" => "bottom", "enters" => "top",
+        "route" => to["column"] == from["column"] ? "straight" : "lane" }
+    end
+
+    def alongside_routing(from, to)
+      leftward = to["column"] < from["column"]
+
+      { "leaves" => leftward ? "left" : "right", "enters" => leftward ? "right" : "left",
+        "route" => to["row"] == from["row"] ? "straight" : "detour" }
+    end
+
+    def palette
+      @registry.step_types.reject(&:begins_here?).map do |step_type|
+        { "type" => step_type.id.to_s, "label" => step_type.step_name,
+          "fields" => step_type.settings.fields.transform_keys(&:to_s).transform_values(&:to_s),
+          "labels" => step_type.settings.labels.transform_keys(&:to_s),
+          "choices" => step_type.settings.choices.transform_keys(&:to_s),
+          "records" => holdings_of(step_type),
+          "record_labels" => step_type.settings.record_labels.to_h { |name, held| [ name.to_s, held.transform_keys(&:to_s) ] },
+          "awaits_input" => step_type.awaits_input? }
+      end
+    end
+
+    def holdings_of(step_type)
+      step_type.settings.record_fields.to_h do |name, holds|
+        [ name.to_s, holds.transform_keys(&:to_s).transform_values(&:to_s) ]
+      end
+    end
+
+    def violations
+      Validator.new(@document, registry: @registry).violations.map do |violation|
+        { "node" => violation.node, "problem" => violation.problem.to_s, "detail" => violation.detail }
+      end
+    end
+
+    def label_for(node)
+      Name.of(node, @registry)
+    end
+
+    def choices_for(node)
+      naming_steps(node).index_with { earlier_than(node) }.merge(drawn_by(node)).merge(named_outputs_by(node))
+    end
+
+    def named_outputs_by(node)
+      step_type_for(node)&.settings&.outputs_of.to_h.to_h do |name, source|
+        [ name.to_s, digest.outputs_of(node.config[source.to_s]) ]
+      end
+    end
+
+    def drawn_by(node)
+      step_type_for(node)&.settings&.drawn_from.to_h.to_h do |name, source|
+        [ name.to_s, digest.values_of(step_named_by(node, source), node.config[source.to_s]) ]
+      end
+    end
+
+    def step_named_by(node, source)
+      node.config[step_type_for(node).settings.outputs_of[source].to_s]
+    end
+
+    def digest
+      Digest.new(@document, registry: @registry)
+    end
+
+    def naming_steps(node)
+      step_type_for(node)&.settings&.naming_steps.to_a.map(&:to_s)
+    end
+
+    def earlier_than(node)
+      digest.preceding(node.id).map do |id|
+        { "value" => id, "label" => label_for(@document.node(id)) }
+      end
+    end
+
+    def ends_here?(node)
+      step_type_for(node)&.ends_here? || false
+    end
+
+    def loose?(node)
+      @document.entry.present? && @document.reachable.exclude?(node.id)
+    end
+
+    def begins_here?(node)
+      step_type_for(node)&.begins_here? || false
+    end
+
+    def ports_for(node)
+      digest.routing_values(node.id)
+    end
+
+    def step_type_for(node)
+      @registry.fetch(node.type) if @registry.registered?(node.type)
+    end
+  end
+end

data/app/models/easy_flow/change.rb

@@ -0,0 +1,16 @@
+module EasyFlow
+  module Change
+    PHRASING = { "added" => "Added", "updated" => "Updated", "removed" => "Removed",
+                 "moved" => "Moved", "connected" => "Connected", "disconnected" => "Disconnected", "returned" => "Returned to" }.freeze
+
+    def self.phrase(change)
+      named = Array(change["named"]).compact_blank.map { |name| "“#{name}”" }
+      verb = PHRASING.fetch(change["action"], change["action"])
+
+      return "#{verb} #{named.join(' → ')}" if named.any?
+      return "#{verb} #{change['detail']}" if change["detail"].present?
+
+      verb
+    end
+  end
+end

data/app/models/easy_flow/choice.rb

@@ -0,0 +1,7 @@
+module EasyFlow
+  Choice = Data.define(:value, :label, :hint) do
+    def initialize(value:, label: nil, hint: nil)
+      super(value: value, label: label.presence || value, hint: hint)
+    end
+  end
+end

data/app/models/easy_flow/condition.rb

@@ -0,0 +1,22 @@
+module EasyFlow
+  class Condition
+    include Step
+
+    step_name "Condition"
+
+    setting :step, type: :previous_step
+    setting :output, outputs_of: :step, required: true
+    setting :comparison, type: :select, options: [ "is", "is not" ], required: true
+    setting :answer, from: :output, required: true
+
+    output :result, type: :boolean, values: [ true, false ]
+
+    names_by { |node| node.config.values_at("step", "comparison", "answer").compact_blank.join(" ").presence }
+
+    def route(node, state)
+      matched = state[node.config["step"]] == node.config["answer"]
+
+      node.config["comparison"] == "is not" ? !matched : matched
+    end
+  end
+end

data/app/models/easy_flow/definition.rb

@@ -0,0 +1,125 @@
+module EasyFlow
+  class Definition < ApplicationRecord
+    self.table_name = "easy_flow_definitions"
+
+    enum :status, { active: "active", hidden: "hidden", inactive: "inactive" }
+    enum :kind, { scored: "scored", guide: "guide" }
+    enum :persists, { unsaved: "unsaved", each_step: "each_step", on_finish: "on_finish" }
+
+    validates :slug, presence: true
+
+    after_initialize :begin_the_flow, if: :new_record?
+
+    scope :listable, -> { active }
+
+    # Declared before :definition_versions so runs clear first, otherwise
+    # destroying a flow trips the runs -> definition_versions FK.
+    has_many :runs, class_name: "EasyFlow::Run", foreign_key: :flow_id, dependent: :destroy
+    has_many :definition_versions, class_name: "EasyFlow::Version", foreign_key: :flow_id, dependent: :destroy
+
+    def self.upsert_definition(definition)
+      find_or_initialize_by(slug: definition["slug"]).tap do |flow|
+        flow.save!
+        flow.record_definition(definition) unless flow.definition == definition
+      end
+    end
+
+    def definition
+      current_definition_version&.definition
+    end
+
+    def current_definition_version
+      definition_versions.find_by(number: cursor)
+    end
+
+    def edit_history
+      @edit_history ||= EditHistory.new(self)
+    end
+
+    def publish
+      create_version
+
+      publish_version(current_definition_version)
+    end
+
+    def return_to(version)
+      raise ActiveRecord::RecordNotFound unless definition_versions.exists?(version.id)
+      raise OutOfService if version.out_of_service?
+
+      update!(document: version.definition, undone_changes: [],
+        changes_since_version: changes_since_version.to_a + [ returning_to(version) ])
+    end
+
+    def create_version
+      record_definition(document, changes_since_version.to_a) unless versioned?
+
+      update!(undo_history: edit_history.undoable, changes_since_version: [], undone_changes: [])
+    end
+
+    def returning_to(version)
+      { "action" => "returned", "steps" => [], "named" => [],
+        "detail" => "version #{version.number}", "before" => document }
+    end
+
+    def versioned?
+      document == definition
+    end
+
+    def record_definition(payload, captured = [])
+      definition_versions.create!(number: next_definition_number, definition: payload,
+        changes_captured: captured.map { |change| change.except("before") })
+        .tap { |version| update!(definition_cursor: version.number, document: payload) }
+    end
+
+    def publish_version(version)
+      raise OutOfService if version.out_of_service?
+      return if live_version == version
+
+      live_version&.update!(status: :superseded)
+      version.update!(status: :live)
+    end
+
+    def available?
+      !inactive?
+    end
+
+    def retire_version(version)
+      version.update!(status: :retired)
+    end
+
+    def withdraw_version(version)
+      version.update!(status: :withdrawn)
+    end
+
+    def live_version
+      definition_versions.find_by(status: :live)
+    end
+
+    def live_definition
+      live_version&.definition
+    end
+
+    def runner
+      Runner.new(live_definition)
+    end
+
+    private
+
+    def begin_the_flow
+      self.document ||= { "nodes" => [ { "id" => "start", "type" => "start" }, { "id" => "end", "type" => "terminal" } ],
+                          "edges" => [ { "from" => "start", "to" => "end" } ] }
+    end
+
+    def cursor
+      definition_cursor || recorded_numbers.max
+    end
+
+    def recorded_numbers
+      definition_versions.pluck(:number)
+    end
+
+    def next_definition_number
+      (definition_versions.maximum(:number) || 0) + 1
+    end
+  end
+end

data/app/models/easy_flow/digest.rb

@@ -0,0 +1,114 @@
+module EasyFlow
+  class Digest
+    def initialize(document, registry: EasyFlow.registry)
+      @document = document
+      @registry = registry
+    end
+
+    def entry
+      @document.node(@document.entry)
+    end
+
+    def step(id)
+      @document.node(id)
+    end
+
+    def steps
+      @document.nodes
+    end
+
+    def preceding(id)
+      return [] unless @document.reachable.include?(id)
+
+      @document.nodes.map(&:id).uniq
+        .reject { |other| other == id || @document.reachable(without: other).include?(id) }
+    end
+
+    def routing_values(id)
+      named = step(id)
+      return [] unless named && step_type(named)&.routes?
+
+      step_type(named).outputs.flat_map { |output| values_taken(output, named) }.map { |value| value["value"].to_s }
+    end
+
+    def values_taken(output, node)
+      return output.values_for(node) unless output.from
+
+      values_out_of(node.config[output.from.to_s])
+    end
+
+    def values_of(id, output_name)
+      named = step(id)
+      return [] unless named && output_name.present?
+
+      step_type(named)&.values_of(output_name, named).to_a
+    end
+
+    def outputs_of(id)
+      named = step(id)
+      return [] unless named
+
+      step_type(named)&.outputs.to_a.map { |output| { "value" => output.name.to_s, "label" => output.label } }
+    end
+
+    def values_out_of(id)
+      named = step(id)
+      return [] unless named
+
+      step_type(named)&.outputs.to_a.flat_map { |output| output.values_for(named) }
+    end
+
+    def requirements(id)
+      node = step(id)
+      step_type(node)&.settings&.requirements_for(node.config).to_a
+    end
+
+    def next_step(state)
+      walk(state).last
+    end
+
+    def state_on_path(state)
+      state.slice(*walk(state).first)
+    end
+
+    private
+
+    def walk(state)
+      recorded = []
+      visited = []
+      cursor = entry
+
+      while cursor && !visited.include?(cursor.id)
+        return [ recorded, cursor ] if pending?(cursor, state)
+
+        recorded << cursor.id if state.key?(cursor.id)
+        visited << cursor.id
+        cursor = successor(cursor, state)
+      end
+
+      [ recorded, nil ]
+    end
+
+    def pending?(node, state)
+      return false if state.key?(node.id)
+
+      step_type(node)&.awaits_input? || acts?(node)
+    end
+
+    def acts?(node)
+      step_type(node)&.acts? || false
+    end
+
+    def successor(node, state)
+      leaving = @document.edges_from(node.id)
+      port = step_type(node)&.route(node, state)
+      taken = port.nil? ? leaving.first : leaving.find { |edge| edge.on.to_s == port.to_s }
+
+      taken && @document.node(taken.to)
+    end
+
+    def step_type(node)
+      @registry.fetch(node.type) if node && @registry.registered?(node.type)
+    end
+  end
+end

data/app/models/easy_flow/document.rb

@@ -0,0 +1,129 @@
+module EasyFlow
+  class Document
+    def initialize(document, registry: EasyFlow.registry)
+      @document = document
+      @registry = registry
+    end
+
+    def nodes
+      Array(@document["nodes"]).map { |node| Node.new(id: node["id"], type: node["type"], config: node.except("id", "type")) }
+    end
+
+    def edges
+      Array(@document["edges"]).map { |edge| Edge.new(from: edge["from"], to: edge["to"], on: edge["on"]) }
+    end
+
+    def entry
+      beginnings.first
+    end
+
+    def beginnings
+      nodes.select { |node| begins_here?(node) }.map(&:id)
+    end
+
+    def begins_here?(node)
+      @registry.registered?(node.type) && @registry.fetch(node.type).begins_here?
+    end
+
+    def node(id)
+      nodes.find { |node| node.id == id }
+    end
+
+    def edges_from(id)
+      edges.select { |edge| edge.from == id }
+    end
+
+    def reachable(without: nil)
+      found = []
+      frontier = [ entry ]
+
+      while (id = frontier.shift)
+        next if found.include?(id) || id == without
+
+        found << id
+        frontier.concat(edges_from(id).map(&:to))
+      end
+
+      found
+    end
+
+    def to_h
+      @document
+    end
+
+    def insert(node, on:, leaving: nil)
+      source, target = on
+      replaced = raw_edges.find { |edge| edge["from"] == source && edge["to"] == target }
+      bridged = [ { "from" => source, "to" => node["id"], "on" => replaced&.fetch("on", nil) }.compact,
+                  { "from" => node["id"], "to" => target, "on" => leaving }.compact ]
+
+      with(nodes: raw_nodes + [ node ], edges: (raw_edges - [ replaced ]) + bridged)
+    end
+
+    def add(node)
+      with(nodes: raw_nodes + [ node ], edges: raw_edges)
+    end
+
+    def connect(from:, to:, on: nil)
+      with(nodes: raw_nodes, edges: raw_edges + [ { "from" => from, "to" => to, "on" => on }.compact ])
+    end
+
+    def disconnect(from:, to:)
+      with(nodes: raw_nodes, edges: raw_edges.reject { |edge| edge["from"] == from && edge["to"] == to })
+    end
+
+    def move(id, on:, leaving: nil)
+      step = raw_nodes.find { |node| node["id"] == id }
+      return self unless step
+
+      remove(id).insert(step, on: on, leaving: leaving)
+    end
+
+    def configure(id, config)
+      reconfigured = raw_nodes.map do |node|
+        node["id"] == id ? node.slice("id", "type").merge(config) : node
+      end
+
+      with(nodes: reconfigured, edges: raw_edges)
+    end
+
+    def rewire(from:, to:, target:)
+      rewritten = raw_edges.map do |edge|
+        edge["from"] == from && edge["to"] == to ? edge.merge("to" => target) : edge
+      end
+
+      with(nodes: raw_nodes, edges: rewritten)
+    end
+
+    def remove(id)
+      incoming = raw_edges.select { |edge| edge["to"] == id }
+      outgoing = raw_edges.select { |edge| edge["from"] == id }
+
+      with(nodes: raw_nodes.reject { |node| node["id"] == id },
+           edges: (raw_edges - incoming - outgoing) + bridges(incoming, outgoing))
+    end
+
+    private
+
+    def bridges(incoming, outgoing)
+      incoming.product(outgoing).map do |arriving, leaving|
+        { "from" => arriving["from"], "to" => leaving["to"], "on" => arriving["on"] }.compact
+      end
+    end
+
+    def raw_nodes
+      Array(@document["nodes"])
+    end
+
+    def raw_edges
+      Array(@document["edges"])
+    end
+
+    def with(nodes:, edges:)
+      Document.new(@document.merge("nodes" => nodes, "edges" => edges), registry: @registry).tap do |edited|
+        broken = Validator.new(edited, registry: @registry).malformations
+        raise InvalidEdit, broken.map { |violation| "#{violation.node}: #{violation.problem}" }.join(", ") if broken.any?
+      end
+    end
+  end
+end

data/app/models/easy_flow/drawing.rb

@@ -0,0 +1,13 @@
+module EasyFlow
+  module Drawing
+    def self.of(node, registry = EasyFlow.registry)
+      named(node, registry).presence || EasyFlow.drawing
+    end
+
+    def self.named(node, registry)
+      return unless node && registry.registered?(node.type)
+
+      registry.fetch(node.type).drawn_by
+    end
+  end
+end

data/app/models/easy_flow/edge.rb

@@ -0,0 +1,7 @@
+module EasyFlow
+  Edge = Data.define(:from, :to, :on) do
+    def initialize(from:, to:, on: nil)
+      super
+    end
+  end
+end