@vcard/vcard4-generator NPM

@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: 'hello@example.com',
    url: 'http://www.example.com/'
};
const vcard = new Vcard4Generator(config);

vcard.toString();
// >> BEGIN:VCARD
// >> VERSION:4.0
// >> EMAIL:hello@example.com
// >> 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
- ADR
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LABEL Parameter
  - LANGUAGE Parameter
  - GEO Parameter
  - TZ Parameter
  - ALTID Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
- ANNIVERSARY
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - ALTID Parameter
  - CALSCALE Parameter (for date-and-or-time type only)
- BDAY
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - ALTID Parameter
  - CALSCALE Parameter (for date-and-or-time type only)
  - LANGUAGE Parameter (for text type only)
- BEGIN
  - No Parameters
- BIRTHPLACE (RFC6474)
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
- CALADRURI
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- CALURI
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- CATEGORIES
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - ALTID Parameter
  - Implement Constructor Array Argument Support
- CLIENTPIDMAP
  - Line Folding
  - Value Escaping
  - No Parameters
  - No VALUE Parameter
  - Implement Constructor Array Argument Support
- CONTACT-URI (RFC8605)
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PREF Parameter
- DEATHDATE (RFC6474)
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - CALSCALE Parameter (for date-and-or-time type only)
  - LANGUAGE Parameter (for text type only)
  - ALTID Parameter
- DEATHPLACE (RFC6474)
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
  - ALTID Parameter
- EMAIL
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - ALTID Parameter
- END
  - No Parameters
- EXPERTISE (RFC6715)
  - Line Folding
  - Value Escaping
  - LEVEL Parameter
  - INDEX Parameter
  - LANGUAGE Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- FBURL
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - ALTID Parameter
- FN
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - TYPE Parameter
  - LANGUAGE Parameter
  - ALTID Parameter
  - PID Parameter
  - PREF Parameter
- GENDER
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - Implement Constructor Array Argument Support
- GEO
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- HOBBY (RFC6715)
  - Line Folding
  - Value Escaping
  - LEVEL Parameter
  - INDEX Parameter
  - LANGUAGE Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- IMPP
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- INTEREST (RFC6715)
  - Line Folding
  - Value Escaping
  - LEVEL Parameter
  - INDEX Parameter
  - LANGUAGE Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- KEY
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - MEDIATYPE Parameter (for URI type only)
  - ALTID Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
- KIND
  - Line Folding
  - Value Escaping
  - VALUE Parameter
- LANG
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- LOGO
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- MEMBER
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - MEDIATYPE Parameter
- N
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - SORT-AS Parameter
  - LANGUAGE Parameter
  - ALTID Parameter
- NICKNAME
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - TYPE Parameter
  - LANGUAGE Parameter
  - ALTID Parameter
  - PID Parameter
  - PREF Parameter
- NOTE
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - ALTID Parameter
- ORG
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - SORT-AS Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- ORG-DIRECTORY (RFC6715)
  - Line Folding
  - Value Escaping
  - INDEX Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- PHOTO
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - ALTID Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - PREF Parameter
  - PID Parameter
- PRODID
  - Line Folding
  - Value Escaping
  - VALUE Parameter
- RELATED
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - MEDIATYPE Parameter (for URI type only)
  - LANGUAGE Parameter (for text type only)
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- REV
  - Line Folding
  - Value Escaping
  - VALUE Parameter
- ROLE
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - ALTID Parameter
- SOUND
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- SOURCE
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - MEDIATYPE Parameter
- TEL
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - MEDIATYPE Parameter (for URI type only)
  - TYPE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
- TITLE
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - LANGUAGE Parameter
  - PID Parameter
  - PREF Parameter
  - ALTID Parameter
  - TYPE Parameter
- TZ
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - ALTID Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
- UID
  - Line Folding
  - Value Escaping
  - VALUE Parameter
- URL
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - PID Parameter
  - PREF Parameter
  - TYPE Parameter
  - MEDIATYPE Parameter
  - ALTID Parameter
- VERSION
  - No Parameters
- XML
  - Line Folding
  - Value Escaping
  - VALUE Parameter
  - ALTID Parameter
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.