nifty_services 0.0.5 → 0.0.6

data/docs/i18n.md

@@ -0,0 +1,55 @@
+# NiftyServices documentation
+
+---
+
+## :us: :fr: :jp: I18n Support :uk: :es: :de:
+
+As you see in the above examples, with `NiftyServices` you can respond in multiples languages for the same service error messages, by default your locales config file must be configured as:
+
+```yml
+ # attention: dont use `resource_type`
+ # use the key setup up in `record_error_key` methods
+ resource_type:
+   not_found: "Invalid or not found post"
+      cant_create: "Can't delete this record"
+      cant_read: "Can't access this record"
+      cant_update: "Can't delete this record"
+      cant_delete: "Can't delete this record"
+ users:
+   not_found: "Invalid or not found user"
+```
+
+You can configure the default I18n namespace using configuration:
+
+```ruby
+NiftyServies.configure do |config|
+  config.i18n_namespace = :my_app
+end
+```
+
+Example config for `Post` and `Comment` resources using `my_app` locale namespace:
+
+```yml
+# default is nifty_services
+my_app:
+ errors:
+  default_crud: &default_crud
+    cant_create: "Can't delete this record"
+    cant_read: "Can't access this record"
+    cant_update: "Can't delete this record"
+    cant_delete: "Can't delete this record"
+  users:
+   not_found: "Invalid or not found user"
+  posts:
+    <<: *default_crud
+    not_found: "Invalid or not found post"
+  comments:
+    <<: *default_crud
+    not_found: "Invalid or not found comment"
+```
+
+---
+
+### Next
+
+See [Callbacks](./callbacks.md)

data/docs/services_markup.md

@@ -0,0 +1,271 @@
+# NiftyServices documentation
+
+---
+
+## :pray: Basic Service Markups :raised_hands:
+
+Here, for your convenience and sanity all basic service structures for reference when you start a brand new Service.
+Most of time, the best way is to copy all content from each service described below and change according to your needs.
+
+### BaseCreateService Basic Markup
+
+```ruby
+class SomeCreateService < NiftyServices::BaseCreateService
+  # [Required]
+  # remember that inside the Service you always can use
+  # @record variable to access current record
+  # and from outside (service instance):
+  # service.record or service.record_type
+  # eg:
+  # record_type BlogPost
+  # service.record # BlogPost.new(...)
+  # service.blog_post # BlogPost.new(...)
+  # service.record == service.blog_post # true
+  # alias_name can be used to create a custom alias name
+  # eg:
+  # record_type BlogPost, alias_name: :post
+  # service.record # BlogPost.new(...)
+  # service.post # BlogPost.new(...)
+  # service.record == service.post # true
+
+  record_type RecordType, alias_name: :my_custom_alias_name
+
+  ## Its a good convention to create a constant and not returning the plain
+  ## array in `record_attributes_whitelist` since this can be accessed from others
+  ## places, as: `SomeCreateService::WHITELIST_ATTRIBUTES`
+  WHITELIST_ATTRIBUTES = [
+    :safe_attribute_1,
+    :safe_attribute_2,
+  ]
+
+  # [Required]
+  # You must setup whitelist attributes or define the method `record_attributes_whitelist` method
+  whitelist_attributes WHITELIST_ATTRIBUTES
+
+  # You can freely override initialize method to receive more arguments
+  def initialize(record, user, options = {})
+    @user = user
+    super(record, options)
+  end
+
+  private
+  # [Optional]
+  # this key is used for I18n translations, you don't need to override or implement
+  # NiftyService will try to inflect this using `record_type.to_s.underscore + 's'`
+
+  # So, if your record type is `Post`, `record_error_key` will be `posts`
+  def record_error_key
+    :posts
+  end
+
+  # [Required]
+  # Always validate if service can be executed based on your rules and ACL
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def can_create_record?
+    unless valid_user?
+      return not_found_error!('users.not_found')
+    end
+
+    return forbidden_error!('errors.some_error') if (some_validation)
+
+    return bad_request_error!('errors.some_other_error') if (another_validation)
+
+    # remember to return true after all validations
+    # if you don't return true Service will not be able to create the record
+    return true
+  end
+
+  # [Optional]
+  # method called when save_error method call raises an exception
+  # this ocurr for example with ActiveRecord objects
+  # default: unprocessable_entity_error!(error)
+  def on_save_record_error(error)
+    logger.error(error)
+
+    if error.is_a?(ActiveRecord::RecordNotUnique)
+     return unprocessable_entity_error!(%s(posts.duplicate_record))
+    end
+  end
+
+  # [Optional]
+  # custom scope for record, eg: @user.posts
+  # default is nil
+  def build_record_scope
+   nil
+  end
+
+  def valid_user?
+    valid_object?(@user, User)
+  end
+end
+```
+
+### BaseUpdateService Basic Markup
+
+```ruby
+class SomeUpdateService < NiftyServices::BaseUpdateService
+  
+  attr_reader :user
+
+  # [Required]
+  record_type RecordType, alias_name: :custom_alias_name
+  
+  # You can freely override initialize method to receive more arguments
+  def initialize(record, user, options = {})
+    @user = user
+    super(record, options)
+  end
+
+  ## Its a good convention to create a constant and not returning the plain
+  ## array in `record_attributes_whitelist` since this can be accessed from others
+  ## places, as: `SomeCreateService::WHITELIST_ATTRIBUTES`
+  WHITELIST_ATTRIBUTES = [
+    :safe_attribute_1,
+    :safe_attribute_2,
+  ]
+
+  # [Required]
+  # You must setup whitelist attributes or define the method `record_attributes_whitelist` method
+  whitelist_attributes WHITELIST_ATTRIBUTES
+
+  private
+
+  # [Required]
+  # When a new instance of Service is created, the @options variables receive some
+  # values, eg: { user: { email: "...", name: "...."} }
+  # use record_attributes_hash to tell the Service from where to pull theses values
+  # eg: @options.fetch(:user, {})
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def record_attributes_hash
+    @options.fetch(:data, {})
+  end
+
+  # [required]
+  # This is a VERY IMPORTANT point of attention
+  # always verify if @user has permissions to update the current @record object
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def can_update_record?
+    @record.user_id == @user.id
+  end
+
+  # [Optional]
+  # This is the default implementation of update record, you may overwrite it
+  # to to custom updates (MOST OF TIME YOU DONT NEED TO DO THIS)
+  # only change this if you know what you are really doing
+  def update_record
+    @record.class.send(:update, @record.id, record_allowed_attributes)
+  end
+
+  # [optional]
+  # Any callback is optional, this is just a example
+  def after_success
+    if changed?
+      logger.info 'Successfully update record ID %s' % @record.id
+      logger.info 'Changed attributes are %s' % changed_attributes
+    end
+  end
+end
+```
+
+---
+
+### BaseDeleteService Basic Markup
+
+```ruby
+class SomeDeleteService < NiftyServices::BaseDeleteService
+  
+  # You can freely override initialize method to receive more arguments
+  def initialize(record, user, options = {})
+    @user = user
+    super(record, options)
+  end
+
+  # [Required]
+  # record_type object must respond to :delete method
+  # But you can override `delete_method` method to do whatever you want
+  record_type RecordType, alias_name: :custom_alias_name
+
+  private
+
+  # [Required]
+  # This is a VERY IMPORTANT point of attention
+  # always verify if @user has permissions to delete the current @record object
+  # Hint: if @record respond_to `user_can_delete?(user)` you can remove this
+  # method and do the validation inside `user_can_delete(user)` method in @record
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def can_delete_record?
+    @record.user_id == @user.id
+  end
+
+  # [optional]
+   # Any callback is optional, this is just a example
+  def after_success
+    logger.info('Successfully Deleted resource ID %s' % @record.id)
+  end
+
+  # [Optional]
+  # This is the default implementation of delete record, you may overwrite it
+  # to do custom delete (MOST OF TIME YOU DONT NEED TO DO THIS)
+  # only change this if you know what you are really doing
+  def delete_record
+    @record.delete
+  end
+
+end
+
+```
+
+### BaseActionService Basic Markup
+
+```ruby
+class SomeCustomActionService < NiftyServices::BaseActionService
+
+  # [required]
+  # this is the action identifier used internally
+  # and to generate error messages
+  # see: invalid_action_error_key method
+  action_name :custom_action_name
+
+  private
+  # [Required]
+  # Always validate if Service can execute the action
+  # This method MUST return a boolean value indicating if Service can or not
+  # run the method `execute_service_action`
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def can_execute_action?
+    # do some specific validation here, you can return errors such:
+    # return not_found_error!(%(users.invalid_user)) # returns false and avoid execution
+    return true
+  end
+
+  # [Required]
+  # The core function of BaseActionServices
+  # This method is called when all validations passes, so here you can put
+  # all logic for Service (eg: send mails, clear logs, any kind of action you want)
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def execute_service_action
+    # (do some complex stuff)
+  end
+ 
+  # [Optional]
+  # You dont need to overwrite this method, just `record_error_key`
+  # But it's important you know how final message key will be created
+  # using the pattern below
+  def invalid_action_error_key
+    "#{record_error_key}.cant_execute_#{action_name}"
+  end
+
+  # [Required]
+  # Key used to created the error messages for this Service
+  # If this method is not implemented a NotImplementedError exception will be raised
+  def record_error_key
+    :users
+  end
+end
+```
+
+---
+
+### Next
+
+See [CLI Generators](./cli.md)

data/docs/usage.md

@@ -0,0 +1,204 @@
+# NiftyServices documentation
+
+---
+
+## Usage
+
+NiftyServices provide a start basic service class for generic code  which is `NiftyServices::BaseService`, the very basic service markup is demonstrated below:
+
+### Basic Service Markup
+
+
+```ruby
+class SemanticServiceName < NiftyServices::BaseService
+
+  def execute
+    execute_action do
+      success_response if do_something_complex
+    end
+  end
+
+  def do_something_complex
+    # (...) some complex bussiness logic
+    return true
+  end
+
+  private
+  def can_execute?
+    return forbidden_error!('errors.message_key') if some_condition
+
+    return not_found_error!('errors.message_key') if another_condition
+
+    return unprocessable_entity_error!('errors.message_key') if other_condition
+
+    # ok, this service can be executed
+    return true
+  end
+end
+
+service = SemanticServiceName.new(options)
+service.execute
+```
+
+---
+
+### Ok, real world example plizzz
+
+Lets work with a real and a little more complex example, an Service responsible to send daily news mail to users.
+The code below shows basically everything you need to know about services structure, such:  entry point, callbacks, authorization, error and success response handling, so after understanding this little piece of code, you will be **ready to code your own services**!
+
+```ruby
+class DailyNewsMailSendService < NiftyServices::BaseService
+
+  before_execute do
+    log.info('Routine started at: %s' % Time.now)
+  end
+
+  after_execute do
+    log.info('Routine ended at: %s' % Time.now)
+  end
+
+  after_initialize do
+    user_data = [@user.name, @user.email]
+    log.info('Routine Details: Send daily news email to user %s(%s)' % user_data)
+  end
+
+  after_success do
+    log.info('Success sent daily news feed email to user')
+  end
+
+  before_error do
+    log.warn('Something went wrong')
+  end
+
+  after_error do
+    log.error('Error sending email to user. See details below :(')
+    log.error(errors)
+  end
+
+  attr_reader :user
+
+  def initialize(user, options = {})
+    @user = user
+    super(options)
+  end
+
+  def execute
+    execute_action do
+      success_response if send_mail_to_user
+    end
+  end
+
+  private
+  def can_execute?
+    unless valid_user?
+      # returns false
+      return not_found_error!('users.not_found')
+    end
+
+    unless @user.abble_to_receive_daily_news_mail?
+      # returns false
+      return forbidden_error!('users.already_received_daily_news_mail')
+    end
+
+    return true
+  end
+
+  def send_mail_to_user
+    # just to fake, a real implementation could be something like:
+    # @user.send_daily_news_mail!
+    return true
+  end
+
+  def valid_user?
+    # check if object is valid and is a User class type
+    valid_object?(@user, User)
+  end
+
+  # you can use `default_options` method to add default { keys => values } to @options
+  # so you can use the option_enabled?(key) to verify if option is enabled
+  # or option_disabled?(key) to verify is option is disabled
+  # This default values can be override when creating new instance of Service, eg:
+  # DailyNewsMailSendService.new(User.last, validate_api_key: false)
+  def default_options
+    { validate_api_key: true }
+  end
+end
+
+class User < Struct.new(:name, :email)
+  # just to play around with results
+  def abble_to_receive_daily_news_mail?
+    rand(10) < 5
+  end
+end
+
+user = User.new('Rafael Fidelis', 'rafa_fidelis@yahoo.com.br')
+
+# Default logger is NiftyService.config.logger = Logger.new('/dev/null')
+service = DailyNewsMailSendService.new(user, logger: Logger.new('daily_news.log'))
+service.execute
+```
+
+### Sample outputs results
+
+#### :smile: Success:
+
+```
+I, [2016-07-15T17:13:40.092854 #2480]  INFO -- : Routine Details: Send daily news email to user
+Rafael Fidelis(rafa_fidelis@yahoo.com.br)
+
+I, [2016-07-15T17:13:40.092987 #2480]  INFO -- : Routine started at: 2016-07-15 17:13:40 -0300
+
+I, [2016-07-15T17:13:40.093143 #2480]  INFO -- : Success sent daily news feed email to user
+
+I, [2016-07-15T17:13:40.093242 #2480]  INFO -- : Routine ended at: 2016-07-15 17:13:40 -0300
+
+
+```
+
+#### :weary: Error:
+
+```
+I, [2016-07-15T17:12:10.954792 #756]  INFO -- : Routine Details: Send daily news email to user
+Rafael Fidelis(rafa_fidelis@yahoo.com.br)
+
+I, [2016-07-15T17:12:10.955025 #756]  INFO -- : Routine started at: 2016-07-15 17:12:10 -0300
+
+W, [2016-07-15T17:12:10.955186 #756]  WARN -- : Something went wrong
+
+E, [2016-07-15T17:12:11.019645 #756] ERROR -- : Error sending email to user. See details below :(
+
+E, [2016-07-15T17:12:11.019838 #756] ERROR -- : ["User has already received daily news mail today"]
+
+I, [2016-07-15T17:12:11.020073 #756]  INFO -- : Routine ended at: 2016-07-15 17:12:11 -0300
+
+```
+
+<br />
+
+### Wrapping things up
+
+The code above demonstrate a very basic example of **how dead easy** is to work with Services, let me clarify some things to your better understanding:
+
+* &#9745; All services classes must inherit from `NiftyServices::BaseService`
+
+* &#9745; For convention(but not a rule) all services must expose only `execute`(and of course, `initialize`) as public methods.
+
+* &#9745; `execute_action(&block)` **MUST** be called to properly setup things in execution context.
+
+* &#9745; `can_execute?` must be **ALWAYS** implemented in service classes, **ALWAYS**, this ensure that your code will **safely runned**.
+Note: A `NotImplementedError` exception will be raised if service won't define your own `can_execute?` method.
+
+* &#9745; There's a very simple helper functions for marking result as success/fail (eg: `unprocessable_entity_error!` or `success_response`).
+
+* &#9745; Simple DSL for actions callbacks inside current execution context. (eg: `after_success` or `before_error`)
+Note: You don't need to use the DSL if you don't want, you can simply define the methods(such as: `private def after_success; do_something; end`
+
+This is the very basic concept of creating and executing a service object, now we need to know how to work with responses to get the most of our services, for this, let's digg in the mainly public API methods of `NiftyService::BaseService` class:
+
+
+---
+
+### Next
+
+See [Crud Objects API Interface](./api.md)