@codelegend/email-validator 0.0.0-stage → 1.0.1

package/index.d.ts

@@ -0,0 +1,26 @@
+declare namespace emailValidator {
+  interface Options {
+    /** Exact exceptions overriding bundled and custom blocks. */
+    allowedDomains?: Iterable<string>;
+    blockedDomains?: Iterable<string>;
+    /** Apply blocking rules to subdomains. Default true. */
+    blockSubdomains?: boolean;
+    /** Use bundled disposable domains. Default true. */
+    useDefaultDomains?: boolean;
+  }
+  interface Accepted { valid: true; code: 'EMAIL_ACCEPTED'; message: string; email: string; domain: string; }
+  interface Rejected { valid: false; code: 'EMAIL_REQUIRED' | 'INVALID_EMAIL' | 'BLOCKED_DOMAIN' | 'DISPOSABLE_EMAIL'; message: string; email?: string; domain?: string; matchedDomain?: string; }
+  type Result = Accepted | Rejected;
+  interface MiddlewareRequest { body?: { email?: unknown; [key: string]: unknown }; }
+  interface MiddlewareResponse { status(code: number): MiddlewareResponse; json(body: Rejected): unknown; }
+  interface Validator {
+    validateEmail(input: unknown): Result;
+    validateMany(inputs: readonly unknown[]): Result[];
+    isValid(input: unknown): boolean;
+    middleware(req: MiddlewareRequest, res: MiddlewareResponse, next: () => void): unknown;
+  }
+  function createEmailValidator(options?: Options): Validator;
+  function validateEmail(input: unknown): Result;
+  function isValidEmail(input: unknown): boolean;
+}
+export = emailValidator;

package/index.js

@@ -0,0 +1,82 @@
+'use strict';
+const { domainToASCII } = require('node:url');
+const bundledDomains = new Set(require('./disposable-domains.json'));
+
+function normalizeDomain(value) {
+  if (typeof value !== 'string') return '';
+  const raw = value.trim().toLowerCase();
+  // IDNA conversion must not silently discard URL paths, ports, or other syntax.
+  if (!raw || /[\s/@:#?\\%\[\]]/.test(raw)) return '';
+  let domain;
+  try { domain = domainToASCII(raw); } catch { return ''; }
+  const labels = domain.split('.');
+  if (domain.length > 253 || labels.length < 2 || /^\d+$/.test(labels.at(-1))) return '';
+  return labels.every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) ? domain : '';
+}
+
+function domainSet(values, name) {
+  if (values == null || typeof values === 'string' || typeof values[Symbol.iterator] !== 'function') throw new TypeError(`${name} must be an iterable of domain strings, such as an array or Set.`);
+  const domains = new Set();
+  for (const value of values) {
+    const domain = normalizeDomain(value);
+    if (!domain) throw new TypeError(`Invalid domain in ${name}: ${String(value)}`);
+    domains.add(domain);
+  }
+  return domains;
+}
+
+/** Compile independent domain sets once and reuse across requests. */
+function createEmailValidator(options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Options must be an object.');
+  const { allowedDomains = [], blockedDomains = [], blockSubdomains = true, useDefaultDomains = true } = options;
+  if (typeof blockSubdomains !== 'boolean' || typeof useDefaultDomains !== 'boolean') throw new TypeError('blockSubdomains and useDefaultDomains must be booleans.');
+  const allowed = domainSet(allowedDomains, 'allowedDomains');
+  const blocked = domainSet(blockedDomains, 'blockedDomains');
+
+  function match(domain, domains) {
+    if (domains.has(domain)) return domain;
+    if (!blockSubdomains) return null;
+    const labels = domain.split('.');
+    for (let i = 1; i < labels.length - 1; i++) {
+      const parent = labels.slice(i).join('.');
+      if (domains.has(parent)) return parent;
+    }
+    return null;
+  }
+
+  function validateEmail(input) {
+    const reject = (code, message, extra = {}) => ({ valid: false, code, message, ...extra });
+    if (typeof input !== 'string' || !input.trim()) return reject('EMAIL_REQUIRED', 'Email is required');
+    const parts = input.trim().split('@');
+    if (parts.length !== 2) return reject('INVALID_EMAIL', 'Invalid email format');
+    const [localPart, rawDomain] = parts;
+    const domain = rawDomain === rawDomain.trim() ? normalizeDomain(rawDomain) : '';
+    const validLocal = /^[A-Za-z0-9!#$%&'*+/=?^_`{|}~.-]+$/.test(localPart) && !localPart.startsWith('.') && !localPart.endsWith('.') && !localPart.includes('..');
+    if (!validLocal || !domain || localPart.length > 64 || localPart.length + domain.length + 1 > 254) return reject('INVALID_EMAIL', 'Invalid email format');
+    const email = `${localPart}@${domain}`;
+    // Exact allowlist exceptions override custom and bundled blocks after syntax checks.
+    if (allowed.has(domain)) return { valid: true, code: 'EMAIL_ACCEPTED', message: 'Email accepted', email, domain };
+    const customMatch = match(domain, blocked);
+    if (customMatch) return reject('BLOCKED_DOMAIN', 'Email domain is blocked', { email, domain, matchedDomain: customMatch });
+    const disposableMatch = useDefaultDomains && match(domain, bundledDomains);
+    if (disposableMatch) return reject('DISPOSABLE_EMAIL', 'Temporary or disposable emails are not allowed', { email, domain, matchedDomain: disposableMatch });
+    return { valid: true, code: 'EMAIL_ACCEPTED', message: 'Email accepted', email, domain };
+  }
+
+  function validateMany(inputs) {
+    if (!Array.isArray(inputs)) throw new TypeError('validateMany expects an array.');
+    return inputs.map(validateEmail);
+  }
+
+  function middleware(req, res, next) {
+    const result = validateEmail(req.body?.email);
+    if (!result.valid) return res.status(400).json(result);
+    req.body.email = result.email;
+    return next();
+  }
+
+  return Object.freeze({ validateEmail, validateMany, isValid: input => validateEmail(input).valid, middleware });
+}
+
+const defaultValidator = createEmailValidator();
+module.exports = { createEmailValidator, validateEmail: defaultValidator.validateEmail, isValidEmail: defaultValidator.isValid };

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@codelegend/email-validator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Reusable email validation and disposable domain blocking",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./disposable-domains.json": "./disposable-domains.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "disposable-domains.json"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "email",
+    "validator",
+    "disposable",
+    "express"
+  ]
+}