triplex/README.md

Copyright (c) 2026 Micha Hoiting

triplex

triplex is a deterministic, reversible serial number engine for high-integrity identifiers. It maps a compact 32-bit integer space to a human-readable serial format:

LLL-NNN-LC

Where:

• L = data letter (A–Z)
• N = number (100–999)
• C = checksum letter (A–Z)

For instance

ABC-123-DT

What it provides

• 4 data letters
• 3 numeric digits (100–999)
• 1 checksum letter
• Optional forbidden-triplet filtering on the first three letters
• Reversible integer encoding/decoding
• Deterministic checksum generation

Total index capacity: 386,942,400 (26^4 * 900)

Features

• Reversible mapping: Encode(code) ↔ Decode(index)
• Deterministic checksum: C = 'A' + (index % 26)
• Compact index space: fits in uint32
• Human-readable serial format
• Useful for manufacturing, logistics, SaaS identifiers, and audit-safe systems

Example

package main

import (
	"fmt"

	"git.hoiting.org/micha/triplex/serial"
)

func main() {
	idx := uint32(123456)

	code, err := serial.Decode(idx)
	if err != nil {
		panic(err)
	}

	idx2, err := serial.Encode(code)
	if err != nil {
		panic(err)
	}

	fmt.Println(code)
	fmt.Println(idx == idx2) // true
}

Notes

• The current serial format is LLL-NNN-LC.
• Forbidden-triplet logic is centralized in serial.IsForbiddenTriplet and can be tailored to project rules.

API

• serial.Encode(code string) (uint32, error)
  • Parses and validates LLL-NNN-LC, checks checksum, and returns the deterministic index.
• serial.Decode(idx uint32) (string, error)
  • Converts a valid index back to LLL-NNN-LC.
• serial.CompleteCode(codeWithoutChecksum string) (string, uint32, error)
  • Takes LLL-NNN-L and returns the completed LLL-NNN-LC plus index.
• serial.RandomCode(isInUse ...func(uint32) bool) (string, uint32, error)
  • Generates a random valid LLL-NNN-LC code and its corresponding index.
  • If provided, the callback is used to skip indices already in use by the client.
• serial.RandomCodeWithOptions(options serial.RandomCodeOptions) (string, uint32, error)
  • Configurable variant with MaxAttempts, IsInUse, and custom RandomIndex source.

Example with options:

// See the runnable command at ./cmd/triplex-example/main.go

Commands

Runnable example command:

go run ./cmd/triplex-example

Using Makefile:

make run-example
make build-example
make test

Exported errors:

• serial.ErrInvalidFormat
• serial.ErrInvalidFormatNoChecksum
• serial.ErrInvalidLetters
• serial.ErrForbiddenLetterTriplet
• serial.ErrInvalidNumber
• serial.ErrNumberOutOfRange
• serial.ErrInvalidChecksum
• serial.ErrIndexOutOfRange
• serial.ErrRandomSourceFailed
• serial.ErrNoAvailableIndex

Testing

Run all tests:

go test ./...

License

This project is licensed under the MIT License. See LICENSE.