@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/best-practices/code-style-standards/documentation.md

@@ -2,6 +2,28 @@
 
 Use JSDoc comments for public APIs to improve IDE support and generate documentation.
 
+## Comment Style
+
+A comment states **only the constraint the code cannot show**. Keep it to 1-3 lines.
+
+Never write:
+
+- History or dates ("changed in June", "was previously async")
+- Decision narration ("we tried X, then chose Y")
+- A restatement of what the next line already says
+
+```typescript
+// ✅ GOOD - states a constraint the code cannot show
+// winston is an optional peer; a compiled binary must register a provider explicitly,
+// because only a class reference carries one into the bundle.
+LoggerFactory.use({ provider: PinoLogger });
+
+// ❌ BAD - restates the code, narrates history
+// 2026-07-18: after discussing with the team we decided to switch the logger
+// provider. This line calls use() on LoggerFactory and passes PinoLogger.
+LoggerFactory.use({ provider: PinoLogger });
+```
+
 ## When to Use JSDoc
 
 | Context | Required? | Reason |
@@ -56,10 +78,7 @@ async find(opts: { filter: TFilter<TUser>; options?: IExtraOptions }): Promise<T
 
 ```typescript
 /**
- * Creates a new user account with the given data.
- *
- * Validates that the email is unique, hashes the password,
- * and sends a welcome email upon successful creation.
+ * Creates a new user account. Email must be unique; the password is hashed here, never by the caller.
  *
  * @param data - User creation data
  * @returns The created user without sensitive fields
@@ -185,14 +204,14 @@ interface IJWTStrategyOptions {
  *
  * @example
  * @repository({ model: User, dataSource: PostgresDataSource })
- * export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+ * export class UserRepository extends DefaultRelationalRepository<typeof User.schema> {
  *   // Custom methods here
  * }
  *
- * @see {@link BasePostgresEntity} for model definition
- * @see {@link BasePostgresDataSource} for database connection
+ * @see {@link BaseRelationalEntity} for model definition
+ * @see {@link BaseRelationalDataSource} for database connection
  */
-class DefaultCRUDRepository<EntitySchema extends TTableSchemaWithId = TTableSchemaWithId> {
+class DefaultRelationalRepository<EntitySchema extends TTableSchemaWithId = TTableSchemaWithId> {
   // ...
 }
 ```
@@ -213,6 +232,7 @@ class DefaultCRUDRepository<EntitySchema extends TTableSchemaWithId = TTableSche
 - Don't copy TypeScript types into JSDoc (they're already visible)
 - Don't write multi-paragraph descriptions for simple functions
 - Don't use JSDoc for private implementation details
+- Don't record history, dates, or the reasoning behind a past change
 
 ## See Also
 

package/content/best-practices/code-style-standards/function-patterns.md

@@ -15,11 +15,12 @@ Avoid `export default` except for configuration files (e.g., `eslint.config.mjs`
 ```typescript
 // ✅ GOOD
 export class UserController { }
-export function createUser() { }
+export const createUser = () => { };
 export const DEFAULT_OPTIONS = { };
 
 // ❌ BAD
 export default class UserController { }
+export function createUser() { }   // arrow functions only, never `function`
 ```
 
 ## The Options Object Pattern
@@ -127,7 +128,8 @@ async syncData() {
 import { executeWithPerformanceMeasure } from '@venizia/ignis-helpers';
 
 await executeWithPerformanceMeasure({
-  logger: this.logger.for('syncData'),
+  logger: this.logger,
+  level: 'info',              // default: 'debug'
   scope: 'DataSync',
   description: 'Sync user records',
   task: async () => {
@@ -139,12 +141,18 @@ await executeWithPerformanceMeasure({
 
 **Method-scoped logging pattern:**
 
+Any class extending `BaseHelper` (services, controllers, repositories, helpers) already has
+`this.logger`. Acquire one standalone with `ApplicationLogger.get(...)` and always annotate
+`ILogger` - never a concrete provider class.
+
 ```typescript
+import { ApplicationLogger, ILogger } from '@venizia/ignis-helpers';
+
 class UserService {
-  private logger = Logger.get('UserService');
+  private logger: ILogger = ApplicationLogger.get('UserService');
 
   async createUser(data: TCreateUserRequest) {
-    // Use .for() to add method context to all logs
+    // .for() returns a method-scoped child logger
     this.logger.for('createUser').info('Creating user: %j', data);
     // Output: [UserService-createUser] Creating user: {...}
 
@@ -153,6 +161,7 @@ class UserService {
       this.logger.for('createUser').info('User created: %s', user.id);
       return user;
     } catch (error) {
+      // %s, not %j - `message` and `stack` are non-enumerable, so %j drops them
       this.logger.for('createUser').error('Failed: %s', error);
       throw error;
     }
@@ -160,6 +169,8 @@ class UserService {
 }
 ```
 
+Levels are exactly five, each a direct method: `debug`, `info`, `warn`, `error`, `emerg`.
+
 ## See Also
 
 - [Naming Conventions](./naming-conventions) - Class and file naming

package/content/best-practices/code-style-standards/index.md

@@ -17,13 +17,18 @@ Maintain consistent code style using **Prettier** (formatting) and **ESLint** (c
 | Error format | `[ClassName][method] Message` |
 | Logging format | `[method] Message \| Key: %s` |
 | Default options | `DEFAULT_OPTIONS` constant |
-| Type safety | No `any` or `unknown` allowed |
+| Type safety | Avoid `any` / `unknown`; derive types, never duplicate them |
+| Abbreviations | None - `ProductRepository`, `TDocument` |
 | Scope naming | `ClassName.name` |
 | Arguments | Options object (`opts`) |
+| Functions | Arrow functions, never `function` declarations |
 | Exports | Named exports only |
 | Return types | Explicitly defined |
 | Control flow | Always use braces (`{}`) |
 | Switch statements | Braces + default case required |
+| Catch blocks | Never silent - always log |
+| Errors | `getError` / `ApplicationError`, never `new Error` |
+| Logger | Type as `ILogger`; `this.logger` or `ApplicationLogger.get(...)` |
 | Imports | Node → Third-party → Internal → Relative |
 | Function naming | `generate*`, `build*`, `to*`, `is*`, `extract*` |
 
@@ -55,7 +60,7 @@ type TUserRequest = { };
 // Classes use PascalCase with suffix
 class UserController extends BaseRestController { }
 class UserService extends BaseService { }
-class UserRepository extends DefaultCRUDRepository { }
+class UserRepository extends DefaultRelationalRepository { }
 ```
 
 ### File Structure

package/content/best-practices/code-style-standards/naming-conventions.md

@@ -2,6 +2,24 @@
 
 Consistent naming improves code readability and maintainability.
 
+## Never Abbreviate an Identifier
+
+Hard rule. Write the whole word - in class names, variables, and type parameters alike.
+
+```typescript
+// ✅ GOOD
+class ProductRepository { }
+type TProductDocument = { };
+const configuration = resolveConfiguration();
+class Repository<TDocument> { }
+
+// ❌ BAD
+class ProductRepo { }
+type TProductDoc = { };
+const cfg = resolveCfg();
+class Repository<TDoc> { }
+```
+
 ## Directory Structure
 
 ### Component Organization
@@ -80,6 +98,8 @@ Both styles are acceptable: `[type].ts` or `[name].[type].ts`
 - Use `[type].ts` when there's only one file of that type in the folder
 - Use `[name].[type].ts` when there are multiple files of the same type
 - Use kebab-case for multi-word names: `jwt-token.service.ts`
+- **A file name never repeats its folder.** Name the file for its role inside the folder:
+  `logger/winston/logger.ts`, not `logger/winston/winston-logger.ts`
 
 ## Type and Interface Prefixes
 
@@ -90,13 +110,17 @@ interface IHealthCheckOptions {
 }
 
 interface IAuthService {
-  signIn(context: Context, opts: TSignInRequest): Promise<AnyObject>;
+  signIn(context: TContext, opts: TSignInRequest): Promise<AnyObject>;
 }
 
 // Type aliases use 'T' prefix
 type TSignInRequest = z.infer<typeof SignInRequestSchema>;
 type TAuthStrategy = TConstValue<typeof AuthenticateStrategy>;
 
+// ❌ Never a bare string-literal union for an enumerable set - it has no runtime
+// values to validate against. Use a const class + TConstValue instead.
+type TLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'emerg';
+
 // Generic constraints
 type TTableSchemaWithId<TC extends TableConfig = TableConfig> = PgTable<TC> & {
   id: TIdColumn;
@@ -123,7 +147,7 @@ export class SocketIOBindingKeys {
 Use underscore prefix (`_`) for private and protected class fields to distinguish them from public fields and method parameters.
 
 ```typescript
-class MyRepository extends DefaultCRUDRepository {
+class MyRepository extends DefaultRelationalRepository {
   // Private fields with underscore prefix
   private _dataSource: AbstractDataSource;
   private _entity: AbstractEntity;

package/content/best-practices/code-style-standards/route-definitions.md

@@ -61,6 +61,9 @@ export class UserController extends BaseRestController {
 }
 ```
 
+`@get`, `@post`, `@put`, `@patch`, and `@del` are the same decorator with `method` preset - the
+config they take omits `method`.
+
 ## Method 3: Using `bindRoute` (Programmatic)
 
 Register routes in the `binding()` lifecycle method:
@@ -115,18 +118,19 @@ Use Zod with `.openapi()` for automatic documentation:
 
 ```typescript
 const CreateUserSchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   name: z.string().min(1).max(100),
 }).openapi({
   description: 'Create user request body',
   example: { email: 'user@example.com', name: 'John Doe' },
 });
 
+// Zod v4 top-level string formats - not the deprecated z.string().email() chain
 const UserSchema = z.object({
-  id: z.string().uuid(),
-  email: z.string().email(),
+  id: z.uuid(),
+  email: z.email(),
   name: z.string(),
-  createdAt: z.string().datetime(),
+  createdAt: z.iso.datetime(),
 }).openapi({
   description: 'User response',
 });
@@ -165,4 +169,4 @@ export const RouteConfigs = {
 
 - [API Usage Examples](../api-usage-examples) - Full API patterns
 - [Controllers Reference](../../references/base/controllers) - Controller API
-- [Swagger Component](../../extensions/components/api-reference) - OpenAPI setup
+- [API Reference Component](../../extensions/components/api-reference) - OpenAPI setup

package/content/best-practices/code-style-standards/tooling.md

@@ -2,6 +2,10 @@
 
 IGNIS provides centralized development configurations via the `@venizia/dev-configs` package.
 
+> [!IMPORTANT]
+> **Bun is the only package manager** - never npm, yarn, or pnpm. **Compile with `tsc` directly** -
+> never `npx`, `bunx`, or `bun x`.
+
 ## Installation
 
 ```bash
@@ -9,7 +13,7 @@ bun add -d @venizia/dev-configs
 ```
 
 This package provides:
-- **ESLint rules** - Pre-configured for Node.js/TypeScript projects
+- **ESLint rules** - flat config, pre-configured for Node.js/TypeScript projects
 - **Prettier settings** - Consistent formatting across all IGNIS projects
 - **TypeScript configs** - Shared base and common configurations
 
@@ -121,6 +125,15 @@ Use the centralized TypeScript configs:
 | `useDefineForClassFields` | `false` | Decorator-compatible class fields |
 | `strict` | `true` | Strict type checking |
 | `skipLibCheck` | `true` | Faster compilation |
+| `noEmitOnError` | `true` | A type error emits nothing - the build fails loudly |
+
+Every package in the monorepo pins **TypeScript `^6.0.3`**; `@venizia/dev-configs` accepts
+`^5.0.0 || ^6.0.0`. Do not upgrade past 6 - `typescript-eslint` breaks.
+
+> [!WARNING]
+> Bun does not resolve `experimentalDecorators` / `emitDecoratorMetadata` through `extends`. In an
+> **application** `tsconfig.json` that Bun executes, declare both flags directly in
+> `compilerOptions`, or `@inject` parameter decorators are dropped silently and DI fails at boot.
 
 ## IDE Integration
 

package/content/best-practices/code-style-standards/type-safety.md

@@ -26,6 +26,39 @@ const data: TUserResponse = await fetchData();
 const result: TProcessResult = processData();
 ```
 
+### When a Cast Is Unavoidable
+
+Some boundaries genuinely cannot be typed. Reach for the **simplest** escape hatch - `as any` or the
+`AnyType` alias - never a chained one.
+
+```typescript
+// ✅ GOOD
+const handler = raw as any;
+const value = raw as AnyType;
+
+// ❌ BAD - baroque, hides what is actually being asserted
+const handler = raw as unknown as TRouteHandler;
+```
+
+## Derive Types, Never Duplicate Them
+
+Prefer a compile-time type derived from the definition over a hand-maintained copy. A duplicate
+drifts silently; a derived type breaks the build the moment the definition changes.
+
+```typescript
+// ✅ GOOD - derived from the single source of truth
+type TUser = typeof User.schema.$inferSelect;
+type TNewUser = typeof User.schema.$inferInsert;
+type TSignInRequest = z.infer<typeof SignInRequestSchema>;
+
+// ❌ BAD - a parallel definition that will drift
+type TUser = {
+  id: string;
+  email: string;
+  createdAt: Date;
+};
+```
+
 ## Explicit Return Types
 
 Always define explicit return types for **public methods** and **API handlers**.
@@ -53,7 +86,7 @@ public async findUser(id: string) {
 ```typescript
 // Define schema
 export const SignInRequestSchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   password: z.string().min(8),
 });
 
@@ -76,7 +109,7 @@ type RouteKey = keyof typeof RouteConfigs; // 'GET_USERS' | 'GET_USER_BY_ID'
 ### Generic Type Constraints
 
 ```typescript
-export class DefaultCRUDRepository<
+export class DefaultRelationalRepository<
   EntitySchema extends TTableSchemaWithId = TTableSchemaWithId
 > {
   // EntitySchema is constrained to have an 'id' column
@@ -124,14 +157,14 @@ const result2 = await userRepository.create({ data: user });
 
 ```typescript
 // Type guard function
-function isUser(obj: unknown): obj is TUser {
+const isUser = (obj: unknown): obj is TUser => {
   return (
     typeof obj === 'object' &&
     obj !== null &&
     'id' in obj &&
     'email' in obj
   );
-}
+};
 
 // Usage
 const data = await fetchData();
@@ -148,7 +181,7 @@ type TResult<T> =
   | { success: true; data: T }
   | { success: false; error: string };
 
-function processResult<T>(result: TResult<T>) {
+const processResult = <T>(result: TResult<T>) => {
   if (result.success) {
     // TypeScript knows result.data exists
     return result.data;
@@ -156,7 +189,7 @@ function processResult<T>(result: TResult<T>) {
 
   // TypeScript knows result.error exists
   throw getError({ message: result.error });
-}
+};
 ```
 
 ## See Also

package/content/best-practices/common-pitfalls.md

@@ -26,7 +26,6 @@ export class Application extends BaseApplication {
 
     // Services
     this.service(MyNewService); // <-- Don't forget this line
-    this.registerAuth();
 
     // Controllers
     this.controller(TestController);
@@ -174,31 +173,44 @@ await userRepository.updateBy({
 
 ## 7. Schema Key Mismatch
 
-**Problem:** Entity name doesn't match the table name registered in the DataSource's schema.
+**Problem:** The repository cannot find its table in the DataSource schema.
 
 **Error Message:**
 ```
-[UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [Configuration, Post] | Ensure the model's TABLE_NAME matches the schema registration key
+[UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [users, Post] | Ensure the model's TABLE_NAME matches the schema registration key
 ```
 
-**Solution:** The schema registration key follows the precedence `@model tableName metadata > static TABLE_NAME > class name`, while the repository looks the query interface up by the entity **class name**. Do not set `TABLE_NAME` (or `tableName` metadata) to a value that differs from the class name:
+**Cause:** Two keys are resolved by *different* rules:
+
+| Key | Rule |
+|-----|------|
+| Schema registration key | `@model({ tableName })` > `static TABLE_NAME` > class name |
+| Repository lookup key (`entity.name`) | `static TABLE_NAME` > class name |
+
+`@model({ tableName })` moves the registration key but not the lookup key. Setting it alone is what breaks:
 
 ```typescript
-// ❌ BAD - Schema is registered under 'users', but looked up as 'User'
-@model({ type: 'entity' })
-export class User extends BasePostgresEntity<typeof User.schema> {
-  static override TABLE_NAME = 'users';  // Differs from class name!
-  static override schema = pgTable('User', { /* ... */ });
+// ❌ BAD - registered under 'users', looked up as 'User'
+@model({ type: 'entity', tableName: 'users' })
+export class User extends BaseRelationalEntity<typeof User.schema> {
+  static override schema = pgTable('users', { /* ... */ });
 }
 
-// ✅ GOOD - No TABLE_NAME override; registration key defaults to the class name
+// ✅ GOOD - set neither; both keys resolve to the class name
 @model({ type: 'entity' })
-export class User extends BasePostgresEntity<typeof User.schema> {
-  static override schema = pgTable('User', { /* ... */ });
+export class User extends BaseRelationalEntity<typeof User.schema> {
+  static override schema = pgTable('users', { /* ... */ });
+}
+
+// ✅ GOOD - or set both to the same value
+@model({ type: 'entity', tableName: 'users' })
+export class User extends BaseRelationalEntity<typeof User.schema> {
+  static override TABLE_NAME = 'users';
+  static override schema = pgTable('users', { /* ... */ });
 }
 ```
 
-**Why this matters:** The framework uses `entity.name` (class name) to look up the query interface in `connector.query`, but registers the schema under the resolved table name. If they don't match, the repository can't find its table. The first argument of `pgTable()` is the physical SQL table name and is independent of this lookup - by convention it matches the class name.
+`static TABLE_NAME` on its own is safe - it moves both keys together. The first argument of `pgTable()` is the physical SQL table name and plays no part in either lookup.
 
 ## 8. Validation Error Response Structure
 
@@ -209,8 +221,12 @@ export class User extends BasePostgresEntity<typeof User.schema> {
 ```json
 {
   "statusCode": 422,
-  "message": "Invalid email",
-  "messageCode": "invalid_string",
+  "message": "Invalid email address",
+  "normalized": {
+    "text": "Invalid email address",
+    "code": "invalid_format",
+    "args": {}
+  },
   "requestId": "abc123",
   "details": {
     "url": "http://localhost:3000/users",
@@ -218,23 +234,30 @@ export class User extends BasePostgresEntity<typeof User.schema> {
     "cause": [
       {
         "path": "email",
-        "message": "Invalid email",
-        "code": "invalid_string",
-        "expected": "email",
-        "received": "string"
+        "message": "Invalid email address",
+        "code": "invalid_format"
       },
       {
         "path": "age",
-        "message": "Expected number, received string",
+        "message": "Invalid input: expected number, received string",
         "code": "invalid_type",
-        "expected": "number",
-        "received": "string"
+        "expected": "number"
       }
     ]
   }
 }
 ```
 
+- `normalized.code` comes from the first issue carrying a `params.code`, otherwise the first issue's raw Zod code. Attach a stable code clients can branch on with `.refine()`:
+  ```typescript
+  z.number().refine(isTwoDecimals, {
+    message: 'At most 2 decimal places',
+    params: { code: 'app.price.too_many_places' },
+  });
+  ```
+- `args` is always `{}` here - per-field detail lives in `details.cause`.
+- `details.stack` is omitted in production; `details.cause` is not.
+
 **Client-side handling:**
 ```typescript
 try {
@@ -253,32 +276,31 @@ try {
 
 **Problem:** Application fails to start with `Cannot access 'X' before initialization` or similar errors.
 
-**Cause:** Two or more modules import each other directly, creating a circular reference that JavaScript cannot resolve.
+**Cause:** Two models reference each other's schema. With a cycle, one module is still mid-evaluation when the other reads its exports, so `User.schema` is `undefined`.
 
-**Solution:** Use lazy imports or restructure your modules:
+**Solution:** `relations` accepts a resolver function. Use it - the framework calls it in `buildSchema()`, after every model has finished loading:
 
 ```typescript
-// ❌ BAD - Direct import causes circular dependency
 import { User } from './user.model';
 
+// ❌ BAD - array literal is evaluated at module load, while the cycle is still open
 @model({ type: 'entity' })
-export class Order extends BasePostgresEntity<typeof Order.schema> {
-  static override relations = (): TRelationConfig[] => [
-    { schema: User.schema, ... }, // User imports Order, Order imports User
+export class Order extends BaseRelationalEntity<typeof Order.schema> {
+  static override relations: TRelationConfig[] = [
+    { name: 'owner', type: RelationTypes.ONE, schema: User.schema, metadata: { ... } },
   ];
 }
 
-// ✅ GOOD - Lazy import breaks the cycle
+// ✅ GOOD - resolver defers the User.schema read until after both modules finish loading
 @model({ type: 'entity' })
-export class Order extends BasePostgresEntity<typeof Order.schema> {
-  static override relations = (): TRelationConfig[] => {
-    const { User } = require('./user.model'); // Lazy require
-    return [{ schema: User.schema, ... }];
-  };
+export class Order extends BaseRelationalEntity<typeof Order.schema> {
+  static override relations = (): TRelationConfig[] => [
+    { name: 'owner', type: RelationTypes.ONE, schema: User.schema, metadata: { ... } },
+  ];
 }
 ```
 
-**Alternative:** Restructure to have a shared module that both import from.
+**Alternative:** Restructure so both models import their shared pieces from a third module.
 
 ## 10. Transaction Not Rolling Back
 
@@ -306,6 +328,8 @@ try {
 }
 ```
 
+This exact shape is safe even when `commit()` is what failed: a rollback on an already-torn-down transaction is a no-op, so it never replaces your original error. A failed `COMMIT` always throws - never treat a resolved `commit()` as anything but success.
+
 ## 11. Fire-and-Forget Promises Losing Context
 
 **Problem:** `getCurrentUserId()` or other context-dependent functions return `null` in background tasks.

package/content/best-practices/contribution-workflow.md

@@ -77,6 +77,7 @@ The project uses a Makefile for common development tasks:
 | `make build` | Rebuild all packages in correct order |
 | `make clean` | Clean build artifacts from all packages |
 | `make lint` | Lint all packages |
+| `make lint-all` | Lint packages **and** examples - this is the bar a PR must clear |
 | `make help` | Show all available commands |
 
 **Individual package builds** (dependencies are automatically resolved):
@@ -153,8 +154,8 @@ git commit -m "chore: upgrade Hono to v4.0"
 ### Step 4: Validate
 
 ```bash
-# Lint and format (from root)
-make lint
+# Lint and format (from root) - zero warnings and zero errors is the bar
+make lint-all
 # Or run `bun run lint:fix` inside a package directory
 
 # Build all packages (from root)
@@ -164,6 +165,9 @@ make build
 cd packages/core && bun test
 ```
 
+> [!WARNING]
+> `make <package>` **cleans `dist/` before it builds**, and the build type-checks `__tests__` too. One broken test therefore aborts the build after `dist/` is already gone, leaving an **empty `dist/`** and a cascade of unrelated-looking import failures in `bun test`. If imports suddenly break everywhere, check `dist/` before chasing the imports.
+
 ## 3. Submit Pull Request
 
 ```bash