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.
- 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.
go get github.com/yomorun/hashids-goTo 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 dependenciesgo build ./...Build the command line tool:
go build -o hashids ./cmd/hashidsgo 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 ./... -raceThe 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
507f1f77bcf86cd799439011Flags: -salt, -min-length, -alphabet. Commands: encode, decode,
encodehex, decodehex, version.
h := hashids.NewWithSalt("this is my salt")
hash := h.Encode(12345) // "NkK9"h := hashids.NewWithSalt("this is my salt")
numbers := h.Decode("NkK9") // []int64{12345}Decoding will not work if the salt differs:
h := hashids.NewWithSalt("this is my pepper")
numbers := h.Decode("NkK9") // []int64{}h := hashids.NewWithSalt("this is my salt")
hash := h.Encode(683, 94108, 123, 5) // "aBMswoO2UB3Sj"h := hashids.NewWithMinLength("this is my salt", 8)
hash := h.Encode(1) // "gB0NV05e"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.
h := hashids.NewWithSalt("This is my salt")
hash := h.EncodeHex("507f1f77bcf86cd799439011") // "YO4jDOaZYlhw9mw6m3kB"
hex := h.DecodeHex(hash) // "507f1f77bcf86cd799439011"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"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.
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.
| 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.
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.
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.
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.
Two Java behaviours have no Go equivalent. Neither is reachable through normal use, and both are listed here rather than silently ignored:
nullalphabet. Java'snew Hashids(salt, minLength, null)throws aNullPointerException. Go has no nilstring, 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"".- 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.
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.
- All 17 tests from
HashidsTest.javawere 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_parityreplays 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, 297decodeHexcases,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.golock down the Java-semantics helpers (String.split(" "), Java's\s,String.matches) and the behaviours that a future reader might "simplify" incorrectly.
- fanweixiao
- 0x3333
- kenumir
- Christophe R.
- Matthias Vill
MIT, as in the original project. See LICENSE.