nummy 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9edb3b21dc12078ceec611949ebf6deb80ed4a69309aaba8a2b01c233025e66
-  data.tar.gz: e066bb5910d68efdca902e242a1cd9269aecc48b9a77bbf9c246516dc995eb8d
+  metadata.gz: 83fe6928d06ebd4ba649eaa37ad3278366e2322a99fe56a7efdfed228b971841
+  data.tar.gz: 7116e7d5febca95ae52544bcbc42a4fd99e895ca8e60ef9cd7e3444e6dae8719
 SHA512:
-  metadata.gz: 401f6427a1c27596f411cf11c6686a9164aabe06980c6db046887848424f01245921d45f15d01b4938d26a5ccb274e08003b51810073e1ec3cd7e71c0e2f284d
-  data.tar.gz: 5e3c46a452c2967bc52c1ddf0df5993545af18801a3bbbaead6663fa91e0aa9d61fa87919b7c4c334791a0c7162867d023e4e346200c9d407029fb4e1497da53
+  metadata.gz: 4d4bb886ad7d5187aca88391c1e9366a82b4bdb08e435cb5567951a5e2a5e5d230ef5f06cdae0bd5b104c8a62d00e41c437969cf9b9b4a4cf7d5eb41e73dd4ac
+  data.tar.gz: dc40fbde79187708d1006bd80475b114f98f8de238faaae8bd4a9b620f5557df06c3d960123e237267041370f59baee13d42e1f4389e97e3394e68fe6e383cfc

data/CHANGELOG.md

@@ -1,5 +1,85 @@
 ## [Unreleased]
 
+## [0.3.0] - 2024-01-04
+
+- **Adds additional flexibility to `Nummy::Enum.to_attribute` (#2)
+
+  This release teaches a few new tricks to `Nummy::Enum.to_attribute`:
+
+  - it allows passing a block to fully customize how keys are transformed
+
+  - it looks for `String#underscore` rather than calling into  `ActiveSupport::Inflector.underscore` directly, which means that users can bring their own monkey patch if they want to.
+
+  - it falls back to `Symbol#downcase` if `String#underscore` is not available. If the constants are defined using `SCREAMING_SNAKE_CASE`, this will generally have the same result as calling `String#underscore`, but without requiring ActiveSupport.
+
+  ```ruby
+  class ShippingStatus < Nummy::Enum
+    IN_TRANSIT = auto
+    OUT_FOR_DELIVERY = auto
+    DELIVERED = auto
+  end
+  ```
+
+  ```ruby
+  # Without ActiveSupport
+  
+  ShippingStatus.to_attribute
+  # v0.2.0 (❌)
+  # => nummy/lib/nummy/enum.rb:379:in `block in to_attribute': uninitialized constant ActiveSupport (NameError)
+  # 
+  #              ::ActiveSupport::Inflector.underscore(key).to_sym
+  #              ^^^^^^^^^^^^^^^
+
+  # v0.3.0 (✅)
+  # => {:in_transit=>0, :out_for_delivery=>1, :delivered=>2}
+  ```
+
+  ```ruby
+  # With ActiveSupport
+  require "active_support/core_ext/string/inflections"
+
+  ShippingStatus.to_attribute
+  # => {:in_transit=>0, :out_for_delivery=>1, :delivered=>2}
+
+  ShippingStatus.to_attribute { |key| key.to_s.underscore.camelize.to_sym }
+  # => {:InTransit=>0, :OutForDelivery=>1, :Delivered=>2}
+  ```
+
+- **Adds JSON serialization support (#3)**
+
+  This release adds two methods to `Nummy::Enum`: `.as_json` and `.to_json`. These methods allow you to serialize an enum to JSON.
+
+  ```ruby
+  class Status < Nummy::Enum
+    ACTIVE = auto
+    ARCHIVED = auto
+  end
+
+  Status.as_json
+  # => {"ACTIVE" => 0, "ARCHIVED" => 1}
+
+  Status.to_json
+  # => "{\"ACTIVE\":0,\"ARCHIVED\":1}
+  ```
+
+## [0.2.0] - 2024-01-04
+
+- Add `Nummy::Enum.to_attribute` (#1), which converts the enum to a hash that can be passed as the values of an `ActiveRecord::Enum`:
+  
+  ```ruby
+  class Conversation < ActiveRecord::Base
+    class Status < Nummy::Enum
+      ACTIVE = auto
+      ARCHIVED = auto
+    end
+
+    enum :status, Status.to_attribute
+  end
+  ```
+
+  > [!IMPORTANT]
+  > The conversion requires that `ActiveRecord::Inflector` is defined, but `nummy` does not depend on `ActiveRecord` directly. If you are using `nummy` in a non-Rails environment, you will need to require `ActiveRecord::Inflector` yourself.
+
 ## [0.1.0] - 2024-01-04
 
 - Initial release

data/README.md

@@ -14,13 +14,13 @@ constants in a module, and iterating over the members of data classes.
 Install the gem and add to the application's Gemfile by executing:
 
 ```console
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add nummy
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```console
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install nummy
 ```
 
 ## Usage
@@ -146,6 +146,58 @@ end
 > [!TIP]
 > `Nummy::Enum` extends `Enumerable` and iterates over the _values_ of the enum, so you have access to things like `.include?(value)`, `.any?`, and `.find`.
 
+#### Rails / ActiveRecord integration
+
+To use nummy enums as ActiveRecord enums, you can use the `.to_attribute` method, which converts the keys to `snake_case` by default:
+
+```ruby
+class Conversation < ActiveRecord::Base
+  class Status < Nummy::Enum
+    ACTIVE = auto
+    ARCHIVED = auto
+  end
+
+  enum :status, Status.to_attribute
+end
+```
+
+> [!NOTE]
+> `to_attribute` will transform keys using `String#underscore` if it is defined, otherwise it will use `Symbol#downcase`.
+
+> [!TIP]
+> You can also do custom transformations by passing a block to `to_attribute`. See the documentation for more details.
+
+Using `to_attribute` allows you to use all of the Rails magic for enums, like scopes and boolean helpers, while also being able to refer to values in a safer way than hash lookups.
+
+That is, these two are the same:
+
+```ruby
+Conversation.statuses[:active] # => 0
+Conversation::Status::ACTIVE   # => 0
+```
+
+But these are not:
+
+```ruby
+Conversation.statuses[:acitve]
+# => nil
+
+Conversation::Status::ACITVE   # => nil
+# =>
+#  uninitialized constant Conversation::Status::ACITVE (NameError)
+#  Did you mean?  Conversation::Status::ACTIVE
+```
+
+You can get similar behavior using `#fetch`:
+
+```ruby
+Conversation.statuses.fetch(:acitve)
+# => key not found: :acitve (KeyError)
+#    Did you mean?  :active
+```
+
+But that still misses out on some of the DX benefits of using constants, like improved support for things like autocompletion, documentation, and navigation ("Go To Definition") in editors.
+
 ### `Nummy::MemberEnumerable`
 
 `Nummy::MemberEnumerable` is a module that includes `Enumerable` and makes it possible to iterate over any class or module that responds to `members`.

data/lib/nummy/enum.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require "nummy/auto_sequenceable"
 require "nummy/ordered_const_enumerable"
 require "nummy/errors"
@@ -354,6 +356,79 @@ module Nummy
       # Alias to support splatting enums into keyword args.
       alias to_hash to_h
 
+      # Converts +self+ to a +Hash+ that can be converted to JSON.
+      #
+      # @return [Hash{String => Object}]
+      #
+      # @see .to_json
+      def as_json
+        to_h.transform_keys!(&:to_s)
+      end
+
+      # Converts +self+ to a +Hash+ and serializes it to  a JSON string.
+      #
+      # Supports same options as +JSON#generate+.
+      #
+      # @return [String]
+      #
+      # @see .as_json
+      def to_json(*)
+        as_json.to_json(*)
+      end
+
+      # Converts the enum to a +Hash+ with snake_case keys.
+      #
+      # This is intended to be used with +ActiveRecord::Enum+, but can be used
+      # with any library that supports defining enums using a +Hash+ and expects
+      # to have lowercase keys.
+      #
+      # @overload to_attribute
+      #   If +String#underscore+ is defined, converts the keys to snake_case
+      #   by calling +underscore+ on the stringified key.
+      #
+      #   Otherwise, converts each key using +Symbol#downcase+.
+      #
+      #   @return [Hash{Symbol => Object}]
+      #
+      #   @example Using with +ActiveRecord::Enum+.
+      #     class Conversation < ActiveRecord::Base
+      #       class Status < Nummy::Enum
+      #         ACTIVE = auto
+      #         ARCHIVED = auto
+      #       end
+      #
+      #       enum :status, Status.to_attribute
+      #     end
+      #
+      # @overload to_attribute(&)
+      #   Transforms the keys by calling the given block on each key.
+      #
+      #   @yieldparam key [Symbol]
+      #   @return [Hash{Symbol => Object}]
+      #
+      #   @example Using custom key transformer.
+      #     class ShippingStatus < Nummy::Enum
+      #       IN_TRANSIT = auto
+      #       OUT_FOR_DELIVERY = auto
+      #       DELIVERED = auto
+      #     end
+      #
+      #     ShippingStatus.to_attribute { |key| key.to_s.underscore.camelize.to_sym }
+      #     # => {:InTransit=>0, :OutForDelivery=>1, :Delivered=>2}
+      def to_attribute(&)
+        return to_h.transform_keys!(&) if block_given?
+
+        # Ignore coverage because it's executed in a forked process, which
+        # messes with the coverage collection.
+        # :nocov:
+        if String.method_defined?(:underscore)
+          return to_attribute { |key| key.to_s.underscore.to_sym }
+        end
+        # :nocov:
+
+        to_attribute(&:downcase)
+      end
+
       # Returns a string representation of +self+.
       #
       # The string will contain the name-value pairs of the constants in +self+.

data/lib/nummy/version.rb

@@ -2,5 +2,5 @@
 
 module Nummy
   # The current version of the gem.
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nummy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Benjamin Chauvette