gl_gtin

A production-ready Gleam library for validating and generating GTIN (Global Trade Item Number) codes.

This library provides type-safe, idiomatic Gleam implementations of GTIN validation, check digit generation, GS1 prefix lookup, and GTIN normalization according to the GS1 specification.

Quick Start

import gl_gtin

// Validate a GTIN code
case gl_gtin.validate("6291041500213") {
  Ok(format) -> io.println("Valid GTIN-13")
  Error(err) -> io.println("Invalid GTIN")
}

// Generate a GTIN with check digit
case gl_gtin.generate("629104150021") {
  Ok(complete_gtin) -> io.println(complete_gtin)
  Error(_) -> io.println("Generation failed")
}

// Look up country from GS1 prefix
case gl_gtin.gs1_prefix_country("6291041500213") {
  Ok(country) -> io.println("Country: " <> country)
  Error(_) -> io.println("Prefix not found")
}

Types

Gtin

opaque </>

A validated GTIN code.

This is an opaque type that can only be constructed through validation. This ensures that any Gtin value in your code is guaranteed to be valid.

pub opaque type Gtin

GtinError

</>

Errors that can occur when working with GTIN codes.

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

Constructors

```
InvalidLength(got: Int)
```
Input has wrong number of digits. Includes the actual length provided.
```
InvalidCheckDigit
```
Check digit does not match the calculated value.
```
InvalidCharacters
```
Input contains non-numeric characters.
```
NoGs1PrefixFound
```
GS1 prefix not found in the database.
```
InvalidFormat
```
Operation not applicable to this GTIN format.

GtinFormat

</>

Supported GTIN formats based on digit count.

pub type GtinFormat {
  Gtin8
  Gtin12
  Gtin13
  Gtin14
}

Constructors

```
Gtin8
```
8-digit GTIN format, used for small packages outside North America
```
Gtin12
```
12-digit GTIN format (UPC-A), primarily used in North America
```
Gtin13
```
13-digit GTIN format (EAN-13), used internationally
```
Gtin14
```
14-digit GTIN format (ITF-14), used for trade items at various packaging levels

Values

format

</>

pub fn format(gtin: Gtin) -> GtinFormat

Get the format of a Gtin.

Examples

let assert Ok(gtin) = from_string("6291041500213")
format(gtin)
// -> Gtin13

from_string

</>

pub fn from_string(code: String) -> Result(Gtin, GtinError)

Create an opaque Gtin value from a validated string.

This function validates the input and wraps it in the opaque Gtin type. Only valid GTINs can be wrapped.

Examples

from_string("6291041500213")
// -> Ok(Gtin(...))

from_string("invalid")
// -> Error(InvalidCharacters)

generate

</>

pub fn generate(code: String) -> Result(String, GtinError)

Generate a complete GTIN with calculated check digit.

Takes an incomplete GTIN (7, 11, 12, or 13 digits) and calculates the check digit to produce a complete GTIN (8, 12, 13, or 14 digits respectively).

Examples

generate("629104150021")
// -> Ok("6291041500213")

generate("123456789012")
// -> Ok("1234567890128")

generate("invalid")
// -> Error(InvalidCharacters)

gs1_prefix_country

</>

pub fn gs1_prefix_country(
  code: String,
) -> Result(String, GtinError)

Look up the country of origin from a GTIN code’s GS1 prefix.

Checks the first 2-3 digits of the GTIN against the GS1 prefix database. Checks 3-digit prefixes first, then 2-digit prefixes.

Examples

gs1_prefix_country("6291041500213")
// -> Ok("GS1 Emirates")

gs1_prefix_country("012345678905")
// -> Ok("GS1 US")

gs1_prefix_country("999999999999")
// -> Error(NoGs1PrefixFound)

normalize

</>

pub fn normalize(code: String) -> Result(String, GtinError)

Convert a GTIN-13 to GTIN-14 format.

Prepends the indicator digit “1” and recalculates the check digit. Only works with GTIN-13 codes; other formats return an error.

Examples

normalize("6291041500213")
// -> Ok("16291041500214")

normalize("012345678905")
// -> Error(InvalidFormat)

to_string

</>

pub fn to_string(gtin: Gtin) -> String

Extract the string value from a Gtin.

Examples

let assert Ok(gtin) = from_string("6291041500213")
to_string(gtin)
// -> "6291041500213"

validate

</>

pub fn validate(code: String) -> Result(GtinFormat, GtinError)

Validate a GTIN code string.

Checks that the input is a valid GTIN (8, 12, 13, or 14 digits) with a correct check digit. Automatically trims leading and trailing whitespace before validation.

Examples

validate("6291041500213")
// -> Ok(Gtin13)

validate("012345678905")
// -> Ok(Gtin12)

validate("invalid")
// -> Error(InvalidCharacters)

validate("123")
// -> Error(InvalidLength(got: 3))