@venizia/ignis-docs 0.0.6-2 → 0.0.7-0

package/wiki/references/base/controllers.md

@@ -58,7 +58,8 @@ For decorator-based routes, you do not need to explicitly annotate the return ty
 The generic `@api` decorator allows you to define a route with a full configuration object. The decorated method will automatically have its `context` parameter and return type inferred and type-checked against the provided route configuration. This ensures strong type safety throughout your API definitions.
 
 ```typescript
-import { api, BaseController, controller, HTTP, jsonContent, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { api, BaseController, controller, jsonContent, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 const MyRouteConfig = {
   method: 'get',
@@ -89,7 +90,8 @@ For convenience, `Ignis` provides decorator shortcuts for each HTTP method: Thes
 **Example using `@get` and `@post`:**
 
 ```typescript
-import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext, HTTP } from '@venizia/ignis';
+import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 // Define route configs as const
 const UserRoutes = {
@@ -153,7 +155,8 @@ const UserRoutes = {
 For better organization, you can define all your route configurations in a constant and reference them in your decorators. This approach also allows you to get a typed context for your handler.
 
 ```typescript
-import { api, BaseController, controller, TRouteContext, jsonContent, jsonResponse, HTTP } from '@venizia/ignis';
+import { api, BaseController, controller, TRouteContext, jsonContent, jsonResponse } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from 'hono/zod-openapi';
 
 const RouteConfigs = {
@@ -264,7 +267,8 @@ request: {
 The `defineRouteConfigs` function is a simple helper for creating a typed object containing multiple route configurations. This is particularly useful for organizing all of a controller's route definitions in a single, type-checked constant.
 
 ```typescript
-import { defineRouteConfigs, HTTP, jsonResponse, jsonContent, z } from '@venizia/ignis';
+import { defineRouteConfigs, jsonResponse, jsonContent, z } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 const RouteConfigs = defineRouteConfigs({
   ROOT: {
@@ -377,12 +381,14 @@ When resolving authentication for a route, the following priority applies:
 ### Authentication Examples
 
 ```typescript
+import { Authentication, ControllerFactory } from '@venizia/ignis';
+
 // 1. JWT auth on ALL routes
 const UserController = ControllerFactory.defineCrudController({
   entity: UserEntity,
   repository: { name: 'UserRepository' },
   controller: { name: 'UserController', basePath: '/users' },
-  authStrategies: ['jwt'],
+  authStrategies: [Authentication.STRATEGY_JWT],
 });
 
 // 2. JWT auth on all, but skip for public read endpoints
@@ -390,7 +396,7 @@ const ProductController = ControllerFactory.defineCrudController({
   entity: ProductEntity,
   repository: { name: 'ProductRepository' },
   controller: { name: 'ProductController', basePath: '/products' },
-  authStrategies: ['jwt'],
+  authStrategies: [Authentication.STRATEGY_JWT],
   routes: {
     find: { skipAuth: true },
     findById: { skipAuth: true },
@@ -404,9 +410,9 @@ const ArticleController = ControllerFactory.defineCrudController({
   repository: { name: 'ArticleRepository' },
   controller: { name: 'ArticleController', basePath: '/articles' },
   routes: {
-    create: { authStrategies: ['jwt'] },
-    updateById: { authStrategies: ['jwt'] },
-    deleteById: { authStrategies: ['jwt'] },
+    create: { authStrategies: [Authentication.STRATEGY_JWT] },
+    updateById: { authStrategies: [Authentication.STRATEGY_JWT] },
+    deleteById: { authStrategies: [Authentication.STRATEGY_JWT] },
   },
 });
 
@@ -415,7 +421,7 @@ const OrderController = ControllerFactory.defineCrudController({
   entity: OrderEntity,
   repository: { name: 'OrderRepository' },
   controller: { name: 'OrderController', basePath: '/orders' },
-  authStrategies: ['jwt'],
+  authStrategies: [Authentication.STRATEGY_JWT],
   routes: {
     find: {
       skipAuth: true,
@@ -432,6 +438,7 @@ const OrderController = ControllerFactory.defineCrudController({
 ### Route Customization Examples
 
 ```typescript
+import { Authentication, ControllerFactory } from '@venizia/ignis';
 import { z } from '@hono/zod-openapi';
 
 // Custom request body for create
@@ -453,7 +460,7 @@ const UserController = ControllerFactory.defineCrudController({
   entity: UserEntity,
   repository: { name: 'UserRepository' },
   controller: { name: 'UserController', basePath: '/users' },
-  authStrategies: ['jwt'],
+  authStrategies: [Authentication.STRATEGY_JWT],
   routes: {
     // Public read endpoints
     find: {
@@ -473,7 +480,7 @@ const UserController = ControllerFactory.defineCrudController({
 
     // Delete requires JWT auth (uses default schema)
     deleteById: {
-      authStrategies: ['jwt'],
+      authStrategies: [Authentication.STRATEGY_JWT],
     },
   },
 });

package/wiki/references/base/middlewares.md

@@ -294,7 +294,8 @@ app.use(requestSpy.value());
 #### Accessing Request ID
 
 ```typescript
-import { RequestSpyMiddleware, get, HTTP, jsonResponse, TRouteContext, z } from '@venizia/ignis';
+import { RequestSpyMiddleware, get, jsonResponse, TRouteContext, z } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 
 const ExampleConfig = {
   method: HTTP.Methods.GET,

package/wiki/references/base/models.md

@@ -32,7 +32,7 @@ Fundamental building block wrapping a Drizzle ORM schema.
 | **Schema Encapsulation** | Holds Drizzle `pgTable` schema for consistent repository access |
 | **Metadata** | Works with `@model` decorator to mark database entities |
 | **Schema Generation** | Uses `drizzle-zod` to generate Zod schemas (`SELECT`, `CREATE`, `UPDATE`) |
-| **Static Properties** | Supports static `schema`, `relations`, and `TABLE_NAME` for cleaner syntax |
+| **Static Properties** | Supports static `schema`, `relations`, `TABLE_NAME`, and `AUTHORIZATION_SUBJECT` |
 | **Convenience** | Includes `toObject()` and `toJSON()` methods |
 
 ### The `@model` Decorator
@@ -49,6 +49,10 @@ The `@model` decorator marks a class as a database entity and configures its beh
   settings?: {
     hiddenProperties?: string[],  // Properties to exclude from query results
     defaultFilter?: TFilter,      // Filter applied to all repository queries
+    authorize?: {                  // Authorization settings
+      principal: string,           // Authorization subject name
+      [extra: string | symbol]: any, // Extensible metadata
+    },
   }
 })
 ```
@@ -60,6 +64,8 @@ The `@model` decorator marks a class as a database entity and configures its beh
 | `skipMigrate` | `boolean` | Skip this model during schema migrations |
 | `settings.hiddenProperties` | `string[]` | Array of property names to exclude from all repository query results |
 | `settings.defaultFilter` | `TFilter` | Filter automatically applied to all repository queries (see [Default Filter](/references/base/filter-system/default-filter)) |
+| `settings.authorize` | `IModelAuthorizeSettings` | Authorization settings — declares the model's authorization principal (see [Authorization](/references/components/authorization/usage#model-based-resource-references)) |
+| `settings.authorize.principal` | `string` | The authorization subject name for this model. Auto-populates `AUTHORIZATION_SUBJECT` static property |
 
 ### Hidden Properties
 
@@ -233,6 +239,7 @@ export class User extends BaseEntity<typeof userTable> {
 | `schema` | `TTableSchemaWithId` | Drizzle table schema defined with `pgTable()` |
 | `relations` | `TValueOrResolver<Array<TRelationConfig>>` | Relation definitions (can be a function for lazy loading) |
 | `TABLE_NAME` | `string \| undefined` | Optional table name (defaults to class name if not set) |
+| `AUTHORIZATION_SUBJECT` | `string \| undefined` | Authorization principal name. Auto-populated from `@model` settings `authorize.principal` |
 
 ### IEntity Interface
 
@@ -269,6 +276,7 @@ export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
   static schema: TTableSchemaWithId;
   static relations?: TValueOrResolver<Array<TRelationConfig>>;
   static TABLE_NAME?: string;  // Optional, defaults to class name
+  static AUTHORIZATION_SUBJECT?: string;  // Auto-set by @model decorator from authorize.principal
 
   // Static singleton for schemaFactory - shared across all instances
   // Performance optimization: avoids creating new factory per entity
@@ -902,7 +910,8 @@ console.log(result);
 **Use case:** API endpoint that accepts snake_case but works with camelCase internally
 
 ```typescript
-import { BaseController, controller, snakeToCamel, HTTP } from '@venizia/ignis';
+import { BaseController, controller, snakeToCamel } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 
 const createUserSchema = snakeToCamel({

package/wiki/references/base/services.md

@@ -64,7 +64,8 @@ Services are the core of your application's logic. They act as a bridge between
 ### Example
 
 ```typescript
-import { BaseService, inject, getError } from '@venizia/ignis';
+import { BaseService, inject } from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
 import { UserRepository } from '../repositories/user.repository';
 import { TUser } from '../models/entities';