@maistik/validate-nif 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maistik Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# @maistik/validate-nif
+
+[![CI](https://github.com/Maistik-Studio/validate-nif/actions/workflows/ci.yml/badge.svg)](https://github.com/Maistik-Studio/validate-nif/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@maistik/validate-nif.svg)](https://www.npmjs.com/package/@maistik/validate-nif)
+[![license](https://img.shields.io/npm/l/@maistik/validate-nif.svg)](./LICENSE)
+
+Zero-dependency, **isomorphic** (Node.js & browser) validator for Spanish fiscal
+identifiers, written in TypeScript with full type definitions included.
+
+- ✅ **DNI / NIF** — natural persons, residents (`12345678Z`)
+- ✅ **NIE** — natural persons, foreigners (`X1234567L`)
+- ✅ **CIF** — legal entities / organizations (`A58818501`)
+- 🧮 Official AEAT control-character algorithms
+- 🪶 No dependencies, tree-shakeable, ESM + CommonJS builds
+- 🛡️ Never throws — any input (including `null`/`undefined`/numbers) is handled
+- 🧪 100% test coverage
+
+## Installation
+
+```bash
+# npm
+npm install @maistik/validate-nif
+
+# pnpm
+pnpm add @maistik/validate-nif
+
+# yarn
+yarn add @maistik/validate-nif
+```
+
+## Usage
+
+### ESM / TypeScript
+
+```ts
+import { isValid, isValidDNI, isValidNIE, isValidCIF, getType } from '@maistik/validate-nif'
+
+isValidDNI('12345678Z')   // true
+isValidNIE('X1234567L')   // true
+isValidCIF('A58818501')   // true
+
+isValid('12345678Z')      // true (any supported type)
+getType('X1234567L')      // 'NIE'
+
+// Loosely formatted input is normalized automatically.
+isValid(' 12.345.678-z ') // true
+```
+
+### CommonJS
+
+```js
+const { validateNif, isValid } = require('@maistik/validate-nif')
+
+isValid('A58818501') // true
+```
+
+### Browser
+
+The package ships an ESM build with no Node.js dependencies, so it works
+directly in the browser via any bundler (Vite, webpack, Rollup, esbuild) or
+straight from a CDN:
+
+```html
+<script type="module">
+  import { isValid } from 'https://esm.sh/@maistik/validate-nif'
+  console.log(isValid('12345678Z')) // true
+</script>
+```
+
+## API
+
+All functions accept `unknown` input and never throw.
+
+| Function | Returns | Description |
+| --- | --- | --- |
+| `isValid(value)` | `boolean` | `true` for a valid DNI, NIE **or** CIF. |
+| `isValidNIF(value)` | `boolean` | `true` for a valid DNI **or** NIE (natural person). |
+| `isValidDNI(value)` | `boolean` | `true` for a valid DNI / NIF. |
+| `isValidNIE(value)` | `boolean` | `true` for a valid NIE. |
+| `isValidCIF(value)` | `boolean` | `true` for a valid CIF. |
+| `getType(value)` | `'DNI' \| 'NIE' \| 'CIF' \| null` | The detected type, or `null` if invalid. |
+| `getCifOrganizationType(value)` | `{ code, description } \| null` | The organization type for a valid CIF, or `null`. |
+| `parse(value)` | `NifInfo` | Structured info: `{ valid, type, normalized, organization }`. |
+| `format(value, options?)` | `string` | Canonical form; `options.separator` inserts a separator before the control char. |
+| `normalize(value)` | `string` | Upper-cases and strips spaces, dots, hyphens and underscores. |
+| `controlLetterFor(num)` | `string` | The DNI/NIE control letter for an 8-digit number. |
+| `validateNif(value)` | `number` | Legacy numeric code (see below). |
+
+### Parsing & organization types
+
+```ts
+import { parse, getCifOrganizationType, format } from '@maistik/validate-nif'
+
+parse('a-58818501')
+// {
+//   valid: true,
+//   type: 'CIF',
+//   normalized: 'A58818501',
+//   organization: { code: 'A', description: 'Sociedad anónima' },
+// }
+
+getCifOrganizationType('G12345678') // { code: 'G', description: 'Asociación o fundación' }
+
+format('12345678z', { separator: '-' }) // '12345678-Z'
+```
+
+A CIF's leading letter is mapped to its Spanish organization type (Sociedad
+anónima, Sociedad de responsabilidad limitada, Cooperativa, Asociación,
+Corporación local, and so on — the full AEAT set is supported).
+
+### `validateNif` result codes
+
+`validateNif` is kept for backwards compatibility. It returns a numeric code:
+negative means **invalid**, `>= 0` means **valid**.
+
+| Code | Constant | Meaning |
+| --- | --- | --- |
+| `-1` | `ValidationResult.ERROR` | Invalid / unknown value |
+| `1` | `ValidationResult.DNI` | Valid DNI / NIF |
+| `4` | `ValidationResult.NIE` | Valid NIE |
+| `20` | `ValidationResult.CIF` | Valid CIF |
+
+```ts
+import { validateNif, ValidationResult } from '@maistik/validate-nif'
+
+validateNif('62805436A') // 1  (>= 0 → valid)
+validateNif('62805436X') // -1 (< 0 → invalid)
+validateNif('A58818501') === ValidationResult.CIF // true
+```
+
+## Types
+
+Type declarations (`.d.ts`) are bundled and exposed automatically — no
+`@types/*` package is required. The package also exports the `NifType`,
+`NifInfo`, `CifOrganizationType`, `FormatOptions` and `ValidationResultCode`
+helper types.
+
+## Development
+
+```bash
+pnpm install
+pnpm test:coverage   # tests with 100% coverage enforcement
+pnpm lint            # eslint
+pnpm typecheck       # tsc --noEmit
+pnpm build           # build dist/ (ESM + CJS + .d.ts)
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contribution guide.
+
+## License
+
+[MIT](./LICENSE) © Maistik Studio

package/dist/index.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const ValidationResult = {
+  /** Unknown or malformed value. */
+  ERROR: -1,
+  /** Valid DNI / NIF (Spanish resident). */
+  DNI: 1,
+  /** Valid NIE (foreigner). */
+  NIE: 4,
+  /** Valid CIF (organization). */
+  CIF: 20
+};
+const DNI_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
+const CIF_LETTERS = "JABCDEFGHI";
+const CIF_LETTER_CONTROL = "NPQRSW";
+const CIF_DIGIT_CONTROL = "ABEH";
+const NIE_PREFIX = { X: "0", Y: "1", Z: "2" };
+const CIF_ORGANIZATION_TYPES = {
+  A: "Sociedad an\xF3nima",
+  B: "Sociedad de responsabilidad limitada",
+  C: "Sociedad colectiva",
+  D: "Sociedad comanditaria",
+  E: "Comunidad de bienes y herencias yacentes",
+  F: "Sociedad cooperativa",
+  G: "Asociaci\xF3n o fundaci\xF3n",
+  H: "Comunidad de propietarios en r\xE9gimen de propiedad horizontal",
+  J: "Sociedad civil",
+  N: "Entidad extranjera",
+  P: "Corporaci\xF3n local",
+  Q: "Organismo p\xFAblico",
+  R: "Congregaci\xF3n o instituci\xF3n religiosa",
+  S: "\xD3rgano de la Administraci\xF3n del Estado o comunidad aut\xF3noma",
+  U: "Uni\xF3n temporal de empresas",
+  V: "Otro tipo de entidad sin personalidad jur\xEDdica",
+  W: "Establecimiento permanente de entidad no residente"
+};
+const DNI_RE = /^\d{8}[A-Z]$/;
+const NIE_RE = /^[XYZ]\d{7}[A-Z]$/;
+const CIF_RE = /^[ABCDEFGHJNPQRSUVW]\d{7}[0-9A-J]$/;
+function normalize(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  const str = typeof value === "string" ? value : String(value);
+  return str.toUpperCase().replace(/[\s.\-_]/g, "");
+}
+function controlLetterFor(num) {
+  return DNI_LETTERS[num % 23];
+}
+function isValidDNI(value) {
+  const v = normalize(value);
+  if (!DNI_RE.test(v)) {
+    return false;
+  }
+  const num = parseInt(v.slice(0, 8), 10);
+  return v[8] === controlLetterFor(num);
+}
+function isValidNIE(value) {
+  const v = normalize(value);
+  if (!NIE_RE.test(v)) {
+    return false;
+  }
+  const num = parseInt(NIE_PREFIX[v[0]] + v.slice(1, 8), 10);
+  return v[8] === controlLetterFor(num);
+}
+function isValidCIF(value) {
+  const v = normalize(value);
+  if (!CIF_RE.test(v)) {
+    return false;
+  }
+  const firstLetter = v[0];
+  const digits = v.slice(1, 8);
+  const control = v[8];
+  let sum = 0;
+  for (let i = 0; i < digits.length; i += 1) {
+    let n = parseInt(digits[i], 10);
+    if (i % 2 === 0) {
+      n *= 2;
+      if (n > 9) {
+        n -= 9;
+      }
+    }
+    sum += n;
+  }
+  const controlDigit = (10 - sum % 10) % 10;
+  const controlLetter = CIF_LETTERS[controlDigit];
+  if (CIF_LETTER_CONTROL.includes(firstLetter)) {
+    return control === controlLetter;
+  }
+  if (CIF_DIGIT_CONTROL.includes(firstLetter)) {
+    return control === String(controlDigit);
+  }
+  return control === String(controlDigit) || control === controlLetter;
+}
+function isValidNIF(value) {
+  return isValidDNI(value) || isValidNIE(value);
+}
+function isValid(value) {
+  return isValidDNI(value) || isValidNIE(value) || isValidCIF(value);
+}
+function getType(value) {
+  if (isValidDNI(value)) {
+    return "DNI";
+  }
+  if (isValidNIE(value)) {
+    return "NIE";
+  }
+  if (isValidCIF(value)) {
+    return "CIF";
+  }
+  return null;
+}
+function getCifOrganizationType(value) {
+  if (!isValidCIF(value)) {
+    return null;
+  }
+  const code = normalize(value)[0];
+  return { code, description: CIF_ORGANIZATION_TYPES[code] };
+}
+function parse(value) {
+  const normalized = normalize(value);
+  const type = getType(value);
+  return {
+    valid: type !== null,
+    type,
+    normalized,
+    organization: type === "CIF" ? getCifOrganizationType(value) : null
+  };
+}
+function format(value, options = {}) {
+  const v = normalize(value);
+  const separator = options.separator ?? "";
+  if (!separator || !isValid(v)) {
+    return v;
+  }
+  return `${v.slice(0, -1)}${separator}${v.slice(-1)}`;
+}
+function validateNif(value) {
+  if (isValidDNI(value)) {
+    return ValidationResult.DNI;
+  }
+  if (isValidNIE(value)) {
+    return ValidationResult.NIE;
+  }
+  if (isValidCIF(value)) {
+    return ValidationResult.CIF;
+  }
+  return ValidationResult.ERROR;
+}
+
+exports.ValidationResult = ValidationResult;
+exports.controlLetterFor = controlLetterFor;
+exports.default = validateNif;
+exports.format = format;
+exports.getCifOrganizationType = getCifOrganizationType;
+exports.getType = getType;
+exports.isValid = isValid;
+exports.isValidCIF = isValidCIF;
+exports.isValidDNI = isValidDNI;
+exports.isValidNIE = isValidNIE;
+exports.isValidNIF = isValidNIF;
+exports.normalize = normalize;
+exports.parse = parse;
+exports.validateNif = validateNif;

package/dist/index.d.cts

@@ -0,0 +1,99 @@
+/**
+ * validate-nif
+ *
+ * Zero-dependency, isomorphic (Node & browser) validator for Spanish fiscal
+ * identifiers:
+ *
+ *   - DNI / NIF — natural persons, residents (8 digits + control letter)
+ *   - NIE       — natural persons, foreigners (X/Y/Z + 7 digits + control letter)
+ *   - CIF       — legal entities / organizations (letter + 7 digits + control)
+ *
+ * The control-character algorithms follow the official AEAT specification.
+ */
+/** The kind of a valid Spanish fiscal identifier. */
+type NifType = 'DNI' | 'NIE' | 'CIF';
+/** The organization type encoded in the first letter of a CIF. */
+interface CifOrganizationType {
+    /** The CIF leading letter (e.g. `'A'`). */
+    code: string;
+    /** Human-readable description of the organization type (in Spanish). */
+    description: string;
+}
+/** Structured result describing a parsed identifier. */
+interface NifInfo {
+    /** Whether the value is a valid DNI, NIE or CIF. */
+    valid: boolean;
+    /** The detected type, or `null` when invalid. */
+    type: NifType | null;
+    /** The normalized (upper-cased, separator-free) value. */
+    normalized: string;
+    /** The organization details, only present for a valid CIF. */
+    organization: CifOrganizationType | null;
+}
+/** Options for {@link format}. */
+interface FormatOptions {
+    /** Separator inserted before the control character (e.g. `'-'`). */
+    separator?: string;
+}
+/**
+ * Numeric result codes returned by {@link validateNif}.
+ * Negative values mean invalid; values `>= 0` mean valid.
+ */
+declare const ValidationResult: {
+    /** Unknown or malformed value. */
+    readonly ERROR: -1;
+    /** Valid DNI / NIF (Spanish resident). */
+    readonly DNI: 1;
+    /** Valid NIE (foreigner). */
+    readonly NIE: 4;
+    /** Valid CIF (organization). */
+    readonly CIF: 20;
+};
+type ValidationResultCode = (typeof ValidationResult)[keyof typeof ValidationResult];
+/**
+ * Normalize any input into an upper-cased string with the common separators
+ * (spaces, dots, hyphens, underscores) removed. Non-string and nullish values
+ * are coerced safely, so the public API never throws.
+ */
+declare function normalize(value: unknown): string;
+/** Compute the control letter for an 8-digit DNI / NIE number. */
+declare function controlLetterFor(num: number): string;
+/** Validate a Spanish DNI / NIF (8 digits + control letter). */
+declare function isValidDNI(value: unknown): boolean;
+/** Validate a Spanish NIE (X/Y/Z + 7 digits + control letter). */
+declare function isValidNIE(value: unknown): boolean;
+/** Validate a Spanish CIF (letter + 7 digits + control digit/letter). */
+declare function isValidCIF(value: unknown): boolean;
+/** Validate a NIF for a natural person (DNI or NIE). */
+declare function isValidNIF(value: unknown): boolean;
+/** Validate any supported Spanish fiscal identifier (DNI, NIE or CIF). */
+declare function isValid(value: unknown): boolean;
+/** Detect the type of a valid identifier, or `null` when it is invalid. */
+declare function getType(value: unknown): NifType | null;
+/**
+ * Resolve the organization type for a valid CIF from its leading letter, or
+ * `null` when the value is not a valid CIF.
+ */
+declare function getCifOrganizationType(value: unknown): CifOrganizationType | null;
+/**
+ * Parse a value into a structured {@link NifInfo} object describing its
+ * validity, type, normalized form and (for CIFs) organization details.
+ */
+declare function parse(value: unknown): NifInfo;
+/**
+ * Return the canonical (normalized, upper-cased) representation of an
+ * identifier. When a `separator` is provided it is inserted before the control
+ * character — e.g. `format('12345678z', { separator: '-' })` → `'12345678-Z'`.
+ * Invalid values are returned normalized without a separator.
+ */
+declare function format(value: unknown, options?: FormatOptions): string;
+/**
+ * Backwards-compatible validator returning a numeric {@link ValidationResult}
+ * code. Negative values mean invalid; values `>= 0` mean valid.
+ */
+declare function validateNif(value: unknown): ValidationResultCode;
+
+// @ts-ignore
+export = validateNif;
+export { ValidationResult, controlLetterFor, format, getCifOrganizationType, getType, isValid, isValidCIF, isValidDNI, isValidNIE, isValidNIF, normalize, parse, validateNif };
+export type { CifOrganizationType, FormatOptions, NifInfo, NifType, ValidationResultCode };

package/dist/index.d.mts

@@ -0,0 +1,97 @@
+/**
+ * validate-nif
+ *
+ * Zero-dependency, isomorphic (Node & browser) validator for Spanish fiscal
+ * identifiers:
+ *
+ *   - DNI / NIF — natural persons, residents (8 digits + control letter)
+ *   - NIE       — natural persons, foreigners (X/Y/Z + 7 digits + control letter)
+ *   - CIF       — legal entities / organizations (letter + 7 digits + control)
+ *
+ * The control-character algorithms follow the official AEAT specification.
+ */
+/** The kind of a valid Spanish fiscal identifier. */
+type NifType = 'DNI' | 'NIE' | 'CIF';
+/** The organization type encoded in the first letter of a CIF. */
+interface CifOrganizationType {
+    /** The CIF leading letter (e.g. `'A'`). */
+    code: string;
+    /** Human-readable description of the organization type (in Spanish). */
+    description: string;
+}
+/** Structured result describing a parsed identifier. */
+interface NifInfo {
+    /** Whether the value is a valid DNI, NIE or CIF. */
+    valid: boolean;
+    /** The detected type, or `null` when invalid. */
+    type: NifType | null;
+    /** The normalized (upper-cased, separator-free) value. */
+    normalized: string;
+    /** The organization details, only present for a valid CIF. */
+    organization: CifOrganizationType | null;
+}
+/** Options for {@link format}. */
+interface FormatOptions {
+    /** Separator inserted before the control character (e.g. `'-'`). */
+    separator?: string;
+}
+/**
+ * Numeric result codes returned by {@link validateNif}.
+ * Negative values mean invalid; values `>= 0` mean valid.
+ */
+declare const ValidationResult: {
+    /** Unknown or malformed value. */
+    readonly ERROR: -1;
+    /** Valid DNI / NIF (Spanish resident). */
+    readonly DNI: 1;
+    /** Valid NIE (foreigner). */
+    readonly NIE: 4;
+    /** Valid CIF (organization). */
+    readonly CIF: 20;
+};
+type ValidationResultCode = (typeof ValidationResult)[keyof typeof ValidationResult];
+/**
+ * Normalize any input into an upper-cased string with the common separators
+ * (spaces, dots, hyphens, underscores) removed. Non-string and nullish values
+ * are coerced safely, so the public API never throws.
+ */
+declare function normalize(value: unknown): string;
+/** Compute the control letter for an 8-digit DNI / NIE number. */
+declare function controlLetterFor(num: number): string;
+/** Validate a Spanish DNI / NIF (8 digits + control letter). */
+declare function isValidDNI(value: unknown): boolean;
+/** Validate a Spanish NIE (X/Y/Z + 7 digits + control letter). */
+declare function isValidNIE(value: unknown): boolean;
+/** Validate a Spanish CIF (letter + 7 digits + control digit/letter). */
+declare function isValidCIF(value: unknown): boolean;
+/** Validate a NIF for a natural person (DNI or NIE). */
+declare function isValidNIF(value: unknown): boolean;
+/** Validate any supported Spanish fiscal identifier (DNI, NIE or CIF). */
+declare function isValid(value: unknown): boolean;
+/** Detect the type of a valid identifier, or `null` when it is invalid. */
+declare function getType(value: unknown): NifType | null;
+/**
+ * Resolve the organization type for a valid CIF from its leading letter, or
+ * `null` when the value is not a valid CIF.
+ */
+declare function getCifOrganizationType(value: unknown): CifOrganizationType | null;
+/**
+ * Parse a value into a structured {@link NifInfo} object describing its
+ * validity, type, normalized form and (for CIFs) organization details.
+ */
+declare function parse(value: unknown): NifInfo;
+/**
+ * Return the canonical (normalized, upper-cased) representation of an
+ * identifier. When a `separator` is provided it is inserted before the control
+ * character — e.g. `format('12345678z', { separator: '-' })` → `'12345678-Z'`.
+ * Invalid values are returned normalized without a separator.
+ */
+declare function format(value: unknown, options?: FormatOptions): string;
+/**
+ * Backwards-compatible validator returning a numeric {@link ValidationResult}
+ * code. Negative values mean invalid; values `>= 0` mean valid.
+ */
+declare function validateNif(value: unknown): ValidationResultCode;
+
+export { ValidationResult, controlLetterFor, validateNif as default, format, getCifOrganizationType, getType, isValid, isValidCIF, isValidDNI, isValidNIE, isValidNIF, normalize, parse, validateNif };
+export type { CifOrganizationType, FormatOptions, NifInfo, NifType, ValidationResultCode };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * validate-nif
+ *
+ * Zero-dependency, isomorphic (Node & browser) validator for Spanish fiscal
+ * identifiers:
+ *
+ *   - DNI / NIF — natural persons, residents (8 digits + control letter)
+ *   - NIE       — natural persons, foreigners (X/Y/Z + 7 digits + control letter)
+ *   - CIF       — legal entities / organizations (letter + 7 digits + control)
+ *
+ * The control-character algorithms follow the official AEAT specification.
+ */
+/** The kind of a valid Spanish fiscal identifier. */
+type NifType = 'DNI' | 'NIE' | 'CIF';
+/** The organization type encoded in the first letter of a CIF. */
+interface CifOrganizationType {
+    /** The CIF leading letter (e.g. `'A'`). */
+    code: string;
+    /** Human-readable description of the organization type (in Spanish). */
+    description: string;
+}
+/** Structured result describing a parsed identifier. */
+interface NifInfo {
+    /** Whether the value is a valid DNI, NIE or CIF. */
+    valid: boolean;
+    /** The detected type, or `null` when invalid. */
+    type: NifType | null;
+    /** The normalized (upper-cased, separator-free) value. */
+    normalized: string;
+    /** The organization details, only present for a valid CIF. */
+    organization: CifOrganizationType | null;
+}
+/** Options for {@link format}. */
+interface FormatOptions {
+    /** Separator inserted before the control character (e.g. `'-'`). */
+    separator?: string;
+}
+/**
+ * Numeric result codes returned by {@link validateNif}.
+ * Negative values mean invalid; values `>= 0` mean valid.
+ */
+declare const ValidationResult: {
+    /** Unknown or malformed value. */
+    readonly ERROR: -1;
+    /** Valid DNI / NIF (Spanish resident). */
+    readonly DNI: 1;
+    /** Valid NIE (foreigner). */
+    readonly NIE: 4;
+    /** Valid CIF (organization). */
+    readonly CIF: 20;
+};
+type ValidationResultCode = (typeof ValidationResult)[keyof typeof ValidationResult];
+/**
+ * Normalize any input into an upper-cased string with the common separators
+ * (spaces, dots, hyphens, underscores) removed. Non-string and nullish values
+ * are coerced safely, so the public API never throws.
+ */
+declare function normalize(value: unknown): string;
+/** Compute the control letter for an 8-digit DNI / NIE number. */
+declare function controlLetterFor(num: number): string;
+/** Validate a Spanish DNI / NIF (8 digits + control letter). */
+declare function isValidDNI(value: unknown): boolean;
+/** Validate a Spanish NIE (X/Y/Z + 7 digits + control letter). */
+declare function isValidNIE(value: unknown): boolean;
+/** Validate a Spanish CIF (letter + 7 digits + control digit/letter). */
+declare function isValidCIF(value: unknown): boolean;
+/** Validate a NIF for a natural person (DNI or NIE). */
+declare function isValidNIF(value: unknown): boolean;
+/** Validate any supported Spanish fiscal identifier (DNI, NIE or CIF). */
+declare function isValid(value: unknown): boolean;
+/** Detect the type of a valid identifier, or `null` when it is invalid. */
+declare function getType(value: unknown): NifType | null;
+/**
+ * Resolve the organization type for a valid CIF from its leading letter, or
+ * `null` when the value is not a valid CIF.
+ */
+declare function getCifOrganizationType(value: unknown): CifOrganizationType | null;
+/**
+ * Parse a value into a structured {@link NifInfo} object describing its
+ * validity, type, normalized form and (for CIFs) organization details.
+ */
+declare function parse(value: unknown): NifInfo;
+/**
+ * Return the canonical (normalized, upper-cased) representation of an
+ * identifier. When a `separator` is provided it is inserted before the control
+ * character — e.g. `format('12345678z', { separator: '-' })` → `'12345678-Z'`.
+ * Invalid values are returned normalized without a separator.
+ */
+declare function format(value: unknown, options?: FormatOptions): string;
+/**
+ * Backwards-compatible validator returning a numeric {@link ValidationResult}
+ * code. Negative values mean invalid; values `>= 0` mean valid.
+ */
+declare function validateNif(value: unknown): ValidationResultCode;
+
+// @ts-ignore
+export = validateNif;
+export { ValidationResult, controlLetterFor, format, getCifOrganizationType, getType, isValid, isValidCIF, isValidDNI, isValidNIE, isValidNIF, normalize, parse, validateNif };
+export type { CifOrganizationType, FormatOptions, NifInfo, NifType, ValidationResultCode };

package/dist/index.mjs

@@ -0,0 +1,149 @@
+const ValidationResult = {
+  /** Unknown or malformed value. */
+  ERROR: -1,
+  /** Valid DNI / NIF (Spanish resident). */
+  DNI: 1,
+  /** Valid NIE (foreigner). */
+  NIE: 4,
+  /** Valid CIF (organization). */
+  CIF: 20
+};
+const DNI_LETTERS = "TRWAGMYFPDXBNJZSQVHLCKE";
+const CIF_LETTERS = "JABCDEFGHI";
+const CIF_LETTER_CONTROL = "NPQRSW";
+const CIF_DIGIT_CONTROL = "ABEH";
+const NIE_PREFIX = { X: "0", Y: "1", Z: "2" };
+const CIF_ORGANIZATION_TYPES = {
+  A: "Sociedad an\xF3nima",
+  B: "Sociedad de responsabilidad limitada",
+  C: "Sociedad colectiva",
+  D: "Sociedad comanditaria",
+  E: "Comunidad de bienes y herencias yacentes",
+  F: "Sociedad cooperativa",
+  G: "Asociaci\xF3n o fundaci\xF3n",
+  H: "Comunidad de propietarios en r\xE9gimen de propiedad horizontal",
+  J: "Sociedad civil",
+  N: "Entidad extranjera",
+  P: "Corporaci\xF3n local",
+  Q: "Organismo p\xFAblico",
+  R: "Congregaci\xF3n o instituci\xF3n religiosa",
+  S: "\xD3rgano de la Administraci\xF3n del Estado o comunidad aut\xF3noma",
+  U: "Uni\xF3n temporal de empresas",
+  V: "Otro tipo de entidad sin personalidad jur\xEDdica",
+  W: "Establecimiento permanente de entidad no residente"
+};
+const DNI_RE = /^\d{8}[A-Z]$/;
+const NIE_RE = /^[XYZ]\d{7}[A-Z]$/;
+const CIF_RE = /^[ABCDEFGHJNPQRSUVW]\d{7}[0-9A-J]$/;
+function normalize(value) {
+  if (value === null || value === void 0) {
+    return "";
+  }
+  const str = typeof value === "string" ? value : String(value);
+  return str.toUpperCase().replace(/[\s.\-_]/g, "");
+}
+function controlLetterFor(num) {
+  return DNI_LETTERS[num % 23];
+}
+function isValidDNI(value) {
+  const v = normalize(value);
+  if (!DNI_RE.test(v)) {
+    return false;
+  }
+  const num = parseInt(v.slice(0, 8), 10);
+  return v[8] === controlLetterFor(num);
+}
+function isValidNIE(value) {
+  const v = normalize(value);
+  if (!NIE_RE.test(v)) {
+    return false;
+  }
+  const num = parseInt(NIE_PREFIX[v[0]] + v.slice(1, 8), 10);
+  return v[8] === controlLetterFor(num);
+}
+function isValidCIF(value) {
+  const v = normalize(value);
+  if (!CIF_RE.test(v)) {
+    return false;
+  }
+  const firstLetter = v[0];
+  const digits = v.slice(1, 8);
+  const control = v[8];
+  let sum = 0;
+  for (let i = 0; i < digits.length; i += 1) {
+    let n = parseInt(digits[i], 10);
+    if (i % 2 === 0) {
+      n *= 2;
+      if (n > 9) {
+        n -= 9;
+      }
+    }
+    sum += n;
+  }
+  const controlDigit = (10 - sum % 10) % 10;
+  const controlLetter = CIF_LETTERS[controlDigit];
+  if (CIF_LETTER_CONTROL.includes(firstLetter)) {
+    return control === controlLetter;
+  }
+  if (CIF_DIGIT_CONTROL.includes(firstLetter)) {
+    return control === String(controlDigit);
+  }
+  return control === String(controlDigit) || control === controlLetter;
+}
+function isValidNIF(value) {
+  return isValidDNI(value) || isValidNIE(value);
+}
+function isValid(value) {
+  return isValidDNI(value) || isValidNIE(value) || isValidCIF(value);
+}
+function getType(value) {
+  if (isValidDNI(value)) {
+    return "DNI";
+  }
+  if (isValidNIE(value)) {
+    return "NIE";
+  }
+  if (isValidCIF(value)) {
+    return "CIF";
+  }
+  return null;
+}
+function getCifOrganizationType(value) {
+  if (!isValidCIF(value)) {
+    return null;
+  }
+  const code = normalize(value)[0];
+  return { code, description: CIF_ORGANIZATION_TYPES[code] };
+}
+function parse(value) {
+  const normalized = normalize(value);
+  const type = getType(value);
+  return {
+    valid: type !== null,
+    type,
+    normalized,
+    organization: type === "CIF" ? getCifOrganizationType(value) : null
+  };
+}
+function format(value, options = {}) {
+  const v = normalize(value);
+  const separator = options.separator ?? "";
+  if (!separator || !isValid(v)) {
+    return v;
+  }
+  return `${v.slice(0, -1)}${separator}${v.slice(-1)}`;
+}
+function validateNif(value) {
+  if (isValidDNI(value)) {
+    return ValidationResult.DNI;
+  }
+  if (isValidNIE(value)) {
+    return ValidationResult.NIE;
+  }
+  if (isValidCIF(value)) {
+    return ValidationResult.CIF;
+  }
+  return ValidationResult.ERROR;
+}
+
+export { ValidationResult, controlLetterFor, validateNif as default, format, getCifOrganizationType, getType, isValid, isValidCIF, isValidDNI, isValidNIE, isValidNIF, normalize, parse, validateNif };

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@maistik/validate-nif",
+  "version": "2.0.1",
+  "description": "Zero-dependency, isomorphic validator for Spanish fiscal identifiers (DNI/NIF, NIE and CIF)",
+  "type": "module",
+  "private": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "stub": "unbuild --stub",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "test:examples": "node examples/index.mjs",
+    "prepack": "unbuild",
+    "release": "npm run lint && npm run test:coverage && npm run build && changelogen --release && npm publish --access public && git push --follow-tags"
+  },
+  "keywords": [
+    "validate",
+    "validation",
+    "nif",
+    "nie",
+    "dni",
+    "cif",
+    "spain",
+    "spanish",
+    "fiscal",
+    "tax-id",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Maistik Studio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maistik-Studio/validate-nif.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Maistik-Studio/validate-nif/issues"
+  },
+  "homepage": "https://github.com/Maistik-Studio/validate-nif#readme",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.5.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.0",
+    "unbuild": "^3.6.1",
+    "vite": "^7.3.5",
+    "vitest": "^4.1.8"
+  },
+  "packageManager": "pnpm@11.6.0"
+}