@budiauktioner/buildi-primitives 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog — `@budiauktioner/buildi-primitives`
+
+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.1.0] - 2026-08-07
+
+First public release.
+
+### Added
+
+- Initial TypeScript port scaffolding.
+- Public types for the Organization, Banking, Person, Geography, Finance,
+  Contact, Web, Property, Validation, and TextScanning namespaces.
+- Subpath exports per namespace for tree-shaking.
+- Local SwedishPersonalIdentityNumber implementation (no ActiveLogin dependency).
+- `TextScanResult` typed accessors for all 24 scannable types.
+- `Country.usesEuro`, `currencyCode`, `currency`, `currencies`,
+  `primaryLanguage`, `officialLanguages`, `latitude`, `longitude`, `value`, and
+  `formatted`.
+- `Address.asCountryAddress()`, `Address.toDomesticMultilineString()`,
+  `Address.supportedCountryAddressTypes`, and `SwedishAddress.countryZipCode`.
+- `Currency.nativeName` / `toNativeString()` and `Url.toUrl()` / `Url.fromUrl()`.
+- `maskSwedishOrganizationName` and `maskPersonAge`.
+- 28 further `PhoneCallingCode` named constants, for 35 in total.
+- `PhoneNumberTestData` covering all 495 PTS-reserved test phone numbers.
+- `TextDirection`, `WritingScript`, and `SwedishOrganizationTypeHintResult` are
+  now exported from their namespace barrels.
+- [PARITY.md](PARITY.md) and a parity guard test covering the .NET public surface.
+
+### Changed
+
+- `Country.isEuropeanUnion` and `Country.isNordic` renamed to
+  `isInEuropeanUnion` and `isInNordics`. See [BREAKING_CHANGES.md](BREAKING_CHANGES.md).
+- Scannable types now import the `text-scanning` leaf modules instead of its
+  barrel, removing an import cycle between the two.
+- `registerDefaultTextScanners` is now exported from the `text-scanning`
+  namespace.
+- `sideEffects` lists the four entries that register defaults at import time
+  instead of claiming `false` for the whole package. Every other entry stays
+  tree-shakeable, so subpath imports are unaffected.
+
+### Fixed
+
+- Importing `@budiauktioner/buildi-primitives/text-scanning` on its own left
+  `defaultTextScanner` empty, so scans silently returned no candidates. The
+  registration ran only from the package root. It now runs when the
+  `text-scanning` entry itself is imported.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Budi AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# @budiauktioner/buildi-primitives
+
+TypeScript primitives for Swedish, EU, and international value-object
+validation, normalization, masking, and text scanning.
+
+This is the TypeScript port of the .NET package
+[`Buildi.Primitives`](https://www.nuget.org/packages/Buildi.Primitives), whose
+[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.
+
+## Install
+
+```sh
+pnpm add @budiauktioner/buildi-primitives
+# or
+npm install @budiauktioner/buildi-primitives
+# or
+yarn add @budiauktioner/buildi-primitives
+# or
+bun add @budiauktioner/buildi-primitives
+```
+
+## Quick start
+
+```ts
+import { SwedishOrganizationNumber } from "@budiauktioner/buildi-primitives/organization";
+
+SwedishOrganizationNumber.isValid("559246-0421"); // true
+SwedishOrganizationNumber.isValid("559246-0420"); // false — bad check digit
+
+// Static helpers accept messy input and return null when it is not valid.
+SwedishOrganizationNumber.format("5592460421"); // "559246-0421"
+SwedishOrganizationNumber.normalize("559246-0421"); // "165592460421"
+SwedishOrganizationNumber.format("nonsense"); // null
+
+// Or parse once and keep the value object around.
+const org = SwedishOrganizationNumber.parse("5592460421");
+org.toString(); // "559246-0421"  — display form
+org.toNormalizedString(); // "165592460421" — storage form
+org.isPerson; // false — this is a legal entity, not a sole trader
+```
+
+`format()` produces the display form and `normalize()` the canonical form for
+storage and comparison. For roughly half the types these are the same string;
+for the rest they deliberately differ, as above. Store the normalized value and
+render the formatted one.
+
+## API conventions
+
+Every value-object type follows the same shape:
+
+```ts
+class TypeName {
+  static readonly typeInfo: PrimitiveTypeInfo;
+
+  static tryParse(input: string | null | undefined): TypeName | null;
+  static parse(input: string): TypeName; // throws on invalid input
+  static isValid(input: string | null | undefined): boolean;
+  static format(
+    input: string | null | undefined,
+    options?: { fallbackToTrimmedInputWhenInvalid?: boolean },
+  ): string | null;
+  static normalize(
+    input: string | null | undefined,
+    options?: { fallbackToTrimmedInputWhenInvalid?: boolean },
+  ): string | null;
+  static isNormalized(input: string | null | undefined): boolean;
+
+  toNormalizedString(): string;
+  toString(): string;
+
+  equals(other: TypeName | null | undefined): boolean;
+  compareTo(other: TypeName | null | undefined): number;
+}
+```
+
+Constructors are private: a value object can only come from `parse` or
+`tryParse`, so an instance is always valid. Every static helper accepts
+`string | null | undefined`, so unvalidated input can be passed straight in.
+
+Pass `{ fallbackToTrimmedInputWhenInvalid: true }` to `format` or `normalize`
+to get the trimmed original input back instead of `null` when the input is not
+valid — useful when rendering user-entered values you do not want to drop.
+
+## Validation
+
+Types with more than one meaningful failure mode add `validate()`, which
+reports why the input was rejected rather than just that it was:
+
+```ts
+import { Iban } from "@budiauktioner/buildi-primitives/banking";
+
+const result = Iban.validate("SE45 5000 0000 0583 9825 7460");
+
+result.isValid; // false
+result.issues.map((i) => i.reason); // ["InvalidCheckDigit"]
+result.issues[0].description; // "Ogiltiga IBAN-kontrollsiffror."
+```
+
+`reason` is a stable `ValidationErrorReason` enum value safe to branch on.
+`description` is human-readable and follows the display language described
+under [Defaults and display language](#defaults-and-display-language); each
+issue also exposes `englishDescription` and `localizedDescription` directly.
+
+## Masking
+
+Masking is done by module-level `maskX` functions, exported from the same
+subpath as the type they mask:
+
+```ts
+import { Iban, maskIban } from "@budiauktioner/buildi-primitives/banking";
+import { EmailAddress, maskEmailAddress } from "@budiauktioner/buildi-primitives/web";
+import { PhoneNumber, maskPhoneNumber } from "@budiauktioner/buildi-primitives/contact";
+
+maskIban(Iban.parse("SE4550000000058398257466")); // "SE45 **** **** **** **** ****"
+maskEmailAddress(EmailAddress.parse("info@example.com")); // "i***@example.com"
+maskPhoneNumber(PhoneNumber.parse("070-174 06 33")); // "+46*****0633"
+```
+
+Some take options, for example `maskEmailAddress(email, { maskDomain: true })`.
+
+## Text scanning
+
+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";
+
+const text = "Hör av dig till info@example.com eller ring 070-174 06 33.";
+const result = defaultTextScanner.scan(text);
+
+result.emails.map((c) => c.normalizedForm); // ["info@example.com"]
+result.phoneNumbers.map((c) => c.normalizedForm); // ["0046701740633"]
+
+result.maskAll(text); // "Hör av dig till i***@example.com eller ring +46*****0633."
+result.redactAll(text); // "Hör av dig till [REDACTED] eller ring [REDACTED]."
+```
+
+`TextScanResult` has a typed accessor per scannable type (`emails`, `ibans`,
+`organizationNumbers`, and so on). Every candidate carries its span in the
+source text, its normalized, formatted and masked forms, and a
+`TextMatchConfidence`. Types with a checksum report `High`; bare digit
+sequences report `Low`. Narrow a scan with
+`scan(text, { minimumConfidence, includeCategories, excludeCategories })`.
+
+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
+subpath deliberately does not. Construct your own `TextScanner` if you want an
+isolated registry.
+
+## Defaults and display language
+
+`PrimitivesDefaults` holds the process-wide culture, UI culture, default
+country and default calling code. It affects display names, localized
+validation messages, and how ambiguous input such as a national phone number
+is interpreted.
+
+```ts
+import { PrimitivesDefaults, Country } from "@budiauktioner/buildi-primitives";
+
+PrimitivesDefaults.culture; // "sv-SE"
+PrimitivesDefaults.countryAlpha2Code; // "SE"
+
+Country.parse("SE").displayName; // "Sverige"
+
+PrimitivesDefaults.uiCulture = "en-US";
+Country.parse("SE").displayName; // "Sweden"
+
+PrimitivesDefaults.reset(); // back to the defaults
+```
+
+`useLocalizedDisplayNames` is a read-only getter derived from `uiCulture` — it
+is `true` when `uiCulture` is Swedish. Set `uiCulture` to change the display
+language; assigning to `useLocalizedDisplayNames` throws a `TypeError`. Types
+that expose a `displayName` also expose `englishName` and `localizedName`, so a
+mixed-locale app can bypass the global entirely.
+
+## Sample data
+
+Valid, publicly known values for tests, fixtures and documentation. Everything
+here is a real parsed value object, so it stays valid as the rules evolve.
+
+```ts
+import { OrganizationSampleData } from "@budiauktioner/buildi-primitives/sample-data";
+
+OrganizationSampleData.OrganizationNumber.all[0].toString(); // "559246-0421"
+```
+
+Only publicly known organizations and reserved test values are used, such as
+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:
+
+```ts
+// ~283 kB minified — the root entry registers every text scanner
+import { SwedishOrganizationNumber } from "@budiauktioner/buildi-primitives";
+
+// ~39 kB minified — the same type, nothing else
+import { SwedishOrganizationNumber } from "@budiauktioner/buildi-primitives/organization";
+```
+
+Available subpaths: `contact`, `person`, `organization`, `geography`, `web`,
+`finance`, `property`, `banking`, `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 { ValidationErrorReason } from "@budiauktioner/buildi-primitives/validation";
+```
+
+Use the root entry when you want the batteries-included behaviour, in
+particular a `defaultTextScanner` that already knows every scannable type.
+
+## Runtime targets
+
+- Node.js 20.10 or newer (see [`.nvmrc`](.nvmrc)).
+- Bun 1.1 or newer.
+- Modern browsers (current Chromium, Firefox, Safari).
+- No Node-only runtime APIs and no runtime dependencies; ES2022 plus standard
+  `Intl` only.
+- Ships ESM and CJS builds with type definitions for both.
+
+## Development
+
+All commands run from the repository root:
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+```
+
+See [AGENTS.md](AGENTS.md) for conventions and the per-type pattern,
+[PARITY.md](PARITY.md) for the current state of .NET parity, and
+[CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices — `@budiauktioner/buildi-primitives` (TypeScript)
+
+`@budiauktioner/buildi-primitives` ships with **zero runtime dependencies**. This document
+collects attributions for the development tooling that builds, tests, and
+validates the package, plus any public references whose definitions or test
+data influenced the implementation.
+
+## Reference specifications and test data
+
+The TypeScript port reimplements all logic from scratch. The following public
+sources are referenced for behavioural parity. None of them are linked at
+runtime.
+
+- [Skatteverket — Personnummer](https://skatteverket.se/privat/folkbokforing/personnummer.4.3810a01c150939e893f18c29.html)
+  — official Swedish personal identity number rules.
+- [Skatteverket — Samordningsnummer](https://skatteverket.se/) — coordination
+  number rules.
+- [Bolagsverket](https://bolagsverket.se/) — Swedish organization registry.
+- [PostNord](https://www.postnord.se/) — Swedish postal city/zip-code rules.
+- ISO 3166-1, ISO 3166-2, ISO 4217, ISO 639 — country / subdivision /
+  currency / language codes.
+- [GLEIF](https://www.gleif.org/) — LEI codes.
+- [VIES VAT](https://ec.europa.eu/taxation_customs/vies/) — EU VAT number
+  formats.
+- [D&B](https://www.dnb.com/) — DUNS numbers.
+- [Skatteverket — OCR](https://skatteverket.se/) and Bankgirot — OCR reference
+  numbers.
+
+## Algorithm derivations
+
+- Luhn (mod 10) checksum — public domain algorithm.
+- IBAN MOD-97 — defined in ISO 13616.
+- LEI MOD-97-10 — defined in ISO 17442.
+
+If any logic is later derived by reading the source of an MIT-licensed library
+such as [ActiveLogin.Identity](https://github.com/ActiveLogin/ActiveLogin.Identity),
+list that derivation here together with the upstream license.
+
+## Development tooling
+
+This package is built and validated using the following tools (development
+dependencies; not shipped to consumers):
+
+- [TypeScript](https://www.typescriptlang.org/) — Apache-2.0
+- [tsup](https://tsup.egoist.dev/) — MIT
+- [tsx](https://tsx.is/) — MIT
+- [vitest](https://vitest.dev/) — MIT
+- [eslint](https://eslint.org/) — MIT
+- [typescript-eslint](https://typescript-eslint.io/) — MIT
+- [prettier](https://prettier.io/) — MIT
+- [publint](https://publint.dev/) — MIT
+- [@arethetypeswrong/cli](https://arethetypeswrong.github.io/) — MIT