ksuid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d7e3d2e87bfbd69ce702f4dcc0d7067394f39fe7
+  data.tar.gz: 8159913d3848e49c9e41143db7e1fc4fb115deee
+SHA512:
+  metadata.gz: a298ed92c64c0398c14853de8d246fc0e78b29aca724dde716fe8c67640e37621db09f62f4a76da86de0576d64a2be7d8265f1cdb692056244a0838efe9a1da9
+  data.tar.gz: 5282c1bfe4bc4a09761510fd4a330c7e8429626e67c245e62af3d41b7b391be2470c598fa91aaf6a5ebe7df51a0aec8a0e3a7f46ac01afc5afbbf733e51e1dd8

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# 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).
+
+## [0.1.0] - 2017-11-05
+
+### Added
+
+- Basic `KSUID.new` interface.
+- Parsing of bytes through `KSUID.from_bytes`.
+- Parsing of strings through `KSUID.from_base62`.
+
+[0.1.0]: https://github.com/michaelherold/interactor-contracts/tree/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# 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 `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake`. If your specs or any of the linters fail, return to step 5.
+7. Open `coverage/index.html`. If your changes are not completely covered by your tests, return to step 3.
+8. Add documentation for your feature or bug fix.
+9. Run `bundle exec inch`. If your changes are below a B in documentation, go back to step 8.
+10. Commit and push your changes.
+11. [Submit a pull request].
+
+[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
+
+After checking out the repository, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+When writing code, you can use the helper application [Guard][guard] to automatically run tests and coverage tools whenever you modify and save a file. This helps to eliminate the tedium of running tests manually and reduces the chance that you will accidentally forget to run the tests. To use Guard, run `bundle exec guard`.
+
+Before committing code, run `bundle exec 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.
+
+[guard]: http://guardgem.org
+[rubygems]: https://rubygems.org

data/LICENSE.md

@@ -0,0 +1,20 @@
+# The MIT License (MIT)
+
+Copyright © 2017 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,124 @@
+# KSUID for Ruby
+
+[![Build Status](https://travis-ci.org/michaelherold/ksuid-ruby.svg)][travis]
+[![Test Coverage](https://api.codeclimate.com/v1/badges/94b2a2d4082bff21c10f/test_coverage)][test-coverage]
+[![Maintainability](https://api.codeclimate.com/v1/badges/94b2a2d4082bff21c10f/maintainability)][maintainability]
+[![Inline docs](http://inch-ci.org/github/michaelherold/ksuid-ruby.svg?branch=master)][inch]
+
+[inch]: http://inch-ci.org/github/michaelherold/ksuid-ruby
+[maintainability]: https://codeclimate.com/github/michaelherold/ksuid-ruby/maintainability
+[test-coverage]: https://codeclimate.com/github/michaelherold/ksuid-ruby/test_coverage
+[travis]: https://travis-ci.org/michaelherold/ksuid-ruby
+
+ksuid is a Ruby library that can generate and parse [KSUIDs](https://github.com/segmentio/ksuid). The original readme for the Go version of KSUID does a great job of explaining what they are and how they should be used, so it is excerpted here.
+
+---
+
+# 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 'ksuid'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ksuid
+
+## Usage
+
+To generate a KSUID for the present time, use:
+
+```ruby
+ksuid = KSUID.new
+```
+
+If you need to parse a KSUID from a string that you received, use the conversion method:
+
+```ruby
+ksuid = KSUID.from_base62(base62_string)
+```
+
+If you need to interpret a series of bytes that you received, use the conversion method:
+
+```ruby
+ksuid = KSUID.from_bytes(bytes)
+```
+
+The `KSUID.from_bytes` method can take either a byte string or a byte array.
+
+If you need to generate a KSUID for a specific timestamp, use:
+
+```ruby
+ksuid = KSUID.new(time: time)  # where time is a Time-like object
+```
+
+## Contributing
+
+So you’re interested in contributing to KSUID? Check out our [contributing guidelines](CONTRIBUTING.md) for more information on how to do that.
+
+## Supported Ruby Versions
+
+This library aims to support and is [tested against][travis] the following Ruby versions:
+
+* Ruby 2.3
+* Ruby 2.4
+* JRuby 9.1
+
+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 "ksuid", "~> 0.1"
+
+[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/ksuid.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require File.expand_path(File.join('..', 'lib', 'ksuid', 'version'), __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name    = 'ksuid'
+  spec.version = KSUID::VERSION
+  spec.authors = ['Michael Herold']
+  spec.email   = ['michael@michaeljherold.com']
+
+  spec.summary     = 'Ruby implementation of the K-Sortable Unique IDentifier'
+  spec.description = spec.summary
+  spec.homepage    = 'https://github.com/michaelherold/ksuid'
+  spec.license     = 'MIT'
+
+  spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md]
+  spec.files += %w[ksuid.gemspec]
+  spec.files += Dir['lib/**/*.rb']
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+end

data/lib/ksuid.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative 'ksuid/type'
+require_relative 'ksuid/version'
+
+# The K-Sortable Unique IDentifier (KSUID)
+#
+# Distributed systems require unique identifiers to track events throughout
+# their subsystems. Many algorithms for generating unique identifiers, like the
+# {https://blog.twitter.com/2010/announcing-snowflake Snowflake ID} system,
+# require coordination with a central authority. This is an unacceptable
+# constraint in the face of systems that run on client devices, yet we still
+# need to be able to generate event identifiers and roughly sort them for
+# processing.
+#
+# The KSUID optimizes this problem into a roughly sortable identifier with
+# a high possibility space to reduce the chance of collision. KSUID uses
+# a 32-bit timestamp with second-level precision combined with 128 bytes of
+# random data for the "payload". The timestamp is based on the Unix epoch, but
+# with its base shifted forward from 1970-01-01 00:00:00 UTC to 2014-05-13
+# 16:532:20 UTC. This is to extend the useful life of the ID format to over
+# 100 years.
+#
+# Because KSUID timestamps use seconds as their unit of precision, they are
+# unsuitable to tasks that require extreme levels of precision. If you need
+# microsecond-level precision, a format like {https://github.com/alizain/ulid
+# ULID} may be more suitable for your use case.
+#
+# KSUIDs are "roughly sorted". Practically, this means that for any given event
+# stream, there may be some events that are ordered in a slightly different way
+# than they actually happened. There are two reasons for this. Firstly, the
+# format is precise to the second. This means that two events that are
+# generated in the same second will be sorted together, but the KSUID with the
+# smaller payload value will be sorted first. Secondly, the format is generated
+# on the client device using its clock, so KSUID is susceptible to clock shift
+# as well. The result of sorting the identifiers is that they will be sorted
+# into groups of identifiers that happened in the same second according to
+# their generating device.
+#
+# @example Generate a new KSUID
+#   KSUID.new
+#
+# @example Parse a KSUID string that you have received
+#   KSUID.from_base62('aWgEPTl1tmebfsQzFP4bxwgy80V')
+#
+# @example Parse a KSUID byte string that you have received
+#   KSUID.from_bytes(
+#     "\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF"
+#   )
+#
+# @example Parse a KSUID byte array that you have received
+#   KSUID.from_bytes(
+#     [255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+#      255, 255, 255, 255]
+#   )
+module KSUID
+  # The shift in the Unix epoch time between the standard and the KSUID base
+  #
+  # @return [Integer] the number of seconds by which we shift the epoch
+  EPOCH_TIME = 1_400_000_000
+
+  # 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
+
+  # The number of characters in a base 62-encoded KSUID
+  #
+  # @return [Integer]
+  STRING_LENGTH = 27
+
+  # The maximum KSUID as a base 62-encoded string.
+  #
+  # @return [String]
+  MAX_STRING_ENCODED = 'aWgEPTl1tmebfsQzFP4bxwgy80V'
+
+  # Converts a base 62-encoded string into a KSUID
+  #
+  # @api public
+  #
+  # @example Parse a KSUID string into an object
+  #   KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+  #
+  # @param string [String] the base 62-encoded KSUID to convert into an object
+  # @return [KSUID::Type] the KSUID generated from the string
+  def self.from_base62(string)
+    string = string.rjust(STRING_LENGTH, Base62::CHARSET[0]) if string.length < STRING_LENGTH
+    int = Base62.decode(string)
+    bytes = Utils.int_to_bytes(int, 160)
+
+    from_bytes(bytes)
+  end
+
+  # Converts a byte string or byte array into a KSUID
+  #
+  # @api public
+  #
+  # @example Parse a KSUID byte string into an object
+  #   KSUID.from_bytes("\x06\x83\xF7\x89\x04\x9C\xC2\x15\xC0\x99\xD4+xM\xBE\x994\e\xD7\x9C")
+  #
+  # @param bytes [String|Array<Integer>] the byte string or array to convert into an object
+  # @return [KSUID::Type] the KSUID generated from the bytes
+  def self.from_bytes(bytes)
+    bytes = bytes.bytes if bytes.is_a?(String)
+
+    timestamp = Utils.int_from_bytes(bytes.first(BYTES[:timestamp]))
+    payload = Utils.byte_string_from_array(bytes.last(BYTES[:payload]))
+
+    KSUID::Type.new(payload: payload, time: Time.at(timestamp + EPOCH_TIME))
+  end
+
+  # Generates the maximum KSUID as a KSUID type
+  #
+  # @api semipublic
+  #
+  # @example Generate the maximum KSUID
+  #   KSUID.max
+  #
+  # @return [KSUID::Type] the maximum KSUID in both timestamp and payload
+  def self.max
+    from_bytes([255] * BYTES[:total])
+  end
+
+  # Instantiates a new KSUID
+  #
+  # @api public
+  #
+  # @example Generate a new KSUID for the current second
+  #   KSUID.new
+  #
+  # @example Generate a new KSUID for a given timestamp
+  #   KSUID.new(time: Time.parse('2017-11-05 15:00:04 UTC'))
+  #
+  # @param payload [String|Array<Integer>|nil] the payload for the KSUID
+  # @param time [Time] the timestamp to use for the KSUID
+  # @return [KSUID::Type] the generated KSUID
+  def self.new(payload: nil, time: Time.now)
+    Type.new(payload: payload, time: time)
+  end
+end

data/lib/ksuid/base62.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative 'utils'
+
+module KSUID
+  # Converts between numbers and an alphanumeric encoding
+  #
+  # We store and report KSUIDs as base 62-encoded numbers to make them
+  # lexicographically sortable and compact to transmit. The base 62 alphabet
+  # consists of the Arabic numerals, followed by the English capital letters
+  # and the English lowercase letters.
+  module Base62
+    # The character set used to encode numbers into base 62
+    #
+    # @api private
+    CHARSET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+
+    # The base (62) that this module encodes numbers into
+    #
+    # @api private
+    BASE = CHARSET.size
+
+    # Decodes a base 62-encoded string into an integer
+    #
+    # @api public
+    #
+    # @example Decode a string into a number
+    #   KSUID::Base62.decode('0000000000000000000001LY7VK')
+    #   #=> 1234567890
+    #
+    # @param ksuid [String] the base 62-encoded number
+    # @return [Integer] the decoded number as an integer
+    def self.decode(ksuid)
+      result = 0
+
+      ksuid.split('').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))
+      end
+
+      result
+    end
+
+    # Encodes a number (integer) as a base 62 string
+    #
+    # @api public
+    #
+    # @example Encode a number as a base 62 string
+    #   KSUID::Base62.encode(1_234_567_890)
+    #   #=> "0000000000000000000001LY7VK"
+    #
+    # @param number [Integer] the number to encode into base 62
+    # @return [String] the base 62-encoded number
+    def self.encode(number)
+      chars = encode_without_padding(number)
+
+      chars << padding if chars.empty?
+      chars.reverse.join('').rjust(STRING_LENGTH, padding)
+    end
+
+    # Encodes a byte string or byte array into base 62
+    #
+    # @api semipublic
+    #
+    # @example Encode a maximal KSUID as a string
+    #   KSUID::Base62.encode_bytes(
+    #     [255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+    #      255, 255, 255, 255, 255, 255, 255, 255, 255, 255]
+    #   )
+    #
+    # @param bytes [String|Array<Integer>] the bytes to encode
+    # @return [String] the encoded bytes as a base 62 string
+    def self.encode_bytes(bytes)
+      encode(Utils.int_from_bytes(bytes))
+    end
+
+    # Encodes a number as a string while disregarding the expected width
+    #
+    # @api private
+    #
+    # @param number [Integer] the number to encode
+    # @return [String] the resulting encoded string
+    def self.encode_without_padding(number)
+      [].tap do |chars|
+        loop do
+          break unless number.positive?
+
+          number, remainder = number.divmod(BASE)
+          chars << CHARSET[remainder]
+        end
+      end
+    end
+    private_class_method :encode_without_padding
+
+    # The character used as padding in strings that are less than 27 characters
+    #
+    # @api private
+    # @return [String]
+    def self.padding
+      CHARSET[0]
+    end
+    private_class_method :padding
+  end
+end

data/lib/ksuid/type.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'base62'
+require_relative 'utils'
+
+module KSUID
+  # Encapsulates the data type for a KSUID
+  #
+  # This is the main class that you will interact with in this gem. You will
+  # not typically generate these directly, but this is the resulting data type
+  # for all of the main generation methods on the {KSUID} module.
+  #
+  # A KSUID type has two pieces of information contained within its
+  # byte-encoded data:
+  #
+  # 1. The timestamp associated with the KSUID (stored as the first 4 bytes)
+  # 2. The payload, or random data, for the KSUID (stored as the last 16 bytes)
+  #
+  # The type gives you access to several handles into these data.
+  class Type
+    include Comparable
+
+    # Instantiates a new KSUID type
+    #
+    # @api semipublic
+    #
+    # @example Generate a new KSUID for the current second
+    #   KSUID::Type.new
+    #
+    # @example Generate a new KSUID for a given timestamp
+    #   KSUID::Type.new(time: Time.parse('2017-11-05 15:00:04 UTC'))
+    #
+    # @param payload [String|Array<Integer>|nil] the payload for the KSUID
+    # @param time [Time] the timestamp to use for the KSUID
+    # @return [KSUID::Type] the generated KSUID
+    def initialize(payload: nil, time: Time.now)
+      payload ||= SecureRandom.random_bytes(BYTES[:payload])
+      byte_encoding = Utils.int_to_bytes(time.to_i - EPOCH_TIME)
+
+      @uid = byte_encoding.bytes + payload.bytes
+    end
+
+    # Implements the Comparable interface for sorting KSUIDs
+    #
+    # @api private
+    #
+    # @param other [KSUID::Type] the other object to compare against
+    # @return [Integer] -1 for less than other, 0 for equal to, 1 for greater than other
+    def <=>(other)
+      to_time <=> other.to_time
+    end
+
+    # Checks whether this KSUID is equal to another
+    #
+    # @api semipublic
+    #
+    # @example Checks whether two KSUIDs are equal
+    #   KSUID.new == KSUID.new
+    #
+    # @param other [KSUID::Type] the other KSUID to check against
+    # @return [Boolean]
+    def ==(other)
+      other.to_s == to_s
+    end
+
+    # The payload for the KSUID, as a hex-encoded string
+    #
+    # This is generally useful for comparing against the Go tool
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+    #
+    #   ksuid.payload #=> "049CC215C099D42B784DBE99341BD79C"
+    #
+    # @return [String] a hex-encoded string
+    def payload
+      Utils.bytes_to_hex_string(uid.last(BYTES[:payload]))
+    end
+
+    # The KSUID as a hex-encoded string
+    #
+    # This is generally useful for comparing against the Go tool.
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+    #
+    #   ksuid.raw #=> "0683F789049CC215C099D42B784DBE99341BD79C"
+    #
+    # @return [String] a hex-encoded string
+    def raw
+      Utils.bytes_to_hex_string(uid)
+    end
+
+    # The KSUID as a byte string
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+    #
+    #   ksuid.to_bytes
+    #
+    # @return [String] a byte string
+    def to_bytes
+      Utils.byte_string_from_array(uid)
+    end
+
+    # The KSUID as a Unix timestamp
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+    #
+    #   ksuid.to_i #=> 109311881
+    #
+    # @return [Integer] the Unix timestamp for the event (without the epoch shift)
+    def to_i
+      unix_time = Utils.int_from_bytes(uid.first(BYTES[:timestamp]))
+
+      unix_time
+    end
+
+    # The KSUID as a base 62-encoded string
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+    #
+    #   ksuid.to_s #=> "0vdbMgWkU6slGpLVCqEFwkkZvuW"
+    #
+    # @return [String] the base 62-encoded string for the KSUID
+    def to_s
+      Base62.encode_bytes(uid)
+    end
+
+    # The time the KSUID was generated
+    #
+    # @api public
+    #
+    # @example
+    #   ksuid = KSUID.from_base62('0vdbMgWkU6slGpLVCqEFwkkZvuW')
+    #
+    #   ksuid.to_time.utc.to_s #=> "2017-10-29 21:18:01 UTC"
+    #
+    # @return [String] the base 62-encoded string for the KSUID
+    def to_time
+      Time.at(to_i + EPOCH_TIME)
+    end
+
+    private
+
+    # The KSUID as a byte array
+    #
+    # @api private
+    #
+    # @return [Array<Integer>]
+    attr_reader :uid
+  end
+end

data/lib/ksuid/utils.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module KSUID
+  # Utility functions for converting between different encodings
+  #
+  # @api private
+  module Utils
+    # Converts a byte string into a byte array
+    #
+    # @param bytes [String] a byte string
+    # @return [Array<Integer>] an array of bytes from the byte string
+    def self.byte_string_from_array(bytes)
+      bytes.pack('C*')
+    end
+
+    # Converts a byte string or byte array into a hex-encoded string
+    #
+    # @param bytes [String|Array<Integer>] the byte string or array
+    # @return [String] the byte string as a hex-encoded string
+    def self.bytes_to_hex_string(bytes)
+      bytes = bytes.bytes if bytes.is_a?(String)
+
+      byte_string_from_array(bytes)
+        .unpack('H*')
+        .first
+        .upcase
+    end
+
+    # Converts a byte string or byte array into an integer
+    #
+    # @param bytes [String|Array<Integer>] the byte string or array
+    # @return [Integer] the resulting integer
+    def self.int_from_bytes(bytes)
+      bytes = bytes.bytes if bytes.is_a?(String)
+
+      bytes
+        .map { |byte| byte.to_s(2).rjust(8, '0') }
+        .join('')
+        .to_i(2)
+    end
+
+    # Converts an integer into a network-ordered (big endian) byte string
+    #
+    # @param int [Integer] the integer to convert
+    # @param bits [Integer] the expected number of bits for the result
+    # @return [String] the byte string
+    def self.int_to_bytes(int, bits = 32)
+      int
+        .to_s(2)
+        .rjust(bits, '0')
+        .split('')
+        .each_slice(8)
+        .map { |digits| digits.join.to_i(2) }
+        .pack("C#{bits / 8}")
+    end
+  end
+end

data/lib/ksuid/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module KSUID
+  # The version of the KSUID gem
+  #
+  # @return [String]
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: ksuid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Herold
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-11-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: Ruby implementation of the K-Sortable Unique IDentifier
+email:
+- michael@michaeljherold.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.md
+- README.md
+- ksuid.gemspec
+- lib/ksuid.rb
+- lib/ksuid/base62.rb
+- lib/ksuid/type.rb
+- lib/ksuid/utils.rb
+- lib/ksuid/version.rb
+homepage: https://github.com/michaelherold/ksuid
+licenses:
+- MIT
+metadata: {}
+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: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: Ruby implementation of the K-Sortable Unique IDentifier
+test_files: []
+has_rdoc: