update readme and docs

Justfile

@@ -2,18 +2,25 @@
 default:
  @just --list
 
+# launch a jshell repl
 repl:
  @rlwrap ./gradlew --console plain jshell
 
+# build and run tests
 test:
  @./gradlew build
 
+# publish locally
 publish-local:
  #ORG_GRADLE_PROJECT_signingKey=...
  #ORG_GRADLE_PROJECT_signingPassword=..
  @./gradlew publishToMavenLocal
 
+# publish to maven central
 publish:
+ #https://oss.sonatype.org/
  #ORG_GRADLE_PROJECT_signingKey=...
  #ORG_GRADLE_PROJECT_signingPassword=..
+ #OSSRH_USER=
+ #OSSRH_PASSWORD=
  @./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository

README.md

@@ -8,3 +8,57 @@ TypeIDs are a modern, **type-safe**, globally unique identifier based on the upc
 UUIDv7 standard. They provide a ton of nice properties that make them a great choice
 as the primary identifiers for your data in a database, APIs, and distributed systems.
 Read more about TypeIDs in their [spec](https://github.com/jetpack-io/typeid).
+
+## Installation
+
+To add this library as a dependency in your app add the following to your build
+
+### Gradle
+
+```kotlin
+implementation("me.lessis:typeid:0.0.1")
+```
+
+### Maven
+
+```xml
+<dependency>
+ <groupId>me.lessis</groupId>
+ <artifactId>typeid</artifactId>
+ <version>0.0.1</version>
+</dependency>
+```
+
+## Usage
+
+This library provides both a statically typed and a dynamically typed version of TypeIDs.
+
+The statically typed version lives under the `typed` package. It makes it possible for
+the go compiler itself to enforce type safety.
+
+To use it, first define your TypeID types:
+
+```java
+import typeid.TypeID
+
+// generate type ids (prefix_7zzzzzzzzqf3b80018tr001cg3)
+var id = new TypeID("prefix");
+
+// parse typed ids from their string representation
+var parsed = TypeID.fromString(id.toString());
+
+// this is a fallible operation so the value returned
+// is an Optional, present when values are valid, empty when not
+parsed.ifPresent(
+ id -> {
+ System.out.println(
+ "prefix %s suffix %s".formmated(
+ id.prefix(), id.suffix();
+ )
+ );
+ }
+);
+
+// get a java.util.UUID representation of a type id (ffffffff-fff7-78d6-8000-28d60000b203)
+id.uuid();
+```

build.gradle.kts

@@ -21,7 +21,7 @@ plugins {
 // https://central.sonatype.org/publish/publish-guide/#introduction
 
 group = "me.lessis"
-version = "0.0.1-SNAPSHOT"
+version = "0.0.1"
 
 repositories {
  // Use Maven Central for resolving dependencies.
@@ -78,16 +78,6 @@ publishing {
  }
  }
  }
- repositories {
- maven {
- // https://central.sonatype.org/publish/publish-guide/#accessing-repositories
- name = "OSSRH"
- val releasesRepoUrl = uri("https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/")
- val snapshotsRepoUrl = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
- url = if (version.toString().endsWith("SNAPSHOT")) snapshotsRepoUrl else releasesRepoUrl
- credentials(PasswordCredentials::class)
- }
- }
 }
 
 signing {
@@ -97,6 +87,7 @@ signing {
  sign(publishing.publications["mavenJava"])
 }
 
+// https://oss.sonatype.org
 nexusPublishing {
  repositories {
  sonatype {

src/main/java/typeid/TypeID.java

@@ -10,7 +10,9 @@
 /**
  * A human friendly, k-sortable, type prefixed, uuid7 compatible identifier.
  *
- * <p>Values are expected to be constructed with <code>new TypeID("typename");</code>
+ * <p>Values are expected to be constructed with <code>new TypeID("typename")</code>
+ * or parsed from their string representation with <code>TypeID.fromString("prefix_01h455vb4pex5vsknk084sn02q")</code>
+ *
  */
 public record TypeID(String prefix, String suffix) {
  private static final Predicate<String> PREFIX =
@@ -29,7 +31,7 @@ public record TypeID(String prefix, String suffix) {
  }
 
  /**
- * create a new TypeID with a given prefix
+ * Creates a new TypeID instance with a given prefix.
  *
  * @param prefix prefix indicating the type of this id
  */