zyra 0.0.2 → 1.0.0

data/lib/zyra/registry.rb

@@ -1,33 +1,199 @@
 # frozen_string_literal: true
 
 module Zyra
-  # @api private
+  # @api public
   #
-  # Registry of all registered builders
+  # Registry of all registered creators
   class Registry
-    # (see Zyra.register)
-    def register(klass, key = klass.name.gsub(/::([A-Z])/, '_\1').downcase)
-      registry[key.to_sym] = Builder.new(klass)
+    # 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
 
-    # Returns a registered builder
+    # Builds an instance of the registered model class
     #
-    # when the builder was not registerd, +nil+ is returned
+    # @param key [String,Symbol] key under which the
+    #   {FinderCreator finder_creator}
+    #   is {Zyra::Registry#register registered}
     #
-    # @param key [String,Symbol] key under which the builder is registered
+    # @param (see FinderCreator#find_or_create)
     #
-    # @return [Zyra::Builder]
-    def builder_for(key)
-      registry[key.to_sym]
+    # @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 builders
+    # Registry store for all creators
     #
-    # @return [Hash] map of all registered builders
+    # @return [Hash] map of all registered creators
     def registry
       @registry ||= {}
     end

data/lib/zyra/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zyra
-  VERSION = '0.0.2'
+  VERSION = '1.0.0'
 end

data/lib/zyra.rb

@@ -1,84 +1,171 @@
 # frozen_string_literal: true
 
-require 'sinclair'
+require 'active_support'
+require 'active_support/core_ext'
 require 'jace'
 
 # @api public
 # @author darthjee
 #
-# Zyra allows builders to be registered to ease up
+# Zyra allows creators to be registered to ease up
 # seeding
+#
 module Zyra
   autoload :VERSION, 'zyra/version'
 
-  autoload :Builder,    'zyra/builder'
-  autoload :Exceptions, 'zyra/exceptions'
-  autoload :Registry,   'zyra/registry'
+  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
+    # @method register(klass, key)
     # @api public
     #
-    # Register a new builder
+    # Register a new creator
     #
-    # The builder will focus on one class and be registered under a
+    # The creator will focus on one class and be registered under a
     # symbol key
     #
-    # @param klass [Class] Model class to be used by the builder
+    # @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 builder
+    #   @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'
+    #   }
     #
-    # @return [Zyra::Builder] registered builder
-    delegate :register, to: :registry
+    #   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 +build+, +create+
+    # Possible events are +found+, +build+, +create+
+    # and +return+
     #
-    # @param key [String,Symbol] key under which the {Builder builder}
-    #   is {Registry registered}
-    # @param (see Builder#after)
+    # @param (see Zyra::Registry#after)
+    # @yield (see Zyra::Registry#after)
+    # @return [Finder] The finder registered under that key
     #
-    # @yield [Object] the model built
+    # @example Adding a hook on return
+    #   Zyra.register(User, find_by: :email)
+    #   Zyra.on(:user, :return) do |user|
+    #     user.update(name: 'initial name')
+    #   end
     #
-    # @return (see Builder#after)
-    def after(key, event, &block)
-      builder_for(key).after(event, &block)
-    end
-
-    # Builds an instance of the registered model class
+    #   email = 'email@srv.com'
     #
-    # @param key [String,Symbol] key under which the {Builder builder}
-    #   is {Registry registered}
-    # @param (see Builder#build)
+    #   user = Zyra.find_or_create(
+    #     :user,
+    #     email: email
+    #   )
+    #   # returns a User with name 'initial name'
     #
-    # @yield (see Builder#build)
+    #   user.update(name: 'some other name')
     #
-    # @return (see Builder#build)
+    #   user = Zyra.find_or_create(:user, email: email)
+    #   # returns a User with name 'initial name'
     #
-    # @see .register
-    # @see Builder#build
-    def build(key, **attributes, &block)
-      builder_for(key).build(**attributes, &block)
-    end
+    # @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'
 
-    # Creates an instance of the registered model class
+    # @method find_or_create(key, attributes = {}, &block)
+    # @api public
     #
-    # This behaves like {.build}, but persists the entry
+    # Builds an instance of the registered model class
     #
-    # @param (see .build)
-    # @yield (see .build)
-    # @return (see .build)
+    # @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
-    # @see Builder#create
-    def create(key, **attributes, &block)
-      builder_for(key).create(**attributes, &block)
-    end
+    #
+    # @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
     #
@@ -96,20 +183,7 @@ module Zyra
     # @private
     # @api private
     #
-    # Returns a registered builder for a key
-    #
-    # @param key [String,Symbol] key under which the {Builder builder}
-    #   is {Registry registered}
-    #
-    # @return [Builder]
-    def builder_for(key)
-      registry.builder_for(key) || raise(Exceptions::BuilderNotRegistered)
-    end
-
-    # @private
-    # @api private
-    #
-    # Returns the registry containing all the builders
+    # Returns the registry containing all the creators
     #
     # @return [Registry]
     def registry

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