payload-guard-filter 1.6.2 → 1.8.0

package/README.md

@@ -1,174 +1,277 @@
-# payload-guard
-
-> Part of the [Professional Node.js Backend Toolkit](https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-)
-
-<p align="center">
-  <strong>🛡️ Lightweight, zero-dependency shape-based payload filtering and sanitization</strong>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/bundle%20size-%3C8KB-brightgreen" alt="Bundle Size">
-  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero Dependencies">
-  <img src="https://img.shields.io/badge/TypeScript-100%25-blue" alt="TypeScript">
-  <img src="https://img.shields.io/badge/Node.js-18%2B-green" alt="Node.js 18+">
-</p>
-
----
-
-## 🛡️ Workflow
-
-```mermaid
-graph LR
-    A[Request] --> B(Gatekeeper)
-    B --> C{Shape Check}
-    C -- Valid --> D[Redact & Clean]
-    C -- Invalid --> E[Strict Error / Fail Safe]
-    D --> F[Secure Response]
-    E --> F
-    F --> G((Metrics))
-```
-
----
-
-## ✨ Features
-
-- **Shape-based filtering** — Define what you want, auto-remove everything else
-- **Sensitive field protection** — `password`, `token`, `secret` automatically removed
-- **Zero dependencies** — Pure TypeScript, no external packages
-- **Universal** — Works in Node.js, Browser, React Native
-- **TypeScript-first** — Full type inference from shape definitions
-- **Blazing fast** — Compiled schemas for production performance
-- **Never crashes** — Graceful failure mode, production-safe
-
----
-
-## 📦 Installation
-
-```bash
-npm install payload-guard
-```
-
----
-
-## 🚀 Quick Start
-
-### Basic Usage
-
-```typescript
-import { guard } from 'payload-guard';
-
-// Define a shape
-const userShape = guard.shape({
-  id: 'number',
-  name: 'string',
-  email: 'string',
-});
-
-// Filter data
-const rawData = {
-  id: 1,
-  name: 'John Doe',
-  email: 'john@example.com',
-  password: 'secret123',      // ❌ Will be removed
-  internalNotes: 'VIP user',  // ❌ Will be removed
-};
-
-const safeData = userShape(rawData);
-// Result: { id: 1, name: 'John Doe', email: 'john@example.com' }
-```
-
-### Advanced Validation (v1.4+)
-
-```typescript
-const userShape = guard.shape({
-  email: guard.string().email().toLowerCase().trim(),
-  age: guard.number().min(18).max(100).default(18),
-  tags: guard.array(guard.string().min(2)),
-  role: guard.string().validate(v => ['admin', 'user'].includes(v)).default('user'),
-  bio: guard.string().max(200).optional(),
-});
-```
-
----
-
-## 📖 API Reference
-
-### `guard.string()`
-Creates a string builder with chained constraints:
-- `.min(length)` — Minimum character length
-- `.max(length)` — Maximum character length
-- `.email()` — Basic email validation
-- `.regex(pattern)` — Regex pattern match
-- `.trim()` — Auto-trim whitespace (Transformation)
-- `.toLowerCase()` / `.toUpperCase()` — Case transformation
-
-### `guard.number()`
-- `.min(value)` / `.max(value)` — Range validation
-- `.integer()` — Ensure number is an integer
-- `.positive()` — Shortcut for `.min(0)`
-
-### Common Builder Methods
-- `.required()` / `.optional()` — Toggle requirement
-- `.default(value)` — Value to use if field is missing or invalid
-- `.transform(fn)` — Custom transformation function
-- `.validate(fn)` — Custom validation function (return `false` to fail)
-
-### Field Aliasing & Mapping (v1.6+)
-
-Rename fields from your database to match your frontend API:
-
-```typescript
-const userShape = guard.shape({
-  id: guard.string().from('_id'), // Map DB _id to id
-  workTime: guard.number().from('totalWorkTimeMs').transform(v => v / 1000),
-  name: 'string',
-});
-
-// Input: { _id: '123', totalWorkTimeMs: 5000, name: 'Sannu' }
-// Output: { id: '123', workTime: 5, name: 'Sannu' }
-```
-
----
-
-## 🛡️ "Never Crash" Policy
-
-Payload Guard is designed for mission-critical enterprise environments where uptime is non-negotiable.
-
-- **Circular Reference Safety**: Automatically detects and handles circular objects without infinite loops or stack overflows.
-- **Hook Isolation**: Custom `.transform()` and `.validate()` callbacks are wrapped in internal try/catch blocks. If your code fails, the library logs the error and safely continues using fallback values.
-- **Middleware Fail-Open**: If internal filtering logic hits an unexpected edge case, `failOpen: true` ensures the original request/response still reaches its destination.
-
----
-
-## ⚡ Performance
-
-| Benchmark | ops/sec | avg (ms) |
-|-----------|---------|----------|
-| **Small payload** (5 fields) | 449,365 | **0.0022ms** |
-| **Medium payload** (50 posts) | 7,791 | **0.1284ms** |
-| **Large payload** (1000 users) | 246 | **4.0724ms** |
-
-> **Memory Usage**: ~121 MB Heap Used (Stable)
-
----
-
-## 🛡️ Fail-Safe Design
-
-Built for production reliability:
-- **Isolation**: Monitoring failures **never** break your API responses. If a storage adapter or plugin crashes, the error is caught and logged, while the user's request continues normally.
-- **Async-Only**: All processing is non-blocking to ensure zero impact on event loop latency.
-
----
-### ⛑️ Maintained actively.
-**Bug fixes usually within 24–48 hours.**
-
----
-## 📄 License
-
-MIT
-
----
-
-<p align="center">
-  Made with ❤️ for safer APIs
-</p>
+# payload-guard
+
+> Part of the [Professional Node.js Backend Toolkit](https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-)
+
+<p align="center">
+  <strong>🛡️ Lightweight, zero-dependency shape-based payload filtering and sanitization</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/bundle%20size-%3C8KB-brightgreen" alt="Bundle Size">
+  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero Dependencies">
+  <img src="https://img.shields.io/badge/TypeScript-100%25-blue" alt="TypeScript">
+  <img src="https://img.shields.io/badge/Node.js-18%2B-green" alt="Node.js 18+">
+</p>
+
+---
+
+## 🛡️ Workflow
+
+```mermaid
+graph LR
+    A[Request] --> B(Gatekeeper)
+    B --> C{Shape Check}
+    C -- Valid --> D[Redact & Clean]
+    C -- Invalid --> E[Strict Error / Fail Safe]
+    D --> F[Secure Response]
+    E --> F
+    F --> G((Metrics))
+```
+
+---
+
+## ✨ Features
+
+- **Shape-based filtering** — Define what you want, auto-remove everything else
+- **Sensitive field protection** — `password`, `token`, `secret` automatically removed
+- **Zero dependencies** — Pure TypeScript, no external packages
+- **Universal** — Works in Node.js, Browser, React Native
+- **TypeScript-first** — Full type inference from shape definitions
+- **Blazing fast** — Compiled schemas for production performance
+- **Never crashes** — Graceful failure mode, production-safe
+
+---
+
+## 📦 Installation
+
+```bash
+npm install payload-guard
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```typescript
+import { guard } from 'payload-guard';
+
+// Define a shape
+const userShape = guard.shape({
+  id: 'number',
+  name: 'string',
+  email: 'string',
+});
+
+// Filter data
+const rawData = {
+  id: 1,
+  name: 'John Doe',
+  email: 'john@example.com',
+  password: 'secret123',      // ❌ Will be removed
+  internalNotes: 'VIP user',  // ❌ Will be removed
+};
+
+const safeData = userShape(rawData);
+// Result: { id: 1, name: 'John Doe', email: 'john@example.com' }
+```
+
+### Advanced Validation (v1.4+)
+
+```typescript
+const userShape = guard.shape({
+  email: guard.string().email().toLowerCase().trim(),
+  age: guard.number().min(18).max(100).default(18),
+  tags: guard.array(guard.string().min(2)),
+  role: guard.string().validate(v => ['admin', 'user'].includes(v)).default('user'),
+  bio: guard.string().max(200).optional(),
+});
+```
+
+### Nested Object Validation (v1.7+)
+
+Define nested shapes for deep object validation:
+
+```typescript
+const userShape = guard.shape({
+  id: 'number',
+  profile: {
+    name: 'string',
+    email: guard.string().email(),
+    age: guard.number().min(18),
+    address: {
+      street: 'string',
+      city: 'string',
+      zipCode: guard.string().regex(/^\d{5}(-\d{4})?$/),
+    },
+  },
+  posts: guard.array({
+    id: 'number',
+    title: 'string',
+    tags: guard.array('string'),
+  }),
+});
+
+const input = {
+  id: 1,
+  profile: {
+    name: 'John',
+    email: 'john@example.com',
+    age: 30,
+    address: {
+      street: '123 Main St',
+      city: 'NYC',
+      zipCode: '10001',
+    },
+  },
+  posts: [
+    { id: 1, title: 'Hello', tags: ['intro'] },
+  ],
+};
+
+const result = userShape(input);
+// Filters all nested levels automatically
+```
+
+### Custom Error Messages (v1.7+)
+
+Add per-field custom error messages:
+
+```typescript
+const userShape = guard.shape({
+  email: guard
+    .string()
+    .email()
+    .error('Please provide a valid email address'),
+  
+  username: guard
+    .string()
+    .min(5)
+    .error((value, field) => `${field} must be at least 5 characters`),
+  
+  age: guard
+    .number()
+    .min(18)
+    .max(100)
+    .errorCodes({ min: 'AGE_TOO_YOUNG', max: 'AGE_TOO_OLD' }),
+});
+
+// Collect validation errors
+const { compile } = require('payload-guard');
+const errors = [];
+const validator = compile(
+  { email: { type: 'string', email: true } },
+  { collectErrors: true, _errors: errors }
+);
+
+validator({ email: 'invalid' });
+// errors: [{ field: 'email', message: '...', code: 'email' }]
+```
+
+---
+
+## 📖 API Reference
+
+### `guard.string()`
+Creates a string builder with chained constraints:
+- `.min(length)` — Minimum character length
+- `.max(length)` — Maximum character length
+- `.email()` — Basic email validation
+- `.regex(pattern)` — Regex pattern match
+- `.trim()` — Auto-trim whitespace (Transformation)
+- `.toLowerCase()` / `.toUpperCase()` — Case transformation
+
+### `guard.number()`
+- `.min(value)` / `.max(value)` — Range validation
+- `.integer()` — Ensure number is an integer
+- `.positive()` — Shortcut for `.min(0)`
+
+### Common Builder Methods
+- `.required()` / `.optional()` — Toggle requirement
+- `.default(value)` — Value to use if field is missing or invalid
+- `.transform(fn)` — Custom transformation function
+- `.validate(fn)` — Custom validation function (return `false` to fail)
+- `.error(message)` — Custom error message (string or function) **(v1.7+)**
+- `.errorCodes(codes)` — Custom error codes for validations **(v1.7+)**
+
+### New in v1.7+
+
+**Nested Object Support:**
+- Define nested shapes as plain objects: `{ profile: { name: 'string', email: 'string' } }`
+- Arrays with nested objects: `guard.array({ id: 'number', name: 'string' })`
+- Deep nesting supported at any level
+
+**Custom Error Messages:**
+- `.error('Custom message')` — Static error message
+- `.error((value, field) => \`${field} is invalid\`)` — Dynamic error message
+- `.errorCodes({ min: 'TOO_SHORT', email: 'BAD_EMAIL' })` — Error codes
+
+**Error Collection:**
+```typescript
+const { compile } = require('payload-guard');
+const errors = [];
+const validator = compile(shape, { collectErrors: true, _errors: errors });
+validator(data);
+// errors array populated with { field, message, code, value }
+```
+
+### Field Aliasing & Mapping (v1.6+)
+
+Rename fields from your database to match your frontend API:
+
+```typescript
+const userShape = guard.shape({
+  id: guard.string().from('_id'), // Map DB _id to id
+  workTime: guard.number().from('totalWorkTimeMs').transform(v => v / 1000),
+  name: 'string',
+});
+
+// Input: { _id: '123', totalWorkTimeMs: 5000, name: 'Sannu' }
+// Output: { id: '123', workTime: 5, name: 'Sannu' }
+```
+
+---
+
+## 🛡️ "Never Crash" Policy
+
+Payload Guard is designed for mission-critical enterprise environments where uptime is non-negotiable.
+
+- **Circular Reference Safety**: Automatically detects and handles circular objects without infinite loops or stack overflows.
+- **Hook Isolation**: Custom `.transform()` and `.validate()` callbacks are wrapped in internal try/catch blocks. If your code fails, the library logs the error and safely continues using fallback values.
+- **Middleware Fail-Open**: If internal filtering logic hits an unexpected edge case, `failOpen: true` ensures the original request/response still reaches its destination.
+
+---
+
+## ⚡ Performance
+
+| Benchmark | ops/sec | avg (ms) |
+|-----------|---------|----------|
+| **Small payload** (5 fields) | 449,365 | **0.0022ms** |
+| **Medium payload** (50 posts) | 7,791 | **0.1284ms** |
+| **Large payload** (1000 users) | 246 | **4.0724ms** |
+
+> **Memory Usage**: ~121 MB Heap Used (Stable)
+
+---
+
+## 🛡️ Fail-Safe Design
+
+Built for production reliability:
+- **Isolation**: Monitoring failures **never** break your API responses. If a storage adapter or plugin crashes, the error is caught and logged, while the user's request continues normally.
+- **Async-Only**: All processing is non-blocking to ensure zero impact on event loop latency.
+
+---
+### ⛑️ Maintained actively.
+**Bug fixes usually within 24–48 hours.**
+
+---
+## 📄 License
+
+MIT
+
+---
+
+<p align="center">
+  Made with ❤️ for safer APIs
+</p>

package/dist/core/compiler.d.ts

@@ -1,4 +1,4 @@
-import { ShapeDescriptor, ArrayShapeDescriptor, CompiledFilter } from './types';
+import { ShapeDescriptor, ArrayShapeDescriptor, CompiledFilter, ValidationError } from './types';
 interface CompileOptions {
     sensitive?: string[];
     dev?: boolean;
@@ -9,6 +9,10 @@ interface CompileOptions {
     maxArrayLength?: number;
     /** Parent path for nested field warnings (internal) */
     _parentPath?: string;
+    /** Collect validation errors */
+    _errors?: ValidationError[];
+    /** Collect errors flag */
+    collectErrors?: boolean;
 }
 /**
  * Compile a shape descriptor into an optimized filter function

package/dist/core/compiler.js

@@ -25,35 +25,118 @@ function compile(shape, opts = {}) {
         const config = shape.__isBuilder ? shape.config : shape;
         const primType = config.type;
         const defaultVal = config.default;
+        const fieldPath = opts._parentPath || 'field';
         return (value) => {
             let val = value == null ? (defaultVal ?? value) : (0, sanitizer_1.coercePrimitive)(primType, value);
+            let error = null;
+            // Helper to create error
+            const createError = (message, code) => {
+                const customMsg = typeof config.errorMessage === 'function'
+                    ? config.errorMessage(val, fieldPath)
+                    : config.errorMessage;
+                return {
+                    field: fieldPath,
+                    message: customMsg || message,
+                    code: config.errorCodes?.[code] || code,
+                    value: val,
+                };
+            };
+            // Required check
+            if (config.required && val == null) {
+                error = createError(`${fieldPath} is required`, 'required');
+                if (opts.collectErrors && opts._errors) {
+                    opts._errors.push(error);
+                }
+                return defaultVal ?? undefined;
+            }
             // Perform validation and transformation if value is not null
             if (val != null) {
+                // Type check
+                if (opts.strict) {
+                    const typeValid = (primType === 'string' && typeof val === 'string') ||
+                        (primType === 'number' && typeof val === 'number') ||
+                        (primType === 'boolean' && typeof val === 'boolean') ||
+                        (primType === 'any');
+                    if (!typeValid) {
+                        error = createError(`${fieldPath} must be of type ${primType}`, 'type');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
+                        return defaultVal ?? undefined;
+                    }
+                }
                 // String validations
                 if (primType === 'string' && typeof val === 'string') {
                     val = (0, sanitizer_1.trimString)(val);
-                    if (config.min !== undefined && val.length < config.min)
+                    if (config.min !== undefined && val.length < config.min) {
+                        error = createError(`${fieldPath} must be at least ${config.min} characters`, 'min');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
                         return defaultVal ?? undefined;
-                    if (config.max !== undefined && val.length > config.max)
+                    }
+                    if (config.max !== undefined && val.length > config.max) {
+                        error = createError(`${fieldPath} must be at most ${config.max} characters`, 'max');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
                         return defaultVal ?? undefined;
-                    if (config.regex && !config.regex.test(val))
+                    }
+                    if (config.regex && !config.regex.test(val)) {
+                        error = createError(`${fieldPath} does not match required pattern`, 'pattern');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
                         return defaultVal ?? undefined;
+                    }
                     if (config.email) {
                         const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-                        if (!emailRegex.test(val))
+                        if (!emailRegex.test(val)) {
+                            error = createError(`${fieldPath} must be a valid email address`, 'email');
+                            if (opts.collectErrors && opts._errors) {
+                                opts._errors.push(error);
+                            }
                             return defaultVal ?? undefined;
+                        }
                     }
                 }
                 // Number validations
                 if (primType === 'number' && typeof val === 'number') {
-                    if (config.min !== undefined && val < config.min)
+                    if (config.min !== undefined && val < config.min) {
+                        error = createError(`${fieldPath} must be at least ${config.min}`, 'min');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
                         return defaultVal ?? undefined;
-                    if (config.max !== undefined && val > config.max)
+                    }
+                    if (config.max !== undefined && val > config.max) {
+                        error = createError(`${fieldPath} must be at most ${config.max}`, 'max');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
                         return defaultVal ?? undefined;
+                    }
                 }
                 // Custom validation
-                if (config.validate && !config.validate(val)) {
-                    return defaultVal ?? undefined;
+                if (config.validate) {
+                    try {
+                        if (!config.validate(val)) {
+                            error = createError(`${fieldPath} failed validation`, 'custom');
+                            if (opts.collectErrors && opts._errors) {
+                                opts._errors.push(error);
+                            }
+                            return defaultVal ?? undefined;
+                        }
+                    }
+                    catch (e) {
+                        if (opts.dev)
+                            (opts.logger ?? console.warn)('[payload-guard] validation error: ' + String(e), 'warn');
+                        error = createError(`${fieldPath} validation threw an error`, 'custom');
+                        if (opts.collectErrors && opts._errors) {
+                            opts._errors.push(error);
+                        }
+                        return defaultVal ?? undefined;
+                    }
                 }
                 // Transformation
                 if (config.transform) {
@@ -97,8 +180,17 @@ function compile(shape, opts = {}) {
     if (isArrayShape(shape)) {
         const itemFn = compile(shape.item, { ...opts, _parentPath: (opts._parentPath || '') + '[]' });
         return (value) => {
-            if (!Array.isArray(value))
+            if (!Array.isArray(value)) {
+                if (opts.collectErrors && opts._errors) {
+                    opts._errors.push({
+                        field: opts._parentPath || 'array',
+                        message: `${opts._parentPath || 'array'} must be an array`,
+                        code: 'type',
+                        value: value,
+                    });
+                }
                 return [];
+            }
             // Memory safety: slice array if maxArrayLength is set
             let arr = value;
             if (opts.maxArrayLength && arr.length > opts.maxArrayLength) {
@@ -108,7 +200,7 @@ function compile(shape, opts = {}) {
                 }
                 arr = arr.slice(0, opts.maxArrayLength);
             }
-            return arr.map(item => {
+            return arr.map((item, idx) => {
                 try {
                     return itemFn(item);
                 }
@@ -121,7 +213,7 @@ function compile(shape, opts = {}) {
             }).filter(v => v !== undefined);
         };
     }
-    // Object shape - compile each field
+    // Object shape - compile each field (nested object support)
     const fieldFilters = {};
     const shapeObj = shape;
     for (const key of Object.keys(shapeObj)) {
@@ -139,7 +231,33 @@ function compile(shape, opts = {}) {
             }
             continue;
         }
-        fieldFilters[key] = compile(shapeObj[key], { ...opts, _parentPath: (opts._parentPath ? opts._parentPath + '.' : '') + key });
+        const fieldDescriptor = shapeObj[key];
+        // Check if this is a FieldConfig with nested shape
+        if (isFieldConfig(fieldDescriptor)) {
+            const config = fieldDescriptor.__isBuilder
+                ? fieldDescriptor.config
+                : fieldDescriptor;
+            if (config.shape) {
+                // Nested object shape - compile both the field validator and nested shape
+                const fieldValidator = compile(fieldDescriptor, { ...opts, _parentPath: (opts._parentPath ? opts._parentPath + '.' : '') + key });
+                const nestedShapeFn = compile(config.shape, { ...opts, _parentPath: (opts._parentPath ? opts._parentPath + '.' : '') + key });
+                fieldFilters[key] = (value) => {
+                    const validated = fieldValidator(value);
+                    if (validated == null)
+                        return validated;
+                    // Apply nested shape filtering
+                    return nestedShapeFn(validated);
+                };
+            }
+            else {
+                // Simple field - just compile the field validator
+                fieldFilters[key] = compile(fieldDescriptor, { ...opts, _parentPath: (opts._parentPath ? opts._parentPath + '.' : '') + key });
+            }
+        }
+        else {
+            // Regular shape descriptor (primitive, nested object, array, etc.)
+            fieldFilters[key] = compile(fieldDescriptor, { ...opts, _parentPath: (opts._parentPath ? opts._parentPath + '.' : '') + key });
+        }
     }
     return (value) => {
         if (value == null || typeof value !== 'object')

package/dist/core/filter.js

@@ -78,6 +78,8 @@ function createBuilder(type) {
         transform(fn) { config.transform = fn; return builder; },
         validate(fn) { config.validate = fn; return builder; },
         from(key) { config.from = key; return builder; },
+        error(msg) { config.errorMessage = msg; return builder; },
+        errorCodes(codes) { config.errorCodes = codes; return builder; },
     };
     Object.setPrototypeOf(builder, proto);
     if (type === 'string') {

package/dist/core/types.d.ts

@@ -3,6 +3,17 @@
  * Provides strong TypeScript inference from shape definitions
  */
 export type PrimitiveType = 'string' | 'number' | 'boolean' | 'any';
+export interface ValidationError {
+    field: string;
+    message: string;
+    code?: string;
+    value?: unknown;
+}
+export interface ValidationResult<T = unknown> {
+    data: T;
+    errors: ValidationError[];
+    valid: boolean;
+}
 export interface FieldConfig<T extends PrimitiveType = PrimitiveType> {
     type: T;
     required?: boolean;
@@ -16,6 +27,20 @@ export interface FieldConfig<T extends PrimitiveType = PrimitiveType> {
     from?: string;
     /** Custom validation function: return false if invalid */
     validate?: (v: any) => boolean;
+    /** Custom error message for validation failures */
+    errorMessage?: string | ((value: unknown, field: string) => string);
+    /** Error codes for different validation failures */
+    errorCodes?: {
+        required?: string;
+        type?: string;
+        min?: string;
+        max?: string;
+        pattern?: string;
+        email?: string;
+        custom?: string;
+    };
+    /** Nested shape for object validation */
+    shape?: ShapeDescriptor;
 }
 export interface ShapeBuilder<T extends PrimitiveType> {
     (value: unknown): InferPrimitive<T>;
@@ -27,6 +52,10 @@ export interface ShapeBuilder<T extends PrimitiveType> {
     transform(fn: (v: InferPrimitive<T>) => any): ShapeBuilder<T>;
     validate(fn: (v: InferPrimitive<T>) => boolean): ShapeBuilder<T>;
     from(key: string): ShapeBuilder<T>;
+    /** Set custom error message */
+    error(msg: string | ((v: unknown, field: string) => string)): ShapeBuilder<T>;
+    /** Set error codes */
+    errorCodes(codes: FieldConfig<T>['errorCodes']): ShapeBuilder<T>;
 }
 export interface StringBuilder extends ShapeBuilder<'string'> {
     min(len: number): StringBuilder;
@@ -36,18 +65,29 @@ export interface StringBuilder extends ShapeBuilder<'string'> {
     trim(): StringBuilder;
     toLowerCase(): StringBuilder;
     toUpperCase(): StringBuilder;
+    error(msg: string | ((v: unknown, field: string) => string)): StringBuilder;
+    errorCodes(codes: FieldConfig<'string'>['errorCodes']): StringBuilder;
 }
 export interface NumberBuilder extends ShapeBuilder<'number'> {
     min(val: number): NumberBuilder;
     max(val: number): NumberBuilder;
     integer(): NumberBuilder;
     positive(): NumberBuilder;
+    error(msg: string | ((v: unknown, field: string) => string)): NumberBuilder;
+    errorCodes(codes: FieldConfig<'number'>['errorCodes']): NumberBuilder;
 }
 export interface BooleanBuilder extends ShapeBuilder<'boolean'> {
+    error(msg: string | ((v: unknown, field: string) => string)): BooleanBuilder;
+    errorCodes(codes: FieldConfig<'boolean'>['errorCodes']): BooleanBuilder;
 }
 export interface AnyBuilder extends ShapeBuilder<'any'> {
+    error(msg: string | ((v: unknown, field: string) => string)): AnyBuilder;
+    errorCodes(codes: FieldConfig<'any'>['errorCodes']): AnyBuilder;
 }
 export type InferPrimitive<T extends PrimitiveType> = T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'any' ? unknown : never;
+export type InferFieldConfig<T extends FieldConfig> = T extends {
+    shape: infer S;
+} ? InferShape<S & ShapeDescriptor> : T extends FieldConfig<infer P> ? InferPrimitive<P> : unknown;
 export type ShapeDescriptor = PrimitiveType | FieldConfig | {
     [key: string]: ShapeDescriptor;
 } | ArrayShapeDescriptor | CompiledFilter | ShapeBuilder<any>;
@@ -56,7 +96,9 @@ export interface ArrayShapeDescriptor {
     readonly item: ShapeDescriptor;
 }
 export type CompiledFilter<T = unknown> = (value: unknown) => T;
-export type InferShape<S extends ShapeDescriptor> = S extends PrimitiveType ? InferPrimitive<S> : S extends FieldConfig<infer T> ? InferPrimitive<T> : S extends ArrayShapeDescriptor ? InferShape<S['item']>[] : S extends CompiledFilter<infer T> ? T : S extends object ? {
+export type InferShape<S extends ShapeDescriptor> = S extends PrimitiveType ? InferPrimitive<S> : S extends FieldConfig<infer T> ? InferFieldConfig<S & FieldConfig<T>> : S extends ArrayShapeDescriptor ? InferShape<S['item']>[] : S extends CompiledFilter<infer T> ? T : S extends {
+    [key: string]: any;
+} ? {
     [K in keyof S]: InferShape<S[K] & ShapeDescriptor>;
 } : unknown;
 export interface GuardConfig {
@@ -96,6 +138,8 @@ export interface GuardConfig {
     skipNonSerializable?: boolean;
     /** Log names of fields removed during filtering (debug mode) */
     logRemovedFields?: boolean;
+    /** Collect validation errors instead of silently failing */
+    collectErrors?: boolean;
 }
 export interface GuardMiddlewareOptions extends GuardConfig {
     /** Sanitize request body */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-guard-filter",
-  "version": "1.6.2",
+  "version": "1.8.0",
   "description": "Lightweight, zero-dependency shape-based payload filtering and sanitization for Node.js and browser",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -86,7 +86,7 @@
     "url": "https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-.git"
   },
   "bugs": {
-    "url": "https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-/issues"
+    "url": "https://mypackagedoc.vercel.app/package/payload-guard-filter"
   },
-  "homepage": "https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-#readme"
+  "homepage": "https://mypackagedoc.vercel.app/package/payload-guard-filter"
 }