vcard-utf8-parser

Modern TypeScript CommonJS parser for VCF/vCard files with a simple, promise-first API that produces easy-to-read JSON.

Features

• Promise-first async API
• Decodes QUOTED-PRINTABLE and BASE64
• Handles CHARSET with iconv-lite
• Line unfolding and structured fields (N, ADR, ORG)
• Keeps all properties in a normalized map

Supported vCard versions

Parses vCard 2.1, 3.0, and 4.0 style property lines. It is lenient and does not validate against the full RFCs.

Install

npm install vcard-utf8-parser

Usage

const { parseFile, parseVcf } = require("vcard-utf8-parser");

async function run() {
  const contacts = await parseFile("contacts.vcf");
  console.log(contacts[0]);
}

run().catch(console.error);

Parse from a string:

const vcfText = "BEGIN:VCARD\nVERSION:2.1\nFN:John Doe\nEND:VCARD";
const contacts = await parseVcf(vcfText);

API

parseFile(path, options)

Reads a VCF file and returns an array of parsed contacts.

Options:

• fileEncoding: file encoding for the entire VCF (default: utf8)
• defaultCharset: charset used for encoded values when not specified
• decodeBase64: return Buffer for base64 values (default: false)
• includeRaw: include raw vCard lines in card.raw

parseVcf(input, options)

Parses a VCF string (or Buffer) and returns an array of contacts.

Options:

• inputEncoding: when input is a Buffer, how to decode it (default: utf8)
• defaultCharset: charset used for encoded values when not specified
• decodeBase64: return Buffer for base64 values (default: false)
• includeRaw: include raw vCard lines in card.raw

Output shape

Each card includes normalized fields and all raw properties:

• formattedName, name, phones, emails, addresses, photos
• properties: map of property name -> array of detailed entries

This lets you consume a clean JSON shape while still keeping full vCard data.

Field mappings

• FN -> formattedName
• N -> name (family, given, additional, prefix, suffix)
• ORG -> organization (array of components)
• TITLE -> title
• TEL -> phones
• EMAIL -> emails
• URL -> urls
• ADR -> addresses
• NOTE -> notes
• PHOTO -> photos

JSON example

[
  {
    "version": "4.0",
    "formattedName": "Valid User",
    "name": {
      "family": "User",
      "given": "Valid"
    },
    "organization": ["Example", "Org"],
    "phones": [{ "value": "+123456", "types": ["cell"], "pref": true }],
    "emails": [{ "value": "[email protected]", "types": ["work"], "pref": false }],
    "addresses": [
      {
        "street": "Street",
        "locality": "City",
        "region": "Region",
        "postalCode": "12345",
        "country": "Country",
        "types": ["work"],
        "pref": false
      }
    ],
    "photos": [],
    "properties": {
      "FN": [{ "name": "FN", "params": {}, "value": "Valid User", "rawValue": "Valid User" }]
    }
  }
]

Limitations

• Lenient parser; it does not validate full vCard conformance.
• Unknown properties are preserved under properties but are not normalized.
• Base64 values are returned as strings unless decodeBase64 is enabled.