@zenweb/body - npm Package Compare versions

Comparing version 5.4.0 to 5.4.1

AGENTS.md

+# @zenweb/body - AI Reference
+
+This document provides a complete reference for AI agents working with this module.
+
+## Exports Overview
+
+```
+setup (default)          - Module setup function
+
+Types:
+BodyOption               - Configuration interface/class
+BodyParserClass          - Parser class type
+
+Injectable Classes (request scope):
+RawBody                  - Raw buffer (decompressed, not decoded)
+TextBody                 - Decoded text string
+Body                     - Parsed body data
+ObjectBody               - Object representation of body
+BodyHelper               - Type conversion & validation helper
+
+Parser Classes (singleton scope):
+BodyParser               - Abstract base parser
+TextBodyParser           - Abstract text parser
+RawBodyParser            - Abstract raw buffer parser
+JSONParser               - JSON parser implementation
+URLEncodedParser         - URL-encoded form parser
+
+Global Functions:
+$getRawBody              - Get raw buffer via AsyncLocalStorage
+$getTextBody             - Get decoded text via AsyncLocalStorage
+$getObjectBody           - Get ObjectBody instance via AsyncLocalStorage
+$body                    - BodyHelper proxy for global access
+
+Middleware:
+useBodyParser            - Force specific parser for request
+USE_BODY_PARSER          - Symbol for parser selection
+```
+
+## Setup Function
+
+```typescript
+import body from '@zenweb/body';
+
+$initCore()
+  .setup(body(options))
+  .start();
+```
+
+### BodyOption
+
+```typescript
+interface BodyOption {
+  encoding?: string;      // Default charset: 'utf-8'
+  limit?: number;         // Size limit in bytes: 1024 * 1024 (1MB)
+  inflate?: boolean;      // Support gzip/deflate: true
+  textTypes?: string[];   // Text-compatible mimetypes
+  parses?: BodyParserClass[];  // Parser classes
+}
+```
+
+Default textTypes: `['text/*', 'xml', '+xml']`
+Default parsers: `[JSONParser, URLEncodedParser]`
+
+## Injectable Classes
+
+### RawBody (request scope)
+```typescript
+class RawBody {
+  data?: Buffer;  // Raw buffer, decompressed if needed
+}
+```
+Use for binary data or when charset conversion is not needed.
+
+### TextBody (request scope)
+```typescript
+class TextBody {
+  data?: string;  // Decoded text with charset conversion
+}
+```
+Charset detected from request or uses `encoding` option.
+
+### Body (request scope)
+```typescript
+class Body {
+  data?: unknown;          // Parsed result
+  type?: 'text' | string;  // matched type or 'text'
+  parser?: BodyParser;     // matched parser instance
+}
+```
+Auto-selects parser based on Content-Type.
+
+### ObjectBody (request scope)
+```typescript
+class ObjectBody {
+  [key: string]: unknown;
+}
+```
+Only works with `objected: true` parsers (JSON, urlencoded).
+
+### BodyHelper (request scope)
+```typescript
+class BodyHelper extends HelperBase {
+  input: ObjectBody;
+  // Methods from HelperBase:
+  data(): unknown;
+  get<O>(fields: O): Promise<PickReturnType<O>>;
+  page(opt?: PageOption): Promise<PageResultWithOption>;
+}
+```
+Type-safe field extraction and validation.
+
+## Global Functions
+
+Use these outside DI context via AsyncLocalStorage:
+
+```typescript
+// Get raw buffer
+const raw = await $getRawBody();
+
+// Get decoded text
+const text = await $getTextBody();
+
+// Get ObjectBody instance
+const obj = await $getObjectBody();
+
+// BodyHelper proxy - same methods as instance
+const data = await $body.data();
+const fields = await $body.get({ name: 'string', age: 'int' });
+const page = await $body.page({ limit: 10 });
+```
+
+## Parser Classes
+
+### BodyParser (abstract, singleton)
+```typescript
+abstract class BodyParser {
+  abstract objected: boolean;     // Can convert to ObjectBody
+  abstract types: string[];       // Supported mimetypes
+  abstract parse(data: Buffer | string): unknown;
+  fail(n: number, ...args): never;  // Throw http-error
+}
+```
+
+### TextBodyParser (abstract, singleton)
+```typescript
+abstract class TextBodyParser extends BodyParser {
+  abstract parse(text: string): unknown;
+}
+```
+Receive decoded text string.
+
+### RawBodyParser (abstract, singleton)
+```typescript
+abstract class RawBodyParser extends BodyParser {
+  abstract parse(data: Buffer): unknown;
+}
+```
+Receive raw buffer.
+
+### JSONParser (singleton)
+```typescript
+class JSONParser extends TextBodyParser {
+  objected = true;
+  types = ['json', '+json'];
+  parse(text: string): any;
+}
+```
+
+### URLEncodedParser (singleton)
+```typescript
+class URLEncodedParser extends TextBodyParser {
+  objected = true;
+  types = ['urlencoded'];
+  parse(text: string): ParsedUrlQuery;
+}
+```
+
+## Custom Parser Example
+
+```typescript
+@Injectable('singleton')
+export class XMLParser extends TextBodyParser {
+  objected = false;
+  types = ['xml', '+xml'];
+
+  parse(text: string) {
+    // Parse XML string
+    return parseXML(text);
+  }
+}
+
+// Register in setup
+.setup(body({ parses: [JSONParser, URLEncodedParser, XMLParser] }))
+```
+
+## Middleware
+
+### useBodyParser
+
+Force a specific parser for a route:
+
+```typescript
+import { useBodyParser, JSONParser } from '@zenweb/body';
+
+router.post('/api', useBodyParser(JSONParser), handler);
+```
+
+## Usage Patterns
+
+### In Controller with DI
+
+```typescript
+import { Body, BodyHelper } from '@zenweb/body';
+
+@Controller()
+class MyController {
+  @Post()
+  post(body: Body) {
+    console.log(body.type, body.data);
+  }
+
+  @Post()
+  validate(helper: BodyHelper) {
+    const { name, age } = await helper.get({
+      name: 'string',
+      age: '!int'  // required integer
+    });
+  }
+}
+```
+
+### Outside Request Context
+
+```typescript
+import { $body } from '@zenweb/body';
+
+async function someFunction() {
+  const data = await $body.data();
+}
+```
+
+## Error Handling
+
+Module throws `http-errors` with structured info:
+
+| Status | Type | Description |
+|--------|------|-------------|
+| 400 | `json.parse-error` | JSON parse failed |
+| 400 | `decode.failed` | Charset decode failed |
+| 413 | `entity.too.large` | Body exceeds limit |
+| 415 | `json.strict` | JSON must be object/array |
+| 415 | `charset.unsupported` | Unknown charset |
+| 415 | `encoding.unsupported` | Unknown compression |

package.json

 {
   "name": "@zenweb/body",
-  "version": "5.4.0",
+  "version": "5.4.1",
   "description": "Zenweb Body module",
@@ -5,0 +5,0 @@ "exports": "./dist/index.js",

New alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

33704

21.7%

Number of package files

15

7.14%

No dependency changes