frontacles 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -8,11 +8,60 @@ 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.2...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 [previous version](https://github.com/frontacles/frontacles/compare/0.2.2...0.3.0).
+
+### New
+
+#### Math
+
+- Add [`clamp`](./README.md#clamp), a function to clamp a number in a given range.
+- Add support for `Infinity` precision to the [`round` function](./README.md#round).
+
+#### String
+
+- Add [`capitalize`](./README.md#capitalize), a function to put the first letter of a word in uppercase.
+
+### Fixed
+
+- `Email` was considering as valid an email without username (e.g. `@domain.tld`). This is now fixed.
+
+### Under the hood
+
+- Shorten `round` by a couple of Bytes.
+- Benchmark [`round` implementations](./benchs/math)
+- Add [Valibot test suite](./src/url/test-utils/valibot-suite.js) to `Email` (all tests are passing!).
+
+### Documentation
+
+- Gather sizes in the documentation introduction.
+- Group utils by categories (_Math_, _String_, _URL_)  to the documentation.
+- Add pull request template.
 
 ## 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
 
@@ -40,7 +89,7 @@ Compare with [previous version](https://github.com/frontacles/frontacles/compare
 
 ### New
 
-- Add [`Email`](https://github.com/frontacles/frontacles#email), a class to validate emails the same way browsers do, which is rock solid.
+- Add [`Email`](./README.md#email), a class to validate emails the same way browsers do, which is rock solid.
 
 ## v0.1.1 (2021-03-13)
 

package/README.md

@@ -5,42 +5,137 @@ Cool utilities for front-end development (and potentially for Node).
 > [!WARNING]  
 > Under heavy development. We are only starting!
 
-## Email
+We love tiny bits (using brotli compression):
 
-A class to instantiate an `Email` object or validate emails. It’s only [221 B compressed](https://bundlejs.com/?q=frontacles&treeshake=[{Email}]&config={%22compression%22%3A%22brotli%22}&bundle).
+| categories | util | size |
+| --- | --- | --- |
+| 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** | 328 B |
 
-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.
+## Math utils
+
+### `clamp`
+
+Clamp a number between two values. A clamped number stays within a specified range. If the number is lower than the minimum, the minimum value is returned. If the number is higher than the maximum, the maximum value is returned.
+
+`clamp` needs 3 parameters:
+
+1. `number`: the number to clamp
+2. `min`: the smallest value your number can have
+3. `max`: the highest value your number can have
 
 ```js
-import { Email } from 'frontacles/url/email'
+import { clamp } from 'frontacles/math'
 
-const email = new Email('someone@domain.tld')
+clamp(17, 3, 8) // 8
+clamp(-3, 3, 8) // 3
+clamp(5, 3, 8)  // 5
 ```
 
-Get or set the username and the hostname separately.
+`-0` and `Infinity` are accepted:
 
 ```js
-email.username // 'someone'
-email.hostname // 'domain.tld'
+clamp(-2, -0, 10)      // -0
+clamp(5, 0, Infinity)  // 5
+clamp(Infinity, 0, 10) // 10
+```
 
-email.hostname = 'newdomain.tld' // ✅ domain migrated
+> [!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.
 
-// destructuring also works
-const { username, hostname } = new Email('someone@domain.tld')
+### `round`
+
+Round a number to the (optionally) provided decimal precision. The default precision is 0 (no decimal).
+
+```js
+import { round } from 'frontacles/math'
+
+round(687.3456)      // 687
+round(687.3456, 0)   // 687
+round(687.3456, 2)   // 687.35
 ```
 
-Turn the email object into a string by using it along another string, or use `toString`.
+A negative precision will round up to multiple of tens:
 
 ```js
-console.log(`email: ${email}`) // 'email: someone@newdomain.tld'
-console.log(email.toString()) // 'someone@newdomain.tld'
+round(687.3456, -1)  // 690
+round(687.3456, -2)  // 700
 ```
 
-Validate that a string is a valid email address. It passes the complete Zod test suites, and beyond.
+Using `Infinity` is also possible:
 
 ```js
-Email.canParse('someone@domain.tld') // true
-Email.canParse('invalid@email.com:3000') // false
+round(Infinity, -2) // Infinity
+round(17.853, Infinity // 17.853
+```
+
+## String utils
+
+### `capitalize`
+
+Put the first letter of a word in uppercase. It works for Latin, Greek and Cyrillic alphabets.
+
+```js
+capitalize('jean-roger')) // 'Jean-roger' (Latin)
+capitalize('έρημος')) // 'Έρημος' (Greek)
+capitalize('0 books') // 0 books
+capitalize('صحراء') // 'صحراء' (Arabic)
+```
+
+> [!TIP]
+> Before using `capitalize`, evaluate if [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS/::first-letter) could be used instead.
+>
+> ```css
+> .my-class::first-letter {
+>   text-transform: uppercase;
+> }
+> ```
+
+## 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. It extends the [`URL` object](https://developer.mozilla.org/en-US/docs/Web/API/URL) and has similar predictable behaviors.
+
+#### `Email.constructor`
+
+```js
+import { Email } from 'frontacles/url/email'
+
+const email = new Email('someone@domain.tld')
 ```
 
 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.
@@ -49,23 +144,57 @@ Trying to instantiate an Email with an invalid address will throw. This behaviou
 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`.
+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'
+email.hostname // 'domain.tld'
+
+email.hostname = 'newdomain.tld' // ✅ domain migrated
+
+// destructuring also works
+const { username, hostname } = new Email('someone@domain.tld')
+```
+
+#### `.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'
+```
+
+#### `Email.canParse`
+
+Validate an email address with `Email.canParse`.
+
+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
+Email.canParse('someone@domain.tld') // true
+Email.canParse('invalid@email.com:3000') // false
+```
+
+If `canParse` is all you need from the `Email` class, consider using [isEmail](#isemail) instead.
+
 ## Changelog
 
-See [CHANGELOG.md](https://github.com/frontacles/frontacles/blob/main/CHANGELOG.md) or the [releases](https://github.com/frontacles/frontacles/releases).
+See [CHANGELOG.md](./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:
+`frontacles` is provided [as module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#browser_compatibility) for [modern browsers usage](./browserslist) with standard JavaScript syntax:
 - it is up to you to transpile it for legacy browsers;
 - you can’t import it using `require('frontacles')`.
 
@@ -73,12 +202,12 @@ See [CHANGELOG.md](https://github.com/frontacles/frontacles/blob/main/CHANGELOG.
 
 ## Security
 
-See the [security policy](https://github.com/frontacles/frontacles/blob/main/SECURITY.md).
+See the [security policy](./SECURITY.md).
 
 ## Contributing
 
-See the [contributing guidelines](https://github.com/frontacles/frontacles/blob/main/CONTRIBUTING.md).
+See the [contributing guidelines](./CONTRIBUTING.md).
 
 ## License
 
-The _datetime-attribute_ package is open-sourced software licensed under the [DWTFYWTPL](https://github.com/frontacles/frontacles/blob/main/LICENSE).
+The _datetime-attribute_ package is open-sourced software licensed under the [DWTFYWTPL](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontacles",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Front-end utilities for artisans",
   "type": "module",
   "sideEffects": false,
@@ -25,11 +25,13 @@
     "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/**/test-utils",
     "!src/**/*.test.js",
     "types/index.d.ts"
   ],

package/src/index.js

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

package/src/math/index.js

@@ -1,5 +1,23 @@
 /**
- * Round a number to the (optionnally) provided precision.
+ * Make sure a number stays between boundaries.
+ * Follows {@link https://github.com/tc39/proposal-math-clamp TC39 proposal}.
+ *
+ * Examples:
+ *
+ * ```
+ * clamp(17, 3, 8)  // 8
+ * clamp(-3, 3, 8)  // 3
+ * clamp(5, 3, 8)   // 5
+ * ```
+ *
+ * @param {number} val The number you want to maintain inside boundaries.
+ * @param {number} min The lowest permitted value.
+ * @param {number} max The highest permitted value.
+ */
+export const clamp = (val, min, max) => Math.max(min, Math.min(max, val))
+
+/**
+ * Round a number to the (optionally) provided precision.
  *
  * Examples:
  * - round(687.3456, 2)   // 687.35
@@ -11,6 +29,9 @@
  * @param {number} [precision=0] Rounding precision
  */
 export const round = (number, precision = 0) => {
-  precision = 10 ** precision
-  return Math.round(number * precision) / precision
+
+  // Testing precision avoids a crash because `10 ** Infinity` gives `NaN`.
+  return precision == Infinity
+    ? number
+    : Math.round(number * 10 ** precision) / 10 ** precision
 }

package/src/string/index.js

@@ -0,0 +1,13 @@
+/**
+ * Capitalize the first letter of a string.
+ *
+ * Before using it, evaluate if CSS could be use instead
+ * (`::first-letter { text-transform: uppercase; }`).
+ *
+ * Examples:
+ * - capitalize('jean-roger')  // 'Jean-roger'
+ * - capitalize('0 books')  // '0 books'
+ *
+ * @param {string} str
+*/
+export const capitalize = str => str[0].toUpperCase() + str.slice(1)

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`…).
@@ -31,13 +34,14 @@ export class Email extends URL {
    * @param {string} address
    */
   #validate (address) {
-    return this.toString() == address
+    // `username` is tested because `@domain.tld` is valid in a `ftp` context
+    return this.toString() == address && this.username
   }
 
   /**
    * Whether or not an email address is parsable and valid.
    *
-   * @param {any|Email} address
+   * @param {any|string|Email|Stringable} address
    */
   static canParse(address) {
     try {
@@ -48,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

@@ -1,4 +1,6 @@
+export function clamp(val: number, min: number, max: number): number;
 export function round(number: number, precision?: number): number;
+export function capitalize(str: string): string;
 export class Email extends URL {
 	/**
 	 * The domain name and extension of the email.
@@ -15,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 {};

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

@@ -1,117 +0,0 @@
-/* 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`,
-]