ksuid 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b5bd73fb4864bb0df8cf57c1214622325afa077e031baffb2a1e73b2820f2c
-  data.tar.gz: 55245cb9fba9e57c9bf115f189fb954f2e1b08604e89ba8b5c9aeea73967e5ba
+  metadata.gz: a25a1c0246464a41b5b419ad0fffbd8c5b08b7dfb882ccb31a29a0a6fbbc0fe1
+  data.tar.gz: 70a978445c93cc062cb704a5156fd919c623677fc1666723ba1f828067978fcd
 SHA512:
-  metadata.gz: af5cc8ed5f9d81616fd61e6f03690c841489e9f2c2d28d892137c1eb410ec88e61540cd3dd10d5ac0d0439f9b9ecd9afdc00cceae61276cca521d5436c159e29
-  data.tar.gz: 13479dc7d24cf9422c6bc3ca705c6c777abf121f5ade7a9f9c8124c7b9f8034844d8707b2f8265c18178b9b16b50be28a3c1894888d97fe7f42aa1e981d11a97
+  metadata.gz: 7ed9fde240ebee2cdffcb81877548b780286844d2ccfa6a4200f4a0c36161e1d53f073b761e22d7b3fb0d857a31b2fae50fdb30a6ca3571b1cc933ea09281363
+  data.tar.gz: 946ad6b51f84fca3b1a0230c4892fc3afd862baabe232efac3b0f9d196d16e2c16702e645faf12bcb9e2614c15a504f007c9cc44383c5ac6e87b8feeb5554d7f

data/CHANGELOG.md

@@ -4,6 +4,22 @@ 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.5.0](https://github.com/michaelherold/ksuid/compare/v0.4.0...v0.5.0) - 2022-08-18
+
+### Added
+
+- If you'd rather deal in KSUID strings instead of `KSUID::Type`s, you can now generate them simply with `KSUID.string`. It takes the same arguments, `payload` and `time` as `KSUID.new`, but returns a string instead of a `KSUID::Type`.
+- `KSUID.prefixed` and the `KSUID::Prefixed` class now can generate prefixed KSUIDs to make them visually identifiable for their source. You cannot prefix a binary-encoded KSUID, only base 62-encoded ones.
+- `ActiveRecord::KSUID` now accepts a `prefix:` argument for handling prefixed KSUIDs. In addition, the `ksuid` column type also accepts a `prefix:` argument to calculate the intended size of the column with the prefix.
+
+### Deprecated
+
+- `KSUID::ActiveRecord` is now `ActiveRecord::KSUID`. The original constant will continue to work until v1.0.0, but will emit a warning upon boot of your application. To silence the deprecation, change all uses of `KSUID::ActiveRecord` to the new constant, `ActiveRecord::KSUID`. See the [upgrading notice][./UPGRADING.md] for more information.
+
+### Miscellaneous
+
+- The compatibility check for the Base62 implementation in the gem is about 10x faster now. The original optimization did not optimize as much due to an error with the benchmark. This change has a tested benchmark that shows a great improvement. Note that this is a micro-optimization and we see no real performance gain in the parsing of KSUID strings.
+
 ## [0.4.0](https://github.com/michaelherold/ksuid/compare/v0.3.0...v0.4.0) - 2022-07-29
 
 ### Added

data/README.md

@@ -100,10 +100,34 @@ KSUID.configure do |config|
 end
 ```
 
+### Prefixed KSUIDs
+
+If you use KSUIDs in multiple contexts, you can prefix them to make them easily identifiable.
+
+```ruby
+ksuid = KSUID.prefixed('evt_')
+```
+
+Just like a normal KSUID, you can use a specific timestamp:
+
+``` ruby
+ksuid = KSUID.prefixed('evt_', time: time)  # where time is a Time-like object
+```
+
+You can also parse a prefixed KSUID from a string that you received:
+
+```ruby
+ksuid = KSUID::Prefixed.from_base62(base62_string, prefix: 'evt_')
+```
+
+Prefixed KSUIDs order themselves with non-prefixed KSUIDs as if their prefix did not exist. With other prefixed KSUIDs, they order first by their prefix, then their timestamp.
+
 ### 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.
 
+_Note: In v1.0.0 of KSUID for Ruby, we will extract this behavior into a separate gem, `activerecord-ksuid`. It will be API-compatible with the implementation in v0.5.0+ of KSUID for Ruby. There will be upgrade instructions for v1.0.0 once we release it._
+
 #### 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:
@@ -124,7 +148,7 @@ Then, to add proper handling to the field, you will want to mix a module into th
 
 ```ruby
 class Event < ApplicationRecord
-  include KSUID::ActiveRecord[:unique_id]
+  include ActiveRecord::KSUID[:unique_id]
 end
 ```
 
@@ -148,7 +172,7 @@ Once you have generated the table that you will use for your model, you will nee
 
 ```ruby
 class Event < ApplicationRecord
-  include KSUID::ActiveRecord[:my_field_name]
+  include ActiveRecord::KSUID[:my_field_name]
 end
 ```
 
@@ -168,7 +192,7 @@ You will need to mix in the module into your model as well:
 
 ```ruby
 class Event < ApplicationRecord
-  include KSUID::ActiveRecord[:id]
+  include ActiveRecord::KSUID[:id]
 end
 ```
 
@@ -177,10 +201,10 @@ end
 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'
+require 'active_record/ksuid'
 
 # If you will be using the ksuid column type in a migration
-require 'ksuid/activerecord/table_definition'
+require 'active_record/ksuid/table_definition'
 ```
 
 Once you have required the file(s) that you need, everything else will work as it does above.
@@ -193,17 +217,39 @@ When you include the KSUID module into your model, you will want to pass the `:b
 
 ```ruby
 class Event < ApplicationRecord
-  include KSUID::ActiveRecord[:my_field_name, binary: true]
+  include ActiveRecord::KSUID[:my_field_name, binary: true]
 end
 ```
 
+#### Using a prefix on your KSUID field
+
+For prefixed KSUIDs in ActiveRecord, you must pass the intended prefix during table definition so that the field is of appropriate size.
+
+```ruby
+class CreateEvents < ActiveRecord::Migration[5.2]
+  create_table :events do |table|
+    table.ksuid :ksuid, prefix: 'evt_'
+  end
+end
+```
+
+You also must pass it in the module builder that you include in your model:
+
+```ruby
+class Event < ApplicationRecord
+  include ActiveRecord::KSUID[:ksuid, prefix: 'evt_']
+end
+```
+
+You cannot use a prefix with a binary-encoded KSUID.
+
 #### 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]
+  include ActiveRecord::KSUID[:my_field_name, created_at: true]
 end
 ```
 
@@ -217,10 +263,10 @@ So you’re interested in contributing to KSUID? Check out our [contributing gui
 
 This library aims to support and is [tested against][actions] the following Ruby versions:
 
-* Ruby 2.5
-* Ruby 2.6
 * Ruby 2.7
-* JRuby 9.2
+* Ruby 3.0
+* Ruby 3.1
+* JRuby 9.3
 
 If something doesn't work on one of these versions, it's a bug.
 

data/UPGRADING.md

@@ -0,0 +1,11 @@
+# Upgrading instructions for KSUID for Ruby
+
+## v0.5.0
+
+### Deprecated `KSUID::ActiveRecord` in favor of `ActiveRecord::KSUID`
+
+This version deprecates the original constant for the ActiveRecord integration, `KSUID::ActiveRecord`. This change is in preparation for extracting the ActiveRecord integration into its own gem. Continuing to use the original constant will show deprecation warnings upon boot of your application.
+
+Migrating for this version should be quick: simply do a global replace of `KSUID::ActiveRecord` for `ActiveRecord::KSUID`. No other changes should be necessary.
+
+In the future release of v1.0.0, you will need to also include `activerecord-ksuid` your Gemfile. This gem is as-yet unreleased, with a release intended concurrently with v1.0.0 of KSUID for Ruby.

data/ksuid.gemspec

@@ -13,10 +13,12 @@ Gem::Specification.new do |spec|
   spec.homepage    = 'https://github.com/michaelherold/ksuid-ruby'
   spec.license     = 'MIT'
 
-  spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md]
+  spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md UPGRADING.md]
   spec.files += %w[ksuid.gemspec]
   spec.files += Dir['lib/**/*.rb']
   spec.require_paths = ['lib']
 
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
   spec.add_development_dependency 'bundler', '>= 1.15'
 end

data/lib/{ksuid/activerecord → active_record/ksuid}/binary_type.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
-module KSUID
-  module ActiveRecord
+module ActiveRecord
+  module KSUID
     # 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 }
+    #   class EventWithBareBinaryType < ActiveRecord::Base
+    #     attribute :ksuid, ActiveRecord::KSUID::BinaryType.new, default: -> { KSUID.new }
     #   end
     #
     # @example Set an attribute as a KSUID using the pre-registered type
-    #   class Event < ActiveRecord::Base
+    #   class EventWithRegisteredBinaryType < ActiveRecord::Base
     #     attribute :ksuid, :ksuid_binary, default: -> { KSUID.new }
     #   end
     class BinaryType < ::ActiveRecord::Type::Binary
@@ -28,7 +28,7 @@ module KSUID
       # @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)
+        ::KSUID.call(value)
       end
 
       # Converts a value from database input to a KSUID
@@ -39,7 +39,7 @@ module KSUID
         return unless value
 
         value = value.to_s if value.is_a?(::ActiveRecord::Type::Binary::Data)
-        KSUID.call(value)
+        ::KSUID.call(value)
       end
 
       # Casts the value from a KSUID into a database-understandable format
@@ -49,10 +49,10 @@ module KSUID
       def serialize(value)
         return unless value
 
-        super(KSUID.call(value).to_bytes)
+        super(::KSUID.call(value).to_bytes)
       end
     end
   end
 end
 
-ActiveRecord::Type.register(:ksuid_binary, KSUID::ActiveRecord::BinaryType)
+ActiveRecord::Type.register(:ksuid_binary, ActiveRecord::KSUID::BinaryType)

data/lib/active_record/ksuid/prefixed_type.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module KSUID
+    # A string-serialized, prefixed KSUID for storage within an ActiveRecord database
+    #
+    # @api private
+    # @since 0.5.0
+    #
+    # @example Set an attribute as a prefixed KSUID using the verbose syntax
+    #   class EventWithBarePrefixedType < ActiveRecord::Base
+    #     attribute(
+    #       :ksuid,
+    #       ActiveRecord::KSUID::PrefixedType.new(prefix: 'evt_'),
+    #       default: -> { KSUID.prefixed('evt_') }
+    #     )
+    #   end
+    #
+    # @example Set an attribute as a prefixed KSUID using the pre-registered type
+    #   class EventWithRegisteredPrefixedType < ActiveRecord::Base
+    #     attribute :ksuid, :ksuid_prefixed, prefix: 'evt_', default: -> { KSUID.prefixed('evt_') }
+    #   end
+    class PrefixedType < ::ActiveRecord::Type::String
+      # Instantiates an ActiveRecord::Type for handling prefixed KSUIDs
+      #
+      # @param prefix [String] the prefix to add to the KSUID
+      def initialize(prefix: '')
+        @prefix = prefix
+        super()
+      end
+
+      # Casts a value from user input into a {KSUID::Prefixed}
+      #
+      # 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::Prefixed] the value to cast into a KSUID
+      # @return [KSUID::Prefixed] the type-casted value
+      def cast(value)
+        ::KSUID::Prefixed.call(value, prefix: @prefix)
+      end
+
+      # Converts a value from database input to a {KSUID::Prefixed}
+      #
+      # @param value [String, nil] the database-serialized, prefixed KSUID to convert
+      # @return [KSUID::Prefixed] the deserialized, prefixed KSUID
+      def deserialize(value)
+        return unless value
+
+        ::KSUID::Prefixed.from_base62(value, prefix: @prefix)
+      end
+
+      # Casts the value from a KSUID into a database-understandable format
+      #
+      # @param value [KSUID::Prefixed, nil] the prefixed KSUID in Ruby format
+      # @return [String, nil] the base 62-encoded, prefixed KSUID for storage in the database
+      def serialize(value)
+        return unless value
+
+        ::KSUID::Prefixed.call(value, prefix: @prefix).to_s
+      end
+    end
+  end
+end
+
+ActiveRecord::Type.register(:ksuid_prefixed, ActiveRecord::KSUID::PrefixedType)

data/lib/active_record/ksuid/railtie.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  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 'active_record/ksuid'
+          require 'ksuid/activerecord'
+        end
+      end
+
+      initializer 'ksuid.table_definition' do
+        ActiveSupport.on_load :active_record do
+          require 'active_record/ksuid/table_definition'
+
+          ActiveRecord::ConnectionAdapters::TableDefinition.include(
+            ActiveRecord::KSUID::TableDefinition
+          )
+        end
+      end
+    end
+  end
+end

data/lib/{ksuid/activerecord → active_record/ksuid}/table_definition.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-module KSUID
-  module ActiveRecord
+module ActiveRecord
+  module KSUID
     # Extends ActiveRecord's table definition language for KSUIDs
     module TableDefinition
       # Defines a field as a string-based KSUID
@@ -22,9 +22,12 @@ module KSUID
       #
       # @param args [Array<Symbol>] the list of fields to define as KSUIDs
       # @param options [Hash] see {ActiveRecord::ConnectionAdapters::TableDefinition}
+      # @option options [String] :prefix the prefix expected in front of the KSUID
       # @return [void]
       def ksuid(*args, **options)
-        args.each { |name| column(name, :string, **options.merge(limit: 27)) }
+        prefix_length = options.delete(:prefix)&.length || 0
+
+        args.each { |name| column(name, :string, **options.merge(limit: 27 + prefix_length)) }
       end
 
       # Defines a field as a binary-based KSUID
@@ -52,5 +55,3 @@ module KSUID
     end
   end
 end
-
-ActiveRecord::ConnectionAdapters::TableDefinition.include(KSUID::ActiveRecord::TableDefinition)

data/lib/{ksuid/activerecord → active_record/ksuid}/type.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
-module KSUID
-  module ActiveRecord
+module ActiveRecord
+  module KSUID
     # 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 }
+    #   class EventWithBareType < ActiveRecord::Base
+    #     attribute :ksuid, ActiveRecord::KSUID::Type.new, default: -> { KSUID.new }
     #   end
     #
     # @example Set an attribute as a KSUID using the pre-registered type
-    #   class Event < ActiveRecord::Base
+    #   class EventWithRegisteredType < ActiveRecord::Base
     #     attribute :ksuid, :ksuid, default: -> { KSUID.new }
     #   end
     class Type < ::ActiveRecord::Type::String
@@ -28,7 +28,7 @@ module KSUID
       # @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)
+        ::KSUID.call(value)
       end
 
       # Converts a value from database input to a KSUID
@@ -38,7 +38,7 @@ module KSUID
       def deserialize(value)
         return unless value
 
-        KSUID.from_base62(value)
+        ::KSUID.from_base62(value)
       end
 
       # Casts the value from a KSUID into a database-understandable format
@@ -48,10 +48,10 @@ module KSUID
       def serialize(value)
         return unless value
 
-        KSUID.call(value).to_s
+        ::KSUID.call(value).to_s
       end
     end
   end
 end
 
-ActiveRecord::Type.register(:ksuid, KSUID::ActiveRecord::Type)
+ActiveRecord::Type.register(:ksuid, ActiveRecord::KSUID::Type)

data/lib/active_record/ksuid.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'active_record/ksuid/binary_type'
+require 'active_record/ksuid/prefixed_type'
+require 'active_record/ksuid/type'
+
+# The Ruby on Rails object-relational mapper
+#
+# @see https://guides.rubyonrails.org/ Ruby on Rails documentation
+module ActiveRecord
+  # Enables an Active Record model to have a KSUID attribute
+  #
+  # @api public
+  # @since 0.5.0
+  module KSUID
+    # Builds a module to include into the model
+    #
+    # @api public
+    #
+    # @example Add a `#ksuid` attribute to a model
+    #   class Event < ActiveRecord::Base
+    #     include ActiveRecord::KSUID[:ksuid]
+    #   end
+    #
+    # @example Add a `#remote_id` attribute to a model and overrides `#created_at` to use the KSUID
+    #   class Event < ActiveRecord::Base
+    #     include ActiveRecord::KSUID[:remote_id, created_at: true]
+    #   end
+    #
+    # @example Add a prefixed `#ksuid` attribute to a model
+    #   class Event < ActiveRecord::Base
+    #     include ActiveRecord::KSUID[:ksuid, prefix: 'evt_']
+    #   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
+    # @param prefix [String, nil] a prefix to prepend to the KSUID attribute
+    # @return [Module] the module to include into the model
+    def self.[](field, created_at: false, binary: false, prefix: nil)
+      raise ArgumentError, 'cannot include a prefix on a binary KSUID' if binary && prefix
+
+      Module.new.tap do |mod|
+        if prefix
+          define_prefixed_attribute(field, mod, prefix)
+        else
+          define_attribute(field, mod, binary)
+        end
+        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
+    # @param binary [Boolean] whether to store the KSUID as a binary or a string
+    # @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)         # def self.included(base)
+          base.__send__(                #   base.__send__(
+            :attribute,                 #     :attribute,
+            :#{field},                  #     :id,
+            :#{type},                   #     :ksuid,
+            default: -> { ::KSUID.new } #     default: -> { ::KSUID.new }
+          )                             #   )
+        end                             # end
+      RUBY
+    end
+    private_class_method :define_attribute
+
+    # Defines the attribute method that will be written in the module for a field
+    #
+    # @api private
+    #
+    # @param field [String, Symbol] the name of the field to set as an attribute
+    # @param mod [Module] the module to extend
+    # @param prefix [String] the prefix to add to the KSUID
+    # @return [void]
+    def self.define_prefixed_attribute(field, mod, prefix)
+      mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.included(base)                                 # def self.included(base)
+          base.__send__(                                        #   base.__send__(
+            :attribute,                                         #     :attribute,
+            :#{field},                                          #     :id,
+            :ksuid_prefixed,                                    #     :ksuid_prefixed,
+            prefix: #{prefix.inspect},                          #     prefix: 'evt_'
+            default: -> { ::KSUID.prefixed(#{prefix.inspect}) } #     default: -> { ::KSUID.prefixed('evt_') }
+          )                                                     #   )
+        end                                                     # end
+      RUBY
+    end
+    private_class_method :define_prefixed_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           # def created_at
+          return unless #{field} #   return unless ksuid
+
+          #{field}.to_time       #   ksuid.to_time
+        end                      # end
+      RUBY
+    end
+    private_class_method :define_created_at
+  end
+end

data/lib/ksuid/activerecord.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require 'ksuid/activerecord/binary_type'
-require 'ksuid/activerecord/type'
+require 'active_record/ksuid'
 
 module KSUID
   # Enables an Active Record model to have a KSUID attribute
   #
   # @api public
+  # @deprecated Use {ActiveRecord::KSUID} instead.
   module ActiveRecord
     # Builds a module to include into the model
     #
     # @api public
+    # @deprecated Use {::ActiveRecord::KSUID.[]} instead.
     #
     # @example Add a `#ksuid` attribute to a model
     #   class Event < ActiveRecord::Base
@@ -22,54 +23,15 @@ module KSUID
     #     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}
+    # @param (see ::ActiveRecord::KSUID.[])
+    # @return  (see ::ActiveRecord::KSUID.[])
+    def self.[](field, created_at: false, binary: false, prefix: nil)
+      ActiveSupport::Deprecation.instance.warn(
+        'KSUID::ActiveRecord is deprecated! Use ActiveRecord::KSUID instead.',
+        caller_locations
+      )
 
-          #{field}.to_time
-        end
-      RUBY
+      ::ActiveRecord::KSUID[field, created_at: created_at, binary: binary, prefix: prefix]
     end
-    private_class_method :define_created_at
   end
 end

data/lib/ksuid/base62.rb

@@ -35,7 +35,7 @@ module KSUID
     # @param string [String] the string to check for compatibility
     # @return [Boolean]
     def self.compatible?(string)
-      string.each_char.all? { |char| !MATCHER.match?(char) }
+      !MATCHER.match?(string)
     end
 
     # Decodes a base 62-encoded string into an integer
@@ -51,12 +51,12 @@ module KSUID
     def self.decode(ksuid)
       result = 0
 
-      ksuid.split('').each_with_index do |char, position|
+      ksuid.chars.each_with_index do |char, position|
         unless (digit = CHARSET.index(char))
           raise(ArgumentError, "#{ksuid} is not a base 62 number")
         end
 
-        result += digit * BASE**(ksuid.length - (position + 1))
+        result += digit * (BASE**(ksuid.length - (position + 1)))
       end
 
       result
@@ -76,7 +76,7 @@ module KSUID
       chars = encode_without_padding(number)
 
       chars << padding if chars.empty?
-      chars.reverse.join('').rjust(STRING_LENGTH, padding)
+      chars.reverse.join.rjust(STRING_LENGTH, padding)
     end
 
     # Encodes a byte string or byte array into base 62

data/lib/ksuid/configuration.rb

@@ -87,8 +87,11 @@ module KSUID
     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 ' \
+      raise(
+        ConfigurationError,
+        'Random generator generates the wrong number of bytes ' \
         "(#{length} generated, #{expected_length} expected)"
+      )
     end
   end
 end

data/lib/ksuid/prefixed.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module KSUID
+  # Encapsulates the data type for a prefixed KSUID
+  #
+  # When you have different types of KSUIDs in your application, it can be
+  # helpful to add an identifier to the front of them to give you an idea for
+  # what kind of object the KSUID belongs to.
+  #
+  # For example, you might use KSUIDs to identify both Events and Customers. For
+  # an Event, you could prefix the KSUID with the string `evt_`. Likewise, for
+  # Customers, you could prefix them with the string `cus_`.
+  #
+  # {KSUID::Prefixed} gives you affordances for doing just this.
+  #
+  # ## Ordering
+  #
+  # {KSUID::Prefixed}s are partially orderable with {KSUID::Type} by their
+  # timestamps. When ordering them with other {KSUID::Prefixed} instances, they
+  # order first by prefix, then by timestamp. This means that in a mixed
+  # collection, all Customer KSUIDs (prefix: `cus_`) would be grouped before all
+  # Event KSUIDs (prefix `evt_`).
+  #
+  # ## Interface
+  #
+  # You typically will not instantiate this class directly, but instead use the
+  # {KSUID.prefixed} builder method to save some typing.
+  #
+  # The most commonly used helper methods for the {KSUID} module also exist on
+  # {KSUID::Prefixed} for converting between different forms of output.
+  #
+  # ## Differences from {KSUID::Type}
+  #
+  # One other thing to note is that {KSUID::Prefixed} is not intended to handle
+  # binary data because the prefix does not make sense in either the byte string
+  # or packed array formats.
+  #
+  # @since 0.5.0
+  class Prefixed < Type
+    include Comparable
+
+    # Converts a KSUID-compatible value into a {KSUID::Prefixed}
+    #
+    # @api public
+    #
+    # @example Converts a base 62 KSUID string into a {KSUID::Prefixed}
+    #   KSUID::Prefixed.call('15Ew2nYeRDscBipuJicYjl970D1', prefix: 'evt_')
+    #
+    # @param ksuid [String, KSUID::Prefixed, KSUID::Type] the prefixed KSUID-compatible value
+    # @return [KSUID::Prefixed] the converted, prefixed KSUID
+    # @raise [ArgumentError] if the value is not prefixed KSUID-compatible
+    def self.call(ksuid, prefix:)
+      return unless ksuid && prefix
+
+      case ksuid
+      when KSUID::Prefixed then from_base62(ksuid.to_ksuid.to_s, prefix: prefix)
+      when KSUID::Type then from_base62(ksuid.to_s, prefix: prefix)
+      when String then cast_string(ksuid, prefix: prefix)
+      else
+        raise ArgumentError, "Cannot convert #{ksuid.inspect} to KSUID::Prefixed"
+      end
+    end
+
+    # Converts a base 62-encoded string into a {KSUID::Prefixed}
+    #
+    # @api public
+    #
+    # @example Parse a KSUID string into a prefixed object
+    #   KSUID::Prefixed.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW', prefix: 'evt_')
+    #
+    # @param string [String] the base 62-encoded KSUID to convert into an object
+    # @param prefix [String] the prefix to add to the KSUID
+    # @return [KSUID::Prefixed] the prefixed KSUID generated from the string
+    def self.from_base62(string, prefix:)
+      string = string.sub(/\A#{prefix}/, '')
+      int = Base62.decode(string)
+      bytes = Utils.int_to_bytes(int, 160)
+
+      from_bytes(bytes, prefix: prefix)
+    end
+
+    # Casts a string into a {KSUID::Prefixed}
+    #
+    # @api private
+    #
+    # @param ksuid [String] the string to convert into a {KSUID::Prefixed}
+    # @param prefix [String] the prefix to prepend to the KSUID
+    # @return [KSUID::Prefixed] the converted, prefixed KSUID
+    def self.cast_string(ksuid, prefix:)
+      ksuid = ksuid[-KSUID::BYTES[:base62]..-1] if ksuid.length >= KSUID::BYTES[:base62]
+
+      unless Base62.compatible?(ksuid)
+        raise ArgumentError, 'Prefixed KSUIDs cannot be binary strings'
+      end
+
+      from_base62(ksuid, prefix: prefix)
+    end
+    private_class_method :cast_string
+
+    # Converts a byte string or byte array into a KSUID
+    #
+    # @api private
+    #
+    # @param bytes [String] the byte string to convert into an object
+    # @return [KSUID::Prefixed] the prefixed KSUID generated from the bytes
+    def self.from_bytes(bytes, prefix:)
+      bytes = bytes.bytes
+      timestamp = Utils.int_from_bytes(bytes.first(KSUID::BYTES[:timestamp]))
+      payload = Utils.byte_string_from_array(bytes.last(KSUID::BYTES[:payload]))
+
+      new(prefix, payload: payload, time: Time.at(timestamp + EPOCH_TIME))
+    end
+    private_class_method :from_bytes
+
+    # Instantiates a new {KSUID::Prefixed}
+    #
+    # @api semipublic
+    #
+    # @example Generate a new {KSUID::Prefixed} for the current second
+    #   KSUID::Prefixed.new('evt_')
+    #
+    # @example Generate a new {KSUID::Prefixed} for a given timestamp
+    #   KSUID::Prefixed.new('cus_', time: Time.parse('2017-11-05 15:00:04 UTC'))
+    #
+    # @param prefix [String] the prefix to add to 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::Prefix] the generated, prefixed KSUID
+    def initialize(prefix, payload: nil, time: Time.now)
+      raise ArgumentError, 'requires a prefix' unless prefix
+
+      super(payload: payload, time: time)
+
+      @prefix = prefix
+    end
+
+    # The prefix in front of the KSUID
+    #
+    # @api semipublic
+    #
+    # @example Getting the prefix to create a similar {KSUID::Prefixed}
+    #   ksuid1 = KSUID.prefixed('cus_')
+    #   ksuid2 = KSUID.prefixed(ksuid1.prefix)
+    #
+    # @return [String] the prefix of the {KSUID::Prefixed}
+    attr_reader :prefix
+
+    # Implements the Comparable interface for sorting {KSUID::Prefixed}s
+    #
+    # @api private
+    #
+    # @param other [KSUID::Type] the other object to compare against
+    # @return [Integer, nil] nil for uncomparable, -1 for less than other,
+    #   0 for equal to, 1 for greater than other
+    def <=>(other)
+      return unless other.is_a?(Type)
+      return super if other.instance_of?(Type)
+
+      if (result = prefix <=> other.prefix).nonzero?
+        result
+      else
+        super
+      end
+    end
+
+    # Checks whether this {KSUID::Prefixed} is equal to another
+    #
+    # @api semipublic
+    #
+    # @example Checks whether two KSUIDs are equal
+    #   KSUID.prefixed('evt_') == KSUID.prefixed('evt_')
+    #
+    # @param other [KSUID::Prefixed] the other {KSUID::Prefixed} to check against
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Prefixed) &&
+        prefix == other.prefix &&
+        super
+    end
+
+    # Generates the key to use when using a {KSUID::Prefixed} as a hash key
+    #
+    # @api semipublic
+    #
+    # @example Using a KSUID as a Hash key
+    #   ksuid1 = KSUID.prefixed('evt_')
+    #   ksuid2 = ksuid1.dup
+    #   values_by_ksuid = {}
+    #
+    #   values_by_ksuid[ksuid1] = "example"
+    #   values_by_ksuid[ksuid2] #=> "example"
+    #
+    # @return [Integer]
+    def hash
+      [prefix, @uid].hash
+    end
+
+    # The {KSUID::Prefixed} as a prefixed, hex-encoded string
+    #
+    # This is generally useful for comparing against the Go tool.
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID::Prefixed.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW', prefix: 'evt_')
+    #
+    #   ksuid.raw #=> "evt_0683F789049CC215C099D42B784DBE99341BD79C"
+    #
+    # @return [String] a prefixed, hex-encoded string
+    def raw
+      super.prepend(prefix)
+    end
+
+    # Converts the {KSUID::Prefixed} into a {KSUID::Type} by dropping the prefix
+    #
+    # @api public
+    #
+    # @example Convert an Event KSUID into a plain KSUID
+    #   ksuid = KSUID.prefixed('evt_')
+    #
+    #   ksuid.to_ksuid
+    #
+    # @return [KSUID::Type] the non-prefixed KSUID
+    def to_ksuid
+      KSUID.from_base62(to_s.sub(/\A#{prefix}/, ''))
+    end
+
+    # The {KSUID::Prefixed} as a base 62-encoded string
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID::Prefixed.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW', prefix: 'evt_')
+    #
+    #   ksuid.to_s #=> "evt_0vdbMgWkU6slGpLVCqEFwkkZvuW"
+    #
+    # @return [String] the prefixed, base 62-encoded string for the {KSUID::Prefixed}
+    def to_s
+      super.prepend(prefix)
+    end
+  end
+end

data/lib/ksuid/type.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base62'
-require_relative 'utils'
-
 module KSUID
   # Encapsulates the data type for a KSUID
   #

data/lib/ksuid/utils.rb

@@ -61,7 +61,7 @@ module KSUID
 
       bytes
         .map { |byte| byte.to_s(2).rjust(8, '0') }
-        .join('')
+        .join
         .to_i(2)
     end
 

data/lib/ksuid/version.rb

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

data/lib/ksuid.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'ksuid/configuration'
-require_relative 'ksuid/type'
 require_relative 'ksuid/version'
 
 # The K-Sortable Unique IDentifier (KSUID)
@@ -41,6 +40,9 @@ require_relative 'ksuid/version'
 # @example Generate a new KSUID
 #   KSUID.new
 #
+# @example Generate a KSUID prefixed by `evt_`
+#   KSUID.prefixed('evt_')
+#
 # @example Parse a KSUID string that you have received
 #   KSUID.from_base62('aWgEPTl1tmebfsQzFP4bxwgy80V')
 #
@@ -63,7 +65,7 @@ module KSUID
   # The number of bytes that are used to represent each part of a KSUID
   #
   # @return [Hash{Symbol => Integer}] the map of data type to number of bytes
-  BYTES = { payload: 16, timestamp: 4, total: 20 }.freeze
+  BYTES = { base62: 27, payload: 16, timestamp: 4, total: 20 }.freeze
 
   # The number of characters in a base 62-encoded KSUID
   #
@@ -75,6 +77,11 @@ module KSUID
   # @return [String]
   MAX_STRING_ENCODED = 'aWgEPTl1tmebfsQzFP4bxwgy80V'
 
+  autoload :Base62, 'ksuid/base62'
+  autoload :Prefixed, 'ksuid/prefixed'
+  autoload :Type, 'ksuid/type'
+  autoload :Utils, 'ksuid/utils'
+
   # Converts a KSUID-compatible value into an actual KSUID
   #
   # @api public
@@ -89,6 +96,7 @@ module KSUID
     return unless ksuid
 
     case ksuid
+    when KSUID::Prefixed then ksuid.to_ksuid
     when KSUID::Type then ksuid
     when Array then KSUID.from_bytes(ksuid)
     when String then cast_string(ksuid)
@@ -190,6 +198,43 @@ module KSUID
     Type.new(payload: payload, time: time)
   end
 
+  # Instantiates a new {KSUID::Prefixed}
+  #
+  # @api public
+  # @since 0.5.0
+  #
+  # @example Generate a new prefixed KSUID for the current second
+  #   KSUID.prefixed('evt_')
+  #
+  # @example Generate a new prefixed KSUID for a given timestamp
+  #   KSUID.prefixed('cus_', time: Time.parse('2022-08-16 10:36:00 UTC'))
+  #
+  # @param prefix [String] the prefix to apply to 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::Prefixed] the generated, prefixed KSUID
+  def self.prefixed(prefix, payload: nil, time: Time.now)
+    Prefixed.new(prefix, payload: payload, time: time)
+  end
+
+  # Generates a KSUID string
+  #
+  # @api public
+  # @since 0.5.0
+  #
+  # @example Generate a new KSUID string for the current second
+  #   KSUID.string
+  #
+  # @example Generate a new KSUID string for a given timestamp
+  #   KSUID.string(time: Time.parse('2017-11-05 15:00:04 UTC'))
+  #
+  # @param payload [String, Array<Integer>, nil] the payload for the KSUID string
+  # @param time [Time] the timestamp to use for the KSUID string
+  # @return [String] the generated string
+  def self.string(payload: nil, time: Time.now)
+    Type.new(payload: payload, time: time).to_s
+  end
+
   # Casts a string into a KSUID
   #
   # @api private
@@ -206,4 +251,4 @@ module KSUID
   private_class_method :cast_string
 end
 
-require 'ksuid/railtie' if defined?(Rails)
+require 'active_record/ksuid/railtie' if defined?(Rails)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ksuid
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Michael Herold
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-29 00:00:00.000000000 Z
+date: 2022-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -35,22 +35,27 @@ files:
 - CONTRIBUTING.md
 - LICENSE.md
 - README.md
+- UPGRADING.md
 - ksuid.gemspec
+- lib/active_record/ksuid.rb
+- lib/active_record/ksuid/binary_type.rb
+- lib/active_record/ksuid/prefixed_type.rb
+- lib/active_record/ksuid/railtie.rb
+- lib/active_record/ksuid/table_definition.rb
+- lib/active_record/ksuid/type.rb
 - 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/prefixed.rb
 - lib/ksuid/type.rb
 - lib/ksuid/utils.rb
 - lib/ksuid/version.rb
 homepage: https://github.com/michaelherold/ksuid-ruby
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/ksuid/railtie.rb

@@ -1,15 +0,0 @@
-# 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