ruby-ulid 0.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e00e5eba399c7d96e26ada6a0f0463fdb7fc08d7ec69c96588a5f85320a997be
+  data.tar.gz: e5f79b9a86ab038be2d0b39a787d8e70108998d3a024c699e401770ec6edade3
+SHA512:
+  metadata.gz: 0b4221414e2cdeeb67f6f6173c5ce25475f388e11df12c16864f576d76cac1fe3197dc5c2dd6ddef03d4fdfe6c079e0256a91c7b1728af73dd9d1b56c6ca7109
+  data.tar.gz: 369838ea1deac94dc44c71a37a606eb57a88f0266910f555a3ede1b7d85653be564499f7bf009cdd426a4a84a4be7e4d0f046ca4106bf25e8613cede927a47c5

data/lib/ulid/version.rb

@@ -0,0 +1,6 @@
+# coding: us-ascii
+# frozen_string_literal: true
+
+class ULID
+  VERSION = '0.0.6'
+end

data/lib/ulid.rb

@@ -0,0 +1,237 @@
+# coding: us-ascii
+# frozen_string_literal: true
+# Copyright (C) 2021 Kenichi Kamiya
+
+require 'securerandom'
+require 'singleton'
+require 'integer/base'
+require_relative 'ulid/version'
+
+# @see https://github.com/ulid/spec
+class ULID
+  include Comparable
+
+  class Error < StandardError; end
+  class OverflowError < Error; end
+  class ParserError < Error; end
+
+  # Crockford's Base32. Excluded I, L, O, U.
+  # @see https://www.crockford.com/base32.html
+  ENCODING_CHARS = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'.chars.map(&:freeze).freeze
+
+  TIME_PART_LENGTH = 10
+  RANDOMNESS_PART_LENGTH = 16
+  ENCODED_ID_LENGTH = TIME_PART_LENGTH + RANDOMNESS_PART_LENGTH
+  TIME_OCTETS_LENGTH = 6
+  RANDOMNESS_OCTETS_LENGTH = 10
+  OCTETS_LENGTH = TIME_OCTETS_LENGTH + RANDOMNESS_OCTETS_LENGTH
+  MAX_MILLISECONDS = 281474976710655
+  MAX_ENTROPY = 1208925819614629174706175
+
+  # Same as Time#inspect since Ruby 2.7, just to keep backward compatibility
+  # @see https://bugs.ruby-lang.org/issues/15958
+  TIME_FORMAT_IN_INSPECT = '%Y-%m-%d %H:%M:%S.%3N %Z'
+
+  class MonotonicGenerator
+    include Singleton
+
+    attr_accessor :latest_milliseconds, :latest_entropy
+
+    def initialize
+      reset
+    end
+
+    # @return [ULID]
+    def generate
+      milliseconds = ULID.current_milliseconds
+      reasonable_entropy = ULID.reasonable_entropy
+
+      @latest_milliseconds ||= milliseconds
+      @latest_entropy ||= reasonable_entropy
+      if @latest_milliseconds != milliseconds
+        @latest_milliseconds = milliseconds
+        @latest_entropy = reasonable_entropy
+      else
+        @latest_entropy += 1
+      end
+
+      ULID.new milliseconds: milliseconds, entropy: @latest_entropy
+    end
+
+    # @return [self]
+    def reset
+      @latest_milliseconds = nil
+      @latest_entropy = nil
+      self
+    end
+
+    # @return [void]
+    def freeze
+      raise TypeError, "cannot freeze #{self.class}"
+    end
+  end
+
+  MONOTONIC_GENERATOR = MonotonicGenerator.instance
+
+  private_constant :ENCODING_CHARS, :TIME_FORMAT_IN_INSPECT, :MonotonicGenerator
+
+  # @param [Integer, Time] moment
+  # @param [Integer] entropy
+  # @return [ULID]
+  def self.generate(moment: current_milliseconds, entropy: reasonable_entropy)
+    milliseconds = moment.kind_of?(Time) ? (moment.to_r * 1000).to_i : moment.to_int
+    new milliseconds: milliseconds, entropy: entropy
+  end
+
+  # @return [ULID]
+  def self.monotonic_generate
+    MONOTONIC_GENERATOR.generate
+  end
+
+  # @return [Integer]
+  def self.current_milliseconds
+    time_to_milliseconds(Time.now)
+  end
+
+  # @param [Time] time
+  # @return [Integer]
+  def self.time_to_milliseconds(time)
+    (time.to_r * 1000).to_i
+  end
+
+  # @return [Integer]
+  def self.reasonable_entropy
+    SecureRandom.random_number(MAX_ENTROPY)
+  end
+
+  # @param [String, #to_str] string
+  # @return [ULID]
+  def self.parse(string)
+    begin
+      string = string.to_str
+      unless string.size == ENCODED_ID_LENGTH
+        raise "parsable string must be #{ENCODED_ID_LENGTH} characters, but actually given #{string.size} characters"
+      end
+      timestamp = string.slice(0, TIME_PART_LENGTH)
+      randomness = string.slice(TIME_PART_LENGTH, RANDOMNESS_PART_LENGTH)
+      milliseconds = Integer::Base.parse(timestamp, ENCODING_CHARS)
+      entropy = Integer::Base.parse(randomness, ENCODING_CHARS)
+    rescue => err
+      raise ParserError, "parsing failure as #{err.inspect} for given #{string.inspect}"
+    end
+  
+    new milliseconds: milliseconds, entropy: entropy
+  end
+
+  # @param [String] string
+  # @return [Boolean]
+  def self.valid?(string)
+    parse(string)
+  rescue Exception
+    false
+  else
+    true
+  end
+
+  attr_reader :milliseconds, :entropy
+
+  def initialize(milliseconds:, entropy:)
+    milliseconds = milliseconds.to_int
+    entropy = entropy.to_int
+    raise OverflowError, "timestamp overflow: given #{milliseconds}, max: #{MAX_MILLISECONDS}" unless milliseconds <= MAX_MILLISECONDS
+    raise OverflowError, "entropy overflow: given #{entropy}, max: #{MAX_ENTROPY}" unless entropy <= MAX_ENTROPY
+    raise ArgumentError, 'milliseconds and entropy should not be negative' if milliseconds.negative? || entropy.negative?
+
+    @milliseconds = milliseconds
+    @entropy = entropy
+  end
+
+  # @return [String]
+  def to_str
+    @string ||= Integer::Base.string_for(to_i, ENCODING_CHARS).rjust(ENCODED_ID_LENGTH, '0').upcase.freeze
+  end
+  alias_method :to_s, :to_str
+
+  # @return [Integer]
+  def to_i
+    @integer ||= inverse_of_digits(octets)
+  end
+  alias_method :hash, :to_i
+
+  # @return [Integer, nil]
+  def <=>(other)
+    other.kind_of?(self.class) ? (to_i <=> other.to_i) : nil
+  end
+
+  # @return [String]
+  def inspect
+    @inspect ||= "ULID(#{to_time.strftime(TIME_FORMAT_IN_INSPECT)}: #{to_str})".freeze
+  end
+
+  # @return [Boolean]
+  def eql?(other)
+    other.equal?(self) || (other.kind_of?(self.class) && other.to_i == to_i)
+  end
+  alias_method :==, :eql?
+
+  # @return [Time]
+  def to_time
+    @time ||= Time.at(0, @milliseconds, :millisecond).utc
+  end
+
+  # @return [Array<Integer>]
+  def octets
+    @octets ||= (time_octets + randomness_octets).freeze
+  end
+
+  # @return [Array<Integer>]
+  def time_octets
+    @time_octets ||= octets_from_integer(@milliseconds, length: TIME_OCTETS_LENGTH).freeze
+  end
+
+  # @return [Array<Integer>]
+  def randomness_octets
+    @randomness_octets ||= octets_from_integer(@entropy, length: RANDOMNESS_OCTETS_LENGTH).freeze
+  end
+
+  # @return [ULID]
+  def next
+    @next ||= self.class.new(milliseconds: @milliseconds, entropy: @entropy + 1)
+  end
+  alias_method :succ, :next
+
+  # @return [self]
+  def freeze
+    # Evaluate all caching
+    inspect
+    octets
+    succ
+    to_i
+    super
+  end
+
+  private
+
+  # @param [Integer] integer
+  # @param [Integer] length
+  # @return [Array<Integer>]
+  def octets_from_integer(integer, length:)
+    digits = integer.digits(256)
+    (length - digits.size).times do
+      digits.push 0
+    end
+    digits.reverse!
+  end
+
+  # @see The logics taken from https://bugs.ruby-lang.org/issues/14401, thanks!
+  # @param [Array<Integer>] reversed_digits
+  # @return [Integer]
+  def inverse_of_digits(reversed_digits)
+    base = 256
+    num = 0
+    reversed_digits.each do |digit|
+      num = (num * base) + digit
+    end
+    num
+  end
+end

data/sig/ulid.rbs

@@ -0,0 +1,74 @@
+# Classes
+class ULID
+  VERSION: String
+  ENCODING_CHARS: Array[String]
+  TIME_PART_LENGTH: Integer
+  RANDOMNESS_PART_LENGTH: Integer
+  ENCODED_ID_LENGTH: Integer
+  TIME_OCTETS_LENGTH: Integer
+  RANDOMNESS_OCTETS_LENGTH: Integer
+  OCTETS_LENGTH: Integer
+  MAX_MILLISECONDS: Integer
+  MAX_ENTROPY: Integer
+  TIME_FORMAT_IN_INSPECT: String
+  MONOTONIC_GENERATOR: MonotonicGenerator
+  include Comparable
+  @string: String
+  @integer: Integer
+  @octets: Array[Integer]
+  @time_octets: Array[Integer]
+  @randomness_octets: Array[Integer]
+  @inspect: String
+  @time: Time
+  @next: ULID
+
+  def self.generate: (?moment: Time | Integer, ?entropy: Integer) -> ULID
+  def self.monotonic_generate: -> ULID
+  def self.current_milliseconds: -> Integer
+  def self.time_to_milliseconds: (Time time) -> Integer
+  def self.reasonable_entropy: -> Integer
+  def self.parse: (String string) -> ULID
+  def self.valid?: (untyped string) -> bool
+  attr_reader milliseconds: Integer
+  attr_reader entropy: Integer
+  def initialize: (milliseconds: Integer, entropy: Integer) -> void
+  def to_str: -> String
+  def to_s: -> String
+  def to_i: -> Integer
+  def hash: -> Integer
+  def <=>: (untyped other) -> Integer?
+  def inspect: -> String
+  def eql?: (untyped other) -> bool
+  def ==: (untyped other) -> bool
+  def to_time: -> Time
+  def octets: -> Array[Integer]
+  def time_octets: -> Array[Integer]
+  def randomness_octets: -> Array[Integer]
+  def next: -> ULID
+  def succ: -> ULID
+  def freeze: -> self
+
+  private
+  def octets_from_integer: (Integer integer, length: Integer) -> Array[Integer]
+  def inverse_of_digits: (Array[Integer] reversed_digits) -> Integer
+
+  class Error < StandardError
+  end
+
+  class OverflowError < Error
+  end
+
+  class ParserError < Error
+  end
+
+  class MonotonicGenerator
+    include Singleton
+
+    attr_accessor latest_milliseconds: Integer?
+    attr_accessor latest_entropy: Integer?
+    def initialize: -> void
+    def generate: -> ULID
+    def reset: -> void
+    def freeze: -> void
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: ruby-ulid
+version: !ruby/object:Gem::Version
+  version: 0.0.6
+platform: ruby
+authors:
+- Kenichi Kamiya
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-04-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: integer-base
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+- !ruby/object:Gem::Dependency
+  name: test-unit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.8.4
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.26
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.26
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: |2
+      ULID(Universally Unique Lexicographically Sortable Identifier) is defined on https://github.com/ulid/spec.
+      It has useful specs for actual applications.
+      This gem aims to provide the generator, monotonic generator, parser and handy manipulation methods for the ID.
+      Also having rbs signature files.
+email:
+- kachick1+ruby@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/ulid.rb
+- lib/ulid/version.rb
+- sig/ulid.rbs
+homepage: https://github.com/kachick/ruby-ulid
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://kachick.github.io/ruby-ulid/
+  homepage_uri: https://github.com/kachick/ruby-ulid
+  source_code_uri: https://github.com/kachick/ruby-ulid
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: A handy ULID library
+test_files: []