frontacles 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -8,12 +8,59 @@ 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).
+Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.3...main).
+
+## v0.3.0 (2025-03-06)
+
+Compare with [last published version](https://github.com/frontacles/frontacles/compare/0.2.2...0.2.3).
+
+### 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](./src/math/bench)
+- 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).
+
+### Breaking
+
+- Make `Email.username` and `Email.hostname` mutable to follow `URL.username` and `URL.hostname` behavior.
+
+### Improved
+
+- Override documentation inherited from `URL` for `Email.username` and `Email.hostname`.
 
 ## v0.2.1 (2025-02-28)
 
 Compare with [previous version](https://github.com/frontacles/frontacles/compare/0.2.0...0.2.1).
 
+### Breaking
+
+- Rename `Email.host` into `Email.hostname` to better match `URL`.
+
 ### Improved
 
 - `Email` is now a couple of bytes lighter.
@@ -24,7 +71,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,11 +5,103 @@ 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 [222 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 | [`Email`](#email) | 173 B |
+|  | **everything** | 252 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 { clamp } from 'frontacles/math'
+
+clamp(17, 3, 8) // 8
+clamp(-3, 3, 8) // 3
+clamp(5, 3, 8)  // 5
+```
+
+`-0` and `Infinity` are accepted:
+
+```js
+clamp(-2, -0, 10)      // -0
+clamp(5, 0, Infinity)  // 5
+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.
+
+```js
+import { round } from 'frontacles/math'
+
+round(687.3456)      // 687
+round(687.3456, 0)   // 687
+round(687.3456, 2)   // 687.35
+```
+
+A negative precision will round up to multiple of tens:
+
+```js
+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:
+
+```js
+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
+
+### `Email`
+
+A class to instantiate an `Email` object or validate email addresses.
+
+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.
 
 ```js
 import { Email } from 'frontacles/url/email'
@@ -17,21 +109,26 @@ import { Email } from 'frontacles/url/email'
 const email = new Email('someone@domain.tld')
 ```
 
-Get the username and the hostname separately.
+Get or set the username and the 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')
 ```
 
-Turn the email object into a string by using it along another string, or use `toString`.
+An `Email` object is converted to a string when used along another string, or by directly calling `toString`.
 
 ```js
-console.log(`email: ${email}`) // 'email: someone@domain.tld'
-console.log(email.toString()) // 'someone@domain.tld'
+console.log(`email: ${email}`) // 'email: someone@newdomain.tld'
+console.log(email.toString()) // 'someone@newdomain.tld'
 ```
 
-Validate that a string is a valid email address. It passes the complete Zod test suites, and beyond.
+Validate an email address with `Email.canParse`. It passes the complete Zod test suites, and beyond.
 
 ```js
 Email.canParse('someone@domain.tld') // true
@@ -44,7 +141,7 @@ 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 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')
@@ -56,11 +153,11 @@ 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).
+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')`.
 
@@ -68,12 +165,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.1",
+  "version": "0.3.0",
   "description": "Front-end utilities for artisans",
   "type": "module",
   "sideEffects": false,
@@ -16,10 +16,12 @@
   },
   "scripts": {
     "types": "tsc && dts-bundle-generator --silent --no-banner=true -o types/index.d.ts types-transitive/index.d.ts",
+    "posttypes": "node scripts/inject-jsdoc.mjs",
     "test": "vitest run",
     "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",
@@ -29,6 +31,8 @@
   "files": [
     "CHANGELOG.md",
     "src/**/*.js",
+    "!src/**/bench",
+    "!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

@@ -2,7 +2,6 @@
 export class Email extends URL {
 
   /**
-   *
    * @param {string|Email} address An email address like `someone@domain.tld`.
    */
   constructor(address) {
@@ -13,24 +12,6 @@ export class Email extends URL {
     }
   }
 
-  /**
-   * 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()
   }
@@ -50,7 +31,8 @@ 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
   }
 
   /**

package/types/index.d.ts

@@ -1,28 +1,29 @@
+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 {
 	/**
-	 * Whether or not an email address is parsable and valid.
+	 * The domain name and extension of the email.
 	 *
-	 * @param {any|Email} address
+	 * In `username@domain.tld`, it is `domain.tld`.
 	 */
-	static canParse(address: any | Email): boolean;
+	declare hostname: string;
 	/**
+	 * The username of the email.
 	 *
-	 * @param {string|Email} address An email address like `someone@domain.tld`.
+	 * In `username@domain.tld`, it is `username`.
 	 */
-	constructor(address: string | Email);
+	declare username: string;
 	/**
-	 * The domain name and extension of the email.
+	 * Whether or not an email address is parsable and valid.
 	 *
-	 * In `username@domain.tld`, it is `domain.tld`.
+	 * @param {any|Email} address
 	 */
-	get hostname(): string;
+	static canParse(address: any | Email): boolean;
 	/**
-	 * The username of the email.
-	 *
-	 * In `username@domain.tld`, it is `username`.
+	 * @param {string|Email} address An email address like `someone@domain.tld`.
 	 */
-	get username(): string;
+	constructor(address: string | Email);
 	#private;
 }
 

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`,
-]