frontacles 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -8,11 +8,29 @@ 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.3...main).
+<!-- Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.4.0...main). -->
+
+## v0.4.0 (2025-03-08)
+
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.3.0...0.4.0).
+
+### New
+
+- Add [`isEmail`](./README.md#isemail) to validate emails.
+
+### Documentation
+
+- It is now more explicit in types that `Email.canParse` expects a `string` or a `Stringable` (changed from `any|Email` to `any|string|Email|Stringable`).
+- Rephrase email documentation.
+
+### Under the hood
+
+- Centralize all benchmarks in [`./benchs`](./benchs).
+- Benchmark [`Email`](./benchs/url).
 
 ## v0.3.0 (2025-03-06)
 
-Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.2...0.2.3).
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.2.2...0.3.0).
 
 ### New
 
@@ -32,7 +50,7 @@ Compare with [last published version](https://github.com/frontacles/frontacles/c
 ### Under the hood
 
 - Shorten `round` by a couple of Bytes.
-- Benchmark [`round` implementations](./src/math/bench)
+- Benchmark [`round` implementations](./benchs/math)
 - Add [Valibot test suite](./src/url/test-utils/valibot-suite.js) to `Email` (all tests are passing!).
 
 ### Documentation
@@ -43,7 +61,7 @@ Compare with [last published version](https://github.com/frontacles/frontacles/c
 
 ## v0.2.2 (2025-03-01)
 
-Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.1...0.2.2).
+Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.2.1...0.2.2).
 
 ### Breaking
 

package/README.md

@@ -12,8 +12,9 @@ We love tiny bits (using brotli compression):
 | math | [`clamp`](#clamp) | 35 B |
 | math | [`round`](#round) | 38 B |
 | string | [`capitalize`](#capitalize) | 40 B |
+| url | [`isEmail`](#isemail) | 86 B |
 | url | [`Email`](#email) | 173 B |
-|  | **everything** | 252 B |
+|  | **everything** | 328 B |
 
 ## Math utils
 
@@ -46,10 +47,9 @@ clamp(Infinity, 0, 10) // 10
 > [!NOTE]  
 > `clamp` mostly follows [`Math.clamp` TC39 proposal](https://github.com/tc39/proposal-math-clamp), except it doesn’t throw if you flip the order of the _min_ (2nd parameter) and _max_ (3rd parameter) numbers.
 
-
 ### `round`
 
-Round a number to the (optionally) provided precision.
+Round a number to the (optionally) provided decimal precision. The default precision is 0 (no decimal).
 
 ```js
 import { round } from 'frontacles/math'
@@ -66,7 +66,7 @@ round(687.3456, -1)  // 690
 round(687.3456, -2)  // 700
 ```
 
-Trying to round `Infinity` or to round a number to an _infinite_ precision is also possible:
+Using `Infinity` is also possible:
 
 ```js
 round(Infinity, -2) // Infinity
@@ -97,11 +97,40 @@ capitalize('صحراء') // 'صحراء' (Arabic)
 
 ## URL utils
 
+### `isEmail`
+
+Tells whether a string is a valid email.
+
+```js
+isEmail('someone@domain.tld') // true
+isEmail('invalid@email.com:3000') // false
+```
+
+> [!TIP]  
+> Should I use `isEmail` or [`Email.canParse`](#emailcanparse) to validate emails?
+>
+> Short answer: use `isEmail`.
+>
+> <details>
+> <summary>Nuanced answer</summary>
+>
+> Your use case:
+>
+> - If you **only need to validate** email addresses, use `isEmail`.
+> - If you also need to be able to get or set an email username or hostname **independently**, use `Email.canParse`.
+>
+> When using the `Email` class, you can still use `isEmail` if you want ultra-performance (e.g. your Node API validates tons of emails per seconds) because `isEmail` is 6✕ faster, at the cost of a bit less than 100 Bytes (compressed).
+>
+> The reason `isEmail` is faster is that it relies on a single RegExp while `Email.canParse` uses the browser built-in, which results in a bit more of computation, but with less code. For now, it’s not planned to use `isEmail` implementation in `Email.canParse` as it would increase its size by 50 Bytes.
+>
+> Keep in mind that **`Email.canParse` is fast enough** for the 99% use cases. Despite their implementation difference, both behave the same and pass the same tests.
+> </details>
+
 ### `Email`
 
-A class to instantiate an `Email` object or validate email addresses.
+A class to instantiate an `Email` object or validate email addresses. It extends the [`URL` object](https://developer.mozilla.org/en-US/docs/Web/API/URL) and has similar predictable behaviors.
 
-Unlike most libraries using [RegEx to validate a string is an email](https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/src/types.ts#L648-L663) (which is prone to [bugs](https://github.com/colinhacks/zod/issues/3913)), Frontacles `Email` relies on the same mechanism as your browser, making it robust, and very likely RFC compliant.
+#### `Email.constructor`
 
 ```js
 import { Email } from 'frontacles/url/email'
@@ -109,7 +138,23 @@ import { Email } from 'frontacles/url/email'
 const email = new Email('someone@domain.tld')
 ```
 
-Get or set the username and the hostname separately.
+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 `URL`: passing an `Email` object to the `Email` constructor or to [`Email.canParse`](#emailcanparse) is possible.
+
+```js
+const email = new Email('someone@domain.tld')
+const alsoEmail = new Email(email) // ✅ a new Email object!
+Email.canParse(email) // ✅ true
+```
+
+#### `.username` and `.hostname`
+
+Get or set the email username and hostname separately.
 
 ```js
 email.username // 'someone'
@@ -121,35 +166,27 @@ email.hostname = 'newdomain.tld' // ✅ domain migrated
 const { username, hostname } = new Email('someone@domain.tld')
 ```
 
-An `Email` object is converted to a string when used along another string, or by directly calling `toString`.
+#### `.toString`
+
+In a string context, an `Email` object is automatically converted to a string, or manually by calling the `toString` method.
 
 ```js
 console.log(`email: ${email}`) // 'email: someone@newdomain.tld'
 console.log(email.toString()) // 'someone@newdomain.tld'
 ```
 
-Validate an email address with `Email.canParse`. It passes the complete Zod test suites, and beyond.
+#### `Email.canParse`
 
-```js
-Email.canParse('someone@domain.tld') // true
-Email.canParse('invalid@email.com:3000') // false
-```
+Validate an email address with `Email.canParse`.
 
-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.
+Unlike most libraries using [RegExp to validate a string is an email](https://github.com/colinhacks/zod/blob/e2b9a5f9ac67d13ada61cd8e4b1385eb850c7592/src/types.ts#L648-L663) (which is prone to [bugs](https://github.com/colinhacks/zod/issues/3913)), Frontacles `Email` relies on the built-in `URL` mechanisms, making it robust, and very likely RFC compliant. It passes [popular libraries test suites](./src/url/test-utils), and beyond.
 
 ```js
-new Email('double@at@sign.com') // ❌ throw TypeError
+Email.canParse('someone@domain.tld') // true
+Email.canParse('invalid@email.com:3000') // false
 ```
 
-Another behaviour from the `URL` class: you can pass an `Email` object to the `Email` constructor (or to `Email.canParse`, but it doesn’t really make sense).
-
-```js
-const email = new Email('someone@domain.tld')
-
-const alsoEmail = new Email(email) // ✅ a new Email object!
-
-Email.canParse(email) // ✅ true
-```
+If `canParse` is all you need from the `Email` class, consider using [isEmail](#isemail) instead.
 
 ## Changelog
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontacles",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Front-end utilities for artisans",
   "type": "module",
   "sideEffects": false,
@@ -21,17 +21,16 @@
     "test:types": "npm exec tsd",
     "test:ui": "vitest --ui --coverage.enabled --coverage.exclude=types",
     "coverage": "vitest run --coverage --coverage.exclude=types",
-    "bench": "vitest bench",
     "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"
+    "lint:fix": "eslint --fix",
+    "lint:inspect": "eslint --inspect-config "
   },
   "files": [
     "CHANGELOG.md",
     "src/**/*.js",
-    "!src/**/bench",
     "!src/**/test-utils",
     "!src/**/*.test.js",
     "types/index.d.ts"

package/src/url/email.js

@@ -17,6 +17,9 @@ export class Email extends URL {
   }
 
   /**
+   * The email address (`username@domain.tld`) as a string.
+   *
+   * (maintainer comment)
    * 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`…).
@@ -38,7 +41,7 @@ export class Email extends URL {
   /**
    * Whether or not an email address is parsable and valid.
    *
-   * @param {any|Email} address
+   * @param {any|string|Email|Stringable} address
    */
   static canParse(address) {
     try {
@@ -49,3 +52,17 @@ export class Email extends URL {
     }
   }
 }
+
+/**
+ * Whether or not an email address is parsable and valid.
+ *
+ * It uses WHATWG recommended RegExp: https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
+ *
+ * @param {any|string|Stringable} address
+ */
+export const isEmail = address => /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/.test(address)
+
+/**
+ * @typedef {Object} Stringable
+ * @property {function(): string} toString - The object as a string.
+ */

package/types/index.d.ts

@@ -17,14 +17,21 @@ export class Email extends URL {
 	/**
 	 * Whether or not an email address is parsable and valid.
 	 *
-	 * @param {any|Email} address
+	 * @param {any|string|Email|Stringable} address
 	 */
-	static canParse(address: any | Email): boolean;
+	static canParse(address: any | string | Email | Stringable): boolean;
 	/**
 	 * @param {string|Email} address An email address like `someone@domain.tld`.
 	 */
 	constructor(address: string | Email);
 	#private;
 }
+export function isEmail(address: any | string | Stringable): boolean;
+export type Stringable = {
+	/**
+	 * - The object as a string.
+	 */
+	toString: () => string;
+};
 
 export {};