typeid 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 549897e90b13cf09d467676b1d2a7aec3e46b2cd7e79fa4c06aaa9a05e033575
-  data.tar.gz: b2d608830c8969876e289ef4324c5b6acfbe93e07deb0d199cb7bc086f737bfc
+  metadata.gz: 283674a725da5d9ffa40b5bbc5f0c2a55020eea487f58d6fa6662ac903e51fa7
+  data.tar.gz: 673a27c6e7cd8c29fb0484564b7ae2eda168d49c386dcfc381fe22d4cdb3e3b5
 SHA512:
-  metadata.gz: f790c54923e70c79e22d2cf95f8ba26e76c8cc45309445c730a017a2e1a0f6c8724d46e067ff7d4219e5eb776f9c0b5227da50c7306e783572b44de510327332
-  data.tar.gz: fdc1976ed3ddd02f4bb0031335da92a251642cc907cda69ea00dca3e4936c8c7e1dff914366bbb9f3d97ea324cc6b6eaf4ba3c2afde154e63703c5b87d92f2a5
+  metadata.gz: a447c767d7dd80fe7b2c555941677fe163508a6ee0c090e20f03475d97399b0418e1184ab159999eebcd5f6e2d055f806d70274166cbae7ca3859f7a0242daf4
+  data.tar.gz: '08fb41867b5af9809cf36635383947972ca7f16c07c7c6df265dff27180aebee3db26dd6ae423775dd45acc49f0e7f374025fec6feed3009780d1944dce32927'

data/lib/typeid/uuid/base32.rb

@@ -1,8 +1,19 @@
 class TypeID < String
   class UUID < String
+
+    # Provides utilities for encoding and decoding UUIDs to and from base32.
+    # Based on https://github.com/jetpack-io/typeid-go/blob/341e2b135e0609db272e6400f2f551487725824a/base32/base32.go.
     module Base32
+      DECODED_BYTE_ARRAY_LENGTH = 16
+      ENCODED_STRING_LENGTH = 26
+
+      class Error < StandardError; end
+
+      # Crockford's Base32 alphabet.
       ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz".freeze
 
+      # Byte to index table for O(1) lookups when unmarshaling.
+      # We use 0xFF as sentinel value for invalid indexes.
       DEC = [
         0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
         0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
@@ -32,53 +43,62 @@ class TypeID < String
         0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
       ].freeze
 
-      # @param bytes [Array<Integer>]
+      # Encodes a size 16 byte +Array+ into a size 26 +String+.
+      # Based on https://github.com/jetpack-io/typeid-go/blob/341e2b135e0609db272e6400f2f551487725824a/base32/base32.go#L14.
+      #
+      # @param bytes [Array<Integer>] size 16 byte array
       # @return [String]
       def self.encode(bytes)
-        encoded = Array.new(26, 0)
+        raise Error, "invalid bytes size" unless bytes.size == DECODED_BYTE_ARRAY_LENGTH
+
+        encoded = Array.new(ENCODED_STRING_LENGTH, 0)
 
         # 10 byte timestamp
-        encoded[0] = ALPHABET[(bytes[0]&224)>>5]
-        encoded[1] = ALPHABET[bytes[0]&31]
-        encoded[2] = ALPHABET[(bytes[1]&248)>>3]
-        encoded[3] = ALPHABET[((bytes[1]&7)<<2)|((bytes[2]&192)>>6)]
-        encoded[4] = ALPHABET[(bytes[2]&62)>>1]
-        encoded[5] = ALPHABET[((bytes[2]&1)<<4)|((bytes[3]&240)>>4)]
-        encoded[6] = ALPHABET[((bytes[3]&15)<<1)|((bytes[4]&128)>>7)]
-        encoded[7] = ALPHABET[(bytes[4]&124)>>2]
-        encoded[8] = ALPHABET[((bytes[4]&3)<<3)|((bytes[5]&224)>>5)]
-        encoded[9] = ALPHABET[bytes[5]&31]
+        encoded[0] = ALPHABET[(bytes[0] & 224) >> 5]
+        encoded[1] = ALPHABET[bytes[0] & 31]
+        encoded[2] = ALPHABET[(bytes[1] & 248) >> 3]
+        encoded[3] = ALPHABET[((bytes[1] & 7) << 2) | ((bytes[2] & 192) >> 6)]
+        encoded[4] = ALPHABET[(bytes[2] & 62) >> 1]
+        encoded[5] = ALPHABET[((bytes[2] & 1) << 4) | ((bytes[3] & 240) >> 4)]
+        encoded[6] = ALPHABET[((bytes[3] & 15) << 1) | ((bytes[4] & 128) >> 7)]
+        encoded[7] = ALPHABET[(bytes[4] & 124) >> 2]
+        encoded[8] = ALPHABET[((bytes[4] & 3) << 3) | ((bytes[5] & 224) >> 5)]
+        encoded[9] = ALPHABET[bytes[5] & 31]
 
         # 16 bytes of entropy
-        encoded[10] = ALPHABET[(bytes[6]&248)>>3]
-        encoded[11] = ALPHABET[((bytes[6]&7)<<2)|((bytes[7]&192)>>6)]
-        encoded[12] = ALPHABET[(bytes[7]&62)>>1]
-        encoded[13] = ALPHABET[((bytes[7]&1)<<4)|((bytes[8]&240)>>4)]
-        encoded[14] = ALPHABET[((bytes[8]&15)<<1)|((bytes[9]&128)>>7)]
-        encoded[15] = ALPHABET[(bytes[9]&124)>>2]
-        encoded[16] = ALPHABET[((bytes[9]&3)<<3)|((bytes[10]&224)>>5)]
-        encoded[17] = ALPHABET[bytes[10]&31]
-        encoded[18] = ALPHABET[(bytes[11]&248)>>3]
-        encoded[19] = ALPHABET[((bytes[11]&7)<<2)|((bytes[12]&192)>>6)]
-        encoded[20] = ALPHABET[(bytes[12]&62)>>1]
-        encoded[21] = ALPHABET[((bytes[12]&1)<<4)|((bytes[13]&240)>>4)]
-        encoded[22] = ALPHABET[((bytes[13]&15)<<1)|((bytes[14]&128)>>7)]
-        encoded[23] = ALPHABET[(bytes[14]&124)>>2]
-        encoded[24] = ALPHABET[((bytes[14]&3)<<3)|((bytes[15]&224)>>5)]
-        encoded[25] = ALPHABET[bytes[15]&31]
+        encoded[10] = ALPHABET[(bytes[6] & 248) >> 3]
+        encoded[11] = ALPHABET[((bytes[6] & 7) << 2) | ((bytes[7] & 192) >> 6)]
+        encoded[12] = ALPHABET[(bytes[7] & 62) >> 1]
+        encoded[13] = ALPHABET[((bytes[7] & 1) << 4) | ((bytes[8] & 240) >> 4)]
+        encoded[14] = ALPHABET[((bytes[8] & 15) << 1) | ((bytes[9] & 128) >> 7)]
+        encoded[15] = ALPHABET[(bytes[9] & 124) >> 2]
+        encoded[16] = ALPHABET[((bytes[9] & 3) << 3) | ((bytes[10] & 224) >> 5)]
+        encoded[17] = ALPHABET[bytes[10] & 31]
+        encoded[18] = ALPHABET[(bytes[11] & 248) >> 3]
+        encoded[19] = ALPHABET[((bytes[11] & 7) << 2) | ((bytes[12] & 192) >> 6)]
+        encoded[20] = ALPHABET[(bytes[12] & 62) >> 1]
+        encoded[21] = ALPHABET[((bytes[12] & 1) << 4) | ((bytes[13] & 240) >> 4)]
+        encoded[22] = ALPHABET[((bytes[13] & 15) << 1) | ((bytes[14] & 128) >> 7)]
+        encoded[23] = ALPHABET[(bytes[14] & 124) >> 2]
+        encoded[24] = ALPHABET[((bytes[14] & 3) << 3) | ((bytes[15] & 224) >> 5)]
+        encoded[25] = ALPHABET[bytes[15] & 31]
 
         encoded.join
       end
 
-      # @param string [String]
+      # Decodes a size 26 +String+ into a size 16 byte +Array+.
+      # Based on https://github.com/jetpack-io/typeid-go/blob/341e2b135e0609db272e6400f2f551487725824a/base32/base32.go#L82.
+      # Each line needs an extra `& 0xFF` because the elements are +Integer+s, which don't truncate on left shifts.
+      #
+      # @param string [String] size 26 base32-encoded string
       # @return [Array<Integer>]
       def self.decode(string)
         bytes = string.bytes
 
-        raise "invalid length" unless bytes.length == 26
-        raise "invalid base32 character" if bytes.any? { |byte| DEC[byte] == 0xFF }
+        raise Error, "invalid length" unless bytes.length == ENCODED_STRING_LENGTH
+        raise Error, "invalid base32 character" if bytes.any? { |byte| DEC[byte] == 0xFF }
 
-        output = Array.new(16, 0)
+        output = Array.new(DECODED_BYTE_ARRAY_LENGTH, 0)
 
         # 6 bytes timestamp (48 bits)
         output[0] = ((DEC[bytes[0]] << 5) | DEC[bytes[1]]) & 0xFF
@@ -94,7 +114,7 @@ class TypeID < String
         output[8] = ((DEC[bytes[13]] << 4) | (DEC[bytes[14]] >> 1)) & 0xFF
         output[9] = ((DEC[bytes[14]] << 7) | (DEC[bytes[15]] << 2) | (DEC[bytes[16]] >> 3)) & 0xFF
         output[10] = ((DEC[bytes[16]] << 5) | DEC[bytes[17]]) & 0xFF
-        output[11] = ((DEC[bytes[18]] << 3) | DEC[bytes[19]]>>2) & 0xFF
+        output[11] = ((DEC[bytes[18]] << 3) | DEC[bytes[19]] >> 2) & 0xFF
         output[12] = ((DEC[bytes[19]] << 6) | (DEC[bytes[20]] << 1) | (DEC[bytes[21]] >> 4)) & 0xFF
         output[13] = ((DEC[bytes[21]] << 4) | (DEC[bytes[22]] >> 1)) & 0xFF
         output[14] = ((DEC[bytes[22]] << 7) | (DEC[bytes[23]] << 2) | (DEC[bytes[24]] >> 3)) & 0xFF

data/lib/typeid/uuid.rb

@@ -2,22 +2,37 @@ require "uuid7"
 require_relative "./uuid/base32.rb"
 
 class TypeID < String
+  # Represents a UUID. Can be treated as a string.
   class UUID < String
+    # @return [Array<Integer>]
     attr_reader :bytes
 
-    # @param timestamp [Integer]
+    # Utility method to generate a timestamp as milliseconds since the Unix epoch.
+    #
+    # @return [Integer]
+    def self.timestamp
+      Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+    end
+
+    # Generates a new +UUID+, using gem "uuid7".
+    #
+    # @param timestamp [Integer] milliseconds since the Unix epoch
     # @return [TypeID::UUID]
-    def self.generate(timestamp: Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond))
+    def self.generate(timestamp: self.class.timestamp)
       from_string(UUID7.generate(timestamp: timestamp))
     end
 
-    # @param string [String]
+    # Parses a +UUID+ from a base32 +String+.
+    #
+    # @param string [String] base32-encoded UUID
     # @return [TypeID::UUID]
     def self.from_base32(string)
       new(TypeID::UUID::Base32.decode(string))
     end
 
-    # @param string [String]
+    # Parses a +UUID+ from a raw +String+.
+    #
+    # @param string [String] raw UUID
     # @return [TypeID::UUID]
     def self.from_string(string)
       bytes = string
@@ -29,7 +44,9 @@ class TypeID < String
       new(bytes)
     end
 
-    # @param bytes [Array<Integer>]
+    # Initializes a +UUID+ from an array of bytes.
+    #
+    # @param bytes [Array<Integer>] size 16 byte array
     def initialize(bytes)
       @bytes = bytes
 

data/lib/typeid/version.rb

@@ -1,3 +1,3 @@
 class TypeID < String
-  VERSION = "0.1.9".freeze
+  VERSION = "0.2.0".freeze
 end

data/lib/typeid.rb

@@ -1,28 +1,52 @@
 require_relative "./typeid/uuid.rb"
 
+# Represents a TypeID.
+# Provides accessors to the underlying prefix, suffix, and UUID.
+# Can be treated as a string.
+#
+# To generate a new +TypeID+:
+#   TypeID.new("foo") #=> #<TypeID foo_01h4vjdvzefw18zfwz5dxw5y8g>
+#
+# To parse a +TypeID+ from a string:
+#   TypeID.from_string("foo_01h4vjdvzefw18zfwz5dxw5y8g") #=> #<TypeID foo_01h4vjdvzefw18zfwz5dxw5y8g>
+#
+# To parse a +TypeID+ from a UUID:
+#   TypeID.from_uuid("foo", "01893726-efee-7f02-8fbf-9f2b7bc2f910") #=> #<TypeID foo_01h4vjdvzefw18zfwz5dxw5y8g>
+#
+# To create a +TypeID+ from a timestamp (in milliseconds since the Unix epoch):
+#   TypeID.new("foo", timestamp: 1688847445998) #=> #<TypeID foo_01h4vjdvzefw18zfwz5dxw5y8g>
 class TypeID < String
-  SUFFIX_LENGTH = 26
   MAX_PREFIX_LENGTH = 63
 
   class Error < StandardError; end
 
+  # @return [String]
   attr_reader :prefix
+
+  # @return [String]
   attr_reader :suffix
   alias type prefix
 
-  # @param string [String]
+  # Parses a +TypeID+ from a string.
+  #
+  # @param string [String] string representation of a +TypeID+
   # @return [TypeID]
   def self.from_string(string)
     case string.split("_")
-    in [suffix] then from("", suffix)
+    in [suffix]
+      from("", suffix)
+
     in [prefix, suffix]
       raise Error, "prefix cannot be empty when there's a separator" if prefix.empty?
 
       from(prefix, suffix)
-    else raise Error, "invalid typeid: #{string}"
+    else
+      raise Error, "invalid typeid: #{string}"
     end
   end
 
+  # Parses a +TypeID+ given a prefix and a raw UUID string.
+  #
   # @param prefix [String]
   # @param uuid [String]
   # @return [TypeID]
@@ -30,6 +54,8 @@ class TypeID < String
     from(prefix, TypeID::UUID.from_string(uuid).base32)
   end
 
+  # Creates a +TypeID+ given a prefix string and a suffix string.
+  #
   # @param prefix [String]
   # @param suffix [String]
   # @return [TypeID]
@@ -37,23 +63,30 @@ class TypeID < String
     new(prefix, suffix: suffix)
   end
 
+  # Returns the +nil+ TypeID.
+  #
   # @return [TypeID]
   def self.nil
-    from("", "0" * SUFFIX_LENGTH)
+    @nil ||= from("", "0" * TypeID::UUID::Base32::ENCODED_STRING_LENGTH)
   end
 
+  # Creates a +TypeID+ given a prefix and an optional suffix or timestamp (in milliseconds since the Unix epoch).
+  # When given only a prefix, generates a new +TypeID+.
+  # When +suffix+ or +timestamp+ is provided, creates a +TypeID+ from the given value.
+  #
   # @param prefix [String]
-  # @param timestamp [Integer]
-  # @param suffix [String]
+  # @param timestamp [Integer] milliseconds since the Unix epoch
+  # @param suffix [String] base32-encoded UUID
   def initialize(
     prefix,
-    timestamp: Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond),
+    timestamp: TypeID::UUID.timestamp,
     suffix: TypeID::UUID.generate(timestamp: timestamp).base32
   )
     raise Error, "prefix length cannot be greater than #{MAX_PREFIX_LENGTH}" if prefix.length > MAX_PREFIX_LENGTH
     raise Error, "prefix must be lowercase ASCII characters" unless prefix.match?(/^[a-z]*$/)
-    raise Error, "suffix must be #{SUFFIX_LENGTH} characters" unless suffix.length == SUFFIX_LENGTH
+    raise Error, "suffix must be #{TypeID::UUID::Base32::ENCODED_STRING_LENGTH} characters" unless suffix.length == TypeID::UUID::Base32::ENCODED_STRING_LENGTH
     raise Error, "suffix must only contain the letters in '#{TypeID::UUID::Base32::ALPHABET}'" unless suffix.chars.all? { |char| TypeID::UUID::Base32::ALPHABET.include?(char) }
+    raise Error, "suffix must start with a 0-7 digit to avoid overflows" unless ("0".."7").cover?(suffix.chars.first)
 
     @prefix = prefix
     @suffix = suffix
@@ -61,6 +94,8 @@ class TypeID < String
     super(string)
   end
 
+  # Returns the UUID component of the +TypeID+, parsed from the suffix.
+  #
   # @return [TypeID::UUID]
   def uuid
     TypeID::UUID.from_base32(suffix)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typeid
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrew Booth
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-01 00:00:00.000000000 Z
+date: 2023-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uuid7
@@ -25,33 +25,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.2.0
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: 0.14.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: 0.14.2
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.2
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.14.2
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement