Punycoder

A Dart implementation of the Punycode (RFC 3492) encoding algorithm used for Internationalized Domain Names in Applications (IDNA).

Overview

This package provides a robust and efficient way to convert Unicode strings, such as internationalized domain names or email addresses, into their ASCII-Compatible Encoding (ACE) representation according to the Punycode specification (RFC 3492), and back again.

Punycode allows representing Unicode characters using only the limited ASCII character subset (letters, digits, and hyphens) allowed in components of domain names. This is essential for the IDNA standard, enabling the use of international characters in domain names while maintaining compatibility with the existing DNS infrastructure. ACE labels generated by IDNA typically start with the prefix xn--.

Features

• RFC 3492 Compliant: Implements the Punycode encoding and decoding algorithms as specified in the standard.
• IDNA Friendly: Provides convenient ways of converting full domain names or email addresses, automatically handling the xn-- prefix and processing only the necessary parts of the string.
• Idiomatic Dart: This package implements the Converter<S, T> interface defined in dart:convert to make working with Punycode feel easy and familiar.
• Efficient and Tested: Based on a port of the well-regarded Punycode.js library, including tests based on official RFC examples.

Getting Started

Add the package to your pubspec.yaml:

dependencies:
  punycoder: ^0.2.0

Then, import the library in your Dart code:

import 'package:punycoder/punycoder.dart';

Usage

import 'package:punycoder/punycoder.dart';

void main() {
  // Designed to be used with domains and emails which have special rules
  const domainCodec = PunycodeCodec();
  // Designed to work with simple strings
  const simpleCodec = PunycodeCodec.simple();

  final encodedString = simpleCodec.encode('münchen');
  final encodedDomain = domainCodec.encode('münchen.com');
  final encodedEmail = domainCodec.encode('münchen@münchen.com');

  stdout.writeln(encodedString); // Output: mnchen-3ya
  // Uses the correct prefix for the domain
  stdout.writeln(encodedDomain); // Output: xn--mnchen-3ya.com
  // Only the domain should be encoded
  stdout.writeln(encodedEmail); // Output: münchen@xn--mnchen-3ya.com

  final decodedString = simpleCodec.decode('mnchen-3ya');
  final decodecDomain = domainCodec.decode('xn--mnchen-3ya.com');
  final decodedEmail = domainCodec.decode('münchen@xn--mnchen-3ya.com');

  stdout.writeln(decodedString); // Output: münchen
  stdout.writeln(decodecDomain); // Output: münchen.com
  stdout.writeln(decodedEmail); // Output: münchen@münchen.com
}