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 | /**
* Public types. Type-only: this module emits no runtime code.
*/
/**
* The kinds of Spanish NIF this package validates:
*
* - `"DNI"`: 8 digits + check letter (DNI-1, DNI-2).
* - `"NIF_KLM"`: K, L or M + 7 digits + check letter (KLM-1, KLM-2).
* - `"NIE"`: X, Y or Z + 7 digits + check letter (NIE-1, NIE-2), or the old
* 10-character form (NIE-3).
* - `"CIF"`: NIF of a legal person or entity, organisation key + 7 digits + control
* (CIF-1 to CIF-4).
*
* `validate()` and `getNifType()` report it.
* @example
* validate("X1234567L").type; // "NIE"
* getNifType("K1234567L"); // "NIF_KLM"
* @example
* const accepted: NifType[] = ["DNI", "NIE"];
* validate("B12345674", { types: accepted }).error?.code; // "UNSUPPORTED_TYPE"
* @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 type NifType = "DNI" | "NIE" | "CIF" | "NIF_KLM";
/**
* Why `validate()` rejected a value. See `docs/api-design.md` for the
* SPEC.md rule that goes with each case.
*
* - `"NOT_A_STRING"`: the value is not a string (INPUT-1).
* - `"EMPTY"`: the value is empty, or only separators (INPUT-2).
* - `"INVALID_LENGTH"`: the wrong number of characters.
* - `"INVALID_FORMAT"`: the wrong characters for the document (for
* example letters in the number part), or an unknown first character.
* - `"INVALID_CONTROL_CHARACTER"`: the format is right, the control
* character is not; `error.expected` has the right one.
* - `"UNSUPPORTED_TYPE"`: a document of a type not in `options.types`
* (POLICY-2).
* - `"PLACEHOLDER"`: a placeholder number, with `rejectPlaceholders`
* (POLICY-1).
* @example
* validate("").error?.code; // "EMPTY"
* validate("12345678A").error?.code; // "INVALID_CONTROL_CHARACTER"
* @example
* const code: NifErrorCode | undefined = validate("12345678A").error?.code;
* const hint = code === "INVALID_CONTROL_CHARACTER" ? "check the letter" : "";
* hint; // "check the letter"
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md SPEC.md}
* @since 2.0.0
*/
export type NifErrorCode =
| "NOT_A_STRING"
| "EMPTY"
| "INVALID_LENGTH"
| "INVALID_FORMAT"
| "INVALID_CONTROL_CHARACTER"
| "UNSUPPORTED_TYPE"
| "PLACEHOLDER";
/**
* SPEC.md rules that an `INVALID_LENGTH` error can cite.
* @since 2.0.0
*/
export type NifLengthRule =
| "DNI-1"
| "KLM-1"
| "NIE-1"
| "NIE-3"
| "CIF-1"
| "VAT-1";
/**
* SPEC.md rules that an `INVALID_FORMAT` error can cite.
* @since 2.0.0
*/
export type NifFormatRule =
| "NIF-1"
| "VAT-1"
| "DNI-1"
| "KLM-1"
| "KLM-3"
| "NIE-1"
| "CIF-1";
/**
* The organisation keys of the NIF of a legal person or entity (CIF): its first letter
* (Orden EHA/451/2008 arts. 3 to 5, as amended by Orden HAP/5/2016).
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-2 SPEC.md#cif-2}
* @since 2.0.0
*/
export type CifOrganisationKey =
| "A"
| "B"
| "C"
| "D"
| "E"
| "F"
| "G"
| "H"
| "J"
| "N"
| "P"
| "Q"
| "R"
| "S"
| "U"
| "V"
| "W";
/**
* The error messages of one locale, keyed by error code and, for the length
* and format errors, by the SPEC.md rule that failed, so they describe the
* right document. Every message is a full sentence.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md SPEC.md}
* @since 2.0.0
*/
export interface NifMessages {
NOT_A_STRING: string;
EMPTY: string;
INVALID_LENGTH: Record<NifLengthRule, string>;
INVALID_FORMAT: Record<NifFormatRule, string>;
/** Must include `expected`, the right control character. */
INVALID_CONTROL_CHARACTER: (type: NifType, expected: string) => string;
UNSUPPORTED_TYPE: (type: NifType) => string;
PLACEHOLDER: string;
}
/**
* A language: every text that `validate()` and `describeCifOrganisation()`
* return. English is built in and is the default. The other languages are
* separate imports, so a bundle only contains the languages it imports:
*
* - `nif-dni-nie-cif-validation/locales/es`: Spanish (`es`)
* - `nif-dni-nie-cif-validation/locales/ca`: Catalan, also for Valencian (`ca`)
* - `nif-dni-nie-cif-validation/locales/eu`: Basque (`eu`)
* - `nif-dni-nie-cif-validation/locales/gl`: Galician (`gl`)
* - `nif-dni-nie-cif-validation/locales/en`: English (`en`), the default
*
* @example
* import { validate } from "nif-dni-nie-cif-validation";
* import { es } from "nif-dni-nie-cif-validation/locales/es";
*
* validate("12345678A", { locale: es }).error?.message;
* // 'El carácter de control no es correcto: para este DNI debería ser «Z».'
* @example
* import { describeCifOrganisation } from "nif-dni-nie-cif-validation";
* import { es } from "nif-dni-nie-cif-validation/locales/es";
*
* describeCifOrganisation("B", es); // "Sociedad de responsabilidad limitada"
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-2 SPEC.md#cif-2}
* @since 2.0.0
*/
export interface NifLocale {
/** The BCP 47 language code, for example `"es"`. */
code: string;
/** The name of each document type, as the messages use it. */
types: Record<NifType, string>;
/** The error messages. */
messages: NifMessages;
/**
* What each CIF organisation key stands for, in the singular (CIF-2).
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-2 SPEC.md#cif-2}
*/
organisations: Record<CifOrganisationKey, string>;
}
/**
* Which control characters the NIF of a legal person or entity (CIF) may have (CIF-3):
*
* - `"official"` (the default): what the AEAT D.I.T. note says. A digit for
* A B C D E F G H J U V, a letter for N P Q R S W.
* - `"lenient"`: C D F G J U V accept a letter or a digit, as v1 did. For
* legacy data only: it has no official basis (SPEC.md, "Explicitly NOT
* implemented"). The other keys are unchanged.
*
* @example
* isValidCif("G1234567D"); // false
* isValidCif("G1234567D", { cifControl: "lenient" }); // true
* @example
* isValidCif("B1234567D", { cifControl: "lenient" }); // false: B always takes a digit
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-3 SPEC.md#cif-3}
* @since 2.0.0
*/
export type CifControlMode = "official" | "lenient";
/**
* Options of `validate()`. Every option is optional and defaults to the
* official behaviour.
* @example
* import { es } from "nif-dni-nie-cif-validation/locales/es";
*
* validate("B12345674", { types: ["DNI", "NIE"], locale: es }).error?.message;
* // "Aquí no se admite un NIF de persona jurídica o entidad (CIF)."
* @example
* // v1-compatible parsing, and VAT numbers accepted:
* const v1 = { normalize: false, cifControl: "lenient", allowVatPrefix: true } as const;
* validate("ESG1234567D", v1).valid; // true
* validate("ES G1234567D", v1).valid; // false: normalize: false keeps the space
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md SPEC.md}
* @since 2.0.0
*/
export interface ValidateOptions {
/**
* Accept only these document types. A valid document of another type
* gives `UNSUPPORTED_TYPE` (POLICY-2). Default: every type.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#policy-2 SPEC.md#policy-2}
*/
types?: NifType[];
/**
* Normalize the input before validating it (default `true`): remove white
* space and dots (NORM-2), hyphens and slashes (NORM-3), left-pad a DNI
* with fewer than 8 digits (NORM-4). See `normalize()`.
*
* `false` turns NORM-2 to NORM-4 off, for v1's strict parsing. Lower case
* (NORM-1) and the old 10-character NIE form (NIE-3) are accepted either
* way, as in v1.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#norm-2 SPEC.md#norm-2}
*/
normalize?: boolean;
/**
* Control characters accepted for the NIF of a legal person or entity (CIF). Default
* `"official"`. See {@link CifControlMode}.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-3 SPEC.md#cif-3}
*/
cifControl?: CifControlMode;
/**
* Reject the placeholder numbers `00000000T`, `00000001R`, `99999999R`
* and `X0000000T` (default `false`). They are valid documents, so they
* are accepted by default; ESNIC filters them as obviously fake.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#policy-1 SPEC.md#policy-1}
*/
rejectPlaceholders?: boolean;
/**
* Accept a Spanish VAT number, `ES` + NIF, as well as a bare NIF
* (default `false`). `normalized` is always the NIF, without `ES`.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#vat-1 SPEC.md#vat-1}
*/
allowVatPrefix?: boolean;
/**
* Language of `error.message` and `meta.orgDescription`: a locale object
* imported from `nif-dni-nie-cif-validation/locales/<code>` (default:
* English). See {@link NifLocale}.
*
* Anything else is ignored and gives English, without throwing. That
* includes a language code such as `"es"`, which pre-release versions of
* the v2 docs showed: import the locale object instead. A locale object
* that lacks a text (plain JavaScript) gives English for that text.
*/
locale?: NifLocale;
}
/**
* Options of the boolean validators (`isValidNif` and the others): the
* options of `validate()` that change the verdict.
* @example
* isValidNif(" 12.345.678-Z "); // true (normalized)
* isValidNif(" 12.345.678-Z ", { normalize: false }); // false, as in v1
* @example
* const v1Compatible: IsValidOptions = { normalize: false, cifControl: "lenient" };
* isValidCif("G1234567D", v1Compatible); // true, as in v1
* @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 type IsValidOptions = Pick<
ValidateOptions,
"normalize" | "cifControl" | "rejectPlaceholders"
>;
/**
* Options of `getNifType()`: the options that change what is parsed.
* @example
* getNifType("ES12345678Z"); // null
* getNifType("ES12345678Z", { allowVatPrefix: true }); // "DNI"
* @example
* getNifType(" 12345678Z", { normalize: false }); // null: the space is kept
* @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 type GetNifTypeOptions = Pick<
ValidateOptions,
"normalize" | "allowVatPrefix"
>;
/**
* Why a value is invalid: `validate(value).error`.
* @example
* validate("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
* validate("T12345678").error;
* // { code: "INVALID_FORMAT", rule: "NIF-1",
* // message: "This is not a NIF, NIE or CIF: it must start with a digit or a valid letter." }
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md SPEC.md}
* @since 2.0.0
*/
export interface NifValidationError {
/** What went wrong. */
code: NifErrorCode;
/** A message for the user, in the requested locale. */
message: string;
/** The SPEC.md rule ID that failed, for example `"DNI-2"`. */
rule: string;
/**
* The correct control character, only with
* `INVALID_CONTROL_CHARACTER`.
*/
expected?: string;
}
/**
* What the organisation key of the NIF of a legal person or entity (CIF) says about the
* entity (Orden EHA/451/2008 arts. 3 to 5, as amended by Orden HAP/5/2016).
* @example
* validate("B12345674").meta;
* // { orgKey: "B", orgDescription: "Limited liability company" }
* @example
* import { es } from "nif-dni-nie-cif-validation/locales/es";
*
* validate("P2807900B", { locale: es }).meta?.orgDescription; // "Corporación local"
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-2 SPEC.md#cif-2}
* @since 2.0.0
*/
export interface CifOrganisationMeta {
/** The organisation key, for example `"B"`. */
orgKey: string;
/**
* Its description in the requested locale, for example
* `"Limited liability company"` / `"Sociedad de responsabilidad
* limitada"`.
*/
orgDescription: string;
}
/**
* The result of `validate()`.
* @example
* validate(" x-0123456-7l ");
* // { valid: true, type: "NIE", normalized: "X1234567L" }
* @example
* import { es } from "nif-dni-nie-cif-validation/locales/es";
*
* const { valid, normalized, error } = validate("12345678A", { locale: es });
* valid; // false
* normalized; // "12345678A"
* error?.code; // "INVALID_CONTROL_CHARACTER"
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md SPEC.md}
* @since 2.0.0
*/
export interface ValidationResult {
/** Whether the value is a valid document (with the given options). */
valid: boolean;
/**
* The document type, as soon as the format is recognisable, even if the
* control character is wrong. `null` otherwise.
*/
type: NifType | null;
/**
* The canonical official form (upper case, no separators, old NIE form
* collapsed, short DNI padded, no `ES` VAT prefix), when the format is
* recognisable. `null` otherwise.
*/
normalized: string | null;
/** Why the value is invalid; absent when it is valid. */
error?: NifValidationError;
/**
* For the NIF of a legal person or entity (CIF) only, whenever `type` is `"CIF"` (valid
* or not): its organisation key and what it means.
* @see {@link https://github.com/josegoval/nif-dni-nie-cif-validation/blob/master/SPEC.md#cif-2 SPEC.md#cif-2}
*/
meta?: CifOrganisationMeta;
}
|