eu-licence-validator

A single source of truth for European licence-plate validation, delivered as native-feeling packages for Node.js / TypeScript, Python, Ruby, Java, and Go.

The validation logic is written once in Go and compiled to a tiny WebAssembly (WASI) binary with [TinyGo]. The binary is bundled inside each language package, so end users just call a normal function — they never know they are running Wasm. The native Go package imports the core logic directly (no Wasm) for maximum performance.

Language	Package	Distribution
TypeScript / JavaScript	`@truejacobg/eu-licence-validator`	npm / GitHub Packages
Python	`eu-licence-validator`	PyPI
Ruby	`eu-licence-validator`	RubyGems
Java	`com.github.truejacobg:eu-licence-validator`	Maven Central
Go	`github.com/TrueJacobG/eu-licence-validator/bindings/go`	Go module

The bindings are landing in Phase 3. Until the first public release, the packages above may not yet exist on the public registries.

Supported countries

Code	Country	Status
`PL`	Poland	✅
`DE`	Germany	✅
`FR`	France (SIV)	✅
`IT`	Italy	✅
`ES`	Spain	✅
`NL`	Netherlands	✅
`BE`	Belgium	✅
`PT`	Portugal	✅
`AT`	Austria	✅
`CH`	Switzerland	✅

More countries are tracked in CONTRIBUTING.md — contributions welcome.

Install

Replace the version placeholder with the published version once the first release is out.

TypeScript / JavaScript (Node, Bun, Deno, Vite, browsers)

npm install @truejacobg/eu-licence-validator

Python

pip install eu-licence-validator

Ruby

gem install eu-licence-validator

Java (Maven)

<dependency>
  <groupId>io.github.truejacobg</groupId>
  <artifactId>eu-licence-validator</artifactId>
  <version>VERSION</version>
</dependency>

go get github.com/TrueJacobG/eu-licence-validator/bindings/go

Usage

Every binding exposes the same API:

// TypeScript / JavaScript (Node, Bun, Deno, Vite, browsers)
import { init, isValid } from "@truejacobg/eu-licence-validator";

await init(); // initialize the Wasm runtime once
isValid("WPI 1234X", "PL"); // true  (sync after init)
isValid("AA-123-SS", "FR"); // false
isValid("B-AB 1234", "DE"); // true

// Types are included:
// function isValid(plate: string, countryCode: string): boolean
// function init(): Promise<void>

See examples/ for a runnable example in each language

How it works

flowchart TD
    logic["<b>core/validator.go</b><br/><i>Business logic — pure Go, no I/O</i><br/>regex per EU country"]
    core["<b>core/main.go</b><br/><i>WASI exports: alloc · validate · dealloc</i><br/>compiled by TinyGo → core.wasm"]

    logic --> core

    core -- "bundled core.wasm" --> JS["<b>TypeScript / JavaScript</b><br/>@truejacobg/eu-licence-validator"]
    core -- "bundled core.wasm" --> PY["<b>Python</b><br/>eu-licence-validator"]
    core -- "bundled core.wasm" --> RB["<b>Ruby</b><br/>eu-licence-validator"]
    core -- "bundled core.wasm" --> JV["<b>Java</b><br/>io.github.truejacobg:eu-licence-validator"]
    core -- "direct import (no Wasm)" --> GO["<b>Go</b><br/>github.com/TrueJacobG/eu-licence-validator/bindings/go"]

    click JS "https://www.npmjs.com/package/@truejacobg/eu-licence-validator" "npm — npmjs.com"
    click PY "https://pypi.org/project/eu-licence-validator/" "PyPI — pypi.org"
    click RB "https://rubygems.org/gems/eu-licence-validator" "RubyGems — rubygems.org"
    click JV "https://central.sonatype.com/artifact/io.github.truejacobg/eu-licence-validator" "Maven Central"
    click GO "https://pkg.go.dev/github.com/TrueJacobG/eu-licence-validator/bindings/go" "pkg.go.dev"

Development

Prerequisites

Tool	Version
Go	1.22+
TinyGo	latest
Node.js	20+
Python	3.10+
Ruby	3.0+
Java (Maven)	17+

Build & test

make build-wasm   # compile core -> core.wasm, copy into every binding
make test-all     # run tests across every language binding
make test-core    # Go core tests only
make clean        # remove generated wasm artifacts

The Go core can be developed and tested without TinyGo:

cd core && go test ./...

Repository layout

eu-licence-validator/
├── Makefile
├── test_cases.json          # unified test data for every language
├── core/                     # Go + WebAssembly core
├── bindings/                # js · python · ruby · java · go
├── examples/                 # one runnable example per language
└── .github/workflows/        # ci · dev-publish · release

Contributing

Please read CONTRIBUTING.md before opening a pull request. By participating you agree to abide by the Code of Conduct.