payload-guard-filter 1.3.1 → 1.4.0

package/README.md

@@ -1,10 +1,11 @@
 # 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">
@@ -45,10 +46,6 @@ graph LR
 
 ```bash
 npm install payload-guard
-# or
-yarn add payload-guard
-# or
-pnpm add payload-guard
 ```
 
 ---
@@ -80,318 +77,67 @@ const safeData = userShape(rawData);
 // Result: { id: 1, name: 'John Doe', email: 'john@example.com' }
 ```
 
-### Express Middleware
+### Advanced Validation (v1.4+)
 
 ```typescript
-import express from 'express';
-import { guard, guardMiddleware } from 'payload-guard';
-
-const app = express();
-app.use(express.json());
-
-// Apply middleware
-app.use(guardMiddleware({
-  sanitizeBody: true,
-  sensitiveFields: ['password', 'token'],
-  devMode: process.env.NODE_ENV === 'development',
-}));
-
 const userShape = guard.shape({
-  id: 'number',
-  name: 'string',
-  email: 'string',
-});
-
-app.post('/users', (req, res) => {
-  const user = createUser(req.body);
-  res.guardJson(userShape, user);  // ✅ Filtered response
+  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(),
 });
-
-app.listen(3000);
-```
-
-### Frontend Usage
-
-```typescript
-import { validateShape } from 'payload-guard/client';
-
-const userShape = { id: 'number', name: 'string', email: 'string' };
-const validateUser = validateShape(userShape, { devMode: true });
-
-// Fetch and validate
-const user = await fetch('/api/user')
-  .then(r => r.json())
-  .then(validateUser);
-
-// Dev mode warnings:
-// ⚠️ Unexpected field "createdAt" in response
-// ⚠️ Missing field "email" in response
 ```
 
 ---
 
 ## 📖 API Reference
 
-### `guard.shape(descriptor, options?)`
-
-Create a filter function from a shape descriptor.
-
-```typescript
-const userShape = guard.shape({
-  id: 'number',
-  name: 'string',
-  email: 'string',
-  role: { type: 'string', default: 'user' },
-});
-```
-
-**Supported types:**
-- `'string'` — String values (auto-trimmed)
-- `'number'` — Numeric values
-- `'boolean'` — Boolean values
-- `'any'` — Any value (no transformation)
-
-**Field config options:**
-```typescript
-{
-  type: 'string',
-  required: false,  // Optional field
-  default: 'value', // Default value if missing
-}
-```
-
-### `guard.array(itemShape)`
-
-Create an array filter.
-
-```typescript
-const postsShape = guard.shape({
-  posts: guard.array({
-    id: 'number',
-    title: 'string',
-  }),
-});
-```
-
-### `guardMiddleware(options)`
-
-Express middleware for automatic sanitization.
-
-```typescript
-app.use(guardMiddleware({
-  sanitizeBody: true,       // Filter req.body
-  requestShape: userShape,  // Shape for request body
-  filterResponse: true,     // Auto-filter all res.json()
-  sensitiveFields: [],      // Extra sensitive field names
-  devMode: false,           // Enable dev warnings
-}));
-```
-
-### `res.guardJson(shape, data)`
-
-Added by middleware — send filtered JSON response.
-
-```typescript
-app.get('/user', (req, res) => {
-  res.guardJson(userShape, userData);
-});
-```
-
-### `validateShape(shape, options?)` (Client)
-
-Create a validator for frontend use.
-
-```typescript
-import { validateShape } from 'payload-guard/client';
-
-const validate = validateShape(userShape, {
-  devMode: true,   // Log warnings
-  strict: false,   // Throw on errors
-});
-```
-
----
-
-## 🔒 Security
-
-### Default Sensitive Fields
-
-These fields are **automatically removed** from all outputs:
-
-- `password`, `password_hash`, `password_reset_token`, `pwd`
-- `token`, `access_token`, `refresh_token`, `auth_token`
-- `secret`, `api_key`, `private_key`, `encryption_key`
-- `authorization`, `auth`, `session_id`
-- `ssn`, `credit_card`, `cvv`, `card_number`
-
-### Add Custom Sensitive Fields
-
-```typescript
-guard.config({
-  sensitiveFields: ['internal_id', 'admin_notes', 'salary'],
-});
-```
-
----
-
-## 🏗️ Nested Objects & Arrays
-
-```typescript
-const postShape = guard.shape({
-  id: 'number',
-  title: 'string',
-  author: guard.shape({
-    id: 'number',
-    name: 'string',
-    // author.password, author.token auto-removed!
-  }),
-  tags: guard.array({
-    id: 'number',
-    name: 'string',
-  }),
-  comments: guard.array(
-    guard.shape({
-      id: 'number',
-      text: 'string',
-      user: guard.shape({
-        id: 'number',
-        name: 'string',
-      }),
-    })
-  ),
-});
-```
+### `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)
 
 ---
 
 ## ⚡ Performance
 
-| Operation | payload-guard | Zod | JOI |
-|-----------|---------------|-----|-----|
-| Simple filter | 0.05ms | 0.8ms | 1.2ms |
-| Nested (3 levels) | 0.15ms | 2.5ms | 3.8ms |
-| Array (100 items) | 1.2ms | 15ms | 22ms |
-| Bundle size | <8KB | 50KB+ | 70KB+ |
-| Dependencies | 0 | 5+ | 10+ |
-
----
-
-## 🏢 Enterprise Features (v1.2.0+)
+| 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** |
 
-Designed for high-performance production systems, Payload Guard includes enterprise-grade features for security, observability, and performance.
-
-### 🛡️ 1. Header Sanitization
-Automatically remove sensitive headers like `Authorization` or `Cookie` before your business logic handles the request.
-```ts
-app.use(guardMiddleware({
-  sanitizeHeaders: true,
-  sensitiveHeaders: ['x-api-key', 'session-id'] // optional extras
-}));
-```
-
-### 🧠 2. Memory Safety (`maxArrayLength`)
-Prevent DoS attacks via extremely large arrays by automatically truncating them to a safe limit.
-```ts
-const shape = guard.shape({ items: guard.array('string') }, { maxArrayLength: 1000 });
-```
-
-### ⚡ 3. Async Safety (`maxPayloadSize`)
-Avoid processing massive JSON payloads that could block the event loop.
-```ts
-app.use(guardMiddleware({
-  maxPayloadSize: 1024 * 512, // 512KB
-  skipLargePayload: true       // Skips filtering if too large
-}));
-```
-
-### ⏱️ 4. Middleware Timing Stats
-Track exactly how much time Payload Guard adds to your request cycle.
-```
-[payload-guard] [POST] /api/data: reduced 15KB -> 4KB (73%) in 0.12ms
-```
-
-### 📊 5. Human-Readable Metrics
-Visibility into bandwidth savings with formatted byte sizes and percentages.
-
-### 🛠️ 6. CLI Type Sync
-Generate frontend TypeScript types from your backend shapes with one command.
-```bash
-npx payload-guard sync
-```
-
-### ⚠️ 7. Route-Aware Dev Warnings
-Dev mode warnings now include the full method, path, and nested field locations (e.g., `user.profile.password`) for faster debugging.
-
-### 🛣️ 8. Ignore Routes
-Skip processing for high-volume or incompatible routes like file uploads or health checks.
-```ts
-app.use(guardMiddleware({ ignoreRoutes: ['/health', '/upload'] }));
-```
-
-### 🏗️ 9. Shared Schemas & Examples
-Built-in support for reusable schemas across your monorepo and a `examples/real-world` project for reference.
-
-### 🚀 10. Performance Benchmarks
-A dedicated benchmark suite to verify sub-millisecond overhead. `npm run benchmark`.
+> **Memory Usage**: ~121 MB Heap Used (Stable)
 
 ---
 
-## 🏗️ Production Hardening
-
-### 🛡️ Fail-Safe Mode (`failOpen`)
-In production, we prioritize availability. If filtering fails for any reason, `failOpen: true` (default) ensures the original data is sent instead of breaking the request.
+## 🛡️ Fail-Safe Design
 
-### 🚫 Non-Serializable Protection
-Payload Guard automatically detects and skips `Buffer`, `Stream`, `File`, and `Blob` objects to prevent crashes and performance bottlenecks.
-
-### 🔍 Detailed Debug Logs
-Enable `logRemovedFields: true` to see exactly which fields were stripped from your payloads:
-`[payload-guard] /api/user Removed fields: password, token, internal_id`
+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.
 
 ---
-
-## 🌐 Multi-Framework Support
-
-The core is zero-dependency and framework-agnostic. Use it anywhere:
-
-### Hono / Cloudflare Workers
-```ts
-app.post('/user', async (c) => {
-  const body = await c.req.json();
-  return c.json(userShape(body));
-});
-```
-
-### Fastify
-```ts
-fastify.post('/user', (req, reply) => {
-  reply.send(userShape(req.body));
-});
-```
-
----
-
-## 🛑 When NOT to use
-
-Payload Guard is optimized for JSON APIs. It is **not** suitable for:
-1. **Binary Data**: PDFs, Images, or raw Buffers.
-2. **File Streams**: Use `multer` or similar for multipart data.
-3. **Heavy Computation**: Don't use it on payloads > 10MB without adjusting `maxPayloadSize`.
-
----
-
-## 🛠️ CLI
-
-```bash
-npx payload-guard init
-```
-
-Creates example files in your project:
-- `shapes.ts` — Example shape definitions
-- `server-example.ts` — Express middleware setup
+### ⛑️ Maintained actively.
+**Bug fixes usually within 24–48 hours.**
 
 ---
-
 ## 📄 License
 
 MIT

package/dist/core/compiler.js

@@ -20,6 +20,55 @@ function compile(shape, opts = {}) {
     if (isShapeFunction(shape)) {
         return shape.compile;
     }
+    // Field config or Builder
+    if (isFieldConfig(shape)) {
+        const config = shape.__isBuilder ? shape.config : shape;
+        const primType = config.type;
+        const defaultVal = config.default;
+        return (value) => {
+            let val = value == null ? (defaultVal ?? value) : (0, sanitizer_1.coercePrimitive)(primType, value);
+            // Perform validation and transformation if value is not null
+            if (val != null) {
+                // String validations
+                if (primType === 'string' && typeof val === 'string') {
+                    val = (0, sanitizer_1.trimString)(val);
+                    if (config.min !== undefined && val.length < config.min)
+                        return defaultVal ?? undefined;
+                    if (config.max !== undefined && val.length > config.max)
+                        return defaultVal ?? undefined;
+                    if (config.regex && !config.regex.test(val))
+                        return defaultVal ?? undefined;
+                    if (config.email) {
+                        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+                        if (!emailRegex.test(val))
+                            return defaultVal ?? undefined;
+                    }
+                }
+                // Number validations
+                if (primType === 'number' && typeof val === 'number') {
+                    if (config.min !== undefined && val < config.min)
+                        return defaultVal ?? undefined;
+                    if (config.max !== undefined && val > config.max)
+                        return defaultVal ?? undefined;
+                }
+                // Custom validation
+                if (config.validate && !config.validate(val)) {
+                    return defaultVal ?? undefined;
+                }
+                // Transformation
+                if (config.transform) {
+                    try {
+                        val = config.transform(val);
+                    }
+                    catch (e) {
+                        if (opts.dev)
+                            (opts.logger ?? console.warn)('[payload-guard] transform error: ' + String(e));
+                    }
+                }
+            }
+            return val;
+        };
+    }
     // If already a regular function, wrap it
     if (typeof shape === 'function') {
         return (value) => shape(value);
@@ -44,17 +93,6 @@ function compile(shape, opts = {}) {
             return primType === 'string' ? (0, sanitizer_1.trimString)(coerced) : coerced;
         };
     }
-    // Field config with type
-    if (isFieldConfig(shape)) {
-        const primType = shape.type;
-        const defaultVal = shape.default;
-        return (value) => {
-            if (value == null)
-                return defaultVal ?? value;
-            const coerced = (0, sanitizer_1.coercePrimitive)(primType, value);
-            return primType === 'string' ? (0, sanitizer_1.trimString)(coerced) : coerced;
-        };
-    }
     // Array shape
     if (isArrayShape(shape)) {
         const itemFn = compile(shape.item, { ...opts, _parentPath: (opts._parentPath || '') + '[]' });
@@ -154,8 +192,11 @@ function isArrayShape(value) {
  * Type guard for FieldConfig
  */
 function isFieldConfig(value) {
-    return (value !== null &&
-        typeof value === 'object' &&
+    if (value === null)
+        return false;
+    if (typeof value === 'function' && value.__isBuilder)
+        return true;
+    return (typeof value === 'object' &&
         !isShapeFunction(value) &&
         'type' in value &&
         typeof value.type === 'string');

package/dist/core/filter.d.ts

@@ -1,4 +1,4 @@
-import { ShapeDescriptor, ShapeFunction, GuardConfig } from './types';
+import { ShapeDescriptor, ShapeFunction, GuardConfig, StringBuilder, NumberBuilder, BooleanBuilder, AnyBuilder, ArrayShapeDescriptor } from './types';
 import { defaultSensitive } from './security';
 /**
  * Configure global guard settings
@@ -10,39 +10,18 @@ export declare function config(opts: GuardConfig): void;
 export declare function getConfig(): GuardConfig;
 /**
  * Build a shape filter function from a shape descriptor
- * Returns a callable function that filters objects to match the shape
  */
 export declare function buildShape<S extends ShapeDescriptor>(shape: S, opts?: GuardConfig): ShapeFunction<S>;
-/**
- * Main guard API object
- */
 export declare const guard: {
-    /**
-     * Create a shape filter from a descriptor
-     * @example
-     * const userShape = guard.shape({ id: 'number', name: 'string' });
-     * const filtered = userShape(userData);
-     */
-    shape: <S extends ShapeDescriptor>(descriptor: S, opts?: GuardConfig) => ShapeFunction<S>;
-    /** Compile a descriptor into a fast filter function directly */
-    compile: <S extends ShapeDescriptor>(descriptor: S, opts?: GuardConfig) => import("./types").CompiledFilter;
-    /**
-     * Create an array shape descriptor
-     * @example
-     * const usersShape = guard.shape({ users: guard.array({ id: 'number', name: 'string' }) });
-     */
-    array: (item: ShapeDescriptor) => import("./types").ArrayShapeDescriptor;
-    /**
-     * Configure global settings
-     */
     config: typeof config;
-    /**
-     * Get current configuration
-     */
     getConfig: typeof getConfig;
-    /**
-     * Get default sensitive fields list
-     */
     defaultSensitive: typeof defaultSensitive;
+    shape: typeof buildShape;
+    array: (item: ShapeDescriptor) => ArrayShapeDescriptor;
+    string: () => StringBuilder;
+    number: () => NumberBuilder;
+    boolean: () => BooleanBuilder;
+    any: () => AnyBuilder;
+    compile: (descriptor: ShapeDescriptor, opts?: GuardConfig) => import("./types").CompiledFilter;
 };
 export default guard;

package/dist/core/filter.js

@@ -38,7 +38,6 @@ function getConfig() {
 }
 /**
  * Build a shape filter function from a shape descriptor
- * Returns a callable function that filters objects to match the shape
  */
 function buildShape(shape, opts) {
     const mergedOpts = {
@@ -53,59 +52,81 @@ function buildShape(shape, opts) {
         logRemovedFields: opts?.logRemovedFields ?? globalConfig.logRemovedFields,
     };
     const compiledFn = (0, compiler_1.compile)(shape, mergedOpts);
-    // Create callable wrapper with compile method attached
     const wrapper = ((value) => compiledFn(value));
     wrapper.compile = compiledFn;
-    // attach extend to allow partial shape merges
     wrapper.extend = function (extra) {
-        // shallow merge for object shapes
         if (typeof shape === 'object' && typeof extra === 'object') {
             const merged = { ...shape, ...extra };
             return buildShape(merged, opts);
         }
-        // fallback: return a wrapper that composes both
         return buildShape({ _v: shape, _e: extra }, opts);
     };
     return wrapper;
 }
-/**
- * Main guard API object
- */
+function createBuilder(type) {
+    const config = { type };
+    const builder = (value) => {
+        // real logic is in compile()
+        return value;
+    };
+    const proto = {
+        __isBuilder: true,
+        config,
+        required() { config.required = true; return builder; },
+        optional() { config.required = false; return builder; },
+        default(val) { config.default = val; return builder; },
+        transform(fn) { config.transform = fn; return builder; },
+        validate(fn) { config.validate = fn; return builder; },
+    };
+    Object.setPrototypeOf(builder, proto);
+    if (type === 'string') {
+        builder.min = (n) => { config.min = n; return builder; };
+        builder.max = (n) => { config.max = n; return builder; };
+        builder.email = () => { config.email = true; return builder; };
+        builder.regex = (re) => { config.regex = re; return builder; };
+        builder.trim = () => {
+            const prev = config.transform;
+            config.transform = (v) => {
+                let val = typeof v === 'string' ? v.trim() : v;
+                return prev ? prev(val) : val;
+            };
+            return builder;
+        };
+        builder.toLowerCase = () => {
+            const prev = config.transform;
+            config.transform = (v) => {
+                let val = typeof v === 'string' ? v.toLowerCase() : v;
+                return prev ? prev(val) : val;
+            };
+            return builder;
+        };
+        builder.toUpperCase = () => {
+            const prev = config.transform;
+            config.transform = (v) => {
+                let val = typeof v === 'string' ? v.toUpperCase() : v;
+                return prev ? prev(val) : val;
+            };
+            return builder;
+        };
+    }
+    if (type === 'number') {
+        builder.min = (n) => { config.min = n; return builder; };
+        builder.max = (n) => { config.max = n; return builder; };
+        builder.integer = () => { config.validate = (v) => Number.isInteger(v); return builder; };
+        builder.positive = () => { config.min = 0; return builder; };
+    }
+    return builder;
+}
 exports.guard = {
-    /**
-     * Create a shape filter from a descriptor
-     * @example
-     * const userShape = guard.shape({ id: 'number', name: 'string' });
-     * const filtered = userShape(userData);
-     */
-    shape: (descriptor, opts) => buildShape(descriptor, opts),
-    /** Compile a descriptor into a fast filter function directly */
-    compile: (descriptor, opts) => (0, compiler_1.compile)(descriptor, {
-        ...opts,
-        sensitive: [...(opts?.sensitiveFields || []), ...(globalConfig.sensitiveFields || [])],
-        dev: opts?.devMode ?? globalConfig.devMode,
-        strict: opts?.strict ?? globalConfig.strict,
-        redact: opts?.redact ?? globalConfig.redact,
-        logger: opts?.logger ?? globalConfig.logger,
-        maxArrayLength: opts?.maxArrayLength ?? globalConfig.maxArrayLength,
-    }),
-    /**
-     * Create an array shape descriptor
-     * @example
-     * const usersShape = guard.shape({ users: guard.array({ id: 'number', name: 'string' }) });
-     */
-    array: (item) => (0, compiler_1.array)(item),
-    /**
-     * Configure global settings
-     */
     config,
-    /**
-     * Get current configuration
-     */
     getConfig,
-    /**
-     * Get default sensitive fields list
-     */
     defaultSensitive: security_1.defaultSensitive,
+    shape: buildShape,
+    array: (item) => (0, compiler_1.array)(item),
+    string: () => createBuilder('string'),
+    number: () => createBuilder('number'),
+    boolean: () => createBuilder('boolean'),
+    any: () => createBuilder('any'),
+    compile: (descriptor, opts) => (0, compiler_1.compile)(descriptor, opts),
 };
 exports.default = exports.guard;

package/dist/core/types.d.ts

@@ -7,11 +7,47 @@ export interface FieldConfig<T extends PrimitiveType = PrimitiveType> {
     type: T;
     required?: boolean;
     default?: InferPrimitive<T>;
+    min?: number;
+    max?: number;
+    regex?: RegExp;
+    email?: boolean;
+    transform?: (v: any) => any;
+    /** Custom validation function: return false if invalid */
+    validate?: (v: any) => boolean;
+}
+export interface ShapeBuilder<T extends PrimitiveType> {
+    (value: unknown): InferPrimitive<T>;
+    readonly __isBuilder: true;
+    readonly config: FieldConfig<T>;
+    required(): ShapeBuilder<T>;
+    optional(): ShapeBuilder<T>;
+    default(val: InferPrimitive<T>): ShapeBuilder<T>;
+    transform(fn: (v: InferPrimitive<T>) => any): ShapeBuilder<T>;
+    validate(fn: (v: InferPrimitive<T>) => boolean): ShapeBuilder<T>;
+}
+export interface StringBuilder extends ShapeBuilder<'string'> {
+    min(len: number): StringBuilder;
+    max(len: number): StringBuilder;
+    email(): StringBuilder;
+    regex(pattern: RegExp): StringBuilder;
+    trim(): StringBuilder;
+    toLowerCase(): StringBuilder;
+    toUpperCase(): StringBuilder;
+}
+export interface NumberBuilder extends ShapeBuilder<'number'> {
+    min(val: number): NumberBuilder;
+    max(val: number): NumberBuilder;
+    integer(): NumberBuilder;
+    positive(): NumberBuilder;
+}
+export interface BooleanBuilder extends ShapeBuilder<'boolean'> {
+}
+export interface AnyBuilder extends ShapeBuilder<'any'> {
 }
 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 ShapeDescriptor = PrimitiveType | FieldConfig | {
     [key: string]: ShapeDescriptor;
-} | ArrayShapeDescriptor | CompiledFilter;
+} | ArrayShapeDescriptor | CompiledFilter | ShapeBuilder<any>;
 export interface ArrayShapeDescriptor {
     readonly __isArray: true;
     readonly item: ShapeDescriptor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payload-guard-filter",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Lightweight, zero-dependency shape-based payload filtering and sanitization for Node.js and browser",
   "main": "dist/index.js",
   "module": "dist/index.js",