pakyow-ui 0.10.0

data/pakyow-ui/lib/pakyow-ui/mutable.rb

@@ -0,0 +1,99 @@
+require_relative 'mutable_data'
+
+# TODO: make it possible to register this as data instead of mutables
+
+module Pakyow
+  module UI
+    # Mutables enable PakyowUI to automatically handle changes in application
+    # state by interacting with the data layer in a declarative manner.
+    #
+    # Wraps a data source (such as a model object) and provides a convenient
+    # interface for defining and executing queries and actions. Queries accept
+    # parameters and return data sets. Actions cause a state change in
+    # application state.
+    #
+    # Once defined, all interactions with the data layer should occur through
+    # Mutables via the `data` helper method. When an action is performed that
+    # changes the state of the application, Pakyow will propogate the change
+    # through to all other connected clients automatically.
+    #
+    # Mutables should be registered with the `Pakyow::App.mutable` helper. The
+    # defined block will be executed in context of a `Mutable` instance.
+    #
+    # @api public
+    class Mutable
+      include Helpers
+
+      attr_reader :context
+
+      # @api private
+      def initialize(context, scope, &block)
+        @context = context
+        @scope   = scope
+        @actions = {}
+        @queries = {}
+
+        instance_exec(&block)
+      end
+
+      # Sets the model object.
+      #
+      # @api public
+      def model(model_class, type: nil)
+        @model_class = model_class
+
+        return if type.nil?
+        @model_type = type
+
+        # TODO: load default actions / queries based on type
+      end
+
+      # Defines an action.
+      #
+      # @api public
+      def action(name, mutation: true, &block)
+        @actions[name] = {
+          block: block,
+          mutation: mutation
+        }
+      end
+
+      # Defines a query.
+      #
+      # @api public
+      def query(name, &block)
+        @queries[name] = block
+      end
+
+      # Handles calling queries or actions. Enables convenience like:
+      #
+      # data(:some_data).{action or query}
+      #
+      # @api public
+      def method_missing(method, *args)
+        action = @actions[method]
+        query = @queries[method]
+
+        if action
+          call_action(action, *args)
+        elsif query
+          call_query(query, method, *args)
+        else
+          fail ArgumentError, "Could not find query or action named #{method}"
+        end
+      end
+
+      private
+
+      def call_action(action, *args)
+        result = action[:block].call(*args)
+        @context.ui.mutated(@scope, result, @context) if action[:mutation]
+        result
+      end
+
+      def call_query(query, method, *args)
+        MutableData.new(query, method, args, @scope)
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/mutable_data.rb

@@ -0,0 +1,21 @@
+module Pakyow
+  module UI
+    # Adds metadata to a dataset returned by a Mutable query.
+    #
+    # @api private
+    class MutableData
+      attr_reader :query_name, :query_args, :scope
+
+      def initialize(query, query_name, query_args, scope)
+        @query = query
+        @query_name = query_name
+        @query_args = query_args
+        @scope = scope
+      end
+
+      def data
+        @data ||= @query.call(*@query_args)
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/mutate_context.rb

@@ -0,0 +1,79 @@
+require_relative 'channel_builder'
+
+module Pakyow
+  module UI
+    # Provides helper methods to perform in context of a mutation. For example:
+    #
+    # view.scope(:foo).mutate(:bar).subscribe
+    #
+    # In the above example `mutate` returns a MutateContext object on which
+    # `subscribe` is called.
+    #
+    # @api public
+    class MutateContext
+      attr_reader :mutation, :view, :data
+
+      # Creates a new context. Intended to be created by a Mutator.
+      #
+      # @api private
+      def initialize(mutation, view, data)
+        @mutation = mutation
+        @view     = view
+        @data     = data
+      end
+
+      # Subscribes a mutation with optional qualifications. Qualifications are
+      # used to control the scope of future mutations. For example:
+      #
+      # view.scope(:foo).mutate(:bar).subscribe(user_id: 1)
+      #
+      # In the above example, a subscription is created qualified by `user_id`.
+      # Only mutations occuring with the same qualifications will cause the
+      # mutation to be performed again, triggering a view refresh.
+      #
+      # ui.mutated(:foo, user_id: 1)
+      #
+      # @api public
+      def subscribe(qualifications = {})
+        if data.is_a?(MutableData)
+          MutationStore.instance.register(self, data, qualifications)
+        end
+
+        channel = ChannelBuilder.build(
+          scope: view.scoped_as,
+          mutation: mutation[:name],
+          qualifiers: mutation[:qualifiers],
+          data: data,
+          qualifications: qualifications
+        )
+
+        # subscribe to the channel
+        view.context.socket.subscribe(channel)
+
+        # handle setting the channel on the view
+        if view.is_a?(Presenter::ViewContext)
+          working_view = view.instance_variable_get(:@view)
+        else
+          working_view = view
+        end
+
+        if working_view.is_a?(Presenter::ViewCollection)
+          # NOTE there's a special case here where if the collection is
+          # empty we insert an empty element in its place; this makes
+          # it possible to know what the data should be applied to when
+          # a mutation occurs in the future
+
+          unless working_view.exists?
+            # TODO: would rather this be an html comment, but they aren't
+            # supported by query selectors; need to finalize how we will
+            # handle this particular edge case
+            working_view.first.doc.append('<span data-channel="' + channel + '" data-version="empty"></span>')
+            return
+          end
+        end
+
+        working_view.attrs.send(:'data-channel=', channel)
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/mutation_set.rb

@@ -0,0 +1,38 @@
+module Pakyow
+  module UI
+    # Stores mutations.
+    #
+    # @api private
+    class MutationSet
+      attr_reader :mutations
+
+      def initialize(&block)
+        @mutations = {}
+        instance_exec(&block)
+      end
+
+      # NOTE I do have some concerns about defining qualifiers in this way;
+      # mainly because it will lead to having lots of versions of the same
+      # mutator just so the proper channels will be created.
+      #
+      # It's could end up being better to pass qualifiers to `subscribe`;
+      # however it feels premature to make this decision since it'll lead
+      # to a large increase in complexity to add at this point.
+      def mutator(name, qualify: [], &block)
+        @mutations[name] = {
+          fn: block,
+          qualifiers: Array.ensure(qualify),
+          name: name
+        }
+      end
+
+      def mutation(name)
+        @mutations.fetch(name)
+      end
+
+      def each(&block)
+        @mutations.each(&block)
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/mutation_store.rb

@@ -0,0 +1,30 @@
+module Pakyow
+  module UI
+    # Stores mutations that have occurred in the configured registry.
+    #
+    # @api private
+    class MutationStore
+      include Singleton
+
+      def initialize
+        @registry = Config.ui.registry.instance
+      end
+
+      def register(mutate_context, mutable_data, qualifications)
+        # TODO: decide how we'll clean these up as clients disconnect
+        @registry.register(
+          mutable_data.scope,
+          mutation: mutate_context.mutation[:name],
+          qualifiers: mutate_context.mutation[:qualifiers],
+          qualifications: qualifications,
+          query_name: mutable_data.query_name,
+          query_args: mutable_data.query_args
+        )
+      end
+
+      def mutations(scope)
+        @registry.mutations(scope) || []
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/mutator.rb

@@ -0,0 +1,63 @@
+require_relative 'mutation_set'
+require_relative 'mutate_context'
+
+module Pakyow
+  module UI
+    # Performs mutations on views.
+    #
+    # @api private
+    class Mutator
+      include Singleton
+
+      attr_reader :sets
+
+      # @api private
+      def initialize
+        reset
+      end
+
+      def reset
+        @sets = {}
+        @mutables = {}
+        self
+      end
+
+      def set(scope, &block)
+        @sets[scope] = MutationSet.new(&block)
+      end
+
+      def mutable(scope, context = nil, &block)
+        if block_given?
+          @mutables[scope] = block
+        else
+          # TODO: inefficient to have to execute the block each time
+          Mutable.new(context, scope, &@mutables[scope])
+        end
+      end
+
+      def mutation(scope, name)
+        if mutations = mutations_by_scope(scope)
+          mutations.mutation(name)
+        end
+      end
+
+      # TODO: rename to mutation_set_for_scope
+      def mutations_by_scope(scope)
+        @sets[scope]
+      end
+
+      def mutate(mutation_name, view, data)
+        if mutation = mutation(view.scoped_as, mutation_name)
+          if data.is_a?(MutableData)
+            working_data = data.data
+          else
+            working_data = data
+          end
+
+          result = mutation[:fn].call(view, working_data)
+          MutateContext.new(mutation, result, data)
+        end
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/no_op_view.rb

@@ -0,0 +1,87 @@
+require_relative 'mock_mutation_eval'
+
+module Pakyow
+  module Presenter
+    # Stands in for a real View object and makes any attempted transformation
+    # a no-op.
+    #
+    # @api private
+    class NoOpView
+      include Helpers
+      VIEW_CLASSES = [ViewContext]
+
+      # The arities of misc view methods that switch the behavior from
+      # instance_exec to yield.
+      #
+      EXEC_ARITIES = { with: 0, for: 1, for_with_index: 2, repeat: 1,
+                       repeat_with_index: 2, bind: 1, bind_with_index: 2,
+                       apply: 1 }
+
+      def initialize(view, context)
+        @view = view
+        @context = context
+      end
+
+      def is_a?(klass)
+        @view.is_a?(klass)
+      end
+
+      # View methods that should be a no-op
+      #
+      %i(bind bind_with_index apply).each do |method|
+        define_method(method) do |_data, **_kargs, &_block|
+          self
+        end
+      end
+
+      def mutate(mutator, with: nil, data: nil)
+        MockMutationEval.new(mutator, with || data, self)
+      end
+
+      # Pass these through, handling the return value.
+      #
+      def method_missing(method, *args, &block)
+        ret = @view.send(method, *args, &wrap(method, &block))
+        handle_return_value(ret)
+      end
+
+      private
+
+      def view?(obj)
+        VIEW_CLASSES.include?(obj.class)
+      end
+
+      # Returns a new context for returned views, or the return value.
+      #
+      def handle_return_value(value)
+        return NoOpView.new(value, @context) if view?(value)
+
+        value
+      end
+
+      # Wrap the block, substituting the view with the current view context.
+      #
+      def wrap(method, &block)
+        return if block.nil?
+
+        proc do |*args|
+          ctx = args.map! { |arg|
+            view?(arg) ? NoOpView.new(arg, @context) : arg
+          }.find { |arg| arg.is_a?(ViewContext) }
+
+          case block.arity
+          when EXEC_ARITIES[method]
+            # Rejecting ViewContext handles the edge cases around the order of
+            # arguments from view methods (since view is not present in some
+            # situations and when it is present, is always the first arg).
+            ctx.instance_exec(*args.reject { |arg|
+              arg.is_a?(ViewContext)
+            }, &block)
+          else
+            block.call(*args)
+          end
+        end
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/registries/redis_mutation_registry.rb

@@ -0,0 +1,34 @@
+require 'json'
+
+module Pakyow
+  module UI
+    # Manages mutations.
+    #
+    # This is the default registry in production systems and is required in
+    # deployments with more than one app instance.
+    #
+    # @api private
+    class RedisMutationRegistry
+      include Singleton
+
+      def initialize
+      end
+
+      def register(scope, mutation)
+        Pakyow::Realtime.redis.sadd(key(scope), mutation.to_json)
+      end
+
+      def mutations(scope)
+        Pakyow::Realtime.redis.smembers(key(scope)).map do |m|
+          Hash.strhash(JSON.parse(m))
+        end
+      end
+
+      private
+
+      def key(scope)
+        "pui-mutation-#{scope}"
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/registries/simple_mutation_registry.rb

@@ -0,0 +1,31 @@
+module Pakyow
+  module UI
+    # Manages mutations.
+    #
+    # Intended only for use in development or single app-instance deployments.
+    #
+    # @api private
+    class SimpleMutationRegistry
+      include Singleton
+
+      def initialize
+        reset
+      end
+
+      def reset
+        @mutations = {}
+      end
+
+      def register(scope, mutation)
+        @mutations[scope] ||= []
+
+        return if @mutations[scope].include?(mutation)
+        @mutations[scope] << mutation
+      end
+
+      def mutations(scope)
+        @mutations[scope]
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/ui.rb

@@ -0,0 +1,83 @@
+require_relative 'mutator'
+require_relative 'channel_builder'
+require_relative 'ui_view'
+
+module Pakyow
+  module UI
+    # The UI context available during routing.
+    #
+    # @api public
+    class UI
+      attr_accessor :context
+      attr_reader :mutator
+
+      # Informs Pakyow that a mutation has occurred in application state,
+      # triggering all the necessary realtime view updates.
+      #
+      # @api public
+      def mutated(scope, data = nil, context = nil)
+        context ||= @context
+
+        MutationStore.instance.mutations(scope).each do |mutation|
+          view = UIView.new(scope)
+
+          qualified = true
+
+          # qualifiers are defined with the mutation
+          unless mutation[:qualifiers].empty? || data.nil?
+            mutation[:qualifiers].each_with_index do |qualifier, i|
+              qualified = false unless data[qualifier] == mutation[:query_args][i]
+            end
+          end
+
+          qualified = false if data.nil? && !mutation[:qualifications].empty?
+
+          # qualifications are set on the subscription
+          unless !qualified || mutation[:qualifications].empty? || data.nil?
+            mutation[:qualifications].each_pair do |key, value|
+              qualified = false unless data[key] == value
+            end
+          end
+
+          next unless qualified
+
+          mutable_data = Mutator.instance.mutable(scope, context).send(mutation[:query_name], *mutation[:query_args]).data
+          Mutator.instance.mutate(mutation[:mutation].to_sym, view, mutable_data)
+
+          Pakyow.app.socket.push(
+            view.finalize,
+
+            ChannelBuilder.build(
+              scope: scope,
+              mutation: mutation[:mutation].to_sym,
+              qualifiers: mutation[:qualifiers],
+              data: mutable_data,
+              qualifications: mutation[:qualifications]
+            )
+          )
+        end
+      end
+
+      # Addresses a component rendered on the client-side.
+      #
+      # @api public
+      def component(name, qualifications = {})
+        UIComponent.new(name, qualifications)
+      end
+
+      # @api private
+      def load(mutators, mutables)
+        # TODO: this is another pattern I see all over the place
+        @mutator = Mutator.instance.reset
+
+        mutators.each_pair do |scope, block|
+          @mutator.set(scope, &block)
+        end
+
+        mutables.each_pair do |scope, block|
+          @mutator.mutable(scope, &block)
+        end
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/ui_attrs.rb

@@ -0,0 +1,40 @@
+require_relative 'ui_instructable'
+
+module Pakyow
+  module UI
+    # Builds up instructions for changing view attributes.
+    #
+    # @api private
+    class UIAttrs
+      include Instructable
+
+      def nested_instruct_object(_method, _data, _scope)
+        UIAttrs.new
+      end
+
+      def method_missing(method, value)
+        nested_instruct(method, value)
+      end
+
+      def class
+        method_missing(:class, nil)
+      end
+
+      def id
+        method_missing(:id, nil)
+      end
+
+      def <<(value)
+        method_missing(:insert, value)
+      end
+
+      def []=(method, value)
+        method_missing(method, value)
+      end
+
+      def [](method)
+        method_missing(method, nil)
+      end
+    end
+  end
+end

data/pakyow-ui/lib/pakyow-ui/ui_component.rb

@@ -0,0 +1,68 @@
+require_relative 'ui_instructable'
+
+module Pakyow
+  module UI
+    # An object for interacting with components rendered in a browser. Custom
+    # messages can be pushed and will be handled by the event listener defined
+    # on the client-side component.
+    #
+    # It's also possible to perform view transformations in realtime. Components
+    # implement a subset of transformations, including `scope` and `append`.
+    # This allows for finer control over particular components, completely
+    # bypassing mutables and mutators.
+    #
+    # @api public
+    class UIComponent
+      include Instructable
+
+      attr_reader :name, :view, :qualifications
+
+      # Intended to be created through the `ui.component` helper.
+      #
+      # @api private
+      def initialize(name, qualifications = {})
+        super()
+        @name = name
+        @qualifications = qualifications
+      end
+
+      # Pushes a message to the component.
+      #
+      # @api public
+      def push(payload = nil)
+        payload ||= { instruct: (root || self).finalize }
+
+        Pakyow.app.socket.push(
+          payload,
+
+          ChannelBuilder.build(
+            component: name,
+            qualifications: qualifications
+          )
+        )
+      end
+
+      # Narrows the scope of component instructions.
+      #
+      # @api public
+      def scope(name)
+        nested_instruct(:scope, name.to_s, name)
+      end
+
+      # Other supported transformation methods.
+      #
+      # @api public
+      %i(append prepend).each do |method|
+        define_method method do |value|
+          instruct(method, value)
+          push
+        end
+      end
+
+      # @api private
+      def nested_instruct_object(_method, _data, _scope)
+        UIComponent.new(name, qualifications)
+      end
+    end
+  end
+end