### vcard4 Parameter Examples

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates the usage of various vcard4 parameters like TypeParameter, PrefParameter, LanguageParameter, MediatypeParameter, AltidParameter, and IndexParameter. Ensure necessary types are imported.

```javascript
import {
  TypeParameter,
  PrefParameter,
  LanguageParameter,
  MediatypeParameter,
  AltidParameter,
  IndexParameter,
  ParameterValueType,
  IntegerType,
  TextType
} from 'vcard4';

// TypeParameter - for work/home/cell distinctions
// For general properties (email, address)
const workType = new TypeParameter('EmailProperty', new ParameterValueType('work'));
const homeType = new TypeParameter('AdrProperty', new ParameterValueType('home'));
console.log(workType.repr());      // "TYPE=work"

// For telephone-specific types
const cellType = new TypeParameter('TelProperty', new ParameterValueType('cell'));
const faxType = new TypeParameter('TelProperty', new ParameterValueType('fax'));
const voiceType = new TypeParameter('TelProperty', new ParameterValueType('voice'));
console.log(cellType.repr());      // "TYPE=cell"

// Multiple types at once
const multiType = new TypeParameter('TelProperty', [
  new ParameterValueType('work'),
  new ParameterValueType('voice')
]);
console.log(multiType.repr());     // "TYPE=\"work,voice\""

// PrefParameter - preference order (1-100, lower is more preferred)
const preferred = new PrefParameter(new IntegerType(1));
console.log(preferred.repr());     // "PREF=1"

const secondary = new PrefParameter(new IntegerType(2));
console.log(secondary.repr());     // "PREF=2"

// LanguageParameter - language of the text value
const englishLang = new LanguageParameter(new TextType('en'));
const frenchLang = new LanguageParameter(new TextType('fr-CA'));
console.log(englishLang.repr());   // "LANGUAGE=en"
console.log(frenchLang.repr());    // "LANGUAGE=fr-CA"

// MediatypeParameter - MIME type for URIs
const jpegMedia = new MediatypeParameter(new TextType('image/jpeg'));
const pngMedia = new MediatypeParameter(new TextType('image/png'));
console.log(jpegMedia.repr());     // "MEDIATYPE=image/jpeg"

// AltidParameter - link alternative representations
const altid1 = new AltidParameter(new TextType('1'));
console.log(altid1.repr());        // "ALTID=1"

// IndexParameter - ordering in multi-value properties (1-based)
const index1 = new IndexParameter(new IntegerType(1));
const index2 = new IndexParameter(new IntegerType(2));
console.log(index1.repr());        // "INDEX=1"
```

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

### Create vCard Properties with Parameters and Values

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates creating various vCard properties with parameters and values, showing the full pattern for property construction. This includes FN, Nickname, Photo, Bday, Anniversary, Gender, Email, Tel, Title, Role, Note, URL, Categories, UID, and Rev properties.

```javascript
import {
  VCARD,
  FNProperty,
  NProperty,
  NicknameProperty,
  PhotoProperty,
  BdayProperty,
  AnniversaryProperty,
  GenderProperty,
  EmailProperty,
  TelProperty,
  AdrProperty,
  OrgProperty,
  TitleProperty,
  RoleProperty,
  NoteProperty,
  URLProperty,
  CategoriesProperty,
  UIDProperty,
  RevProperty,
  TextType,
  TextListType,
  URIType,
  DateTimeType,
  SpecialValueType,
  SexType,
  TypeParameter,
  PrefParameter,
  LanguageParameter,
  MediatypeParameter,
  ParameterValueType,
  IntegerType
} from 'vcard4';

// FNProperty - Formatted Name (required)
const fn = new FNProperty([], new TextType('Dr. John William Doe Jr.'));

// NicknameProperty - with multiple nicknames
const nickname = new NicknameProperty(
  [],
  new TextListType(['Johnny', 'JD', 'Doc'])
);

// PhotoProperty - with media type
const photo = new PhotoProperty(
  [new MediatypeParameter(new TextType('image/jpeg'))],
  new URIType('https://example.com/photos/johndoe.jpg')
);

// BdayProperty - birthday with date value
const bday = new BdayProperty(
  [],
  new DateTimeType('dateandortime', '19850415')
);

// AnniversaryProperty
const anniversary = new AnniversaryProperty(
  [],
  new DateTimeType('dateandortime', '20100620')
);

// GenderProperty - with both sex and identity
const gender = new GenderProperty(
  [],
  new SpecialValueType('GenderProperty', [
    new SexType('M'),
    new TextType('Male')
  ])
);

// Multiple email addresses with preference
const email1 = new EmailProperty(
  [
    new TypeParameter('EmailProperty', new ParameterValueType('work')),
    new PrefParameter(new IntegerType(1))
  ],
  new TextType('john.doe@company.com')
);

const email2 = new EmailProperty(
  [
    new TypeParameter('EmailProperty', new ParameterValueType('home')),
    new PrefParameter(new IntegerType(2))
  ],
  new TextType('johndoe@personal.com')
);

// Multiple phone numbers
const tel1 = new TelProperty(
  [
    new TypeParameter('TelProperty', [
      new ParameterValueType('work'),
      new ParameterValueType('voice')
    ]),
    new PrefParameter(new IntegerType(1))
  ],
  new URIType('tel:+1-555-WORK-000')
);

const tel2 = new TelProperty(
  [new TypeParameter('TelProperty', new ParameterValueType('cell'))],
  new URIType('tel:+1-555-CELL-111')
);

// TitleProperty - job title
const title = new TitleProperty([], new TextType('Chief Technology Officer'));

// RoleProperty - role/function
const role = new RoleProperty([], new TextType('Executive Leadership'));

// NoteProperty - with language
const note = new NoteProperty(
  [new LanguageParameter(new TextType('en'))],
  new TextType('Key contact for technical partnerships')
);

// URLProperty - website
const url = new URLProperty(
  [new TypeParameter('URLProperty', new ParameterValueType('work'))],
  new URIType('https://www.company.com/team/johndoe')
);

// CategoriesProperty - tags/categories
const categories = new CategoriesProperty(
  [],
  new TextListType(['Executive', 'Engineering', 'VIP'])
);

// UIDProperty - unique identifier
const uid = new UIDProperty(
  [],
  new TextType('urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6')
);

// RevProperty - last revision timestamp
const rev = new RevProperty(
  [],
  new DateTimeType('timestamp', '20240115T120000Z')
);

// Complete vCard
const vcard = new VCARD([
  fn, nickname, photo, bday, anniversary, gender,
  email1, email2, tel1, tel2, title, role,
  note, url, categories, uid, rev
]);

console.log(vcard.repr());
```

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

### Create a Complete Contact vCard

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates creating a comprehensive vCard 4.0 contact using the VCARD class and various property types. Ensure all necessary imports are included before use.

```javascript
import {
  VCARD,
  FNProperty,
  NProperty,
  EmailProperty,
  TelProperty,
  AdrProperty,
  OrgProperty,
  TitleProperty,
  NoteProperty,
  TextType,
  SpecialValueType,
  TypeParameter,
  PrefParameter,
  IntegerType,
  ParameterValueType,
  URIType
} from 'vcard4';

// Create a complete contact vCard
const fullName = new FNProperty([], new TextType('John Doe'));

const structuredName = new NProperty(
  [],
  new SpecialValueType('NProperty', [
    new TextType('Doe'),      // surname
    new TextType('John'),     // given name
    new TextType('William'),  // additional names
    new TextType('Dr.'),      // prefix
    new TextType('Jr.')       // suffix
  ])
);

const workEmail = new EmailProperty(
  [
    new TypeParameter('EmailProperty', new ParameterValueType('work')),
    new PrefParameter(new IntegerType(1))
  ],
  new TextType('john.doe@company.com')
);

const homeEmail = new EmailProperty(
  [new TypeParameter('EmailProperty', new ParameterValueType('home'))],
  new TextType('john@personal.com')
);

const cellPhone = new TelProperty(
  [new TypeParameter('TelProperty', new ParameterValueType('cell'))],
  new URIType('tel:+1-555-123-4567')
);

const workAddress = new AdrProperty(
  [new TypeParameter('AdrProperty', new ParameterValueType('work'))],
  new SpecialValueType('AdrProperty', [
    null,                           // PO Box
    null,                           // Extended address
    new TextType('123 Business St'), // Street
    new TextType('New York'),       // City
    new TextType('NY'),             // Region/State
    new TextType('10001'),          // Postal code
    new TextType('USA')             // Country
  ])
);

const organization = new OrgProperty(
  [],
  new SpecialValueType('OrgProperty', [
    new TextType('Acme Corporation'),
    new TextType('Engineering Department')
  ])
);

const title = new TitleProperty([], new TextType('Senior Software Engineer'));

const note = new NoteProperty([], new TextType('Met at tech conference 2024'));

const vcard = new VCARD([
  fullName,
  structuredName,
  workEmail,
  homeEmail,
  cellPhone,
  workAddress,
  organization,
  title,
  note
]);

// Output as vCard text format
console.log(vcard.repr());
/* Output:
BEGIN:VCARD
VERSION:4.0
FN:John Doe
N:Doe;John;William;Dr.;Jr.
EMAIL;TYPE=work;PREF=1:john.doe@company.com
EMAIL;TYPE=home:john@personal.com
TEL;TYPE=cell:tel:+1-555-123-4567
ADR;TYPE=work:;;123 Business St;New York;NY;10001;USA
ORG:Acme Corporation;Engineering Department
TITLE:Senior Software Engineer
NOTE:Met at tech conference 2024
END:VCARD
*/

// Output as XML vCard
console.log(vcard.reprXML());
/* Output:
<?xml version="1.0" encoding="UTF-8"?><vcards xmlns="urn:ietf:params:xml:ns:vcard-4.0"><vcard>...</vcard></vcards>
*/

// Output as jCard JSON
console.log(JSON.stringify(vcard.reprJSON(), null, 2));
/* Output:
["vcard", [
  ["fn", {}, "text", "John Doe"],
  ["n", {}, "text", ["Doe", "John", "William", "Dr.", "Jr."]],
  ...
]]
*/
```

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

### Using vCard4 Value Types

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates the instantiation and representation methods for TextType, URIType, DateTimeType, IntegerType, BooleanType, and LanguageTagType. Ensure correct import of types.

```javascript
import {
  TextType,
  URIType,
  DateTimeType,
  IntegerType,
  BooleanType,
  LanguageTagType
} from 'vcard4';

// TextType - for plain text values
const textValue = new TextType('Hello, World!');
console.log(textValue.repr());      // "Hello\, World!" (escaped)
console.log(textValue.reprXML());   // "<text>Hello, World!</text>"
console.log(textValue.reprJSON());  // ["text", "Hello, World!"]

// URIType - for validated URIs
const uriValue = new URIType('https://example.com/profile');
console.log(uriValue.repr());       // "https://example.com/profile"
console.log(uriValue.reprXML());    // "<uri>https://example.com/profile</uri>"

const telUri = new URIType('tel:+1-555-123-4567');
const mailtoUri = new URIType('mailto:user@example.com');

// DateTimeType - various date/time formats
// Date only (YYYYMMDD)
const dateValue = new DateTimeType('dateandortime', '19850401');
console.log(dateValue.repr());      // "19850401"
console.log(dateValue.reprXML());   // "<date>19850401</date>"
console.log(dateValue.reprJSON());  // ["date-and-or-time", "1985-04-01"]

// Time only
const timeValue = new DateTimeType('time', '083000');
console.log(timeValue.repr());      // "083000"

// Date and time combined
const dateTimeValue = new DateTimeType('datetime', '20240115T143022');
console.log(dateTimeValue.repr());  // "20240115T143022"

// Timestamp with timezone
const timestampValue = new DateTimeType('timestamp', '20240115T143022Z');
console.log(timestampValue.repr()); // "20240115T143022Z"

// UTC offset
const utcOffset = new DateTimeType('utcoffset', '-0500');
console.log(utcOffset.repr());      // "-0500"

// IntegerType - for numeric values
const intValue = new IntegerType(42);
console.log(intValue.repr());       // "42"
console.log(intValue.reprXML());    // "<integer>42</integer>"

// BooleanType - for true/false values
const boolValue = new BooleanType(true);
console.log(boolValue.repr());      // "true"

// LanguageTagType - for language codes
const langTag = new LanguageTagType('en-US');
console.log(langTag.repr());        // "en-US"
```

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

### Creating GenderProperty Value with SpecialValueType

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates how to create a GenderProperty value using SpecialValueType. It requires a 2-element array for sex and gender identity text. Imports are required.

```javascript
import {
  SpecialValueType,
  TextType,
  TextListType,
  SexType,
  IntegerType,
  URIType
} from 'vcard4';

// GenderProperty value - 2-element array: [sex, identity]
const genderValue = new SpecialValueType('GenderProperty', [
  new SexType('M'),                // sex component (M, F, O, N, U)
  new TextType('Male')             // gender identity text
]);
console.log(genderValue.value);    // "M;Male"

```

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

### Creating NProperty Value with SpecialValueType

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates creating a full NProperty value using SpecialValueType, which expects a 5-element array for surname, given name, additional names, prefix, and suffix. Imports are required.

```javascript
import {
  SpecialValueType,
  TextType,
  TextListType,
  SexType,
  IntegerType,
  URIType
} from 'vcard4';

// NProperty value - 5-element array: [surname, given, additional, prefix, suffix]
const nameValue = new SpecialValueType('NProperty', [
  new TextType('Smith'),           // surname
  new TextType('John'),            // given name
  new TextListType(['William', 'Robert']), // additional names (can be list)
  new TextType('Dr.'),             // honorific prefix
  new TextType('PhD')              // honorific suffix
]);
console.log(nameValue.value);      // "Smith;John;William,Robert;Dr.;PhD"
console.log(nameValue.valueXML);   // "<surname>Smith</surname><given>John</given>..."

// Partial name (null for missing components)
const partialName = new SpecialValueType('NProperty', [
  new TextType('Doe'),
  new TextType('Jane'),
  null,  // no additional names
  null,  // no prefix
  null   // no suffix
]);
console.log(partialName.value);    // "Doe;Jane;;;"

```

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

### Creating AdrProperty Value with SpecialValueType

Source: https://context7.com/kelseykm/vcard4/llms.txt

Shows how to construct an AdrProperty value using SpecialValueType. This type requires a 7-element array for address components including PO Box, extended address, street, locality, region, postal code, and country. Imports are required.

```javascript
import {
  SpecialValueType,
  TextType,
  TextListType,
  SexType,
  IntegerType,
  URIType
} from 'vcard4';

// AdrProperty value - 7-element array
const addressValue = new SpecialValueType('AdrProperty', [
  new TextType('PO Box 123'),      // PO Box
  new TextType('Suite 400'),       // Extended address
  new TextType('123 Main Street'), // Street address
  new TextType('Anytown'),         // Locality (city)
  new TextType('CA'),              // Region (state)
  new TextType('12345'),           // Postal code
  new TextType('USA')              // Country
]);
console.log(addressValue.value);
// "PO Box 123;Suite 400;123 Main Street;Anytown;CA;12345;USA"

```

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

### Creating KindProperty Value with SpecialValueType

Source: https://context7.com/kelseykm/vcard4/llms.txt

Shows the creation of a KindProperty value using SpecialValueType with a single string argument. Valid kinds include 'individual', 'group', 'org', 'location', 'application', and 'x-*'. Imports are required.

```javascript
import {
  SpecialValueType,
  TextType,
  TextListType,
  SexType,
  IntegerType,
  URIType
} from 'vcard4';

// KindProperty value - single string
const kindValue = new SpecialValueType('KindProperty', 'individual');
console.log(kindValue.value);      // "individual"
// Valid kinds: individual, group, org, location, application, x-*

```

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

### Handle MissingArgument Errors in vcard4

Source: https://context7.com/kelseykm/vcard4/llms.txt

Demonstrates how to catch and handle `MissingArgument` errors, which occur when required arguments are not provided to vcard4 constructors.

```javascript
import {
  VCARD,
  FNProperty,
  UIDProperty,
  TextType,
  IntegerType,
  PrefParameter,
  MissingArgument,
  InvalidArgument,
  InvalidVcard,
  parse
} from 'vcard4';

// MissingArgument - when required arguments are missing
try {
  new FNProperty(); // Missing params and value
} catch (error) {
  if (error instanceof MissingArgument) {
    console.log('Missing argument:', error.message);
    // "Parameters and value for FNProperty must be supplied"
  }
}
```

```javascript
// VCARD requires at least one FNProperty
try {
  new VCARD([]); // No FNProperty
} catch (error) {
  if (error instanceof MissingArgument) {
    console.log('Missing FN:', error.message);
    // "One or more FNProperty instances must be supplied"
  }
}
```

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

### Creating OrgProperty Value with SpecialValueType

Source: https://context7.com/kelseykm/vcard4/llms.txt

Illustrates the creation of an OrgProperty value using SpecialValueType. This type supports a variable-length array for organization components, such as company name, division, and department. Imports are required.

```javascript
import {
  SpecialValueType,
  TextType,
  TextListType,
  SexType,
  IntegerType,
  URIType
} from 'vcard4';

// OrgProperty value - variable length array
const orgValue = new SpecialValueType('OrgProperty', [
  new TextType('ABC Corporation'),
  new TextType('North American Division'),
  new TextType('Engineering')
]);
console.log(orgValue.value);       // "ABC Corporation;North American Division;Engineering"

```

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

### Handle InvalidVcard Parsing Errors

Source: https://context7.com/kelseykm/vcard4/llms.txt

Shows how to catch `InvalidVcard` errors that occur when attempting to parse malformed vCard strings, such as those with incorrect line endings.

```javascript
// InvalidVcard - when parsing invalid vCard strings
try {
  // vCard must use CRLF line endings
  parse('BEGIN:VCARD\nVERSION:4.0\nFN:Test\nEND:VCARD\n');
} catch (error) {
  if (error instanceof InvalidVcard) {
    console.log('Parse error:', error.message);
  }
}
```

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

### Implement Safe vCard Parsing

Source: https://context7.com/kelseykm/vcard4/llms.txt

Provides a utility function `safeParseVcard` that wraps the `parse` function to handle potential errors gracefully, returning a structured result indicating success or failure.

```javascript
// Safe parsing with error handling
function safeParseVcard(vcardString) {
  try {
    return { success: true, data: parse(vcardString) };
  } catch (error) {
    return {
      success: false,
      error: error.message,
      type: error.constructor.name
    };
  }
}

const result = safeParseVcard('invalid vcard');
console.log(result);
// { success: false, error: "...", type: "InvalidVcard" }
```

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

### Parse vCard Strings to JavaScript Objects

Source: https://context7.com/kelseykm/vcard4/llms.txt

Use the `parse` function to convert vCard formatted strings into JavaScript objects. It supports parsing both single and multiple vCards within a single string.

```javascript
import { parse } from 'vcard4';

// Parse a single vCard
const vcardString = `BEGIN:VCARD\r\nVERSION:4.0\r\nN:Doe;John;;;\r\nFN:John Doe\r\nORG:Example.com Inc.;Marketing\r\nTITLE:Imaginary test person\r\nEMAIL;TYPE=work;PREF=1:johnDoe@example.org\r\nTEL;TYPE=cell:tel:+1-781-555-1212\r\nTEL;TYPE=home:tel:+1-202-555-1212\r\nNOTE:John Doe has a long and varied history\, being documented on more police files than anyone else.\r\nCATEGORIES:Work,Test group\r\nEND:VCARD\r\n`;

const parsedVcard = parse(vcardString);
console.log(parsedVcard);
/* Output: Object containing parsed vCard properties:
{
  VERSION: '4.0',
  N: { value: 'Doe;John;;;', params: {} },
  FN: { value: 'John Doe', params: {} },
  ORG: { value: 'Example.com Inc.;Marketing', params: {} },
  ...
}
*/

// Parse multiple vCards
const multipleVcards = `BEGIN:VCARD\r\nVERSION:4.0\r\nFN:James Bond\r\nEND:VCARD\r\nBEGIN:VCARD\r\nVERSION:4.0\r\nFN:Jane Bond\r\nEND:VCARD\r\nBEGIN:VCARD\r\nVERSION:4.0\r\nFN:Michael Bond\r\nEND:VCARD\r\n`;

const parsedArray = parse(multipleVcards);
console.log(parsedArray.length); // 3
console.log(parsedArray[0]); // First vCard object
console.log(parsedArray[1]); // Second vCard object

```

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

### Group Related vCard Properties

Source: https://context7.com/kelseykm/vcard4/llms.txt

The `Group` class allows logical grouping of related vCard properties with a common prefix, useful for associating contact information like addresses and phone numbers.

```javascript
import {
  VCARD,
  Group,
  FNProperty,
  TelProperty,
  AdrProperty,
  TextType,
  URIType,
  SpecialValueType,
  TypeParameter,
  ParameterValueType
} from 'vcard4';

// Create grouped properties for work contact info
const workGroup = new Group(
  [
    new TelProperty(
      [new TypeParameter('TelProperty', new ParameterValueType('voice'))],
      new URIType('tel:+1-555-WORK-123')
    ),
    new AdrProperty(
      [new TypeParameter('AdrProperty', new ParameterValueType('work'))],
      new SpecialValueType('AdrProperty', [
        null, null,
        new TextType('456 Corporate Blvd'),
        new TextType('San Francisco'),
        new TextType('CA'),
        new TextType('94102'),
        new TextType('USA')
      ])
    )
  ],
  'work'
);

// Create grouped properties for home contact info
const homeGroup = new Group(
  [
    new TelProperty(
      [new TypeParameter('TelProperty', new ParameterValueType('voice'))],
      new URIType('tel:+1-555-HOME-456')
    ),
    new AdrProperty(
      [new TypeParameter('AdrProperty', new ParameterValueType('home'))],
      new SpecialValueType('AdrProperty', [
        null, null,
        new TextType('789 Residential Lane'),
        new TextType('Oakland'),
        new TextType('CA'),
        new TextType('94612'),
        new TextType('USA')
      ])
    )
  ],
  'home'
);

const vcard = new VCARD([
  new FNProperty([], new TextType('Alice Smith')),
  workGroup,
  homeGroup
]);

console.log(vcard.repr());
/* Output:
BEGIN:VCARD
VERSION:4.0
FN:Alice Smith
work.TEL;TYPE=voice:tel:+1-555-WORK-123
work.ADR;TYPE=work:;;456 Corporate Blvd;San Francisco;CA;94102;USA
home.TEL;TYPE=voice:tel:+1-555-HOME-456
home.ADR;TYPE=home:;;789 Residential Lane;Oakland;CA;94612;USA
END:VCARD
*/

// Group XML output
console.log(workGroup.reprXML());
/* Output:
<group name="work"><tel><parameters><type><text>voice</text></type></parameters><uri>tel:+1-555-WORK-123</uri></tel><adr>...</adr></group>
*/

// Group JSON output
console.log(JSON.stringify(workGroup.reprJSON(), null, 2));
/* Output:
[
  ["tel", { "group": "work", "type": "voice" }, "uri", "tel:+1-555-WORK-123"],
  ["adr", { "group": "work", "type": "work" }, "text", [...]]
]
*/

```

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

### Handle InvalidArgument Errors in vcard4

Source: https://context7.com/kelseykm/vcard4/llms.txt

Illustrates catching `InvalidArgument` errors, which are raised when provided arguments have values outside the acceptable range or format.

```javascript
// InvalidArgument - when arguments have invalid values
try {
  // PrefParameter must be 1-100
  new PrefParameter(new IntegerType(150));
} catch (error) {
  if (error instanceof InvalidArgument) {
    console.log('Invalid argument:', error.message);
    // "Value for PrefParameter must be between 1 and 100"
  }
}
```

```javascript
// Cardinality validation - UIDProperty can only appear once
try {
  new VCARD([
    new FNProperty([], new TextType('John Doe')),
    new UIDProperty([], new TextType('uid-1')),
    new UIDProperty([], new TextType('uid-2')) // Duplicate!
  ]);
} catch (error) {
  if (error instanceof InvalidArgument) {
    console.log('Cardinality error:', error.message);
  }
}
```

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