@venizia/ignis-docs 0.0.4 → 0.0.5

package/wiki/references/base/filter-system/json-filtering.md

@@ -193,5 +193,7 @@ CREATE INDEX idx_metadata_gin ON "Product" USING GIN ("metadata");
 // This is safe - no errors, just no matches
 { where: { 'metadata.nonexistent.field': 'value' } }
 // SQL: "metadata" #>> '{nonexistent,field}' = 'value'
-// Result: No rows (NULL != 'value')
-```
+## See Also
+
+- [Nested JSON Updates](../repositories/advanced.md#nested-json-updates) - Updating JSON fields
+

package/wiki/references/base/middlewares.md

@@ -7,7 +7,7 @@ lastUpdated: 2026-01-03
 
 # Middlewares Reference
 
-IGNIS provides a collection of built-in middlewares for common application needs including error handling, request logging, request normalization, and favicon serving.
+IGNIS provides a collection of built-in middlewares for common application needs including error handling, request logging, and favicon serving.
 
 **Files:**
 - `packages/core/src/base/middlewares/*.ts`
@@ -24,16 +24,14 @@ IGNIS provides a collection of built-in middlewares for common application needs
 |------------|---------|-------------|
 | `appErrorHandler` | Catches and formats application errors | `logger` |
 | `notFoundHandler` | Handles 404 Not Found responses | `logger` |
-| `requestNormalize` | Pre-parses JSON request bodies | None |
-| `RequestSpyMiddleware` | Logs request lifecycle and timing | None |
+| `RequestSpyMiddleware` | Logs request lifecycle, timing, and parses request body | None |
 | `emojiFavicon` | Serves an emoji as favicon | `icon` |
 
 ## Table of Contents
 
 - [Error Handler (`appErrorHandler`)](#error-handler-apporerrorhandler)
 - [Not Found Handler (`notFoundHandler`)](#not-found-handler-notfoundhandler)
-- [Request Normalizer (`requestNormalize`)](#request-normalizer-requestnormalize)
-- [Request Spy (Debug)](#request-spy-debug)
+- [Request Spy (`RequestSpyMiddleware`)](#request-spy-requestspymiddleware)
 - [Emoji Favicon](#emoji-favicon)
 - [Creating Custom Middleware](#creating-custom-middleware)
 - [Middleware Order & Priority](#middleware-order--priority)
@@ -237,65 +235,23 @@ app.notFound(notFoundHandler({
 
 ---
 
-### Request Normalizer (`requestNormalize`)
+### Request Spy (`RequestSpyMiddleware`)
 
-Pre-parses JSON request bodies to ensure consistent request handling and prevent common parsing issues.
-
-**File:** `packages/core/src/base/middlewares/request-normalize.middleware.ts`
-
-#### How It Works
-
-1. **Skip for GET/OPTIONS**: No normalization for read-only requests
-2. **Check Content-Length**: Skip if no body is present (`Content-Length: 0`)
-3. **Check Content-Type**: Only process `application/json` requests
-4. **Pre-parse JSON**: Calls `context.req.json()` to cache the parsed body
-
-#### Benefits
-
-- Prevents multiple body parsing attempts
-- Ensures body is available for all subsequent middleware/handlers
-- Catches JSON parsing errors early in the request lifecycle
-
-#### Usage
-
-```typescript
-import { requestNormalize } from '@venizia/ignis';
-
-const app = new IgnisApplication({
-  // ...
-});
-
-// Register as early middleware
-app.use(requestNormalize());
-```
-
-:::tip Why Pre-parse?
-Hono's request body can only be read once. This middleware ensures the body is parsed and cached early, making it available to all downstream handlers.
-:::
-
-#### API Reference
-
-##### `requestNormalize()`
-
-**Parameters:** None
-
-**Returns:** `MiddlewareHandler` - Hono middleware function
-
----
-
-### Request Spy (Debug)
-
-Logs detailed information about each request including timing, IP address, method, path, and query parameters.
+Logs detailed information about each request including timing, IP address, method, path, query parameters, and request body. Also handles request body parsing for JSON, form data, and text content types.
 
 **File:** `packages/core/src/base/middlewares/request-spy.middleware.ts`
 
 #### Features
 
-- Request lifecycle logging (START/DONE)
+- Request lifecycle logging (incoming/outgoing)
 - Performance timing tracking
 - IP address extraction (supports `x-real-ip` and `x-forwarded-for` headers)
 - Request ID tracking
-- Query and body parameter logging
+- Query and body parameter logging (body only logged in non-production)
+- **Request body parsing**: Automatically parses and caches request bodies:
+  - `application/json` → `req.json()`
+  - `multipart/form-data`, `application/x-www-form-urlencoded` → `req.parseBody()`
+  - Other content types (text, html, xml) → `req.text()`
 
 #### Usage
 
@@ -511,43 +467,39 @@ app.use(cors());
 // 2. Request ID generation
 app.use(requestId());
 
-// 3. Request spy/logging
+// 3. Request spy/logging (also handles body parsing)
 const requestSpy = new RequestSpyMiddleware();
 app.use(requestSpy.value());
 
-// 4. Request normalization
-app.use(requestNormalize());
-
-// 5. Security middleware (helmet, etc.)
+// 4. Security middleware (helmet, etc.)
 app.use(helmet());
 
-// 6. Rate limiting
+// 5. Rate limiting
 app.use(rateLimit());
 
-// 7. Authentication
+// 6. Authentication
 app.use('/api/*', authenticate());
 
-// 8. Favicon (can be early or late)
+// 7. Favicon (can be early or late)
 app.use(emojiFavicon({ icon: '🚀' }));
 
-// 9. Application routes
+// 8. Application routes
 app.mountControllers();
 
-// 10. Error handler (LAST in chain)
+// 9. Error handler (LAST in chain)
 app.onError(appErrorHandler({ logger: app.logger }));
 
-// 11. Not found handler (AFTER error handler)
+// 10. Not found handler (AFTER error handler)
 app.notFound(notFoundHandler({ logger: app.logger }));
 ```
 
 ### Key Principles
 
 1. **Request ID First**: Generate request ID before logging
-2. **Logging Early**: Log requests before normalization/parsing
-3. **Normalization Before Business Logic**: Parse bodies before they're needed
-4. **Security Middleware Before Routes**: Protect routes with security checks
-5. **Error Handler Last**: Catch all errors from previous middleware
-6. **404 Handler After Error Handler**: Ensure unhandled routes return 404
+2. **Request Spy Early**: Log and parse request bodies before business logic
+3. **Security Middleware Before Routes**: Protect routes with security checks
+4. **Error Handler Last**: Catch all errors from previous middleware
+5. **404 Handler After Error Handler**: Ensure unhandled routes return 404
 
 :::warning Order Matters
 Placing error handler before routes will prevent it from catching route errors. Always register error handlers last.
@@ -584,7 +536,7 @@ app.use('/api/public/*', rateLimitMiddleware());
 const apiMiddleware = (): MiddlewareHandler => {
   return createMiddleware(async (context, next) => {
     // Run multiple middleware in sequence
-    await requestNormalize()(context, async () => {
+    await rateLimit()(context, async () => {
       await authenticate()(context, next);
     });
   });

package/wiki/references/base/repositories/advanced.md

@@ -513,6 +513,89 @@ await tx.commit();
 > See [Default Filter](../filter-system/default-filter.md) for full documentation on configuring model default filters.
 
 
+## Nested JSON Updates
+
+Repositories support updating specific fields within `json` or `jsonb` columns without overwriting the entire object. This is achieved using **JSON Path Notation** in the update data.
+
+### Basic Usage
+
+Use dot notation keys to target nested properties:
+
+```typescript
+// Assume 'metadata' is a JSONB column
+// Current value: { theme: 'light', notifications: { email: true } }
+
+await repo.updateById({
+  id: '123',
+  data: {
+    // Update only the theme, preserving other fields
+    'metadata.theme': 'dark'
+  }
+});
+
+// New value: { theme: 'dark', notifications: { email: true } }
+```
+
+### Supported Features
+
+- **Deep Nesting:** Update properties at any depth (e.g., `settings.display.font.size`).
+- **Array Access:** Update array elements by index (e.g., `tags[0]`).
+- **Auto-Creation:** Creates missing intermediate keys automatically.
+- **Type Safety:** Validates that the target column is a JSON type.
+- **Multiple Updates:** Chain multiple updates to the same or different columns.
+
+### Examples
+
+#### Deeply Nested Updates
+
+```typescript
+await repo.updateById({
+  id: '123',
+  data: {
+    'metadata.settings.display.fontSize': 16,
+    'metadata.settings.display.showSidebar': true
+  }
+});
+```
+
+#### Array Element Updates
+
+```typescript
+await repo.updateById({
+  id: '123',
+  data: {
+    // Set the first address as primary
+    'metadata.addresses[0].primary': true
+  }
+});
+```
+
+#### Mixed Updates (Regular + JSON)
+
+You can mix regular column updates with JSON path updates:
+
+```typescript
+await repo.updateById({
+  id: '123',
+  data: {
+    status: 'active',           // Regular column
+    'metadata.lastLogin': now,  // JSON path
+    'preferences.lang': 'en'    // Another JSON path
+  }
+});
+```
+
+### Security & Validation
+
+The framework validates JSON paths to prevent SQL injection:
+- **Allowed Characters:** Alphanumeric, underscores `_`, hyphens `-`, and brackets `[]`.
+- **Validation:** Invalid paths (e.g., containing SQL commands or special characters) throw an error before reaching the database.
+- **Values:** Values are safely serialized and parameterized.
+
+> [!NOTE]
+> This feature uses PostgreSQL's `jsonb_set` function. It is only available for columns defined as `json` or `jsonb`.
+
+
 ## Quick Reference
 
 | Feature | Code |

package/wiki/references/base/repositories/index.md

@@ -214,7 +214,7 @@ await repo.deleteAll({ where: {}, options: { force: true } });
 
 - **Repository Topics:**
   - [Relations & Includes](./relations) - Loading related data
-  - [Advanced Features](./advanced) - JSON queries, performance tuning, transactions
+  - [Advanced Features](./advanced) - JSON updates, transactions, performance tuning
   - [Repository Mixins](./mixins) - Soft delete and auditing
 
 - **Filtering:**