npm - @venizia/ignis-docs - Versions diffs - 0.2.0 → 0.2.1-0 - Mend

@venizia/ignis-docs 0.2.0 → 0.2.1-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 (142) hide show

package/README.md +14 -14
package/content/best-practices/api-usage-examples.md +39 -19
package/content/best-practices/architectural-patterns.md +22 -11
package/content/best-practices/architecture-decisions.md +29 -16
package/content/best-practices/code-style-standards/advanced-patterns.md +43 -31
package/content/best-practices/code-style-standards/constants-configuration.md +19 -4
package/content/best-practices/code-style-standards/control-flow.md +33 -1
package/content/best-practices/code-style-standards/documentation.md +28 -8
package/content/best-practices/code-style-standards/function-patterns.md +15 -4
package/content/best-practices/code-style-standards/index.md +7 -2
package/content/best-practices/code-style-standards/naming-conventions.md +26 -2
package/content/best-practices/code-style-standards/route-definitions.md +9 -5
package/content/best-practices/code-style-standards/tooling.md +14 -1
package/content/best-practices/code-style-standards/type-safety.md +39 -6
package/content/best-practices/common-pitfalls.md +59 -35
package/content/best-practices/contribution-workflow.md +6 -2
package/content/best-practices/data-modeling.md +78 -62
package/content/best-practices/deployment-strategies.md +56 -19
package/content/best-practices/error-handling.md +182 -93
package/content/best-practices/index.md +6 -0
package/content/best-practices/performance-optimization.md +26 -13
package/content/best-practices/security-guidelines.md +35 -9
package/content/best-practices/testing-strategies.md +7 -2
package/content/best-practices/troubleshooting-tips.md +27 -17
package/content/extensions/components/api-reference.md +107 -322
package/content/extensions/components/authentication/api.md +454 -603
package/content/extensions/components/authentication/errors.md +121 -498
package/content/extensions/components/authentication/index.md +88 -801
package/content/extensions/components/authentication/usage.md +207 -956
package/content/extensions/components/authorization/api.md +736 -656
package/content/extensions/components/authorization/errors.md +168 -206
package/content/extensions/components/authorization/index.md +82 -797
package/content/extensions/components/authorization/usage.md +194 -527
package/content/extensions/components/health-check.md +71 -243
package/content/extensions/components/mail/api.md +504 -287
package/content/extensions/components/mail/errors.md +73 -61
package/content/extensions/components/mail/index.md +96 -467
package/content/extensions/components/mail/usage.md +130 -172
package/content/extensions/components/request-tracker.md +66 -173
package/content/extensions/components/socket-io/api.md +195 -13
package/content/extensions/components/socket-io/errors.md +3 -3
package/content/extensions/components/socket-io/index.md +50 -337
package/content/extensions/components/socket-io/usage.md +143 -26
package/content/extensions/components/static-asset/api.md +410 -142
package/content/extensions/components/static-asset/errors.md +110 -53
package/content/extensions/components/static-asset/index.md +79 -608
package/content/extensions/components/static-asset/usage.md +180 -300
package/content/extensions/components/websocket/api.md +275 -399
package/content/extensions/components/websocket/errors.md +47 -56
package/content/extensions/components/websocket/index.md +74 -407
package/content/extensions/components/websocket/usage.md +110 -341
package/content/extensions/helpers/cron/index.md +51 -160
package/content/extensions/helpers/crypto/index.md +62 -483
package/content/extensions/helpers/crypto/reference.md +456 -0
package/content/extensions/helpers/env/index.md +60 -178
package/content/extensions/helpers/error/index.md +221 -207
package/content/extensions/helpers/inversion/index.md +65 -556
package/content/extensions/helpers/inversion/reference.md +522 -0
package/content/extensions/helpers/kafka/admin.md +20 -1
package/content/extensions/helpers/kafka/compile-binary.md +41 -35
package/content/extensions/helpers/kafka/consumer.md +54 -20
package/content/extensions/helpers/kafka/examples.md +21 -16
package/content/extensions/helpers/kafka/index.md +80 -610
package/content/extensions/helpers/kafka/producer.md +134 -5
package/content/extensions/helpers/kafka/schema-registry.md +45 -70
package/content/extensions/helpers/logger/hf-logger.md +193 -0
package/content/extensions/helpers/logger/index.md +64 -563
package/content/extensions/helpers/logger/pino.md +85 -0
package/content/extensions/helpers/logger/reference.md +746 -0
package/content/extensions/helpers/network/api.md +241 -195
package/content/extensions/helpers/network/index.md +72 -530
package/content/extensions/helpers/queue/index.md +72 -900
package/content/extensions/helpers/queue/reference.md +467 -0
package/content/extensions/helpers/redis/index.md +73 -645
package/content/extensions/helpers/redis/reference.md +727 -0
package/content/extensions/helpers/secrets/index.md +66 -0
package/content/extensions/helpers/socket-io/api.md +305 -203
package/content/extensions/helpers/socket-io/index.md +66 -432
package/content/extensions/helpers/storage/api.md +564 -462
package/content/extensions/helpers/storage/index.md +77 -573
package/content/extensions/helpers/types/index.md +66 -499
package/content/extensions/helpers/types/reference.md +650 -0
package/content/extensions/helpers/uid/index.md +58 -227
package/content/extensions/helpers/websocket/api.md +329 -216
package/content/extensions/helpers/websocket/index.md +65 -503
package/content/extensions/helpers/worker-thread/index.md +58 -396
package/content/extensions/helpers/worker-thread/reference.md +428 -0
package/content/guides/core-concepts/persistent/models.md +1 -1
package/content/guides/core-concepts/persistent/search-typesense.md +3 -3
package/content/guides/core-concepts/persistent/transactions.md +1 -1
package/content/guides/core-concepts/secrets-vault.md +177 -0
package/content/guides/core-concepts/services.md +1 -1
package/content/guides/migrations/redis-helpers-migration.md +1 -1
package/content/guides/migrations/unified-connectors-migration.md +2 -2
package/content/guides/tutorials/ecommerce-api.md +3 -8
package/content/references/base/application.md +1 -1
package/content/references/base/connectors.md +79 -136
package/content/references/base/datasources-reference.md +599 -0
package/content/references/base/datasources.md +84 -444
package/content/references/base/dependency-injection.md +17 -39
package/content/references/base/filter-system/application-usage.md +69 -121
package/content/references/base/filter-system/array-operators.md +12 -0
package/content/references/base/filter-system/comparison-operators.md +12 -0
package/content/references/base/filter-system/default-filter.md +136 -348
package/content/references/base/filter-system/fields-order-pagination.md +38 -16
package/content/references/base/filter-system/index.md +106 -257
package/content/references/base/filter-system/json-filtering.md +12 -2
package/content/references/base/filter-system/list-operators.md +16 -2
package/content/references/base/filter-system/logical-operators.md +13 -0
package/content/references/base/filter-system/null-operators.md +13 -0
package/content/references/base/filter-system/pattern-matching.md +12 -0
package/content/references/base/filter-system/quick-reference.md +11 -2
package/content/references/base/filter-system/range-operators.md +12 -0
package/content/references/base/filter-system/tips.md +70 -133
package/content/references/base/filter-system/use-cases.md +156 -233
package/content/references/base/middlewares.md +35 -21
package/content/references/base/models-reference.md +886 -0
package/content/references/base/models.md +80 -1452
package/content/references/base/repositories/advanced.md +156 -192
package/content/references/base/repositories/index.md +77 -650
package/content/references/base/repositories/mixins.md +22 -18
package/content/references/base/repositories/relations.md +123 -171
package/content/references/base/repositories/soft-deletable.md +58 -56
package/content/references/base/secrets.md +263 -0
package/content/references/base/services.md +2 -2
package/content/references/configuration/environment-variables.md +48 -4
package/content/references/configuration/index.md +49 -31
package/content/references/quick-reference.md +3 -16
package/content/references/utilities/crypto.md +35 -76
package/content/references/utilities/date.md +33 -73
package/content/references/utilities/index.md +1 -1
package/content/references/utilities/jsx-reference.md +298 -0
package/content/references/utilities/jsx.md +82 -525
package/content/references/utilities/module.md +29 -62
package/content/references/utilities/parse.md +34 -64
package/content/references/utilities/performance.md +33 -58
package/content/references/utilities/promise.md +28 -62
package/content/references/utilities/request.md +57 -218
package/content/references/utilities/schema.md +43 -137
package/content/references/utilities/statuses-reference.md +361 -0
package/content/references/utilities/statuses.md +63 -667
package/package.json +8 -8

package/content/references/utilities/jsx-reference.md ADDED Viewed

@@ -0,0 +1,298 @@
+---
+title: JSX/HTML Utility - Full Reference
+description: Complete reference for the JSX/HTML response helpers, defineJSXRoute, and Hono JSX component patterns
+difficulty: beginner
+---
+# JSX/HTML Utility - Full Reference
+Exhaustive reference for `htmlContent()`, `htmlResponse()`, and `BaseRestController.defineJSXRoute()`. For a readable introduction and the common tasks, start with the [JSX/HTML overview](/references/utilities/jsx).
+**Files:**
+- [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts) - `htmlContent`, `htmlResponse`
+- [`packages/core/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/base.ts) - `BaseRestController.defineJSXRoute`
+- [`packages/core/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/abstract.ts) - `AbstractRestController.getJSXRouteConfigs`
+- [`packages/helpers/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/types.ts) - `FC`, `PropsWithChildren`, `Child` (re-exported from `hono/jsx`)
+## `htmlContent()`
+Creates a standard OpenAPI content object for `text/html` responses.
+`Source ->` [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts)
+```typescript
+const htmlContent = (opts: { description: string; required?: boolean }) => ({
+  description: opts.description,
+  content: {
+    'text/html': {
+      schema: z.string().openapi({
+        description: 'HTML content',
+        example: '<!DOCTYPE html><html><head><title>Page</title></head><body>...</body></html>',
+      }),
+    },
+  },
+  required: opts.required ?? false,
+});
+```
+### Parameters
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | Yes | - | Description of the HTML content, shown in the generated OpenAPI document |
+| `required` | `boolean` | No | `false` | Whether the content is required |
+### Returns
+An OpenAPI content configuration object: `description`, `content['text/html'].schema` (a `z.string()`), and `required`.
+## `htmlResponse()`
+Creates a standard OpenAPI response object for HTML endpoints: a success (`200`) HTML response plus a JSON error response for `4xx | 5xx` status codes using `ErrorSchema`.
+`Source ->` [`packages/core/src/utilities/jsx.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/jsx.utility.ts)
+```typescript
+const htmlResponse = (opts: { description: string; required?: boolean }) => ({
+  [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: opts.description, required: opts.required }),
+  ['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
+A responses object: `200` (via `htmlContent()`) plus `4xx | 5xx` (JSON `ErrorSchema`).
+```typescript
+import { htmlResponse } from '@venizia/ignis';
+this.defineRoute({
+  configs: {
+    path: '/dashboard',
+    method: 'get',
+    responses: htmlResponse({ description: 'Dashboard HTML page' }),
+  },
+  handler: c => c.html(<h1>Dashboard</h1>),
+});
+```
+## `BaseRestController.defineJSXRoute()`
+Defines and registers a JSX/HTML route in a single call - the JSX counterpart of `defineRoute()`.
+`Source ->` [`packages/core/src/base/controllers/rest/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/base.ts)
+```typescript
+defineJSXRoute<RouteConfig extends IAuthRouteConfig, ResponseType = unknown>(opts: {
+  configs: RouteConfig;
+  handler: TRouteHandler<ResponseType, RouteEnv>;
+  hook?: Hook<any, RouteEnv, string, ValueOrPromise<any>>;
+}): IDefineRouteOptions<RouteConfig, RouteEnv, RouteSchema, BasePath>
+```
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `configs` | `RouteConfig` (extends `IAuthRouteConfig`) | Yes | `path`, `method`, `responses`, plus the same `authenticate`/`authorize`/`request`/`middleware` fields `defineRoute` accepts |
+| `handler` | `TRouteHandler<ResponseType, RouteEnv>` | Yes | Receives the route context (`TRouteContext`); return `c.html(<Component />)` |
+| `hook` | `Hook<...>` | No | Same validation hook `defineRoute` accepts |
+### Behavior
+`defineJSXRoute` is `defineRoute` with one difference: it builds the route configuration through `getJSXRouteConfigs` instead of `getRouteConfigs`.
+`Source ->` [`packages/core/src/base/controllers/rest/abstract.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/rest/abstract.ts)
+```typescript
+getJSXRouteConfigs<RouteConfig extends IAuthRouteConfig>(opts: { configs: RouteConfig }) {
+  const { restConfig, security, mws } = this.buildRouteMiddlewares(opts);
+  const { responses, tags = [] } = restConfig;
+  return createRoute<string, RouteConfig>(
+    Object.assign({}, restConfig, {
+      middleware: mws,
+      responses: Object.assign({}, htmlResponse({ description: 'HTML page' }), responses),
+      tags: [...tags, this.scope],
+      security,
+    }) as any,
+  );
+}
+```
+- **Default response merged in first.** `htmlResponse({ description: 'HTML page' })` is the base object; your own `responses` is merged over it with `Object.assign`, so any status code you declare (typically `200`) overrides the default entry with the same key.
+- **Everything else matches `defineRoute`.** Auth middleware, tags (`this.scope` is always appended), and OpenAPI security are built the same way as JSON routes via `buildRouteMiddlewares`.
+- **Handler contract is unchanged.** The handler still returns whatever `c.html(...)` produces (a `Response`) - `defineJSXRoute` only changes how the route's OpenAPI shape is computed, not how the handler runs.
+## JSX setup
+### `tsconfig.json`
+`.tsx` files compile against Hono's JSX runtime, not React's:
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  }
+}
+```
+Verified in [`packages/core/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/tsconfig.json) and the JSX example app's [`examples/rpc-api-server/tsconfig.json`](https://github.com/VENIZIA-AI/ignis/blob/main/examples/rpc-api-server/tsconfig.json).
+### Component types
+`FC`, `PropsWithChildren`, and `Child` are re-exported from `@venizia/ignis-helpers` (sourced from `hono/jsx`) - import them from there rather than reaching into `hono/jsx` directly.
+`Source ->` [`packages/helpers/src/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/types.ts)
+```typescript
+export type { Child, FC, PropsWithChildren } from 'hono/jsx';
+```
+### No separate renderer
+IGNIS registers no `jsxRenderer` middleware and no template engine. A handler builds a JSX tree and calls Hono's own `c.html()` on it - that call is what triggers rendering to an HTML string.
+## Component patterns
+### Layout composition
+A layout component takes `children` (typed via `PropsWithChildren`) and wraps them in the surrounding document shell. Page components render into a layout the same way any JSX component nests another.
+```tsx
+import type { FC, PropsWithChildren } from '@venizia/ignis-helpers';
+interface MainLayoutProps {
+  title: string;
+  description?: string;
+}
+export const MainLayout: FC<PropsWithChildren<MainLayoutProps>> = ({ title, description, children }) => (
+  <html lang="en">
+    <head>
+      <meta charSet="UTF-8" />
+      <title>{title}</title>
+      {description && <meta name="description" content={description} />}
+    </head>
+    <body>
+      <main>{children}</main>
+    </body>
+  </html>
+);
+interface HomePageProps {
+  timestamp?: string;
+}
+export const HomePage: FC<HomePageProps> = ({ timestamp }) => (
+  <MainLayout title="Home" description="Welcome to IGNIS">
+    <h1>Welcome to IGNIS!</h1>
+    {timestamp && <p>Page rendered at: {timestamp}</p>}
+  </MainLayout>
+);
+```
+### Wiring pages into a controller
+```tsx
+import { BaseRestController, controller, htmlContent, type IControllerOptions, type ValueOrPromise } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
+import { HomePage } from '@/views/pages/home.page';
+@controller({ path: '/' })
+export class ViewController extends BaseRestController {
+  constructor(opts: IControllerOptions) {
+    super({ ...opts, scope: ViewController.name, path: '/' });
+  }
+  override binding(): ValueOrPromise<void> {
+    this.defineJSXRoute({
+      configs: {
+        path: '/',
+        method: 'get',
+        description: 'Home page rendered with JSX',
+        tags: ['Views'],
+        responses: {
+          [HTTP.ResultCodes.RS_2.Ok]: htmlContent({ description: 'Home page HTML' }),
+        },
+      },
+      handler: c => {
+        const timestamp = new Date().toISOString();
+        return c.html(<HomePage timestamp={timestamp} />);
+      },
+    });
+  }
+}
+```
+### Raw HTML with `dangerouslySetInnerHTML`
+Hono JSX's intrinsic elements accept a `dangerouslySetInnerHTML` prop - an object with an `__html` string - matching React's escape hatch. Use it only for HTML you already trust (a stored template, sanitized markdown output) - never for unsanitized user input.
+```tsx
+async previewTemplate(c: TRouteContext) {
+  const { templateId } = c.req.valid<{ templateId: string }>('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>,
+  );
+}
+```
+## Comparison with JSON utilities
+### `htmlContent` vs `jsonContent`
+| Aspect | `htmlContent()` | `jsonContent()` |
+|--------|------------------|-------------------|
+| Content type | `text/html` | `application/json` |
+| Schema | `z.string()` | Caller-supplied Zod schema |
+| Use case | HTML pages, JSX rendering | API responses, structured data |
+### `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 | Server-rendered web pages | REST APIs |
+See [Schema Utility](./schema.md) for `jsonContent`/`jsonResponse`.
+## Route definition choices
+`defineJSXRoute` is the recommended way to register a JSX route because it fills in a default HTML `200` response automatically. Two equivalent alternatives exist when you need more control:
+| Approach | When to use |
+|----------|-------------|
+| `this.defineJSXRoute({ configs, handler })` | Default choice - HTML response shape is inferred, override `responses[200]` only if you need a custom description |
+| `this.defineRoute({ configs: { responses: htmlResponse({ description }) }, handler })` | You want the full `responses` object built explicitly via `htmlResponse()`, without relying on the JSX default merge |
+| `this.bindRoute({ configs }).to({ handler })` | Fluent two-step registration, same `configs` shape as either of the above |
+Authentication and authorization on a JSX route use the same `configs.authenticate` / `configs.authorize` fields as JSON routes - see [Controllers](../base/controllers.md).
+## See also
+- [JSX/HTML overview](/references/utilities/jsx) - introduction and common tasks
+- [Schema Utility](./schema.md) - `jsonContent`, `jsonResponse`, and the wider response-helper family
+- [Controllers](../base/controllers.md) - `defineRoute`, `bindRoute`, route configuration, authentication
+- **External:** [Hono JSX Documentation](https://hono.dev/docs/guides/jsx)