A Kotlin Multiplatform library of strongly-typed, shareable data types — money and currency, locales, coordinates and telemetry, GeoJSON geometry, RFC-compliant identifiers, and arbitrary-precision math. It exists because KMP projects kept redefining the same types incompatibly; these are the shared ones, with no platform-specific API leaking through.

Targets: Android, JVM, iOS, JS, Wasm and Linux.

Published to Maven Central as io.github.aughtone:types.

// build.gradle.kts
implementation("io.github.aughtone:types:4.1.0")

Or through a version catalog:

# gradle/libs.versions.toml
[versions]
aughtone-types = "4.1.0"

[libraries]
aughtone-types = { module = "io.github.aughtone:types", version.ref = "aughtone-types" }

// build.gradle.kts
implementation(libs.aughtone.types)

[!IMPORTANT] v4.1.0 Breaking Changes: Outcome is aligned with kotlin.Result. dataOrNull, dataOrThrow and dataOrElse are renamed getOrNull, getOrThrow and getOrElse, with no deprecated aliases, and the callbacks handed to onFailure, fold, recover and getOrElse now receive the Throwable rather than the Outcome.Failure. Check the callbacks first: they still compile. A body reading it.message keeps building but now gets the nullable Throwable.message instead of the non-null Outcome.Failure.message, so an exception with no message renders the text null. Use it.message ?: it.toString(). isSuccess, isFailure, exceptionOrNull() and getOrDefault are new. Currency now compares by its ISO 4217 code alone, so a Set or map keyed by Currency may hold one entry where it held two, and Money amounts from different sources sort instead of throwing. Gigabyte is now GiB and Gigabit Gbit, keeping GB and Gb as alternatives, so rendering .symbol changes for those two. Also: localizedDisplayName returned English for every locale on the JS and Wasm targets in 3.4.0 and 4.0.0 and now returns real translations, so anything rendering locale names on web changes output.

v4.0.0 Breaking Changes: A breaking release. Outcome.Error and Locale.toLanguageTag() are removed; Money equality is now numeric so 5.1 equals 5.10; Distance and Speed throw instead of clamping to zero; GeoBoundingBox leaves the geometry hierarchy; GeoFeature.properties becomes JsonObject; invalid GeoJSON is now rejected; and UnitOfMeasure.findFirst refuses ambiguous symbols rather than guessing. Several change behaviour without a compile error — see the changelog before upgrading.

v3.4.0 Outcome.Error renamed: The failure case of Outcome is now Outcome.Failure, and the factory is Outcome.failure(...). The old names shipped as deprecated aliases in 3.4.0 and are removed in 4.0.0. Outcome$Error no longer exists as a class, so upgrading from 3.3.0 needs a clean and rebuild rather than a code change.

v3.3.0 Locale Display Names: Eleven locale displayName values are corrected — renamed countries (Czechia, North Macedonia, Türkiye), incomplete or abbreviated country names, and dated language exonyms (Farsi → Persian, Azeri → Azerbaijani). No API changed, but snapshot tests and cached UI strings holding the old names will need updating. See the changelog for the full table.

v3.2.0 Behavioral Fixes: Still worth reading if you are coming from 3.1.x — that release corrected long-standing bugs whose output or validation changes for existing code. UrlEncoder.encode is now true RFC 3986 percent-encoding — use encodeFormData for the previous application/x-www-form-urlencoded behavior. Url/Uri/Urn/GeoUri string output is now well-formed, and Urn/GeoUri construction now rejects invalid input. Critical arbitrary-precision fixes also land in BigInteger/BigDecimal division and BankersValue. See the changelog for the full list.

v3.0.0 Breaking Change: All GeoJSON geometry types (e.g., Point, Polygon) have been renamed with a Geo prefix (e.g., GeoPoint, GeoPolygon). Money now uses BigDecimal for its internal value to support sub-minor units, and Telemetry has moved to the quantitative package.

• 📖 Developer Guide: Building, testing, publishing.
• ⚖️ Architecture Decision Records: Why the library is shaped this way, and what was rejected.
• 📜 Changelog: History of changes and release notes.
• 🗺️ How the docs work: The whole system — knowledge in docs/knowledge/, work in Issues.

• Locales: Locale.current or localeFor("fr-CH").
• Money: Money(12.50, Currency.Usd) or Money(BigDecimal("1.23456"), Currency.Eur).
• Telemetry: Telemetry(coords, speed = 2.5.mps, azimuth = 90.degrees).

• Distance: 100.meters or 5.kilometers.
• Units: UnitOfMeasure.Litre.symbol ("L"), MetricPrefix.Kilo.

• Identifiers: Url("https://pkg.dev"), Urn("urn:uuid:...").
• Geo: GeoUri(45.5, -122.6) (RFC 5870).

• Arbitrary Precision: BigInteger("999999999999999999999999") or BigDecimal("123.456").
• Rounding: BigDecimal("1.255").setScale(2, RoundingMode.HALF_EVEN) -> 1.26.

• Outcome: runOutcome { parse(input) } returns Outcome.Success or Outcome.Failure; when over the two, or use fold, map, recover, getOrNull, getOrElse.
• Unlike kotlin.Result it is a sealed class, so Swift and JavaScript callers can read the failure as data. It otherwise reads as Result does — same members, same callback arguments — so it stands in for one where Result cannot cross the language boundary. See ADR-0004.

• GeoJSON: GeoPoint(45.5, -122.6, 100.0).toGeoJson() (RFC 7946).

Locale.displayName from the bundled resource data is always English. To show a locale's name in the end user's own language:

localeFor("bn")?.localizedDisplayName() // "bengali" for a French user, "ベンガル語" for a Japanese user

Rather than bundling a full translation matrix (~90 × 90 names) into every app, this delegates to the CLDR data each platform already ships — java.util.Locale (JVM/Android), NSLocale (Apple), Intl.DisplayNames (JS/Wasm). Bundled resource files aren't viable everywhere: browsers can't read files synchronously, and klibs can't deliver resources into an iOS app bundle.

This is the one place the library does not promise every platform the same answer, and the reason is measured rather than assumed. Of the locale names that the JVM, Apple and a browser can all produce, they disagree on 40.8% between Apple and the browser, and 9.6% between the JVM and Apple. Not near-misses: nl-BE is "Nederlands (België)" on two platforms and "Vlaams" on the third. That is CLDR version skew between operating systems and browsers, and delegation cannot remove it.

So the goal here is completeness — every locale gets a name in the reader's language — and not consistency, which would mean bundling the full translation matrix into every artifact. That costs roughly 107 KB gzipped on web and mobile to fix a problem those platforms do not have, since they already ship the data. Elsewhere in this library identical behaviour everywhere is the point; for display names the price was judged wrong, deliberately.

What that means for you:

• Never depend on the exact string. Compare locales, not their rendered names. A snapshot test or a cache key built on one will differ across targets.
• localizedDisplayName never returns null — the worst case is the English displayName. That fallback is silent, so use localizedDisplayNameOrNull when showing the wrong language matters more than showing nothing: it returns null where the platform has no data, instead of quietly handing back English.
• Coverage varies by platform and the holes differ. Each lacks 6–7% of pairs, but not the same ones — the JVM has no Inuktitut, Apple has some; Apple is thin on Igbo where the JVM is not.
• Linux has no system CLDR at all and returns the English fallback for everything.
• Browsers need Intl.DisplayNames, available since roughly 2020; older environments fall back to English.

See ADR-0005 for the decision and the measurements, ADR-0003 for the original delegation rationale, and issue #20 for gap-filling work.

To ensure mathematical precision and behavior consistency, this library employs rigorous Differential Parity Testing against standard baseline libraries:

• JVM Baseline: Parity verified against standard JDK types (java.math.BigInteger and java.math.BigDecimal).
• KMP Baseline: Parity verified against the official Multiplatform Ionspin BigNum library.

BigInteger and BigDecimal are benchmarked against the JDK types. Figures are relative to java.math, so 1.0x is parity and below 1.0x is faster than the JDK.

Small values are the exception, and deliberately so: the JDK keeps any BigDecimal under 19 digits in a long, so it answers toDouble on one by reading a field. There is no equivalent fast path here, and short-value operations run from several times to two orders of magnitude slower as a result. Two other costs are worth knowing: modPow is around 5x, lacking Montgomery reduction, and comparing two BigDecimal values of different scale is quick only when their magnitudes differ enough to settle it without aligning them — equal scales, the common case, beat the JDK.

Run them yourself with ./gradlew :benchmarks:benchmark. Ratios hold reasonably across machines; absolute throughput does not, so the benchmarks report both.