npm - @venizia/ignis-docs - Versions diffs - 0.0.3 → 0.0.4-0 - Mend

@venizia/ignis-docs 0.0.3 → 0.0.4-0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (131) hide show

package/README.md +1 -1
package/package.json +4 -2
package/wiki/best-practices/api-usage-examples.md +591 -0
package/wiki/best-practices/architectural-patterns.md +415 -0
package/wiki/best-practices/architecture-decisions.md +488 -0
package/wiki/{get-started/best-practices → best-practices}/code-style-standards.md +406 -17
package/wiki/{get-started/best-practices → best-practices}/common-pitfalls.md +109 -4
package/wiki/{get-started/best-practices → best-practices}/contribution-workflow.md +34 -7
package/wiki/best-practices/data-modeling.md +376 -0
package/wiki/best-practices/deployment-strategies.md +698 -0
package/wiki/best-practices/index.md +27 -0
package/wiki/best-practices/performance-optimization.md +196 -0
package/wiki/best-practices/security-guidelines.md +218 -0
package/wiki/{get-started/best-practices → best-practices}/troubleshooting-tips.md +97 -1
package/wiki/changelogs/2025-12-16-initial-architecture.md +1 -1
package/wiki/changelogs/2025-12-16-model-repo-datasource-refactor.md +1 -1
package/wiki/changelogs/2025-12-17-refactor.md +1 -1
package/wiki/changelogs/2025-12-18-performance-optimizations.md +5 -5
package/wiki/changelogs/2025-12-18-repository-validation-security.md +13 -7
package/wiki/changelogs/2025-12-26-nested-relations-and-generics.md +2 -2
package/wiki/changelogs/2025-12-29-dynamic-binding-registration.md +104 -0
package/wiki/changelogs/2025-12-29-snowflake-uid-helper.md +100 -0
package/wiki/changelogs/2025-12-30-repository-enhancements.md +214 -0
package/wiki/changelogs/2025-12-31-json-path-filtering-array-operators.md +214 -0
package/wiki/changelogs/2025-12-31-string-id-custom-generator.md +137 -0
package/wiki/changelogs/2026-01-02-default-filter-and-repository-mixins.md +418 -0
package/wiki/changelogs/index.md +6 -0
package/wiki/changelogs/planned-schema-migrator.md +0 -8
package/wiki/{get-started/core-concepts → guides/core-concepts/application}/bootstrapping.md +18 -5
package/wiki/{get-started/core-concepts/application.md → guides/core-concepts/application/index.md} +47 -104
package/wiki/guides/core-concepts/components-guide.md +509 -0
package/wiki/{get-started → guides}/core-concepts/components.md +24 -17
package/wiki/{get-started → guides}/core-concepts/controllers.md +30 -13
package/wiki/{get-started → guides}/core-concepts/dependency-injection.md +97 -0
package/wiki/guides/core-concepts/persistent/datasources.md +179 -0
package/wiki/guides/core-concepts/persistent/index.md +119 -0
package/wiki/guides/core-concepts/persistent/models.md +241 -0
package/wiki/guides/core-concepts/persistent/repositories.md +219 -0
package/wiki/guides/core-concepts/persistent/transactions.md +170 -0
package/wiki/{get-started → guides}/core-concepts/services.md +26 -3
package/wiki/{get-started → guides/get-started}/5-minute-quickstart.md +59 -14
package/wiki/guides/get-started/philosophy.md +682 -0
package/wiki/guides/get-started/setup.md +157 -0
package/wiki/guides/index.md +89 -0
package/wiki/guides/reference/glossary.md +243 -0
package/wiki/{get-started → guides/reference}/mcp-docs-server.md +0 -10
package/wiki/{get-started → guides/tutorials}/building-a-crud-api.md +134 -132
package/wiki/{get-started/quickstart.md → guides/tutorials/complete-installation.md} +107 -71
package/wiki/guides/tutorials/ecommerce-api.md +1399 -0
package/wiki/guides/tutorials/realtime-chat.md +1261 -0
package/wiki/guides/tutorials/testing.md +723 -0
package/wiki/index.md +176 -37
package/wiki/references/base/application.md +27 -0
package/wiki/references/base/bootstrapping.md +30 -26
package/wiki/references/base/components.md +24 -7
package/wiki/references/base/controllers.md +51 -20
package/wiki/references/base/datasources.md +30 -0
package/wiki/references/base/dependency-injection.md +39 -3
package/wiki/references/base/filter-system/application-usage.md +224 -0
package/wiki/references/base/filter-system/array-operators.md +132 -0
package/wiki/references/base/filter-system/comparison-operators.md +109 -0
package/wiki/references/base/filter-system/default-filter.md +428 -0
package/wiki/references/base/filter-system/fields-order-pagination.md +155 -0
package/wiki/references/base/filter-system/index.md +127 -0
package/wiki/references/base/filter-system/json-filtering.md +197 -0
package/wiki/references/base/filter-system/list-operators.md +71 -0
package/wiki/references/base/filter-system/logical-operators.md +156 -0
package/wiki/references/base/filter-system/null-operators.md +58 -0
package/wiki/references/base/filter-system/pattern-matching.md +108 -0
package/wiki/references/base/filter-system/quick-reference.md +431 -0
package/wiki/references/base/filter-system/range-operators.md +63 -0
package/wiki/references/base/filter-system/tips.md +190 -0
package/wiki/references/base/filter-system/use-cases.md +452 -0
package/wiki/references/base/index.md +90 -0
package/wiki/references/base/middlewares.md +602 -0
package/wiki/references/base/models.md +215 -23
package/wiki/references/base/providers.md +732 -0
package/wiki/references/base/repositories/advanced.md +555 -0
package/wiki/references/base/repositories/index.md +228 -0
package/wiki/references/base/repositories/mixins.md +331 -0
package/wiki/references/base/repositories/relations.md +486 -0
package/wiki/references/base/repositories.md +40 -635
package/wiki/references/base/services.md +28 -4
package/wiki/references/components/authentication.md +22 -2
package/wiki/references/components/health-check.md +12 -0
package/wiki/references/components/index.md +23 -0
package/wiki/references/components/mail.md +687 -0
package/wiki/references/components/request-tracker.md +16 -0
package/wiki/references/components/socket-io.md +18 -0
package/wiki/references/components/static-asset.md +14 -26
package/wiki/references/components/swagger.md +17 -0
package/wiki/references/configuration/environment-variables.md +427 -0
package/wiki/references/configuration/index.md +73 -0
package/wiki/references/helpers/cron.md +14 -0
package/wiki/references/helpers/crypto.md +15 -0
package/wiki/references/helpers/env.md +16 -0
package/wiki/references/helpers/error.md +17 -0
package/wiki/references/helpers/index.md +14 -0
package/wiki/references/helpers/inversion.md +24 -4
package/wiki/references/helpers/logger.md +19 -0
package/wiki/references/helpers/network.md +11 -0
package/wiki/references/helpers/queue.md +19 -0
package/wiki/references/helpers/redis.md +21 -0
package/wiki/references/helpers/socket-io.md +24 -5
package/wiki/references/helpers/storage.md +18 -10
package/wiki/references/helpers/testing.md +18 -0
package/wiki/references/helpers/types.md +16 -0
package/wiki/references/helpers/uid.md +167 -0
package/wiki/references/helpers/worker-thread.md +16 -0
package/wiki/references/index.md +177 -0
package/wiki/references/quick-reference.md +634 -0
package/wiki/references/src-details/boot.md +3 -3
package/wiki/references/src-details/dev-configs.md +0 -4
package/wiki/references/src-details/docs.md +2 -2
package/wiki/references/src-details/index.md +86 -0
package/wiki/references/src-details/inversion.md +1 -6
package/wiki/references/src-details/mcp-server.md +3 -15
package/wiki/references/utilities/index.md +86 -10
package/wiki/references/utilities/jsx.md +577 -0
package/wiki/references/utilities/request.md +0 -2
package/wiki/references/utilities/statuses.md +740 -0
package/wiki/get-started/best-practices/api-usage-examples.md +0 -266
package/wiki/get-started/best-practices/architectural-patterns.md +0 -170
package/wiki/get-started/best-practices/data-modeling.md +0 -177
package/wiki/get-started/best-practices/deployment-strategies.md +0 -121
package/wiki/get-started/best-practices/performance-optimization.md +0 -97
package/wiki/get-started/best-practices/security-guidelines.md +0 -99
package/wiki/get-started/core-concepts/persistent.md +0 -539
package/wiki/get-started/index.md +0 -65
package/wiki/get-started/philosophy.md +0 -296
package/wiki/get-started/prerequisites.md +0 -113

package/wiki/references/utilities/jsx.md ADDED Viewed

@@ -0,0 +1,577 @@
+---
+title: JSX/HTML Utilities Reference
+description: Utilities for HTML and JSX responses in OpenAPI routes
+difficulty: beginner
+lastUpdated: 2026-01-03
+---
+# JSX/HTML Utility
+The JSX utility provides helper functions for defining HTML/JSX response schemas in OpenAPI routes. These utilities are companions to `jsonContent` and `jsonResponse` but for HTML content type.
+**File:** `packages/core/src/utilities/jsx.utility.ts`
+## Quick Reference
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `htmlContent()` | Create HTML content configuration | OpenAPI content object |
+| `htmlResponse()` | Create HTML response with error handling | OpenAPI response object |
+## When to Use
+Use these utilities when creating routes that:
+- Render HTML pages using Hono JSX
+- Return server-side rendered content
+- Serve HTML documentation or views
+- Generate HTML emails or reports
+## htmlContent()
+Creates a standard OpenAPI content object for `text/html` responses.
+### Signature
+```typescript
+function htmlContent(opts: {
+  description: string;
+  required?: boolean;
+}): {
+  description: string;
+  content: {
+    'text/html': {
+      schema: ZodString;
+    };
+  };
+  required: boolean;
+}
+```
+### Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | Yes | - | Description of the HTML content |
+| `required` | `boolean` | No | `false` | Whether the content is required |
+### Returns
+Returns an OpenAPI content configuration object with:
+- `description`: The provided description
+- `content`: Content type configuration for `text/html`
+- `required`: Whether the content is required
+### Example
+```typescript
+import { htmlContent } from '@venizia/ignis';
+const pageContent = htmlContent({
+  description: 'HTML page content',
+  required: true,
+});
+// Result:
+// {
+//   description: 'HTML page content',
+//   content: {
+//     'text/html': {
+//       schema: z.string().openapi({
+//         description: 'HTML content',
+//         example: '<!DOCTYPE html><html>...</html>',
+//       }),
+//     },
+//   },
+//   required: true,
+// }
+```
+---
+## htmlResponse()
+Creates a standard OpenAPI response object for HTML endpoints, including success (200 OK) HTML response and JSON error responses for 4xx/5xx status codes.
+### Signature
+```typescript
+function htmlResponse(opts: {
+  description: string;
+  required?: boolean;
+}): {
+  200: typeof htmlContent;
+  '4xx | 5xx': {
+    description: 'Error Response';
+    content: {
+      'application/json': {
+        schema: ErrorSchema;
+      };
+    };
+  };
+}
+```
+### Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | Yes | - | Description of the successful HTML response |
+| `required` | `boolean` | No | `false` | Whether the content is required |
+### Returns
+Returns an OpenAPI responses object with:
+- `200`: Success response with HTML content
+- `4xx | 5xx`: Error responses with JSON error schema
+### Example
+```typescript
+import { htmlResponse } from '@venizia/ignis';
+this.defineRoute({
+  configs: {
+    path: '/dashboard',
+    method: 'get',
+    responses: htmlResponse({
+      description: 'Dashboard HTML page',
+    }),
+  },
+  handler: async (context) => {
+    return context.html(
+      <html>
+        <head>
+          <title>Dashboard</title>
+        </head>
+        <body>
+          <h1>Welcome to Dashboard</h1>
+        </body>
+      </html>
+    );
+  },
+});
+```
+---
+## Usage Examples
+### Basic HTML Route
+```typescript
+import { BaseController, get, htmlResponse } from '@venizia/ignis';
+export class PageController extends BaseController {
+  @get({
+    path: '/home',
+    responses: htmlResponse({
+      description: 'Home page HTML',
+    }),
+  })
+  async getHomePage() {
+    return this.context.html(
+      <html>
+        <head>
+          <title>Home</title>
+        </head>
+        <body>
+          <h1>Welcome Home</h1>
+        </body>
+      </html>
+    );
+  }
+}
+```
+### HTML Email Preview
+```typescript
+import { BaseController, get, htmlResponse, TRouteContext, HTTP, z } from '@venizia/ignis';
+const EmailRoutes = {
+  PREVIEW: {
+    method: HTTP.Methods.GET,
+    path: '/preview/:templateId',
+    request: {
+      params: z.object({ templateId: z.string() }),
+    },
+    responses: htmlResponse({
+      description: 'Email template preview',
+    }),
+  },
+} as const;
+export class EmailController extends BaseController {
+  @get({ configs: EmailRoutes.PREVIEW })
+  async previewTemplate(c: TRouteContext<typeof EmailRoutes.PREVIEW>) {
+    const { templateId } = c.req.valid('param');
+    const template = await this.emailService.getTemplate(templateId);
+    return c.html(
+      <html>
+        <head>
+          <title>Email Preview: {template.subject}</title>
+        </head>
+        <body>
+          <div dangerouslySetInnerHTML={{ __html: template.html }} />
+        </body>
+      </html>
+    );
+  }
+}
+```
+### Documentation Page
+```typescript
+import { BaseController, get, htmlResponse, TRouteContext, HTTP, z } from '@venizia/ignis';
+const DocsRoutes = {
+  GET_SECTION: {
+    method: HTTP.Methods.GET,
+    path: '/docs/:section',
+    request: {
+      params: z.object({ section: z.string() }),
+    },
+    responses: htmlResponse({
+      description: 'API documentation page',
+    }),
+  },
+} as const;
+export class DocsController extends BaseController {
+  @get({ configs: DocsRoutes.GET_SECTION })
+  async getDocumentation(c: TRouteContext<typeof DocsRoutes.GET_SECTION>) {
+    const { section } = c.req.valid('param');
+    const content = await this.docsService.getSection(section);
+    return c.html(
+      <html>
+        <head>
+          <title>Docs - {content.title}</title>
+          <link rel="stylesheet" href="/styles/docs.css" />
+        </head>
+        <body>
+          <nav>
+            <a href="/docs/getting-started">Getting Started</a>
+            <a href="/docs/api">API Reference</a>
+          </nav>
+          <main>
+            <h1>{content.title}</h1>
+            <div dangerouslySetInnerHTML={{ __html: content.html }} />
+          </main>
+        </body>
+      </html>
+    );
+  }
+}
+```
+### Admin Dashboard
+```typescript
+import { BaseController, get, htmlResponse } from '@venizia/ignis';
+import { authenticate } from '../middleware/auth';
+export class AdminController extends BaseController {
+  @get({
+    path: '/admin',
+    middleware: [authenticate({ role: 'admin' })],
+    responses: htmlResponse({
+      description: 'Admin dashboard',
+    }),
+  })
+  async getDashboard() {
+    const stats = await this.statsService.getAdminStats();
+    return this.context.html(
+      <html>
+        <head>
+          <title>Admin Dashboard</title>
+          <script src="/js/dashboard.js" defer />
+        </head>
+        <body>
+          <div class="dashboard">
+            <h1>Admin Dashboard</h1>
+            <div class="stats">
+              <div class="stat-card">
+                <h3>Total Users</h3>
+                <p>{stats.totalUsers}</p>
+              </div>
+              <div class="stat-card">
+                <h3>Active Sessions</h3>
+                <p>{stats.activeSessions}</p>
+              </div>
+            </div>
+          </div>
+        </body>
+      </html>
+    );
+  }
+}
+```
+---
+## Comparison with JSON Utilities
+### htmlContent vs jsonContent
+| Aspect | `htmlContent()` | `jsonContent()` |
+|--------|----------------|-----------------|
+| **Content-Type** | `text/html` | `application/json` |
+| **Schema** | `z.string()` | Custom Zod schema |
+| **Use Case** | HTML pages, JSX rendering | API responses, data |
+| **Example** | HTML document string | JSON object |
+### htmlResponse vs jsonResponse
+| Aspect | `htmlResponse()` | `jsonResponse()` |
+|--------|------------------|------------------|
+| **Success Type** | `text/html` (200) | `application/json` (200) |
+| **Error Type** | `application/json` (4xx/5xx) | `application/json` (4xx/5xx) |
+| **Use Case** | Web pages | REST APIs |
+---
+## Best Practices
+### 1. Use for Server-Side Rendering
+```typescript
+// ✅ Good: Use htmlResponse for SSR routes
+const ProfileConfig = {
+  method: HTTP.Methods.GET,
+  path: '/profile/:userId',
+  request: { params: z.object({ userId: z.string() }) },
+  responses: htmlResponse({ description: 'User profile page' }),
+} as const;
+@get({ configs: ProfileConfig })
+async getUserProfile(c: TRouteContext<typeof ProfileConfig>) {
+  const { userId } = c.req.valid('param');
+  const user = await this.userService.getUser(userId);
+  return c.html(<UserProfile user={user} />);
+}
+// ❌ Bad: Don't use htmlResponse for API endpoints
+const BadConfig = {
+  method: HTTP.Methods.GET,
+  path: '/api/users/:userId',
+  request: { params: z.object({ userId: z.string() }) },
+  responses: htmlResponse({ description: 'User data' }), // Wrong!
+} as const;
+@get({ configs: BadConfig })
+async getUser(c: TRouteContext<typeof BadConfig>) {
+  const { userId } = c.req.valid('param');
+  return { id: userId, name: 'John' }; // Should use jsonResponse
+}
+```
+### 2. Combine with Authentication
+```typescript
+// ✅ Good: Protect HTML routes with auth
+const SettingsConfig = {
+  method: HTTP.Methods.GET,
+  path: '/admin/settings',
+  authStrategies: [Authentication.STRATEGY_JWT],
+  responses: htmlResponse({ description: 'Settings page' }),
+} as const;
+@get({ configs: SettingsConfig })
+async getSettings(c: TRouteContext<typeof SettingsConfig>) {
+  return c.html(<SettingsPage />);
+}
+```
+### 3. Error Handling
+HTML routes automatically return JSON errors for 4xx/5xx:
+```typescript
+const ArticleConfig = {
+  method: HTTP.Methods.GET,
+  path: '/article/:id',
+  request: { params: z.object({ id: z.string() }) },
+  responses: htmlResponse({ description: 'Article page' }),
+} as const;
+@get({ configs: ArticleConfig })
+async getArticle(c: TRouteContext<typeof ArticleConfig>) {
+  const { id } = c.req.valid('param');
+  const article = await this.articleService.findById(id);
+  if (!article) {
+    // Returns JSON error: { message: 'Not found', statusCode: 404 }
+    throw new NotFoundError('Article not found');
+  }
+  return c.html(<ArticlePage article={article} />);
+}
+```
+### 4. SEO-Friendly Metadata
+```typescript
+const BlogConfig = {
+  method: HTTP.Methods.GET,
+  path: '/blog/:slug',
+  request: { params: z.object({ slug: z.string() }) },
+  responses: htmlResponse({ description: 'Blog post page' }),
+} as const;
+@get({ configs: BlogConfig })
+async getBlogPost(c: TRouteContext<typeof BlogConfig>) {
+  const { slug } = c.req.valid('param');
+  const post = await this.blogService.getBySlug(slug);
+  return c.html(
+    <html>
+      <head>
+        <title>{post.title} | My Blog</title>
+        <meta name="description" content={post.excerpt} />
+        <meta property="og:title" content={post.title} />
+        <meta property="og:description" content={post.excerpt} />
+        <meta property="og:image" content={post.coverImage} />
+      </head>
+      <body>
+        <article>
+          <h1>{post.title}</h1>
+          <div dangerouslySetInnerHTML={{ __html: post.content }} />
+        </article>
+      </body>
+    </html>
+  );
+}
+```
+---
+## Integration with Hono JSX
+IGNIS uses Hono's built-in JSX support. Make sure to configure your `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  }
+}
+```
+### JSX Components
+```typescript
+// components/Layout.tsx
+export const Layout = (props: { title: string; children: any }) => {
+  return (
+    <html>
+      <head>
+        <title>{props.title}</title>
+        <link rel="stylesheet" href="/styles/main.css" />
+      </head>
+      <body>
+        <header>
+          <nav>
+            <a href="/">Home</a>
+            <a href="/about">About</a>
+          </nav>
+        </header>
+        <main>{props.children}</main>
+        <footer>
+          <p>&copy; 2026 My App</p>
+        </footer>
+      </body>
+    </html>
+  );
+};
+// controller.ts
+import { Layout } from './components/Layout';
+@get({
+  path: '/',
+  responses: htmlResponse({ description: 'Home page' }),
+})
+async getHome() {
+  return this.context.html(
+    <Layout title="Home">
+      <h1>Welcome to My App</h1>
+      <p>This is the home page.</p>
+    </Layout>
+  );
+}
+```
+---
+## Common Pitfalls
+### Pitfall 1: Missing HTML Wrapper
+```typescript
+// ❌ Bad: Incomplete HTML
+@get({
+  path: '/page',
+  responses: htmlResponse({ description: 'Page' }),
+})
+async getPage() {
+  return this.context.html(<div>Hello</div>); // Missing <html>, <head>, <body>
+}
+// ✅ Good: Complete HTML document
+@get({
+  path: '/page',
+  responses: htmlResponse({ description: 'Page' }),
+})
+async getPage() {
+  return this.context.html(
+    <html>
+      <head><title>Page</title></head>
+      <body><div>Hello</div></body>
+    </html>
+  );
+}
+```
+### Pitfall 2: Using htmlResponse for APIs
+```typescript
+// ❌ Bad: HTML response for API
+@get({
+  path: '/api/users',
+  responses: htmlResponse({ description: 'Users' }),
+})
+async getUsers() {
+  return { users: [...] }; // Should return HTML or use jsonResponse
+}
+// ✅ Good: Use jsonResponse for APIs
+@get({
+  path: '/api/users',
+  responses: jsonResponse({
+    description: 'Users list',
+    schema: z.object({ users: z.array(UserSchema) }),
+  }),
+})
+async getUsers() {
+  return { users: await this.userService.findAll() };
+}
+```
+---
+## See Also
+- **Related References:**
+  - [Schema Utility](./schema.md) - JSON content and response helpers
+  - [Controllers](../base/controllers.md) - Defining routes and handlers
+  - [OpenAPI Component](../components/swagger.md) - API documentation
+- **External Resources:**
+  - [Hono JSX Documentation](https://hono.dev/guides/jsx)
+  - [OpenAPI Specification](https://swagger.io/specification/)
+  - [React JSX (for reference)](https://react.dev/learn/writing-markup-with-jsx)

package/wiki/references/utilities/request.md CHANGED Viewed

@@ -139,7 +139,6 @@ sanitizeFilename('');                        // Returns: 'download'
 sanitizeFilename('..');                      // Returns: 'download'
 ```
----
 ### `encodeRFC5987`
@@ -160,7 +159,6 @@ encodeRFC5987('my document.pdf');     // Returns: 'my%20document.pdf'
 encodeRFC5987('файл.txt');            // Returns: '%D1%84%D0%B0%D0%B9%D0%BB.txt'
 ```
----
 ## Complete File Download Example