@vcard/vcard4-generator

A library for generating v4 vCards

Heads Up!

This is still very much a WIP project and is not feature complete.

Install

npm install @vcard/vcard4-generator

Usage

import Vcard4Generator, { Vcard4GeneratorConfig } from '@vcard/vcard4-generator';

const config: Vcard4GeneratorConfig = {
    fn: 'Captain Awesome',
    email: '[email protected]',
    url: 'http://www.example.com/'
};
const vcard = new Vcard4Generator(config);

vcard.toString();
// >> BEGIN:VCARD
// >> VERSION:4.0
// >> EMAIL:[email protected]
// >> FN:Captain Awesome
// >> URL:http://www.example.com/
// >> END:VCARD

Building

From the monorepo root:

npx lerna --scope @vcard/vcard4-generator run build

Testing

From the monorepo root:

npm test

To-Do

• [ ] Properties
  • [x] ADR
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LABEL Parameter
    • [x] LANGUAGE Parameter
    • [x] GEO Parameter
    • [x] TZ Parameter
    • [x] ALTID Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
  • [x] ANNIVERSARY
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] ALTID Parameter
    • [x] CALSCALE Parameter (for date-and-or-time type only)
  • [x] BDAY
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] ALTID Parameter
    • [x] CALSCALE Parameter (for date-and-or-time type only)
    • [x] LANGUAGE Parameter (for text type only)
  • [x] BEGIN
    • [x] No Parameters
  • [x] BIRTHPLACE (RFC6474)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
  • [x] CALADRURI
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] CALURI
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] CATEGORIES
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] ALTID Parameter
    • [ ] Implement Constructor Array Argument Support
  • [x] CLIENTPIDMAP
    • [x] Line Folding
    • [x] Value Escaping
    • [x] No Parameters
    • [x] No VALUE Parameter
    • [ ] Implement Constructor Array Argument Support
  • [x] CONTACT-URI (RFC8605)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PREF Parameter
  • [x] DEATHDATE (RFC6474)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] CALSCALE Parameter (for date-and-or-time type only)
    • [x] LANGUAGE Parameter (for text type only)
    • [x] ALTID Parameter
  • [x] DEATHPLACE (RFC6474)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
    • [x] ALTID Parameter
  • [x] EMAIL
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] ALTID Parameter
  • [x] END
    • [x] No Parameters
  • [x] EXPERTISE (RFC6715)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] LEVEL Parameter
    • [x] INDEX Parameter
    • [x] LANGUAGE Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] FBURL
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] ALTID Parameter
  • [x] FN
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] TYPE Parameter
    • [x] LANGUAGE Parameter
    • [x] ALTID Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
  • [x] GENDER
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [ ] Implement Constructor Array Argument Support
  • [x] GEO
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] HOBBY (RFC6715)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] LEVEL Parameter
    • [x] INDEX Parameter
    • [x] LANGUAGE Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] IMPP
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] INTEREST (RFC6715)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] LEVEL Parameter
    • [x] INDEX Parameter
    • [x] LANGUAGE Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] KEY
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] MEDIATYPE Parameter (for URI type only)
    • [x] ALTID Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
  • [x] KIND
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
  • [x] LANG
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] LOGO
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] MEMBER
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] MEDIATYPE Parameter
  • [x] N
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] SORT-AS Parameter
    • [x] LANGUAGE Parameter
    • [x] ALTID Parameter
  • [x] NICKNAME
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] TYPE Parameter
    • [x] LANGUAGE Parameter
    • [x] ALTID Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
  • [x] NOTE
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] ALTID Parameter
  • [x] ORG
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] SORT-AS Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] ORG-DIRECTORY (RFC6715)
    • [x] Line Folding
    • [x] Value Escaping
    • [x] INDEX Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] PHOTO
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] PREF Parameter
    • [x] PID Parameter
  • [x] PRODID
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
  • [x] RELATED
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] MEDIATYPE Parameter (for URI type only)
    • [x] LANGUAGE Parameter (for text type only)
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] REV
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
  • [x] ROLE
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] ALTID Parameter
  • [x] SOUND
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] SOURCE
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] MEDIATYPE Parameter
  • [x] TEL
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] MEDIATYPE Parameter (for URI type only)
    • [x] TYPE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
  • [x] TITLE
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] LANGUAGE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] ALTID Parameter
    • [x] TYPE Parameter
  • [x] TZ
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] ALTID Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
  • [x] UID
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
  • [x] URL
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] PID Parameter
    • [x] PREF Parameter
    • [x] TYPE Parameter
    • [x] MEDIATYPE Parameter
    • [x] ALTID Parameter
  • [x] VERSION
    • [x] No Parameters
  • [x] XML
    • [x] Line Folding
    • [x] Value Escaping
    • [x] VALUE Parameter
    • [x] ALTID Parameter
• [x] Implement Parameter Value Encoding as Specified in RFC6868

Reference

Property Cardinalities

Property cardinalities are indicated using the following notation, which is based on ABNF (see [RFC5234], Section 3.6):

| Cardinality | Meaning | |:-----------:|--------------------------------------------------| | 1 | Exactly one instance per vCard MUST be present. | | 1 | Exactly one instance per vCard MAY be present. | | 1 | One or more instances per vCard MUST be present. | | * | One or more instances per vCard MAY be present. |

Properties defined in a vCard instance may have multiple values depending on the property cardinality. The general rule for encoding multi-valued properties is to simply create a new content line for each value (including the property name). However, it should be noted that some value types support encoding multiple values in a single content line by separating the values with a comma ",". This approach has been taken for several of the content types defined below (date, time, integer, float).

Property Parameters

A property can have attributes associated with it. These "property parameters" contain meta-information about the property or the property value. In some cases, the property parameter can be multi- valued in which case the property parameter value elements are separated by a COMMA (U+002C).

Property parameter value elements that contain the COLON (U+003A), SEMICOLON (U+003B), or COMMA (U+002C) character separators MUST be specified as quoted-string text values. Property parameter values MUST NOT contain the DQUOTE (U+0022) character. The DQUOTE character is used as a delimiter for parameter values that contain restricted characters or URI text.

Applications MUST ignore x-param and iana-param values they don't recognize.

Property Value Escaping

Some properties may contain one or more values delimited by a COMMA character (U+002C). Therefore, a COMMA character in a value MUST be escaped with a BACKSLASH character (U+005C), even for properties that don't allow multiple instances (for consistency).

Some properties (e.g., N and ADR) comprise multiple fields delimited by a SEMICOLON character (U+003B). Therefore, a SEMICOLON in a field of such a "compound" property MUST be escaped with a BACKSLASH character. SEMICOLON characters in non-compound properties MAY be escaped. On input, an escaped SEMICOLON character is never a field separator. An unescaped SEMICOLON character may be a field separator, depending on the property in which it appears.

Furthermore, some fields of compound properties may contain a list of values delimited by a COMMA character. Therefore, a COMMA character in one of a field's values MUST be escaped with a BACKSLASH character, even for fields that don't allow multiple values (for consistency). Compound properties allowing multiple instances MUST NOT be encoded in a single content line.

Finally, BACKSLASH characters in values MUST be escaped with a BACKSLASH character. NEWLINE (U+000A) characters in values MUST be encoded by two characters: a BACKSLASH followed by either an 'n' (U+006E) or an 'N' (U+004E).

In all other cases, escaping MUST NOT be used.

Links

• vCard Format Specification
• vCard KIND:application
• vCard Format Extensions: Place of Birth, Place and Date of Death
• vCard Format Extensions: Representing vCard Extensions Defined by the Open Mobile Alliance (OMA) Converged Address Book (CAB) Group
• Additional Data Related to an Emergency Call § vCard Parameter Value Registration
• vCard Format Extensions: ICANN Extensions for the Registration Data Access Protocol (RDAP)
• vCard Elements (IANA Protocol Registry)

License

The MIT License (Expat). See the license file for details.