ksuid 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d7e3d2e87bfbd69ce702f4dcc0d7067394f39fe7
-  data.tar.gz: 8159913d3848e49c9e41143db7e1fc4fb115deee
+SHA256:
+  metadata.gz: 65b5bd73fb4864bb0df8cf57c1214622325afa077e031baffb2a1e73b2820f2c
+  data.tar.gz: 55245cb9fba9e57c9bf115f189fb954f2e1b08604e89ba8b5c9aeea73967e5ba
 SHA512:
-  metadata.gz: a298ed92c64c0398c14853de8d246fc0e78b29aca724dde716fe8c67640e37621db09f62f4a76da86de0576d64a2be7d8265f1cdb692056244a0838efe9a1da9
-  data.tar.gz: 5282c1bfe4bc4a09761510fd4a330c7e8429626e67c245e62af3d41b7b391be2470c598fa91aaf6a5ebe7df51a0aec8a0e3a7f46ac01afc5afbbf733e51e1dd8
+  metadata.gz: af5cc8ed5f9d81616fd61e6f03690c841489e9f2c2d28d892137c1eb410ec88e61540cd3dd10d5ac0d0439f9b9ecd9afdc00cceae61276cca521d5436c159e29
+  data.tar.gz: 13479dc7d24cf9422c6bc3ca705c6c777abf121f5ade7a9f9c8124c7b9f8034844d8707b2f8265c18178b9b16b50be28a3c1894888d97fe7f42aa1e981d11a97

data/CHANGELOG.md

@@ -4,12 +4,38 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2017-11-05
+## [0.4.0](https://github.com/michaelherold/ksuid/compare/v0.3.0...v0.4.0) - 2022-07-29
+
+### Added
+
+- `KSUID::Type` acts as a proper value object now, which means that you may use it as a Hash key or use it in ActiveRecord's `.includes`. `KSUID::Type#eql?`, `KSUID::Type#hash`, and `KSUID::Type#==` now work as expected. Note that `KSUID::Type#==` is more lax than `KSUID::Type#eql?` because it can also match any object that converts to a string matching its value. This means that you can use it to match against `String` KSUIDs.
+
+### Fixed
+
+- `ActiveRecord::QueryMethods#include` works as expected now due to the fix on the value object semantics of `KSUID::Type`.
+- Binary KSUID primary and foreign keys work as expected on JRuby.
+
+## [0.3.0](https://github.com/michaelherold/ksuid/compare/v0.2.0...v0.3.0) - 2021-10-07
+
+### Added
+
+- A utility function for converting from a hexidecimal-encoded string to a byte string. This is necessary to handle the default encoding of binary fields within PostgreSQL.
+
+## [0.2.0](https://github.com/michaelherold/ksuid/compare/v0.1.0...v0.2.0) - 2020-11-11
+
+### Added
+
+- The ability to configure the random generator for the gem via `KSUID.configure`. This allows you to set up random generation to the specifications you need, whether that is for speed or for security.
+- Support for ActiveRecord. You can now use `KSUID::ActiveRecord[:my_field]` to define a KSUID field using the Rails 5 Attributes API. There is also two new column types for migrations: `ksuid` and `ksuid_binary`. The first stores your KSUID as a string in the database, the latter as binary data.
+
+### Changed
+
+- The `KSUID::Type#inspect` method now makes it much easier to see what you're looking at in the console when you're debugging.
+
+## [0.1.0](https://github.com/michaelherold/ksuid/tree/v0.1.0) - 2017-11-05
 
 ### Added
 
 - Basic `KSUID.new` interface.
 - Parsing of bytes through `KSUID.from_bytes`.
 - Parsing of strings through `KSUID.from_base62`.
-
-[0.1.0]: https://github.com/michaelherold/interactor-contracts/tree/v0.1.0

data/CONTRIBUTING.md

@@ -28,14 +28,13 @@ Ideally, a bug report should include a pull request with failing specs.
 1. [Fork the repository].
 2. [Create a topic branch].
 3. Add specs for your unimplemented feature or bug fix.
-4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+4. Run `appraisal rake spec`. If your specs pass, return to step 3.
 5. Implement your feature or bug fix.
-6. Run `bundle exec rake`. If your specs or any of the linters fail, return to step 5.
+6. Run `appraisal rake`. If your specs or any of the linters fail, return to step 5.
 7. Open `coverage/index.html`. If your changes are not completely covered by your tests, return to step 3.
 8. Add documentation for your feature or bug fix.
-9. Run `bundle exec inch`. If your changes are below a B in documentation, go back to step 8.
-10. Commit and push your changes.
-11. [Submit a pull request].
+9. Commit and push your changes.
+10. [Submit a pull request].
 
 [Create a topic branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
 [Fork the repository]: http://learn.github.com/p/branching.html

data/README.md

@@ -1,14 +1,14 @@
 # KSUID for Ruby
 
-[![Build Status](https://travis-ci.org/michaelherold/ksuid-ruby.svg)][travis]
+[![Build Status](https://github.com/michaelherold/ksuid-ruby/workflows/Continuous%20integration/badge.svg)][actions]
 [![Test Coverage](https://api.codeclimate.com/v1/badges/94b2a2d4082bff21c10f/test_coverage)][test-coverage]
 [![Maintainability](https://api.codeclimate.com/v1/badges/94b2a2d4082bff21c10f/maintainability)][maintainability]
 [![Inline docs](http://inch-ci.org/github/michaelherold/ksuid-ruby.svg?branch=master)][inch]
 
+[actions]: https://github.com/michaelherold/ksuid-ruby/actions
 [inch]: http://inch-ci.org/github/michaelherold/ksuid-ruby
 [maintainability]: https://codeclimate.com/github/michaelherold/ksuid-ruby/maintainability
 [test-coverage]: https://codeclimate.com/github/michaelherold/ksuid-ruby/test_coverage
-[travis]: https://travis-ci.org/michaelherold/ksuid-ruby
 
 ksuid is a Ruby library that can generate and parse [KSUIDs](https://github.com/segmentio/ksuid). The original readme for the Go version of KSUID does a great job of explaining what they are and how they should be used, so it is excerpted here.
 
@@ -92,17 +92,135 @@ If you need to generate a KSUID for a specific timestamp, use:
 ksuid = KSUID.new(time: time)  # where time is a Time-like object
 ```
 
+If you need to use a faster or more secure way of generating the random payloads (or if you want the payload to be non-random data), you can configure the gem for those use cases:
+
+```ruby
+KSUID.configure do |config|
+  config.random_generator = -> { Random.new.bytes(16) }
+end
+```
+
+### ActiveRecord
+
+Whether you are using ActiveRecord inside an existing project or in a new project, usage is simple. Additionally, you can use it with or without Rails.
+
+#### Adding to an existing model
+
+Within a Rails project, it is very easy to get started using KSUIDs within your models. You can use the `ksuid` column type in a Rails migration to add a column to an existing model:
+
+    rails generate migration add_ksuid_to_events ksuid:ksuid
+
+This will generate a migration like the following:
+
+```ruby
+class AddKsuidToEvents < ActiveRecord::Migration[5.2]
+  def change
+    add_column :events, :unique_id, :ksuid
+  end
+end
+```
+
+Then, to add proper handling to the field, you will want to mix a module into the model:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:unique_id]
+end
+```
+
+#### Creating a new model
+
+To create a new model with a `ksuid` field that is stored as a KSUID, use the `ksuid` column type. Using the Rails generators, this looks like:
+
+    rails generate model Event my_field_name:ksuid
+
+If you would like to add a KSUID to an existing model, you can do so with the following:
+
+```ruby
+class AddKsuidToEvents < ActiveRecord::Migration[5.2]
+  change_table :events do |table|
+    table.ksuid :my_field_name
+  end
+end
+```
+
+Once you have generated the table that you will use for your model, you will need to include a module into the model class, as follows:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:my_field_name]
+end
+```
+
+##### With a KSUID primary key
+
+You can also use a KSUID as the primary key on a table, much like you can use a UUID in vanilla Rails. To do so requires a little more finagling than you can manage through the generators. When hand-writing the migration, it will look like this:
+
+```ruby
+class CreateEvents < ActiveRecord::Migration[5.2]
+  create_table :events, id: false do |table|
+    table.ksuid :id, primary_key: true
+  end
+end
+```
+
+You will need to mix in the module into your model as well:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:id]
+end
+```
+
+#### Outside of Rails
+
+Outside of Rails, you cannot rely on the Railtie to load the appropriate files for you automatically. Toward the start of your application's boot process, you will want to require the following:
+
+```ruby
+require 'ksuid/activerecord'
+
+# If you will be using the ksuid column type in a migration
+require 'ksuid/activerecord/table_definition'
+```
+
+Once you have required the file(s) that you need, everything else will work as it does above.
+
+#### Binary vs. String KSUIDs
+
+These examples all store your identifier as a string-based KSUID. If you would like to use binary KSUIDs instead, use the `ksuid_binary` column type. Unless you need to be super-efficient with your database, we recommend using string-based KSUIDs because it makes looking at the data while in the database a little easier to understand.
+
+When you include the KSUID module into your model, you will want to pass the `:binary` option as well:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:my_field_name, binary: true]
+end
+```
+
+#### Use the KSUID as your `created_at` timestamp
+
+Since KSUIDs include a timestamp as well, you can infer the `#created_at` timestamp from the KSUID. The module builder enables that option automatically with the `:created_at` option, like so:
+
+```ruby
+class Event < ApplicationRecord
+  include KSUID::ActiveRecord[:my_field_name, created_at: true]
+end
+```
+
+This allows you to be efficient in your database design if that is a constraint you need to satisfy.
+
 ## Contributing
 
 So you’re interested in contributing to KSUID? Check out our [contributing guidelines](CONTRIBUTING.md) for more information on how to do that.
 
 ## Supported Ruby Versions
 
-This library aims to support and is [tested against][travis] the following Ruby versions:
+This library aims to support and is [tested against][actions] the following Ruby versions:
 
-* Ruby 2.3
-* Ruby 2.4
-* JRuby 9.1
+* Ruby 2.5
+* Ruby 2.6
+* Ruby 2.7
+* JRuby 9.2
 
 If something doesn't work on one of these versions, it's a bug.
 

data/ksuid.gemspec

@@ -6,11 +6,11 @@ Gem::Specification.new do |spec|
   spec.name    = 'ksuid'
   spec.version = KSUID::VERSION
   spec.authors = ['Michael Herold']
-  spec.email   = ['michael@michaeljherold.com']
+  spec.email   = ['opensource@michaeljherold.com']
 
   spec.summary     = 'Ruby implementation of the K-Sortable Unique IDentifier'
   spec.description = spec.summary
-  spec.homepage    = 'https://github.com/michaelherold/ksuid'
+  spec.homepage    = 'https://github.com/michaelherold/ksuid-ruby'
   spec.license     = 'MIT'
 
   spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md]
@@ -18,5 +18,5 @@ Gem::Specification.new do |spec|
   spec.files += Dir['lib/**/*.rb']
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'bundler', '>= 1.15'
 end

data/lib/ksuid/activerecord/binary_type.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module KSUID
+  module ActiveRecord
+    # A binary-serialized KSUID for storage within an ActiveRecord database
+    #
+    # @api private
+    #
+    # @example Set an attribute as a KSUID using the verbose syntax
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, KSUID::ActiveRecord::BinaryType.new, default: -> { KSUID.new }
+    #   end
+    #
+    # @example Set an attribute as a KSUID using the pre-registered type
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, :ksuid_binary, default: -> { KSUID.new }
+    #   end
+    class BinaryType < ::ActiveRecord::Type::Binary
+      # Casts a value from user input into a KSUID
+      #
+      # Type casting happens via the attribute setter and can take input from
+      # many places, including:
+      #
+      #   1. The Rails form builder
+      #   2. Directly from the attribute setter
+      #   3. From the model initializer
+      #
+      # @param value [String, Array<Integer>, KSUID::Type] the value to cast into a KSUID
+      # @return [KSUID::Type] the type-casted value
+      def cast(value)
+        KSUID.call(value)
+      end
+
+      # Converts a value from database input to a KSUID
+      #
+      # @param value [String, nil] the database-serialized KSUID to convert
+      # @return [KSUID::Type] the deserialized KSUID
+      def deserialize(value)
+        return unless value
+
+        value = value.to_s if value.is_a?(::ActiveRecord::Type::Binary::Data)
+        KSUID.call(value)
+      end
+
+      # Casts the value from a KSUID into a database-understandable format
+      #
+      # @param value [KSUID::Type, nil] the KSUID in Ruby format
+      # @return [String, nil] the base 62-encoded KSUID for storage in the database
+      def serialize(value)
+        return unless value
+
+        super(KSUID.call(value).to_bytes)
+      end
+    end
+  end
+end
+
+ActiveRecord::Type.register(:ksuid_binary, KSUID::ActiveRecord::BinaryType)

data/lib/ksuid/activerecord/table_definition.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module KSUID
+  module ActiveRecord
+    # Extends ActiveRecord's table definition language for KSUIDs
+    module TableDefinition
+      # Defines a field as a string-based KSUID
+      #
+      # @example Define a KSUID field as a non-primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true do |table|
+      #       table.ksuid :ksuid, index: true, unique: true
+      #     end
+      #   end
+      #
+      # @example Define a KSUID field as a primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true, id: false do |table|
+      #       table.ksuid :id, primary_key: true
+      #     end
+      #   end
+      #
+      # @param args [Array<Symbol>] the list of fields to define as KSUIDs
+      # @param options [Hash] see {ActiveRecord::ConnectionAdapters::TableDefinition}
+      # @return [void]
+      def ksuid(*args, **options)
+        args.each { |name| column(name, :string, **options.merge(limit: 27)) }
+      end
+
+      # Defines a field as a binary-based KSUID
+      #
+      # @example Define a KSUID field as a non-primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true do |table|
+      #       table.ksuid_binary :ksuid, index: true, unique: true
+      #     end
+      #   end
+      #
+      # @example Define a KSUID field as a primary key
+      #   ActiveRecord::Schema.define do
+      #     create_table :events, force: true, id: false do |table|
+      #       table.ksuid_binary :id, primary_key: true
+      #     end
+      #   end
+      #
+      # @param args [Array<Symbol>] the list of fields to define as KSUIDs
+      # @param options [Hash] see {ActiveRecord::ConnectionAdapters::TableDefinition}
+      # @return [void]
+      def ksuid_binary(*args, **options)
+        args.each { |name| column(name, :binary, **options.merge(limit: 20)) }
+      end
+    end
+  end
+end
+
+ActiveRecord::ConnectionAdapters::TableDefinition.include(KSUID::ActiveRecord::TableDefinition)

data/lib/ksuid/activerecord/type.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module KSUID
+  module ActiveRecord
+    # A string-serialized KSUID for storage within an ActiveRecord database
+    #
+    # @api private
+    #
+    # @example Set an attribute as a KSUID using the verbose syntax
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, KSUID::ActiveRecord::Type.new, default: -> { KSUID.new }
+    #   end
+    #
+    # @example Set an attribute as a KSUID using the pre-registered type
+    #   class Event < ActiveRecord::Base
+    #     attribute :ksuid, :ksuid, default: -> { KSUID.new }
+    #   end
+    class Type < ::ActiveRecord::Type::String
+      # Casts a value from user input into a KSUID
+      #
+      # Type casting happens via the attribute setter and can take input from
+      # many places, including:
+      #
+      #   1. The Rails form builder
+      #   2. Directly from the attribute setter
+      #   3. From the model initializer
+      #
+      # @param value [String, Array<Integer>, KSUID::Type] the value to cast into a KSUID
+      # @return [KSUID::Type] the type-casted value
+      def cast(value)
+        KSUID.call(value)
+      end
+
+      # Converts a value from database input to a KSUID
+      #
+      # @param value [String, nil] the database-serialized KSUID to convert
+      # @return [KSUID::Type] the deserialized KSUID
+      def deserialize(value)
+        return unless value
+
+        KSUID.from_base62(value)
+      end
+
+      # Casts the value from a KSUID into a database-understandable format
+      #
+      # @param value [KSUID::Type, nil] the KSUID in Ruby format
+      # @return [String, nil] the base 62-encoded KSUID for storage in the database
+      def serialize(value)
+        return unless value
+
+        KSUID.call(value).to_s
+      end
+    end
+  end
+end
+
+ActiveRecord::Type.register(:ksuid, KSUID::ActiveRecord::Type)

data/lib/ksuid/activerecord.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'ksuid/activerecord/binary_type'
+require 'ksuid/activerecord/type'
+
+module KSUID
+  # Enables an Active Record model to have a KSUID attribute
+  #
+  # @api public
+  module ActiveRecord
+    # Builds a module to include into the model
+    #
+    # @api public
+    #
+    # @example Add a `#ksuid` attribute to a model
+    #   class Event < ActiveRecord::Base
+    #     include KSUID::ActiveRecord[:ksuid]
+    #   end
+    #
+    # @example Add a `#remote_id` attribute to a model and overrides `#created_at` to use the KSUID
+    #   class Event < ActiveRecord::Base
+    #     include KSUID::ActiveRecord[:remote_id, created_at: true]
+    #   end
+    #
+    # @param field [String, Symbol] the name of the field to use as a KSUID
+    # @param created_at [Boolean] whether to override the `#created_at` method
+    # @param binary [Boolean] whether to store the KSUID as a binary or a string
+    # @return [Module] the module to include into the model
+    def self.[](field, created_at: false, binary: false)
+      Module
+        .new
+        .tap do |mod|
+          define_attribute(field, mod, binary)
+          define_created_at(field, mod) if created_at
+        end
+    end
+
+    # Defines the attribute method that will be written in the module
+    #
+    # @api private
+    #
+    # @param field [String, Symbol] the name of the field to set as an attribute
+    # @param mod [Module] the module to extend
+    # @return [void]
+    def self.define_attribute(field, mod, binary)
+      type = 'ksuid'
+      type = 'ksuid_binary' if binary
+
+      mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.included(base)
+          base.__send__(:attribute, :#{field}, :#{type}, default: -> { KSUID.new })
+        end
+      RUBY
+    end
+    private_class_method :define_attribute
+
+    # Defines the `#created_at` method that will be written in the module
+    #
+    # @api private
+    #
+    # @param field [String, Symbol] the name of the KSUID attribute field
+    # @param mod [Module] the module to extend
+    # @return [void]
+    def self.define_created_at(field, mod)
+      mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def created_at
+          return unless #{field}
+
+          #{field}.to_time
+        end
+      RUBY
+    end
+    private_class_method :define_created_at
+  end
+end

data/lib/ksuid/base62.rb

@@ -20,6 +20,24 @@ module KSUID
     # @api private
     BASE = CHARSET.size
 
+    # A matcher that checks whether a String has a character outside the charset
+    #
+    # @api private
+    MATCHER = /[^#{CHARSET}]/.freeze
+
+    # Checks whether a string is a base 62-compatible string
+    #
+    # @api public
+    #
+    # @example Checks a KSUID for base 62 compatibility
+    #   KSUID::Base62.compatible?("15Ew2nYeRDscBipuJicYjl970D1") #=> true
+    #
+    # @param string [String] the string to check for compatibility
+    # @return [Boolean]
+    def self.compatible?(string)
+      string.each_char.all? { |char| !MATCHER.match?(char) }
+    end
+
     # Decodes a base 62-encoded string into an integer
     #
     # @api public
@@ -71,7 +89,7 @@ module KSUID
     #      255, 255, 255, 255, 255, 255, 255, 255, 255, 255]
     #   )
     #
-    # @param bytes [String|Array<Integer>] the bytes to encode
+    # @param bytes [String, Array<Integer>] the bytes to encode
     # @return [String] the encoded bytes as a base 62 string
     def self.encode_bytes(bytes)
       encode(Utils.int_from_bytes(bytes))

data/lib/ksuid/configuration.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module KSUID
+  # Encapsulates the configuration for the KSUID gem as a whole.
+  #
+  # You can override the generation of the random payload data by setting the
+  # {#random_generator} value to a valid random payload generator. This should
+  # be done via the module-level {KSUID.configure} method.
+  #
+  # The gem-level configuration lives at the module-level {KSUID.config}.
+  #
+  # @api semipublic
+  class Configuration
+    # Raised when the gem is misconfigured.
+    ConfigurationError = Class.new(StandardError)
+
+    # The default generator for generating random payloads
+    #
+    # @api private
+    #
+    # @return [Proc]
+    def self.default_generator
+      -> { SecureRandom.random_bytes(BYTES[:payload]) }
+    end
+
+    # Instantiates a new KSUID configuration
+    #
+    # @api private
+    #
+    # @return [KSUID::Configuration] the new configuration
+    def initialize
+      self.random_generator = self.class.default_generator
+    end
+
+    # The method for generating random payloads in the gem
+    #
+    # @api private
+    #
+    # @return [#call] a callable that returns 16 bytes
+    attr_reader :random_generator
+
+    # Override the method for generating random payloads in the gem
+    #
+    # @api semipublic
+    #
+    # @example Override the random generator with a null data generator
+    #   KSUID.configure do |config|
+    #     config.random_generator = -> { "\x00" * KSUID::BYTES[:payload] }
+    #   end
+    #
+    # @example Override the random generator with the faster, but less secure, Random
+    #   KSUID.configure do |config|
+    #     config.random_generator = -> { Random.new.bytes(KSUID::BYTES[:payload]) }
+    #   end
+    #
+    # @param generator [#call] a callable that returns 16 bytes
+    # @return [#call] a callable that returns 16 bytes
+    def random_generator=(generator)
+      assert_generator_is_callable(generator)
+      assert_payload_size(generator)
+
+      @random_generator = generator
+    end
+
+    private
+
+    # Raises an error if the assigned generator is not callable
+    #
+    # @api private
+    #
+    # @raise [ConfigurationError] if the generator is not callable
+    # @return [nil]
+    def assert_generator_is_callable(generator)
+      return if generator.respond_to?(:call)
+
+      raise ConfigurationError, "Random generator #{generator} is not callable"
+    end
+
+    # Raises an error if the assigned generator generates the wrong size
+    #
+    # @api private
+    #
+    # @raise [ConfigurationError] if the generator generates the wrong size payload
+    # @return [nil]
+    def assert_payload_size(generator)
+      return if (length = generator.call.length) == (expected_length = BYTES[:payload])
+
+      raise ConfigurationError, 'Random generator generates the wrong number of bytes ' \
+        "(#{length} generated, #{expected_length} expected)"
+    end
+  end
+end

data/lib/ksuid/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module KSUID
+  # Enables the usage of KSUID types within ActiveRecord when Rails is loaded
+  #
+  # @api private
+  class Railtie < ::Rails::Railtie
+    initializer 'ksuid' do
+      ActiveSupport.on_load :active_record do
+        require 'ksuid/activerecord'
+        require 'ksuid/activerecord/table_definition'
+      end
+    end
+  end
+end

data/lib/ksuid/type.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'securerandom'
 require_relative 'base62'
 require_relative 'utils'
 
@@ -31,11 +30,11 @@ module KSUID
     # @example Generate a new KSUID for a given timestamp
     #   KSUID::Type.new(time: Time.parse('2017-11-05 15:00:04 UTC'))
     #
-    # @param payload [String|Array<Integer>|nil] the payload for the KSUID
+    # @param payload [String, Array<Integer>, nil] the payload for the KSUID
     # @param time [Time] the timestamp to use for the KSUID
     # @return [KSUID::Type] the generated KSUID
     def initialize(payload: nil, time: Time.now)
-      payload ||= SecureRandom.random_bytes(BYTES[:payload])
+      payload ||= KSUID.config.random_generator.call
       byte_encoding = Utils.int_to_bytes(time.to_i - EPOCH_TIME)
 
       @uid = byte_encoding.bytes + payload.bytes
@@ -64,6 +63,48 @@ module KSUID
       other.to_s == to_s
     end
 
+    # Checks whether this KSUID hashes to the same hash key as another
+    #
+    # @api semipublic
+    #
+    # @example Checks whether two KSUIDs hash to the same key
+    #   KSUID.new.eql? KSUID.new
+    #
+    # @param other [KSUID::Type] the other KSUID to check against
+    # @return [Boolean]
+    def eql?(other)
+      hash == other.hash
+    end
+
+    # Generates the key to use when using a KSUID as a hash key
+    #
+    # @api semipublic
+    #
+    # @example Using a KSUID as a Hash key
+    #   ksuid1 = KSUID.new
+    #   ksuid2 = KSUID.from_base62(ksuid1.to_s)
+    #   values_by_ksuid = {}
+    #
+    #   values_by_ksuid[ksuid1] = "example"
+    #   values_by_ksuid[ksuid2] #=> "example"
+    #
+    # @return [Integer]
+    def hash
+      @uid.hash
+    end
+
+    # Prints the KSUID for debugging within a console
+    #
+    # @api public
+    #
+    # @example Show the maximum KSUID
+    #   KSUID.max.inspect  #=> "<KSUID(aWgEPTl1tmebfsQzFP4bxwgy80V)>"
+    #
+    # @return [String]
+    def inspect
+      "<KSUID(#{self})>"
+    end
+
     # The payload for the KSUID, as a hex-encoded string
     #
     # This is generally useful for comparing against the Go tool
@@ -121,9 +162,7 @@ module KSUID
     #
     # @return [Integer] the Unix timestamp for the event (without the epoch shift)
     def to_i
-      unix_time = Utils.int_from_bytes(uid.first(BYTES[:timestamp]))
-
-      unix_time
+      Utils.int_from_bytes(uid.first(BYTES[:timestamp]))
     end
 
     # The KSUID as a base 62-encoded string

data/lib/ksuid/utils.rb

@@ -5,7 +5,19 @@ module KSUID
   #
   # @api private
   module Utils
-    # Converts a byte string into a byte array
+    # A regular expression for splitting bytes out of a "binary" string
+    #
+    # @api private
+    # @return [Regexp] the splitter
+    BYTES = /.{8}/.freeze
+
+    # A regular expression for splitting a String into pairs of characters
+    #
+    # @api private
+    # @return [Regexp] the splitter
+    PAIRS = /.{2}/.freeze
+
+    # Converts a byte array into a byte string
     #
     # @param bytes [String] a byte string
     # @return [Array<Integer>] an array of bytes from the byte string
@@ -13,22 +25,36 @@ module KSUID
       bytes.pack('C*')
     end
 
+    # Converts a hex string into a byte string
+    #
+    # @param hex [String] a hex-encoded KSUID
+    # @param bits [Integer] the expected number of bits for the result
+    # @return [String] the byte string
+    def self.byte_string_from_hex(hex, bits = 32)
+      byte_array =
+        hex
+        .rjust(bits, '0')
+        .scan(PAIRS)
+        .map { |bytes| bytes.to_i(16) }
+
+      byte_string_from_array(byte_array)
+    end
+
     # Converts a byte string or byte array into a hex-encoded string
     #
-    # @param bytes [String|Array<Integer>] the byte string or array
+    # @param bytes [String, Array<Integer>] the byte string or array
     # @return [String] the byte string as a hex-encoded string
     def self.bytes_to_hex_string(bytes)
       bytes = bytes.bytes if bytes.is_a?(String)
 
       byte_string_from_array(bytes)
-        .unpack('H*')
-        .first
+        .unpack1('H*')
         .upcase
     end
 
     # Converts a byte string or byte array into an integer
     #
-    # @param bytes [String|Array<Integer>] the byte string or array
+    # @param bytes [String, Array<Integer>] the byte string or array
     # @return [Integer] the resulting integer
     def self.int_from_bytes(bytes)
       bytes = bytes.bytes if bytes.is_a?(String)
@@ -48,9 +74,8 @@ module KSUID
       int
         .to_s(2)
         .rjust(bits, '0')
-        .split('')
-        .each_slice(8)
-        .map { |digits| digits.join.to_i(2) }
+        .scan(BYTES)
+        .map { |digits| digits.to_i(2) }
         .pack("C#{bits / 8}")
     end
   end

data/lib/ksuid/version.rb

@@ -4,5 +4,5 @@ module KSUID
   # The version of the KSUID gem
   #
   # @return [String]
-  VERSION = '0.1.0'
+  VERSION = '0.4.0'
 end

data/lib/ksuid.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'ksuid/configuration'
 require_relative 'ksuid/type'
 require_relative 'ksuid/version'
 
@@ -74,6 +75,57 @@ module KSUID
   # @return [String]
   MAX_STRING_ENCODED = 'aWgEPTl1tmebfsQzFP4bxwgy80V'
 
+  # Converts a KSUID-compatible value into an actual KSUID
+  #
+  # @api public
+  #
+  # @example Converts a base 62 KSUID string into a KSUID
+  #   KSUID.call('15Ew2nYeRDscBipuJicYjl970D1')
+  #
+  # @param ksuid [String, Array<Integer>, KSUID::Type] the KSUID-compatible value
+  # @return [KSUID::Type] the converted KSUID
+  # @raise [ArgumentError] if the value is not KSUID-compatible
+  def self.call(ksuid)
+    return unless ksuid
+
+    case ksuid
+    when KSUID::Type then ksuid
+    when Array then KSUID.from_bytes(ksuid)
+    when String then cast_string(ksuid)
+    else
+      raise ArgumentError, "Cannot convert #{ksuid.inspect} to KSUID"
+    end
+  end
+
+  # The configuration for creating new KSUIDs
+  #
+  # @api private
+  #
+  # @return [KSUID::Configuration] the gem's configuration
+  def self.config
+    @config ||= KSUID::Configuration.new
+  end
+
+  # Configures the KSUID gem by passing a block
+  #
+  # @api public
+  #
+  # @example Override the random generator with a null data generator
+  #   KSUID.configure do |config|
+  #     config.random_generator = -> { "\x00" * KSUID::BYTES[:payload] }
+  #   end
+  #
+  # @example Override the random generator with the faster, but less secure, Random
+  #   KSUID.configure do |config|
+  #     config.random_generator = -> { Random.new.bytes(KSUID::BYTES[:payload]) }
+  #   end
+  #
+  # @return [KSUID::Configuration] the gem's configuration
+  def self.configure
+    yield config if block_given?
+    config
+  end
+
   # Converts a base 62-encoded string into a KSUID
   #
   # @api public
@@ -98,7 +150,7 @@ module KSUID
   # @example Parse a KSUID byte string into an object
   #   KSUID.from_bytes("\x06\x83\xF7\x89\x04\x9C\xC2\x15\xC0\x99\xD4+xM\xBE\x994\e\xD7\x9C")
   #
-  # @param bytes [String|Array<Integer>] the byte string or array to convert into an object
+  # @param bytes [String, Array<Integer>] the byte string or array to convert into an object
   # @return [KSUID::Type] the KSUID generated from the bytes
   def self.from_bytes(bytes)
     bytes = bytes.bytes if bytes.is_a?(String)
@@ -131,10 +183,27 @@ module KSUID
   # @example Generate a new KSUID for a given timestamp
   #   KSUID.new(time: Time.parse('2017-11-05 15:00:04 UTC'))
   #
-  # @param payload [String|Array<Integer>|nil] the payload for the KSUID
+  # @param payload [String, Array<Integer>, nil] the payload for the KSUID
   # @param time [Time] the timestamp to use for the KSUID
   # @return [KSUID::Type] the generated KSUID
   def self.new(payload: nil, time: Time.now)
     Type.new(payload: payload, time: time)
   end
+
+  # Casts a string into a KSUID
+  #
+  # @api private
+  #
+  # @param ksuid [String] the string to convert into a KSUID
+  # @return [KSUID::Type] the converted KSUID
+  def self.cast_string(ksuid)
+    if Base62.compatible?(ksuid)
+      KSUID.from_base62(ksuid)
+    else
+      KSUID.from_bytes(ksuid)
+    end
+  end
+  private_class_method :cast_string
 end
+
+require 'ksuid/railtie' if defined?(Rails)

metadata

@@ -1,32 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: ksuid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Michael Herold
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-11-05 00:00:00.000000000 Z
+date: 2022-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
 description: Ruby implementation of the K-Sortable Unique IDentifier
 email:
-- michael@michaeljherold.com
+- opensource@michaeljherold.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -37,15 +37,21 @@ files:
 - README.md
 - ksuid.gemspec
 - lib/ksuid.rb
+- lib/ksuid/activerecord.rb
+- lib/ksuid/activerecord/binary_type.rb
+- lib/ksuid/activerecord/table_definition.rb
+- lib/ksuid/activerecord/type.rb
 - lib/ksuid/base62.rb
+- lib/ksuid/configuration.rb
+- lib/ksuid/railtie.rb
 - lib/ksuid/type.rb
 - lib/ksuid/utils.rb
 - lib/ksuid/version.rb
-homepage: https://github.com/michaelherold/ksuid
+homepage: https://github.com/michaelherold/ksuid-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -60,10 +66,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.13
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: Ruby implementation of the K-Sortable Unique IDentifier
 test_files: []
-has_rdoc: