Class: Inquirex::Definition

Inherits:
Object
  • Object
show all
Defined in:
lib/inquirex/definition.rb

Overview

Immutable, versionable flow graph. Maps step ids to Node objects and defines the entry point. Carries optional metadata (id, version, title, subtitle, brand) for the JS widget. Supports JSON round-trip serialization; lambdas are stripped on serialization.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {}) ⇒ Definition

Returns a new instance of Definition.

Parameters:

  • start_step_id (Symbol) —

    id of the initial step

  • nodes (Hash<Symbol, Node>) —

    all steps keyed by id

  • id (String, nil) (defaults to: nil) —

    flow identifier

  • version (String) (defaults to: "1.0.0") —

    semver

  • meta (Hash) (defaults to: {}) —

    frontend metadata

Raises:



24
25
26
27
28
29
30
31
32
 
# File 'lib/inquirex/definition.rb', line 24

def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {})
  @id = id
  @version = version
  @meta = meta.freeze
  @start_step_id = start_step_id.to_sym
  @steps = nodes.freeze
  validate!
  freeze
end

Instance Attribute Details

#id ⇒ String? (readonly)

flow identifier (e.g. “tax-intake-2025”)

Returns:

  • (String, nil) —

    the current value of id



15
16
17
 
# File 'lib/inquirex/definition.rb', line 15

def id
  @id
end

#meta ⇒ Hash (readonly)

title, subtitle, brand info for the frontend

Returns:

  • (Hash) —

    the current value of meta



15
16
17
 
# File 'lib/inquirex/definition.rb', line 15

def meta
  @meta
end

#start_step_id ⇒ Symbol (readonly)

id of the first step in the flow

Returns:

  • (Symbol) —

    the current value of start_step_id



15
16
17
 
# File 'lib/inquirex/definition.rb', line 15

def start_step_id
  @start_step_id
end

#steps ⇒ Hash<Symbol, Node> (readonly)

frozen map of step id => node

Returns:

  • (Hash<Symbol, Node>) —

    the current value of steps



15
16
17
 
# File 'lib/inquirex/definition.rb', line 15

def steps
  @steps
end

#version ⇒ String (readonly)

semver string (default: “1.0.0”)

Returns:

  • (String) —

    the current value of version



15
16
17
 
# File 'lib/inquirex/definition.rb', line 15

def version
  @version
end

Class Method Details

.from_h(hash) ⇒ Definition

Deserializes a Definition from a plain Hash.

Parameters:

  • hash (Hash) —

    definition attributes (string or symbol keys)

Returns:



86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/inquirex/definition.rb', line 86

def self.from_h(hash)
  id = hash["id"] || hash[:id]
  version = hash["version"] || hash[:version] || "1.0.0"
  meta = hash["meta"] || hash[:meta] || {}
  start = hash["start"] || hash[:start]
  steps_data = hash["steps"] || hash[:steps] || {}

  nodes = steps_data.each_with_object({}) do |(step_id, step_hash), acc|
    sym_id = step_id.to_sym
    acc[sym_id] = Node.from_h(sym_id, step_hash)
  end

  new(start_step_id: start, nodes:, id:, version:, meta:)
end

.from_json(json) ⇒ Definition

Deserializes a Definition from a JSON string.

Parameters:

  • json (String) —

    JSON representation

Returns:



76
77
78
79
80
 
# File 'lib/inquirex/definition.rb', line 76

def self.from_json(json)
  from_h(JSON.parse(json))
rescue JSON::ParserError => e
  raise Errors::SerializationError, "Invalid JSON: #{e.message}"
end

Instance Method Details

#start_step ⇒ Node

Returns the node for the start step.

Returns:

  • (Node) —

    the node for the start step



35
36
37
 
# File 'lib/inquirex/definition.rb', line 35

def start_step
  step(@start_step_id)
end

#step(id) ⇒ Node

Returns the node for that step.

Parameters:

  • id (Symbol) —

    step id

Returns:

  • (Node) —

    the node for that step

Raises:



42
43
44
 
# File 'lib/inquirex/definition.rb', line 42

def step(id)
  @steps.fetch(id.to_sym) { raise Errors::UnknownStepError, "Unknown step: #{id.inspect}" }
end

#step_ids ⇒ Array<Symbol>

Returns all step ids.

Returns:

  • (Array<Symbol>) —

    all step ids



47
48
49
 
# File 'lib/inquirex/definition.rb', line 47

def step_ids
  @steps.keys
end

#to_h ⇒ Hash

Serializes to a plain Hash.

Returns:

  • (Hash) 


62
63
64
65
66
67
68
69
70
 
# File 'lib/inquirex/definition.rb', line 62

def to_h
  hash = {}
  hash["id"] = @id if @id
  hash["version"] = @version
  hash["meta"] = @meta unless @meta.empty?
  hash["start"] = @start_step_id.to_s
  hash["steps"] = @steps.transform_keys(&:to_s).transform_values(&:to_h)
  hash
end

#to_json ⇒ String

Serializes the definition to a JSON string. Lambdas (default procs, compute blocks) are silently stripped.

Returns:

  • (String) —

    JSON representation



55
56
57
 
# File 'lib/inquirex/definition.rb', line 55

def to_json(*)
  JSON.generate(to_h)
end