frontacles 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+Nothing for now.
+
+<!-- ⚠️ Before a new release, make sure the documentation doesn't contain any **unreleased** mention.  -->
+
+Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.0...main).
+
+## v0.2.1 (2025-02-28)
+
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.2.0...0.2.1).
+
+### Improved
+
+- `Email` is now a couple of bytes lighter.
+
+## v0.2.0 (2025-02-28)
+
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/dda10c3...0.2.0).
+
+### New
+
+- Add [`Email`](https://github.com/frontacles/frontacles#email), a class to validate emails the same way browsers do, which is rock solid.
+
+## v0.1.1 (2021-03-13)
+
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/986c759...dda10c3).
+
+First published version.
+
+## v0.1.0 (2021-03-13)
+
+Almost published version.

package/README.md

@@ -1 +1,79 @@
-Documentation in progress
+# Frontacles
+
+Cool utilities for front-end development (and potentially for Node).
+
+> [!WARNING]  
+> Under heavy development. We are only starting!
+
+## Email
+
+A class to instantiate an `Email` object or validate emails. It’s only [222 B compressed](https://bundlejs.com/?q=frontacles&treeshake=[{Email}]&config={%22compression%22%3A%22brotli%22}&bundle).
+
+Unlike most libraries using [RegEx for emails](https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/src/types.ts#L648-L663) (and prone to [bugs](https://github.com/colinhacks/zod/issues/3913)), Frontacles `Email` class relies on the same mechanism as your browser to validate email addresses, making it robust, and very likely RFC compliant.
+
+```js
+import { Email } from 'frontacles/url/email'
+
+const email = new Email('someone@domain.tld')
+```
+
+Get the username and the hostname separately.
+
+```js
+email.username // 'someone'
+email.hostname // 'domain.tld'
+```
+
+Turn the email object into a string by using it along another string, or use `toString`.
+
+```js
+console.log(`email: ${email}`) // 'email: someone@domain.tld'
+console.log(email.toString()) // 'someone@domain.tld'
+```
+
+Validate that a string is a valid email address. It passes the complete Zod test suites, and beyond.
+
+```js
+Email.canParse('someone@domain.tld') // true
+Email.canParse('invalid@email.com:3000') // false
+```
+
+Trying to instantiate an Email with an invalid address will throw. This behaviour is similar to the [`URL` constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL), since `Email` relies on it under the hood.
+
+```js
+new Email('double@at@sign.com') // ❌ throw TypeError
+```
+
+Another behaviour from the `URL` class: you can pass an `Email` object to the `Email` constructor or to `Email.canParse`.
+
+```js
+const email = new Email('someone@domain.tld')
+
+const alsoEmail = new Email(email) // ✅ a new Email object!
+
+Email.canParse(email) // ✅ true
+```
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/frontacles/frontacles/blob/main/CHANGELOG.md) or the [releases](https://github.com/frontacles/frontacles/releases).
+
+## Browser and tooling support
+
+`frontacles` is provided [as module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#browser_compatibility) for [modern browsers usage](https://github.com/frontacles/frontacles/blob/main/browserslist) with standard JavaScript syntax:
+- it is up to you to transpile it for legacy browsers;
+- you can’t import it using `require('frontacles')`.
+
+[Read more about ESModules](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+
+## Security
+
+See the [security policy](https://github.com/frontacles/frontacles/blob/main/SECURITY.md).
+
+## Contributing
+
+See the [contributing guidelines](https://github.com/frontacles/frontacles/blob/main/CONTRIBUTING.md).
+
+## License
+
+The _datetime-attribute_ package is open-sourced software licensed under the [DWTFYWTPL](https://github.com/frontacles/frontacles/blob/main/LICENSE).

package/package.json

@@ -1,41 +1,68 @@
 {
   "name": "frontacles",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Front-end utilities for artisans",
   "type": "module",
-  "exports": "./src",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./types/index.d.ts"
+    }
+  },
+  "types": "./types/index.d.ts",
   "engines": {
-    "node": ">=12.8"
+    "node": ">=20.18.1"
   },
   "scripts": {
-    "test": "jest",
-    "test:coverage": "c8 --all --include=src npm test",
-    "watch": "jest --watch"
+    "types": "tsc && dts-bundle-generator --silent --no-banner=true -o types/index.d.ts types-transitive/index.d.ts",
+    "test": "vitest run",
+    "test:types": "npm exec tsd",
+    "test:ui": "vitest --ui --coverage.enabled --coverage.exclude=types",
+    "coverage": "vitest run --coverage --coverage.exclude=types",
+    "watch": "vitest watch",
+    "build": "echo \"Nothing to build, this command is only here to please size-limit GitHub action\" && exit 0",
+    "size": "size-limit",
+    "lint": "eslint",
+    "lint-fix": "eslint --fix"
   },
   "files": [
-    "src/"
+    "CHANGELOG.md",
+    "src/**/*.js",
+    "!src/**/*.test.js",
+    "types/index.d.ts"
   ],
   "keywords": [
     "utilities",
-    "datetime",
-    "attribute"
+    "email",
+    "math",
+    "round"
   ],
   "homepage": "https://github.com/frontacles/frontacles",
   "author": "Mehdi Merah",
   "license": "WTFPL",
-  "repository": "https://github.com/frontacles/frontacles.git",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frontacles/frontacles.git"
+  },
   "bugs": {
     "url": "https://github.com/frontacles/frontacles/issues"
   },
   "publishConfig": {
-    "access": "public",
-    "cache": "~/.npm"
+    "access": "public"
   },
   "devDependencies": {
-    "@babel/core": "^7.13.8",
-    "@babel/preset-env": "^7.13.9",
-    "babel-jest": "^26.6.3",
-    "c8": "^7.6.0",
-    "jest": "^26.6.3"
+    "@eslint/js": "^9.9.0",
+    "@size-limit/preset-small-lib": "^11.1.4",
+    "@vitest/coverage-v8": "^3",
+    "@vitest/eslint-plugin": "^1.0.1",
+    "@vitest/ui": "^3",
+    "dts-bundle-generator": "^9.5.1",
+    "eslint": "^9.9.0",
+    "size-limit": "^11.1.4",
+    "tsd": "^0.31.1",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.0.1",
+    "vitest": "^3"
   }
 }

package/src/index.js

@@ -1 +1,2 @@
 export * from './math/index.js'
+export * from './url/email.js'

package/src/math/index.js

@@ -1,11 +1,14 @@
 /**
- * Round a number to provided precision.
+ * Round a number to the (optionnally) provided precision.
  *
  * Examples:
  * - round(687.3456, 2)   // 687.35
  * - round(687.3456, 0)   // 687
  * - round(687.3456)      // 687
  * - round(687.3456, -1)  // 690
+ *
+ * @param {number} number
+ * @param {number} [precision=0] Rounding precision
  */
 export const round = (number, precision = 0) => {
   precision = 10 ** precision

package/src/url/email.js

@@ -0,0 +1,69 @@
+// eslint-disable-next-line no-undef
+export class Email extends URL {
+
+  /**
+   *
+   * @param {string|Email} address An email address like `someone@domain.tld`.
+   */
+  constructor(address) {
+    super(`ftp://${address}`)
+
+    if (!this.#validate(address)) {
+      throw new TypeError(`Email constructor: ${address} is not a valid Email.`)
+    }
+  }
+
+  /**
+   * The domain name and extension of the email.
+   *
+   * In `username@domain.tld`, it is `domain.tld`.
+   */
+  get hostname() {
+    return super.hostname
+  }
+
+  /**
+   * The username of the email.
+   *
+   * In `username@domain.tld`, it is `username`.
+   */
+  get username() {
+    return super.username
+  }
+
+  toJSON () {
+    return this.toString()
+  }
+
+  /**
+   * Replace the string representation of the top-level class (`URL`) to be an
+   * email address instead of `ftp://username@domain.tld`. It is needed for
+   * situation where type casting to string is involved (`console.log`…).
+   */
+  toString () {
+    return `${this.username}@${this.hostname}`
+  }
+
+  /**
+   * Recompose the email address and compare it to the input.
+   *
+   * @param {string} address
+   */
+  #validate (address) {
+    return this.toString() == address
+  }
+
+  /**
+   * Whether or not an email address is parsable and valid.
+   *
+   * @param {any|Email} address
+   */
+  static canParse(address) {
+    try {
+      new this(address)
+      return true
+    } catch {
+      return false
+    }
+  }
+}

package/src/url/test-utils/zod-suite.js

@@ -0,0 +1,117 @@
+/* eslint-disable no-useless-escape */
+// https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/src/types.ts#L648-L663
+// https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/deno/lib/__tests__/string.test.ts#L42-L154
+
+export const validEmailsFromZod = [
+  `email@domain.com`,
+  `firstname.lastname@domain.com`,
+  `email@subdomain.domain.com`,
+  `firstname+lastname@domain.com`,
+  `1234567890@domain.com`,
+  `email@domain-one.com`,
+  `_______@domain.com`,
+  `email@domain.name`,
+  `email@domain.co.jp`,
+  `firstname-lastname@domain.com`,
+  `very.common@example.com`,
+  `disposable.style.email.with+symbol@example.com`,
+  `other.email-with-hyphen@example.com`,
+  `fully-qualified-domain@example.com`,
+  `user.name+tag+sorting@example.com`,
+  `x@example.com`,
+  `mojojojo@asdf.example.com`,
+  `example-indeed@strange-example.com`,
+  `example@s.example`,
+  `user-@example.org`,
+  `user@my-example.com`,
+  `a@b.cd`,
+  `work+user@mail.com`,
+  `tom@test.te-st.com`,
+  `something@subdomain.domain-with-hyphens.tld`,
+  `common'name@domain.com`,
+  `francois@etu.inp-n7.fr`,
+]
+
+export const invalidEmailsFromZod = [
+  // no "printable characters"
+  // `user%example.com@example.org`,
+  // `mailhost!username@example.org`,
+  // `test/test@test.com`,
+
+  // double @
+  `francois@@etu.inp-n7.fr`,
+  // do not support quotes
+  `"email"@domain.com`,
+  `"e asdf sadf ?<>ail"@domain.com`,
+  `" "@example.org`,
+  `"john..doe"@example.org`,
+  `"very.(),:;<>[]\".VERY.\"very@\\ \"very\".unusual"@strange.example.com`,
+  // do not support comma
+  `a,b@domain.com`,
+
+  // do not support IPv4
+  `email@123.123.123.123`,
+  `email@[123.123.123.123]`,
+  `postmaster@123.123.123.123`,
+  `user@[68.185.127.196]`,
+  `ipv4@[85.129.96.247]`,
+  `valid@[79.208.229.53]`,
+  `valid@[255.255.255.255]`,
+  `valid@[255.0.55.2]`,
+  `valid@[255.0.55.2]`,
+
+  // do not support ipv6
+  `hgrebert0@[IPv6:4dc8:ac7:ce79:8878:1290:6098:5c50:1f25]`,
+  `bshapiro4@[IPv6:3669:c709:e981:4884:59a3:75d1:166b:9ae]`,
+  `jsmith@[IPv6:2001:db8::1]`,
+  `postmaster@[IPv6:2001:0db8:85a3:0000:0000:8a2e:0370:7334]`,
+  `postmaster@[IPv6:2001:0db8:85a3:0000:0000:8a2e:0370:192.168.1.1]`,
+
+  // microsoft test cases
+  `plainaddress`,
+  `#@%^%#$@#$@#.com`,
+  `@domain.com`,
+  `Joe Smith &lt;email@domain.com&gt;`,
+  `email.domain.com`,
+  `email@domain@domain.com`,
+  `.email@domain.com`,
+  `email.@domain.com`,
+  `email..email@domain.com`,
+  `あいうえお@domain.com`,
+  `email@domain.com (Joe Smith)`,
+  `email@domain`,
+  `email@-domain.com`,
+  `email@111.222.333.44444`,
+  `email@domain..com`,
+  `Abc.example.com`,
+  `A@b@c@example.com`,
+  `colin..hacks@domain.com`,
+  `a"b(c)d,e:f;g<h>i[j\k]l@example.com`,
+  `just"not"right@example.com`,
+  `this is"not\allowed@example.com`,
+  `this\ still\"not\\allowed@example.com`,
+
+  // random
+  `i_like_underscore@but_its_not_allowed_in_this_part.example.com`,
+  `QA[icon]CHOCOLATE[icon]@test.com`,
+  `invalid@-start.com`,
+  `invalid@end.com-`,
+  `a.b@c.d`,
+  `invalid@[1.1.1.-1]`,
+  `invalid@[68.185.127.196.55]`,
+  `temp@[192.168.1]`,
+  `temp@[9.18.122.]`,
+  `double..point@test.com`,
+  `asdad@test..com`,
+  `asdad@hghg...sd...au`,
+  `asdad@hghg........au`,
+  `invalid@[256.2.2.48]`,
+  `invalid@[256.2.2.48]`,
+  `invalid@[999.465.265.1]`,
+  `jkibbey4@[IPv6:82c4:19a8::70a9:2aac:557::ea69:d985:28d]`,
+  `mlivesay3@[9952:143f:b4df:2179:49a1:5e82:b92e:6b6]`,
+  `gbacher0@[IPv6:bc37:4d3f:5048:2e26:37cc:248e:df8e:2f7f:af]`,
+  `invalid@[IPv6:5348:4ed3:5d38:67fb:e9b:acd2:c13:192.168.256.1]`,
+  `test@.com`,
+  `aaaaaaaaaaaaaaalongemailthatcausesregexDoSvulnerability@test.c`,
+]

package/types/index.d.ts

@@ -0,0 +1,29 @@
+export function round(number: number, precision?: number): number;
+export class Email extends URL {
+	/**
+	 * Whether or not an email address is parsable and valid.
+	 *
+	 * @param {any|Email} address
+	 */
+	static canParse(address: any | Email): boolean;
+	/**
+	 *
+	 * @param {string|Email} address An email address like `someone@domain.tld`.
+	 */
+	constructor(address: string | Email);
+	/**
+	 * The domain name and extension of the email.
+	 *
+	 * In `username@domain.tld`, it is `domain.tld`.
+	 */
+	get hostname(): string;
+	/**
+	 * The username of the email.
+	 *
+	 * In `username@domain.tld`, it is `username`.
+	 */
+	get username(): string;
+	#private;
+}
+
+export {};