@venizia/ignis-docs 0.0.1-5 → 0.0.1-6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.1-5",
+  "version": "0.0.1-6",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",
@@ -54,7 +54,8 @@
     "README.md",
     "LICENSE.md",
     "mcp-server/dist",
-    "wiki"
+    "wiki",
+    "!**/*.tsbuildinfo"
   ],
   "publishConfig": {
     "access": "public"
@@ -94,7 +95,7 @@
   "bugs": {
     "url": "https://github.com/VENIZIA-AI/ignis/issues"
   },
-  "homepage": "https://github.com/VENIZIA-AI/ignis/wiki",
+  "homepage": "https://venizia-ai.github.io/ignis",
   "license": "MIT",
   "dependencies": {
     "@mastra/core": "^0.24.6",
@@ -110,7 +111,7 @@
     "@braintree/sanitize-url": "^7.1.1",
     "@types/bun": "^1.3.4",
     "@types/glob": "^8.1.0",
-    "@venizia/dev-configs": "^0.0.1-3",
+    "@venizia/dev-configs": "^0.0.1-4",
     "eslint": "^9.36.0",
     "glob": "^10.4.2",
     "prettier": "^3.6.2",

package/wiki/public/logo.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 92.27 122.88" style="enable-background:new 0 0 92.27 122.88" xml:space="preserve"><style type="text/css">.st0{fill-rule:evenodd;clip-rule:evenodd;fill:#EC6F59;} .st1{fill-rule:evenodd;clip-rule:evenodd;fill:#FAD15C;}</style><g><path class="st0" d="M18.61,54.89C15.7,28.8,30.94,10.45,59.52,0C42.02,22.71,74.44,47.31,76.23,70.89 c4.19-7.15,6.57-16.69,7.04-29.45c21.43,33.62,3.66,88.57-43.5,80.67c-4.33-0.72-8.5-2.09-12.3-4.13C10.27,108.8,0,88.79,0,69.68 C0,57.5,5.21,46.63,11.95,37.99C12.85,46.45,14.77,52.76,18.61,54.89L18.61,54.89z"/><path class="st1" d="M33.87,92.58c-4.86-12.55-4.19-32.82,9.42-39.93c0.1,23.3,23.05,26.27,18.8,51.14 c3.92-4.44,5.9-11.54,6.25-17.15c6.22,14.24,1.34,25.63-7.53,31.43c-26.97,17.64-50.19-18.12-34.75-37.72 C26.53,84.73,31.89,91.49,33.87,92.58L33.87,92.58z"/></g></svg>

package/wiki/references/base/models.md

@@ -79,7 +79,7 @@ Enrichers are helper functions located in `packages/core/src/base/models/enriche
 | Enricher Function | Purpose |
 | :--- | :--- |
 | **`generateIdColumnDefs`** | Adds a primary key `id` column (string UUID or numeric serial). |
-| **`generateTzColumnDefs`** | Adds `createdAt` and `modifiedAt` timestamp columns with timezone support. |
+| **`generateTzColumnDefs`** | Adds `createdAt`, `modifiedAt`, and `deletedAt` timestamp columns with timezone support. |
 | **`generateUserAuditColumnDefs`** | Adds `createdBy` and `modifiedBy` columns to track user audit information. |
 | **`generateDataTypeColumnDefs`** | Adds generic data type columns (`dataType`, `nValue`, `tValue`, `bValue`, `jValue`, `boValue`) for flexible data storage. |
 | **`generatePrincipalColumnDefs`** | Adds polymorphic fields for associating with different principal types. |
@@ -102,3 +102,321 @@ export const myTable = pgTable('MyTable', {
   name: text('name').notNull(),
 });
 ```
+
+---
+
+## Detailed Enricher Reference
+
+### `generateTzColumnDefs`
+
+Adds timestamp columns for tracking entity creation, modification, and soft deletion.
+
+**File:** `packages/core/src/base/models/enrichers/tz.enricher.ts`
+
+#### Signature
+
+```typescript
+generateTzColumnDefs(opts?: TTzEnricherOptions): TTzEnricherResult
+```
+
+#### Options (`TTzEnricherOptions`)
+
+```typescript
+type TTzEnricherOptions = {
+  created?: { columnName: string; withTimezone: boolean };
+  modified?: { enable: boolean; columnName: string; withTimezone: boolean };
+  deleted?: { enable: boolean; columnName: string; withTimezone: boolean };
+};
+```
+
+**Default values:**
+- `created`: `{ columnName: 'created_at', withTimezone: true }`
+- `modified`: `{ enable: true, columnName: 'modified_at', withTimezone: true }`
+- `deleted`: `{ enable: false }` (disabled by default)
+
+#### Generated Columns
+
+| Column | Type | Constraints | Default | Description |
+|--------|------|-------------|---------|-------------|
+| `createdAt` | `timestamp` | `NOT NULL` | `now()` | When the record was created (always included) |
+| `modifiedAt` | `timestamp` | `NOT NULL` | `now()` | When the record was last modified (optional, enabled by default) |
+| `deletedAt` | `timestamp` | nullable | `null` | When the record was soft-deleted (optional, **disabled by default**) |
+
+#### Usage Examples
+
+**Basic usage (default columns):**
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { generateTzColumnDefs } from '@venizia/ignis';
+
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs(),
+  name: text('name').notNull(),
+});
+
+// Generates: createdAt, modifiedAt (deletedAt is disabled by default)
+```
+
+**Enable soft delete:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    deleted: { enable: true, columnName: 'deleted_at', withTimezone: true },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: createdAt, modifiedAt, deletedAt
+```
+
+**Custom column names:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    created: { columnName: 'created_date', withTimezone: true },
+    modified: { enable: true, columnName: 'updated_date', withTimezone: true },
+    deleted: { enable: true, columnName: 'removed_date', withTimezone: true },
+  }),
+  name: text('name').notNull(),
+});
+```
+
+**Without timezone:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    created: { columnName: 'created_at', withTimezone: false },
+    modified: { enable: true, columnName: 'modified_at', withTimezone: false },
+    deleted: { enable: true, columnName: 'deleted_at', withTimezone: false },
+  }),
+  name: text('name').notNull(),
+});
+```
+
+
+
+**Minimal setup (only createdAt):**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    modified: { enable: false },
+    deleted: { enable: false },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: createdAt only
+```
+
+#### Soft Delete Pattern
+
+The `deletedAt` column enables the soft delete pattern, where records are marked as deleted rather than physically removed from the database.
+
+**Example soft delete query:**
+
+```typescript
+import { eq, isNull } from 'drizzle-orm';
+
+// Soft delete: set deletedAt timestamp
+await db.update(myTable)
+  .set({ deletedAt: new Date() })
+  .where(eq(myTable.id, id));
+
+// Query only active (non-deleted) records
+const activeRecords = await db.select()
+  .from(myTable)
+  .where(isNull(myTable.deletedAt));
+
+// Query deleted records
+const deletedRecords = await db.select()
+  .from(myTable)
+  .where(isNotNull(myTable.deletedAt));
+
+// Restore a soft-deleted record
+await db.update(myTable)
+  .set({ deletedAt: null })
+  .where(eq(myTable.id, id));
+```
+
+#### Type Inference
+
+The enricher provides proper TypeScript type inference:
+
+```typescript
+type TTzEnricherResult<ColumnDefinitions extends TColumnDefinitions = TColumnDefinitions> = {
+  createdAt: PgTimestampBuilderInitial<string> & NotNull & HasDefault;
+  modifiedAt?: PgTimestampBuilderInitial<string> & NotNull & HasDefault;
+  deletedAt?: PgTimestampBuilderInitial<string>;
+};
+```
+
+---
+
+## Schema Utilities
+
+### `snakeToCamel`
+
+Converts a Zod schema from snake_case to camelCase, transforming both the schema shape and runtime data.
+
+**File:** `packages/core/src/base/models/common/types.ts`
+
+#### Signature
+
+```typescript
+snakeToCamel<T extends z.ZodRawShape>(shape: T): z.ZodEffects<...>
+```
+
+#### Purpose
+
+This utility is useful when working with databases that use snake_case column names but you want to work with camelCase in your TypeScript code. It creates a Zod schema that:
+
+1. Accepts snake_case input (validates against original schema)
+2. Transforms the data to camelCase at runtime
+3. Validates the transformed data against a camelCase schema
+
+#### Usage Example
+
+```typescript
+import { z } from 'zod';
+import { snakeToCamel } from '@venizia/ignis';
+
+// Define schema with snake_case fields
+const userSnakeSchema = {
+  user_id: z.number(),
+  first_name: z.string(),
+  last_name: z.string(),
+  created_at: z.date(),
+  is_active: z.boolean(),
+};
+
+// Convert to camelCase schema
+const userCamelSchema = snakeToCamel(userSnakeSchema);
+
+// Input data from database (snake_case)
+const dbData = {
+  user_id: 123,
+  first_name: 'John',
+  last_name: 'Doe',
+  created_at: new Date(),
+  is_active: true,
+};
+
+// Parse and transform to camelCase
+const result = userCamelSchema.parse(dbData);
+
+// Result is automatically camelCase:
+console.log(result);
+// {
+//   userId: 123,
+//   firstName: 'John',
+//   lastName: 'Doe',
+//   createdAt: Date,
+//   isActive: true
+// }
+```
+
+#### Real-world Example
+
+**Use case:** API endpoint that accepts snake_case but works with camelCase internally
+
+```typescript
+import { BaseController, controller, snakeToCamel } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+const createUserSchema = snakeToCamel({
+  first_name: z.string().min(1),
+  last_name: z.string().min(1),
+  email_address: z.string().email(),
+  phone_number: z.string().optional(),
+});
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+  override binding() {
+    this.bindRoute({
+      configs: {
+        path: '/',
+        method: 'post',
+        request: {
+          body: {
+            content: {
+              'application/json': { schema: createUserSchema },
+            },
+          },
+        },
+      },
+    }).to({
+      handler: async (ctx) => {
+        // Request body is automatically camelCase
+        const data = ctx.req.valid('json');
+        
+        // data = {
+        //   firstName: string,
+        //   lastName: string,
+        //   emailAddress: string,
+        //   phoneNumber?: string
+        // }
+        
+        // Work with camelCase data
+        console.log(data.firstName);  // ✅ TypeScript knows this exists
+        console.log(data.first_name);  // ❌ TypeScript error
+        
+        return ctx.json({ success: true });
+      },
+    });
+  }
+}
+```
+
+#### Type Transformation
+
+The utility includes sophisticated TypeScript type transformation:
+
+```typescript
+type TSnakeToCamelCase<S extends string> = 
+  S extends `${infer T}_${infer U}`
+    ? `${T}${Capitalize<TSnakeToCamelCase<U>>}`
+    : S;
+
+type TCamelCaseKeys<T extends z.ZodRawShape> = {
+  [K in keyof T as K extends string ? TSnakeToCamelCase<K> : K]: 
+    T[K] extends z.ZodType<infer U> ? z.ZodType<U> : T[K];
+};
+```
+
+This ensures full type safety: TypeScript will know that `first_name` becomes `firstName`, `created_at` becomes `createdAt`, etc.
+
+#### Validation
+
+The schema validates twice for safety:
+
+1. **First validation:** Checks that input matches snake_case schema
+2. **Transformation:** Converts keys from snake_case to camelCase
+3. **Second validation:** Validates transformed data against camelCase schema
+
+```typescript
+// If validation fails at any step, you get clear error messages
+const invalidData = {
+  user_id: 'not-a-number',  // ❌ Fails first validation
+  first_name: 'John',
+  last_name: 'Doe',
+};
+
+try {
+  userCamelSchema.parse(invalidData);
+} catch (error) {
+  // ZodError with clear message about user_id expecting number
+}
+```
+
+#### Notes
+
+- Built on top of `keysToCamel()` and `toCamel()` utilities from `@venizia/ignis-helpers`
+- Recursively handles nested objects
+- Preserves array structures
+- Works seamlessly with Zod's other features (refinements, transforms, etc.)

package/wiki/references/components/index.md

@@ -8,8 +8,10 @@ Reusable, pluggable modules that encapsulate specific features in Ignis applicat
 |-----------|---------|--------------|
 | [Authentication](./authentication.md) | JWT-based auth | Token generation, protected routes, user payload |
 | [Health Check](./health-check.md) | Monitoring endpoint | `/health` endpoint, ping/pong functionality |
-| [Swagger](./swagger.md) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
+| [Request Tracker](./request-tracker.md) | Request logging | Request ID generation, timing, structured logging |
 | [Socket.IO](./socket-io.md) | Real-time communication | WebSocket support, Redis adapter, event-based |
+| [Static Asset](./static-asset.md) | File management | Upload/download files, MinIO & local filesystem support |
+| [Swagger](./swagger.md) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
 
 ## Creating a Component