Migration to v4

Version 4.0.0 is a major, breaking release focused on production identity hardening. This page covers what changed and the concrete edits to make when upgrading from 3.x.

At a glance#

Breaking changes and fixes#

1. format() now validates the verifier#

In 3.x, format() would happily format a structurally-shaped value even if the verifier digit was wrong. In 4.0.0, non-incremental format() throws (or returns null in safe mode) when the verifier is incorrect.

import { format } from 'rut.ts'
 
// 3.x: returned a formatted string
// 4.0.0: throws — verifier is wrong
format('12.345.678-0', { throwOnError: false }) // null
 
// Incremental mode is unchanged: still formats partial input
format('123456', { incremental: true }) // '123.456'

Action: if you relied on format() to format unvalidated input, either switch to incremental: true, or validate first and handle the null/throw path.

2. Generic error messages#

Errors no longer include the offending RUT, so Chilean ID values never leak into logs, traces, or error trackers.

import { clean } from 'rut.ts'
 
try {
  clean('invalid')
} catch (e) {
  // 3.x: "Invalid RUT: invalid"
  // 4.0.0: "Invalid RUT input"
  console.error((e as Error).message)
}

Action: if you string-matched on error messages, update those checks. Prefer safe mode ({ throwOnError: false }) and branch on null instead.

3. Non-string inputs are invalid, not a TypeError#

getBody(), getVerifier(), decompose(), and friends previously could throw a TypeError on null/undefined/numbers. Now they treat non-strings as ordinary invalid input.

import { getBody } from 'rut.ts'
 
getBody(null, { throwOnError: false })        // null  (was: TypeError)
getBody(12345678, { throwOnError: false })    // null  (was: TypeError)

Action: remove try/catch blocks that specifically handled TypeError; rely on the null path in safe mode.

4. Stricter validate() and the new strict option#

validate() now rejects ambiguous dot grouping (e.g. 12.345678-5) and oversized input fails fast. The new strict: true option also rejects repeated-digit placeholders.

import { validate } from 'rut.ts'
 
validate('12.345.678-5')                   // true
validate('12.345678-5')                    // false (was: true in some 3.x paths)
validate('11.111.111-1')                   // true
validate('11.111.111-1', { strict: true }) // false (placeholder)

Action: adopt validate(input, { strict: true }) as the final acceptance gate for real identities. See Security.

5. generate() is crypto-backed#

generate() now uses the Web Crypto API when available, always produces 8-digit, non-suspicious bodies, and the result passes validate(rut, { strict: true }).

import { generate, validate } from 'rut.ts'
 
const rut = generate()
validate(rut, { strict: true }) // always true

Action: none required. Generated values remain test/dev data — never assign them as real identities.

Recommended upgrade checklist#

npm install rut.ts@^4

Related#