From 97495ad2036b4877021168f946329466443519db Mon Sep 17 00:00:00 2001
From: Pat Garrity <pfm@garrity.co>
Date: Tue, 7 Apr 2026 03:50:46 +0000
Subject: [PATCH] (patch) update to latest scala, minor documentation/code
 improvements (#17)

Reviewed-on: https://git.garrity.co/garrity-software/gs-uuid/pulls/17
---
 .scalafmt.conf                            |  2 +-
 build.sbt                                 |  6 ++--
 project/build.properties                  |  2 +-
 src/main/scala/gs/uuid/v0/UUID.scala      | 39 +++++++++++++++++++++--
 src/test/scala/gs/uuid/v0/UUIDTests.scala | 10 ++++++
 5 files changed, 52 insertions(+), 7 deletions(-)

diff --git a/.scalafmt.conf b/.scalafmt.conf
index ed3b6eb..11f6020 100644
--- a/.scalafmt.conf
+++ b/.scalafmt.conf
@@ -1,5 +1,5 @@
 // See: https://github.com/scalameta/scalafmt/tags for the latest tags.
-version = 3.10.4
+version = 3.10.7
 runner.dialect = scala3
 maxColumn = 80
 
diff --git a/build.sbt b/build.sbt
index 9264173..ec8e4fe 100644
--- a/build.sbt
+++ b/build.sbt
@@ -1,4 +1,4 @@
-val scala3: String = "3.8.1"
+val scala3: String = "3.8.3"
 
 ThisBuild / scalaVersion  := scala3
 ThisBuild / versionScheme := Some("semver-spec")
@@ -20,7 +20,7 @@ val sharedSettings = Seq(
 
 lazy val testSettings = Seq(
   libraryDependencies ++= Seq(
-    "org.scalameta" %% "munit" % "1.2.1" % Test
+    "org.scalameta" %% "munit" % "1.2.4" % Test
   )
 )
 
@@ -31,6 +31,6 @@ lazy val `gs-uuid` = project
   .settings(name := s"${gsProjectName.value}-v${semVerMajor.value}")
   .settings(
     libraryDependencies ++= Seq(
-      "com.fasterxml.uuid" % "java-uuid-generator" % "5.1.0"
+      "com.fasterxml.uuid" % "java-uuid-generator" % "5.2.0"
     )
   )
diff --git a/project/build.properties b/project/build.properties
index 30b7fd9..08a6fc0 100644
--- a/project/build.properties
+++ b/project/build.properties
@@ -1 +1 @@
-sbt.version=1.12.0
+sbt.version=1.12.8
diff --git a/src/main/scala/gs/uuid/v0/UUID.scala b/src/main/scala/gs/uuid/v0/UUID.scala
index a4d29fe..f138ed2 100644
--- a/src/main/scala/gs/uuid/v0/UUID.scala
+++ b/src/main/scala/gs/uuid/v0/UUID.scala
@@ -2,8 +2,8 @@ package gs.uuid.v0
 
 import com.fasterxml.uuid.Generators
 
-/** Alias for the `java.util.UUID` type, which represents a 128-bit (16-byte)
-  * value.
+/** `gs.uuid.v0.UUID` is an alias for the `java.util.UUID` type, which
+  * represents a 128-bit (16-byte) value.
   *
   * ## ID Generation
   *
@@ -26,6 +26,28 @@ import com.fasterxml.uuid.Generators
   */
 opaque type UUID = java.util.UUID
 
+/** `gs.uuid.v0.UUID` is an alias for the `java.util.UUID` type, which
+  * represents a 128-bit (16-byte) value.
+  *
+  * ## ID Generation
+  *
+  * This library provides generator implementations for the following types of
+  * UUID:
+  *
+  *   - Type 4: `UUID.v4()`
+  *   - Type 7: `UUID.v7()`
+  *
+  * These implementations are provided by JUG.
+  *
+  * ## Serialization
+  *
+  * This library supports the following representations:
+  *
+  *   - Hexadecimal string without dashes
+  *   - Byte array
+  *
+  * Serialization code is based on Jackson Databind (Apache 2.0).
+  */
 object UUID:
   /** Express any `java.util.UUID` as a GS UUID.
     *
@@ -66,6 +88,13 @@ object UUID:
     G: Generator
   ): UUID = G.next()
 
+  /** Alias for `v4()`.
+    *
+    * @return
+    *   New v4 UUID (Random).
+    */
+  def random(): UUID = v4()
+
   /** @return
     *   New v4 UUID (Random).
     */
@@ -101,6 +130,12 @@ object UUID:
       .getOrElse(None)
 
   extension (uid: UUID)
+
+    /** @return
+      *   The unwrapped value -- the underlying `java.util.UUID`.
+      */
+    def unwrap(): java.util.UUID = uid
+
     /** @return
       *   The underlying `java.util.UUID`.
       */
diff --git a/src/test/scala/gs/uuid/v0/UUIDTests.scala b/src/test/scala/gs/uuid/v0/UUIDTests.scala
index e4b66d4..b7ed8ef 100644
--- a/src/test/scala/gs/uuid/v0/UUIDTests.scala
+++ b/src/test/scala/gs/uuid/v0/UUIDTests.scala
@@ -5,6 +5,15 @@ class UUIDTests extends munit.FunSuite:
   private val v7                                 = UUID.Generator.version7
   given CanEqual[java.util.UUID, java.util.UUID] = CanEqual.derived
 
+  test(
+    "should instantiate a random UUID, serialize it, and parse the result"
+  ) {
+    val base   = UUID.random()
+    val str    = base.str()
+    val parsed = UUID.parse(str)
+    assertEquals(parsed, Some(base))
+  }
+
   test(
     "should instantiate a type 4 UUID, serialize it, and parse the result"
   ) {
@@ -48,6 +57,7 @@ class UUIDTests extends munit.FunSuite:
     val parsed = UUID.fromString(str)
     assertEquals(parsed, Some(base))
     assertEquals(parsed.map(_.toUUID()), Some(raw))
+    assertEquals(parsed.map(_.unwrap()), Some(raw))
   }
 
   test("should successfully parse a UUID with dashes") {