zyra 0.0.1 → 1.1.0

data/lib/zyra/registry.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Zyra
+  # @api public
+  #
+  # Registry of all registered creators
+  class Registry
+    # Register a new creator
+    #
+    # The creator will focus on one class and be registered under a
+    # symbol key
+    #
+    # @param klass [Class] Model class to be used by the creator
+    #
+    # @overload register(klass)
+    #   When the key is not provided, it is infered from the class name
+    #
+    # @overload register(klass, key)
+    #   @param key [String,Symbol] key to be used when storyin the creator
+    #
+    # @return [Zyra::FinderCreator] registered finder_creator
+    #
+    # @example Register models searching
+    #   registry = Zyra::Registry.new
+    #
+    #   registry.register(User, find_by: :email)
+    #   registry
+    #     .register(User, :user_by_name, find_by: :name)
+    #     .on(:return) do |user|
+    #       user.update(email: "#{user.name.gsub(/ /, '_')}@srv.com")
+    #     end
+    #
+    #   attributes = {
+    #     name: 'my name',
+    #     email: 'my_email@srv.com'
+    #   }
+    #
+    #   user = registry.find_or_create(:user, attributes)
+    #   # returns a User with name 'my_email@srv.com'
+    #
+    #   user = registry.find_or_create(:user_by_name, attributes)
+    #   # returns a User with name 'my_name@srv.com'
+    def register(klass, key = nil, find_by:)
+      key ||= klass.name.gsub(/::([A-Z])/, '_\1').downcase
+
+      registry[key.to_sym] = FinderCreator.new(klass, find_by)
+    end
+
+    # Register a handler on a certain event
+    #
+    # Possible events are +found+, +build+, +create+
+    # and +return+
+    #
+    # @param key [String,Symbol] key under which the
+    #   {FinderCreator finder_creator}
+    #   is {Zyra::Registry#register registered}
+    #
+    # @param (see FinderCreator#after)
+    # @yield (see FinderCreator#after)
+    # @return [Finder] The finder registered under that key
+    #
+    # @see Zyra::Finder#find
+    # @see Zyra::Creator#create
+    #
+    # @example Adding a hook on return
+    #   registry = Zyra::Registry.new
+    #   registry.register(User, find_by: :email)
+    #   registry.on(:user, :return) do |user|
+    #     user.update(name: 'initial name')
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = registry.find_or_create(
+    #     :user,
+    #     email: email
+    #   )
+    #   # returns a User with name 'initial name'
+    #
+    #   user.update(name: 'some other name')
+    #
+    #   user = registry.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
+    #
+    # @example Adding a hook on found
+    #   registry = Zyra::Registry.new
+    #   registry.register(User, find_by: :email)
+    #   registry.on(:user, :found) do |user|
+    #     user.update(name: 'final name')
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #   attributes = { email: email, name: 'initial name' }
+    #
+    #   user = registry.find_or_create(:user, attributes)
+    #   # returns a User with name 'initial name'
+    #
+    #   user = registry.find_or_create(:user, attributes)
+    #   # returns a User with name 'final name'
+    #
+    # @example Adding a hook on build
+    #   registry = Zyra::Registry.new
+    #   registry.register(User, find_by: :email)
+    #   registry.on(:user, :build) do |user|
+    #     user.name = 'initial name'
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = registry.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
+    #
+    #   user.update(name: 'some other name')
+    #
+    #   user = registry.find_or_create(:user, email: email)
+    #   # returns a User with name 'some other name'
+    #
+    # @example Adding a hook on create
+    #   registry = Zyra::Registry.new
+    #   registry.register(User, find_by: :email)
+    #   registry.on(:user, :create) do |user|
+    #     user.update(name: 'initial name')
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = registry.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
+    #
+    #   user.update(name: 'some other name')
+    #
+    #   user = registry.find_or_create(:user, email: email)
+    #   # returns a User with name 'some other name'
+    def on(key, event, &block)
+      finder_creator_for(key).on(event, &block)
+    end
+
+    # Builds an instance of the registered model class
+    #
+    # @param key [String,Symbol] key under which the
+    #   {FinderCreator finder_creator}
+    #   is {Zyra::Registry#register registered}
+    #
+    # @param (see FinderCreator#find_or_create)
+    #
+    # @yield (see FinderCreator#find_or_create)
+    #
+    # @return [Object] A model either from the database or just
+    #   inserted into it
+    #
+    # @see #register
+    # @see FinderCreator#find_or_create
+    #
+    # @example Regular usage passing all attributes
+    #   registry = Zyra::Registry.new
+    #   registry.register(User, find_by: :email)
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = registry.find_or_create(
+    #     :user,
+    #     email: email, name: 'initial name'
+    #   )
+    #   # returns a User with name 'initial name'
+    #
+    #   user = registry.find_or_create(
+    #     :user,
+    #     email: email, name: 'final name'
+    #   )
+    #   # returns a User with name 'initial name'
+    def find_or_create(key, attributes, &block)
+      finder_creator_for(key).find_or_create(attributes, &block)
+    end
+
+    private
+
+    # @private
+    # @api private
+    # Returns a registered creator
+    #
+    # when the creator was not registerd, +nil+ is returned
+    #
+    # @param key [String,Symbol] key under which the creator is registered
+    #
+    # @return [Zyra::Creator]
+    def finder_creator_for(key)
+      registry[key.to_sym] ||
+        raise(Exceptions::NotRegistered)
+    end
+
+    # @private
+    # @api private
+    #
+    # Registry store for all creators
+    #
+    # @return [Hash] map of all registered creators
+    def registry
+      @registry ||= {}
+    end
+  end
+end

data/lib/zyra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-class Zyra
-  VERSION = '0.0.1'
+module Zyra
+  VERSION = '1.1.0'
 end

data/lib/zyra.rb

@@ -1,7 +1,193 @@
 # frozen_string_literal: true
 
+require 'active_support'
+require 'active_support/core_ext'
+require 'jace'
+
 # @api public
 # @author darthjee
-class Zyra
+#
+# Zyra allows creators to be registered to ease up
+# seeding
+#
+module Zyra
   autoload :VERSION, 'zyra/version'
+
+  autoload :Creator,       'zyra/creator'
+  autoload :Exceptions,    'zyra/exceptions'
+  autoload :Finder,        'zyra/finder'
+  autoload :FinderCreator, 'zyra/finder_creator'
+  autoload :Registry,      'zyra/registry'
+
+  class << self
+    # @method register(klass, key)
+    # @api public
+    #
+    # Register a new creator
+    #
+    # The creator will focus on one class and be registered under a
+    # symbol key
+    #
+    # @param klass [Class] Model class to be used by the creator
+    #
+    # @overload register(klass)
+    #   When the key is not provided, it is infered from the class name
+    #
+    # @overload register(klass, key)
+    #   @param key [String,Symbol] key to be used when storyin the creator
+    #
+    # @return [Zyra::FinderCreator] registered finder_creator
+    #
+    # @example Register models searching
+    #   registry = Zyra::Registry.new
+    #
+    #   registry.register(User, find_by: :email)
+    #   registry
+    #     .register(User, :user_by_name, find_by: :name)
+    #     .on(:return) do |user|
+    #       user.update(email: "#{user.name.gsub(/ /, '_')}@srv.com")
+    #     end
+    #
+    #   attributes = {
+    #     name: 'my name',
+    #     email: 'my_email@srv.com'
+    #   }
+    #
+    #   user = registry.find_or_create(:user, attributes)
+    #   # returns a User with name 'my_email@srv.com'
+    #
+    #   user = registry.find_or_create(:user_by_name, attributes)
+    #   # returns a User with name 'my_name@srv.com'
+
+    # @method on(key, event, &block)
+    # @api public
+    #
+    # Register a handler on a certain event
+    #
+    # Possible events are +found+, +build+, +create+
+    # and +return+
+    #
+    # @param (see Zyra::Registry#after)
+    # @yield (see Zyra::Registry#after)
+    # @return [Finder] The finder registered under that key
+    #
+    # @example Adding a hook on return
+    #   Zyra.register(User, find_by: :email)
+    #   Zyra.on(:user, :return) do |user|
+    #     user.update(name: 'initial name')
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = Zyra.find_or_create(
+    #     :user,
+    #     email: email
+    #   )
+    #   # returns a User with name 'initial name'
+    #
+    #   user.update(name: 'some other name')
+    #
+    #   user = Zyra.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
+    #
+    # @example Adding a hook on found
+    #   Zyra.register(User, find_by: :email)
+    #   Zyra.on(:user, :found) do |user|
+    #     user.update(name: 'final name')
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #   attributes = { email: email, name: 'initial name' }
+    #
+    #   user = Zyra.find_or_create(:user, attributes)
+    #   # returns a User with name 'initial name'
+    #
+    #   user = Zyra.find_or_create(:user, attributes)
+    #   # returns a User with name 'final name'
+    #
+    # @example Adding a hook on build
+    #   Zyra.register(User, find_by: :email)
+    #   Zyra.on(:user, :build) do |user|
+    #     user.name = 'initial name'
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = Zyra.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
+    #
+    #   user.update(name: 'some other name')
+    #
+    #   user = Zyra.find_or_create(:user, email: email)
+    #   # returns a User with name 'some other name'
+    #
+    # @example Adding a hook on create
+    #   Zyra.register(User, find_by: :email)
+    #   Zyra.on(:user, :create) do |user|
+    #     user.update(name: 'initial name')
+    #   end
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = Zyra.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
+    #
+    #   user.update(name: 'some other name')
+    #
+    #   user = Zyra.find_or_create(:user, email: email)
+    #   # returns a User with name 'some other name'
+
+    # @method find_or_create(key, attributes = {}, &block)
+    # @api public
+    #
+    # Builds an instance of the registered model class
+    #
+    # @param (see Zyra::Registry#after)
+    # @yield (see Zyra::Registry#after)
+    # @return [Object] A model either from the database or just
+    #   inserted into it
+    #
+    # @see .register
+    #
+    # @example Regular usage passing all attributes
+    #   Zyra.register(User, find_by: :email)
+    #
+    #   email = 'email@srv.com'
+    #
+    #   user = Zyra.find_or_create(
+    #     :user,
+    #     email: email, name: 'initial name'
+    #   )
+    #   # returns a User with name 'initial name'
+    #
+    #   user = Zyra.find_or_create(
+    #     :user,
+    #     email: email, name: 'final name'
+    #   )
+    #   # returns a User with name 'initial name'
+    delegate :register, :on, :find_or_create, to: :registry
+
+    # @api private
+    #
+    # Resets the state of the registry
+    #
+    # This is mainly used for testing
+    #
+    # @return [NilClass]
+    def reset
+      @registry = nil
+    end
+
+    private
+
+    # @private
+    # @api private
+    #
+    # Returns the registry containing all the creators
+    #
+    # @return [Registry]
+    def registry
+      @registry ||= Registry.new
+    end
+  end
 end

data/spec/integration/readme/zyra_spec.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Zyra do
+  describe 'readme' do
+    it 'registering a model' do
+      Zyra
+        .register(User, find_by: :email)
+        .on(:build) do |user|
+          user.reference = SecureRandom.hex(16)
+        end
+
+      attributes = {
+        email: 'usr@srv.com',
+        name: 'Some User',
+        password: 'pass'
+      }
+
+      user = Zyra.find_or_create(:user, attributes) do |usr|
+        usr.update(attributes)
+      end
+
+      expect(user.name).to eq('Some User')
+      expect(user.email).to eq('usr@srv.com')
+      expect(user.password).to eq('pass')
+      expect(user.reference).not_to be_nil
+    end
+
+    it 'Registering hooks' do
+      Zyra
+        .register(User, find_by: :email)
+        .on(:build) do |user|
+          user.posts.build(name: 'first', content: 'some content')
+        end
+
+      Zyra.on(:user, :return) do |user|
+        user.update(reference: SecureRandom.hex(16))
+      end
+
+      attributes = {
+        email: 'usr@srv.com',
+        name: 'Some User',
+        password: 'pass'
+      }
+
+      user = Zyra.find_or_create(:user, attributes).reload
+
+      expect(user.email).to eq('usr@srv.com')
+      expect(user.posts).not_to be_empty
+      expect(user.reference).not_to be_nil
+    end
+  end
+end

data/spec/integration/yard/zyra/registry_spec.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Zyra::Registry do
+  describe 'yard' do
+    describe '#register' do
+      it 'Register models searching' do
+        registry = Zyra::Registry.new
+
+        registry.register(User, find_by: :email)
+        registry
+          .register(User, :user_by_name, find_by: :name)
+          .on(:return) do |user|
+            user.update(email: "#{user.name.gsub(/ /, '_')}@srv.com")
+          end
+
+        attributes = {
+          name: 'my name',
+          email: 'my_email@srv.com'
+        }
+
+        user = registry.find_or_create(:user, attributes)
+        expect(user.email).to eq('my_email@srv.com')
+
+        user = registry.find_or_create(:user_by_name, attributes)
+        expect(user.email).to eq('my_name@srv.com')
+      end
+    end
+
+    describe '#find_or_create' do
+      it 'Regular usage passing all attributes' do
+        registry = Zyra::Registry.new
+        registry.register(User, find_by: :email)
+
+        email = 'email@srv.com'
+
+        user = registry.find_or_create(
+          :user,
+          email: email, name: 'initial name'
+        )
+
+        expect(user.name).to eq('initial name')
+
+        user = registry.find_or_create(
+          :user,
+          email: email, name: 'final name'
+        )
+
+        expect(user.name).to eq('initial name')
+      end
+    end
+
+    describe '#on' do
+      it 'Adding a hook on return' do
+        registry = Zyra::Registry.new
+        registry.register(User, find_by: :email)
+        registry.on(:user, :return) do |user|
+          user.update(name: 'initial name')
+        end
+
+        email = 'email@srv.com'
+
+        user = registry.find_or_create(
+          :user,
+          email: email
+        )
+
+        expect(user.name).to eq('initial name')
+        user.update(name: 'some other name')
+
+        user = registry.find_or_create(:user, email: email)
+
+        expect(user.name).to eq('initial name')
+      end
+
+      it 'Adding a hook on found' do
+        registry = Zyra::Registry.new
+        registry.register(User, find_by: :email)
+        registry.on(:user, :found) do |user|
+          user.update(name: 'final name')
+        end
+
+        email = 'email@srv.com'
+        attributes = { email: email, name: 'initial name' }
+
+        user = registry.find_or_create(:user, attributes)
+
+        expect(user.name).to eq('initial name')
+
+        user = registry.find_or_create(:user, attributes)
+
+        expect(user.name).to eq('final name')
+      end
+
+      it 'Adding a hook on build' do
+        registry = Zyra::Registry.new
+        registry.register(User, find_by: :email)
+        registry.on(:user, :build) do |user|
+          user.name = 'initial name'
+        end
+
+        email = 'email@srv.com'
+
+        user = registry.find_or_create(:user, email: email)
+
+        expect(user.name).to eq('initial name')
+        user.update(name: 'some other name')
+
+        user = registry.find_or_create(:user, email: email)
+
+        expect(user.name).to eq('some other name')
+      end
+
+      it 'Adding a hook on create' do
+        registry = Zyra::Registry.new
+        registry.register(User, find_by: :email)
+        registry.on(:user, :create) do |user|
+          user.update(name: 'initial name')
+        end
+
+        email = 'email@srv.com'
+
+        user = registry.find_or_create(:user, email: email)
+
+        expect(user.name).to eq('initial name')
+        user.update(name: 'some other name')
+
+        user = registry.find_or_create(:user, email: email)
+
+        expect(user.name).to eq('some other name')
+      end
+    end
+  end
+end