qa-smart-validator 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# qa-smart-validator
+
+A small, framework-agnostic validation library for QA automation. Use it in Node.js test scripts, CI checks, or any JavaScript environment (Node.js ≥ 18). No Playwright or test-runner dependency—just validators and a safe wrapper so your automation never crashes on bad input.
+
+## Features
+
+- **Email validator** – Standard format; supports gmail.com, outlook.com, yahoo.com, and custom domains (e.g. talentica.com). Rejects empty, null, and invalid formats.
+- **String validator** – Ensures value is a string and enforces optional min/max length (after trim). Clear, controlled errors.
+- **Phone validator** – Digits only; length 10–15. Rejects empty, null, non-digits, and out-of-range length.
+- **safeValidate(fn)** – Wraps any sync validation in try/catch. Returns `{ valid: true, data }` or `{ valid: false, error }` so execution never throws.
+- **ValidationError** – All validators throw this (subclass of `Error`) with `message`, `code`, and optional `field` for stable assertions and reporting.
+
+## Requirements
+
+- **Node.js** ≥ 18  
+- **ES Modules** (`"type": "module"` or `.mjs`)
+
+## Installation
+
+```bash
+npm install qa-smart-validator
+```
+
+## Usage
+
+```javascript
+import {
+  validateEmail,
+  validateString,
+  validatePhone,
+  safeValidate,
+  ValidationError,
+} from 'qa-smart-validator';
+```
+
+## Validator examples
+
+### validateEmail(email)
+
+Supports gmail.com, outlook.com, yahoo.com, and custom domains (e.g. talentica.com). Rejects empty, null, and invalid formats.
+
+```javascript
+validateEmail('user@gmail.com');       // { valid: true, message: 'Valid email' }
+validateEmail('admin@talentica.com');  // { valid: true, message: 'Valid email' }
+validateEmail('');                     // throws ValidationError: Email cannot be empty
+validateEmail(null);                   // throws ValidationError: Email is required
+validateEmail('not-an-email');         // throws ValidationError: Invalid email format
+```
+
+### validateString(value, minLength?, maxLength?)
+
+Ensures value is a string and enforces optional min/max length (after trim).
+
+```javascript
+validateString('hello', 1, 10);  // { valid: true, value: 'hello' }
+validateString('short', 10);     // throws ValidationError: String length 5 is less than minimum 10
+validateString(123);             // throws ValidationError: Value must be a string, got number
+```
+
+### validatePhone(phone)
+
+Digits only; length 10–15.
+
+```javascript
+validatePhone('1234567890');   // { valid: true, value: '1234567890' }
+validatePhone('+1234567890');  // throws ValidationError: Phone must contain only digits
+validatePhone('123');          // throws ValidationError: Phone length 3 is less than minimum 10
+```
+
+## safeValidate example
+
+Wraps execution in try/catch and returns a structured result. Never throws.
+
+- **Success:** `{ valid: true, data }` – `data` is the return value of the function.
+- **Failure:** `{ valid: false, error }` – `error` is the thrown error message.
+
+```javascript
+import { validateEmail, safeValidate } from 'qa-smart-validator';
+
+const result = safeValidate(() => validateEmail('test@gmail.com'));
+
+console.log(result);
+// { valid: true, data: { valid: true, message: 'Valid email' } }
+
+const failed = safeValidate(() => validateEmail(''));
+console.log(failed);
+// { valid: false, error: 'Email cannot be empty' }
+```
+
+## Example file
+
+An `example.js` is included in the package. After installing, you can run it from your app directory:
+
+```bash
+node example.js
+```
+
+## API summary
+
+| Export            | Description |
+|-------------------|-------------|
+| `validateEmail`   | Validates email; throws `ValidationError` on failure. |
+| `validateString`  | Validates string and optional length; throws `ValidationError` on failure. |
+| `validatePhone`   | Validates phone (digits, 10–15); throws `ValidationError` on failure. |
+| `safeValidate(fn)`| Runs `fn()` in try/catch; returns `{ valid, data }` or `{ valid, error }`. |
+| `ValidationError` | Error class with `message`, `code`, `field`. |
+| `EMAIL_REGEX`     | RegExp for email (advanced use). |
+| `DIGITS_ONLY`     | RegExp for digits (advanced use). |
+| `PHONE_MIN_LENGTH` / `PHONE_MAX_LENGTH` | 10 and 15 (advanced use). |
+
+## Contributing
+
+1. Fork the repository.
+2. Create a branch (`git checkout -b feature/your-feature`).
+3. Run tests: `npm test`. Run lint: `npm run lint`. Format: `npm run format`.
+4. Commit your changes and push the branch.
+5. Open a Pull Request.
+
+## Publishing to npm
+
+Before publishing:
+
+1. **Dry run** – See what will be packed and run lint/tests:
+   ```bash
+   npm run prepublishOnly
+   npm pack
+   ```
+2. **Login** (if needed):
+   ```bash
+   npm login
+   ```
+3. **Publish** (scoped packages use `--access public` for first publish):
+   ```bash
+   npm publish --access public
+   ```
+
+Update `repository`, `bugs`, `homepage`, and `author` in `package.json` to your own repo and identity before publishing.
+
+## License
+
+MIT

package/example.js

@@ -0,0 +1,12 @@
+/**
+ * Example usage of qa-smart-validator.
+ * Run from project root (after npm install): node example.js
+ */
+
+import { validateEmail, safeValidate } from 'qa-smart-validator';
+
+const result = safeValidate(() => validateEmail('test@gmail.com'));
+
+console.log(result);
+// Success: { valid: true, data: { valid: true, message: 'Valid email' } }
+// Failure: { valid: false, error: '...' }

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "qa-smart-validator",
+  "version": "1.0.0",
+  "description": "Reusable validation library for QA automation testing",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "example.js"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.js\"",
+    "lint": "eslint src",
+    "format": "prettier --write \"src/**/*.js\" \"test/**/*.js\" example.js",
+    "format:check": "prettier --check \"src/**/*.js\" \"test/**/*.js\" example.js",
+    "prepublishOnly": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "qa",
+    "automation",
+    "validation",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "Sarath Sasidharan <sarathsasidharan13031997@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/qa-smart-validator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/qa-smart-validator/issues"
+  },
+  "homepage": "https://github.com/your-org/qa-smart-validator#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "eslint": "^9.15.0",
+    "prettier": "^3.3.3"
+  }
+}

package/src/index.js

@@ -0,0 +1,15 @@
+/**
+ * qa-smart-validator – Reusable validation library for QA automation.
+ * @module qa-smart-validator
+ */
+
+export { validateEmail, EMAIL_REGEX } from './validators/emailValidator.js';
+export { validateString } from './validators/stringValidator.js';
+export {
+  validatePhone,
+  DIGITS_ONLY,
+  PHONE_MIN_LENGTH,
+  PHONE_MAX_LENGTH,
+} from './validators/phoneValidator.js';
+export { safeValidate } from './utils/safeValidate.js';
+export { ValidationError } from './utils/ValidationError.js';

package/src/utils/ValidationError.js

@@ -0,0 +1,20 @@
+/**
+ * Custom error for validation failures. Use in try/catch to distinguish
+ * validation errors and assert on stable `code` / `field`.
+ * @extends Error
+ */
+export class ValidationError extends Error {
+  /**
+   * @param {string} message - Human-readable error message.
+   * @param {Object} [options] - Optional config.
+   * @param {string} [options.code] - Machine-readable code (e.g. 'EMAIL_INVALID').
+   * @param {string} [options.field] - Field name for form/API context.
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'ValidationError';
+    this.code = options.code ?? 'VALIDATION_ERROR';
+    this.field = options.field;
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}

package/src/utils/assertions.js

@@ -0,0 +1,56 @@
+/**
+ * Shared assertion helpers for validators. Centralizes error type and messages.
+ * @module utils/assertions
+ */
+
+import { ValidationError } from './ValidationError.js';
+
+/**
+ * Ensures value is a non-null, non-undefined string.
+ * @param {*} value - Value to check.
+ * @param {string} name - Name of the field (for error messages).
+ * @returns {string} Trimmed string.
+ * @throws {ValidationError}
+ */
+export function assertString(value, name = 'Value') {
+  if (value === undefined || value === null) {
+    throw new ValidationError(`${name} is required`, { code: 'REQUIRED' });
+  }
+  if (typeof value !== 'string') {
+    throw new ValidationError(
+      `${name} must be a string, got ${typeof value}`,
+      { code: 'INVALID_TYPE' }
+    );
+  }
+  return value.trim();
+}
+
+/**
+ * Ensures a trimmed string is non-empty.
+ * @param {string} trimmed - Already trimmed string.
+ * @param {string} name - Field name for error message.
+ * @throws {ValidationError}
+ */
+export function assertNonEmpty(trimmed, name = 'Value') {
+  if (trimmed.length === 0) {
+    throw new ValidationError(`${name} cannot be empty`, { code: 'EMPTY' });
+  }
+}
+
+/**
+ * Ensures a value is a valid non-negative number (for length constraints).
+ * @param {*} value - Value to check.
+ * @param {string} name - Parameter name for error message.
+ * @returns {number}
+ * @throws {ValidationError}
+ */
+export function assertNonNegativeNumber(value, name) {
+  const num = Number(value);
+  if (value === undefined || value === null || Number.isNaN(num) || num < 0) {
+    throw new ValidationError(
+      `${name} must be a non-negative number`,
+      { code: 'INVALID_PARAMETER' }
+    );
+  }
+  return num;
+}

package/src/utils/safeValidate.js

@@ -0,0 +1,32 @@
+/**
+ * Safe validation wrapper for QA automation.
+ * Wraps a synchronous function in try/catch so execution never throws.
+ * @module utils/safeValidate
+ */
+
+/**
+ * Runs a synchronous validation (or any sync function) and returns a result object.
+ * Never throws; use in automation when you want a stable result shape instead of exceptions.
+ * @param {() => *} fn - Synchronous function to run (e.g. () => validateEmail(value)). No arguments.
+ * @returns {{ valid: true, data: * } | { valid: false, error: string, code?: string }} Success: `{ valid: true, data }`. Failure: `{ valid: false, error, code? }` (code from ValidationError if present).
+ * @example
+ * safeValidate(() => validateEmail('user@gmail.com'));
+ * // { valid: true, data: { valid: true, message: 'Valid email' } }
+ *
+ * safeValidate(() => validateEmail(''));
+ * // { valid: false, error: 'Email cannot be empty', code: 'EMPTY' }
+ */
+export function safeValidate(fn) {
+  if (typeof fn !== 'function') {
+    return { valid: false, error: 'safeValidate requires a function' };
+  }
+  try {
+    const data = fn();
+    return { valid: true, data };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const result = { valid: false, error: message };
+    if (err?.code) result.code = err.code;
+    return result;
+  }
+}

package/src/validators/emailValidator.js

@@ -0,0 +1,39 @@
+/**
+ * Email validator for QA automation.
+ * Validates standard email format. Supports gmail.com, outlook.com, yahoo.com,
+ * and custom domains (e.g. talentica.com). Rejects empty, null, and invalid formats.
+ * @module validators/emailValidator
+ */
+
+import { ValidationError } from '../utils/ValidationError.js';
+import { assertString, assertNonEmpty } from '../utils/assertions.js';
+
+/** Standard email format: local@domain.tld (supports common and custom domains) */
+const EMAIL_REGEX = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+
+/**
+ * Validates an email address.
+ * @param {string} email - The email string to validate.
+ * @returns {{ valid: true, message: string }} Success result with message.
+ * @throws {ValidationError} If email is empty, null, not a string, or invalid format.
+ * @example
+ * validateEmail('user@gmail.com');   // { valid: true, message: 'Valid email' }
+ * validateEmail('admin@talentica.com'); // { valid: true, message: 'Valid email' }
+ * validateEmail('');   // throws ValidationError: Email cannot be empty
+ * validateEmail(null); // throws ValidationError: Email is required
+ */
+export function validateEmail(email) {
+  const trimmed = assertString(email, 'Email');
+  assertNonEmpty(trimmed, 'Email');
+
+  if (!EMAIL_REGEX.test(trimmed)) {
+    throw new ValidationError(`Invalid email format: "${trimmed}"`, {
+      code: 'EMAIL_INVALID',
+      field: 'email',
+    });
+  }
+
+  return { valid: true, message: 'Valid email' };
+}
+
+export { EMAIL_REGEX };

package/src/validators/phoneValidator.js

@@ -0,0 +1,55 @@
+/**
+ * Phone validator for QA automation.
+ * Accepts only digits; length must be between 10 and 15 (inclusive).
+ * Rejects empty, null, non-string, non-digits, and out-of-range length.
+ * @module validators/phoneValidator
+ */
+
+import { ValidationError } from '../utils/ValidationError.js';
+import { assertString, assertNonEmpty } from '../utils/assertions.js';
+
+/** Digits only (for phone validation) */
+const DIGITS_ONLY = /^\d+$/;
+
+/** Phone length bounds (inclusive) */
+const PHONE_MIN_LENGTH = 10;
+const PHONE_MAX_LENGTH = 15;
+
+/**
+ * Validates a phone number (digits only, 10–15 characters).
+ * @param {string} phone - The phone string to validate.
+ * @returns {{ valid: true, value: string }} Success result with digit string.
+ * @throws {ValidationError} If phone is empty, null, non-string, contains non-digits, or length out of range.
+ * @example
+ * validatePhone('1234567890');  // { valid: true, value: '1234567890' }
+ * validatePhone('123');        // throws ValidationError: Phone length 3 is less than minimum 10
+ */
+export function validatePhone(phone) {
+  const trimmed = assertString(phone, 'Phone');
+  assertNonEmpty(trimmed, 'Phone');
+
+  if (!DIGITS_ONLY.test(trimmed)) {
+    throw new ValidationError('Phone must contain only digits', {
+      code: 'PHONE_INVALID',
+      field: 'phone',
+    });
+  }
+
+  if (trimmed.length < PHONE_MIN_LENGTH) {
+    throw new ValidationError(
+      `Phone length ${trimmed.length} is less than minimum ${PHONE_MIN_LENGTH}`,
+      { code: 'PHONE_TOO_SHORT', field: 'phone' }
+    );
+  }
+
+  if (trimmed.length > PHONE_MAX_LENGTH) {
+    throw new ValidationError(
+      `Phone length ${trimmed.length} exceeds maximum ${PHONE_MAX_LENGTH}`,
+      { code: 'PHONE_TOO_LONG', field: 'phone' }
+    );
+  }
+
+  return { valid: true, value: trimmed };
+}
+
+export { DIGITS_ONLY, PHONE_MIN_LENGTH, PHONE_MAX_LENGTH };

package/src/validators/stringValidator.js

@@ -0,0 +1,59 @@
+/**
+ * String validator for QA automation.
+ * Ensures value is a string and enforces optional min/max length (after trim).
+ * @module validators/stringValidator
+ */
+
+import { ValidationError } from '../utils/ValidationError.js';
+import {
+  assertString,
+  assertNonNegativeNumber,
+} from '../utils/assertions.js';
+
+/**
+ * Validates a string value with optional length constraints.
+ * Value is trimmed before length checks. Throws controlled ValidationError for invalid input.
+ * @param {*} value - The value to validate (must be a string).
+ * @param {number} [minLength] - Minimum length (inclusive). Omit for no minimum.
+ * @param {number} [maxLength] - Maximum length (inclusive). Omit for no maximum.
+ * @returns {{ valid: true, value: string }} Success result with trimmed value.
+ * @throws {ValidationError} If value is null/undefined, not a string, or fails length validation.
+ * @example
+ * validateString('hello', 1, 10);  // { valid: true, value: 'hello' }
+ * validateString(123);             // throws ValidationError: Value must be a string, got number
+ */
+export function validateString(value, minLength, maxLength) {
+  const trimmed = assertString(value, 'Value');
+
+  if (minLength !== undefined && minLength !== null) {
+    const min = assertNonNegativeNumber(minLength, 'minLength');
+    if (trimmed.length < min) {
+      throw new ValidationError(
+        `String length ${trimmed.length} is less than minimum ${min}`,
+        { code: 'STRING_TOO_SHORT', field: 'value' }
+      );
+    }
+  }
+
+  if (maxLength !== undefined && maxLength !== null) {
+    const max = assertNonNegativeNumber(maxLength, 'maxLength');
+    if (trimmed.length > max) {
+      throw new ValidationError(
+        `String length ${trimmed.length} exceeds maximum ${max}`,
+        { code: 'STRING_TOO_LONG', field: 'value' }
+      );
+    }
+  }
+
+  if (
+    minLength != null &&
+    maxLength != null &&
+    Number(minLength) > Number(maxLength)
+  ) {
+    throw new ValidationError('minLength cannot be greater than maxLength', {
+      code: 'INVALID_PARAMETER',
+    });
+  }
+
+  return { valid: true, value: trimmed };
+}