Skip to content

About

Hashids algorithm v1.0.0 implementation in Java

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

hashids-go

A Go port of hashids-java.

Generate short, unique, non-sequential ids from numbers. Encoded ids can be decoded back to the original numbers, can be padded to a minimum length, and can use a custom alphabet. The default alphabet leaves out the letters that form the most common English curse words, so generated ids do not accidentally spell them.

This is a behaviour-preserving migration: the algorithm, public surface, validation, error messages, edge cases and observable output are identical to the Java original. See Migration notes for the details and for the two divergences that Go cannot express.

Requirements

  • Go 1.21 or newer.

There are no third-party dependencies. The package uses only the standard library (math, regexp, strconv, strings, unicode/utf16), mirroring the Java original, which depended only on the JDK.

Setup

go get github.com/yomorun/hashids-go

To work on the repository itself:

git clone https://github.com/yomorun/hashids-go
cd hashids-go
go mod download   # no-op: there are no external dependencies

Build

go build ./...

Build the command line tool:

go build -o hashids ./cmd/hashids

Test

go test ./...

With coverage, and with the race detector (-race needs CGO_ENABLED=1 and a C toolchain):

go test ./... -cover
CGO_ENABLED=1 go test ./... -race

Run

The cmd/hashids binary is a thin wrapper around the library:

$ go run ./cmd/hashids -salt "this is my salt" encode 12345
NkK9

$ go run ./cmd/hashids -salt "this is my salt" decode NkK9
12345

$ go run ./cmd/hashids -salt "this is my salt" encode 683 94108 123 5
aBMswoO2UB3Sj

$ go run ./cmd/hashids -salt "this is my salt" -min-length 8 encode 1
gB0NV05e

$ go run ./cmd/hashids -salt "this is my salt" -alphabet 0123456789abcdef encode 1234567
b332db5

$ go run ./cmd/hashids -salt "This is my salt" encodehex 507f1f77bcf86cd799439011
YO4jDOaZYlhw9mw6m3kB

$ go run ./cmd/hashids -salt "This is my salt" decodehex YO4jDOaZYlhw9mw6m3kB
507f1f77bcf86cd799439011

Flags: -salt, -min-length, -alphabet. Commands: encode, decode, encodehex, decodehex, version.

Usage

Encoding one number

h := hashids.NewWithSalt("this is my salt")
hash := h.Encode(12345) // "NkK9"

Decoding

h := hashids.NewWithSalt("this is my salt")
numbers := h.Decode("NkK9") // []int64{12345}

Decoding with a different salt

Decoding will not work if the salt differs:

h := hashids.NewWithSalt("this is my pepper")
numbers := h.Decode("NkK9") // []int64{}

Encoding several numbers

h := hashids.NewWithSalt("this is my salt")
hash := h.Encode(683, 94108, 123, 5) // "aBMswoO2UB3Sj"

Making an id longer

h := hashids.NewWithMinLength("this is my salt", 8)
hash := h.Encode(1) // "gB0NV05e"

Using a custom alphabet

h, err := hashids.NewWithAlphabet("this is my salt", 0, "0123456789abcdef")
if err != nil {
    return err
}
hash := h.Encode(1234567) // "b332db5"

MustNewWithAlphabet is available when an invalid alphabet should panic instead, matching the Java constructor.

Encoding hexadecimal

h := hashids.NewWithSalt("This is my salt")
hash := h.EncodeHex("507f1f77bcf86cd799439011") // "YO4jDOaZYlhw9mw6m3kB"
hex := h.DecodeHex(hash)                        // "507f1f77bcf86cd799439011"

Randomness

Repeated numbers do not produce repeated output:

h := hashids.NewWithSalt("this is my salt")
h.Encode(5, 5, 5, 5)                      // "1Wc8cwcE"
h.Encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)   // "kRHnurhptKcjIDTWC3sx"

Incrementing inputs produce unrelated output:

h.Encode(1) // "NV"
h.Encode(2) // "6m"
h.Encode(3) // "yD"
h.Encode(4) // "2l"
h.Encode(5) // "rD"

Curse word avoidance

The default alphabet keeps the characters c, C, s, S, f, F, h, H, u, U, i, I, t, T apart as separators, so they never end up adjacent to each other in an id.

Limitation

The largest encodable number is hashids.MaxNumber (2^53 = 9007199254740992), the limit of an IEEE-754 double. Larger values cause a panic with an *IllegalArgumentError.

API mapping

Java Go
new Hashids() New()
new Hashids(salt) NewWithSalt(salt)
new Hashids(salt, minHashLength) NewWithMinLength(salt, minHashLength)
new Hashids(salt, minHashLength, alphabet) NewWithAlphabet(salt, minHashLength, alphabet) (*Hashids, error) and MustNewWithAlphabet(...)
String encode(long...) Encode(...int64) string
long[] decode(String) Decode(string) []int64
String encodeHex(String) EncodeHex(string) string
String decodeHex(String) DecodeHex(string) string
String getVersion() Version() string
static int checkedCast(long) CheckedCast(int64) int
static final long MAX_NUMBER MaxNumber
IllegalArgumentException *IllegalArgumentError (raised via panic)

Only the three-argument constructor can fail in Java, so only it gets an error-returning form in Go; the other three can never fail because the default alphabet is always valid.

Migration notes

Errors are raised with panic

Java's IllegalArgumentException is unchecked, and decode relies on that: it re-encodes the numbers it recovered to verify the hash, so a hostile input can make decode itself throw. Returning an error from Encode would therefore have forced Decode to return one too, changing both signatures and turning a thrown exception into a silently different result. Instead *IllegalArgumentError is raised with panic, keeping the signatures and the behaviour intact:

defer func() {
    if r := recover(); r != nil {
        if illegal, ok := r.(*hashids.IllegalArgumentError); ok {
            // handle it
            _ = illegal
        }
    }
}()

cmd/hashids/main.go shows this being converted back into an ordinary error.

Strings are processed as UTF-16 code units

java.lang.String is a sequence of UTF-16 code units, and the algorithm depends on that: consistentShuffle adds raw char values together, and the salt, alphabet and hash are indexed and sliced by code unit. Go strings are UTF-8, so text is converted to []uint16 internally (the jstring type) and back at the API boundary. Without this, any non-ASCII salt or alphabet would produce different ids from the Java version.

Java's \s is implemented by hand

The constructor strips whitespace from the alphabet with replaceAll("\\s+", ""). Java's \s is [ \t\n\x0B\f\r], but Go's RE2 \s is [\t\n\f\r ] and leaves out the vertical tab. Using Go's regexp here would keep a \u000B in a custom alphabet that Java removes, so the character set is implemented explicitly.

Known divergences

Two Java behaviours have no Go equivalent. Neither is reachable through normal use, and both are listed here rather than silently ignored:

  1. null alphabet. Java's new Hashids(salt, minLength, null) throws a NullPointerException. Go has no nil string, so the case cannot occur; an empty alphabet is rejected with the usual "alphabet must contain at least 16 unique characters" error, exactly as Java does for "".
  2. Lone surrogates in output. A custom alphabet containing astral-plane characters could make Java emit a string holding an unpaired surrogate, which is not representable in Go's UTF-8 strings and is replaced with U+FFFD. Astral characters in the salt are handled correctly, because the salt is only read, never emitted; this is covered by a test.

A stale example in the Java README

The Java README shows encodeHex("507f1f77bcf86cd799439011") returning goMYDnAezwurPKWKKxL2 for the salt "This is my salt". The Java code actually returns YO4jDOaZYlhw9mw6m3kB, and passing the README's value to Java's own decodeHex yields 07f1f77bcf8cd799439011 instead of the original input. This port matches the Java implementation, so it returns YO4jDOaZYlhw9mw6m3kB.

How parity was verified

  • All 17 tests from HashidsTest.java were migrated one-for-one, keeping their scenarios, inputs, assertions and names (Test_large_number, Test_issue45, and so on).
  • A characterization harness was run against the original Java library and its output recorded in testdata/java_baseline.txt. Test_java_parity replays the same 5215 cases against this port and requires every line to match. The golden file covers constructor internals (the derived alphabet, separators and guards) for 31 configurations, 261 encode/decode round trips, 297 hostile decode inputs, 225 hex cases, 297 decodeHex cases, CheckedCast, exception types and messages, 4000 deterministic pseudo-random sweeps across 9 configurations, and a minimum-length sweep from 0 to 40.
  • Additional Go tests in javastring_test.go lock down the Java-semantics helpers (String.split(" "), Java's \s, String.matches) and the behaviours that a future reader might "simplify" incorrectly.

Contributors

License

MIT, as in the original project. See LICENSE.

About

Hashids algorithm v1.0.0 implementation in Java

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages