@rbl-dev/validator-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rbl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,335 @@
+# @rbl/validator-ts
+
+[![CI](https://github.com)](https://github.com)
+[![npm version](https://shields.io)](https://npmjs.com)
+[![License: MIT](https://shields.io)](https://opensource.org)
+
+A lightweight, class-based, extensible validation engine for TypeScript applications that mirrors Laravel's native validation architecture. Stop rewriting form validation logic across the stack—reuse your standard pipe-syntax schemas (`required|email|min:8`) natively inside frontend user interfaces.
+
+## ✨ Features
+
+- **Pipe Syntax String Parsing:** Supports classic rule definitions like `required|email|min:6|max:24`.
+- **Compatible Lifecycle API:** Exposes familiar helpers like `.passes()`, `.fails()`, `.invalid()`, and `.getError()`.
+- **Advanced Engine Features:** Bundled out-of-the-box support for validation short-circuiting (`bail`), implicit validation rule skipping, and tokenized custom error message overrides (`:attribute`).
+- **Framework Reactivity Integrations:** Dedicated, optimized reactive hooks for both **React** and **Vue 3**.
+- **Highly Extensible:** Write custom rule classes implementing a standard structural contract or register global shortcuts dynamically via `Validator.extend()`.
+
+---
+
+## 📦 Installation
+
+Install the package via your preferred node package manager:
+
+```bash
+npm install @rbl/validator-ts
+```
+
+---
+
+## 🚀 Basic Core Usage
+
+You can use the standalone validation engine anywhere in your TypeScript or Node.js environment exactly like Laravel's backend implementation:
+
+```typescript
+import { Validator } from '@rbl/validator-ts';
+
+const data = {
+  email: 'not-an-email',
+  password: '123',
+};
+
+const rules = {
+  email: 'bail|required|email',
+  password: 'required|min:8',
+};
+
+// Custom messages with token placement overrides
+const customMessages = {
+  'email.required': 'We absolutely require an email address.',
+  'password.min': 'Your chosen password is insecure! It must be at least :min characters.',
+};
+
+// 1. Core instantiation using the static make factory
+const validator = Validator.make(data, rules, customMessages);
+
+// 2. Evaluate outcomes using structural flags
+if (validator.fails()) {
+  console.log(validator.invalid()); 
+  // Output: ['email', 'password']
+
+  console.log(validator.getError('email')); 
+  // Output: ['The email must be a valid email address.']
+}
+```
+
+---
+
+## 🎨 Frontend Framework Integrations
+
+### 1. React Integration (`useReactFormValidator`)
+
+The React hook tracks state using immutable updates. It auto-evaluates on input cycles via a performance-optimized `useMemo` block.
+
+```tsx
+import React from 'react';
+import { useReactFormValidator } from '@rbl/validator-ts';
+
+export function RegistrationForm() {
+  const { form, handleChange, getError, passes } = useReactFormValidator(
+    { email: '', password: '' },
+    { email: 'bail|required|email', password: 'required|min:8' },
+    { 'email.required': 'Please enter your email address to register.' }
+  );
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (passes) {
+      console.log('Validation success! Sending payload:', form);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '300px' }}>
+      <div>
+        <label>Email</label>
+        <input 
+          type="text" 
+          value={form.email} 
+          onChange={(e) => handleChange('email', e.target.value)} 
+        />
+        {getError('email') && <p style={{ color: 'red', margin: 0 }}>{getError('email')[0]}</p>}
+      </div>
+
+      <div>
+        <label>Password</label>
+        <input 
+          type="password" 
+          value={form.password} 
+          onChange={(e) => handleChange('password', e.target.value)} 
+        />
+        {getError('password') && <p style={{ color: 'red', margin: 0 }}>{getError('password')[0]}</p>}
+      </div>
+
+      <button type="submit" disabled={!passes}>Register</button>
+    </form>
+  );
+}
+```
+
+### 2. Vue 3 Integration (`useVueFormValidator`)
+
+The Vue integration hooks into Vue's native proxy reactivity system via `reactive` states and `computed` properties, validating input fields instantly on every keystroke.
+
+```html
+<script setup lang="ts">
+import { useVueFormValidator } from '@rbl/validator-ts';
+
+const { form, getError, passes } = useVueFormValidator(
+  { email: '', password: '' },
+  { email: 'bail|required|email', password: 'required|min:8' }
+);
+
+const submitForm = () => {
+  if (passes.value) {
+    console.log('Validation success! Sending payload:', form);
+  }
+};
+</script>
+
+<template>
+  <form @submit.prevent="submitForm" class="form-container">
+    <div class="field">
+      <label>Email Address</label>
+      <input v-model="form.email" type="text" />
+      <span v-if="getError('email')" class="error-msg">{{ getError('email')[0] }}</span>
+    </div>
+
+    <div class="field">
+      <label>Password</label>
+      <input v-model="form.password" type="password" />
+      <span v-if="getError('password')" class="error-msg">{{ getError('password')[0] }}</span>
+    </div>
+
+    <button type="submit" :disabled="!passes">Submit Form</button>
+  </form>
+</template>
+
+<style scoped>
+.form-container { display: flex; flex-direction: column; gap: 1rem; max-width: 300px; }
+.error-msg { color: red; font-size: 0.85rem; display: block; }
+</style>
+```
+
+---
+
+## 🛠 Adding Custom Rules
+
+### Method A: Global Extensions (String Shortcuts)
+Register global closures inside your app initialization file to use them anywhere in your string chains:
+
+```typescript
+import { Validator } from '@rbl/validator-ts';
+
+// Example: Registering a custom slug format string shortcut rule
+Validator.extend('slug', () => {
+  return {
+    validate(attribute, value, fail) {
+      const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+      if (typeof value === 'string' && !slugPattern.test(value)) {
+        fail('The :attribute field must be a valid url slug format.');
+      }
+    }
+  };
+});
+
+// Usage
+const rules = { project_name: 'required|slug' };
+```
+
+### Method B: Instantiated Contract Rule Classes
+For complex rules (like domain-specific checks), create a custom class implementing the `ValidationRule` blueprint contract:
+
+```typescript
+import { ValidationRule, FailCallback } from '@rbl/validator-ts';
+
+export class ProhibitDomain implements ValidationRule {
+  constructor(protected bannedDomain: string) {}
+
+  public validate(attribute: string, value: unknown, fail: FailCallback): void {
+    if (typeof value === 'string' && value.endsWith(`@${this.bannedDomain}`)) {
+      fail(`The :attribute cannot use email addresses registered under ${this.bannedDomain}.`);
+    }
+  }
+}
+
+// Usage
+import { ProhibitDomain } from './rules/ProhibitDomain';
+
+const rules = {
+  email: ['required', new ProhibitDomain('competitor.com')]
+};
+```
+### Method C: Asynchronous Custom Rules (e.g., Database/API Lookups)
+For rules that require server interaction—such as checking if an email is unique—implement the `ValidationRule` contract using an `async/await` signature. The engine natively coordinates async promises concurrently:
+
+```typescript
+import { ValidationRule, FailCallback } from '@rbl/validator-ts';
+
+export class UniqueEmailRule implements ValidationRule {
+  // Simulating an asynchronous database verification query
+  private async checkDatabaseAvailability(email: string): Promise<boolean> {
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        const registeredEmails = ['admin@site.com', 'hello@rbl.dev'];
+        resolve(!registeredEmails.includes(email));
+      }, 300); // 300ms network delay simulation
+    });
+  }
+
+  public async validate(attribute: string, value: unknown, fail: FailCallback): Promise<void> {
+    if (typeof value !== 'string') return;
+
+    const isAvailable = await this.checkDatabaseAvailability(value);
+    if (!isAvailable) {
+      fail(`The :attribute has already been taken.`);
+    }
+  }
+}
+
+// Usage with Async Engine Setup
+const validator = Validator.make(
+  { email: 'hello@rbl.dev' },
+  { email: ['required', 'email', new UniqueEmailRule()] }
+);
+
+// Trigger the async processing sequence
+await validator.validate();
+
+if (validator.fails()) {
+  console.log(validator.getError('email')); 
+  // Output: ['The email has already been taken.']
+}
+```
+
+## 🚀 Full-Stack Usage Examples
+
+### 1. Node.js Backend API Route (Express Example)
+
+Because the core engine supports asynchronous checks, you can use `@rbl/validator-ts` to secure your backend API endpoints. This example shows how to validate incoming request data, use an asynchronous database check, and return structured errors exactly like a Laravel API controller:
+
+```typescript
+import express, { Request, Response } from 'express';
+import { Validator } from '@rbl/validator-ts';
+import { UniqueEmailRule } from './rules/UniqueEmailRule'; // Your custom async rule
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/register', async (req: Request, res: Response) => {
+  // 1. Define your full-stack shared validation rules layout
+  const rules = {
+    'user.profile.username': 'bail|required|min:3',
+    'email': ['required', 'email', new UniqueEmailRule()],
+    'password': 'required|min:8'
+  };
+
+  // 2. Custom error messages with dynamic token replacement attributes
+  const customMessages = {
+    'user.profile.username.min': 'The username must be at least :min characters long.',
+    'email.required': 'An email address is strictly required to sign up.'
+  };
+
+  // 3. Initialize the style validation instance container
+  const validator = Validator.make(req.body, rules, customMessages);
+
+  // 4. Trigger the asynchronous verification pipeline sequence
+  await validator.validate();
+
+  // 5. Intercept failures and return an immediate 422 Unprocessable Entity payload
+  if (validator.fails()) {
+    return res.status(422).json({
+      message: 'The given data was invalid.',
+      errors: validator.getErrors() // Returns standard structured error maps
+    });
+  }
+
+  // 6. Execution proceeds safely if all validation parameters pass
+  try {
+    // Process user registration model database inserts here...
+    return res.status(201).json({ message: 'User registered successfully!' });
+  } catch (error) {
+    return res.status(500).json({ error: 'Internal Server Error' });
+  }
+});
+
+app.listen(3000, () => console.log('API Server running on port 3000'));
+```
+
+---
+
+### 2. Standalone Synchronous Usage
+
+If you are running a script or validating data locally on the fly without complex asynchronous database checks, use the instant execution method:
+
+```typescript
+import { Validator } from '@rbl/validator-ts';
+
+const localData = { username: 'jo' };
+const localRules = { username: 'required|min:5' };
+
+const validator = Validator.make(localData, localRules);
+
+// 🚀 Execute calculations immediately without using async/await keywords
+validator.validateSync();
+
+if (validator.fails()) {
+  console.log(validator.getError('username'));
+  // Output: ['The username must be at least 5 characters.']
+}
+```
+
+---
+
+## 📜 License
+
+Distributed under the MIT License. See `LICENSE` for more information.

package/dist/Validator.d.ts

@@ -0,0 +1,26 @@
+import { CustomRuleClosureFactory, ValidationRule } from './contracts/Validation.js';
+export declare class Validator {
+    private data;
+    private customMessages;
+    private errors;
+    private normalizedRules;
+    private static extensions;
+    constructor(data: Record<string, unknown>, rules: Record<string, string | (string | ValidationRule)[]>, customMessages?: Record<string, string>);
+    static make(data: Record<string, unknown>, rules: Record<string, string | (string | ValidationRule)[]>, customMessages?: Record<string, string>): Validator;
+    static extend(ruleName: string, factory: CustomRuleClosureFactory): void;
+    private normalizeRules;
+    private run;
+    validate(): Promise<boolean>;
+    /**
+     * Run the validation process synchronously across all rules.
+     * Automatically skips any complex asynchronous rule objects.
+     */
+    validateSync(): boolean;
+    private resolveStringRule;
+    private addError;
+    passes(): boolean;
+    fails(): boolean;
+    invalid(): string[];
+    getError(name: string): string[] | null;
+    getErrors(): Record<string, string[]>;
+}

package/dist/Validator.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Validator = void 0;
+const EmailRule_js_1 = require("./rules/EmailRule.js");
+const MaxRule_js_1 = require("./rules/MaxRule.js");
+const MinRule_js_1 = require("./rules/MinRule.js");
+const RequiredRule_js_1 = require("./rules/RequiredRule.js");
+const data_1 = require("./utils/data");
+class Validator {
+    data;
+    customMessages;
+    errors = {};
+    normalizedRules = {};
+    static extensions = {};
+    constructor(data, rules, customMessages = {}) {
+        this.data = data;
+        this.customMessages = customMessages;
+        this.normalizeRules(rules);
+        this.run();
+    }
+    static make(data, rules, customMessages = {}) {
+        return new Validator(data, rules, customMessages);
+    }
+    static extend(ruleName, factory) {
+        Validator.extensions[ruleName] = factory;
+    }
+    normalizeRules(rules) {
+        for (const [attribute, ruleMix] of Object.entries(rules)) {
+            let ruleArray = [];
+            if (typeof ruleMix === 'string') {
+                ruleArray = ruleMix.split('|');
+            }
+            else {
+                for (const item of ruleMix) {
+                    if (typeof item === 'string') {
+                        ruleArray.push(...item.split('|'));
+                    }
+                    else {
+                        ruleArray.push(item);
+                    }
+                }
+            }
+            this.normalizedRules[attribute] = ruleArray;
+        }
+    }
+    run() {
+        this.errors = {};
+        for (const [attribute, attributeRules] of Object.entries(this.normalizedRules)) {
+            const value = this.data[attribute];
+            const isEmpty = value === undefined || value === null || value === '';
+            let shouldBail = false;
+            for (const rawRule of attributeRules) {
+                if (rawRule === 'bail') {
+                    shouldBail = true;
+                    continue;
+                }
+                const rule = typeof rawRule === 'string'
+                    ? this.resolveStringRule(rawRule)
+                    : rawRule;
+                if (!rule)
+                    continue;
+                const isImplicit = rule.isImplicit === true;
+                if (isEmpty && !isImplicit)
+                    continue;
+                let ruleFailed = false;
+                const ruleName = typeof rawRule === 'string'
+                    ? rawRule.split(':')[0]
+                    : rule.constructor.name
+                        .toLowerCase()
+                        .replace('rule', '');
+                rule.validate(attribute, value, (defaultMessage) => {
+                    ruleFailed = true;
+                    const customKeyWithAttr = `${attribute}.${ruleName}`;
+                    const finalMessagePattern = this.customMessages[customKeyWithAttr] ||
+                        this.customMessages[ruleName] ||
+                        defaultMessage;
+                    const localizedMessage = finalMessagePattern.replace(/:attribute/g, attribute);
+                    this.addError(attribute, localizedMessage);
+                });
+                if (shouldBail && ruleFailed)
+                    break;
+            }
+        }
+    }
+    async validate() {
+        this.errors = {};
+        const validationPromises = [];
+        for (const [attribute, attributeRules] of Object.entries(this.normalizedRules)) {
+            // 🚀 Fix: Dynamically locate deeply nested object keys using dot notation
+            const value = (0, data_1.dataGet)(this.data, attribute);
+            const isEmpty = value === undefined || value === null || value === '';
+            // We handle bails in an isolation chain block per field
+            validationPromises.push((async () => {
+                let shouldBail = false;
+                for (const rawRule of attributeRules) {
+                    if (rawRule === 'bail') {
+                        shouldBail = true;
+                        continue;
+                    }
+                    const rule = typeof rawRule === 'string'
+                        ? this.resolveStringRule(rawRule)
+                        : rawRule;
+                    if (!rule)
+                        continue;
+                    const isImplicit = rule.isImplicit === true;
+                    if (isEmpty && !isImplicit)
+                        continue;
+                    let ruleFailed = false;
+                    const ruleName = typeof rawRule === 'string'
+                        ? rawRule.split(':')[0]
+                        : rule.constructor.name
+                            .toLowerCase()
+                            .replace('rule', '');
+                    // Wrap execution safely inside a Promise to manage potential async rules
+                    await Promise.resolve(rule.validate(attribute, value, (defaultMessage) => {
+                        ruleFailed = true;
+                        const customKeyWithAttr = `${attribute}.${ruleName}`;
+                        const finalMessagePattern = this.customMessages[customKeyWithAttr] ||
+                            this.customMessages[ruleName] ||
+                            defaultMessage;
+                        const localizedMessage = finalMessagePattern.replace(/:attribute/g, attribute);
+                        this.addError(attribute, localizedMessage);
+                    }));
+                    if (shouldBail && ruleFailed)
+                        break;
+                }
+            })());
+        }
+        // Await execution blocks concurrently across all fields
+        await Promise.all(validationPromises);
+        return this.passes();
+    }
+    /**
+     * Run the validation process synchronously across all rules.
+     * Automatically skips any complex asynchronous rule objects.
+     */
+    validateSync() {
+        this.errors = {};
+        for (const [attribute, attributeRules] of Object.entries(this.normalizedRules)) {
+            const value = (0, data_1.dataGet)(this.data, attribute);
+            const isEmpty = value === undefined || value === null || value === '';
+            let shouldBail = false;
+            for (const rawRule of attributeRules) {
+                if (rawRule === 'bail') {
+                    shouldBail = true;
+                    continue;
+                }
+                const rule = typeof rawRule === 'string'
+                    ? this.resolveStringRule(rawRule)
+                    : rawRule;
+                if (!rule)
+                    continue;
+                // Skip async promise rule instances safely in synchronous mode
+                if (
+                //@ts-ignore
+                typeof rule.validate(attribute, value, () => { })?.then ===
+                    'function') {
+                    continue;
+                }
+                const isImplicit = rule.isImplicit === true;
+                if (isEmpty && !isImplicit)
+                    continue;
+                let ruleFailed = false;
+                const ruleName = typeof rawRule === 'string'
+                    ? rawRule.split(':')[0]
+                    : rule.constructor.name
+                        .toLowerCase()
+                        .replace('rule', '');
+                rule.validate(attribute, value, (defaultMessage) => {
+                    ruleFailed = true;
+                    const customKeyWithAttr = `${attribute}.${ruleName}`;
+                    const finalMessagePattern = this.customMessages[customKeyWithAttr] ||
+                        this.customMessages[ruleName] ||
+                        defaultMessage;
+                    const localizedMessage = finalMessagePattern.replace(/:attribute/g, attribute);
+                    this.addError(attribute, localizedMessage);
+                });
+                if (shouldBail && ruleFailed)
+                    break;
+            }
+        }
+        return this.passes();
+    }
+    resolveStringRule(ruleString) {
+        const [ruleName, ...paramParts] = ruleString.split(':');
+        const paramString = paramParts.join(':');
+        const params = paramString ? paramString.split(',') : [];
+        if (ruleName === 'required')
+            return new RequiredRule_js_1.RequiredRule();
+        if (ruleName === 'email')
+            return new EmailRule_js_1.EmailRule();
+        if (ruleName === 'min')
+            return new MinRule_js_1.MinRule(parseInt(params[0], 10));
+        if (ruleName === 'max')
+            return new MaxRule_js_1.MaxRule(parseInt(params[0], 10));
+        if (Validator.extensions[ruleName]) {
+            return Validator.extensions[ruleName](params);
+        }
+        throw new Error(`Validation rule "${ruleName}" is not registered.`);
+    }
+    addError(attribute, message) {
+        if (!this.errors[attribute])
+            this.errors[attribute] = [];
+        this.errors[attribute].push(message);
+    }
+    passes() {
+        return Object.keys(this.errors).length === 0;
+    }
+    fails() {
+        return !this.passes();
+    }
+    invalid() {
+        return Object.keys(this.errors);
+    }
+    getError(name) {
+        return this.errors[name] ? this.errors[name] : null;
+    }
+    getErrors() {
+        return this.errors;
+    }
+}
+exports.Validator = Validator;

package/dist/contracts/Validation.d.ts

@@ -0,0 +1,5 @@
+export type FailCallback = (message: string) => void;
+export interface ValidationRule {
+    validate(attribute: string, value: unknown, fail: FailCallback): void;
+}
+export type CustomRuleClosureFactory = (params: string[]) => ValidationRule;

package/dist/contracts/Validation.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './contracts/Validation';
+export * from './rules/EmailRule';
+export * from './rules/MaxRule';
+export * from './rules/MinRule';
+export * from './rules/RequiredRule';
+export * from './Validator';
+export * from './integrations/react';
+export * from './integrations/vue';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contracts/Validation"), exports);
+__exportStar(require("./rules/EmailRule"), exports);
+__exportStar(require("./rules/MaxRule"), exports);
+__exportStar(require("./rules/MinRule"), exports);
+__exportStar(require("./rules/RequiredRule"), exports);
+__exportStar(require("./Validator"), exports);
+__exportStar(require("./integrations/react"), exports);
+__exportStar(require("./integrations/vue"), exports);

package/dist/integrations/react.d.ts

@@ -0,0 +1,29 @@
+import { ValidationRule } from '../contracts/Validation';
+/**
+ * SYNCHRONOUS HOOK: Instant keystroke validation
+ * Best for fast local layout constraints (min, max, email format, required)
+ */
+export declare function useReactFormValidator<T extends Record<string, unknown>>(initialData: T, rules: Record<keyof T | string, string | (string | ValidationRule)[]>, customMessages?: Record<string, string>): {
+    form: T;
+    setForm: import("react").Dispatch<import("react").SetStateAction<T>>;
+    handleChange: (field: keyof T, value: unknown) => void;
+    errors: Record<string, string[]>;
+    passes: boolean;
+    fails: boolean;
+    getError: (field: keyof T | string) => string[];
+};
+/**
+ * ASYNCHRONOUS HOOK: Explicit / Managed Lifecycle Validation
+ * Best for network checks (unique email lookup, coupon codes, server validations)
+ */
+export declare function useReactAsyncFormValidator<T extends Record<string, unknown>>(initialData: T, rules: Record<keyof T | string, string | (string | ValidationRule)[]>, customMessages?: Record<string, string>): {
+    form: T;
+    setForm: import("react").Dispatch<import("react").SetStateAction<T>>;
+    handleChange: (field: keyof T, value: unknown) => void;
+    validateAsync: (currentData?: T) => Promise<boolean>;
+    errors: Record<string, string[]>;
+    isPending: boolean;
+    passes: boolean;
+    fails: boolean;
+    getError: (field: keyof T | string) => string[];
+};

package/dist/integrations/react.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useReactFormValidator = useReactFormValidator;
+exports.useReactAsyncFormValidator = useReactAsyncFormValidator;
+const react_1 = require("react");
+const Validator_1 = require("../Validator");
+/**
+ * SYNCHRONOUS HOOK: Instant keystroke validation
+ * Best for fast local layout constraints (min, max, email format, required)
+ */
+function useReactFormValidator(initialData, rules, customMessages = {}) {
+    const [form, setForm] = (0, react_1.useState)(initialData);
+    // Run synchronously via useMemo so there is zero rendering delay
+    const validator = (0, react_1.useMemo)(() => {
+        const v = Validator_1.Validator.make(form, rules, customMessages);
+        // Explicitly runs sync rules; skips async lookups seamlessly on keystroke
+        v.validateSync();
+        return v;
+    }, [form, rules, customMessages]);
+    const handleChange = (0, react_1.useCallback)((field, value) => {
+        setForm((prev) => ({ ...prev, [field]: value }));
+    }, []);
+    return {
+        form,
+        setForm,
+        handleChange,
+        errors: validator.getErrors(),
+        passes: validator.passes(),
+        fails: validator.fails(),
+        getError: (field) => validator.getErrors()[field] || null,
+    };
+}
+/**
+ * ASYNCHRONOUS HOOK: Explicit / Managed Lifecycle Validation
+ * Best for network checks (unique email lookup, coupon codes, server validations)
+ */
+function useReactAsyncFormValidator(initialData, rules, customMessages = {}) {
+    const [form, setForm] = (0, react_1.useState)(initialData);
+    const [errors, setErrors] = (0, react_1.useState)({});
+    const [isPending, setIsPending] = (0, react_1.useState)(false);
+    const [isValid, setIsValid] = (0, react_1.useState)(true);
+    const handleChange = (0, react_1.useCallback)((field, value) => {
+        setForm((prev) => ({ ...prev, [field]: value }));
+    }, []);
+    // Call this explicitly on form submit or input blur events
+    const validateAsync = (0, react_1.useCallback)(async (currentData = form) => {
+        setIsPending(true);
+        const v = Validator_1.Validator.make(currentData, rules, customMessages);
+        await v.validate();
+        setErrors(v.getErrors());
+        setIsValid(v.passes());
+        setIsPending(false);
+        return v.passes();
+    }, [form, rules, customMessages]);
+    return {
+        form,
+        setForm,
+        handleChange,
+        validateAsync,
+        errors,
+        isPending,
+        passes: isValid,
+        fails: !isValid,
+        getError: (field) => errors[field] || null,
+    };
+}

package/dist/integrations/vue.d.ts

@@ -0,0 +1,23 @@
+import { ValidationRule } from '../contracts/Validation';
+/**
+ *SYNCHRONOUS COMPOSABLE: Instant Keystroke Validation
+ */
+export declare function useVueFormValidator<T extends Record<string, unknown>>(initialData: T, rules: Record<keyof T | string, string | (string | ValidationRule)[]>, customMessages?: Record<string, string>): {
+    form: import("vue").Reactive<T>;
+    errors: import("vue").ComputedRef<Record<string, string[]>>;
+    passes: import("vue").ComputedRef<boolean>;
+    fails: import("vue").ComputedRef<boolean>;
+    getError: (field: keyof T | string) => string[];
+};
+/**
+ * ASYNCHRONOUS COMPOSABLE: Controlled Server Validation
+ */
+export declare function useVueAsyncFormValidator<T extends Record<string, unknown>>(initialData: T, rules: Record<keyof T | string, string | (string | ValidationRule)[]>, customMessages?: Record<string, string>): {
+    form: import("vue").Reactive<T>;
+    validateAsync: () => Promise<boolean>;
+    errors: import("vue").Ref<Record<string, string[]>, Record<string, string[]>>;
+    isPending: import("vue").Ref<boolean, boolean>;
+    passes: import("vue").ComputedRef<boolean>;
+    fails: import("vue").ComputedRef<boolean>;
+    getError: (field: keyof T | string) => string[];
+};

package/dist/integrations/vue.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useVueFormValidator = useVueFormValidator;
+exports.useVueAsyncFormValidator = useVueAsyncFormValidator;
+const vue_1 = require("vue");
+const Validator_1 = require("../Validator");
+/**
+ *SYNCHRONOUS COMPOSABLE: Instant Keystroke Validation
+ */
+function useVueFormValidator(initialData, rules, customMessages = {}) {
+    const form = (0, vue_1.reactive)(initialData);
+    const validator = (0, vue_1.computed)(() => {
+        const v = Validator_1.Validator.make(form, rules, customMessages);
+        v.validateSync(); // 🚀 Uses the instant, synchronous evaluation loop!
+        return v;
+    });
+    return {
+        form,
+        errors: (0, vue_1.computed)(() => validator.value.getErrors()),
+        passes: (0, vue_1.computed)(() => validator.value.passes()),
+        fails: (0, vue_1.computed)(() => validator.value.fails()),
+        getError: (field) => validator.value.getErrors()[field] || null,
+    };
+}
+/**
+ * ASYNCHRONOUS COMPOSABLE: Controlled Server Validation
+ */
+function useVueAsyncFormValidator(initialData, rules, customMessages = {}) {
+    const form = (0, vue_1.reactive)(initialData);
+    const errors = (0, vue_1.ref)({});
+    const isPending = (0, vue_1.ref)(false);
+    const isValid = (0, vue_1.ref)(true);
+    // Controlled execution trigger
+    const validateAsync = async () => {
+        isPending.value = true;
+        const v = Validator_1.Validator.make(form, rules, customMessages);
+        await v.validate();
+        errors.value = v.getErrors();
+        isValid.value = v.passes();
+        isPending.value = false;
+        return v.passes();
+    };
+    return {
+        form,
+        validateAsync,
+        errors,
+        isPending,
+        passes: (0, vue_1.computed)(() => isValid.value),
+        fails: (0, vue_1.computed)(() => !isValid.value),
+        getError: (field) => errors.value[field] || null,
+    };
+}

package/dist/rules/EmailRule.d.ts

@@ -0,0 +1,4 @@
+import { FailCallback, ValidationRule } from '../contracts/Validation';
+export declare class EmailRule implements ValidationRule {
+    validate(attr: string, val: unknown, fail: FailCallback): void;
+}

package/dist/rules/EmailRule.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailRule = void 0;
+class EmailRule {
+    validate(attr, val, fail) {
+        if (typeof val === 'string' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val))
+            fail(`The :attribute must be a valid email address.`);
+    }
+}
+exports.EmailRule = EmailRule;

package/dist/rules/MaxRule.d.ts

@@ -0,0 +1,6 @@
+import { FailCallback, ValidationRule } from '../contracts/Validation';
+export declare class MaxRule implements ValidationRule {
+    private max;
+    constructor(max: number);
+    validate(attr: string, val: unknown, fail: FailCallback): void;
+}

package/dist/rules/MaxRule.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaxRule = void 0;
+class MaxRule {
+    max;
+    constructor(max) {
+        this.max = max;
+    }
+    validate(attr, val, fail) {
+        if (typeof val === 'string' && val.length > this.max)
+            fail(`The :attribute may not be greater than ${this.max} characters.`);
+    }
+}
+exports.MaxRule = MaxRule;

package/dist/rules/MinRule.d.ts

@@ -0,0 +1,6 @@
+import { FailCallback, ValidationRule } from '../contracts/Validation';
+export declare class MinRule implements ValidationRule {
+    private min;
+    constructor(min: number);
+    validate(attr: string, val: unknown, fail: FailCallback): void;
+}

package/dist/rules/MinRule.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MinRule = void 0;
+class MinRule {
+    min;
+    constructor(min) {
+        this.min = min;
+    }
+    validate(attr, val, fail) {
+        if (typeof val === 'string' && val.length < this.min)
+            fail(`The :attribute must be at least ${this.min} characters.`);
+    }
+}
+exports.MinRule = MinRule;

package/dist/rules/RequiredRule.d.ts

@@ -0,0 +1,6 @@
+import { FailCallback, ValidationRule } from '../contracts/Validation';
+/** Built-In Core Rule Fallbacks */
+export declare class RequiredRule implements ValidationRule {
+    isImplicit: boolean;
+    validate(attr: string, val: unknown, fail: FailCallback): void;
+}

package/dist/rules/RequiredRule.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequiredRule = void 0;
+/** Built-In Core Rule Fallbacks */
+class RequiredRule {
+    isImplicit = true;
+    validate(attr, val, fail) {
+        if (val === undefined || val === null || val === '')
+            fail(`The :attribute field is required.`);
+    }
+}
+exports.RequiredRule = RequiredRule;

package/dist/rules/UniqueEmailRule.d.ts

@@ -0,0 +1,5 @@
+import { FailCallback, ValidationRule } from '../contracts/Validation';
+export declare class UniqueEmailRule implements ValidationRule {
+    private checkDatabaseAvailability;
+    validate(attribute: string, value: unknown, fail: FailCallback): Promise<void>;
+}

package/dist/rules/UniqueEmailRule.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniqueEmailRule = void 0;
+class UniqueEmailRule {
+    // Simulate an async data call / API lookup query
+    async checkDatabaseAvailability(email) {
+        return new Promise((resolve) => {
+            setTimeout(() => {
+                const takenEmails = ['admin@site.com', 'hello@rbl.dev'];
+                resolve(!takenEmails.includes(email));
+            }, 400); // 400ms server delay simulation
+        });
+    }
+    async validate(attribute, value, fail) {
+        if (typeof value !== 'string')
+            return;
+        const isAvailable = await this.checkDatabaseAvailability(value);
+        if (!isAvailable) {
+            fail(`The :attribute has already been taken.`);
+        }
+    }
+}
+exports.UniqueEmailRule = UniqueEmailRule;

package/dist/utils/data.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Safely extracts a value from a deeply nested object using dot-notation.
+ * Example: dataGet({ user: { age: 25 } }, 'user.age') -> 25
+ */
+export declare function dataGet(target: Record<string, unknown>, path: string): unknown;

package/dist/utils/data.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataGet = dataGet;
+/**
+ * Safely extracts a value from a deeply nested object using dot-notation.
+ * Example: dataGet({ user: { age: 25 } }, 'user.age') -> 25
+ */
+function dataGet(target, path) {
+    return path.split('.').reduce((accumulator, key) => {
+        if (accumulator &&
+            typeof accumulator === 'object' &&
+            key in accumulator) {
+            return accumulator[key];
+        }
+        return undefined;
+    }, target);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@rbl-dev/validator-ts",
+	"version": "1.0.0",
+	"description": "A Laravel-inspired class-based pipe validator for TypeScript applications.",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "rimraf dist",
+		"prebuild": "npm run clean",
+		"build": "tsc",
+		"test": "vitest run"
+	},
+	"keywords": [
+		"laravel",
+		"validator",
+		"validation",
+		"typescript",
+		"react",
+		"vue"
+	],
+	"author": "Ruel B. Lapid",
+	"license": "MIT",
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0",
+		"vue": "^3.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"vue": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.2",
+		"@types/react": "^19.2.15",
+		"happy-dom": "^20.9.0",
+		"react": "^19.0.0",
+		"rimraf": "^5.0.0",
+		"typescript": "^5.0.0",
+		"vitest": "^4.1.7",
+		"vue": "^3.5.0"
+	}
+}