Readme (#18)

.rubocop.yml

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

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
+```

lib/zyra/registry.rb

@@ -168,7 +168,7 @@ def on(key, event, &block)
     #     email: email, name: 'final name'
     #   )
     #   # returns a User with name 'initial name'
-    def find_or_create(key, attributes = {}, &block)
+    def find_or_create(key, attributes, &block)
       finder_creator_for(key).find_or_create(attributes, &block)
     end
 

lib/zyra/version.rb

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

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

spec/support/models/post.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Post < ActiveRecord::Base
+  belongs_to :user
+end

spec/support/models/user.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 
 class User < ActiveRecord::Base
+  has_many :posts
 end

spec/support/schema.rb

@@ -7,5 +7,12 @@
     t.string :name
     t.string :email
     t.string :password
+    t.string :reference
+  end
+
+  create_table :posts, force: true do |t|
+    t.integer :user_id
+    t.string :name
+    t.text :content
   end
 end