aughtone-types

Facilitates shared data types across projects, addressing duplication issues. Includes types for Location, Locale, Currency, and potentially Duration shortcuts for types like Distance.

#uri
#data

Suggest an edit

Android JVMJVMKotlin/NativeWasmJS

GitHub stars1

Authorsaughtone

Dependents3

LicenseApache License 2.0

Creation dateover 1 year ago

Last activity2 days ago

Latest release3.2.0 (2 days ago)

GitHub repository

Aughtone Types

[!IMPORTANT] v3.2.0 Behavioral Fixes: This release corrects 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.

This project follows a specialized documentation hierarchy.

📚 Documentation Sectors

📐 Architecture Guidelines: Engineering rules and design patterns.
🧠 Functional Specifications: Business logic and domain constraints.
🎨 Design & UI: Presentation layer and user stories.
📋 Acceptance Criteria: Success outcomes and verification.
📖 Developer Guide: Environment setup and onboarding.
⚖️ Architectural Decisions: Log of key technical choices.
📜 Changelog: History of changes and release notes.

📦 Core Data Types

Category	Type	Standard / Compliance	Description
Financial	`Money`	Banker's Rounding	Arbitrary-precision monetary values with `BigDecimal` storage.
	`Currency`	ISO 4217	Global currency definitions with scale factors.
Localization	`Locale`	BCP 47	Universal language, region, and script identifiers.
Quantitative	`Coordinates`	WGS84	Geodetic latitude and longitude degrees.
	`Distance`	SI (Meters)	Linear distance with accuracy support.
	`Speed`	SI (mps)	Rate of motion in meters per second.
	`Altitude`	SI (Meters)	Vertical distance above/below reference.
	`Azimuth`	Degrees	Compass bearing (0-360°).
	`Telemetry`	Unified Domain	Comprehensive model with coordinates, azimuth, speed, and altitude.
Geospatial	`GeoJson`	RFC 7946	`GeoPoint`, `GeoFeature`, and `GeoFeatureCollection` models.
SI Units	`UnitOfMeasure`	SI / Imperial	Definitions for meters, liters, bytes, etc.
	`MetricPrefix`	SI Prefixes	Scaling factors from `Quetta` to `Quecto`.
Identifiers	`Url`	RFC 3986	Uniform Resource Locators (Web).
	`Urn`	RFC 8141	Uniform Resource Names (Persistent IDs).
	`GeoUri`	RFC 5870	Geographic 'geo' URI scheme.
Mathematics	`BigInteger`	Pure Kotlin	Arbitrary-precision integer math support.
	`BigDecimal`	Pure Kotlin	Arbitrary-precision decimal math with rounding support.
Utilities	`BitSet`	Multiplatform	Space-efficient storage for bit-level flags.
	`BankersValue`	Half-to-Even	Precision math with bias-free rounding rules.

🚀 Quick Usage

🌎 Domain Fundamentals

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).

📏 Quantitative & SI

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

🔗 RFC Compliant Identifiers

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

🔢 Precision Math

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

🗺️ GeoJSON

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

🌐 Localized Display Names

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.

Tradeoffs to be aware of:

Names come from the OS, so wording may differ slightly between platforms and OS versions (e.g. "Chinese (Simplified)" vs "Simplified Chinese").
Linux targets have no system CLDR data — they always return the English fallback.
Browsers need Intl.DisplayNames (widely available since ~2020); older environments fall back to English.
The function never returns null — the worst case is the English displayName.

See ADR 0003 for the full rationale, and GAPS.md for the deferred bundled-tables alternative.

🧪 Verification & Parity

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.

🤖 AI-Assisted Development

This library includes embedded, machine-readable "skills" to help AI assistants understand its APIs and best practices.

Discovery: Look for META-INF/ai-skills/*.ai-skill.md

🪄 Magic Prompt for AI Assistants

If you are using an AI assistant (like Claude, Gemini, or ChatGPT) to write code with this library, paste this prompt first:

"Scan all project dependencies for AI Skill files in META-INF/ai-skills/ with the prefix io.github.aughtone. Use these to understand the API patterns, types, and governance for this library. If they are not found in the local classpath, refer to https://github.com/aughtone/aughtone-types for the source definitions."