feat: add UUIDv7 support with encoding options

shortuuid.go

@@ -53,6 +53,40 @@ func NewWithAlphabet(abc string) string {
 	return enc.Encode(uuid.New())
 }
 
+// NewV7 returns a new UUIDv7, encoded with base57.
+// UUIDv7 is time-based and provides monotonicity, making it ideal for certain database indexing scenarios.
+func NewV7() string {
+	return DefaultEncoder.Encode(uuid.Must(uuid.NewV7()))
+}
+
+// NewV7WithEncoder returns a new UUIDv7, encoded with enc.
+func NewV7WithEncoder(enc Encoder) string {
+	return enc.Encode(uuid.Must(uuid.NewV7()))
+}
+
+// NewV7WithNamespace returns a new UUIDv5 (or v7 if name is empty), encoded with base57.
+func NewV7WithNamespace(name string) string {
+	var u uuid.UUID
+
+	switch {
+	case name == "":
+		u = uuid.Must(uuid.NewV7())
+	case hasPrefixCaseInsensitive(name, "https://"), hasPrefixCaseInsensitive(name, "http://"):
+		u = hashedUUID(uuid.NameSpaceURL, name)
+	default:
+		u = hashedUUID(uuid.NameSpaceDNS, name)
+	}
+
+	return DefaultEncoder.Encode(u)
+}
+
+// NewV7WithAlphabet returns a new UUIDv7, encoded with base57 using the
+// alternative alphabet abc.
+func NewV7WithAlphabet(abc string) string {
+	enc := encoder{newAlphabet(abc)}
+	return enc.Encode(uuid.Must(uuid.NewV7()))
+}
+
 func hasPrefixCaseInsensitive(s, prefix string) bool {
 	return len(s) >= len(prefix) && strings.EqualFold(s[:len(prefix)], prefix)
 }

shortuuid_test.go

@@ -283,6 +283,79 @@ func TestAlphabet_MB(t *testing.T) {
 	}
 }
 
+func TestNewV7(t *testing.T) {
+	shortUUID := NewV7()
+
+	decodedUUID, err := DefaultEncoder.Decode(shortUUID)
+	if err != nil {
+		t.Fatalf("failed to decode short UUIDv7: %v", err)
+	}
+
+	if decodedUUID.Version() != 7 {
+		t.Errorf("expected UUID version 7, got %d", decodedUUID.Version())
+	}
+
+	if decodedUUID.Variant() != uuid.RFC4122 {
+		t.Errorf("expected RFC4122 variant, got %d", decodedUUID.Variant())
+	}
+}
+
+func TestNewV7WithEncoder(t *testing.T) {
+	customAlphabet := "abcdef0123456789"
+	enc := encoder{newAlphabet(customAlphabet)}
+
+	shortUUID := NewV7WithEncoder(enc)
+
+	decodedUUID, err := enc.Decode(shortUUID)
+	if err != nil {
+		t.Fatalf("failed to decode short UUIDv7 with custom encoder: %v", err)
+	}
+
+	if decodedUUID.Version() != 7 {
+		t.Errorf("expected UUID version 7, got %d", decodedUUID.Version())
+	}
+}
+
+func TestNewV7WithNamespace(t *testing.T) {
+	var tests = []struct {
+		name string
+	}{
+		{"http://www.example.com/"},
+		{"example.com/"},
+		{"https://shortuuid.example/"},
+		{""}, // Empty name for UUIDv7
+	}
+	for _, test := range tests {
+		shortUUID := NewV7WithNamespace(test.name)
+
+		decodedUUID, err := DefaultEncoder.Decode(shortUUID)
+		if err != nil {
+			t.Fatalf("failed to decode short UUIDv7 with namespace %q: %v", test.name, err)
+		}
+
+		if test.name == "" && decodedUUID.Version() != 7 {
+			t.Errorf("expected UUID version 7, got %d for empty namespace", decodedUUID.Version())
+		} else if test.name != "" && decodedUUID.Version() != 5 {
+			t.Errorf("expected UUID version 5, got %d for namespace %q", decodedUUID.Version(), test.name)
+		}
+	}
+}
+
+func TestNewV7WithAlphabet(t *testing.T) {
+	customAlphabet := "abcdefghij12345"
+	shortUUID := NewV7WithAlphabet(customAlphabet)
+
+	enc := encoder{newAlphabet(customAlphabet)}
+	decodedUUID, err := enc.Decode(shortUUID)
+	if err != nil {
+		t.Fatalf("failed to decode short UUIDv7 with custom alphabet: %v", err)
+	}
+
+	if decodedUUID.Version() != 7 {
+		t.Errorf("expected UUID version 7, got %d", decodedUUID.Version())
+	}
+}
+
 func BenchmarkUUID(b *testing.B) {
 	for i := 0; i < b.N; i++ {
 		New()
@@ -375,3 +448,21 @@ func BenchmarkNewWithNamespaceHttps(b *testing.B) {
 		_ = NewWithNamespace("https://someaveragelengthurl.test")
 	}
 }
+
+func BenchmarkNewV7(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		_ = NewV7()
+	}
+}
+
+func BenchmarkNewV7WithAlphabet(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		_ = NewV7WithAlphabet("abcdefghij12345")
+	}
+}
+
+func BenchmarkNewV7WithNamespace(b *testing.B) {
+	for i := 0; i < b.N; i++ {
+		_ = NewV7WithNamespace("http://example.com/")
+	}
+}