Update with better support for quoted strings in the local portion of a mailbox address (#1)

Author: asimpletune

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 generated
-dist
+dist
+.vscode

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Next
 
+## 0.0.2 (2025-11-20)
+
+- Improve support for quoted strings in the local portion of an email
+- Export the `mailbox` function by default
+- Return a discriminated union instead of a success object or array of error strings
+- Automate generating the example code used in the README
+- Add explicit license
+
 ## 0.0.1 (2025-09-23)
 
 - Document how it's used and why there won't be many updates

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spencer Van Wessem Scorcelletti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -11,75 +11,159 @@ Also:
 
 ⚠️ THIS LIBRARY IS NOT ABANDONED ⚠️
 
-While there are few commits and not much activity, sometimes things are just done and work.
+At some point in the future it may seem like this project is abandoned, but it's not. While there _may_ be few commits or not much activity, the code from this project is almost entirely derived from the email [rfc](https://www.rfc-editor.org/rfc/rfc5322#section-3.4) spec, and it therefore benefits from all the very mature work that has gone into those efforts.
 
 Examples:
 
 ```ts
-import { mailbox } from './src'
-
-/**
- * {  local: 'bob', domain: 'example.com' }
- */
-mailbox('bob@example.com')
-
-/**
- * {  name: undefined, local: 'bob', domain: 'example.com', addr: 'bob@example.com'  }
- */
-mailbox('<bob@example.com>')
-
-/**
-   {
-      name: 'Bruce Springsteen',
-      local: 'bruce',
-      domain: 'springsteen.com',
-      addr: 'bruce@springsteen.com'
-   }
- */
-mailbox('Bruce Springsteen <bruce@springsteen.com>')
-
-
-/**
-   {
-      name: 'Bruce "The Boss" Springsteen',
-      local: 'bruce',
-      domain: 'springsteen.com',
-      addr: 'bruce@springsteen.com'
-   }
- */
-mailbox('Bruce "The Boss" Springsteen <bruce@springsteen.com>')
+import mailbox from 'typescript-mailbox-parser'
+
+// {
+//   "ok": true,
+//   "local": "bob",
+//   "domain": "example.com",
+//   "addr": "bob@example.com"
+// }
+console.log(mailbox('<bob@example.com>'))
+
+// {
+//   "ok": true,
+//   "name": "Bob Hope",
+//   "local": "bob",
+//   "domain": "example.com",
+//   "addr": "bob@example.com"
+// }
+console.log(mailbox('Bob Hope <bob@example.com>'))
+
+// {
+//   "ok": true,
+//   "name": "Bob Hope",
+//   "local": "bob",
+//   "domain": "example.com",
+//   "addr": "bob@example.com"
+// }
+console.log(mailbox('"Bob Hope" <bob@example.com>'))
+
+// {
+//   "ok": true,
+//   "name": "Bruce \"The Boss\" Springsteen",
+//   "local": "bruce",
+//   "domain": "example.com",
+//   "addr": "bruce@example.com"
+// }
+console.log(mailbox('Bruce "The Boss" Springsteen <bruce@example.com>'))
+
+// {
+//   "ok": true,
+//   "local": "bob",
+//   "domain": "example",
+//   "addr": "bob@example"
+// }
+console.log(mailbox('bob@example'))
+
+// {
+//   "ok": true,
+//   "local": "BOB",
+//   "domain": "example",
+//   "addr": "BOB@example"
+// }
+console.log(mailbox('BOB@example'))
+
+// {
+//   "ok": true,
+//   "local": "bob",
+//   "domain": "EXAMPLE",
+//   "addr": "bob@EXAMPLE"
+// }
+console.log(mailbox('bob@EXAMPLE'))
+
+// {
+//   "ok": true,
+//   "local": "a.b.c",
+//   "domain": "d.e.f.g",
+//   "addr": "a.b.c@d.e.f.g"
+// }
+console.log(mailbox('a.b.c@d.e.f.g'))
+
+// {
+//   "ok": true,
+//   "local": "\"site.local.test:1111\"",
+//   "domain": "example.com",
+//   "addr": "\"site.local.test:1111\"@example.com"
+// }
+console.log(mailbox('"site.local.test:1111"@example.com'))
+
+// {
+//   "ok": true,
+//   "local": "\"hello, world\"",
+//   "domain": "example.com",
+//   "addr": "\"hello, world\"@example.com"
+// }
+console.log(mailbox('"hello, world"@example.com'))
+
+// {
+//   "ok": false,
+//   "errors": [
+//     "{\"pos\":{\"overallPos\":11,\"line\":1,\"offset\":11},\"expmatches\":[{\"kind\":\"RegexMatch\",\"literal\":\"[A-Za-z0-9!#$%&\\\\x27\\\\*\\\\+\\\\-\\\\/=?^_\\\\`{|}~]\",\"negated\":false},{\"kind\":\"RegexMatch\",\"literal\":\"\\\\x20\",\"negated\":false},{\"kind\":\"RegexMatch\",\"literal\":\"\\\\x09\",\"negated\":false},{\"kind\":\"RegexMatch\",\"literal\":\"\\\\r\\\\n\",\"negated\":false},{\"kind\":\"RegexMatch\",\"literal\":\"\\\\(\",\"negated\":false},{\"kind\":\"RegexMatch\",\"literal\":\"\\\\x22\",\"negated\":false},{\"kind\":\"RegexMatch\",\"literal\":\"<\",\"negated\":false}]}"
+//   ]
+// }
+console.log(mailbox('foo bar baz'))
 ```
 
 ## Installation and Usage
 
 To install `npm install typescript-mailbox-parser`
 
-Then to use it you just need to import it and call the `mailbox` function on a string. If successful it will return an object representing the parts of the email address (mailbox).
+Then to use it you just need to import it and call the `mailbox` function on a string.
 
 ```ts
-import { mailbox } from 'typescript-mailbox-parser'
+import mailbox from 'typescript-mailbox-parser'
 
 const email = mailbox('hello@example.com')
 ```
 
-If the string supplied is not a valid email address (mailbox), then it will return an array of error strings.
+It returns the following type
 
 ```ts
-import { mailbox } from 'typescript-mailbox-parser'
+type MailboxParseResult =
+  | { ok: false; errors: string[] }
+  | { ok: true; addr: string; name?: string; local: string; domain: string }
+```
+
+In other words, if successful it will return an object representing the parts of the email address (mailbox):
+
+```ts
+import mailbox from 'typescript-mailbox-parser'
+
+// {
+//   ok: true,
+//   name: 'Bruce "The Boss" Springsteen',
+//   local: 'bruce',
+//   domain: 'example.com',
+//   addr: 'bruce@example.com'
+// }
+console.log(mailbox('Bruce "The Boss" Springsteen <bruce@example.com>'))
+```
+
+If unsuccessful it will return an object with an `errors` field containing an array of error messages as strings:
 
-/**
-  [
-    '{"pos":{"overallPos":11,"line":1,"offset":11},"expmatches":[{"kind":"RegexMatch","literal":"[A-Za-z0-9!#$%&\\\\x27\\\\*\\\\+\\\\-\\\\/=?^_\\\\`{|}~]","negated":false},{"kind":"RegexMatch","literal":"\\\\x20","negated":false},{"kind":"RegexMatch","literal":"\\\\x09","negated":false},{"kind":"RegexMatch","literal":"\\\\r\\\\n","negated":false},{"kind":"RegexMatch","literal":"\\\\(","negated":false},{"kind":"RegexMatch","literal":"\\\\x22","negated":false},{"kind":"RegexMatch","literal":"<","negated":false}]}'
-  ]
- */
+```ts
+import mailbox from 'typescript-mailbox-parser'
+
+// {
+//   ok: false,
+//   errors: [
+//     '{"pos":{"overallPos":11,"line":1,"offset":11},"expmatches":[{"kind":"RegexMatch","literal":"[A-Za-z0-9!#$%&\\\\x27\\\\*\\\\+\\\\-\\\\/=?^_\\\\`{|}~]","negated":false},{"kind":"RegexMatch","literal":"\\\\x20","negated":false},{"kind":"RegexMatch","literal":"\\\\x09","negated":false},{"kind":"RegexMatch","literal":"\\\\r\\\\n","negated":false},{"kind":"RegexMatch","literal":"\\\\(","negated":false},{"kind":"RegexMatch","literal":"\\\\x22","negated":false},{"kind":"RegexMatch","literal":"<","negated":false}]}'
+//   ]
+// }
 const email = mailbox('foo bar baz')
 ```
 
 For development
 
 ```sh
 # run tests
-npm run test
+npm test
 
 # build the parser from the grammar
 npm run build:parser
@@ -90,10 +174,13 @@ npm run build:compile
 # combine build:parser and build:compile
 npm run build:all
 
+# generate the examples used in the README
+npm run docs:examples
+
 # run formatter
 npm run fmt
 ```
 
 ## Notes
 
-This _should_ in theory work with 100% accuracy, as the logic is based off the [rfc5322](https://www.rfc-editor.org/rfc/rfc5322) specification... however mistakes can always be made. Please file an issue if there are any bugs.
+This _should_ in theory work with 100% accuracy, as the logic is based off the [rfc5322](https://www.rfc-editor.org/rfc/rfc5322) specification. Please file an issue if there are any bugs.

example.ts

@@ -0,0 +1,31 @@
+import mailbox from './dist'
+import vm from 'node:vm'
+
+const sandbox = { mailbox, console }
+vm.createContext(sandbox)
+
+const examples = [
+  `mailbox('<bob@example.com>')`,
+  `mailbox('Bob Hope <bob@example.com>')`,
+  `mailbox('"Bob Hope" <bob@example.com>')`,
+  `mailbox('Bruce "The Boss" Springsteen <bruce@example.com>')`,
+  `mailbox('bob@example')`,
+  `mailbox('BOB@example')`,
+  `mailbox('bob@EXAMPLE')`,
+  `mailbox('a.b.c@d.e.f.g')`,
+  `mailbox('"site.local.test:1111"@example.com')`,
+  `mailbox('"hello, world"@example.com')`,
+  `mailbox('foo bar baz')`,
+]
+
+for (const e of examples) {
+  const result = vm.runInContext(e, sandbox)
+  // Print the result as a commented block
+  const commented = JSON.stringify(result, null, 2)
+    .split('\n')
+    .map((line) => `// ${line}`)
+    .join('\n')
+
+  console.log(commented)
+  console.log(`console.log(${e})\n`)
+}