zyra 0.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00f7455045c5d24031d971b23b6e4aacea3e256de330600fd03993798c447b70
-  data.tar.gz: ab6f1d457d198075c2c41040cfeced8417f003c2ead58f0ac14747e8dddb08b4
+  metadata.gz: 62a10b511a268b79401186b32fb0c25fe60cfbe062770f8d6de2d97a6dfee4ea
+  data.tar.gz: 9f5a45fc0216b1e65a7d2f5482a05087ef78787accf8c5e940bf26794e5ca7bb
 SHA512:
-  metadata.gz: fb9d2ef90e2ab27699c3dbb97b24a651e8341e6064eeb1a7e9497775039f3fc551c2f1f513b7bd44e301b63ef18c1d8fe556cd7c01ff284e71699cab6f3b3e02
-  data.tar.gz: 61ac5329ed5bc9f015415bca09336be77580a9eb746d4f40bf88bee4696bb5893257ea91912dc3e3e318436a01952c6e1738566775971f5471a39f39d35fd4ba
+  metadata.gz: 0c63b3d56aec07eacdc683fb8c8084ddb1a5f8c45011bcd8f85ce43a08df85c7d412482256075539038b266d7678dfe36a019dd36267402b8bc625ec4c821a71
+  data.tar.gz: bc6e5d3e3a3d3695716b048c40ea29bfeb43e62f3ffd192fb94f5887526acba84b28dcabaed422d1dd9c9e8caaa9a4b5d51528ac0504a5146b1cb79b8816c548

data/.circleci/config.yml

@@ -7,8 +7,12 @@ workflows:
           filters:
             tags:
               only: /.*/
+      - checks:
+          filters:
+            tags:
+              only: /.*/
       - build-and-release:
-          requires: [test]
+          requires: [test, checks]
           filters:
             tags:
               only: /\d+\.\d+\.\d+/
@@ -18,7 +22,7 @@ workflows:
 jobs:
   test:
     docker:
-      - image: darthjee/circleci_ruby_270:1.1.0
+      - image: darthjee/circleci_rails_gems:1.1.0
         environment:
           PROJECT: zyra
     steps:
@@ -32,12 +36,22 @@ jobs:
       - run:
           name: RSpec
           command: bundle exec rspec
-      - run:
-          name: Rubocop
-          command: rubocop
       - run:
           name: Coverage Test Report
           command: cc-test-reporter after-build --exit-code $?
+  checks:
+    docker:
+      - image: darthjee/circleci_rails_gems:1.1.0
+        environment:
+          PROJECT: zyra
+    steps:
+      - checkout
+      - run:
+          name: Bundle Install
+          command: bundle install
+      - run:
+          name: Rubocop
+          command: rubocop
       - run:
           name: Yardstick coverage check
           command: bundle exec rake verify_measurements
@@ -52,7 +66,7 @@ jobs:
           command: check_specs
   build-and-release:
     docker:
-      - image: darthjee/circleci_ruby_270:1.1.0
+      - image: darthjee/circleci_rails_gems:1.1.0
         environment:
           PROJECT: zyra
     steps:

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/Dockerfile

@@ -1,6 +1,6 @@
 FROM darthjee/scripts:0.3.1 as scripts
 
-FROM darthjee/ruby_270:1.1.0 as base
+FROM darthjee/rails_gems:1.1.0 as base
 
 COPY --chown=app:app ./ /home/app/app/
 

data/Dockerfile.circleci

@@ -0,0 +1,7 @@
+FROM darthjee/scripts:0.3.1 as scripts
+
+FROM darthjee/circleci_rails_gems:1.1.0 as base
+
+COPY --chown=circleci:circleci ./ /home/circleci/project/
+
+RUN bundle install

data/README.md

@@ -1,4 +1,4 @@
-Jace
+Zyra
 ====
 [![Code Climate](https://codeclimate.com/github/darthjee/zyra/badges/gpa.svg)](https://codeclimate.com/github/darthjee/zyra)
 [![Test Coverage](https://codeclimate.com/github/darthjee/zyra/badges/coverage.svg)](https://codeclimate.com/github/darthjee/zyra/coverage)
@@ -9,9 +9,15 @@ Jace
 
 ![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.1](https://www.rubydoc.info/gems/zyra/0.0.1)
+[https://www.rubydoc.info/gems/zyra/1.1.0](https://www.rubydoc.info/gems/zyra/1.1.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/check_specs.yml

@@ -1,2 +1,3 @@
 ignore:
   - lib/zyra/version.rb
+  - lib/zyra/exceptions.rb

data/config/yardstick.yml

@@ -15,13 +15,17 @@ rules:
     exclude: []
   ExampleTag:
     enabled: true
-    exclude: []
+    excludei: []
   ReturnTag:
     enabled: true
     exclude: []
   Summary::Presence:
     enabled: true
-    exclude: []
+    exclude:
+      - Zyra::Finder#initialize
+      - Zyra::Creator#initialize
+      - Zyra::FinderCreator#initialize
+      - Zyra::Registry#initialize
   Summary::Length:
     enabled: true
     exclude: []

data/docker-compose.yml

@@ -21,3 +21,14 @@ services:
     <<: *base
     depends_on: [base_build]
     command: /bin/bash -c 'rspec && yard && rake yardstick_measure && rake verify_measurements'
+
+  circleci:
+    <<: *base
+    build:
+      context: ./
+      dockerfile: Dockerfile.circleci
+    command: echo done
+    image: zyra_circleci
+    working_dir: /home/circleci/project
+    volumes:
+      - .:/home/circleci/project

data/lib/zyra/creator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Zyra
+  # @api private
+  # @author Darthjee
+  #
+  # Class responsible for building a model
+  class Creator
+    # @param model_class [Class] Model class to be initialized
+    #   into a model
+    # @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
+
+    # 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
+    # will be set
+    #
+    # @yield [Object] Instance of the model class
+    #
+    # @return [Object] an instance of model class
+    def create(**attributes, &block)
+      block ||= proc {}
+
+      model = build(**attributes)
+
+      event_registry.trigger(:create, model) do
+        model.tap(&:save).tap(&block)
+      end
+    end
+
+    protected
+
+    # @private
+    # Builds an instance of the registered model class
+    #
+    # @param (see #create)
+    # @yield (see #create)
+    # @return (see #create)
+    def build(**attributes)
+      model_class.new(attributes).tap do |model|
+        event_registry.trigger(:build, model)
+      end
+    end
+
+    # @method model_class
+    # @api private
+    #
+    # Model class to be initialized into a model
+    #
+    # @return [Class]
+
+    # @method event_registry
+    # @private
+    #
+    # Event registry
+    #
+    # The event registry will contain all handlers for
+    # post build or creating events
+    #
+    # @return [Jace::Registry]
+    attr_reader :model_class, :event_registry
+  end
+end

data/lib/zyra/exceptions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'jace'
+
+module Zyra
+  module Exceptions
+    # 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