API Reference

import type {
  DecomposedRut,
  EqualsOptions,
  FormatOptions,
  GenerateOptions,
  Rut,
  SafeOptions,
  ValidateOptions,
  VerifierDigit,
} from 'rut.ts'

type Rut = string & { readonly __brand: 'Rut' } // branded validated-RUT string

type DecomposedRut = {
  body: string            // RUT body (7-8 digits, no leading zeros)
  verifier: VerifierDigit // Verifier digit ('0'-'9' or 'K')
}

type EqualsOptions = {
  requireValid?: boolean // Require the shared value to pass Modulo 11 (default: true)
}

type FormatOptions = {
  incremental?: boolean // Progressive formatting (default: false)
  dots?: boolean        // Include dot separators (default: true)
  throwOnError?: boolean // Throw vs. return null (default: true)
}

type GenerateOptions = {
  bodyLength?: 7 | 8                          // Body digit count (default: 7 or 8)
  format?: 'dotted' | 'compact' | 'hyphen'    // Output shape (default: 'dotted')
  count?: number                              // Return an array of this many RUTs
}

type SafeOptions = {
  throwOnError?: boolean // Throw vs. return null (default: true)
}

type ValidateOptions = {
  strict?: boolean // Reject suspicious placeholders (default: false)
}

type VerifierDigit =
  | '0' | '1' | '2' | '3' | '4' | '5'
  | '6' | '7' | '8' | '9' | 'K'

import { InvalidRutError } from 'rut.ts'
 
class InvalidRutError extends Error {
  readonly code: 'INVALID_RUT'
  // message: 'Invalid RUT input'
}

import { clean, InvalidRutError } from 'rut.ts'
 
try {
  clean('not-a-rut')
} catch (error) {
  if (error instanceof InvalidRutError) {
    // error.code === 'INVALID_RUT'
  }
}

import { isRutLike, validate } from 'rut.ts'
 
function validateRutPipeline(input: unknown): boolean {
  if (typeof input !== 'string') return false
  if (!isRutLike(input)) return false        // cheap reject
  return validate(input, { strict: true })   // authoritative gate
}

import { clean, decompose } from 'rut.ts'
 
function safeProcessRut(input: string) {
  const cleaned = clean(input, { throwOnError: false })
  if (!cleaned) return null
  return decompose(cleaned, { throwOnError: false })
}

import { format, validate } from 'rut.ts'
 
function formatAndValidate(input: string) {
  const formatted = format(input, { throwOnError: false })
  if (!formatted) return { valid: false, formatted: null }
  return { valid: validate(formatted), formatted }
}