payload-guard-filter 1.3.2 → 1.4.0

package/README.md

@@ -77,6 +77,42 @@ 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)
+
 ---
 
 ## ⚡ Performance

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.2",
+  "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",