rut.ts 4.0.0 → 4.0.1

package/README.md

@@ -1,181 +1,174 @@
 <div align="center">
   <img src="https://user-images.githubusercontent.com/12705403/158434864-7f13401a-b973-4267-b035-d9882cf6c545.png" alt="Rut.ts logo" width="100%">
   <h1>Rut.ts: Handle chilean RUT values with ease using TypeScript.</h1>
-</div>
-
-![Open Bundle](https://deno.bundlejs.com/badge?q=rut.ts@4.0.0)
-
-> **v4.0.0 is a major, breaking release** focused on production identity hardening.
-> Read the [CHANGELOG](./CHANGELOG.md) before upgrading from `3.x`.
-
-## What is a RUT?
-
-The **RUT** (Rol Único Tributario) is the unique Chilean identification number used for:
-
-- Tax purposes
-- Legal identification
-- Government services
-- Banking and financial transactions
 
-**Format**: `XX.XXX.XXX-Y` where:
+[![npm version](https://img.shields.io/npm/v/rut.ts?color=000&label=npm)](https://www.npmjs.com/package/rut.ts)
+[![downloads](https://img.shields.io/npm/dm/rut.ts?color=000)](https://www.npmjs.com/package/rut.ts)
+[![bundle size](https://deno.bundlejs.com/badge?q=rut.ts&treeshake=[*])](https://bundlejs.com/?q=rut.ts)
+[![types included](https://img.shields.io/npm/types/rut.ts?color=000)](https://www.npmjs.com/package/rut.ts)
+![zero dependencies](https://img.shields.io/badge/dependencies-0-000)
+[![license](https://img.shields.io/npm/l/rut.ts?color=000)](./LICENSE)
 
-- `X` = Body (7-8 digits)
-- `Y` = Verifier digit (0-9 or K)
-
-**Example**: `12.345.678-5`
-
-The verifier digit is calculated using the [Modulo 11 algorithm](https://en.wikipedia.org/wiki/Rol_%C3%9Anico_Tributario) to validate the RUT's authenticity.
-
----
+</div>
 
-## Features
+The complete, security-hardened toolkit for the Chilean **RUT** (Rol Único
+Tributario): validate, format, clean, decompose and generate — with a
+correctness contract you can rely on in production.
 
-- **Validation**: Check if a RUT is valid with bounded input parsing, verifier validation, and optional strict mode.
-- **Cleaning**: Permissively remove extraneous characters and leading zeros from RUT strings.
-- **Formatting**: Convert valid RUTs into a standardized format, with or without dots.
-- **Incremental Formatting**: Format RUTs progressively as the user types (ideal for form inputs).
-- **Decomposition**: Split a RUT into its body and verifier digit.
-- **Generation**: Generate valid random RUT numbers for testing, using Web Crypto when available.
-- **Calculate Verifier**: Calculate the verifier digit for a given RUT body.
-- **Format Detection**: Check if a bounded string looks like a RUT format with `isRutLike`.
-- **Safe Mode**: All safe functions support `throwOnError: false` to return `null` instead of throwing generic errors.
+- 🪶 **Tiny & zero-dependency** — tree-shakeable ESM, ships only what you import.
+- 🔒 **Hardened by default** — bounded parsing, strict mode, generic errors. No ID values leak into logs or traces.
+- 🧠 **Fully typed** — first-class TypeScript types, no `@types` package needed.
+- 🌐 **Universal** — runs in Node, the browser, Deno and Bun. Uses Web Crypto when available.
+- ✅ **Battle-tested** — a differential harness guards every release against regressions.
 
 ## Installation
 
-Using [bun](https://bun.sh/):
-
-    $ bun add rut.ts
-
-Using [npm](https://www.npmjs.com/):
-
-    $ npm install rut.ts
-
-Using [pnpm](https://pnpm.io/):
-
-    $ pnpm install rut.ts
+```bash
+npm install rut.ts
+# or: bun add rut.ts · pnpm add rut.ts · yarn add rut.ts
+```
 
-## Quick Examples
+## Quick start
 
 ```typescript
-import { validate, format, clean, isRutLike, decompose } from 'rut.ts'
+import { validate, format, clean, decompose, isRutLike } from 'rut.ts'
 
-// Validation
+// Validate — strict mode also rejects suspicious placeholder RUTs
 validate('12.345.678-5') // true
 validate('12.345.678-0') // false (wrong verifier)
-validate('11.111.111-1', { strict: true }) // false (strict mode rejects suspicious RUTs)
-validate('8.888.888-K', { strict: true }) // false (uppercase K suspicious RUT)
+validate('11.111.111-1', { strict: true }) // false (suspicious)
 
-// Formatting
+// Format — accepts compact or formatted input
 format('123456785') // '12.345.678-5'
 format('123456785', { dots: false }) // '12345678-5'
 format('123456789', { throwOnError: false }) // null (wrong verifier)
 
-// Incremental formatting (for form inputs)
+// Format progressively as the user types (great for form inputs)
 format('1234', { incremental: true }) // '1.234'
-format('12345678', { incremental: true }) // '1.234.567-8' (8 chars = complete)
-format('123456785', { incremental: true }) // '12.345.678-5' (9 chars = complete)
+format('123456785', { incremental: true }) // '12.345.678-5'
 
-// Cleaning
+// Clean & decompose
 clean('12.345.678-5') // '123456785'
-// clean() normalizes shape only. Use validate() before accepting a RUT.
-
-// Decomposition
-const { body, verifier } = decompose('12.345.678-5')
-console.log(body) // '12345678'
-console.log(verifier) // '5'
+decompose('12.345.678-5') // { body: '12345678', verifier: '5' }
 
-// Format detection (without full validation)
+// Cheap shape check, no full validation
 isRutLike('12.345.678-5') // true
-isRutLike('not-a-rut') // false
 
-// Safe mode (returns null instead of throwing)
-clean('invalid', { throwOnError: false }) // null
+// Safe mode everywhere — return null instead of throwing
 format('abc', { throwOnError: false }) // null
 ```
 
-## Incremental Formatting
+> 📚 Full guides and live examples: **[rut.arrowsw.com](https://rut.arrowsw.com/)**
 
-The `incremental` option in `format()` allows you to format RUTs progressively as the user types. This is useful for real-time formatting in form inputs.
+## Features
 
-```typescript
-// Example: React input handler
-const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-  const formatted = format(e.target.value, { incremental: true })
-  setRut(formatted)
-}
-```
+- **Validation** — verifier check with bounded input parsing and an optional `strict` mode that rejects placeholder/repeated-digit RUTs.
+- **Formatting** — standardized output, with or without dots.
+- **Incremental formatting** — progressive formatting as the user types, ideal for form inputs.
+- **Cleaning** — permissively strip extraneous characters and leading zeros.
+- **Decomposition** — split a RUT into its body and verifier digit.
+- **Generation** — cryptographically-backed random valid RUTs for tests (Web Crypto when available).
+- **Calculate verifier** — compute the verifier digit for a given body.
+- **Format detection** — cheap `isRutLike` check without full validation.
+- **Safe mode** — every safe function supports `throwOnError: false` to return `null` instead of throwing.
+
+<details>
+<summary><strong>New to RUTs? What the format means</strong></summary>
 
-> **Note**: Incremental formatting will format the input progressively even for incomplete RUTs. The formatted output may not represent a valid RUT until the input is complete. Always use `validate()` to verify the final RUT before processing.
+<br>
 
-## Production Validation Notes
+The **RUT** (Rol Único Tributario) is the unique Chilean identification number
+used for tax, legal identification, government services, and banking.
 
-For security-sensitive identity flows, prefer `validate(input, { strict: true })` as the acceptance gate. The validator now rejects malformed dot grouping, caps oversized inputs before parsing, rejects repeated-digit placeholders in strict mode, and compares the verifier digit using the Modulo 11 algorithm.
+**Format**: `XX.XXX.XXX-Y`
+
+- `X` = Body (7–8 digits)
+- `Y` = Verifier digit (`0`–`9` or `K`)
+
+**Example**: `12.345.678-5`
 
-`clean()` remains intentionally permissive for input normalization. It is useful before display or storage, but it does not prove that the verifier digit is correct. `format()` validates the verifier digit in non-incremental mode and returns `null` in safe mode for invalid complete RUTs.
+The verifier digit is derived from the body via the
+[Modulo 11 algorithm](https://en.wikipedia.org/wiki/Rol_%C3%9Anico_Tributario),
+which is what makes a RUT self-validating.
 
-Error messages are generic (`Invalid RUT input`) so invalid Chilean ID values are not echoed into logs, traces, or user-visible exceptions.
+</details>
+
+## Security & correctness
+
+`rut.ts` treats RUT validation as an identity-security boundary, not just string
+formatting. That posture is the point of the library:
+
+- **`validate(input, { strict: true })` is the recommended acceptance gate** for identity-sensitive flows. It rejects malformed dot grouping, caps oversized inputs before parsing, rejects repeated-digit placeholders, and compares the verifier via Modulo 11.
+- **Errors are generic** (`Invalid RUT input`) so Chilean ID values never end up echoed into logs, traces, or user-visible exceptions.
+- **`clean()` is intentionally permissive** — useful for display/storage normalization, but it does _not_ prove the verifier is correct. Always `validate()` before accepting a RUT.
 
 ### Accepted input formats (the validation contract)
 
-`validate()` and `isRutLike()` accept **only** these shapes (optionally with leading
-zeros and surrounding whitespace, verifier `k`/`K` case-insensitive):
+`validate()` and `isRutLike()` accept **only** these shapes (optionally with
+leading zeros and surrounding whitespace, verifier `k`/`K` case-insensitive):
 
-| Shape | Example | Notes |
-|-------|---------|-------|
-| Compact | `123456785` | 7–8 digit body + verifier |
-| Compact + hyphen | `12345678-5` | |
+| Shape            | Example                       | Notes                           |
+| ---------------- | ----------------------------- | ------------------------------- |
+| Compact          | `123456785`                   | 7–8 digit body + verifier       |
+| Compact + hyphen | `12345678-5`                  |                                 |
 | Canonical dotted | `12.345.678-5`, `1.234.567-4` | Chilean grouping from the right |
 
 Anything else is rejected, **including non-canonical dot grouping** that older
-versions accepted: `12.345678-5`, `12345.678-5`, `1.2.3.4.5.6.7.8-5`,
-internal spaces (`12 345 678 5`), commas, and any input longer than 64 chars.
+versions accepted (`12.345678-5`, `12345.678-5`, `1.2.3.4-5`), internal spaces,
+commas, and any input longer than 64 chars.
 
 > The 64-char limit is a **security bound, not a format rule**. A real RUT is
-> ~9 significant characters (~12 formatted), so the cap never rejects a
-> realistically formatted RUT — it only refuses to *process* implausibly long
-> strings, which neutralizes CPU/ReDoS-style abuse before any parsing runs.
-
-> ⚠️ **Migrating a large dataset?** If your upstream emits RUTs in a non-canonical
-> shape, normalize it to one of the three accepted forms **before** calling
-> `validate()`, or run the differential harness against a representative sample
-> first: `npm run test:differential` (see
-> [`tests/differential.test.ts`](./tests/differential.test.ts); it writes
-> `tests/differential-report.md`). `clean()`/`decompose()` stay permissive and
-> will still parse some of those shapes — never treat their output as
+> ~9 significant characters, so the cap never rejects a realistic RUT — it just
+> refuses to _process_ implausibly long strings, neutralizing CPU/ReDoS-style
+> abuse before any parsing runs.
+
+> 💡 **Migrating a dataset?** If your upstream emits RUTs in a non-canonical
+> shape, normalize to one of the three accepted forms before calling
+> `validate()`, or sanity-check a representative sample with
+> `npm run test:differential` (writes `tests/differential-report.md`).
+> `clean()` / `decompose()` stay permissive — never treat their output as
 > "validated".
 
-### When to use incremental mode
-
-**✅ Use incremental when:**
-
-- Formatting user input in real-time as they type
-- Providing immediate visual feedback in form fields
-- Improving UX with progressive formatting
+## Incremental formatting
 
-**❌ Don't use incremental when:**
+`format(input, { incremental: true })` formats a RUT progressively as the user
+types — ideal for real-time feedback in form fields.
 
-- Formatting already complete/stored RUTs (use default `format()`)
-- Validating RUTs (use `validate()` instead)
-- Processing final form submission values
-
-## Usage
-
-Please refer to [the documentation](https://rut.arrowsw.com/) for more detailed examples.
+```typescript
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  setRut(format(e.target.value, { incremental: true }))
+}
+```
 
-## TypeScript Types
+**Use it for:** real-time input formatting and visual feedback.
+**Don't use it for:** validating, or formatting already-complete/stored RUTs
+(use `format()` / `validate()`). Incremental output may not be a valid RUT until
+the input is complete — always `validate()` the final value.
 
-The library exports the following types:
+## TypeScript types
 
 ```typescript
 import type { DecomposedRut, FormatOptions, SafeOptions, ValidateOptions, VerifierDigit } from 'rut.ts'
 
-// VerifierDigit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'K'
-// DecomposedRut: { body: string; verifier: string }
-// FormatOptions: { incremental?: boolean; dots?: boolean; throwOnError?: boolean }
-// ValidateOptions: { strict?: boolean }
-// SafeOptions: { throwOnError?: boolean }
+// VerifierDigit:  '0' | '1' | … | '9' | 'K'
+// DecomposedRut:  { body: string; verifier: string }
+// FormatOptions:  { incremental?: boolean; dots?: boolean; throwOnError?: boolean }
+// ValidateOptions:{ strict?: boolean }
+// SafeOptions:    { throwOnError?: boolean }
 ```
 
+## Upgrading from v3
+
+`v4` hardens validation for production identity flows and tightens the accepted
+input contract (see the table above). If you're coming from `3.x`, the
+[**CHANGELOG**](./CHANGELOG.md) lists every change and how to migrate — most
+codebases only need to normalize input shape before `validate()`.
+
 ## Contributing
 
-Contributions to this library are welcome. Please feel free to submit pull requests or create issues for bugs and feature requests.
+Contributions are welcome — feel free to open issues for bugs and feature
+requests, or submit a pull request.
+
+## License
+
+[MIT](./LICENSE) © rut.ts contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rut.ts",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "description": "Handle chilean RUT values with ease.",
   "author": "arrowsw",
@@ -46,6 +46,7 @@
     "eslint-plugin-prettier": "5.5.5",
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.0.1",
+    "expect-type": "1.3.0",
     "jest": "30.2.0",
     "prettier": "3.8.1",
     "terser": "5.46.0",