Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 | 28x 28x 529797x 561714x 2882231x 2873436x 5126240x 4473359x 3149858x 1605141x 28644x 663039x 1258331x 1258331x 8808317x 1258331x 1258331x 1258331x 595292x 663039x 1258331x 523594x 523594x 523594x 523594x 523594x 523594x 523594x 523594x 523594x 270434x 253160x 523594x 2882231x 2882231x 2873436x 44933x 15111x 15111x 2836353x 2836353x 2836353x 2807711x 522536x 392163x 269161x 124468x 2285175x 2285175x 653858x 130264x 523594x 1631317x 194808x 1436509x 178178x 1258331x 28x 2072472x 2069978x 1766392x 518250x 518250x 1766392x 2892600x 2892600x 32171x 32763x 2860429x 2892600x 1094037x 1095663x 1094037x 1766392x 1766392x 1766392x 1766392x 56295x 56534x 1710097x 886894x 886924x 823203x 581x 588x 822622x 10791x 9414x 10791x | /**
* `validate()` and `getNifType()`: the detailed API. Where the boolean
* validators answer "valid or not" as fast as possible, `validate()` says
* which document it is, its canonical form, and, when it is invalid, why:
* an error code, the SPEC.md rule that failed, a message in the caller's
* language (a locale object, src/locales/; English by default), and the
* expected control character.
*
* The steps, in order (the first failure wins):
*
* 1. INPUT-1: only strings. INPUT-2: not empty after cleanup.
* 2. NORM-1 to NORM-4 and NIE-3: the canonical form. VAT-1: an `ES`
* prefix only with `allowVatPrefix`.
* 3. NIF-1: the first character selects one format: a digit (DNI-1), K L M
* (KLM-1), X Y Z (NIE-1) or an organisation key (CIF-2).
* 4. That format's length, digits and control position (DNI-1, KLM-1,
* KLM-3, NIE-1, NIE-3, CIF-1). From here the type is known.
* 5. POLICY-2: the caller's `types`.
* 6. The control character: DNI-2, DNI-3, KLM-2, NIE-2, CIF-3, CIF-4.
* 7. POLICY-1: placeholders, with `rejectPlaceholders`.
*
* Rule IDs refer to SPEC.md.
*/
import {
cifControlValue,
cifKeyKind,
LEGAL_ENTITY_CONTROL_LETTERS,
LENIENT_KEY_CONTROL,
LETTER_CONTROL,
NOT_A_KEY,
} from "./cif";
import { DNI_CONTROL_LETTERS } from "./dni";
import { localize } from "./localize";
import {
areDigits,
canonicalize,
cleanup,
isUpperLetter,
upperCase,
} from "./normalize";
import { describeCifOrganisation } from "./organisations";
import { PLACEHOLDERS } from "./policy";
import type {
NifFormatRule as FormatRule,
GetNifTypeOptions,
NifLengthRule as LengthRule,
NifLocale,
NifMessages,
NifType,
NifValidationError,
ValidateOptions,
ValidationResult,
} from "./types";
/** Every NIF has 9 characters in canonical form. */
const NIF_LENGTH = 9;
/** SPEC.md rules that `INVALID_CONTROL_CHARACTER` can cite. */
type ControlRule = "DNI-2" | "DNI-3" | "KLM-2" | "NIE-2" | "CIF-3" | "CIF-4";
/** A problem found before the type is known. */
type FormatProblem =
| { code: "EMPTY"; rule: "INPUT-2" }
| { code: "INVALID_LENGTH"; rule: LengthRule }
| { code: "INVALID_FORMAT"; rule: FormatRule };
/** A recognised document, valid or with a wrong control character. */
interface Document {
type: NifType;
/** Canonical form. */
normalized: string;
/** The control problem, or `null` when the control character is right. */
control: { rule: ControlRule; expected: string } | null;
}
/** What `inspect` found: a document, or why there is none. */
type Inspection = Document | FormatProblem;
const EMPTY: FormatProblem = { code: "EMPTY", rule: "INPUT-2" };
function lengthProblem(rule: LengthRule): FormatProblem {
return { code: "INVALID_LENGTH", rule };
}
function formatProblem(rule: FormatRule): FormatProblem {
return { code: "INVALID_FORMAT", rule };
}
/** NORM-1..3, or NORM-1 only with `normalize: false`. Internal helper. */
function cleanNif(value: string, normalize: boolean): string {
return normalize ? cleanup(value) : upperCase(value);
}
/** VAT-1: does the cleaned value start with the `ES` prefix? */
function hasVatPrefix(clean: string): boolean {
return clean.charCodeAt(0) === 69 && clean.charCodeAt(1) === 83;
}
/** NIF-1: the type selected by the first character of a canonical value. */
export function typeOf(first: number): NifType | null {
// DNI-1: a digit.
if ((first - 48) >>> 0 < 10) return "DNI";
// KLM-1: K, L or M.
if ((first - 75) >>> 0 < 3) return "NIF_KLM";
// NIE-1: X, Y or Z.
if ((first - 88) >>> 0 < 3) return "NIE";
// CIF-2: an organisation key.
if (cifKeyKind(first) !== NOT_A_KEY) return "CIF";
return null;
}
/** DNI-3: I, Ñ, O and U are never check letters. */
function isNeverACheckLetter(code: number): boolean {
return code === 73 || code === 0xd1 || code === 79 || code === 85;
}
/**
* DNI-2, KLM-2, NIE-2: checks the letter of a DNI, K/L/M NIF or NIE whose
* format is already checked.
*/
function checkLetter(value: string, type: NifType): Document {
// DNI-2: the 8 digits. KLM-2: the 7 digits only. NIE-2: X -> 0, Y -> 1,
// Z -> 2, then the 7 digits.
const first = value.charCodeAt(0);
let number = type === "DNI" ? first - 48 : type === "NIE" ? first - 88 : 0;
for (let i = 1; i < 8; i++) number = number * 10 + value.charCodeAt(i) - 48;
const expected = DNI_CONTROL_LETTERS.charAt(number % 23);
const code = value.charCodeAt(8);
if (code === expected.charCodeAt(0))
return { type, normalized: value, control: null };
const rule: ControlRule = isNeverACheckLetter(code)
? "DNI-3"
: type === "DNI"
? "DNI-2"
: type === "NIE"
? "NIE-2"
: "KLM-2";
return { type, normalized: value, control: { rule, expected } };
}
/** CIF-3, CIF-4: checks the control of a NIF of a legal person or entity (CIF). */
function checkCifControl(value: string, lenient: boolean): Document {
// CIF-4: the control value; CIF-3: the key decides digit or letter.
const control = cifControlValue(value);
const digit = String(control);
const letter = LEGAL_ENTITY_CONTROL_LETTERS.charAt(control);
const kind = cifKeyKind(value.charCodeAt(0));
const either = kind === LENIENT_KEY_CONTROL && lenient;
const code = value.charCodeAt(8);
const isDigit = (code - 48) >>> 0 < 10;
// CIF-3: which class the key accepts: A B E H (and C D F G J U V in
// official mode) a digit, N P Q R S W a letter; lenient C D F G J U V
// either.
const classAccepted =
either || (isDigit ? kind !== LETTER_CONTROL : kind === LETTER_CONTROL);
if (classAccepted && code === (isDigit ? digit : letter).charCodeAt(0))
return { type: "CIF", normalized: value, control: null };
const expected =
kind === LETTER_CONTROL || (either && !isDigit) ? letter : digit;
return {
type: "CIF",
normalized: value,
control: { rule: classAccepted ? "CIF-4" : "CIF-3", expected },
};
}
/**
* Parses and checks `value`: everything `validate` needs except the
* options that only filter the verdict (`types`, `rejectPlaceholders`).
*/
export function inspect(
value: string,
normalize: boolean,
lenient: boolean,
allowVatPrefix: boolean
): Inspection {
// NORM-1..3 (or NORM-1 only, as v1 did, with normalize: false).
let clean = cleanNif(value, normalize);
// INPUT-2: nothing left.
if (clean.length === 0) return EMPTY;
// VAT-1: "ES" + NIF. No NIF starts with "ES" (an E key is followed by a
// digit), so the prefix is unambiguous.
if (hasVatPrefix(clean)) {
if (!allowVatPrefix) return formatProblem("VAT-1");
clean = clean.slice(2);
if (clean.length === 0) return lengthProblem("VAT-1");
}
// NIE-3 always; NORM-4 only when normalizing.
const canonical = canonicalize(clean, normalize);
// NIF-1: the first character selects the format.
const type = typeOf(canonical.charCodeAt(0));
if (type === null) return formatProblem("NIF-1");
if (canonical.length !== NIF_LENGTH) {
if (type === "DNI") return lengthProblem("DNI-1");
if (type === "NIF_KLM") return lengthProblem("KLM-1");
if (type === "CIF") return lengthProblem("CIF-1");
// NIE-3: only old X0 NIEs have 10 characters.
return lengthProblem(canonical.length === 10 ? "NIE-3" : "NIE-1");
}
const last = canonical.charCodeAt(8);
if (type === "CIF") {
// CIF-1: key + 7 digits + a control character (a digit or a letter).
if (
!areDigits(canonical, 1, 8) ||
!((last - 65) >>> 0 < 26 || (last - 48) >>> 0 < 10)
)
return formatProblem("CIF-1");
return checkCifControl(canonical, lenient);
}
// DNI-1: 8 digits. KLM-3: 7 digits after K, L or M. NIE-1: 7 digits
// after X, Y or Z.
if (!areDigits(canonical, type === "DNI" ? 0 : 1, 8))
return formatProblem(
type === "DNI" ? "DNI-1" : type === "NIE" ? "NIE-1" : "KLM-3"
);
// DNI-1, KLM-1, NIE-1: the control character is a letter.
if (!isUpperLetter(last))
return formatProblem(
type === "DNI" ? "DNI-1" : type === "NIE" ? "NIE-1" : "KLM-1"
);
return checkLetter(canonical, type);
}
const NO_VALIDATE_OPTIONS: ValidateOptions = {};
/** An error message in the caller's locale, or in English. */
function text(
locale: NifLocale | undefined,
pick: (messages: NifMessages) => string
): string {
return localize(locale, (l) => pick(l.messages));
}
function invalid(
type: NifType | null,
normalized: string | null,
error: NifValidationError
): ValidationResult {
return { valid: false, type, normalized, error };
}
/** CIF-2: adds the organisation key and its description to a CIF result. */
function withMeta(
result: ValidationResult,
locale: NifLocale | undefined
): ValidationResult {
if (result.type === "CIF") {
const orgKey = (result.normalized as string).charAt(0);
result.meta = {
orgKey,
orgDescription: describeCifOrganisation(orgKey, locale) as string,
};
}
return result;
}
/**
* Validates a Spanish NIF (DNI, K/L/M NIF, NIE or NIF of a legal person or entity,
* formerly CIF) and explains the result.
*
* - `valid`: whether it is a valid document with these options.
* - `type`: `"DNI"`, `"NIF_KLM"`, `"NIE"` or `"CIF"`, as soon as the format
* is recognisable, even if the control character is wrong.
* - `normalized`: the canonical form to store (upper case, no separators).
* - `error`: `code`, the SPEC.md `rule` that failed, a `message` for the
* user (in the `locale`, English by default), and `expected` (the right
* control character) when the control character is wrong.
* - `meta`: for a CIF, its organisation key and what it means (Orden
* EHA/451/2008 arts. 3 to 5), in the requested locale.
*
* Defaults follow SPEC.md: the input is normalized (NORM-1 to NORM-4, NIE-3)
* and CIFs follow CIF-3. Never throws.
*
* Languages are locale objects, imported one by one so that a bundle only
* has the ones it uses: `import { es } from
* "nif-dni-nie-cif-validation/locales/es"`, then `{ locale: es }`. Anything
* else as `locale`, including a language code string such as `"es"`, gives
* English. See {@link NifLocale}.
*
* @param value The value to validate, typically untrusted form input.
* @param opts `types`, `normalize`, `cifControl`, `rejectPlaceholders`,
* `allowVatPrefix`, `locale`. See {@link ValidateOptions}.
* @returns A result object, allocated on every call: `valid` is `true` only
* for a valid document (with these options), and then `error` is absent.
* Otherwise `error` says why (`code`, `rule`, `message` and, for a wrong
* control character, `expected`), and `type`, `normalized` and `meta` are
* set as far as the format was recognisable (`null` where it was not).
* @example
* validate("12345678A");
* // { valid: false, type: "DNI", normalized: "12345678A",
* // error: { code: "INVALID_CONTROL_CHARACTER", rule: "DNI-2", expected: "Z",
* // message: 'The control character is not correct: for this DNI it should be "Z".' } }
* @example
* import { es } from "nif-dni-nie-cif-validation/locales/es";
*
* validate(" b-1234567-4 ", { locale: es });
* // { valid: true, type: "CIF", normalized: "B12345674",
* // meta: { orgKey: "B", orgDescription: "Sociedad de responsabilidad limitada" } }
* @example
* validate("G1234567D").error?.rule; // "CIF-3"
* validate("G1234567D", { cifControl: "lenient" }).valid; // true
* validate("12345678Z", { types: ["CIF"] }).error?.code; // "UNSUPPORTED_TYPE"
* validate(null).error?.code; // "NOT_A_STRING"
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-3 SPEC.md#cif-3}
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#norm-2 SPEC.md#norm-2}
* @since 2.0.0
*/
export function validate(
value: unknown,
opts: ValidateOptions = NO_VALIDATE_OPTIONS
): ValidationResult {
const locale = opts?.locale;
// INPUT-1: only strings, never converted.
if (typeof value !== "string")
return invalid(null, null, {
code: "NOT_A_STRING",
message: text(locale, (m) => m.NOT_A_STRING),
rule: "INPUT-1",
});
const found = inspect(
value,
opts?.normalize !== false,
opts?.cifControl === "lenient",
opts?.allowVatPrefix === true
);
if (!("type" in found)) {
const message = text(locale, (m) =>
found.code === "EMPTY"
? m.EMPTY
: found.code === "INVALID_LENGTH"
? m.INVALID_LENGTH[found.rule]
: m.INVALID_FORMAT[found.rule]
);
return invalid(null, null, { code: found.code, message, rule: found.rule });
}
return withMeta(check(found, opts, locale), locale);
}
/** Steps 5 to 7 of `validate`, on a recognised document. */
function check(
found: Document,
opts: ValidateOptions,
locale: NifLocale | undefined
): ValidationResult {
const { type, normalized, control } = found;
// POLICY-2: the caller accepts only some types.
const types = opts?.types;
if (Array.isArray(types) && !types.includes(type))
return invalid(type, normalized, {
code: "UNSUPPORTED_TYPE",
message: text(locale, (m) => m.UNSUPPORTED_TYPE(type)),
rule: "POLICY-2",
});
if (control !== null)
return invalid(type, normalized, {
code: "INVALID_CONTROL_CHARACTER",
message: text(locale, (m) =>
m.INVALID_CONTROL_CHARACTER(type, control.expected)
),
rule: control.rule,
expected: control.expected,
});
// POLICY-1: placeholders, only when asked.
if (opts?.rejectPlaceholders === true && PLACEHOLDERS.includes(normalized))
return invalid(type, normalized, {
code: "PLACEHOLDER",
message: text(locale, (m) => m.PLACEHOLDER),
rule: "POLICY-1",
});
return { valid: true, type, normalized };
}
/**
* Detects the document type from its format, **without checking the control
* character**: the type `validate` would report. A non-null result does not
* mean the document is valid; use `validate` or a boolean for that.
*
* Returns `null` when the format isn't recognisable: an unknown first
* character (NIF-1), the wrong length, non-digits in the number, or a
* control character of the wrong class. The input is normalized first
* unless `{ normalize: false }`. An `ES` VAT prefix is accepted only with
* `{ allowVatPrefix: true }`. Never throws.
*
* @param value The value to inspect.
* @param opts `normalize` (default `true`), `allowVatPrefix` (default
* `false`).
* @returns `"DNI"`, `"NIF_KLM"`, `"NIE"`, `"CIF"` or `null`.
* @example
* getNifType("12345678Z"); // "DNI"
* getNifType("12345678A"); // "DNI" (wrong letter, but a DNI's format)
* getNifType("k1234567l"); // "NIF_KLM"
* @example
* getNifType("B1234567D"); // "CIF" (B needs a digit: invalid, but a CIF)
* getNifType("T1234567A"); // null (no document starts with T, NIF-1)
* getNifType("123456789"); // null (a DNI ends in a letter, DNI-1)
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#nif-1 SPEC.md#nif-1}
* @since 2.0.0
*/
export function getNifType(
value: unknown,
opts: GetNifTypeOptions = NO_VALIDATE_OPTIONS
): NifType | null {
if (typeof value !== "string") return null;
const found = inspect(
value,
opts?.normalize !== false,
false,
opts?.allowVatPrefix === true
);
return "type" in found ? found.type : null;
}
|