zyra 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cb11a8449da1cdc0b87c0600b96c3b7e9c76b024b95bc4a722b764570296f50
-  data.tar.gz: 5848a55463e899d78ff4c28dd6ae81993916cd449b3dfd35692bb47f46777452
+  metadata.gz: 7c8f905bbdb0fec56487d7be0a0999983394975cfe3878397ffa7b12f8b43229
+  data.tar.gz: ef03ada86291579a39b0f1dbb9b4bd6dc868090752240522eb22a5c89d6ad559
 SHA512:
-  metadata.gz: 5b13ca88db8dfa338c68f4af3177d39202d2274a88ec0738a7146b59619e6ccb3369277280e0954fe68150e43ed3f8aac1566d95802c79a552b74db340235f96
-  data.tar.gz: ff5cfc24cbc93e90107ec311b1c6baf25c9fc81d9e8aba0bb89ba1f2d876cf93198f6769a5fcf21d3db5db670e4ad399a1762081a41cf21cdd848d46bbf0dc8f
+  metadata.gz: 6132bf64c4fb482e408c24d6e84964bc7862ed31890ee3257608476ee659e63252db0f01602da4afe367ce7a8f6661c65d7099634a9982aa97b20c6d10817d29
+  data.tar.gz: 8b79a9c2f74a31b83e50e98571920f6b3d2e8ac441c58a64e88dd9224a2b5bfe7a5bd043bc5b131c63d2857d6840ff1b9e8f0f1fa1e1009bc213a7fcc808d29b

data/.rubocop.yml

@@ -20,6 +20,7 @@ RSpec/AlignLeftLetBrace:
 RSpec/DescribedClass:
   Exclude:
     - 'spec/integration/yard/**/*_spec.rb'
+    - 'spec/integration/readme/**/*_spec.rb'
 
 RSpec/ExampleLength:
   Exclude:

data/README.md

@@ -9,9 +9,15 @@ Zyra
 
 ![zyra](https://raw.githubusercontent.com/darthjee/zyra/master/zyra.jpg)
 
+Zyra is intented to easy the seeding stage of projects by ensuring an
+entity exists without having to reinsert it every time in the database
+
+The process is done by registering a model class, then performing
+a creation in case of missing the entry
+
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/zyra/0.0.2](https://www.rubydoc.info/gems/zyra/0.0.2)
+[https://www.rubydoc.info/gems/zyra/1.0.0](https://www.rubydoc.info/gems/zyra/1.0.0)
 
 Installation
 ---------------
@@ -31,3 +37,63 @@ Installation
 ```bash
   bundle install zyra
 ```
+
+Usage
+-----
+
+The usage is done by registering a model, adding hooks
+and calling `find_or_create` and passing a block to be executed
+after
+
+```ruby
+  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
+
+  # returns an instance of User that is persisted in the database
+  # user.email is the key as 'usr@srv.com'
+  # user.name will always be updated to 'Some User'
+  # user.password will always be updated to 'pass'
+  # user.reference will be generated in the first time, and never again regenerated
+```
+
+## Hooks
+
+hooks can be registered when registering a model or after to be executed in 4
+points, `found`, `build`, `create` and `return`
+
+```ruby
+  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
+
+  # Returns a User with email 'usr@srv.com'
+  # Creates a post for the user, only in the first time
+  # Regenerates the reference every time the code is ran
+```

data/config/yardstick.yml

@@ -1,4 +1,4 @@
-threshold: 96
+threshold: 100
 require_exact_threshold: false
 rules:
   ApiTag::Presence:
@@ -15,25 +15,17 @@ rules:
     exclude: []
   ExampleTag:
     enabled: true
-    exclude:
-      - Zyra.register
-      - Zyra.after
-      - Zyra.build
-      - Zyra.create
-      - Zyra::Builder#after
-      - Zyra::Builder#build
-      - Zyra::Builder#create
-      - Zyra::Registry#register
+    excludei: []
   ReturnTag:
     enabled: true
-    exclude:
-      - Zyra.after
-      - Zyra.build
-      - Zyra.create
+    exclude: []
   Summary::Presence:
     enabled: true
     exclude:
-      - Zyra::Builder#initialize
+      - Zyra::Finder#initialize
+      - Zyra::Creator#initialize
+      - Zyra::FinderCreator#initialize
+      - Zyra::Registry#initialize
   Summary::Length:
     enabled: true
     exclude: []

data/lib/zyra/{builder.rb → creator.rb}

@@ -5,15 +5,16 @@ module Zyra
   # @author Darthjee
   #
   # Class responsible for building a model
-  class Builder
+  class Creator
     # @param model_class [Class] Model class to be initialized
     #   into a model
-    def initialize(model_class)
+    # @param event_registry [Jace::Registry] event registry to handle events
+    def initialize(model_class, event_registry:)
       @model_class = model_class
+      @event_registry = event_registry
     end
 
-    # @api public
-    # Builds an instance of the registered model class
+    # Creates an instance of the registered model class
     #
     # @param attributes [Hash] attributes to be set in the model
     # @param block [Proc] block to be ran after where more attributes
@@ -22,22 +23,6 @@ module Zyra
     # @yield [Object] Instance of the model class
     #
     # @return [Object] an instance of model class
-    def build(**attributes, &block)
-      block ||= proc {}
-
-      model_class.new(attributes).tap(&block).tap do |model|
-        event_registry.trigger(:build, model)
-      end
-    end
-
-    # @api public
-    # Creates an instance of the registered model class
-    #
-    # This behaves like {#build}, but persists the entry
-    #
-    # @param (see #build)
-    # @yield (see #build)
-    # @return (see #build)
     def create(**attributes, &block)
       model = build(**attributes, &block)
 
@@ -46,44 +31,30 @@ module Zyra
       end
     end
 
-    # @api public
-    # Register a handler on a certain event
-    #
-    # Possible events are +build+, +create+
-    #
-    # @param event [Symbol,String] event to be watched.
-    # @param block [Proc] block to be executed when the event is called
-    #
-    # @yield [Object] the model built
-    #
-    # @return [Builder] the builder itself
-    def after(event, &block)
-      tap { event_registry.register(event, &block) }
-    end
+    protected
 
-    # Checks if another builder is equal to the current builder
-    #
-    # This is used mostly for rspec expectations
-    #
-    # @param other [Object] other object to be compared
+    # @private
+    # Builds an instance of the registered model class
     #
-    # @return [TrueClass,FalseClass]
-    def ==(other)
-      return unless other.class == self.class
+    # @param (see #create)
+    # @yield (see #create)
+    # @return (see #create)
+    def build(**attributes, &block)
+      block ||= proc {}
 
-      other.model_class == model_class
+      model_class.new(attributes).tap(&block).tap do |model|
+        event_registry.trigger(:build, model)
+      end
     end
 
-    protected
-
     # @method model_class
     # @api private
     #
     # Model class to be initialized into a model
     #
     # @return [Class]
-    attr_reader :model_class
 
+    # @method event_registry
     # @private
     #
     # Event registry
@@ -92,8 +63,6 @@ module Zyra
     # post build or creating events
     #
     # @return [Jace::Registry]
-    def event_registry
-      @event_registry ||= Jace::Registry.new
-    end
+    attr_reader :model_class, :event_registry
   end
 end

data/lib/zyra/exceptions.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require 'sinclair'
 require 'jace'
 
 module Zyra
   module Exceptions
-    class BuilderNotRegistered < StandardError; end
+    # Exception returned when a model has not been registered
+    # and there is an attempt to use it
+    class NotRegistered < StandardError; end
   end
 end

data/lib/zyra/finder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Zyra
+  # @api private
+  # @author Darthjee
+  #
+  # Class responsible for finding a model in the DB
+  class Finder
+    # @param model_class [Class] Model class that does the ORM
+    # @param keys [Array<Symbol,String>] keys used when searching
+    #   for the entry
+    # @param event_registry [Jace::Registry] event registry to handle events
+    def initialize(model_class, keys, event_registry:)
+      @model_class = model_class
+      @keys = [keys].flatten.map(&:to_sym)
+      @event_registry = event_registry
+    end
+
+    # Search the entry in the database
+    #
+    # The query is done using part of the expected
+    # attributes filtered by the configured keys}
+    #
+    # if the model is found an event is triggered
+    #
+    # @param attributes [Hash] expected model attribiutes
+    # @param block [Proc] block to be ran after where
+    # more attributes will be set
+    #
+    # @yield [Object] Instance of the model class found
+    #
+    # @return [Object] the model from the database
+    def find(attributes, &block)
+      model = find_by(attributes)
+      return unless model
+
+      block ||= proc {}
+      model.tap(&block)
+
+      event_registry.trigger(:found, model) { model }
+    end
+
+    protected
+
+    # @method model_class
+    # @api private
+    #
+    # Model class to be initialized into a model
+    #
+    # @return [Class]
+
+    # @method keys
+    # @api private
+    #
+    # Keys used when finding a model
+    #
+    # @return [Array<Symbol>]
+
+    # @method event_registry
+    # @private
+    #
+    # Event registry
+    #
+    # The event registry will contain all handlers for
+    # post found events
+    #
+    # @return [Jace::Registry]
+    attr_reader :model_class, :keys, :event_registry
+
+    # private
+    #
+    # Extracts queriable attributes
+    #
+    # The queriable attributes are taken from the expected
+    # attributes filtered by the given keys in the Finder
+    # initialization
+    #
+    # @param (see #find)
+    #
+    # @return [Hash]
+    def query_from(attributes)
+      attributes.symbolize_keys.select do |attribute, _value|
+        keys.include?(attribute)
+      end
+    end
+
+    # @private
+    #
+    # Search the entry in the database
+    #
+    # The query is done using part of the expected
+    # attributes filtered by the configured keys}
+    #
+    # @param (see #find)
+    #
+    # @return (see #find)
+    def find_by(attributes)
+      query = query_from(attributes)
+
+      model_class.find_by(**query)
+    end
+  end
+end

data/lib/zyra/finder_creator.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Zyra
+  # @api private
+  # Class responsible for making sure a model existis
+  #
+  # First, the object searchs in he database by the keys, and
+  # if it fails to finds, it creates a new entry
+  class FinderCreator
+    # @param model_class [Class] Model class that does the ORM
+    # @param keys [Array<Symbol,String>] keys used when searching
+    #   for the entry
+    def initialize(model_class, keys)
+      @model_class = model_class
+      @keys = [keys].flatten.map(&:to_sym)
+    end
+
+    # Ensures an entry exists in the database
+    #
+    # The query happens first by looking in the database
+    # for an entry using {Finder finder}
+    #
+    # The query only takes some attributes into consideration,
+    #
+    # In case no entry is found, a new one is created using all
+    # the given attributes
+    #
+    # @param attributes [Hash] expected attributes
+    # @param block [Proc] block to be ran after where more attributes
+    # will be set
+    #
+    # @yield [Object] Instance of the model class
+    #
+    # @return [Object] An instance of model either from
+    #   database or recently inserted
+    #
+    # @see Zyra::Finder#find
+    # @see Zyra::Creator#create
+    def find_or_create(attributes, &block)
+      model = find(attributes, &block) || create(attributes, &block)
+
+      event_registry.trigger(:return, model) { model }
+    end
+
+    # Register a handler on a certain event
+    #
+    # Possible events are +found+, +build+, +create+
+    # and +return+
+    #
+    # @param event [Symbol,String] event to be watched.
+    #   Current events are +found+, +build+, +create+ and +return+
+    # @param block [Proc] block to be executed when the event is called
+    #
+    # @yield [Object] the model to be returned
+    #
+    # @return [Finder] the finder itself
+    def on(event, &block)
+      tap { event_registry.register(event, &block) }
+    end
+
+    # Checks if another finder creator is equal to the current
+    #
+    # This is used mostly for rspec expectations
+    #
+    # @param other [Object] other object to be compared
+    #
+    # @return [TrueClass,FalseClass]
+    def ==(other)
+      return unless other.class == self.class
+
+      other.model_class == model_class &&
+        other.keys == keys
+    end
+
+    protected
+
+    # @method model_class
+    # @api private
+    #
+    # Model class to be initialized into a model
+    #
+    # @return [Class]
+
+    # @method keys
+    # @api private
+    #
+    # Keys used when finding a model
+    #
+    # @return [Array<Symbol>]
+    attr_reader :model_class, :keys
+
+    # @private
+    #
+    # Event registry
+    #
+    # The event registry will contain all handlers for
+    # post build or creating events
+    #
+    # @return [Jace::Registry]
+    def event_registry
+      @event_registry ||= Jace::Registry.new
+    end
+
+    # @private
+    #
+    # Returns an instance of {Finder}
+    #
+    # Finder will use the same event registry so that event
+    # handling and registration is centralized
+    #
+    # @return Finder
+    def finder
+      @finder ||= Finder.new(model_class, keys, event_registry: event_registry)
+    end
+
+    # @method find(attributes)
+    #
+    # @private
+    # @api private
+    #
+    # Search the entry in the database
+    #
+    # The query is done using part of the expected
+    # attributes filtered by the configured keys}
+    #
+    # if the model is found an event is triggered
+    #
+    # @overload find(attributes)
+    #   @param attributes [Hash] expected model attribiutes
+    #
+    # @return [Object] the model from the database
+    delegate :find, to: :finder
+
+    # @method create(attributes, &block)
+    # @private
+    # @api private
+    #
+    # Creates an instance of the registered model class
+    #
+    # @overload create(attributes, &block)
+    #   @param attributes [Hash] attributes to be set in the model
+    #   @param block [Proc] block to be ran after where more attributes
+    #   will be set
+    #
+    # @yield [Object] Instance of the model class
+    #
+    # @return [Object] an instance of model class
+    delegate :create, to: :creator
+
+    # @private
+    #
+    # Returns an instance of {Creator}
+    #
+    # Creator will use the same event registry so that event
+    # handling and registration is centralized
+    #
+    # @return Creator
+    def creator
+      @creator ||= Creator.new(model_class, event_registry: event_registry)
+    end
+  end
+end