npm - @venizia/ignis-docs - Versions diffs - 0.0.8-3 → 0.1.0 - Mend

@venizia/ignis-docs 0.0.8-3 → 0.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 (213) hide show

package/wiki/references/base/repositories/mixins.md DELETED Viewed

@@ -1,335 +0,0 @@
----
-title: Repository Mixins
-description: Composable mixins for repository functionality
-difficulty: intermediate
-lastUpdated: 2026-01-02
----
-# Repository Mixins <Badge type="tip" text="v0.0.5+" />
-Composable mixins that provide reusable functionality for repository classes.
-> [!NOTE] Refactored in v0.0.5
-> Repository mixins were extracted and refactored in v0.0.5 to provide better composition and reusability.
-**Files:** `packages/core/src/base/repositories/mixins/`
-## Overview
-Ignis uses the mixin pattern to compose repository features. This enables:
-- **Separation of concerns** - Each mixin handles one responsibility
-- **Reusability** - Mixins can be applied to different base classes
-- **Testability** - Individual features can be tested in isolation
-- **Flexibility** - Create custom repositories with only needed features
-## Available Mixins
-| Mixin | Responsibility |
-|-------|----------------|
-| `FieldsVisibilityMixin` | Hidden properties exclusion at SQL level |
-| `DefaultFilterMixin` | Automatic filter application from model settings |
-## FieldsVisibilityMixin
-Provides hidden properties management for SQL-level field exclusion. Reads `hiddenProperties` from `@model` metadata settings and builds a visible columns map for Drizzle's `select()` and `returning()` calls.
-**File:** `packages/core/src/base/repositories/mixins/fields-visibility.ts`
-### Abstract Requirements
-Classes using this mixin must implement:
-```typescript
-abstract getEntity(): BaseEntity<TTableSchemaWithId>;
-```
-### Properties
-| Property | Type | Description |
-|----------|------|-------------|
-| `_hiddenProperties` | `Set<string> \| null` | Cached hidden property names (`null` = not yet computed) |
-| `_visibleProperties` | `Record<string, any> \| null \| undefined` | Cached visible columns (`null` = not yet computed, `undefined` = computed with no hidden props) |
-### Methods
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `get hiddenProperties` | `Set<string>` | Getter that delegates to `getHiddenProperties()` |
-| `set hiddenProperties` | `void` | Override hidden properties set |
-| `getHiddenProperties()` | `Set<string>` | Get hidden properties from model metadata (cached) |
-| `hasHiddenProperties()` | `boolean` | Check if model has any hidden properties |
-| `get visibleProperties` | `Record<string, any> \| undefined` | Getter that delegates to `getVisibleProperties()` |
-| `set visibleProperties` | `void` | Override visible properties |
-| `getVisibleProperties()` | `Record<string, any> \| undefined` | Build visible columns object for Drizzle (cached). Returns `undefined` if no hidden props. |
-### Usage
-```typescript
-import { FieldsVisibilityMixin } from '@venizia/ignis';
-import { BaseHelper } from '@venizia/ignis-helpers';
-class MyRepository extends FieldsVisibilityMixin(BaseHelper) {
-  // Required abstract implementation
-  abstract getEntity(): BaseEntity;
-  // Now has access to:
-  // - hiddenProperties (getter/setter)
-  // - visibleProperties (getter/setter)
-  // - getHiddenProperties()
-  // - hasHiddenProperties()
-  // - getVisibleProperties()
-}
-```
-### Visible Properties for Drizzle
-The `getVisibleProperties()` method returns a columns object for Drizzle's `select()` or `returning()`:
-```typescript
-// Model with hiddenProperties: ['password', 'apiKey']
-// Schema columns: { id, email, password, apiKey, createdAt }
-const visibleProps = this.getVisibleProperties();
-// Result: { id: column, email: column, createdAt: column }
-// (password and apiKey excluded)
-// Used in Drizzle queries
-await connector.select(visibleProps).from(schema);
-// SELECT id, email, created_at FROM users
-```
-### How It Resolves Hidden Properties
-1. Checks the cache (`_hiddenProperties`). If not `null`, returns cached value.
-2. Looks up the entity name in `MetadataRegistry.getModelEntry()`.
-3. Reads `metadata.settings.hiddenProperties` (array of field names).
-4. Converts to a `Set<string>` and caches.
-## DefaultFilterMixin
-Provides automatic default filter application for all repository queries. Reads `defaultFilter` from `@model` metadata settings and merges it with user-provided filters.
-**File:** `packages/core/src/base/repositories/mixins/default-filter.ts`
-### Abstract Requirements
-Classes using this mixin must implement:
-```typescript
-abstract getEntity(): BaseEntity<TTableSchemaWithId>;
-abstract get filterBuilder(): FilterBuilder;
-```
-### Properties
-| Property | Type | Description |
-|----------|------|-------------|
-| `_defaultFilter` | `TFilter \| null \| undefined` | Cached default filter (`null` = not yet computed, `undefined` = computed with no default filter) |
-### Methods
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `getDefaultFilter()` | `TFilter \| undefined` | Get default filter from model metadata (cached) |
-| `hasDefaultFilter()` | `boolean` | Check if model has a default filter configured |
-| `applyDefaultFilter(opts)` | `TFilter` | Merge default filter with user filter |
-### Usage
-```typescript
-import { DefaultFilterMixin } from '@venizia/ignis';
-import { BaseHelper } from '@venizia/ignis-helpers';
-class MyRepository extends DefaultFilterMixin(BaseHelper) {
-  // Required abstract implementations
-  abstract getEntity(): BaseEntity;
-  abstract get filterBuilder(): FilterBuilder;
-  // Now has access to:
-  // - getDefaultFilter()
-  // - hasDefaultFilter()
-  // - applyDefaultFilter()
-}
-```
-### applyDefaultFilter Options
-```typescript
-applyDefaultFilter<DataObject = any>(opts: {
-  userFilter?: TFilter<DataObject>;        // User-provided filter
-  shouldSkipDefaultFilter?: boolean;       // If true, bypass default filter
-}): TFilter<DataObject>
-```
-**Behavior:**
-1. If `shouldSkipDefaultFilter` is `true`, returns the user filter as-is (or `{}` if none).
-2. If no default filter is configured, returns the user filter as-is (or `{}` if none).
-3. Otherwise, delegates to `filterBuilder.mergeFilter({ defaultFilter, userFilter })` which deep-merges `where` conditions and uses user values for other filter properties (`order`, `limit`, `offset`, `skip`, `fields`, `include`).
-## Mixin Composition
-The `AbstractRepository` composes both mixins:
-```typescript
-export abstract class AbstractRepository<...>
-  extends DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper))
-  implements IPersistableRepository<...>
-{
-  // Inherits from both mixins:
-  // From FieldsVisibilityMixin:
-  //   - hiddenProperties (getter/setter)
-  //   - visibleProperties (getter/setter)
-  //   - getHiddenProperties()
-  //   - hasHiddenProperties()
-  //   - getVisibleProperties()
-  //
-  // From DefaultFilterMixin:
-  //   - getDefaultFilter()
-  //   - hasDefaultFilter()
-  //   - applyDefaultFilter()
-}
-```
-### Composition Order
-Mixins are applied right-to-left:
-```typescript
-// FieldsVisibilityMixin applied first (to BaseHelper)
-// DefaultFilterMixin applied second (to the result)
-DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper))
-```
-## Creating Custom Mixins
-Follow the TypeScript mixin pattern using `TMixinTarget`:
-```typescript
-import { TMixinTarget } from '@venizia/ignis-helpers';
-export const AuditLogMixin = <T extends TMixinTarget<object>>(baseClass: T) => {
-  abstract class Mixed extends baseClass {
-    // Properties
-    private _auditEnabled: boolean = true;
-    // Abstract dependencies (if needed)
-    abstract getEntity(): BaseEntity;
-    // Public methods
-    enableAudit(): void {
-      this._auditEnabled = true;
-    }
-    disableAudit(): void {
-      this._auditEnabled = false;
-    }
-    isAuditEnabled(): boolean {
-      return this._auditEnabled;
-    }
-    logOperation(operation: string, data: any): void {
-      if (this._auditEnabled) {
-        console.log(`[${this.getEntity().name}] ${operation}:`, data);
-      }
-    }
-  }
-  return Mixed;
-};
-```
-### Using Custom Mixins
-```typescript
-// Compose with existing mixins
-class MyRepository extends AuditLogMixin(DefaultFilterMixin(BaseHelper)) {
-  getEntity() {
-    return this._entity;
-  }
-  get filterBuilder() {
-    return this._filterBuilder;
-  }
-}
-// Or create a composed base
-const AuditableRepository = AuditLogMixin(DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper)));
-class ProductRepository extends AuditableRepository {
-  // Has all mixin functionality
-}
-```
-## Caching Behavior
-Both mixins use a three-state caching pattern for performance:
-```typescript
-// DefaultFilterMixin caching
-// null = not computed yet
-// undefined = computed, no default filter exists
-// TFilter = computed, has default filter
-_defaultFilter: TFilter | null | undefined = null;
-getDefaultFilter() {
-  if (this._defaultFilter !== null) {
-    return this._defaultFilter;  // Return cached value (either TFilter or undefined)
-  }
-  // Compute from MetadataRegistry and cache...
-}
-// FieldsVisibilityMixin caching
-// null = not computed yet
-// Set<string> = computed (may be empty)
-_hiddenProperties: Set<string> | null = null;
-// null = not computed yet
-// undefined = computed, no hidden properties exist
-// Record<string, any> = computed, has visible column map
-_visibleProperties: Record<string, any> | null | undefined = null;
-```
-This ensures metadata lookups happen only once per repository instance, with subsequent calls returning the cached value.
-## Quick Reference
-| Mixin | Method | Purpose |
-|-------|--------|---------|
-| `FieldsVisibilityMixin` | `hasHiddenProperties()` | Check if hidden props exist |
-| `FieldsVisibilityMixin` | `getHiddenProperties()` | Get hidden property names as `Set<string>` |
-| `FieldsVisibilityMixin` | `getVisibleProperties()` | Get Drizzle columns object (excludes hidden) |
-| `DefaultFilterMixin` | `hasDefaultFilter()` | Check if default filter exists |
-| `DefaultFilterMixin` | `getDefaultFilter()` | Get raw default filter from model metadata |
-| `DefaultFilterMixin` | `applyDefaultFilter()` | Merge default filter with user filter |
-## Next Steps
-- [Default Filter](../filter-system/default-filter.md) - Full default filter documentation
-- [Advanced Features](./advanced.md) - Hidden properties usage
-- [Repository Overview](./index.md) - Repository basics
-## See Also
-- **Related Concepts:**
-  - [Repositories Overview](./index) - Core repository operations
-  - [Models](/guides/core-concepts/persistent/models) - Entity definitions
-- **Related Topics:**
-  - [Default Filter](../filter-system/default-filter) - Automatic filtering
-  - [Advanced Features](./advanced) - Hidden properties and transactions
-  - [Relations & Includes](./relations) - Loading related data
-- **Best Practices:**
-  - [Data Modeling](/best-practices/data-modeling) - Soft delete patterns

package/wiki/references/base/services.md DELETED Viewed

@@ -1,201 +0,0 @@
----
-title: Services Reference
-description: Technical reference for BaseService and business logic layer
-difficulty: beginner
----
-# Deep Dive: Services
-Technical reference for `BaseService` - the foundation for business logic layers in Ignis.
-**File:** `packages/core/src/base/services/base.ts`
-## Quick Reference
-| Feature | Benefit |
-|---------|---------|
-| **Extends `BaseHelper`** | Auto-configured scoped logger (`this.logger`) |
-| **DI Integration** | Fits into framework's dependency injection system |
-| **Business Logic Layer** | Bridge between Controllers and Repositories |
-| **No built-in CRUD** | Services are for business logic, not data access — that's what Repositories are for |
-## `BaseService` Class
-Abstract class that all application services should extend. It implements the `IService` interface (currently a marker interface with no required methods).
-### Class Definition
-```typescript
-import { BaseHelper } from '@venizia/ignis-helpers';
-import { IService } from './types';
-export abstract class BaseService extends BaseHelper implements IService {
-  constructor(opts: { scope: string }) {
-    super({ scope: opts.scope });
-  }
-}
-```
-### Key Features
-| Feature | Description |
-| :--- | :--- |
-| **Standardization** | Common base for all services, fits framework architecture |
-| **Logging** | Extends `BaseHelper` from `@venizia/ignis-helpers` — auto-configured logger at `this.logger` (scope = class name) |
-| **Clarity** | Signals the class contains business logic |
-### Constructor
-The constructor requires an options object with a `scope` string, which is typically set to the class name:
-```typescript
-class UserService extends BaseService {
-  constructor() {
-    super({ scope: UserService.name });
-  }
-}
-```
-## `IService` Interface
-The `IService` interface is a marker interface with no required methods. It exists to provide a type-level contract for services.
-```typescript
-export interface IService {}
-```
-## No Built-in CRUD Service
-Ignis intentionally does not provide a `BaseCrudService`. CRUD operations belong in the Repository layer (`DefaultCRUDRepository`). Services are for business logic that orchestrates one or more repositories, performs validation, handles transactions, or coordinates cross-cutting concerns.
-## Registration
-Services are registered with the DI container using the `app.service()` method or via the boot system's auto-discovery:
-```typescript
-// Manual registration (in preConfigure or registerComponents)
-app.service(UserService); // Binds as 'services.UserService'
-// Or via boot system auto-discovery:
-// Place file at src/services/user.service.ts → auto-discovered and bound
-```
-## How Services Fit into the Architecture
-Services are the core of your application's logic. They act as a bridge between the presentation layer (Controllers) and the data access layer (Repositories).
-### Typical Service Flow
-1.  **Instantiated by DI Container**: When the application starts, the DI container creates instances of your services.
-2.  **Dependencies Injected**: The service's constructor receives instances of any repositories or other services it depends on.
-3.  **Called by a Controller**: An HTTP request comes into a controller, which then calls a method on a service to handle the business logic for that request.
-4.  **Orchestrates Logic**: The service method executes the business logic. This may involve:
-    -   Validating input data.
-    -   Calling one or more repository methods to fetch or save data.
-    -   Calling other services to perform related tasks.
-    -   Performing calculations or data transformations.
-5.  **Returns Data**: The service returns the result of the operation back to the controller, which then formats it into an HTTP response.
-### Example
-```typescript
-import { BaseService, inject, injectable } from '@venizia/ignis';
-import { getError } from '@venizia/ignis-helpers';
-import { UserRepository } from '../repositories/user.repository';
-import { TUser } from '../models/entities';
-// 1. Service is decorated with @injectable (or registered via app.service())
-@injectable()
-export class UserService extends BaseService {
-  // 2. Dependencies (like UserRepository) are injected
-  constructor(
-    @inject({ key: 'repositories.UserRepository' })
-    private _userRepository: UserRepository,
-  ) {
-    super({ scope: UserService.name });
-  }
-  // 3. Method is called by a controller
-  async getUserProfile(opts: { userId: string }): Promise<Partial<TUser>> {
-    this.logger.info(`Fetching profile for user ${opts.userId}`);
-    // 4. Orchestrates logic: calls the repository
-    const user = await this._userRepository.findById({ id: opts.userId });
-    if (!user) {
-      throw getError({ message: 'User not found' });
-    }
-    // 5. Returns transformed data
-    return {
-      id: user.id,
-      name: user.name,
-      email: user.email,
-    };
-  }
-}
-```
-### Transaction Orchestration
-A common service pattern is orchestrating transactions across multiple repositories:
-```typescript
-@injectable()
-export class OrderService extends BaseService {
-  constructor(
-    @inject({ key: 'repositories.OrderRepository' })
-    private orderRepo: OrderRepository,
-    @inject({ key: 'repositories.InventoryRepository' })
-    private inventoryRepo: InventoryRepository,
-    @inject({ key: 'datasources.PostgresDataSource' })
-    private dataSource: PostgresDataSource,
-  ) {
-    super({ scope: OrderService.name });
-  }
-  async placeOrder(opts: { userId: string; items: OrderItem[] }) {
-    const transaction = await this.dataSource.beginTransaction();
-    try {
-      const order = await this.orderRepo.create({
-        data: { userId: opts.userId, items: opts.items },
-        options: { transaction },
-      });
-      for (const item of opts.items) {
-        await this.inventoryRepo.updateById({
-          id: item.productId,
-          data: { quantity: item.quantity },
-          options: { transaction },
-        });
-      }
-      await transaction.commit();
-      return order;
-    } catch (error) {
-      await transaction.rollback();
-      throw error;
-    }
-  }
-}
-```
-By adhering to this pattern, you keep your code organized, testable, and maintainable. You can easily test `UserService` by providing a mock `UserRepository` without needing a real database connection.
-## See Also
-- **Related References:**
-  - [Controllers](./controllers.md) - HTTP request handlers that call services
-  - [Repositories](./repositories/) - Data access layer used by services
-  - [Providers](./providers.md) - Factory pattern for runtime instantiation
-  - [Dependency Injection](./dependency-injection.md) - DI container and injection patterns
-- **Guides:**
-  - [Building Services](/guides/core-concepts/services.md)
-  - [Dependency Injection Guide](/guides/core-concepts/dependency-injection.md)
-- **Best Practices:**
-  - [Architectural Patterns](/best-practices/architectural-patterns)
-  - [Testing Guide](/guides/tutorials/testing)

package/wiki/references/utilities/crypto.md DELETED Viewed

@@ -1,56 +0,0 @@
-# Crypto Utility
-The Crypto utility provides simple, stateless functions for cryptographic hashing using Node.js's built-in `node:crypto` module.
-## `hash`
-The `hash` function allows you to create a hash of a string using either `SHA256` (with a secret for HMAC) or `MD5`.
-### `hash(text, options)`
--   `text` (string): The input string to hash.
--   `options` (object):
-    -   `algorithm` (`'SHA256'` | `'MD5'`): The hashing algorithm to use.
-    -   `secret` (string, optional): The secret key for HMAC-SHA256. If `algorithm` is `'SHA256'` and no `secret` is provided, the original text is returned unchanged.
-    -   `outputType` (`BinaryToTextEncoding`): The output encoding (e.g., `'hex'`, `'base64'`).
-### Behavior
--   **SHA256**: Creates an HMAC using the provided `secret`. Returns the original text if no secret is given.
--   **MD5**: Creates a standard hash digest (no secret needed).
--   **Other algorithms**: Returns the original text unchanged.
-### Examples
-**MD5 Hash**
-```typescript
-import { hash } from '@venizia/ignis-helpers';
-const md5Hash = hash('some text', { algorithm: 'MD5', outputType: 'hex' });
-// => '552e21cd4cd99186789c2370c7482837'
-```
-**SHA256 HMAC**
-```typescript
-import { hash } from '@venizia/ignis-helpers';
-const sha256Hash = hash('some text', {
-  algorithm: 'SHA256',
-  secret: 'a-secret-key',
-  outputType: 'hex',
-});
-// => 'b8a1c3f2... (64-character hex string)'
-```
-**Base64 output**
-```typescript
-import { hash } from '@venizia/ignis-helpers';
-const base64Hash = hash('some text', {
-  algorithm: 'MD5',
-  outputType: 'base64',
-});
-```

package/wiki/references/utilities/module.md DELETED Viewed

@@ -1,42 +0,0 @@
-# Module Utility
-The Module utility provides a function to validate the existence of Node.js modules at runtime. It uses `createRequire` from `node:module` rooted at the application's `process.cwd()/node_modules`, so peer dependencies in the consuming application are properly resolved even though this utility lives inside `packages/helpers`.
-## `validateModule`
-The `validateModule` function checks if a list of modules can be resolved. If a module is not found, it logs the error and throws a descriptive error, prompting the developer to install it. This is particularly useful for features that have optional peer dependencies.
-### `validateModule(opts)`
--   `opts` (object):
-    -   `scope` (string, optional): A string to identify the feature or component that requires the module, making the error message more informative. Defaults to empty string.
-    -   `modules` (Array&lt;string&gt;): An array of module names to validate. Defaults to empty array.
-This is an `async` function, though it performs synchronous resolution internally.
-### Example
-The `SwaggerComponent` uses `validateModule` to ensure that `@hono/swagger-ui` is installed before attempting to use it.
-```typescript
-import { validateModule } from '@venizia/ignis-helpers';
-export class SwaggerComponent extends BaseComponent {
-  // ...
-  override async binding() {
-    // This will throw an error if '@hono/swagger-ui' is not installed
-    await validateModule({ scope: SwaggerComponent.name, modules: ['@hono/swagger-ui'] });
-    const { swaggerUI } = await import('@hono/swagger-ui');
-    // ... rest of the setup
-  }
-}
-```
-If the module is missing, the application will fail with an error message like:
-```
-[validateModule] @hono/swagger-ui is required for SwaggerComponent. Please install '@hono/swagger-ui'
-```