Rut.ts (arrowsw/rut.ts)

Rut.ts

https://github.com/arrowsw/rut.ts
Admin
A TypeScript library for validating, formatting, and handling Chilean RUT (Rol Único Tributario)...

Tokens:26,381
Snippets:211
Trust Score:7.5
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# rut.ts

rut.ts is a TypeScript library for handling Chilean RUT (Rol Único Tributario) values. The RUT is Chile's unique identification number used for tax purposes, legal identification, government services, and banking transactions. The standard format is `XX.XXX.XXX-Y` where X represents the body (7-8 digits) and Y is the verifier digit (0-9 or K) calculated using the Modulo 11 algorithm.

The library provides comprehensive RUT operations including validation, formatting, cleaning, decomposition, generation, and verifier calculation. All functions support a "safe mode" via `throwOnError: false` that returns `null` instead of throwing errors, making it ideal for form handling and user input processing. The library works in both Node.js and browser environments with full TypeScript support.

## validate()

Validates a RUT string by checking both format and verifier digit correctness. Accepts `unknown` input type for type safety, with optional strict mode to reject suspicious patterns like repeated digits (e.g., 11.111.111-1).

```typescript
import { validate } from 'rut.ts'

// Basic validation
validate('12.345.678-5')                      // true
validate('12.345.678-0')                      // false (wrong verifier)
validate('12345678-5')                        // true (without dots)
validate('123456785')                         // true (no formatting)
validate('14.625.621-K')                      // true (K verifier)

// Invalid inputs
validate('abc')                               // false
validate('')                                  // false
validate(null)                                // false
validate(123)                                 // false

// Strict mode rejects suspicious patterns
validate('11.111.111-1', { strict: true })    // false
validate('22.222.222-2', { strict: true })    // false
validate('11.111.111-1')                      // true (without strict)

// Type-safe validation
function processUserInput(input: unknown) {
  if (validate(input)) {
    console.log('Valid RUT')
  }
}
```

## format()

Converts RUT strings into a standardized format with dots and hyphens. Supports incremental formatting for real-time input formatting as users type, with options to include/exclude dot separators.

```typescript
import { format } from 'rut.ts'

// Standard formatting
format('123456785')                           // '12.345.678-5'
format('9068826K')                            // '9.068.826-K'
format('123456785', { dots: false })          // '12345678-5'

// Handles various input formats
format('12.345.678-5')                        // '12.345.678-5'
format('12-345-678-5')                        // '12.345.678-5'
format('  123456785  ')                       // '12.345.678-5'
format('00012345678')                         // '1.234.567-8' (leading zeros removed)

// Incremental formatting (for real-time input)
format('1', { incremental: true })            // '1'
format('1234', { incremental: true })         // '1.234'
format('12345678', { incremental: true })     // '1.234.567-8'
format('123456785', { incremental: true })    // '12.345.678-5'

// Safe mode (returns null instead of throwing)
format('invalid', { throwOnError: false })    // null
format('123', { throwOnError: false })        // null

// React input handler example
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  const formatted = format(e.target.value, { incremental: true })
  setRut(formatted)
}
```

## clean()

Removes extraneous characters (dots, hyphens, spaces) and leading zeros from RUT strings, returning a normalized uppercase version suitable for database storage or API calls.

```typescript
import { clean } from 'rut.ts'

// Basic cleaning
clean('12.345.678-5')                         // '123456785'
clean('  12-345-678-5  ')                     // '123456785'
clean('00012345678K')                         // '12345678K'
clean('12345678k')                            // '12345678K' (uppercase)

// Handles various formats
clean('12#345$678%5')                         // '123456785'
clean('(12.345.678-5)')                       // '123456785'

// Safe mode
clean('invalid', { throwOnError: false })     // null
clean('123', { throwOnError: false })         // null (too short)

// Practical usage
const handleInput = (value: string) => {
  const cleaned = clean(value, { throwOnError: false })
  if (cleaned) {
    saveToDatabase(cleaned)
  } else {
    showError('Invalid RUT format')
  }
}
```

## decompose()

Splits a RUT into its body and verifier digit components, returning an object with both parts. Useful for storing RUT parts separately or comparing RUT bodies.

```typescript
import { decompose } from 'rut.ts'

// Basic decomposition
const { body, verifier } = decompose('12.345.678-5')
console.log(body)                             // '12345678'
console.log(verifier)                         // '5'

// K verifier
const rut = decompose('9.068.826-K')
console.log(rut.body)                         // '9068826'
console.log(rut.verifier)                     // 'K'

// Safe mode
const result = decompose('invalid', { throwOnError: false })
console.log(result)                           // null

// Store body and verifier separately
const { body: rutBody, verifier: rutVerifier } = decompose('12.345.678-5')
await db.users.create({
  rutBody: rutBody,                           // '12345678'
  rutVerifier: rutVerifier                    // '5'
})

// Compare RUT bodies
const rut1 = decompose('12.345.678-5')
const rut2 = decompose('12345678-5')
if (rut1.body === rut2.body) {
  console.log('Same person')
}
```

## getBody()

Extracts just the body (without verifier digit) from a RUT string. A convenience function for when you only need the body portion.

```typescript
import { getBody } from 'rut.ts'

// Basic extraction
getBody('12.345.678-5')                       // '12345678'
getBody('18.972.631-7')                       // '18972631'
getBody('9.068.826-K')                        // '9068826'

// Safe mode
getBody('invalid', { throwOnError: false })   // null

// Use for database queries
const body = getBody('12.345.678-5')
const users = await db.users.findMany({
  where: { rutBody: body }
})
```

## getVerifier()

Extracts just the verifier digit from a RUT string. Returns a single character ('0'-'9' or 'K'), always uppercase.

```typescript
import { getVerifier } from 'rut.ts'

// Basic extraction
getVerifier('12.345.678-5')                   // '5'
getVerifier('18.972.631-7')                   // '7'
getVerifier('9.068.826-K')                    // 'K'
getVerifier('9068826k')                       // 'K' (converted to uppercase)

// Safe mode
getVerifier('invalid', { throwOnError: false }) // null

// Verify correctness manually
import { calculateVerifier, getBody } from 'rut.ts'

const rut = '12.345.678-5'
const body = getBody(rut)
const verifier = getVerifier(rut)
const calculated = calculateVerifier(body)

if (verifier === calculated) {
  console.log('Verifier is correct!')
}
```

## calculateVerifier()

Calculates the verifier digit for a given RUT body using the Modulo 11 algorithm. Useful for generating custom RUTs or verifying RUT correctness.

```typescript
import { calculateVerifier, format } from 'rut.ts'

// Basic calculation
calculateVerifier('12345678')                 // '5'
calculateVerifier('18972631')                 // '7'
calculateVerifier('24657622')                 // 'K'
calculateVerifier('14625621')                 // 'K'

// Build a complete RUT
const body = '12345678'
const verifier = calculateVerifier(body)
const completeRut = format(body + verifier)
console.log(completeRut)                      // '12.345.678-5'

// Safe mode
calculateVerifier('123', { throwOnError: false }) // null (too short)

// Accepts formatted input
calculateVerifier('18.972.631')               // '7'
calculateVerifier('18-972-631')               // '7'

// Form validation
const handleBodyInput = (body: string) => {
  const verifier = calculateVerifier(body, { throwOnError: false })
  if (verifier) {
    console.log(`Complete RUT: ${body}-${verifier}`)
  } else {
    console.log('Invalid body length or format')
  }
}
```

## generate()

Generates random valid RUT numbers for testing and development purposes. Returns formatted RUTs with dots and hyphens that pass validation.

```typescript
import { generate, validate, decompose } from 'rut.ts'

// Generate single RUT
const rut = generate()
console.log(rut)                              // e.g., '45.123.789-2'

// Generate multiple RUTs
const ruts = Array.from({ length: 10 }, () => generate())
console.log(ruts)
// ['18.972.631-7', '45.123.789-2', '67.890.123-K', ...]

// All generated RUTs are valid
const testRuts = Array.from({ length: 100 }, () => generate())
testRuts.forEach(rut => {
  console.assert(validate(rut) === true)
  console.assert(validate(rut, { strict: true }) === true)
})

// Seed test database
const testUsers = Array.from({ length: 50 }, (_, i) => {
  const rut = generate()
  const { body, verifier } = decompose(rut)
  return {
    id: i + 1,
    name: `Test User ${i + 1}`,
    rut: rut,
    rutBody: body,
    rutVerifier: verifier
  }
})
await db.users.insertMany(testUsers)
```

## isRutLike()

Quick format check to determine if a string looks like a RUT, without validating the verifier digit. Faster than `validate()` for early filtering.

```typescript
import { isRutLike, validate } from 'rut.ts'

// Valid formats
isRutLike('12.345.678-9')                     // true
isRutLike('12345678-9')                       // true (no dots)
isRutLike('123456789')                        // true (no formatting)
isRutLike('1.234.567-K')                      // true (7-digit body)

// Invalid formats
isRutLike('abcdefgh')                         // false
isRutLike('')                                 // false
isRutLike('12.34.56-7')                       // false (wrong pattern)

// Difference from validate()
const rut = '12.345.678-0'                    // Wrong verifier (should be 5)
isRutLike(rut)                                // true (format is correct)
validate(rut)                                 // false (verifier is wrong)

// Quick filter before validation
const inputs = ['12.345.678-5', 'invalid', '18.972.631-7', 'abc']
const potentialRuts = inputs.filter(isRutLike)
// ['12.345.678-5', '18.972.631-7']

// Pre-validation performance optimization
function validateRut(input: unknown): boolean {
  if (typeof input !== 'string' || !isRutLike(input)) {
    return false
  }
  return validate(input)  // Full validation only if format matches
}
```

## React Hook Form Integration

Integrate rut.ts with React Hook Form for form validation with automatic formatting.

```typescript
import { useForm } from 'react-hook-form'
import { validate, format } from 'rut.ts'

type FormData = { rut: string; name: string }

function MyForm() {
  const { register, handleSubmit, setValue, formState: { errors } } = useForm<FormData>()

  const onSubmit = (data: FormData) => {
    console.log('Valid RUT:', data.rut)
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input
        {...register('rut', {
          required: 'RUT is required',
          validate: (value) => validate(value) || 'RUT is invalid',
          onChange: (e) => {
            const formatted = format(e.target.value, { incremental: true })
            setValue('rut', formatted)
          }
        })}
        placeholder="12.345.678-5"
      />
      {errors.rut && <span>{errors.rut.message}</span>}
      <button type="submit">Submit</button>
    </form>
  )
}
```

## Zod Schema Validation

Use rut.ts with Zod for schema-based validation in TypeScript applications.

```typescript
import { z } from 'zod'
import { validate, clean } from 'rut.ts'

const userSchema = z.object({
  name: z.string(),
  rut: z.string().refine(
    (val) => validate(val),
    { message: 'Invalid RUT' }
  ),
  email: z.string().email()
})

// Usage
const result = userSchema.safeParse({
  name: 'Juan Pérez',
  rut: '12.345.678-5',
  email: 'juan@example.com'
})

if (result.success) {
  const cleanedRut = clean(result.data.rut)
  console.log('Valid data:', { ...result.data, rut: cleanedRut })
}

// Next.js Server Action
'use server'
export async function createUser(formData: FormData) {
  const data = { rut: formData.get('rut') as string }
  const result = userSchema.safeParse(data)

  if (!result.success) {
    return { error: result.error.flatten() }
  }

  const cleanedRut = clean(data.rut)
  await db.users.create({ data: { rut: cleanedRut } })
  return { success: true }
}
```

## TypeScript Types

The library exports TypeScript types for all options and return values.

```typescript
import type {
  DecomposedRut,
  FormatOptions,
  SafeOptions,
  ValidateOptions,
  VerifierDigit
} from 'rut.ts'

// DecomposedRut: { body: string; verifier: string }
// FormatOptions: { incremental?: boolean; dots?: boolean; throwOnError?: boolean }
// SafeOptions: { throwOnError?: boolean }
// ValidateOptions: { strict?: boolean }
// VerifierDigit: '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'K'
```

rut.ts is primarily designed for Chilean applications that need to handle RUT values in forms, databases, and APIs. Common use cases include user registration forms with real-time RUT formatting, API input validation, database normalization (storing clean RUTs), and generating test data for development. The incremental formatting feature is particularly useful for improving UX in form inputs by formatting RUTs as users type.

The library integrates seamlessly with popular form libraries (React Hook Form, Formik), validation libraries (Zod, Yup), and frameworks (Next.js, React). For optimal usage, use `format()` with `incremental: true` for real-time input formatting, always validate with `validate()` before processing, use `clean()` before storing to databases, and leverage safe mode (`throwOnError: false`) for graceful error handling in user-facing applications.