### Install the library

Source: https://github.com/tonyc726/china-id-card/blob/master/README_EN.md

Use the package manager to add the library to your project.

```bash
pnpm add china-id-card
```

--------------------------------

### Usage Examples

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Basic usage patterns for TypeScript, CommonJS, and browser environments.

```typescript
import { isValid, parse, mask } from 'china-id-card';

// 验证身份证
isValid('622922197808118498'); // → true

// 解析身份证信息
const info = parse('622922197808118498');
// → { isValid: true, province: '甘肃省', birthDate: '1978-08-11', gender: 'male', ... }

// 脱敏处理
mask('622922197808118498'); // → '622***********8498'
```

```javascript
const { isValid, parse } = require('china-id-card');
isValid('622922197808118498'); // → true
```

```html
<script src="https://cdn.jsdelivr.net/npm/china-id-card/dist/index.umd.js"></script>
<script>
  const { isValid, parse } = window.ChinaIdCard;
  console.log(isValid('622922197808118498'));
</script>
```

--------------------------------

### Quick Start usage

Source: https://github.com/tonyc726/china-id-card/blob/master/README_EN.md

Import the core functions to parse, validate, or mask ID card numbers.

```typescript
import { isValid, parse, mask } from 'china-id-card';

// Parse ID card information
const info = parse('622922197808118498');
// → { isValid: true, province: '甘肃省', birthDate: '1978-08-11', gender: 'male', age: 46, ... }

// Quick validation
isValid('622922197808118498'); // → true

// Mask sensitive data
mask('622922197808118498'); // → '622***********8498'
```

--------------------------------

### Quick Start: Parse, Validate, and Mask ID Cards

Source: https://github.com/tonyc726/china-id-card/blob/master/README.md

Import and use core functions to parse ID card details, perform quick validation, and mask the ID number for privacy. Requires importing functions from 'china-id-card'.

```typescript
import { isValid, parse, mask } from 'china-id-card';

// 解析身份证信息
const info = parse('622922197808118498');
// → { isValid: true, province: '甘肃省', birthDate: '1978-08-11', gender: 'male', age: 46, ... }

// 快速验证
isValid('622922197808118498'); // → true

// 脱敏处理
mask('622922197808118498'); // → '622***********8498'
```

--------------------------------

### Library Summary and Usage

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Provides a summary of the China ID Card library's applications and integration recommendations.

```APIDOC
## Summary

### Description
The China ID Card library is primarily used in scenarios such as user registration, real-name authentication, data cleaning, and form validation that require processing Chinese citizen ID card numbers. The `isValid` function allows for quick validation of ID card validity, the `parse` function extracts complete personal information, and the `mask` function protects user privacy in log records or interface displays.

### Usage Recommendations
In practical integration, it is recommended to use `isValid` for real-time front-end form validation and `parse` for back-end data processing and information extraction.

### Integration
This library has zero dependencies, making it safe to integrate into any TypeScript/JavaScript project. It supports both ES Module and CommonJS module specifications and can be used in various runtime environments such as Node.js, browsers, and React Native.
```

--------------------------------

### Validate Province Code

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/checkProvince.md

Demonstrates how to import and use the checkProvince function to verify ID card province codes.

```typescript
import { checkProvince } from 'china-id-card'

checkProvince('622922197808118498') // → true (甘肃省)
checkProvince('999922197808118498') // → false
```

--------------------------------

### Validate ID Card Usage

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/isValid.md

Demonstrates how to import and use the isValid function to check ID card validity.

```typescript
import { isValid } from 'china-id-card';

isValid('622922197808118498'); // → true
isValid('123456789012345678'); // → false
```

--------------------------------

### Define toEighteen function signature

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/toEighteen.md

The function accepts a string and returns either a string or null.

```typescript
function toEighteen(id: string): string | null
```

--------------------------------

### toEighteen - Convert 15-digit to 18-digit ID

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Converts a 15-digit ID card number to its 18-digit equivalent by inserting '19' and calculating the checksum.

```APIDOC
## toEighteen - Convert 15-digit to 18-digit ID

### Description
Converts a 15-digit ID card number to its 18-digit equivalent. It inserts '19' after the 6th digit (for the year) and calculates the checksum for the 18th digit. Returns null for invalid inputs.

### Method
`toEighteen(fifteenDigitId: string): string | null`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { toEighteen } from 'china-id-card';

console.log(toEighteen('310000810227632')); // '310000198102276323'
console.log(toEighteen('')); // null
console.log(toEighteen('3100008102276321')); // null (16 digits)
```

### Response
#### Success Response (string | null)
- The 18-digit ID card number if conversion is successful.
- `null` if the input is not a valid 15-digit ID.

#### Response Example
```json
"310000198102276323"
```
```

--------------------------------

### Check Base Format

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Validate the basic length and character rules of an ID card.

```typescript
import { checkBaseFormat } from 'china-id-card';
checkBaseFormat('622922197808118498'); // → true
```

--------------------------------

### Convert 15-digit to 18-digit ID

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Use toEighteen to convert a 15-digit ID to the 18-digit standard format. Returns null for invalid inputs.

```typescript
import { toEighteen } from 'china-id-card';

// 正常转换
console.log(toEighteen('310000810227632')); // → '310000198102276323'

// 边界测试
console.log(toEighteen('999999990123456')); // → '999999199901234568'

// 无效输入返回 null
console.log(toEighteen('3100008102276321')); // → null (16位)
console.log(toEighteen('31000081022763')); // → null (14位)
console.log(toEighteen('')); // → null
console.log(toEighteen('31abc08102276321')); // → null (包含非数字)
```

--------------------------------

### Parse an ID Card Number

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/parse.md

Demonstrates importing the parse function and using it to retrieve details from a specific ID card number.

```typescript
import { parse } from 'china-id-card'

const result = parse('622922197808118498')
// {
//   isValid: true,
//   province: '甘肃省',
//   birthDate: '1978-08-11',
//   gender: 'male',
//   age: 47,
//   eighteenDigit: '622922197808118498',
//   fifteenDigit: null
// }
```

--------------------------------

### Core Functions

Source: https://github.com/tonyc726/china-id-card/blob/master/README.md

These functions provide the main capabilities for working with Chinese ID card numbers, including validation, parsing, masking, conversion, and checksum calculation.

```APIDOC
## Core Functions API Reference

### `isValid(id)`

#### Description
Quickly validates if a given string is a valid Chinese ID card number.

#### Parameters
- **id** (string) - Required - The ID card number to validate.

#### Returns
- **boolean** - `true` if the ID card is valid, `false` otherwise.

### `parse(id)`

#### Description
Parses a Chinese ID card number to extract detailed information.

#### Parameters
- **id** (string) - Required - The ID card number to parse.

#### Returns
- **IDCardInfo** - An object containing detailed information about the ID card.

### `mask(id)`

#### Description
Masks a Chinese ID card number, typically showing the first 3 and last 4 digits.

#### Parameters
- **id** (string) - Required - The ID card number to mask.

#### Returns
- **string** - The masked ID card number.

### `toEighteen(id)`

#### Description
Converts a 15-digit ID card number to its 18-digit equivalent.

#### Parameters
- **id** (string) - Required - The 15-digit ID card number.

#### Returns
- **string | null** - The 18-digit ID card number, or `null` if conversion fails.

### `getCheckCode(id)`

#### Description
Calculates the checksum digit for a given 17-digit ID card number prefix.

#### Parameters
- **id** (string) - Required - The first 17 digits of the ID card number.

#### Returns
- **string | null** - The calculated checksum digit, or `null` if calculation fails.
```

--------------------------------

### Convert 15-digit ID to 18-digit

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/toEighteen.md

Import the function from the package and pass a 15-digit ID string to receive the 18-digit result.

```typescript
import { toEighteen } from 'china-id-card'

toEighteen('110101900101001')  // → '110101199001010018'
```

--------------------------------

### Verify ID base format

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Use checkBaseFormat to validate the structural format of an ID string without checking the validity of the data itself.

```typescript
import { checkBaseFormat } from 'china-id-card';

// 有效格式
console.log(checkBaseFormat('310000810227632')); // → true (15位)
console.log(checkBaseFormat('310000198102276323')); // → true (18位)
console.log(checkBaseFormat('31000019830212878X')); // → true (18位带X)
console.log(checkBaseFormat('31000019830212878x')); // → true (小写x也有效)

// 无效格式
console.log(checkBaseFormat('31000019810227632')); // → false (17位)
console.log(checkBaseFormat('3100001981022763234')); // → false (19位)
console.log(checkBaseFormat('abc')); // → false
console.log(checkBaseFormat('')); // → false
console.log(checkBaseFormat('12345')); // → false
```

--------------------------------

### Test Data Array

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

A collection of sample ID numbers for testing purposes.

```typescript
[
  '622922197808118498', // 甘肃省
  '37012519790112881X', // 山东省
  '510726198609245808', // 四川省
  '530629198901284967', // 云南省
  '31000019850412412X', // 上海市
  '110101900101001', // 15位北京市
  '810000199012305532', // 香港特别行政区
  '820000199012305521', // 澳门特别行政区
];
```

--------------------------------

### Validate Province Code with checkProvince

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Use `checkProvince` to verify if the first two digits of an ID card represent a valid Chinese province, municipality, autonomous region, or special administrative region. This function supports all valid provincial codes. Ensure the `china-id-card` library is imported.

```typescript
import { checkProvince } from 'china-id-card';

// 有效省份编码
console.log(checkProvince('110000000000000')); // → true (北京市 11)
console.log(checkProvince('310000000000000')); // → true (上海市 31)
console.log(checkProvince('440100000000000')); // → true (广东省 44)
console.log(checkProvince('620000000000000')); // → true (甘肃省 62)
console.log(checkProvince('710000000000000')); // → true (台湾省 71)
console.log(checkProvince('810000000000000')); // → true (香港特别行政区 81)
console.log(checkProvince('820000000000000')); // → true (澳门特别行政区 82)

// 无效省份编码
console.log(checkProvince('000000000000000')); // → false
console.log(checkProvince('990000000000000')); // → false
console.log(checkProvince('abc')); // → false
```

--------------------------------

### Check Province Code

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Verify if the province code within the ID is valid.

```typescript
import { checkProvince } from 'china-id-card';
checkProvince('622922197808118498'); // → true
```

--------------------------------

### Function Signature for checkProvince

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/checkProvince.md

Defines the expected input type and return type for the province validation function.

```typescript
function checkProvince(id: string): boolean
```

--------------------------------

### Define IDCardInfo Interface and parse Function Signature

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/parse.md

Defines the structure of the returned ID card information object and the signature of the parsing function.

```typescript
interface IDCardInfo {
  isValid: boolean           // 是否有效
  provinceCode: string       // 省份编码
  province: string           // 省份名称
  birthDate: string          // 出生日期 (YYYY-MM-DD)
  gender: 'male' | 'female'  // 性别
  age: number                // 年龄
  fifteenDigit: string | null // 15位身份证
  eighteenDigit: string | null // 18位身份证
}

function parse(id: string): IDCardInfo
```

--------------------------------

### getCheckCode - Calculate Checksum

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Calculates the checksum digit (0-9 or X) for an 17-digit ID card number based on the GB 11643-1999 standard.

```APIDOC
## getCheckCode - Calculate Checksum

### Description
Calculates the checksum digit (the 18th digit) for an ID card number based on the GB 11643-1999 standard's weighted algorithm. Takes the first 17 digits as input.

### Method
`getCheckCode(seventeenDigits: string): string | null`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { getCheckCode } from 'china-id-card';

console.log(getCheckCode('31000019810227632')); // '3'
console.log(getCheckCode('31000019830212878')); // 'X'
console.log(getCheckCode('')); // null
console.log(getCheckCode('310000198102276323')); // '3' (uses first 17 digits)
```

### Response
#### Success Response (string | null)
- The calculated checksum digit ('0'-'9' or 'X').
- `null` if the input is invalid (e.g., not 17 digits, contains non-numeric characters).

#### Response Example
```json
"3"
```
```

--------------------------------

### Validation Functions

Source: https://github.com/tonyc726/china-id-card/blob/master/README_EN.md

Specific validation utilities for ID card components.

```APIDOC
## checkBaseFormat(id)

### Description
Validates the basic format of the ID card number.

### Parameters
- **id** (string) - Required - The ID card number.

### Response
- **boolean** - Returns true if the format is valid.

## checkProvince(id)

### Description
Validates the province code portion of the ID card number.

### Parameters
- **id** (string) - Required - The ID card number.

### Response
- **boolean** - Returns true if the province code is valid.
```

--------------------------------

### Calculate ID Card Checksum

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/getCheckCode.md

Use this function to compute the checksum for the first 17 digits of a Chinese ID card. It returns the checksum (0-9 or X) or null if the input format is invalid.

```typescript
import { getCheckCode } from 'china-id-card'

getCheckCode('62292219780811849')  // → '8'
getCheckCode('31000019810227632')  // → '3'
```

--------------------------------

### ID Card Parsing Function

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/parse.md

Parses a given Chinese ID card number and returns a structured object with detailed information.

```APIDOC
## parse(id)

### Description
Parses a Chinese ID card number to extract detailed information.

### Method
N/A (This is a function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Function Signature
```typescript
interface IDCardInfo {
  isValid: boolean           // Whether the ID is valid
  provinceCode: string       // Province code
  province: string           // Province name
  birthDate: string          // Birth date (YYYY-MM-DD)
  gender: 'male' | 'female'  // Gender
  age: number                // Age
  fifteenDigit: string | null // 15-digit ID card number if applicable
  eighteenDigit: string | null // 18-digit ID card number if applicable
}

function parse(id: string): IDCardInfo
```

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```typescript
import { parse } from 'china-id-card'

const result = parse('622922197808118498')
// { 
//   isValid: true,
//   province: '甘肃省',
//   birthDate: '1978-08-11',
//   gender: 'male',
//   age: 47,
//   eighteenDigit: '622922197808118498',
//   fifteenDigit: null
// }
```

### Response
#### Success Response (IDCardInfo Object)
- **isValid** (boolean) - Indicates if the ID card number is valid.
- **provinceCode** (string) - The code representing the province.
- **province** (string) - The name of the province.
- **birthDate** (string) - The date of birth in YYYY-MM-DD format.
- **gender** (string) - The gender ('male' or 'female').
- **age** (number) - The calculated age.
- **fifteenDigit** (string | null) - The 15-digit ID card number, if applicable.
- **eighteenDigit** (string | null) - The 18-digit ID card number, if applicable.

#### Response Example
```json
{
  "isValid": true,
  "provinceCode": "62",
  "province": "甘肃省",
  "birthDate": "1978-08-11",
  "gender": "male",
  "age": 47,
  "fifteenDigit": null,
  "eighteenDigit": "622922197808118498"
}
```
```

--------------------------------

### toEighteen(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/toEighteen.md

Converts a 15-digit Chinese ID card number to an 18-digit format.

```APIDOC
## Function: toEighteen(id)

### Description
Converts a 15-digit Chinese ID card number to an 18-digit format. If the input is not a valid 15-digit ID, the function returns null.

### Parameters
- **id** (string) - Required - The 15-digit ID card number to convert.

### Returns
- (string | null) - The converted 18-digit ID card number, or null if the input is invalid.

### Example
```typescript
import { toEighteen } from 'china-id-card'

toEighteen('110101900101001')  // → '110101199001010018'
```
```

--------------------------------

### parse - Parse ID Card Information

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Parses a full ID card number, returning an object with validity, province, birth date, gender, and age. Automatically converts 15-digit IDs to 18-digit.

```APIDOC
## parse - Parse ID Card Information

### Description
Parses a full ID card number, returning an object with validity, province, birth date, gender, and age. Supports both 15 and 18-digit formats, automatically converting 15-digit IDs to 18-digit.

### Method
`parse(idCardNumber: string): IdCardInfo`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { parse } from 'china-id-card';

const info18 = parse('310000198102276323');
console.log(info18);
// { isValid: true, provinceCode: '31', province: '上海市', birthDate: '1981-02-27', gender: 'female', age: 44, fifteenDigit: null, eighteenDigit: '310000198102276323' }

const info15 = parse('310000810227632');
console.log(info15);
// { isValid: true, provinceCode: '31', province: '上海市', birthDate: '1981-02-27', gender: 'female', age: 44, fifteenDigit: '310000810227632', eighteenDigit: '310000198102276323' }
```

### Response
#### Success Response (IdCardInfo)
- `isValid` (boolean): Indicates if the ID card is valid.
- `provinceCode` (string): The province code of the ID card.
- `province` (string): The name of the province.
- `birthDate` (string): The birth date in 'YYYY-MM-DD' format.
- `gender` (string): The gender ('male' or 'female').
- `age` (number): The calculated age.
- `fifteenDigit` (string | null): The original 15-digit ID if applicable, otherwise null.
- `eighteenDigit` (string | null): The 18-digit ID, either original or converted.

#### Response Example
```json
{
  "isValid": true,
  "provinceCode": "31",
  "province": "上海市",
  "birthDate": "1981-02-27",
  "gender": "female",
  "age": 44,
  "fifteenDigit": null,
  "eighteenDigit": "310000198102276323"
}
```
```

--------------------------------

### Calculate ID checksum

Source: https://context7.com/tonyc726/china-id-card/llms.txt

The getCheckCode function calculates the 18th digit of an ID card based on the first 17 digits using the GB 11643-1999 algorithm.

```typescript
import { getCheckCode } from 'china-id-card';

// 计算校验码
console.log(getCheckCode('31000019810227632')); // → '3'
console.log(getCheckCode('31000019830212878')); // → 'X'
console.log(getCheckCode('62292219780811849')); // → '8'

// 18 位身份证也可以计算（只使用前 17 位）
console.log(getCheckCode('310000198102276323')); // → '3'

// 无效输入返回 null
console.log(getCheckCode('310000810227632')); // → null (15位)
console.log(getCheckCode('abc')); // → null
console.log(getCheckCode('')); // → null
console.log(getCheckCode('31000019abc276323')); // → null (包含非数字)
```

--------------------------------

### checkProvince(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/checkProvince.md

Validates the province code of a Chinese ID card number.

```APIDOC
## checkProvince(id)

### Description
Verifies if the province code in the ID card number is valid.

### Method
Function Call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **id** (string) - Required - The ID card number to validate.

### Request Example
```typescript
import { checkProvince } from 'china-id-card'

checkProvince('622922197808118498')
```

### Response
#### Success Response (boolean)
- **true**: Province code is valid.
- **false**: Province code is invalid.

#### Response Example
```json
true
```

#### Error Response
None explicitly defined for this function, assumes invalid input returns false.
```

--------------------------------

### IDCardInfo Type Definition

Source: https://github.com/tonyc726/china-id-card/blob/master/README.md

Defines the structure of the object returned by the `parse` function.

```APIDOC
## IDCardInfo Type

This interface describes the structure of the object returned when parsing a Chinese ID card number.

```typescript
interface IDCardInfo {
  isValid: boolean; // Indicates if the ID card number is valid.
  provinceCode: string; // The province code (e.g., '62').
  province: string; // The name of the province (e.g., '甘肃省').
  birthDate: string; // The birth date in 'YYYY-MM-DD' format.
  gender: 'male' | 'female'; // The gender of the individual.
  age: number; // The calculated age.
  fifteenDigit: string | null; // The 15-digit version of the ID card number, if applicable.
  eighteenDigit: string | null; // The 18-digit version of the ID card number, if applicable.
}
```
```

--------------------------------

### checkBaseFormat(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/checkBaseFormat.md

Validates the basic format of an ID card number, checking for correct length and character types.

```APIDOC
## checkBaseFormat(id)

### Description
Validates the basic format of an ID card number (length and characters).

### Method
N/A (This is a function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **boolean** (boolean) - `true` if the format is correct (15 digits or 17 digits + 'X'), `false` otherwise.

#### Response Example
```json
{
  "example": "true"
}
```

### Code Example
```typescript
import { checkBaseFormat } from 'china-id-card'

checkBaseFormat('622922197808118498') // → true
checkBaseFormat('110101900101001')   // → true (15位)
checkBaseFormat('12345')             // → false
```
```

--------------------------------

### parse(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Parses an ID card number to extract detailed information such as province, birth date, gender, and age.

```APIDOC
## parse(id)

### Description
Parses the ID card number and returns an object containing demographic and structural information.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID card number to parse.

### Response
#### Success Response (200)
- **isValid** (boolean) - Whether the ID is valid
- **provinceCode** (string) - The administrative division code
- **province** (string) - The province name
- **birthDate** (string) - Birth date in YYYY-MM-DD format
- **gender** (string) - 'male' or 'female'
- **age** (number) - Calculated age
- **fifteenDigit** (string|null) - 15-digit representation
- **eighteenDigit** (string|null) - 18-digit representation
```

--------------------------------

### Validate Basic ID Card Format

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/checkBaseFormat.md

Use this function to check if an ID string is a valid 15-digit or 17-digit number optionally ending with 'X'. Requires importing the function.

```typescript
import { checkBaseFormat } from 'china-id-card'

checkBaseFormat('622922197808118498') // → true
checkBaseFormat('110101900101001')   // → true (15位)
checkBaseFormat('12345')             // → false
```

--------------------------------

### Core Functions

Source: https://github.com/tonyc726/china-id-card/blob/master/README_EN.md

Primary functions for validating, parsing, and manipulating Chinese ID card numbers.

```APIDOC
## isValid(id)

### Description
Performs a quick validation of the provided ID card number.

### Parameters
- **id** (string) - Required - The ID card number to validate.

### Response
- **boolean** - Returns true if the ID is valid, false otherwise.

## parse(id)

### Description
Parses a Chinese ID card number to extract detailed information.

### Parameters
- **id** (string) - Required - The ID card number to parse.

### Response
- **IDCardInfo** (object) - Returns an object containing validation status, province, birth date, gender, age, and digit conversions.

## mask(id)

### Description
Masks sensitive ID card data by hiding middle digits.

### Parameters
- **id** (string) - Required - The ID card number to mask.

### Response
- **string** - Returns the masked ID (e.g., '622***********8498').

## toEighteen(id)

### Description
Converts a 15-digit ID card number to an 18-digit format.

### Parameters
- **id** (string) - Required - The 15-digit ID card number.

### Response
- **string | null** - Returns the 18-digit ID or null if conversion fails.

## getCheckCode(id)

### Description
Calculates the check digit for an ID card number.

### Parameters
- **id** (string) - Required - The ID card number.

### Response
- **string | null** - Returns the calculated check digit.
```

--------------------------------

### Calculate Check Code

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Compute the checksum digit for an 18-digit ID card.

```typescript
import { getCheckCode } from 'china-id-card';
getCheckCode('11010119900101100'); // → '1'
```

--------------------------------

### Parse ID Card Information

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Extract detailed information from an ID card number.

```typescript
import { parse } from 'china-id-card';
parse('622922197808118498');
// → { isValid: true, province: '甘肃省', birthDate: '1978-08-11', gender: 'male', ... }
```

--------------------------------

### Parse ID card information

Source: https://context7.com/tonyc726/china-id-card/llms.txt

The parse function returns an object containing validity, province, birth date, gender, and age. It automatically converts 15-digit IDs to 18-digit format.

```typescript
import { parse } from 'china-id-card';

// 解析 18 位身份证
const info18 = parse('310000198102276323');
console.log(info18);
// → {
//   isValid: true,
//   provinceCode: '31',
//   province: '上海市',
//   birthDate: '1981-02-27',
//   gender: 'female',
//   age: 44,
//   fifteenDigit: null,
//   eighteenDigit: '310000198102276323'
// }

// 解析 15 位身份证（自动转换为 18 位）
const info15 = parse('310000810227632');
console.log(info15);
// → {
//   isValid: true,
//   provinceCode: '31',
//   province: '上海市',
//   birthDate: '1981-02-27',
//   gender: 'female',
//   age: 44,
//   fifteenDigit: '310000810227632',
//   eighteenDigit: '310000198102276323'
// }

// 解析带 X 校验码的身份证
const infoX = parse('31000019830212878X');
console.log(infoX.isValid); // → true
console.log(infoX.birthDate); // → '1983-02-12'
console.log(infoX.gender); // → 'female'

// 无效身份证返回默认值
const invalid = parse('abc');
console.log(invalid);
// → {
//   isValid: false,
//   provinceCode: '',
//   province: '',
//   birthDate: '',
//   gender: 'male',
//   age: 0,
//   fifteenDigit: null,
//   eighteenDigit: null
// }
```

--------------------------------

### IDCardInfo interface definition

Source: https://github.com/tonyc726/china-id-card/blob/master/README_EN.md

The structure of the object returned by the parse function.

```typescript
interface IDCardInfo {
  isValid: boolean; // Whether the ID is valid
  provinceCode: string; // Province code (e.g., '62')
  province: string; // Province name (e.g., '甘肃省')
  birthDate: string; // Birth date (YYYY-MM-DD)
  gender: 'male' | 'female'; // Gender
  age: number; // Age
  fifteenDigit: string | null; // 15-digit ID
  eighteenDigit: string | null; // 18-digit ID
}
```

--------------------------------

### isValid(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Quickly validates whether a given ID card number is valid.

```APIDOC
## isValid(id)

### Description
Validates the provided ID card number based on format and checksum rules.

### Parameters
#### Path Parameters
- **id** (string) - Required - The 15 or 18 digit ID card number to validate.

### Response
#### Success Response (200)
- **result** (boolean) - Returns true if valid, false otherwise.
```

--------------------------------

### checkBaseFormat - Validate Basic Format

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Validates the basic format of an ID card number, accepting 15-digit numeric strings or 18-digit strings (17 digits + digit or 'X').

```APIDOC
## checkBaseFormat - Validate Basic Format

### Description
Validates the basic format of an ID card number. It accepts a 15-digit numeric string or an 18-digit string (17 digits followed by a digit or 'X'). This function only checks the format, not the content validity.

### Method
`checkBaseFormat(idCardNumber: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { checkBaseFormat } from 'china-id-card';

console.log(checkBaseFormat('310000810227632')); // true (15 digits)
console.log(checkBaseFormat('310000198102276323')); // true (18 digits)
console.log(checkBaseFormat('31000019830212878X')); // true (18 digits with X)
console.log(checkBaseFormat('31000019810227632')); // false (17 digits)
console.log(checkBaseFormat('abc')); // false
```

### Response
#### Success Response (boolean)
- `true`: The ID card number has a valid basic format.
- `false`: The ID card number has an invalid format.

#### Response Example
```json
true
```
```

--------------------------------

### isValid - Validate ID Card

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Quickly checks if an ID card number is valid by performing format, province code, and checksum validation.

```APIDOC
## isValid - Validate ID Card

### Description
Quickly checks if an ID card number is valid by performing format, province code, and checksum validation. Returns a boolean.

### Method
`isValid(idCardNumber: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { isValid } from 'china-id-card';

console.log(isValid('310000198102276323')); // true
console.log(isValid('123456789012345678')); // false
```

### Response
#### Success Response (boolean)
- `true`: The ID card number is valid.
- `false`: The ID card number is invalid.

#### Response Example
```json
true
```
```

--------------------------------

### IDCardInfo Type Definition

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Defines the structure of the object returned when parsing an ID card number.

```APIDOC
## IDCardInfo Type Definition

### Description
Defines the structure of the object returned when parsing an ID card number.

### Type Definition
```typescript
interface IDCardInfo {
  isValid: boolean;              //身份证是否有效 (Is the ID card valid)
  provinceCode: string;          //省份代码 (如: '31') (Province code, e.g., '31')
  province: string;              //省份名称 (如: '上海市') (Province name, e.g., 'Shanghai')
  birthDate: string;             //出生日期 (YYYY-MM-DD) (Birth date in YYYY-MM-DD format)
  gender: 'male' | 'female';     //性别 (Gender)
  age: number;                   //年龄 (Age)
  fifteenDigit: string | null;   //15位身份证号 (15-digit ID card number)
  eighteenDigit: string | null;  //18位身份证号 (18-digit ID card number)
}
```
```

--------------------------------

### IDCardInfo Type Definition

Source: https://github.com/tonyc726/china-id-card/blob/master/README.md

Defines the structure of the object returned by the `parse` function, including validity, province code and name, birth date, gender, age, and 15/18-digit representations.

```typescript
interface IDCardInfo {
  isValid: boolean; // 身份证是否有效
  provinceCode: string; // 省份代码 (如: '62')
  province: string; // 省份名称 (如: '甘肃省')
  birthDate: string; // 出生日期 (YYYY-MM-DD)
  gender: 'male' | 'female'; // 性别
  age: number; // 年龄
  fifteenDigit: string | null; // 15位身份证
  eighteenDigit: string | null; // 18位身份证
}
```

--------------------------------

### Validate ID card validity

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Use isValid to perform a full check on an ID number, including format, province code, and checksum verification.

```typescript
import { isValid } from 'china-id-card';

// 验证有效的 18 位身份证
console.log(isValid('310000198102276323')); // → true

// 验证有效的 15 位身份证
console.log(isValid('310000810227632')); // → true

// 验证带 X 校验码的身份证
console.log(isValid('31000019830212878X')); // → true

// 无效的身份证号码
console.log(isValid('123456789012345678')); // → false

// 无效的省份编码
console.log(isValid('00000019830212878X')); // → false

// 校验码错误
console.log(isValid('310000198302128788')); // → false

// 空字符串
console.log(isValid('')); // → false
```

--------------------------------

### mask(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Masks the ID card number for privacy, showing only the first 3 and last 4 digits.

```APIDOC
## mask(id)

### Description
Returns a masked version of the ID card number.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID card number to mask.

### Response
#### Success Response (200)
- **maskedId** (string) - The masked ID string (e.g., '622***********8498').
```

--------------------------------

### Validate ID Card

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Check if an ID card number is valid.

```typescript
import { isValid } from 'china-id-card';
isValid('622922197808118498'); // → true
isValid('622922197808118499'); // → false
```

--------------------------------

### checkProvince - Validate Province Code

Source: https://context7.com/tonyc726/china-id-card/llms.txt

This function validates if the province code (first two digits) of an ID card number is valid. It supports codes for all provinces, municipalities, autonomous regions, and special administrative regions.

```APIDOC
## checkProvince - Validate Province Code

### Description
Validates if the province code (first two digits) of an ID card number is valid. Supports codes for all provinces, municipalities, autonomous regions, and special administrative regions.

### Method
`checkProvince(idCardNumber: string): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { checkProvince } from 'china-id-card';

// Valid province codes
console.log(checkProvince('110000000000000')); // → true (Beijing 11)
console.log(checkProvince('310000000000000')); // → true (Shanghai 31)
console.log(checkProvince('440100000000000')); // → true (Guangdong 44)
console.log(checkProvince('620000000000000')); // → true (Gansu 62)
console.log(checkProvince('710000000000000')); // → true (Taiwan 71)
console.log(checkProvince('810000000000000')); // → true (Hong Kong SAR 81)
console.log(checkProvince('820000000000000')); // → true (Macau SAR 82)

// Invalid province codes
console.log(checkProvince('000000000000000')); // → false
console.log(checkProvince('990000000000000')); // → false
console.log(checkProvince('abc')); // → false
```

### Response
#### Success Response (boolean)
- `true`: If the province code is valid.
- `false`: If the province code is invalid.

#### Response Example
```json
true
```
```

--------------------------------

### mask(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/mask.md

Anonymizes a Chinese ID card number by masking the middle section.

```APIDOC
## mask(id)

### Description
Performs privacy masking on a Chinese ID card number.

### Method
Function Call

### Parameters
#### Path Parameters
- **id** (string) - Required - The Chinese ID card number to be masked.

### Response
- **string** - Returns the masked ID card number in the format 'first 3 digits + *********** + last 4 digits'.

### Request Example
mask('622922197808118498')

### Response Example
'622***********8498'
```

--------------------------------

### isValid(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/isValid.md

Validates whether a given string is a valid Chinese ID card number.

```APIDOC
## isValid(id)

### Description
Validates the format and checksum of a Chinese ID card number.

### Parameters
- **id** (string) - Required - The ID card number to validate.

### Returns
- **boolean** - Returns true if the ID format is valid, otherwise false.

### Request Example
```typescript
import { isValid } from 'china-id-card';

isValid('622922197808118498'); // → true
```
```

--------------------------------

### Validation Functions

Source: https://github.com/tonyc726/china-id-card/blob/master/README.md

These functions are specifically designed for validating different aspects of a Chinese ID card number.

```APIDOC
## Validation Functions API Reference

### `checkBaseFormat(id)`

#### Description
Checks if the ID card number adheres to the basic format (15 or 18 digits).

#### Parameters
- **id** (string) - Required - The ID card number to check.

#### Returns
- **boolean** - `true` if the format is valid, `false` otherwise.

### `checkProvince(id)`

#### Description
Verifies if the province code within the ID card number is valid.

#### Parameters
- **id** (string) - Required - The ID card number to check.

#### Returns
- **boolean** - `true` if the province code is valid, `false` otherwise.
```

--------------------------------

### getCheckCode(id)

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/getCheckCode.md

Calculates the check digit (last digit) of a Chinese ID card number.

```APIDOC
## getCheckCode(id)

### Description
Calculates the check digit (last digit) of a Chinese ID card number.

### Method
N/A (This is a function, not an API endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Parameters
- **id** (string) - Required - The first 17 digits of the ID card number.

### Request Example
```typescript
import { getCheckCode } from 'china-id-card'

getCheckCode('62292219780811849')
```

### Response
#### Success Response
- **string | null** - The calculated check digit (0-9 or X), or `null` if the input format is invalid.

#### Response Example
```json
{
  "checkCode": "8"
}
```
```

--------------------------------

### isValid Function Signature

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/isValid.md

Defines the function signature for the ID card validation utility.

```typescript
function isValid(id: string): boolean;
```

--------------------------------

### Mask Chinese ID Number

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/api/mask.md

Use the `mask` function to obfuscate a Chinese ID number. It requires the ID number as a string and returns a masked string. Ensure the input is a valid string representing an ID number.

```typescript
import { mask } from 'china-id-card'

mask('622922197808118498')  // → '622***********8498'
mask('110101900101001')    // → '110***********1001'
```

--------------------------------

### Mask ID Card

Source: https://github.com/tonyc726/china-id-card/blob/master/docs/index.md

Obfuscate an ID card number by showing only the first 3 and last 4 digits.

```typescript
import { mask } from 'china-id-card';
mask('622922197808118498'); // → '622***********8498'
```

--------------------------------

### Mask ID card for privacy

Source: https://context7.com/tonyc726/china-id-card/llms.txt

The mask function replaces the middle section of an ID number with 11 asterisks, keeping the first 3 and last 4 digits visible.

```typescript
import { mask } from 'china-id-card';

// 脱敏 18 位身份证
console.log(mask('310000198102276323')); // → '310***********6323'

// 脱敏 15 位身份证（先转换为 18 位再脱敏）
console.log(mask('310000810227632')); // → '310***********6323'

// 无效输入返回错误提示
console.log(mask('abc')); // → 'Invalid ID'
console.log(mask('')); // → 'Invalid ID'
console.log(mask('12345')); // → 'Invalid ID'
```

--------------------------------

### mask - Mask ID Card

Source: https://context7.com/tonyc726/china-id-card/llms.txt

Masks an ID card number, preserving the first 3 and last 4 digits, with the middle replaced by asterisks. Handles both 15 and 18-digit formats.

```APIDOC
## mask - Mask ID Card

### Description
Masks an ID card number, preserving the first 3 and last 4 digits, with the middle replaced by 11 asterisks. Handles both 15 and 18-digit formats by first converting 15-digit IDs to 18-digit.

### Method
`mask(idCardNumber: string): string`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import { mask } from 'china-id-card';

console.log(mask('310000198102276323')); // '310***********6323'
console.log(mask('310000810227632')); // '310***********6323'
console.log(mask('abc')); // 'Invalid ID'
```

### Response
#### Success Response (string)
- The masked ID card number.

#### Response Example
```json
"310***********6323"
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.