nd-enum 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8c39fe2ee839c606ce8bba0ed32181fff0ab45b39d091f6d5f4070d560eff9e
-  data.tar.gz: 190d2bd1a22ed5b7551b91a1ffe086e8f80d2010228cc568c86d1dc8b7d99fab
+  metadata.gz: 1319016da965b32314532d641038f67316c07087b03f8a0a195786d783307c08
+  data.tar.gz: e88397852614473313ba633c1d3029de0cad1466b9ddfa0787b54e5cc7133eb8
 SHA512:
-  metadata.gz: f4adb87f1df4b296625c32c3eedaef521bc5fccf8de94ef8bf77644be19324e5395cbed035cb96bd023a8555c30ca7843a802c2289f553ef310f5fb2f9e788a3
-  data.tar.gz: 8df576525c8d46cdb705e7ade16a4158e0d0387baaf7429239fc9e74e7ddb6dd6878787d77dde8fa0f8a8d3c61b55d58e64aea82cd6994d447c30568336e5884
+  metadata.gz: 65596f68728490a34c575fac8191438d85b4490268a5938c725f5ed7c0fbe3e0616679b332971dd8991f0989c34bd41c51b89bdaf1153f822f6446a0714613fc
+  data.tar.gz: c583f3f1e8a655bcf9ba604ef3851cbb27dba1acc7743ea5c158a763c33792e3cd2dc826659b7e53c1ae3380ac045aef60e53e6fd1bff3b9d8e83b315bd37b5f

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.2.0] - 2022-08-10
+
+- Add initializer
+- Validate translations
+
 ## [0.1.2] - 2022-08-08
 
 - Add specs

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nd-enum (0.1.1)
+    nd-enum (0.2.0)
       activerecord (>= 6.0.0)
       activesupport (>= 6.0.0)
 

data/README.md

@@ -1,8 +1,6 @@
 # ND::Enum
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/nd/enum`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+This gem allows you to create and use enums easily and quickly in your Rails project.
 
 ## Installation
 
@@ -16,17 +14,222 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-TODO: Write usage instructions here
+- [Basic usage](#basic-usage)
+- [Configuration](#configuration)
+- [I18n](#i18n)
+  - [Validate translations presence](#validate-translations-presence)
+  - [Enforce translations presence](#enforce-translations-presence)
+- [ActiveRecord Enum](#activerecord-enum)
+
+### Basic usage
+
+Define your enum in an ActiveRecord model:
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin))
+end
+```
+
+It creates a module for your enum that contains one constant per enum value. Say goodbye to [magic strings](https://en.wikipedia.org/wiki/Magic_string)!
+
+In our example, the module is `User::Role`, and the constants are `User::Role::USER` and `User::Role::ADMIN`.
+
+```ruby
+irb(main)> User::Role::USER
+=> "user"
+
+irb(main)> User::Role::ADMIN
+=> "admin"
+
+irb(main)> User::Role.all
+=> ["user", "admin"]
+
+irb(main)> User::Role.length
+=> 2
+
+irb(main)> User::Role[1]
+=> "admin"
+
+irb(main)> User::Role[:user]
+=> "user"
+
+irb(main)> User::Role.include?('foobar')
+=> false
+
+irb(main)> User::Role.include?('user')
+=> true
+```
+
+ND::Enum inheritates from [`Enumerable`](https://ruby-doc.org/core-3.1.2/Enumerable.html), so it is possible to use all `Enumerable` methods on the enum module: `each`, `map`, `find`...
+
+### Configuration
+
+Fine-tune `ND::Enum` behaviour by creating an initializer (for example: `config/initializers/nd_enum.rb`).
+The values shown in the example below are the default values.
+
+```ruby
+ND::Enum.configure do |c|
+  c.default_i18n_scope = :base
+  c.default_i18n_validation_mode = :ignore # Allowed values: ignore, log, enforce
+end
+```
+
+### I18n
+
+Allows to translate your enum values.
+Add to your locale files:
+
+```yaml
+en:
+  users: # Model.table_name
+    role: # attribute
+      base: # default scope
+        user: User
+        admin: Admin
+      foobar: # custom scope
+        user: The user
+        admin: The admin
+```
+
+Then call `t` (or `translate`) method:
+
+```ruby
+irb(main)> User::Role.t(:user) # Or `translate` method (alias)
+=> "translation missing: en.users.role.base.user"
+```
+
+Use a different scope to have several translations for a single value, depending on context:
+
+```ruby
+irb(main)> User::Role.t(:user, :foobar)
+=> "translation missing: en.users.role.foobar.user"
+```
+
+Please note that the default scope (`base`) can be configured using the `default_i18n_scope` initializer option.
+
+#### Validate translations presence
+
+Validate that your enum are translated. By default, this feature is disabled.
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin), i18n: { mode: :log })
+end
+```
+
+It will log the missing translations for each scope & locale. For example:
+
+```
+I, [2022-08-10T21:17:53.931669 #67401]  INFO -- : ND::Enum: User#role scopes=[:base, :short]
+I, [2022-08-10T21:17:53.931669 #67401]  INFO -- : ND::Enum: User#role locale=en missing_keys=[]
+I, [2022-08-10T21:17:53.931669 #67401]  INFO -- : ND::Enum: User#role locale=nl missing_keys=["users.role.base.user", "users.role.short.user"]
+```
+
+This mode can be used as default with the `c.default_i18n_validation_mode = :log` initializer option.
+
+#### Enforce translations presence
+
+Raise an exception when some translations are missing.
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin), i18n: { mode: :enforce })
+end
+```
+
+```
+(irb):1:in `<main>': One or several translations are missing (ND::Enum::MissingTranslationError)
+        from bin/console:15:in `<main>'
+```
+
+This mode can be used as default with the `c.default_i18n_validation_mode = :enforce` initializer option.
+
+### `ActiveRecord` Enum
+
+Add a wrapper to [`ActiveRecord` Enum](https://api.rubyonrails.org/classes/ActiveRecord/Enum.html) by specifying the `db: true` option.
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin), db: true)
+end
+
+# It does exactly the same thing than below, but shorter:
+
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin))
+  enum(role: User::Role.to_h) # Or `enum(role: { user: 'user', admin: 'admin '})`
+end
+```
+
+It allows to use these methods:
+
+```ruby
+user.admin!
+user.admin? # => true
+user.role # => "admin"
+```
+
+And these scopes:
+
+```ruby
+User.admin
+User.not_admin
+
+User.user
+User.not_user
+
+# ...
+```
+
+Disable scope definition by setting `scopes: false` to your enum:
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin), db: { scopes: false })
+end
+```
+
+Set the default enum:
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin), db: { default: :admin })
+end
+```
+
+Add a `prefix` or `suffix` option when you need to define multiple enums with same values. If the passed value is true, the methods are prefixed/suffixed with the name of the enum. It is also possible to supply a custom value:
+
+```ruby
+class User < ApplicationRecord
+  nd_enum(role: %i(user admin), db: { prefix: true })
+
+  # Scopes: `User.role_admin`, `User.role_user` ...
+  # Methods: `User.role_admin!`, `User.role_user!` ...
+
+  nd_enum(role: %i(user admin), db: { suffix: true })
+
+  # Scopes: `User.admin_role`, `User.user_role` ...
+  # Methods: `User.admin_role!`, `User.user_role!` ...
+
+  nd_enum(role: %i(user admin), db: { prefix: 'foobar' })
+
+  # Scopes: `User.foobar_admin`, `User.foobar_user` ...
+  # Methods: `User.foobar_admin!`, `User.foobar_user!` ...
+end
+```
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Guard is also installed: `bundle exec guard`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, run `gem bump` (or manually update the version number in `version.rb`), and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/nd-enum.
+Bug reports and pull requests are welcome on GitHub at https://github.com/rclavel/nd-enum.
 
 ## License
 

data/lib/nd/enum/base.rb

@@ -3,34 +3,38 @@
 require 'forwardable'
 require 'active_support'
 
-module ND
-  module Enum
-    module Base
-      extend ActiveSupport::Concern
-
-      included do
-        class << self
-          include Enumerable
-          extend Forwardable
-
-          def_delegators :all, :size, :length, :[], :empty?, :last, :index
-
-          def each(&block)
-            all.each(&block)
-          end
-
-          def to_h
-            all.map { |value| [value.to_sym, value] }.to_h
-          end
-
-          def [](value)
-            value.is_a?(Integer) ? all[value] : to_h[value.to_sym]
-          end
-
-          def t(value, scope = :base)
-            I18n.t(value, scope: "#{model.table_name}.#{attribute}.#{scope}")
-          end
-        end
+module ND::Enum::Base
+  extend ActiveSupport::Concern
+
+  included do
+    class << self
+      include Enumerable
+      extend Forwardable
+
+      def_delegators :all, :size, :length, :[], :empty?, :last, :index
+
+      def each(&block)
+        all.each(&block)
+      end
+
+      def to_h
+        all.map { |value| [value.to_sym, value] }.to_h
+      end
+
+      def [](value)
+        value.is_a?(Integer) ? all[value] : to_h[value.to_sym]
+      end
+
+      def t(value, scope = nil)
+        scope ||= configuration.default_i18n_scope
+        ::I18n.t(value, scope: "#{model.table_name}.#{attribute}.#{scope}")
+      end
+      alias_method :translate, :t
+
+      private
+
+      def configuration
+        ND::Enum.configuration
       end
     end
   end

data/lib/nd/enum/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ND::Enum::Configuration
+  Configuration = Struct.new(:default_i18n_validation_mode, :default_i18n_scope)
+  DEFAULT_CONFIGURATION = {
+    default_i18n_validation_mode: :ignore,
+    default_i18n_scope: :base,
+  }
+
+  def configuration
+    @_configuration ||= Configuration.new(*DEFAULT_CONFIGURATION.values_at(*Configuration.members))
+  end
+
+  def configure
+    yield(configuration)
+  end
+end

data/lib/nd/enum/i18n.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ND::Enum::I18n
+  class << self
+    # TODO: Transform into a nd_enum
+    module Mode
+      LOG = 'log'
+      ENFORCE = 'enforce'
+      IGNORE = 'ignore'
+
+      def self.all
+        [LOG, ENFORCE, IGNORE]
+      end
+    end
+
+    def validate!(options)
+      mode = get_mode_from_options(options)
+      return if mode == Mode::IGNORE
+
+      i18n_scope = build_i18n_scope(options)
+      scopes = get_scopes_from_translations(i18n_scope)
+      missing_keys_by_locale = get_missing_keys_by_locale(options, i18n_scope, scopes)
+
+      log_missing_keys(options, scopes, missing_keys_by_locale)
+
+      if mode == Mode::ENFORCE && missing_keys_by_locale.values.any?(&:present?)
+        raise ND::Enum::MissingTranslationError
+      end
+    end
+
+    private
+
+    def get_mode_from_options(options)
+      case options.dig(:i18n, :validate)
+      when 'log', :log then Mode::LOG
+      when 'enforce', :enforce then Mode::ENFORCE
+      else
+        default_mode = configuration.default_i18n_validation_mode&.to_s
+        Mode.all.include?(default_mode) ? default_mode : Mode::IGNORE
+      end
+    end
+
+    def build_i18n_scope(options)
+      "#{options[:model].table_name}.#{options[:attribute]}"
+    end
+
+    def get_scopes_from_translations(i18n_scope)
+      scopes = %i(base)
+
+      I18n.available_locales.each do |locale|
+        configuration = I18n.t(i18n_scope, locale: locale, default: {})
+        configuration.each_key do |scope|
+          scopes << scope.to_sym unless scopes.include?(scope.to_sym)
+        end
+      end
+
+      scopes
+    end
+
+    def get_missing_keys_by_locale(options, i18n_scope, scopes)
+      I18n.available_locales.each_with_object({}) do |locale, missing_keys_by_locale|
+        missing_keys = []
+
+        scopes.each do |scope|
+          options[:values].each do |value|
+            value_i18n_scope = "#{i18n_scope}.#{scope}.#{value}"
+            next if I18n.exists?(value_i18n_scope, locale: locale)
+
+            missing_keys << value_i18n_scope
+          end
+        end
+
+        missing_keys_by_locale[locale] = missing_keys
+      end
+    end
+
+    def log_missing_keys(options, scopes, missing_keys_by_locale)
+      prefix = "ND::Enum: #{options[:model_name]}##{options[:attribute]}"
+      logger.info("#{prefix} scopes=#{scopes}")
+
+      missing_keys_by_locale.each do |locale, missing_keys|
+        logger.info("#{prefix} locale=#{locale} missing_keys=#{missing_keys}")
+      end
+    end
+
+    def logger
+      @_logger ||= Logger.new(STDOUT)
+    end
+
+    def configuration
+      ND::Enum.configuration
+    end
+  end
+end

data/lib/nd/enum/version.rb

@@ -2,6 +2,6 @@
 
 module ND
   module Enum
-    VERSION = '0.1.2'
+    VERSION = '0.2.0'
   end
 end

data/lib/nd/enum.rb

@@ -8,64 +8,79 @@ require 'active_support/core_ext/string/inflections.rb'
 
 require_relative 'enum/version'
 require_relative 'enum/base'
+require_relative 'enum/configuration'
+require_relative 'enum/i18n'
 
-module ND
-  module Enum
-    extend ActiveSupport::Concern
+module ND::Enum
+  extend ActiveSupport::Concern
 
-    included do
-      def self.nd_enum(db: false, i18n: {}, **configuration)
-        options = ND::Enum.set_options(binding, self)
-        enum_module = ND::Enum.define_module(options)
+  included do
+    def self.nd_enum(db: false, i18n: {}, model: self, model_name: nil, **configuration)
+      options = ND::Enum.set_options(binding, model, model_name)
+      enum_module = ND::Enum.define_module(options)
 
-        ND::Enum.define_db_enum(options, enum_module) if options[:db]
+      ND::Enum.define_db_enum(options, enum_module) if options[:db]
+      ND::Enum::I18n.validate!(options)
 
-        const_set(options[:attribute].to_s.camelize, enum_module)
-      end
+      const_set(options[:attribute].to_s.camelize, enum_module)
     end
+  end
 
-    class << self
-      def set_options(caller_binding, caller_class)
-        options = caller_class.method(:nd_enum).parameters.each_with_object({}) do |(_, name), options|
-          options[name.to_sym] = caller_binding.local_variable_get(name)
-        end
-        options[:attribute], options[:values] = options.delete(:configuration).to_a.first
-        options[:model] = caller_class
+  class Error < StandardError; end
+  class MissingTranslationError < Error
+    def message
+      'One or several translations are missing'
+    end
+  end
+
+  class << self
+    include ND::Enum::Configuration
 
-        options
+    def set_options(caller_binding, caller_class, caller_class_name)
+      options = caller_class.method(:nd_enum).parameters.each_with_object({}) do |(_, name), options|
+        options[name.to_sym] = caller_binding.local_variable_get(name)
       end
+      options[:attribute], options[:values] = options.delete(:configuration).to_a.first
+      options[:model] = caller_class
+      options[:model_name] = caller_class_name
+
+      options
+    end
 
-      def define_module(options)
-        Module.new do
-          include ND::Enum::Base
+    def define_module(options)
+      Module.new do
+        include ND::Enum::Base
 
-          # Public methods
+        # Public methods
 
-          define_singleton_method(:all) { options[:values] }
+        define_singleton_method(:all) { options[:values] }
 
-          # Private methods
+        # Private methods
 
-          define_singleton_method(:options) { options }
-          options.each_key do |name|
-            define_singleton_method(name) { options[name] }
-          end
+        define_singleton_method(:options) { options }
+        options.each_key do |name|
+          define_singleton_method(name) { options[name] }
+        end
 
-          [:options, *options.keys].each do |method_name|
-            singleton_class.class_eval { private method_name.to_sym }
-          end
+        [:options, *options.keys].each do |method_name|
+          singleton_class.class_eval { private method_name.to_sym }
+        end
 
-          # Constants
+        # Constants
 
-          options[:values].map do |value|
-            const_set(value.to_s.upcase, value.to_s)
-          end
+        options[:values].map do |value|
+          const_set(value.to_s.upcase, value.to_s)
         end
       end
+    end
 
-      def define_db_enum(options, enum_module)
-        enum_options = options[:db].is_a?(Hash) ? options[:db] : {}
-        options[:model].enum(options[:attribute] => enum_module.to_h, **enum_options)
-      end
+    def define_db_enum(options, enum_module)
+      enum_options = options[:db].is_a?(Hash) ? options[:db] : {}
+
+      enum_options[:_prefix] = enum_options.delete(:prefix) if enum_options.key?(:prefix)
+      enum_options[:_suffix] = enum_options.delete(:suffix) if enum_options.key?(:suffix)
+
+      options[:model].enum(options[:attribute] => enum_module.to_h, **enum_options)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nd-enum
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Romain Clavel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-08 00:00:00.000000000 Z
+date: 2022-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -55,6 +55,8 @@ files:
 - Rakefile
 - lib/nd/enum.rb
 - lib/nd/enum/base.rb
+- lib/nd/enum/configuration.rb
+- lib/nd/enum/i18n.rb
 - lib/nd/enum/version.rb
 - nd-enum.gemspec
 - sig/nd/enum.rbs