GL GTIN

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 gl_gtin

Quick Start

Validating a GTIN

import gl_gtin

pub fn main() {
  // Validate a GTIN-13
  case gl_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 gl_gtin

pub fn main() {
  // Generate a GTIN-13 from 12 digits
  case gl_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 gl_gtin

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

Normalizing GTIN-13 to GTIN-14

import gl_gtin

pub fn main() {
  // Convert GTIN-13 to GTIN-14
  case gl_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 gl_gtin
import result

pub fn validate_and_lookup(code: String) -> Result(String, GtinError) {
  use _format <- result.try(gl_gtin.validate(code))
  gl_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/gl_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

gl_gtin/
├── src/
│   ├── gl_gtin.gleam           # Main public API
│   ├── gl_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/
    ├── gl_gtin_test.gleam      # Integration tests
    └── gl_gtin/
        ├── validation_test.gleam
        ├── check_digit_test.gleam
        ├── gs1_prefix_test.gleam
        └── internal/
            └── utils_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