README about API is outdated/incomplete

RFC6868 describes parameter value escaping:

• ^n to \n
• ^^ to ^
• ^' to "
• Everything else remains untouched (no removal of the ^ escaping character!)

Nag on "everything else"?

Two approaches

1. Have an extra groups?: Record<string, PartialVCard>; property on vCards, which includes the grouped properties. Then, user code could decide whether it wants

• Items ungrouped: Just use the pre-existing structure, ignoring group field in properties, or
• Items grouped: Read through groups and then ignore all values which have a group field

2. Have a groupVCard() function, which groups all entries by group name (and those without, into ungrouped) into a Record<string, PartialVCard>

I am currently favoring 2, as groups are rarely used and most consumers will not want to bother about it. This also reduces code size for group-agnostic consumers.

Maybe generate a text/vcard representation out of the structure

RFC6473 defines the additional KIND application.

So that e.g. EMAIL[0] refers to the highest-priority email address.

Is shorter and probably more appropriate.

RFC6715 defines the Open Mobile Alliance Converged Address Book extensions:

Properties

• EXPERTISE, cardinality *, single text value
• HOBBY, cardinality *, single text value
• INTEREST, cardinality *, single text value
• ORG-DIRECTORY, cardinality *, a single URI value

Parameters

• INDEX, strictly positive integer representing UI ordering of the value (may contradict PREF ordering)
• LEVEL, one of beginner, average, expert, high, medium, low

Maybe the additional parser logic is minimal, after having abstracted the type information

RFC8605 defines the following:

Property

• CONTACT-URI, cardinality *, a single URI value

Parameter

• CC (two-letter country code) parameter on ADR

According to the spec, the line TEL;TYPE="work,fax";PREF=1:+45 1234 1234 is a valid result to represent "type parameter values specified as a parameter list (e.g., TYPE=text;TYPE=voice) or as a list (e.g., TYPE="text,voice")".

However, vcard4-ts logs this nag:

{
  "key":"PARAM_UNESCAPED_COMMA",
  "description": "Unescaped comma in parameter value",
  "isError": false,
  "attributes": {
    "property": "TEL",
    "parameter": "TYPE",
    "line": "TEL;TYPE=\"work,fax\";PREF=1:+45 1234 1234"
  }
}

Am I misunderstanding something, or can I safely ignore this nag?

RFC6474 defines the following additional properties:

• BIRTHPLACE, cardinality *1, single text (or URI) value
• DEATHPLACE, cardinality *1, single text (or URI) value
• DEATHDATE, cardinality *1, single date-and-or-time (or text) value

Observation about vCard format: There is no possibility to have multilingual place names or death date descriptions, as this would require * cardinality (which would in turn cause confusions, as most humans are only ever born once and die once). For multilingual representations, something like a CONTENTS[fr]=Schaffhouse parameter would be useful (using CONTENTS, as the more natural VALUE defines the data type of the VALUE).

RFC7852 defines the main-number TYPE to the TEL property.

I'm trying to use this package inside oclif, but I'm hitting this error. Essentially it doesn't support loading es modules. Despite the fact that this module is TypeScript and my code is TypeScript, the modules won't play nice.

I don't fully understand the ins and outs. I guess that you're only publishing an ESM module which is the latest and greatest, and oclif is using some older module loading strategy which won't play nice.

Question, would you be open to publishing a dual build module? For inspiration, I've been able to import tsdav without issue in oclif.