nid

nid

nid package provides human-readable named unique identifiers.

Overview

The package offers the following functionalities:

• Named prefix: All identifiers have name prefix that makes them more readable.
• Universally unique: Random part of identifier base is 8 bytes length that is comparable to commonly used UUIDv4 & ULID.
• Sortable by time: All identifiers have 8 bytes length time prefix. They are sortable both in string & binary format and have sequential order by time.
• Text, JSON & SQL Support: Identifiers implement multiple encoding reducing code needed to add manual conversion:
  • encoding.TextMarshaler, encoding.TextUnmarshaler for text encoding.
  • json.Marshaler, json.Unmarshaler for JSON encoding.
  • sql.Scanner, driver.Valuer for storing in SQL database.

Installation

To use this package in your Go project, you can import it using:

import "go.wamod.dev/nid"

Usage

To start creating named identifiers, create new Naming first:

var BookIDN = nid.MustNaming("book") // snake_case 

Create your resource type:

type Book struct {
    ID     nid.NID `json:"id"`
    Title  string  `json:"title"`
    Author string  `json:"author"`
}

Then whenever you need to generate new identifier for your resource use identifier Naming:

book := Book{
    ID:     BookIDN.New(),
    Title:  "The Hobbit",
    Author: "J.R.R. Tolkien",
}

Helpers

Parsing strings

To parse named identifier from string use Parse function:

bookID, err := nid.Parse("book_000034o5m20uo63o22umrn7kcs")

To parse base identifier from string using ParseBase function:

base, err := nid.ParseBase("000034o5m20uo63o22umrn7kcs")
if err != nil {
    // handle error
}

// Apply resource naming to identifier
bookID := BookIDN.Apply(base)

Converting to string

When you need to convert it to string format you can use String() method:

fmt.Print(bookID.String()) 
// Output:
// book_000034o5m20uo63o22umrn7kcs

Similarly, you can also get identifier base string value:

fmt.Print(bookID.Base().String())
// Output:
// 000034o5m20uo63o22umrn7kcs

Compare

To check if two named identifiers are the same you can use equal operator:

var (
    a nid.NID
    b nid.NID
)

if a == b {
    fmt.Print("a == b")
}

You can also use Compare helpers that return 0, -1, 1:

switch nid.Compare(a, b) {
    case 0:
        fmt.Print("a == b")
    case 1:
        fmt.Print("a > b")
    case -1:
        fmt.Print("a < b")
}

Similarly, you can also compare identifier base:

switch nid.CompareBase(a.Base(), b.Base()) {
    case 0:
        fmt.Print("a == b")
    case 1:
        fmt.Print("a > b")
    case -1:
        fmt.Print("a < b")
}

Sort

When you need to sort multiple identifiers you can use Sort helper:

var ids []nid.NID

nid.Sort(ids)

Similarly, you can also sort identifier base:

var baseIDs []nid.Base

nid.SortBase(baseIDs)

Contributing

Thank you for your interest in contributing to the nid Go library! We welcome and appreciate any contributions, whether they be bug reports, feature requests, or code changes.

If you've found a bug, please create an issue describing the problem, including any relevant error messages and a minimal reproduction of the issue.

License

nid is licensed under the MIT License.