typeid 0.1.10 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4ab90e4532a67246f422ad22f264ae2b238418de7246998d40e2a725dd0c6da
-  data.tar.gz: 017e98dc29bce78fb73e217f771865f8477ba8f73fb585a1fca07804e1fa48f1
+  metadata.gz: af045f36c25f729104c597aec25af3c3755bee1d163bc22badce8fa85952d7ec
+  data.tar.gz: 8869cf01f856b513c501229d69fe262233934f7a8c886c8703e1c65a3c53692c
 SHA512:
-  metadata.gz: 3ba0df0442f474b7890e03190f21f7162ba8c36ab6f449bd1df2049ef3ea378568bdb4436517ac23795eefd613854060413c87e7722d3f37bd7d5eca02702e9a
-  data.tar.gz: e4506709a38e017030717e2acd1792e68e1e9715a90668d5e8afea51b4a4cb67595aa88b2b4c16b3b0773026a2612b7a8c08f160b73d650909f34f50ce41eb51
+  metadata.gz: 6f0019bff65125af55cf414d9bd0d5145cdafa1fedc1cbc6cf69b207966c4674a461daba129bc4cf4d9cb021c9f976a5b77b875bb3041ceae561c0cfd48f4941
+  data.tar.gz: 41def5ca6d85fe6a5a5b4133d64b1c47a3c56632564fe2c83d45c8ddeec752e96523738bf1cc9bf615f547afa60149928552cf01593dcc583c3da729dab1e2f6

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,18 +44,31 @@ 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
 
       super(string)
     end
 
+    # Returns the +UUID+ encoded as a base32 +String+.
+    #
     # @return [String]
     def base32
       TypeID::UUID::Base32.encode(bytes)
     end
 
+    # Returns the timestamp of the +UUID+ as milliseconds since the Unix epoch.
+    #
+    # @return [Integer]
+    def timestamp
+      bytes[0..5]
+        .map.with_index { |byte, index| byte << (5 - index) * 8 }
+        .inject(:|)
+    end
+
     # @return [String]
     def inspect
       "#<#{self.class.name} #{to_s}>"

data/lib/typeid/version.rb

@@ -1,3 +1,3 @@
 class TypeID < String
-  VERSION = "0.1.10".freeze
+  VERSION = "0.2.1".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,22 +63,28 @@ 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)
 
@@ -62,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.10
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrew Booth
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-07 00:00:00.000000000 Z
+date: 2023-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uuid7