@budiauktioner/buildi-primitives 0.1.1 → 0.2.0

package/BREAKING_CHANGES.md

@@ -0,0 +1,81 @@
+# Breaking changes
+
+Backwards-incompatible changes between versions of `@budiauktioner/buildi-primitives`.
+Newest version on top. Non-breaking additions belong in [CHANGELOG.md](CHANGELOG.md),
+not here.
+
+## Conventions
+
+- One `## Breaking changes <previous-version> - <new-version>` heading per release
+  that contains breaking changes (e.g. `## Breaking changes 0.1.0 - 0.2.0`). The
+  range makes it explicit which upgrade hop the entries apply to.
+- One `### <short title>` heading per breaking change inside that version. Use as
+  many sub-sections per change as you need: **What changed**, **Why**,
+  **Migration**, **Examples**, etc.
+- Order versions from newest to oldest.
+
+## Breaking changes 0.1.1 - 0.2.0
+
+### `Country` membership flags renamed to match the .NET port
+
+**Area:** `@budiauktioner/buildi-primitives/geography`
+
+**What changed**
+
+Two `Country` getters were renamed so that all five regional membership flags
+follow the same naming as `Buildi.Primitives`:
+
+| Before            | After               |
+| ----------------- | ------------------- |
+| `isEuropeanUnion` | `isInEuropeanUnion` |
+| `isNordic`        | `isInNordics`       |
+
+`isInEea`, `isInSchengen`, and `isInSepa` are unchanged.
+
+**Why**
+
+The two renamed getters were the only members of the group that diverged from
+the .NET names, which made the set inconsistent both with the behavioural spec
+and internally.
+
+**Migration**
+
+Rename the call sites. The semantics are identical.
+
+```ts
+// Before
+if (country.isEuropeanUnion && country.isNordic) { ... }
+
+// After
+if (country.isInEuropeanUnion && country.isInNordics) { ... }
+```
+
+### `ScreenResolution.totalPixels` now returns `bigint`
+
+**Area:** `@budiauktioner/buildi-primitives/product`
+
+**What changed**
+
+`ScreenResolution.totalPixels` changed from `number` to `bigint`.
+
+**Why**
+
+The exact width-by-height product can exceed JavaScript's safe integer range.
+Using `bigint` preserves the full .NET `Int64` value and keeps resolution
+comparisons exact.
+
+**Migration**
+
+Use bigint literals and bigint arithmetic when comparing or calculating with
+`totalPixels`. Convert explicitly only when a downstream API requires a
+`number` and precision loss is acceptable.
+
+```ts
+// Before
+const isLarge = resolution.totalPixels > 8_000_000;
+const doubled = resolution.totalPixels * 2;
+
+// After
+const isLarge = resolution.totalPixels > 8_000_000n;
+const doubled = resolution.totalPixels * 2n;
+```

package/CHANGELOG.md

@@ -4,7 +4,64 @@ All notable changes to the TypeScript port of `Buildi.Primitives` will be
 documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.2.0] - 2026-08-07
+
+### Added
+
+- The `Measurement` namespace, available from the new
+  `@budiauktioner/buildi-primitives/measurement` subpath: 19 dimensions, 133
+  units, five standalone types, plus `TemperatureDelta`. The dimensions are
+  `Area`, `DataSize`, `ElectricCharge`, `ElectricCurrent`, `Energy`,
+  `FlowRate`, `Frequency`, `Length`, `Luminance`, `LuminousFlux`, `Power`,
+  `Pressure`, `RotationalSpeed`, `Speed`, `Temperature`, `Torque`, `Voltage`,
+  `Volume` and `Weight`. Each supports parsing from any of its units, exact
+  conversion between them, `toNaturalString()` auto-scaling, arithmetic, a
+  `mask*` helper, and text scanning through the matching `TextScanResult`
+  accessor. The five types with no unit table are `Count`, `Percentage`,
+  `SoundLevel`, `Year` and `YearMonth`.
+- Internal foundation for the rest of the namespace: exact base-10 arithmetic
+  matching .NET `System.Decimal`, the measurement string splitter, and the
+  shared unit-index and quantity base classes.
+- The `Vehicle` namespace, available from the new
+  `@budiauktioner/buildi-primitives/vehicle` subpath. All 29 types: the lookup
+  types `FuelType`, `BodyType`, `TransmissionType`, `DrivetrainType`,
+  `SuspensionType`, `TireType`, `TrackType`, `EuroEmissionClass`,
+  `FuelConsumptionNorm`, `BoatHullMaterial`, `BoatCeDesignCategory`,
+  `SwedishVehicleType`, `SwedishVehicleStatus`, `SwedishEcoVehicleClassification`
+  and `SwedishDrivingLicenseCategory`; the measurements `EngineDisplacement`,
+  `EnginePower`, `OdometerReading`, `OperatingHours`, `FuelConsumption`,
+  `EnergyConsumption` and `EmissionRate`; and the identifiers and dimensions
+  `VehicleIdentificationNumber`, `SwedishVehicleRegistrationNumber`,
+  `TireDimension`, `WheelRimDimension`, `BoltPattern`, `EuTypeApprovalNumber`
+  and `EuVehicleCategory`.
+- Thirteen new `TextScanResult` accessors for the vehicle types the .NET
+  `TextScanner` runs, including `vehicleRegistrationNumbers`,
+  `vehicleIdentificationNumbers`, `tireDimensions` and `enginePowers`.
+- The `Product` namespace, available from the new
+  `@budiauktioner/buildi-primitives/product` subpath, which completes the port
+  of all thirteen .NET namespaces. All 36 types: the lookup types
+  `AspectRatio`, `BatteryChemistry`, `ClothingFit`, `ClothingGender`,
+  `ClothingSeason`, `DisplayPanelType`, `ElectricalPhase`,
+  `EuEnergyEfficiencyClass`, `PowerSource`, `Refrigerant` and
+  `StorageMediaType`; the capacities `StorageCapacity`, `RamCapacity`,
+  `ProcessorSpeed` and `BatteryCapacity`; the GTIN family `Gtin`, `Gtin8`,
+  `Gtin12`, `Gtin13` and `Gtin14`; the sizes `ClothingSize`,
+  `AdultClothingSize`, `ChildClothingSize`, `ShoeSize`, `AdultShoeSize` and
+  `ChildShoeSize`; and `Color`, `CameraResolution`, `ScreenResolution`,
+  `ScreenSize`, `IpRating`, `HsCode`, `GoogleProductCategory`,
+  `OperatingSystemInfo`, `OperatingSystemName` and `OperatingSystemVersion`.
+- Ten new `TextScanResult` accessors for the product types the .NET
+  `TextScanner` runs: `gtin8s`, `gtin12s`, `gtin13s`, `gtin14s`, `ipRatings`,
+  `electricalPhases`, `refrigerants`, `colors`, `screenResolutions` and
+  `screenSizes`.
+
+### Changed
+
+- Version 0.2.0 expands `defaultTextScanner` with the Measurement, Vehicle, and
+  Product scanners. Existing callers that need the 0.1.x scan scope can migrate
+  by passing `excludeCategories` for `TextCandidateCategory.Measurement`,
+  `.Vehicle`, and `.Product`; callers that want an explicit allowlist can use
+  `includeCategories` instead.
 
 ## [0.1.1] - 2026-08-07
 

package/PARITY.md

@@ -0,0 +1,202 @@
+# .NET parity
+
+`@budiauktioner/buildi-primitives` is a port of the .NET package
+[`Buildi.Primitives`](https://github.com/BudiAuktioner/Buildi.Primitives), which
+is the behavioural specification for both languages. This document records
+exactly how much of that surface is implemented here.
+
+|                   |                            |
+| ----------------- | -------------------------- |
+| .NET baseline     | `Buildi.Primitives` 0.21.0 |
+| This package      | `0.2.0`                    |
+| Namespaces ported | 13 of 13                   |
+| Types ported      | 200 of 200                 |
+
+Type counts follow the catalog in the .NET README — the value-object types a
+consumer works with directly, excluding extension-method containers and internal
+helpers.
+
+Parity is enforced by [`test/parity/dotnet-parity.test.ts`](test/parity/dotnet-parity.test.ts),
+which asserts that every .NET public type, masking function, `validate()`
+implementation, `findCandidatesInText()` implementation, and `TextScanResult`
+accessor in the ported namespaces exists here. Update that test in the same
+commit that changes the .NET baseline.
+
+## Namespace coverage
+
+| .NET namespace | Status      | Notes                                                                 |
+| -------------- | ----------- | --------------------------------------------------------------------- |
+| `Organization` | Complete    | 10 types                                                              |
+| `Banking`      | Complete    | 10 types                                                              |
+| `Person`       | Complete    | 6 types                                                               |
+| `Geography`    | Complete    | 7 types                                                               |
+| `Finance`      | Complete    | 3 types, plus `ExchangeRates`                                         |
+| `Contact`      | Complete    | Including all 31 country address / zip-code pairs                     |
+| `Web`          | Complete    | 2 types                                                               |
+| `Property`     | Complete    | 2 types                                                               |
+| `Validation`   | Complete    | Shared `ValidationResult` infrastructure                              |
+| `TextScanning` | Complete    | Scanner, candidates, overlap resolution, typed accessors              |
+| `Measurement`  | Full parity | 19 dimensions, 133 units, 5 standalone types, plus `TemperatureDelta` |
+| `Vehicle`      | Full parity | 29 types, plus the `SwedishDrivingLicenseVehicleGroup` enum           |
+| `Product`      | Full parity | 36 types, plus 6 nested enums                                         |
+
+## Cross-cutting features
+
+| Feature                                                                    | Status                                              |
+| -------------------------------------------------------------------------- | --------------------------------------------------- |
+| `tryParse` / `parse` / `isValid` / `format` / `normalize` / `isNormalized` | Complete for every value-object type                |
+| `typeInfo` metadata (English + Swedish name, emoji, sources)               | Complete                                            |
+| `validate()` structured validation                                         | Complete — all 14 types that have it in .NET        |
+| `findCandidatesInText()` text scanning                                     | Complete — all 70 types that have it in .NET        |
+| `TextScanResult` typed accessors                                           | Complete — all 67 .NET accessors, plus `luminances` |
+| Masking (`toMaskedString` → `mask*` functions)                             | Complete                                            |
+| Lookup and external-link helpers                                           | Complete                                            |
+| `PrimitivesDefaults` (culture, UI culture, country, calling code)          | Complete                                            |
+| Sample data                                                                | Partial — see below                                 |
+| `toNaturalString()` natural unit display                                   | Complete                                            |
+
+## Known gaps within ported namespaces
+
+- **`SampleOrganizations` / `SampleOrganization`.** The .NET package ships a
+  composite record joining ~22 publicly known Swedish organizations across
+  organization number, VAT, address, banking, and geography. This port has
+  per-type sample data for the same organizations, but not the composite record.
+
+## Intentional API divergences
+
+These differ from .NET on purpose and are not tracked as gaps.
+
+| .NET                                      | This package                                   | Reason                                               |
+| ----------------------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
+| `static bool TryParse(s, out T)`          | `static tryParse(s): T \| null`                | No `out` parameters in TypeScript                    |
+| Extension method `value.ToMaskedString()` | `maskXxx(value)` module function               | No extension methods; keeps masking tree-shakeable   |
+| `IReadOnlyList<T>`                        | `readonly T[]`                                 | Idiomatic TypeScript                                 |
+| `Uri` interop via `ToUri()` / `FromUri()` | `toUrl()` / `fromUrl()` using `URL`            | `URL` is the web-platform equivalent of `System.Uri` |
+| `GeoCoordinate.DistanceTo(other)`         | `distanceKilometersTo(other)`                  | Names the unit at the call site                      |
+| `CultureInfo`                             | BCP-47 strings on `PrimitivesDefaults.culture` | Standard `Intl` has no `CultureInfo` equivalent      |
+| `IBudiTimeProvider`                       | `Clock` interface in `internal/clock.ts`       | Minimal injectable clock for date-dependent types    |
+
+`Address.asCountryAddress()` additionally depends on the country-specific
+address modules having been loaded. Every package entry point re-exports them,
+so this is transparent to consumers; see
+[`src/contact/country-address-registry.ts`](src/contact/country-address-registry.ts).
+
+## Porting `Measurement`
+
+The namespace divides into 19 quantity types, each paired with a unit class,
+five standalone types (`Count`, `Percentage`, `SoundLevel`, `Year`,
+`YearMonth`), and `TemperatureDelta`. There are 133 units in total.
+
+The namespace is fully ported: 19 dimensions, 133 units, five standalone types,
+plus `TemperatureDelta`. The standalone types `Count`, `Percentage`,
+`SoundLevel`, `Year` and `YearMonth` have no unit table and no conversion.
+
+Four things do not follow the common pattern:
+
+- **`Temperature` is affine.** `TemperatureUnit` has no `ToBaseUnitFactor`
+  because Celsius, Fahrenheit and kelvin differ by offset as well as scale, so
+  it neither uses the shared multiplicative conversion nor extends the common
+  base classes. Subtracting two temperatures yields a `TemperatureDelta`, where
+  a kelvin and a Celsius degree are the same interval and Fahrenheit scales by
+  9/5. Round-tripping through Fahrenheit drifts in the last digits — 0 °F comes
+  back as -4e-27 °F — and the port reproduces that rather than hiding it,
+  because .NET lands on the same value.
+- **Some factors are repeating decimals.** 1/60 for rpm, 1/3600 for coulomb,
+  1000/3600 for km/h. Multiplying by the rounded factor and dividing by it are
+  not inverses, so those five units carry an exact numerator/denominator pair
+  instead. .NET special-cases exactly the same units.
+- **`mW` against `MW`, `mV` against `MV`.** Unit lookup is otherwise
+  case-insensitive, but these two pairs differ by a factor of a billion, so
+  `PowerUnit` and `VoltageUnit` resolve them case-sensitively first. For the
+  same reason `Power`'s scan pattern is split in two: .NET writes it as one
+  regex with a scoped `(?i:...)` group, which JavaScript has no equivalent for.
+- **Arithmetic has no operators.** C# overloads `+ - * /` and the comparison
+  operators on every quantity; those become `plus`, `minus`, `times`,
+  `dividedBy`, `negated`, `isLessThan` and `isGreaterThan`.
+
+Unit lookup case-folds by upper-casing rather than lower-casing, matching
+.NET's `StringComparer.OrdinalIgnoreCase`. Lower-casing would break `ΜW`: the
+micro sign `µ` and the Greek capital mu `Μ` fold together going up but not
+going down.
+
+Two dimensions accept a bare number and assume a unit, as .NET does:
+`Luminance` reads it as candela per square metre and rejects negatives, and
+`RotationalSpeed` reads it as rpm.
+
+`Speed`, `Torque` and `RotationalSpeed` have no curated display scale in .NET,
+so `naturalUnit` falls back to the base unit for them.
+
+With the preserve-module output, bundlers can remove unreferenced Measurement
+dimensions. A retained quantity class still keeps its own static unit table, so
+importing `Length` includes the Length units but not unrelated dimension tables.
+
+Values are held internally as an exact base-10 decimal
+([`internal/decimal.ts`](src/internal/decimal.ts)) rather than `number`.
+Binary floating point turns `3 ft` into `0.9144000000000001 m` on the
+`normalize()` path, which would break the `isNormalized` contract and diverge
+from .NET. Consumer-facing accessors such as `length.meters` still return
+`number`; the conversion happens only at the boundary.
+
+## Porting `Vehicle`
+
+The namespace splits three ways. Sixteen types are closed sets of named members
+(`FuelType`, `BodyType`, `EuroEmissionClass` and so on), seven wrap a
+`Measurement` quantity or an exact decimal (`EngineDisplacement` over `Volume`,
+`EnginePower` over `Power`, `OdometerReading` over `Length`, plus
+`OperatingHours` and the three consumption / emission rates), and seven are
+structured identifiers and dimensions (`VehicleIdentificationNumber`,
+`SwedishVehicleRegistrationNumber`, `TireDimension`, `WheelRimDimension`,
+`BoltPattern`, `EuTypeApprovalNumber`, `EuVehicleCategory`).
+
+The lookup types were generated from the .NET assembly rather than transcribed,
+because each one folds its lookup keys slightly differently — which diacritics
+are stripped, which punctuation collapses to a space — and those rules only
+exist as fifteen separate private methods. Both test suites in
+[`test/vehicle`](test/vehicle) run against fixtures captured from .NET rather
+than from expectations written here.
+
+Three details do not follow the .NET source line for line:
+
+- **Word boundaries.** .NET's `\b` is Unicode-aware, JavaScript's is not, so
+  scan patterns that would otherwise miss `supermiljöbil` use explicit
+  `(?<!\p{L}\p{N}_)` lookarounds instead.
+- **Masking reads the parsed scale.** .NET masks a decimal by the length of its
+  `ToString()`, which keeps trailing zeros, so `OperatingHours`, `BoltPattern`
+  and `WheelRimDimension` hold a `Decimal` internally and mask from that rather
+  than from a `number`.
+- **`EnergyConsumption` is not registered on the default scanner.** It has a
+  `findCandidatesInText`, but the .NET `TextScanner` does not run it, and
+  neither do we. Applications that want it can register it on their own
+  `TextScanner`.
+
+## Porting `Product`
+
+The namespace splits much like `Vehicle`. Eleven types are closed sets of named
+members (`BatteryChemistry`, `ClothingFit`, `Refrigerant` and so on), four wrap
+a `Measurement` quantity (`StorageCapacity` and `RamCapacity` over `DataSize`,
+`ProcessorSpeed` over `Frequency`, `BatteryCapacity` over either
+`ElectricCharge` or `Energy`), and the rest are structured — the GTIN family,
+the clothing and shoe size pairs, `Color`, the screen types, `IpRating`,
+`HsCode`, `GoogleProductCategory` and the `OperatingSystem*` trio.
+
+As with `Vehicle`, the lookup types were generated from the .NET assembly rather
+than transcribed, and [`test/product`](test/product) runs against fixtures
+captured from .NET rather than expectations written here.
+
+Four details are worth calling out:
+
+- **`BatteryCapacity` carries one of two dimensions.** A capacity in mAh is a
+  charge, one in Wh is an energy, and .NET refuses to add or compare across the
+  two. The port throws on the same combinations rather than silently
+  converting, which would need a cell voltage nobody supplied.
+- **Lookup keys fold by upper-casing.** `DisplayPanelType` accepts `µLED`,
+  where the micro sign and the Greek capital mu fold together going up but not
+  going down, so lookups go through
+  [`internal/case-folding.ts`](src/internal/case-folding.ts) — the same reason
+  `Measurement` unit lookup does.
+- **`Color` rounds half to even.** Its HSL round-trip lands on exact halves
+  often enough that the JavaScript default of rounding half away from zero
+  would drift from .NET by one channel step.
+- **`CameraResolution` is not registered on the default scanner.** It has a
+  `findCandidatesInText`, but the .NET `TextScanner` does not run it, the same
+  way `EnergyConsumption` is left out of the `Vehicle` set.

package/README.md

@@ -8,9 +8,9 @@ This is the TypeScript port of the .NET package
 [source](https://github.com/BudiAuktioner/Buildi.Primitives) remains the
 behavioural specification for both languages.
 
-> **Status**: early release, versioned from 0.1.0. Ten of the thirteen .NET
-> namespaces are ported and track the .NET package closely; three are not
-> ported yet. See [PARITY.md](PARITY.md) for the exact coverage and gaps.
+> **Status**: early release, versioned from 0.1.0. All thirteen .NET namespaces
+> are ported and track the .NET package closely. See [PARITY.md](PARITY.md) for
+> the exact coverage and the handful of intentional divergences.
 
 ## Install
 
@@ -129,7 +129,10 @@ Types that can plausibly appear in prose expose `findCandidatesInText`, and
 `defaultTextScanner` runs all of them at once:
 
 ```ts
-import { defaultTextScanner } from "@budiauktioner/buildi-primitives/text-scanning";
+import {
+  TextCandidateCategory,
+  defaultTextScanner,
+} from "@budiauktioner/buildi-primitives/text-scanning";
 
 const text = "Hör av dig till info@example.com eller ring 070-174 06 33.";
 const result = defaultTextScanner.scan(text);
@@ -148,6 +151,21 @@ source text, its normalized, formatted and masked forms, and a
 sequences report `Low`. Narrow a scan with
 `scan(text, { minimumConfidence, includeCategories, excludeCategories })`.
 
+Version 0.2.0 expands `defaultTextScanner` with the Measurement, Vehicle, and
+Product scanners, so an unfiltered scan may now find or mask more values than
+0.1.x. To preserve the previous category scope during migration, exclude the
+new categories:
+
+```ts
+const result = defaultTextScanner.scan(text, {
+  excludeCategories: new Set([
+    TextCandidateCategory.Measurement,
+    TextCandidateCategory.Vehicle,
+    TextCandidateCategory.Product,
+  ]),
+});
+```
+
 Scanning is the one part of the package with import-time behaviour: importing
 `@budiauktioner/buildi-primitives/text-scanning` (or the root entry) registers
 all built-in scanners on `defaultTextScanner`. Importing only a value-object
@@ -198,25 +216,56 @@ RFC 2606 domains for email and the standard international test IBANs.
 ## Subpath exports and bundle size
 
 The root entry re-exports everything for convenience. Import from a namespace
-subpath instead when bundle size matters:
+subpath instead when bundle size matters. These figures bundle and minify the
+complete consumers shown below with esbuild for an ES2022 browser target:
 
 ```ts
-// ~283 kB minified — the root entry registers every text scanner
+// 439,333 bytes minified
 import { SwedishOrganizationNumber } from "@budiauktioner/buildi-primitives";
 
-// ~39 kB minified — the same type, nothing else
+console.log(SwedishOrganizationNumber.parse("559246-0421").toNormalizedString());
+```
+
+```ts
+// 22,024 bytes minified
 import { SwedishOrganizationNumber } from "@budiauktioner/buildi-primitives/organization";
+
+console.log(SwedishOrganizationNumber.parse("559246-0421").toNormalizedString());
+```
+
+```ts
+// 15,502 bytes minified
+import { Length } from "@budiauktioner/buildi-primitives/measurement";
+
+console.log(Length.fromMeters(1).toNormalizedString());
 ```
 
+The root named import remains substantially larger because importing the root
+entry registers all built-in scanners as an import-time side effect. Namespace
+imports avoid that registration graph, and tree-shaking drops unrelated
+Measurement dimensions from the `Length` consumer.
+
 Available subpaths: `contact`, `person`, `organization`, `geography`, `web`,
-`finance`, `property`, `banking`, `validation`, `text-scanning`, and
-`sample-data`.
+`finance`, `property`, `banking`, `measurement`, `vehicle`, `product`,
+`validation`, `text-scanning`, and `sample-data`.
 
 ```ts
 import { SwedishPersonalIdentityNumber } from "@budiauktioner/buildi-primitives/person";
 import { Country, Continent, Language } from "@budiauktioner/buildi-primitives/geography";
 import { AddressCity, PhoneNumber, SwedishAddress } from "@budiauktioner/buildi-primitives/contact";
 import { Currency, MoneyAmount, ExchangeRates } from "@budiauktioner/buildi-primitives/finance";
+import {
+  Length,
+  Weight,
+  Temperature,
+  Percentage,
+} from "@budiauktioner/buildi-primitives/measurement";
+import {
+  FuelType,
+  TireDimension,
+  VehicleIdentificationNumber,
+} from "@budiauktioner/buildi-primitives/vehicle";
+import { Gtin13, ScreenSize, ClothingSize } from "@budiauktioner/buildi-primitives/product";
 import { ValidationErrorReason } from "@budiauktioner/buildi-primitives/validation";
 ```