sourced-component 0.1.0

data/lib/sourced/component/graph.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # Returned by Component#graph. #components are hashes describing each declared component, by full path:
+    #   {
+    #     key: 'sourced.db',          # the component's full path from the root
+    #     type: <Plumb type>,
+    #     type_name: 'Interface[exec]',
+    #     implemented: true,
+    #     mode: :singleton,           # nil if not implemented
+    #     status: :built,
+    #     deps: ['logger'],           # full paths of the components this one depends on
+    #     missing: [],                # deps that aren't declared, or are namespaces without an implementation
+    #     dependents: ['app'],        # components in the graph that depend on this one
+    #     provider: <provider>        # the provider, or the block of #config!/#config. nil for blocks of hooks
+    #   }
+    class Graph < Data.define(:status, :components)
+      # Mermaid classes for component statuses, plus declared-but-unimplemented components,
+      # missing dependencies, and dependencies outside the graph (ex. a library's graph, with an app's overrides)
+      MERMAID_CLASSES = Mermaid::STATUS_CLASSES.merge(
+        missing: 'fill:#fee2e2,stroke:#dc2626,stroke-dasharray:4 3',
+        external: 'fill:#ffffff,stroke:#a1a1aa,stroke-dasharray:2 2'
+      ).freeze
+
+      # A Mermaid flowchart of the dependency graph.
+      # Edges point from each dependency to its dependents (build and start order).
+      # Singletons are rectangles, dynamic components are rounded, and nodes are styled by status.
+      # Unimplemented components, missing dependencies and dependencies outside the graph are included, with dashed borders.
+      def to_mermaid
+        ids = {}
+        id_for = ->(key) { ids[key] ||= "c#{ids.size}" }
+        lines = ['flowchart LR']
+
+        components.each do |node|
+          details = Mermaid.details(node[:implemented], node[:mode], node[:status], node[:deferred])
+          label = "#{Mermaid.escape(node[:key])}<br/>#{Mermaid.escape(node[:type_name])}<br/><i>#{details}</i>"
+          open, close = Mermaid.component_shape(node[:mode])
+          css_class = node[:implemented] ? node[:status] : :unimplemented
+          lines << "  #{id_for.(node[:key])}#{open}#{label}#{close}:::#{css_class}"
+        end
+
+        keys = components.map { |node| node[:key] }
+        missing = components.flat_map { |node| node.fetch(:missing, []) }.uniq
+        outside = components.flat_map { |node| node[:deps] }.uniq - keys
+        outside.each do |key|
+          details, css_class = missing.include?(key) ? ['not declared', :missing] : ['outside this component', :external]
+          lines << "  #{id_for.(key)}[\"#{Mermaid.escape(key)}<br/><i>#{details}</i>\"]:::#{css_class}"
+        end
+
+        components.each do |node|
+          node[:deps].each { |dep| lines << "  #{id_for.(dep)} --> #{id_for.(node[:key])}" }
+        end
+
+        lines.concat(Mermaid.class_defs(MERMAID_CLASSES))
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/sourced/component/implementation.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # singleton: built once, on #build!, and memoized
+    # dynamic:   built on every read
+    # alias:     reads another component (its only dep). Memoized if that component is, see Component#alias
+    MODES = %i[singleton dynamic alias].freeze
+
+    # How a node is built. Deps are keys relative to the implementer: the component that called #component! or #component.
+    #   prepare:  hooks run with no arguments
+    #   build:    hooks run with dep values. The last result is the node's value
+    #   start:    hooks run with (value, context). Again after each stop, for a component started by key
+    #   stop:     hooks run with (value), when a started component is stopped, or torn down
+    #   teardown: hooks run with (value), once, when the root is torn down
+    # A dep ending in '.*' depends on every component directly under that key, and its value is
+    # a hash of their values by key segment, ex. 'reactors.*' => { 'foo' => <Foo>, 'bar' => <Bar> }
+    class Implementation
+      WILDCARD = /\A[^.*]+(\.[^.*]+)*\.\*\z/
+
+      # provider: the provider the component was implemented with (see Component#component!), the block of
+      # Component#config! and #config, or nil for blocks of hooks
+      attr_reader :deps, :implementer, :mode, :provider
+
+      def self.from_block(deps, implementer:, mode:, &block)
+        dsl = DSL.new
+        if block
+          block.arity > 0 ? block.call(dsl) : dsl.instance_eval(&block)
+        end
+        new(deps, implementer:, mode:, hooks: dsl.hooks)
+      end
+
+      # An alias of the component at +target+, relative to the implementer: its value is the target's,
+      # and it has no other hooks
+      def self.alias(target, implementer:)
+        target = target.to_s
+        raise ArgumentError, "can't alias #{target.inspect}: an alias takes a single component, not a wildcard" if target.include?('*')
+
+        new([target], implementer:, mode: :alias, hooks: DSL.new.build { |value| value }.hooks)
+      end
+
+      # Hooks that a provider's builder can implement, besides #call (the build step)
+      OPTIONAL_HOOKS = %i[prepare start stop teardown].freeze
+
+      # From a provider's builder: #call(*deps) is the build step, and it can also implement
+      # #prepare, #start(value, context), #stop(value) and #teardown(value).
+      def self.from_builder(builder, deps, implementer:, mode:, provider: nil)
+        dsl = DSL.new
+        dsl.build(builder)
+        OPTIONAL_HOOKS.each do |name|
+          dsl.public_send(name, builder.method(name)) if builder.respond_to?(name)
+        end
+        new(deps, implementer:, mode:, hooks: dsl.hooks, provider:)
+      end
+
+      def initialize(deps, implementer:, mode:, hooks:, provider: nil)
+        raise ArgumentError, "unknown mode #{mode.inspect}, expected one of #{MODES.join(', ')}" unless MODES.include?(mode)
+
+        @deps = deps.map { |d| d.to_s.freeze }.freeze
+        @deps.each do |dep|
+          next unless dep.include?('*')
+          next if dep.match?(WILDCARD)
+
+          raise ArgumentError, "invalid dependency #{dep.inspect}: a wildcard must be the last segment, ex. 'reactors.*'"
+        end
+        @implementer = implementer
+        @mode = mode
+        @provider = provider
+        @hooks = hooks.transform_values(&:freeze).freeze
+      end
+
+      def singleton? = mode == :singleton
+      def dynamic? = mode == :dynamic
+      def alias? = mode == :alias
+
+      def prepare = @hooks[:prepare].each(&:call)
+      def build(*deps) = @hooks[:build].reduce(nil) { |_, b| b.call(*deps) }
+      def start(value, context) = @hooks[:start].each { |b| b.call(value, context) }
+      def stop(value) = @hooks[:stop].each { |b| b.call(value) }
+      def teardown(value) = @hooks[:teardown].each { |b| b.call(value) }
+    end
+  end
+end

data/lib/sourced/component/injector.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # A module that injects components into a class as keyword arguments to #initialize,
+    # defaulting to the component's value when the object is instantiated.
+    #   include App.inject('logger', 'sourced.store' => 'st')
+    # Each include prepends its own #initialize, which takes its kwargs and passes the rest on to super,
+    # so multiple injections (and the class' own #initialize) compose.
+    # Including it raises InjectionError if the class already has a method named like an injected reader.
+    # Values are read from the nodes themselves, so a class injecting from a library's component
+    # gets the overrides of the application that mounts it.
+    class Injector < Module
+      attr_reader :names
+
+      # nodes: { 'component.key' => <Component node> }
+      # names: { 'component.key' => :kwarg_name }
+      def initialize(nodes, names)
+        super()
+        @names = names.freeze
+
+        # Instance variable names are computed once, not on every #new
+        entries = names.map { |key, name| [nodes.fetch(key), name, :"@#{name}"] }.freeze
+
+        initializer = Module.new do
+          define_method(:initialize) do |*args, **kwargs, &block|
+            entries.each do |node, name, ivar|
+              instance_variable_set(ivar, kwargs.key?(name) ? kwargs.delete(name) : node.read)
+            end
+            super(*args, **kwargs, &block)
+          end
+        end
+
+        # Checked before the module is added to the class, so a refused include leaves the class untouched
+        define_singleton_method(:append_features) do |base|
+          taken = (base.ancestors.grep(Injector) - [self]).flat_map { |i| i.names.values } & names.values
+          raise InjectionError, "#{base} already injects #{taken.join(', ')}" if taken.any?
+
+          # Readers would silently replace these, including private ones (ex. Kernel#format)
+          defined = names.values.select { |name| base.method_defined?(name) || base.private_method_defined?(name) }
+          if defined.any?
+            methods = defined.map { |name| "##{name} (from #{base.instance_method(name).owner})" }
+            raise InjectionError, "#{base} already defines #{methods.join(', ')}: " \
+                                  "inject under another name instead, ex. inject('key' => 'other_name')"
+          end
+
+          super(base)
+        end
+
+        define_singleton_method(:included) do |base|
+          base.prepend(initializer)
+          base.attr_reader(*names.values)
+        end
+      end
+
+      def inspect = "#<#{self.class} #{names.map { |key, name| "#{key} => #{name}" }.join(', ')}>"
+    end
+  end
+end

data/lib/sourced/component/mermaid.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # Helpers shared by Graph#to_mermaid and Tree#to_mermaid
+    module Mermaid
+      # Styles for component statuses, and for declared-but-unimplemented components
+      STATUS_CLASSES = {
+        open: 'fill:#f4f4f5,stroke:#71717a',
+        prepared: 'fill:#e0f2fe,stroke:#0284c7',
+        built: 'fill:#ede9fe,stroke:#7c3aed',
+        started: 'fill:#dcfce7,stroke:#16a34a',
+        stopped: 'fill:#ffedd5,stroke:#ea580c',
+        torn_down: 'fill:#e4e4e7,stroke:#52525b,color:#52525b',
+        unimplemented: 'fill:#fef9c3,stroke:#ca8a04,stroke-dasharray:4 3'
+      }.freeze
+
+      # Escape label text, so type names with brackets, pipes or quotes are safe
+      def self.escape(text)
+        text.to_s.gsub('&', '#amp;').gsub('"', '#quot;').gsub('<', '#lt;').gsub('>', '#gt;')
+      end
+
+      # ex. 'singleton, started', 'singleton, built, deferred', or 'not implemented'
+      def self.details(implemented, mode, status, deferred = false)
+        return 'not implemented' unless implemented
+
+        [mode, status, ('deferred' if deferred)].compact.join(', ')
+      end
+
+      # Open and close brackets: singletons are rectangles, dynamic components are rounded
+      def self.component_shape(mode) = mode == :dynamic ? ['(["', '"])'] : ['["', '"]']
+
+      def self.class_defs(classes) = classes.map { |name, style| "  classDef #{name} #{style}" }
+    end
+  end
+end

data/lib/sourced/component/notifier.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # The default notifier. Custom notifiers must implement the same #publish and #subscribe interface.
+    # Handlers are called synchronously, in the order they subscribed, by the thread or fiber running the lifecycle step.
+    # Errors raised by handlers propagate to the caller.
+    class Notifier
+      def initialize
+        @subscriptions = [].freeze
+        @lock = Mutex.new
+      end
+
+      # Subscribe to an event type string (ex. 'components.built'),
+      # or an event class, which also matches its subclasses (ex. Events::ComponentEvent for all component events)
+      def subscribe(event_class_or_type, &handler)
+        raise ArgumentError, 'a handler block is required' unless handler
+
+        matcher = case event_class_or_type
+                  when Class
+                    ->(event) { event.is_a?(event_class_or_type) }
+                  when String, Symbol
+                    type = event_class_or_type.to_s
+                    raise ArgumentError, "unknown event type #{type}" unless Event.registry[type]
+
+                    ->(event) { event.type == type }
+                  else
+                    raise ArgumentError, "can't subscribe to #{event_class_or_type.inspect}"
+                  end
+
+        # copy-on-write, so publishing never needs the lock
+        @lock.synchronize { @subscriptions = [*@subscriptions, [matcher, handler]].freeze }
+        self
+      end
+
+      def publish(event)
+        @subscriptions.each { |matcher, handler| handler.call(event) if matcher.call(event) }
+        self
+      end
+    end
+
+    NotifierInterface = Plumb::Types::Interface[:publish, :subscribe]
+  end
+end

data/lib/sourced/component/tree.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    # Returned by Component#tree: the tree of components under a component, as nested nodes.
+    # Unlike Component#graph (the dependency graph), it shows how components are nested,
+    # which components are mounted, and who declared and implemented each node.
+    #   tree = App.tree
+    #   tree.status  # => :built, the root's status
+    #   tree.root    # => a Tree::Node, with #children
+    #   puts tree    # => an ASCII tree
+    #   tree.to_h    # => nested hashes
+    class Tree < Data.define(:status, :root)
+      # key:         the node's segment, ex. 'db'. nil for the root of a tree
+      # path:        the full path from the root, ex. 'sourced.db'. nil for the root of a tree
+      # namespace:   whether it has no type and no implementation
+      # mounted:     whether it's a component mounted here (it owns itself)
+      # deferred:    whether the root's start! skips it (see Component#defer)
+      # owner:       the full path of the component that declared it. nil for the root
+      # implementer: the full path of the component that implemented it. nil for the root, or if not implemented
+      class Node < Data.define(
+        :key, :path, :type, :type_name, :namespace, :mounted, :implemented, :mode, :status, :deferred, :owner, :implementer, :children
+      )
+        # Whether it's implemented by a component other than the one that declared it, ex. an app overriding a library's component
+        def overridden? = implemented && owner != implementer
+
+        def to_h = super.merge(children: children.map(&:to_h))
+      end
+
+      def to_h = { status:, root: root.to_h }
+
+      #   (root)
+      #   ├── logger Interface[info] (singleton, built)
+      #   ├── sourced [mounted]
+      #   │   ├── logger Interface[info] (singleton, built)
+      #   │   └── db DB (singleton, built) implemented by (root)
+      #   └── cache
+      #       └── redis String (singleton, built)
+      def to_s
+        lines = [label(root, root.path || '(root)')]
+        render(root.children, '', lines)
+        lines.join("\n")
+      end
+
+      # Mermaid classes for component statuses and unimplemented components, plus namespaces and roots
+      MERMAID_CLASSES = Mermaid::STATUS_CLASSES.merge(
+        namespace: 'fill:#ffffff,stroke:#a1a1aa',
+        root: 'fill:#fafafa,stroke:#18181b,stroke-width:2px'
+      ).freeze
+
+      # A top-down Mermaid flowchart of the tree, with an edge from each node to its children.
+      # Roots (the root of the tree, and mounted components) are hexagons, namespaces are rounded,
+      # and components are styled like Graph#to_mermaid: singletons are rectangles, dynamic components
+      # are rounded, colored by status. Components implemented by another component say which one.
+      #   flowchart TD
+      #     n0{{"(root)"}}:::root
+      #     n1["logger<br/>Interface[info]<br/><i>singleton, built</i>"]:::built
+      #     n2{{"sourced"}}:::root
+      #     n3["db<br/>DB<br/><i>singleton, built</i><br/><i>implemented by (root)</i>"]:::built
+      #     n0 --> n1
+      #     n0 --> n2
+      #     n2 --> n3
+      def to_mermaid
+        nodes = []
+        edges = []
+        add = lambda do |node, name, parent_id, subtree_root|
+          id = "n#{nodes.size}"
+          nodes << "  #{id}#{mermaid_node(node, name, subtree_root)}"
+          edges << "  #{parent_id} --> #{id}" if parent_id
+          node.children.each { |child| add.(child, child.key, id, child.mounted) }
+        end
+        add.(root, root.path || '(root)', nil, true)
+
+        ['flowchart TD', *nodes, *edges, *Mermaid.class_defs(MERMAID_CLASSES)].join("\n")
+      end
+
+      private def mermaid_node(node, name, subtree_root)
+        lines = [Mermaid.escape(name)]
+        unless node.namespace
+          lines << Mermaid.escape(node.type_name)
+          lines << "<i>#{Mermaid.details(node.implemented, node.mode, node.status, node.deferred)}</i>"
+        end
+        lines << "<i>implemented by #{Mermaid.escape(node.implementer || '(root)')}</i>" if node.overridden?
+        label = lines.join('<br/>')
+
+        css_class = if node.namespace then subtree_root ? :root : :namespace
+                    elsif node.implemented then node.status
+                    else :unimplemented
+                    end
+        open, close = if subtree_root then ['{{"', '"}}']
+                      elsif node.namespace then ['("', '")']
+                      else Mermaid.component_shape(node.mode)
+                      end
+        "#{open}#{label}#{close}:::#{css_class}"
+      end
+
+      private def render(nodes, prefix, lines)
+        nodes.each_with_index do |node, i|
+          last = i == nodes.size - 1
+          lines << "#{prefix}#{last ? '└── ' : '├── '}#{label(node, node.key)}"
+          render(node.children, prefix + (last ? '    ' : '│   '), lines)
+        end
+      end
+
+      private def label(node, name)
+        parts = [name]
+        parts << '[mounted]' if node.mounted
+        unless node.namespace
+          parts << node.type_name
+          parts << "(#{[node.implemented ? node.mode : 'not implemented', node.status, ('deferred' if node.deferred)].compact.join(', ')})"
+        end
+        parts << "implemented by #{node.implementer || '(root)'}" if node.overridden?
+        parts.join(' ')
+      end
+    end
+  end
+end

data/lib/sourced/component/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sourced
+  class Component
+    VERSION = "0.1.0"
+  end
+end