How should I detect ParsedGroup? about email-addresses HOT 5 CLOSED

I ran into a similar issue - I opened PR #45 that allows you to safely use the type as a discriminant:

const addr = parseOneAddress(value);
if (addr && addr.type == "mailbox") {
  return addr.address;
}

from email-addresses.

I merged sciyoshi's PR.

from email-addresses.

Looks to me like the types for parseOneAddress are incorrect as it only ever returns a ParsedMailbox (single address) or null (for invalid addresses & which is not included in the types).

The types should instead be:

function parseOneAddress(input: string | Options): ParsedMailbox | null;

I guess the other functions may need an update to also potentially return null.

Correct me if I've missed some case where parseOneAddress returns more than one address.

Here's what I ran to check the output: https://gist.github.com/JakeSidSmith/7682c55c902867e60854be036e860547

from email-addresses.

Hey, thanks for the issue.

First off, I'm not using the typescript definitions myself, so I'm happy to take suggestions and PRs on how to make them better.

Second, let me explain what a "ParsedMailbox" and a "ParsedGroup" are. These terms I am pulling from the RFCs' productions on which email-addresses is based. parseOneAddress is a helper that tries to parse an address-list, but expects a list of size one, and returns that. An address-list is made up of addresses which can be either a mailbox or a group. The problem here is that you could have an address-list that has one address in it, which is a group, which could be made of multiple mailboxes! Technically parseOneAddress is giving you one address, but this isn't intuitively the thing you expect. See my example below.

I think the easiest thing to do here (please tell me if this is what you want) is to change the type of these functions so that they can all possibly return null.

But maybe we should also add a parseOneMailbox function, which is what people probably want most of the time.

Here's some examples to show you what I'm talking about:

> addrs('My fun group: [email protected];')
{ ast: 
   { name: 'address-list',
     tokens: 'My fun group: [email protected];',
     semantic: 'My fun group:[email protected];',
     children: [ [Object] ] },
  addresses: 
   [ { node: [Object],
       parts: [Object],
       type: 'group',
       name: 'My fun group',
       addresses: [Array] } ] }
> addrs.parseOneAddress('My fun group: [email protected];')
{ parts: 
   { name: 
      { name: 'display-name',
        tokens: 'My fun group',
        semantic: 'My fun group',
        children: [Array] } },
  type: 'group',
  name: 'My fun group',
  addresses: 
   [ { node: [Object],
       parts: [Object],
       type: 'mailbox',
       name: null,
       address: '[email protected]',
       local: 'foo',
       domain: 'example.com',
       groupName: null } ] }
> addrs.parseOneAddress('[email protected]')
{ parts: 
   { name: null,
     address: 
      { name: 'addr-spec',
        tokens: '[email protected]',
        semantic: '[email protected]',
        children: [Array] },
     local: 
      { name: 'local-part',
        tokens: 'foo',
        semantic: 'foo',
        children: [Array] },
     domain: 
      { name: 'domain',
        tokens: 'example.com',
        semantic: 'example.com',
        children: [Array] },
     comments: [] },
  type: 'mailbox',
  name: null,
  address: '[email protected]',
  local: 'foo',
  domain: 'example.com',
  groupName: null }

from email-addresses.

If I didn't make it clear, a ParsedGroup is not just a list of ParsedMailboxes; it's a separate thing conceptually, because it has a name. It looks like This is the name of the group: [email protected], [email protected];.

from email-addresses.