payload-guard-filter 1.3.0 → 1.3.2

package/README.md

@@ -1,5 +1,7 @@
 # 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>
@@ -44,10 +46,6 @@ graph LR
 
 ```bash
 npm install payload-guard
-# or
-yarn add payload-guard
-# or
-pnpm add payload-guard
 ```
 
 ---
@@ -79,318 +77,31 @@ const safeData = userShape(rawData);
 // Result: { id: 1, name: 'John Doe', email: 'john@example.com' }
 ```
 
-### Express Middleware
-
-```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
-});
-
-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',
-      }),
-    })
-  ),
-});
-```
-
 ---
 
 ## ⚡ 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+)
-
-Designed for high-performance production systems, Payload Guard includes enterprise-grade features for security, observability, and 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** |
 
-### 🛡️ 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`.
+### ⛑️ Maintained actively.
+**Bug fixes usually within 24–48 hours.**
 
 ---
-
-## 🛠️ CLI
-
-```bash
-npx payload-guard init
-```
-
-Creates example files in your project:
-- `shapes.ts` — Example shape definitions
-- `server-example.ts` — Express middleware setup
-
----
-
 ## 📄 License
 
 MIT

package/package.json

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