Class: TypeID

Inherits:
String
  • Object
show all
Defined in:
lib/typeid.rb,
lib/typeid/uuid.rb,
lib/typeid/version.rb,
lib/typeid/uuid/base32.rb

Overview

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>

Defined Under Namespace

Classes: Error, UUID

Constant Summary collapse

MAX_PREFIX_LENGTH = 
63
VERSION = 
"0.2.2".freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(prefix, timestamp: TypeID::UUID.timestamp, suffix: TypeID::UUID.generate(timestamp: timestamp).base32) ⇒ TypeID

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.

Parameters:

  • prefix (String)
  • timestamp (Integer) (defaults to: TypeID::UUID.timestamp) —

    milliseconds since the Unix epoch

  • suffix (String) (defaults to: TypeID::UUID.generate(timestamp: timestamp).base32) —

    base32-encoded UUID

Raises:



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/typeid.rb', line 80

def initialize(
  prefix,
  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, "prefix cannot start or end with an underscore" if prefix.start_with?("_") || prefix.end_with?("_")
  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

  super(string)
end

Instance Attribute Details

#prefix ⇒ String (readonly) Also known as: type

Returns:

  • (String) 


24
25
26
 
# File 'lib/typeid.rb', line 24

def prefix
  @prefix
end

#suffix ⇒ String (readonly)

Returns:

  • (String) 


27
28
29
 
# File 'lib/typeid.rb', line 27

def suffix
  @suffix
end

Class Method Details

.from(prefix, suffix) ⇒ TypeID

Creates a TypeID given a prefix string and a suffix string.

Parameters:

  • prefix (String)
  • suffix (String)

Returns:



62
63
64
 
# File 'lib/typeid.rb', line 62

def self.from(prefix, suffix)
  new(prefix, suffix: suffix)
end

.from_string(string) ⇒ TypeID

Parses a TypeID from a string.

Parameters:

  • string (String) —

    string representation of a TypeID

Returns:



34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/typeid.rb', line 34

def self.from_string(string)
  case string.rpartition("_")
  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}"
  end
end

.from_uuid(prefix, uuid) ⇒ TypeID

Parses a TypeID given a prefix and a raw UUID string.

Parameters:

  • prefix (String)
  • uuid (String)

Returns:



53
54
55
 
# File 'lib/typeid.rb', line 53

def self.from_uuid(prefix, uuid)
  from(prefix, TypeID::UUID.from_string(uuid).base32)
end

.nil ⇒ TypeID

Returns the nil TypeID.

Returns:



69
70
71
 
# File 'lib/typeid.rb', line 69

def self.nil
  @nil ||= from("", "0" * TypeID::UUID::Base32::ENCODED_STRING_LENGTH)
end

Instance Method Details

#inspect ⇒ String

Returns:

  • (String) 


106
107
108
 
# File 'lib/typeid.rb', line 106

def inspect
  "#<#{self.class.name} #{self}>"
end

#uuid ⇒ TypeID::UUID

Returns the UUID component of the TypeID, parsed from the suffix.

Returns:



101
102
103
 
# File 'lib/typeid.rb', line 101

def uuid
  TypeID::UUID.from_base32(suffix)
end