activerecord-ksuid 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6038503571420197cb5b5c7f8cecbc1f6b358a07cc83186266f55df362115109
+  data.tar.gz: 29f103117d1a6cf608db290998edb04f86c493d48832483215af57ea83bf9817
+SHA512:
+  metadata.gz: ba30a46e24e3e4faee905adcab9d94166b9a432908c30ffab5094dc76c8deea4a7744b6bb17a6eca13626d3571332eb9882536af9b01ffab43a47d78d1baf3cf
+  data.tar.gz: 01f5fbd805569c80ab1c42c5d5b242173b3210f26305e82042e1286a28852b9205864f0f77a87ec4da64369d1b01f02b2a932e1661f07266f79394f583b37ee9

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+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
+
+### Added
+
+- Extracted the ActiveRecord behavior from [`ksuid-v0.5.0`](https://github.com/michaelherold/ksuid-ruby/tree/v0.5.0) into its own gem to slim down the gem and remove unnecessary functionality for people who only want the KSUID functionality.
+- Added the ability to disable the automatic generation of KSUIDs for fields by passing `auto_gen: false` to the module builder. This is helpful for foreign key fields, where an invalid value can raise errors, or for cases where you don't want to set the value until a later time.
+
+### Fixed
+
+- Binary KSUIDs on PostgreSQL now correctly deserialize without any extra configuration.

data/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+In the spirit of [free software], **everyone** is encouraged to help improve this project. Here are some ways *you* can contribute:
+
+* Use alpha, beta, and pre-release versions.
+* Report bugs.
+* Suggest new features.
+* Write or edit documentation.
+* Write specifications.
+* Write code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace).
+* Refactor code.
+* Fix [issues].
+* Review patches.
+
+[free software]: http://www.fsf.org/licensing/essays/free-sw.html
+[issues]: https://github.com/michaelherold/ksuid-ruby/issues
+
+## Submitting an Issue
+
+We use the [GitHub issue tracker][issues] to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted.
+
+When submitting a bug report, please include a [Gist](https://gist.github.com) that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system.
+
+Ideally, a bug report should include a pull request with failing specs.
+
+## Submitting a Pull Request
+
+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.
+5. Implement your feature or bug fix.
+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. 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
+[Submit a pull request]: https://help.github.com/articles/creating-a-pull-request/
+
+## Tools to Help You Succeed
+
+You will need a working copy of MySQL and PostgreSQL to run tests against them. At the root level of the gem, there is a `docker-compose.yml` file that sets up both of these services for you using either [Podman Compose](https://github.com/containers/podman-compose) or [Docker Compose](https://docs.docker.com/compose/). Both of these services will bind their default ports, so keep that in mind if you already have either database running on that port. Assuming you picked Podman, run:
+
+    podman-compose up
+
+in the `activerecord-ksuid` directory to start the services.
+
+After checking out the repository, run `bin/setup` to install dependencies. Then, run `appraisal rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Before committing code, run `appraisal rake` to check that the code conforms to the style guidelines of the project, that all of the tests are green (if you're writing a feature; if you're only submitting a failing test, then it does not have to pass!), and that the changes are sufficiently documented.
+
+[rubygems]: https://rubygems.org

data/LICENSE.md

@@ -0,0 +1,20 @@
+# The MIT License (MIT)
+
+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
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,251 @@
+# KSUID for ActiveRecord
+
+[![Build Status](https://github.com/michaelherold/ksuid-ruby/workflows/CI/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=main)][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
+
+activerecord-ksuid is a Ruby library that enables the use of [KSUIDs](https://github.com/segmentio/ksuid) within ActiveRecord. 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.
+
+---
+
+# What is a KSUID?
+
+KSUID is for K-Sortable Unique IDentifier. It's a way to generate globally unique IDs similar to RFC 4122 UUIDs, but contain a time component so they can be "roughly" sorted by time of creation. The remainder of the KSUID is randomly generated bytes.
+
+# Why use KSUIDs?
+
+Distributed systems often require unique IDs. There are numerous solutions out there for doing this, so why KSUID?
+
+## 1. Sortable by Timestamp
+
+Unlike the more common choice of UUIDv4, KSUIDs contain a timestamp component that allows them to be roughly sorted by generation time. This is obviously not a strong guarantee as it depends on wall clocks, but is still incredibly useful in practice.
+
+## 2. No Coordination Required
+
+[Snowflake IDs][1] and derivatives require coordination, which significantly increases the complexity of implementation and creates operations overhead. While RFC 4122 UUIDv1 does have a time component, there aren't enough bytes of randomness to provide strong protections against duplicate ID generation.
+
+KSUIDs use 128-bits of pseudorandom data, which provides a 64-times larger number space than the 122-bits in the well-accepted RFC 4122 UUIDv4 standard. The additional timestamp component drives down the extremely rare chance of duplication to the point of near physical infeasibility, even assuming extreme clock skew (> 24-hours) that would cause other severe anomalies.
+
+[1]: https://blog.twitter.com/2010/announcing-snowflake
+
+## 3. Lexicographically Sortable, Portable Representations
+
+The binary and string representations are lexicographically sortable, which allows them to be dropped into systems which do not natively support KSUIDs and retain their k-sortable characteristics.
+
+The string representation is that it is base 62-encoded, so that they can "fit" anywhere alphanumeric strings are accepted.
+
+# How do they work?
+
+KSUIDs are 20-bytes: a 32-bit unsigned integer UTC timestamp and a 128-bit randomly generated payload. The timestamp uses big-endian encoding, to allow lexicographic sorting. The timestamp epoch is adjusted to March 5th, 2014, providing over 100 years of useful life starting at UNIX epoch + 14e8. The payload uses a cryptographically strong pseudorandom number generator.
+
+The string representation is fixed at 27-characters encoded using a base 62 encoding that also sorts lexicographically.
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord-ksuid', require: 'active_record/ksuid/railtie'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ksuid
+
+## Usage
+
+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 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 unique_id: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 ActiveRecord::KSUID[:unique_id]
+end
+```
+
+#### Creating a new model
+
+To create a new model with a `ksuid` field that serializes as a KSUID string, 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 ActiveRecord::KSUID[: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 ActiveRecord::KSUID[:id]
+end
+```
+
+##### Without generating a default value
+
+In some cases, such as foreign keys, you do not want to generate a default value for the field and, instead, want to set the value manually. When this is true, you can disable the default generation behavior by passing `auto_gen: false` to the module builder.
+
+```ruby
+class Event < ApplicationRecord
+  include ActiveRecord::KSUID[:correlation_id, auto_gen: false]
+
+  belongs_to :correlation, class_name: Event
+end
+```
+
+You can also use the [Attributes API](http://api.rubyonrails.org/classes/ActiveRecord/Attributes/ClassMethods.html) directly:
+
+```ruby
+class Event < ApplicationRecord
+  attribute :correlation_id, :ksuid
+
+  belongs_to :correlation, class_name: Event
+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'
+require 'active_record/ksuid'
+
+# If you will be using the ksuid column type in a migration
+require 'active_record/ksuid/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 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 ActiveRecord::KSUID[: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 for ActiveRecord? 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][actions] the following Ruby versions:
+
+* Ruby 2.7
+* Ruby 3.0
+* Ruby 3.1
+* JRuby 9.3
+
+If something doesn't work on one of these versions, it's a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby versions, however support will only be provided for the versions listed above.
+
+If you would like this library to support another Ruby version or implementation, you may volunteer to be a maintainer. Being a maintainer entails making sure all tests run and pass on that implementation. When something breaks on your implementation, you will be responsible for providing patches in a timely fashion. If critical issues for a particular implementation exist at the time of a major release, support for that Ruby version may be dropped.
+
+## Versioning
+
+This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, you can (and should) specify a dependency on this gem using the [Pessimistic Version Constraint][pessimistic] with two digits of precision. For example:
+
+    spec.add_dependency "activerecord-ksuid", "~> 1.0"
+
+[pessimistic]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
+[semver]: http://semver.org/spec/v2.0.0.html
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/UPGRADING.md

@@ -0,0 +1,18 @@
+# Upgrading instructions for KSUID for ActiveRecord
+
+## v1.0.0
+
+This is the initial release of this library. If you are upgrading from KSUID for Ruby 0.x, follow the notice below.
+
+### 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 of KSUID for Ruby 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.

data/activerecord-ksuid.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require File.expand_path(File.join(__dir__, 'lib', 'active_record', 'ksuid', 'version'))
+
+Gem::Specification.new do |spec|
+  spec.name    = 'activerecord-ksuid'
+  spec.version = ActiveRecord::KSUID::VERSION
+  spec.authors = ['Michael Herold']
+  spec.email   = ['opensource@michaeljherold.com']
+
+  spec.summary     = 'ActiveRecord integration for KSUIDs using the ksuid gem'
+  spec.description = spec.summary
+  spec.homepage    = 'https://github.com/michaelherold/ksuid-ruby'
+  spec.license     = 'MIT'
+
+  spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md UPGRADING.md]
+  spec.files += %w[activerecord-ksuid.gemspec]
+  spec.files += Dir['lib/**/*.rb']
+  spec.require_paths = ['lib']
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.add_dependency 'activerecord', '>= 6.0'
+  spec.add_dependency 'ksuid', '~> 1.0'
+
+  spec.add_development_dependency 'bundler', '>= 1.15'
+end

data/lib/active_record/ksuid/binary_type.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+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 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 EventWithRegisteredBinaryType < 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)
+        value = ::KSUID::Utils.byte_string_from_hex(value[2..]) if value.start_with?('\x')
+        ::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, 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,28 @@
+# 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
+        require 'ksuid'
+
+        ActiveSupport.on_load :active_record do
+          require 'active_record/ksuid'
+        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/active_record/ksuid/table_definition.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module KSUID
+    # 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}
+      # @option options [String] :prefix the prefix expected in front of the KSUID
+      # @return [void]
+      def ksuid(*args, **options)
+        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
+      #
+      # @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

data/lib/active_record/ksuid/type.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+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 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 EventWithRegisteredType < 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, ActiveRecord::KSUID::Type)

data/lib/active_record/ksuid/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module KSUID
+    # The version of the activerecord-ksuid gem
+    #
+    # @return [String]
+    VERSION = '1.0.0'
+  end
+end

data/lib/active_record/ksuid.rb

@@ -0,0 +1,127 @@
+# 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 auto_gen [Boolean] whether to generate a KSUID upon initialization
+    # @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, auto_gen: true, 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, auto_gen, prefix)
+        else
+          define_attribute(field, mod, auto_gen, 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 auto_gen [Boolean] whether to generate a KSUID upon initialization
+    # @param binary [Boolean] whether to store the KSUID as a binary or a string
+    # @return [void]
+    def self.define_attribute(field, mod, auto_gen, binary)
+      type = 'ksuid'
+      type = 'ksuid_binary' if binary
+      default = 'default: -> { ::KSUID.new }' if auto_gen
+
+      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}                  #     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 auto_gen [Boolean] whether to generate a KSUID upon initialization
+    # @param prefix [String] the prefix to add to the KSUID
+    # @return [void]
+    def self.define_prefixed_attribute(field, mod, auto_gen, prefix)
+      default = "default: -> { ::KSUID.prefixed('#{prefix}') }" if auto_gen
+
+      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}                 #     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
+
+require 'active_record/ksuid/railtie' if defined?(Rails)

data/lib/activerecord-ksuid.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'active_record/ksuid'

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: activerecord-ksuid
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Michael Herold
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: ksuid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !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: ActiveRecord integration for KSUIDs using the ksuid gem
+email:
+- opensource@michaeljherold.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.md
+- README.md
+- UPGRADING.md
+- activerecord-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/active_record/ksuid/version.rb
+- lib/activerecord-ksuid.rb
+homepage: https://github.com/michaelherold/ksuid-ruby
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: ActiveRecord integration for KSUIDs using the ksuid gem
+test_files: []