GTIN Gleam

A production-ready Gleam library for validating and generating GTIN (Global Trade Item Number) codes according to the GS1 specification. This library provides type-safe, idiomatic Gleam implementations with feature parity to the Elixir ex_gtin library.

Features

• GTIN Validation: Validate GTIN-8, GTIN-12, GTIN-13, and GTIN-14 codes
• Check Digit Generation: Generate complete GTINs with calculated check digits using the GS1 Modulo 10 algorithm
• GS1 Country Prefix Lookup: Identify the country of origin from GTIN codes (100+ countries supported)
• GTIN Normalization: Convert GTIN-13 codes to GTIN-14 format for logistics applications
• Type-Safe API: Leverage Gleam’s strong type system to prevent invalid GTINs
• Comprehensive Error Handling: Specific error types for different failure modes
• Well-Documented: Extensive documentation with practical examples for all functions

Installation

gleam add gtin

Quick Start

Validating a GTIN

import gtin

pub fn main() {
  // Validate a GTIN-13
  case gtin.validate("6291041500213") {
    Ok(format) -> io.println("Valid GTIN: " <> format_to_string(format))
    Error(err) -> io.println("Invalid GTIN: " <> error_to_string(err))
  }
}

Generating a GTIN with Check Digit

import gtin

pub fn main() {
  // Generate a GTIN-13 from 12 digits
  case gtin.generate("629104150021") {
    Ok(complete_gtin) -> io.println("Generated: " <> complete_gtin)
    Error(err) -> io.println("Error: " <> error_to_string(err))
  }
}

Looking Up Country of Origin

import gtin

pub fn main() {
  // Find the country for a GTIN
  case gtin.gs1_prefix_country("6291041500213") {
    Ok(country) -> io.println("Country: " <> country)
    Error(_) -> io.println("Country not found")
  }
}

Normalizing GTIN-13 to GTIN-14

import gtin

pub fn main() {
  // Convert GTIN-13 to GTIN-14
  case gtin.normalize("6291041500213") {
    Ok(gtin14) -> io.println("GTIN-14: " <> gtin14)
    Error(err) -> io.println("Error: " <> error_to_string(err))
  }
}

Supported GTIN Formats

Error Handling

The library uses Gleam’s Result type for explicit error handling:

pub type GtinError {
  InvalidLength(got: Int)
  InvalidCheckDigit
  InvalidCharacters
  NoGs1PrefixFound
  InvalidFormat
}

All functions return Result(value, GtinError), allowing you to handle errors gracefully:

import gtin
import result

pub fn validate_and_lookup(code: String) -> Result(String, GtinError) {
  use _format <- result.try(gtin.validate(code))
  gtin.gs1_prefix_country(code)
}

API Overview

Main Functions

• validate(code: String) -> Result(GtinFormat, GtinError) - Validate a GTIN code
• generate(code: String) -> Result(String, GtinError) - Generate a complete GTIN with check digit
• gs1_prefix_country(code: String) -> Result(String, GtinError) - Look up the country from a GTIN
• normalize(code: String) -> Result(String, GtinError) - Convert GTIN-13 to GTIN-14
• from_string(code: String) -> Result(Gtin, GtinError) - Create an opaque Gtin type
• to_string(gtin: Gtin) -> String - Extract the string value from a Gtin
• format(gtin: Gtin) -> GtinFormat - Get the format of a Gtin

Documentation

Full API documentation is available at hexdocs.pm/gtin.

Generate local documentation with:

gleam docs build

Development

Running Tests

gleam test

Building Documentation

gleam docs build

Format

Check the format

gleam format --check

Format

gleam format

Project Structure

gtin/
├── src/
│   ├── gtin.gleam              # Main public API
│   ├── gtin/
│   │   ├── validation.gleam    # Core validation logic
│   │   ├── check_digit.gleam   # Check digit calculation
│   │   ├── gs1_prefix.gleam    # GS1 country prefix lookup
│   │   └── internal/
│   │       └── utils.gleam     # Internal utility functions
└── test/
    ├── gtin_test.gleam         # Integration tests
    └── gtin/
        ├── validation_test.gleam
        ├── check_digit_test.gleam
        └── gs1_prefix_test.gleam

GS1 Specification Compliance

This library implements the GS1 Modulo 10 check digit algorithm as specified in the GS1 General Specifications. The check digit is calculated as follows:

1. Multiply each digit alternately by 3 and 1, starting from the rightmost digit
2. Sum all products
3. Calculate modulo 10 of the sum
4. If the result is 0, the check digit is 0; otherwise, the check digit is (10 - result)

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

References

• GS1 General Specifications
• ISO/IEC 15459 - Item identification

Sponsors

This project is sponsored by KickinEspresso

Versioning

We use SemVer for versioning.

Code of Conduct

Please refer to the Code of Conduct for details

Security

Please refer to the Security for details