feat(pkg:string): added API String.isEmailAddress

Author: fenying

CHANGES.md

@@ -11,6 +11,7 @@
 - feat(pkg:async): added API `Async.autoRetry`, with exponential backoff and jitter supports.
 - fix(pkg:network): export API `Network.isValidIPv4Address`
 - feat(pkg:network): add API `Network.isValidMacAddress`
+- feat(pkg:string): add API `String.isEmailAddress`
 
 ## v1.2.1
 

packages/partials/string/src/Functions/IsEmailAddress.test.ts

@@ -0,0 +1,99 @@
+import * as NodeTest from 'node:test';
+import * as NodeAssert from 'node:assert';
+import { isEmailAddress } from './IsEmailAddress';
+
+NodeTest.describe('Function String.isEmailAddress', () => {
+
+    NodeTest.it('Should return true for valid email addresses', () => {
+
+        for (const email of [
+            '[email protected]',
+            '[email protected]',
+            '[email protected]',
+            '[email protected]',
+        ]) {
+
+            NodeAssert.strictEqual(isEmailAddress(email), true, `Email "${email}" should be valid.`);
+        }
+    });
+
+    NodeTest.it('Specific maximum length of email addresses should work', () => {
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { maxLength: 20, domains: [], }),
+            true,
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { maxLength: 10 }),
+            false,
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('i'.repeat(244) + '@example.org', { maxLength: 256 }),
+            false,
+            'The maxLength should not exceed the hard limit of the maximum length 255.',
+        );
+    });
+
+    NodeTest.it('Specific allowed list of domains should work', () => {
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { domains: [
+                'example.org',
+                'example.io',
+            ] }),
+            true,
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { domains: [
+                'example.org',
+                'example.io',
+            ] }),
+            true,
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { domains: [
+                'example.org',
+                'example.IO',
+            ] }),
+            false,
+            'The domain will not be treated as case-insensitive.',
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { domains: [
+                'example.org',
+                'example.io',
+            ] }),
+            true,
+            'The domain and email address should be case-insensitive.',
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { domains: ['example.com'] }),
+            false,
+        );
+
+        NodeAssert.strictEqual(
+            isEmailAddress('[email protected]', { domains: ['example.com'] }),
+            false,
+            'The domain and email address should be case-insensitive.',
+        );
+    });
+
+    NodeTest.it('Should return false for invalid email addresses', () => {
+
+        for (const email of [
+            '[email protected]',
+            '[email protected]',
+            '[email protected]',
+            '',
+        ]) {
+
+            NodeAssert.strictEqual(isEmailAddress(email), false, `Email "${email}" should be invalid.`);
+        }
+    });
+});

packages/partials/string/src/Functions/IsEmailAddress.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright 2025 Angus.Fenying <[email protected]>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// eslint-disable-next-line max-len
+const EMAIL_REGEXP = /^[-a-z0-9_+][-a-z0-9+_.]{0,62}@[a-z0-9][-a-z0-9]{0,62}(\.[a-z0-9][-a-z0-9]{0,62})*\.[a-z]{2,26}$/i;
+
+const MAX_EMAIL_LENGTH = 255;
+const MIN_EMAIL_LENGTH = 6; // 1 char before '@' + 1 char after '@' + 4 chars for domain
+
+/**
+ * The extra options for email validation.
+ */
+export interface IEmailValidationOptions {
+
+    /**
+     * The expected maximum length of the email address.
+     *
+     * Useful when some systems have a hard limit on the length of email
+     * addresses.
+     *
+     * If this value is larger than `MAX_EMAIL_LENGTH`, it will be ignored and
+     * `MAX_EMAIL_LENGTH` will be used instead.
+     *
+     * @default MAX_EMAIL_LENGTH
+     */
+    maxLength?: number;
+
+    /**
+     * The allowed list of domains.
+     *
+     * If omitted or an empty array is provided, all domains are allowed.
+     *
+     * > NOTICE: The email address are compared in lower-case, but only
+     * > lower-case domains are supported. The domains containing upper-case
+     * > characters will not match.
+     *
+     * @default []
+     */
+    domains?: string[];
+}
+
+/**
+ * Test if a string is a valid email address.
+ *
+ * @param email  The string to test.
+ * @param opts   The extra options for email validation.
+ *
+ * @returns `true` if the string is a valid email address, `false` otherwise.
+ */
+export function isEmailAddress(email: string, opts?: IEmailValidationOptions): boolean {
+
+    const formatOk = email.length >= MIN_EMAIL_LENGTH &&
+        email.length <= Math.min(opts?.maxLength ?? MAX_EMAIL_LENGTH, MAX_EMAIL_LENGTH) &&
+        !email.includes('..') &&
+        !email.includes('.@') &&
+        EMAIL_REGEXP.test(email);
+
+    if (!formatOk) {
+
+        return false;
+    }
+
+    if (opts?.domains?.length) {
+
+        return opts.domains.includes(email.split('@')[1].toLowerCase());
+    }
+
+    return true;
+}

packages/partials/string/src/index.ts

@@ -19,6 +19,7 @@ export * from './Functions/EvilSpace';
 export * from './Functions/Random';
 export * from './Functions/RegexpEscape';
 export * from './Functions/Html';
+export * from './Functions/IsEmailAddress';
 export * from './Functions/ToChunks';
 export * from './Functions/NameCase';
 export * from './Classes/UnitParser';