Sealed World

A pure Dart, fully tested and ISO-driven ecosystem for the world's data in the form of compile-time, tree-shakable constant classes with a sealed origin.

Tip

Flutter packages use world prefix, Dart packages use sealed prefix for core functionality and l10n prefix for localization maps.

Package	SDK	Stand-alone	Description	Pub
world_countries	Flutter	No	Pickers and APIs for typed localizations
world_flags	Flutter	No	Declarative flags built with CustomPainters
sealed_countries	Dart	No	Countries in the form of sealed classes
sealed_currencies	Dart	No	Currencies in the form of sealed classes
sealed_languages	Dart	Partially1	Languages in the form of sealed classes
l10n_countries	Dart	Yes	Country names localization maps
l10n_currencies	Dart	Yes	Currency names localization maps
l10n_languages	Dart	Yes	Language names localization maps

This ecosystem follows a hierarchical structure with optional localization support. At the foundation are languages and scripts, providing core functionality across all packages. Building upon this, currencies extend the system, followed by countries. Each core package has an optional l10n companion that provides localization maps. The countries package serves as a bridge to Flutter, enabling the rendering of country flags, which the world_countries package uses to create UI components like country pickers with localized names and visual elements.

graph TB

    %% Sealed packages
    sealed_languages["<span title='Sealed Languages Package'>sealed_languages</span>"]
    sealed_currencies["<span title='Sealed Currencies Package'>sealed_currencies</span>"]
    sealed_countries["<span title='Sealed Countries Package'>sealed_countries</span>"]

    %% l10n packages
    l10n_languages["<span title='L10N Languages Package'>l10n_languages</span>"]
    l10n_currencies["<span title='L10N Currencies Package'>l10n_currencies</span>"]
    l10n_countries["<span title='L10N Countries Package'>l10n_countries</span>"]

    %% World packages
    world_flags["<span title='World Flags Package'>world_flags</span>"]
    world_countries["<span title='World Countries Package'>world_countries</span>"]

    %% Main chain, labeled arrow for Flutter
    sealed_languages --> sealed_currencies --> sealed_countries -->| ― Flutter ― | world_flags --> world_countries

    %% l10n packages pointing to each sealed package
    l10n_languages --> sealed_languages
    l10n_currencies --> sealed_currencies
    l10n_countries --> sealed_countries

    %% Styles for sealed (light fill) and world packages (darker border)
    style sealed_languages fill:#aec7e8,stroke:#aec7e8,stroke-width:2px,fill-opacity:0.2,rx:10,ry:10
    style sealed_currencies fill:#aec7e8,stroke:#aec7e8,stroke-width:2px,fill-opacity:0.2,rx:10,ry:10
    style sealed_countries fill:#aec7e8,stroke:#aec7e8,stroke-width:2px,fill-opacity:0.2,rx:10,ry:10
    style world_flags fill:#aec7e8,stroke:#0050B9,stroke-width:2px,fill-opacity:0.5,rx:10,ry:10
    style world_countries fill:#aec7e8,stroke:#0050B9,stroke-width:2px,fill-opacity:0.5,rx:10,ry:10

    %% Styles for l10n packages (turquoise fill)
    style l10n_languages fill:#40DBE0BE,stroke:#aec7e8,stroke-width:2px,fill-opacity:0.2,rx:10,ry:10
    style l10n_currencies fill:#40DBE0BE,stroke:#aec7e8,stroke-width:2px,fill-opacity:0.2,rx:10,ry:10
    style l10n_countries fill:#40DBE0BE,stroke:#aec7e8,stroke-width:2px,fill-opacity:0.2,rx:10,ry:10

    %% Attempt to remove the label background only on the "Flutter" arrow (link index 2).
    linkStyle 2 stroke:#0050B9,stroke-width:2px,color:#000,fill:none

    %% Clickable links
    click sealed_languages "https://github.com/tsinis/sealed_world/tree/main/packages/sealed_languages"
    click sealed_currencies "https://github.com/tsinis/sealed_world/tree/main/packages/sealed_currencies"
    click sealed_countries "https://github.com/tsinis/sealed_world/tree/main/packages/sealed_countries"
    click l10n_languages "https://github.com/tsinis/sealed_world/tree/main/packages/l10n_languages"
    click l10n_currencies "https://github.com/tsinis/sealed_world/tree/main/packages/l10n_currencies"
    click l10n_countries "https://github.com/tsinis/sealed_world/tree/main/packages/l10n_countries"
    click world_flags "https://github.com/tsinis/sealed_world/tree/main/packages/world_flags"
    click world_countries "https://github.com/tsinis/sealed_world/tree/main/packages/world_countries"

Loading

Versioning and Release Policy

This section explains how the ecosystem handles SDK pinning, semantic versioning, and release cadence, and why this approach benefits users and contributors.

SDK Compatibility and Pinning

• Pinning to the Dart version bundled with Flutter stable ensures local developer environments match CI, minimizing SDK mismatches and hard-to-reproduce issues. The Flutter SDK archive lists each Flutter stable release together with its bundled Dart version Flutter SDK archive.
• Production packages target Dart stable rather than beta/dev, in line with Dart's guidance to use stable for building and deploying apps Get the Dart SDK.
• Formatter and workspace changes introduced around Dart 3.7/3.8 can create large diffs when mixing pre/post language versions. Dart 3.8 includes a rewritten/updated formatter behavior; formatting changes apply when the package opts into the newer language version Announcing Dart 3.8, Breaking changes (formatter behavior >=3.8).

Semantic Versioning

• Semantic Versioning is followed: MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes Semantic Versioning.
• Dart's pub ecosystem applies SemVer for resolution and documents conventions including pre-1.0 handling and "next breaking" logic Package versioning.

Release Cadence

• Major releases: approximately once per year, potentially including breaking changes; aligned after Flutter/Dart stable cycles to reduce churn Semantic Versioning.
• Minor releases: about once per month for feature additions (especially for Flutter-facing packages), without breaking changes Package versioning.
• Patch releases: as needed for fixes and docs, with no API changes Package versioning.

Deprecation-First Policy

• Most breaking changes are introduced via deprecation first, with warnings and migration time provided before removal. This mirrors Dart and Flutter practices of listing deprecations alongside breaking changes and offering migration guides Breaking changes and deprecations (Dart), Flutter breaking changes and migration guides.
• Deprecated APIs are removed only after reaching end of life in a subsequent stable release cycle, consistent with Flutter's deprecation policy and examples across releases (e.g., removals after 3.7, 3.13, 3.19).
• Migration guidance is linked in release notes for major removals, reducing friction and helping teams adopt changes in predictable windows Flutter breaking changes and migration guides.

Rationale

• Aligning with Flutter stable's Dart ensures consistent environments across CI and contributors, reducing surprise failures and easing support Flutter SDK archive.

Benchmark & regression verification system

This package includes an automated benchmark system that runs on every release to detect performance regressions. Each version produces immutable JSON artifacts containing build metadata (APK size, toolchain versions, Android configuration) and runtime metrics (startup time, frame performance, memory and CPU usage, etc.).

Tip

These artifacts are attached to GitHub Releases and committed to the repository, enabling historical comparison and transparent performance tracking across versions. The benchmark flow uses low-end physical ARM64 Android devices with Flashlight + Maestro for reproducible, device-driven testing.

To run benchmarks locally or learn more about the system, see the benchmarks documentation. All benchmark data is immutable and versioned, ensuring full auditability and regression traceability.

Footnotes

1. While sealed_languages technically depends on l10n_languages for localization, this is not part of its core functionality. The package primarily serves as the backbone for all sealed_* and world_* packages by providing typed locale classes and extensions that power localization maps across the entire ecosystem. ↩