ksuid 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b5bd73fb4864bb0df8cf57c1214622325afa077e031baffb2a1e73b2820f2c
-  data.tar.gz: 55245cb9fba9e57c9bf115f189fb954f2e1b08604e89ba8b5c9aeea73967e5ba
+  metadata.gz: c97a36378134ab6cdd674866a6744e5b84ff5976db6575d5364cc844cc9dbf4f
+  data.tar.gz: c5ebfa42d22044e518a63f9508924517a5b7ec83a9e3059c64ecb8075ee88e07
 SHA512:
-  metadata.gz: af5cc8ed5f9d81616fd61e6f03690c841489e9f2c2d28d892137c1eb410ec88e61540cd3dd10d5ac0d0439f9b9ecd9afdc00cceae61276cca521d5436c159e29
-  data.tar.gz: 13479dc7d24cf9422c6bc3ca705c6c777abf121f5ade7a9f9c8124c7b9f8034844d8707b2f8265c18178b9b16b50be28a3c1894888d97fe7f42aa1e981d11a97
+  metadata.gz: 6743031c8702c60e3be6d58f2bde58b1290abc1943afb110adf3a9a2066017d24a453a826373312539175629b2ed9a612ed257abdad22e0cef74a88e045a12e5
+  data.tar.gz: c2c504f17a31fe7d0c25475b606045424868aca2aa0015e78ff41da89828a7e1eb5b88bcf88a8e0da34a81945d5c68b3cbfb1d4acead1d9227c423cc89ece0ae

data/CHANGELOG.md

@@ -4,6 +4,28 @@ 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).
 
+## [1.0.0](https://github.com/michaelherold/ksuid/compare/v0.5.0...v1.0.0) - 2023-02-25
+
+### Removed
+
+- Extracted the ActiveRecord functionality into its own gem, `activerecord-ksuid`. It is API-compatible with v0.5.0 so to restore functionality, you should only need to add the new gem to your application. See [the upgrading notice](./UPGRADING.md) for more information.
+
+## [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/CONTRIBUTING.md

@@ -28,9 +28,9 @@ 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 `appraisal rake spec`. If your specs pass, return to step 3.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
 5. Implement your feature or bug fix.
-6. Run `appraisal rake`. If your specs or any of the linters fail, return to step 5.
+6. Run `bundle exec 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. Commit and push your changes.

data/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 
-Copyright © 2017 Michael Herold
+Copyright © 2017-2022 Michael Herold
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.md

@@ -100,114 +100,43 @@ KSUID.configure do |config|
 end
 ```
 
-### ActiveRecord
+### Prefixed KSUIDs
 
-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:
+If you use KSUIDs in multiple contexts, you can prefix them to make them easily identifiable.
 
 ```ruby
-class CreateEvents < ActiveRecord::Migration[5.2]
-  create_table :events, id: false do |table|
-    table.ksuid :id, primary_key: true
-  end
-end
+ksuid = KSUID.prefixed('evt_')
 ```
 
-You will need to mix in the module into your model as well:
+Just like a normal KSUID, you can use a specific timestamp:
 
-```ruby
-class Event < ApplicationRecord
-  include KSUID::ActiveRecord[:id]
-end
+``` ruby
+ksuid = KSUID.prefixed('evt_', time: time)  # where time is a Time-like object
 ```
 
-#### 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:
+You can also parse a prefixed KSUID from a string that you received:
 
 ```ruby
-require 'ksuid/activerecord'
-
-# If you will be using the ksuid column type in a migration
-require 'ksuid/activerecord/table_definition'
+ksuid = KSUID::Prefixed.from_base62(base62_string, prefix: 'evt_')
 ```
 
-Once you have required the file(s) that you need, everything else will work as it does above.
+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.
 
-#### Binary vs. String KSUIDs
+### Integrations
 
-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.
+KSUID for Ruby can integrate with other systems through adapter gems. Below is a sample of these adapter gems.
 
-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
-```
+#### ActiveRecord
 
-#### Use the KSUID as your `created_at` timestamp
+If you want to include KSUID columns in your ActiveRecord models, install the `activerecord-ksuid` gem. If you are using it within a Rails app, run the following:
 
-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:
+    bundle add activerecord-ksuid --require active_record/ksuid/railtie
+    
+If you are using it outside of Rails, add this to your Gemfile:
 
-```ruby
-class Event < ApplicationRecord
-  include KSUID::ActiveRecord[:my_field_name, created_at: true]
-end
-```
+    gem 'activerecord-ksuid', require: ['ksuid', 'active_record/ksuid', 'active_record/ksuid/table_definition']
 
-This allows you to be efficient in your database design if that is a constraint you need to satisfy.
+See [the readme for the integration](https://github.com/michaelherold/ksuid-ruby/blob/main/activerecord-ksuid/README.md) for more information.
 
 ## Contributing
 
@@ -217,10 +146,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,26 @@
+# Upgrading instructions for KSUID for Ruby
+
+## v1.0.0
+
+### Extracted `ActiveRecord::KSUID` into its own gem
+
+That KSUID for Ruby included ActiveRecord support directly in its gem has always been a regret of mine. It adds ActiveRecord and Rails concerns to a gem that you can use in any context. It makes running the test suite more complicated for no real gain. And it makes it kludgy to add support for more systems, like Sequel, since you have conflicting concerns in the same gem.
+
+To remove this problem, v1.0.0 extracts the ActiveRecord behavior into its own gem, `activerecord-ksuid`. This version is a straight extraction with an improved test suite so it _should_ mean that the only change you have to make when upgrading from v0.5.0 is to do the following in your Gemfile:
+
+```diff
+- gem 'ksuid'
++ gem 'activerecord-ksuid'
+```
+
+If you are still on a version prior to v0.5.0, upgrade to that version first, solve the deprecation notice below, ensure your app still works, and then upgrade to v1.0.0.
+
+## 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/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 = '1.0.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
@@ -205,5 +250,3 @@ module KSUID
   end
   private_class_method :cast_string
 end
-
-require '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: 1.0.0
 platform: ruby
 authors:
 - Michael Herold
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-29 00:00:00.000000000 Z
+date: 2023-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -35,22 +35,20 @@ files:
 - CONTRIBUTING.md
 - LICENSE.md
 - README.md
+- UPGRADING.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/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:
@@ -66,7 +64,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Ruby implementation of the K-Sortable Unique IDentifier

data/lib/ksuid/activerecord/binary_type.rb

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

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

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

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