@quenty/metricutils 2.4.3 → 2.5.0

package/CHANGELOG.md

@@ -3,111 +3,73 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [2.4.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.4.2...@quenty/metricutils@2.4.3) (2026-01-12)
+# [2.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.4.4...@quenty/metricutils@2.5.0) (2026-11-11)
 
+### Features
 
-### Bug Fixes
+- **metricutils:** add MetricUnit, typed measurements with parsing and localized formatting ([#859](https://github.com/Quenty/NevermoreEngine/issues/859)) ([2ba1298](https://github.com/Quenty/NevermoreEngine/commit/2ba1298f7f226c4e3e04eb3e9bc6f48a1c1a9172))
 
-* Fix dependency installation process for pnpm ([9651b09](https://github.com/Quenty/NevermoreEngine/commit/9651b09af34f252ef3f9c7c539793cc878dd8cba))
+## [2.4.4](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.4.3...@quenty/metricutils@2.4.4) (2026-05-30)
 
+**Note:** Version bump only for package @quenty/metricutils
 
+## [2.4.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.4.2...@quenty/metricutils@2.4.3) (2026-01-12)
 
+### Bug Fixes
 
+- Fix dependency installation process for pnpm ([9651b09](https://github.com/Quenty/NevermoreEngine/commit/9651b09af34f252ef3f9c7c539793cc878dd8cba))
 
 ## [2.4.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.4.1...@quenty/metricutils@2.4.2) (2026-01-10)
 
 **Note:** Version bump only for package @quenty/metricutils
 
-
-
-
-
 ## [2.4.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.4.0...@quenty/metricutils@2.4.1) (2025-03-21)
 
 **Note:** Version bump only for package @quenty/metricutils
 
-
-
-
-
 # [2.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.3.0...@quenty/metricutils@2.4.0) (2024-11-12)
 
-
 ### Features
 
-* Add MetricUtils.studsPerSecondToMetersPerSecond(studsPerSecond) ([7e2165f](https://github.com/Quenty/NevermoreEngine/commit/7e2165fa6c028d8cea2f0c59d65f330b23ab1e2c))
-
-
-
-
+- Add MetricUtils.studsPerSecondToMetersPerSecond(studsPerSecond) ([7e2165f](https://github.com/Quenty/NevermoreEngine/commit/7e2165fa6c028d8cea2f0c59d65f330b23ab1e2c))
 
 # [2.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.2.0...@quenty/metricutils@2.3.0) (2024-05-09)
 
-
 ### Bug Fixes
 
-* Fix .package-lock.json replicating in packages ([75d0efe](https://github.com/Quenty/NevermoreEngine/commit/75d0efeef239f221d93352af71a5b3e930ec23c5))
-
-
-
-
+- Fix .package-lock.json replicating in packages ([75d0efe](https://github.com/Quenty/NevermoreEngine/commit/75d0efeef239f221d93352af71a5b3e930ec23c5))
 
 # [2.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.1.0...@quenty/metricutils@2.2.0) (2022-03-27)
 
 **Note:** Version bump only for package @quenty/metricutils
 
-
-
-
-
 # [2.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.0.1...@quenty/metricutils@2.1.0) (2022-01-03)
 
-
 ### Features
 
-* Add MetricUtils.kphToStudsPerSecond(kph) and MetricUtils.mphToStudsPerSecond(mph) ([23c4c96](https://github.com/Quenty/NevermoreEngine/commit/23c4c96158a582b30f13d58ebb8b9f8139aca130))
-* Add MetricUtils.studsPerSecondToKph(studsPerSecond) and MetricUtils.studsPerSecondToMph(studsPerSecond) ([a833467](https://github.com/Quenty/NevermoreEngine/commit/a833467c4f970604f9c32aee8effe064cf884c90))
-
-
-
-
+- Add MetricUtils.kphToStudsPerSecond(kph) and MetricUtils.mphToStudsPerSecond(mph) ([23c4c96](https://github.com/Quenty/NevermoreEngine/commit/23c4c96158a582b30f13d58ebb8b9f8139aca130))
+- Add MetricUtils.studsPerSecondToKph(studsPerSecond) and MetricUtils.studsPerSecondToMph(studsPerSecond) ([a833467](https://github.com/Quenty/NevermoreEngine/commit/a833467c4f970604f9c32aee8effe064cf884c90))
 
 ## [2.0.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@2.0.0...@quenty/metricutils@2.0.1) (2021-12-30)
 
 **Note:** Version bump only for package @quenty/metricutils
 
-
-
-
-
 # [2.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/metricutils@1.2.0...@quenty/metricutils@2.0.0) (2021-09-05)
 
-
 ### Bug Fixes
 
-* Remove peer dependencies. This is because lerna doesn't really support peer dependencies being linked and getting a new version on build, which is unfortunate. ([5f5aeee](https://github.com/Quenty/NevermoreEngine/commit/5f5aeeea8de9975435309e53679f0ef7064f9dd0))
-
-
-
-
+- Remove peer dependencies. This is because lerna doesn't really support peer dependencies being linked and getting a new version on build, which is unfortunate. ([5f5aeee](https://github.com/Quenty/NevermoreEngine/commit/5f5aeeea8de9975435309e53679f0ef7064f9dd0))
 
 # 1.2.0 (2021-07-31)
 
-
 ### Bug Fixes
 
-* Add CI and CD ([47513e9](https://github.com/Quenty/NevermoreEngine/commit/47513e9b568162707534af132396dd8756947dd3))
-* Adjust CI badge to show automatic build and release state ([5a55d3f](https://github.com/Quenty/NevermoreEngine/commit/5a55d3f19bf8d66a760d67da9b56ed47fab74656))
-* Fix selene linting ([45fc074](https://github.com/Quenty/NevermoreEngine/commit/45fc07489ee59127ac6582689f19a0e87c1e5b5a))
-
-
+- Add CI and CD ([47513e9](https://github.com/Quenty/NevermoreEngine/commit/47513e9b568162707534af132396dd8756947dd3))
+- Adjust CI badge to show automatic build and release state ([5a55d3f](https://github.com/Quenty/NevermoreEngine/commit/5a55d3f19bf8d66a760d67da9b56ed47fab74656))
+- Fix selene linting ([45fc074](https://github.com/Quenty/NevermoreEngine/commit/45fc07489ee59127ac6582689f19a0e87c1e5b5a))
 
 ## 1.0.2 (2021-07-25)
 
-
-
 ## 1.0.1 (2021-07-25)
 
-
-
 # 1.0.0 (2021-07-24)

package/README.md

@@ -11,11 +11,89 @@
   </a>
 </div>
 
-Provides ways to convert to or from metric
+Typed, immutable measurements in metric, US customary and Roblox units, with localized formatting
 
-<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/MetricUtils">View docs →</a></div>
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/MetricUnit">View docs →</a></div>
 
 ## Installation
 ```
 npm install @quenty/metricutils --save
 ```
+
+## Usage
+
+A `MetricUnit` knows what it measures. Arithmetic checks dimensions, and any unit reads back with `:In`.
+
+```lua
+local MetricUnit = require("MetricUnit")
+
+local speed = MetricUnit.kilometers(36) / MetricUnit.hours(1)
+speed:In("meterPerSecond") --> 10
+speed:In("milePerHour") --> 22.369
+speed:GetKind() --> "speed"
+
+local energy = MetricUnit.new(2, "kilowatt") * MetricUnit.hours(3)
+energy:In("kilowattHour") --> 6
+
+MetricUnit.kilometers(1) + MetricUnit.seconds(1) --> error: cannot add length and time
+```
+
+Roblox values come in through studs, and angles are their own dimension:
+
+```lua
+MetricUnit.fromStudVelocity(part.AssemblyLinearVelocity):In("kilometerPerHour")
+MetricUnit.studs(100):In("meter") --> 28, at Roblox's 28 cm stud
+CFrame.Angles(0, MetricUnit.degrees(90):In("radian"), 0)
+```
+
+Temperatures and points in time are absolute or a difference, so the arithmetic stays honest:
+
+```lua
+(MetricUnit.celsius(15) + MetricUnit.difference(12, "celsius")):In("celsius") --> 27
+MetricUnit.celsius(15) * 2 --> error: cannot multiply an absolute temperature
+
+local worldStart = MetricUnit.instant(0)
+local now = worldStart + MetricUnit.years(250)
+(now - worldStart):In("year") --> 250
+```
+
+Format for players in their language. A value shows itself in the system of the unit it was made from; convert it to show another. A locale never chooses the system:
+
+```lua
+MetricUnit.format(MetricUnit.meters(2500)) --> 2.5 km
+MetricUnit.format(MetricUnit.meters(1234.5), { unit = "meter", locale = "de-de" }) --> 1 234,5 m
+MetricUnit.format(MetricUnit.kilometers(5):ToUSCustomary()) --> 3.107 mi
+MetricUnit.format(MetricUnit.new(2, "liter"):ToImperial()) --> 3.52 imp pt
+MetricUnit.format(MetricUnit.minutes(90), { locale = "es-es" }) --> 1 hora, 30 minutos
+MetricUnit.format(MetricUnit.minutes(90), { durationStyle = "clock" }) --> 1:30:00
+```
+
+`MetricUnitTranslator` streams unit names and symbols in 17 languages, one per player, from Unicode CLDR data:
+
+```lua
+local translator = serviceBag:GetService(require("MetricUnitTranslator"))
+MetricUnit.format(MetricUnit.kilometers(5), { translator = translator }) --> 5 км in Russian, 5公里 in Chinese
+```
+
+The translations derive from Unicode CLDR; see the notice in `src/Shared/Localization/MetricUnitTranslator/init.lua`.
+
+And read what players type:
+
+```lua
+MetricUnit.parse("1h30m") --> 90 minutes
+MetricUnit.parse("5 m", "time") --> 5 minutes, since a time was expected
+local value, err = MetricUnit.parse(textBox.Text, "length")
+```
+
+Units belong to systems: metric, US customary, British imperial and Roblox are built in, and a game can declare its own, such as studs at another scale:
+
+```lua
+local MINI = MetricUnitSystems.roblox({ name = "robloxMini", metersPerStud = 0.028 })
+local height = MINI:New(5, "stud")
+height:In("meter") --> 0.14
+MetricUnit.format(height) --> 5 studs
+MetricUnitSystems.IMPERIAL:Format(height) --> 5.512 in
+MINI:Parse("5 studs", "length")
+```
+
+`MetricUtils` keeps its plain-number stud conversions at 3.57 studs to the metre, such as `MetricUtils.studsToMeters(357)`.

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 128882159252211,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "@quenty/metricutils",
-  "version": "2.4.3",
-  "description": "Provides ways to convert to or from metric",
+  "version": "2.5.0",
+  "description": "Typed, immutable measurements in metric, US customary and Roblox stud units (time, length, mass, memory, temperature and derived SI units) with localized formatting",
   "keywords": [
     "Roblox",
     "Nevermore",
     "Lua",
-    "Metric"
+    "Metric",
+    "Units",
+    "SI",
+    "Measurement",
+    "Conversion",
+    "Localization",
+    "Imperial",
+    "Studs"
   ],
   "bugs": {
     "url": "https://github.com/Quenty/NevermoreEngine/issues"
@@ -27,8 +34,19 @@
   "contributors": [
     "Quenty"
   ],
+  "dependencies": {
+    "@quenty/clienttranslator": "14.55.1",
+    "@quenty/loader": "10.11.3",
+    "@quenty/nevermore-test-runner": "1.6.3",
+    "@quenty/rx": "13.35.1",
+    "@quenty/time": "2.8.1",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
+  },
+  "devDependencies": {
+    "@quenty/spring": "10.12.3"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "55f4a7407de7247aceea574de4d2f57dab70cb91"
+  "gitHead": "014669a5d6cef7bc42ab007a372d2b2e28352d6e"
 }