@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/changelogs/2025-12-31-string-id-custom-generator.md

@@ -0,0 +1,137 @@
+---
+title: String ID with Custom Generator
+description: Text column with customizable ID generator for maximum database compatibility
+---
+
+# Changelog - 2025-12-31
+
+## String ID with Custom Generator
+
+This release changes the string ID implementation from PostgreSQL `uuid` type to `text` column with a customizable ID generator for maximum database compatibility.
+
+## Overview
+
+- **Text Column**: String IDs now use `text` column type instead of PostgreSQL `uuid`
+- **Custom Generator**: Optional `generator` function to use any ID format (UUID, nanoid, cuid, etc.)
+- **Default UUID**: Uses `crypto.randomUUID()` by default for backwards compatibility
+- **Consistent Naming**: Renamed `visibleColumns` to `visibleProperties` for consistency with `hiddenProperties`
+- **Removed 'uuid' Option**: Principal enricher now only supports `'number' | 'string'`
+
+
+## String ID Changes
+
+### Before
+
+```typescript
+// Used PostgreSQL uuid type
+uuid('id').defaultRandom().primaryKey()
+// Column type: uuid
+```
+
+### After
+
+```typescript
+// Uses text column with $defaultFn
+text('id').primaryKey().$defaultFn(() => crypto.randomUUID())
+// Column type: text
+```
+
+### Custom Generator Option
+
+```typescript
+import { nanoid } from 'nanoid';
+
+generateIdColumnDefs({
+  id: {
+    dataType: 'string',
+    generator: () => nanoid(),  // Custom generator
+  },
+})
+```
+
+### Type Definition
+
+```typescript
+type TIdEnricherOptions = {
+  id?: { columnName?: string } & (
+    | { dataType: 'string'; generator?: () => string }  // NEW: optional generator
+    | { dataType: 'number'; sequenceOptions?: PgSequenceOptions }
+    | { dataType: 'big-number'; numberMode: 'number' | 'bigint'; sequenceOptions?: PgSequenceOptions }
+  );
+};
+```
+
+
+## Naming Consistency
+
+Renamed internal properties for consistency:
+
+| Before | After |
+|--------|-------|
+| `_visibleColumns` | `_visibleProperties` |
+| `getVisibleColumns()` | `getVisibleProperties()` |
+| `visibleColumns` getter/setter | `visibleProps` getter/setter |
+
+
+## Principal Enricher Simplification
+
+Removed 'uuid' option since it's now identical to 'string':
+
+```typescript
+// Before
+type IdType = 'number' | 'string' | 'uuid';
+
+// After
+type IdType = 'number' | 'string';
+```
+
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/models/enrichers/id.enricher.ts` | Text column with custom generator, type aliases |
+| `src/base/models/enrichers/principal.enricher.ts` | Removed 'uuid' option, uses text for string IDs |
+| `src/base/repositories/core/base.ts` | Renamed visibleColumns to visibleProperties |
+| `src/base/repositories/core/readable.ts` | Updated to use getVisibleProperties() |
+| `src/base/repositories/core/persistable.ts` | Updated to use getVisibleProperties() |
+| `src/components/static-asset/models/base.model.ts` | uuid() to text() |
+| `src/components/auth/models/entities/*.ts` | uuid() to text() for all auth models |
+
+
+## Migration Guide
+
+### No Breaking Changes for Most Users
+
+If you're using `generateIdColumnDefs({ id: { dataType: 'string' } })`, your code continues to work. The only difference is the underlying column type changes from `uuid` to `text`.
+
+### Database Migration
+
+If you have existing `uuid` columns and want to migrate to `text`:
+
+```sql
+-- Option 1: Alter column type (data preserved)
+ALTER TABLE "your_table" ALTER COLUMN "id" TYPE TEXT;
+
+-- Option 2: Keep uuid type (still works with text-based code)
+-- No migration needed - uuid values are compatible with text operations
+```
+
+### Custom ID Generator
+
+To use a custom generator:
+
+```typescript
+import { nanoid } from 'nanoid';
+// or
+import { createId } from '@paralleldrive/cuid2';
+
+generateIdColumnDefs({
+  id: {
+    dataType: 'string',
+    generator: () => nanoid(),  // or createId
+  },
+})
+```

package/wiki/changelogs/2026-01-02-default-filter-and-repository-mixins.md

@@ -0,0 +1,418 @@
+---
+title: Default Filter & Repository Mixins
+description: Added default filter support for models and refactored repository architecture with composable mixins
+---
+
+# Changelog - 2026-01-02
+
+## Default Filter & Repository Mixins
+
+This release introduces **Default Filter** - a powerful feature that automatically applies predefined filter conditions to all repository queries. Additionally, the repository architecture has been refactored to use composable mixins for better code organization and reusability.
+
+## Overview
+
+- **Default Filter**: Configure automatic filter conditions at the model level (e.g., soft delete, tenant isolation)
+- **Skip Default Filter**: Bypass default filters with `shouldSkipDefaultFilter: true` for admin/maintenance operations
+- **Repository Mixins**: Extracted `DefaultFilterMixin` and `FieldsVisibilityMixin` for composable repository features
+- **FilterBuilder Enhancement**: Renamed `DrizzleFilterBuilder` to `FilterBuilder`, added `mergeFilter` method
+- **IExtraOptions Interface**: New interface replacing `TTransactionOption` with `shouldSkipDefaultFilter` support
+
+## New Features
+
+### Default Filter
+
+**Files:**
+- `packages/core/src/base/repositories/mixins/default-filter.ts`
+- `packages/core/src/base/repositories/operators/filter.ts`
+
+**Problem:** Applications often need to apply the same filter conditions to every query - soft delete (`isDeleted: false`), tenant isolation (`tenantId: 'xxx'`), or active record patterns. Without a centralized solution, developers must manually add these conditions to every repository call.
+
+**Solution:** Configure a `defaultFilter` in your model settings. The repository automatically merges this filter with user-provided filters for all read, update, and delete operations.
+
+```typescript
+// Model configuration with default filter
+@model({
+  type: 'entity',
+  settings: {
+    // Automatically applied to all queries
+    defaultFilter: {
+      where: { isDeleted: false },
+      limit: 100,  // Prevent unbounded queries
+    },
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
+}
+```
+
+**Automatic Application:**
+
+```typescript
+// User query - default filter automatically merged
+await userRepo.find({
+  filter: { where: { status: 'active' } }
+});
+// Actual query: WHERE isDeleted = false AND status = 'active' LIMIT 100
+
+// Default filter also applies to count, update, delete
+await userRepo.count({ where: { role: 'admin' } });
+// Actual query: WHERE isDeleted = false AND role = 'admin'
+```
+
+**Filter Merge Strategy:**
+
+| Property | Strategy |
+|----------|----------|
+| `where` | Deep merge (user overrides matching keys) |
+| `limit` | User replaces default (if provided) |
+| `offset`/`skip` | User replaces default (if provided) |
+| `order` | User replaces default (if provided) |
+| `fields` | User replaces default (if provided) |
+| `include` | User replaces default (if provided) |
+
+```typescript
+// Default: { where: { isDeleted: false, status: 'pending' }, limit: 100 }
+// User: { where: { status: 'active' }, limit: 10 }
+// Result: { where: { isDeleted: false, status: 'active' }, limit: 10 }
+```
+
+### Skip Default Filter
+
+**Problem:** Admin users or maintenance scripts sometimes need to query all records, including soft-deleted ones or records from all tenants.
+
+**Solution:** Pass `shouldSkipDefaultFilter: true` in the options to bypass the default filter:
+
+```typescript
+// Normal query - default filter applies
+await repo.find({ filter: { where: { role: 'admin' } } });
+// WHERE isDeleted = false AND role = 'admin'
+
+// Admin query - bypass default filter
+await repo.find({
+  filter: { where: { role: 'admin' } },
+  options: { shouldSkipDefaultFilter: true }
+});
+// WHERE role = 'admin' (includes deleted records)
+
+// Works with all operations
+await repo.count({ where: {}, options: { shouldSkipDefaultFilter: true } });
+await repo.updateAll({
+  where: { status: 'archived' },
+  data: { isDeleted: true },
+  options: { shouldSkipDefaultFilter: true }
+});
+await repo.deleteAll({
+  where: { createdAt: { lt: '2020-01-01' } },
+  options: { shouldSkipDefaultFilter: true, force: true }
+});
+```
+
+**Benefits:**
+- Automatic soft-delete filtering without manual `where` additions
+- Multi-tenant isolation at the data layer
+- Consistent query behavior across the application
+- Easy bypass for admin/maintenance operations
+
+### Repository Mixins
+
+**Files:**
+- `packages/core/src/base/repositories/mixins/default-filter.ts`
+- `packages/core/src/base/repositories/mixins/fields-visibility.ts`
+- `packages/core/src/base/repositories/mixins/index.ts`
+
+**Problem:** Repository base classes were becoming monolithic with multiple concerns (hidden properties, default filters, transaction handling) mixed together.
+
+**Solution:** Extract cross-cutting concerns into composable mixins:
+
+```typescript
+// DefaultFilterMixin - Provides default filter functionality
+export const DefaultFilterMixin = <T extends TMixinTarget<object>>(baseClass: T) => {
+  abstract class Mixed extends baseClass {
+    getDefaultFilter(): TFilter | undefined;
+    hasDefaultFilter(): boolean;
+    applyDefaultFilter(opts: { userFilter?: TFilter; shouldSkipDefaultFilter?: boolean }): TFilter;
+  }
+  return Mixed;
+};
+
+// FieldsVisibilityMixin - Provides hidden properties functionality
+export const FieldsVisibilityMixin = <T extends TMixinTarget<object>>(baseClass: T) => {
+  abstract class Mixed extends baseClass {
+    get hiddenProperties(): Set<string>;
+    get visibleProperties(): Record<string, any> | undefined;
+    getHiddenProperties(): Set<string>;
+    hasHiddenProperties(): boolean;
+    getVisibleProperties(): Record<string, any> | undefined;
+  }
+  return Mixed;
+};
+```
+
+**Usage in AbstractRepository:**
+
+```typescript
+export abstract class AbstractRepository<...>
+  extends DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper))
+  implements IPersistableRepository<...>
+{
+  // Mixins provide getDefaultFilter, applyDefaultFilter,
+  // getHiddenProperties, getVisibleProperties, etc.
+}
+```
+
+**Benefits:**
+- Separation of concerns
+- Reusable logic across different repository types
+- Easier testing of individual features
+- Clear dependency chain
+
+### IExtraOptions Interface
+
+**File:** `packages/core/src/base/repositories/common/types.ts`
+
+**Problem:** The `TTransactionOption` type only supported `transaction` option. With the new default filter feature, we need additional options.
+
+**Solution:** Introduced `IExtraOptions` interface that extends beyond transactions:
+
+```typescript
+// New interface
+export interface IExtraOptions extends IWithTransaction {
+  /**
+   * If true, bypass the default filter configured in model settings.
+   * Use this when you need to query all records regardless of default filter constraints.
+   */
+  shouldSkipDefaultFilter?: boolean;
+}
+
+// Base transaction interface
+export interface IWithTransaction {
+  transaction?: ITransaction;
+}
+
+// Deprecated alias for backward compatibility
+/** @deprecated Use IExtraOptions instead */
+export type TTransactionOption = IExtraOptions;
+```
+
+### FilterBuilder Enhancements
+
+**File:** `packages/core/src/base/repositories/operators/filter.ts`
+
+**Changes:**
+- Renamed `DrizzleFilterBuilder` to `FilterBuilder`
+- Added `mergeFilter` method for combining default and user filters
+- Added `resolveHiddenProperties` and `resolveRelations` methods
+- Simplified `build` method signature (relations resolved internally)
+
+```typescript
+// New mergeFilter method
+const filterBuilder = new FilterBuilder();
+
+const result = filterBuilder.mergeFilter({
+  defaultFilter: { where: { isDeleted: false }, limit: 100 },
+  userFilter: { where: { status: 'active' }, limit: 10 }
+});
+// Result: { where: { isDeleted: false, status: 'active' }, limit: 10 }
+```
+
+**Internal Changes:**
+- Relations now resolved internally via `resolveRelations` method
+- Hidden properties resolved via `resolveHiddenProperties` method
+- Simplified API for `build` method (no need to pass resolvers)
+
+## Files Changed
+
+### Core Package (`packages/core`)
+
+| File | Changes |
+|------|---------|
+| `src/base/repositories/mixins/default-filter.ts` | **NEW** - DefaultFilterMixin implementation |
+| `src/base/repositories/mixins/fields-visibility.ts` | **NEW** - FieldsVisibilityMixin implementation |
+| `src/base/repositories/mixins/index.ts` | **NEW** - Barrel export for mixins |
+| `src/base/repositories/common/types.ts` | Added `IExtraOptions`, `IWithTransaction` interfaces |
+| `src/base/repositories/core/base.ts` | Refactored to use mixins, updated method signatures |
+| `src/base/repositories/core/readable.ts` | Added `applyDefaultFilter` calls to read operations |
+| `src/base/repositories/core/persistable.ts` | Added `applyDefaultFilter` calls to update/delete |
+| `src/base/repositories/core/default-crud.ts` | Updated type parameters |
+| `src/base/repositories/operators/filter.ts` | Renamed to `FilterBuilder`, added `mergeFilter` |
+| `src/helpers/inversion/common/types.ts` | Added `defaultFilter` to model settings type |
+
+### Tests (`packages/core/src/__tests__`)
+
+| File | Changes |
+|------|---------|
+| `default-filter/default-filter.test.ts` | **NEW** - Comprehensive test suite (150+ test cases) |
+
+### Examples (`examples/vert`)
+
+| File | Changes |
+|------|---------|
+| `src/services/tests/default-filter-test.service.ts` | **NEW** - Integration test service |
+| `src/services/tests/TEST_CASES.md` | **NEW** - Test case documentation |
+
+## Breaking Changes
+
+### DrizzleFilterBuilder Renamed to FilterBuilder
+
+**Before:**
+```typescript
+import { DrizzleFilterBuilder } from '@venizia/ignis';
+const builder = new DrizzleFilterBuilder();
+```
+
+**After:**
+```typescript
+import { FilterBuilder } from '@venizia/ignis';
+const builder = new FilterBuilder();
+```
+
+### FilterBuilder.build() Signature Changed
+
+**Before:**
+```typescript
+filterBuilder.build({
+  tableName: 'users',
+  schema: userSchema,
+  relations: { posts: { ... } },
+  filter: myFilter,
+  relationResolver: (schema) => { ... },
+  hiddenPropertiesResolver: (relationName) => { ... },
+});
+```
+
+**After:**
+```typescript
+// Relations and hidden properties resolved internally
+filterBuilder.build({
+  tableName: 'users',
+  schema: userSchema,
+  filter: myFilter,
+});
+```
+
+### TTransactionOption Deprecated
+
+**Before:**
+```typescript
+import { TTransactionOption } from '@venizia/ignis';
+
+class MyRepo extends AbstractRepository<Schema, Data, Persist, TTransactionOption> {}
+```
+
+**After:**
+```typescript
+import { IExtraOptions } from '@venizia/ignis';
+
+class MyRepo extends AbstractRepository<Schema, Data, Persist, IExtraOptions> {}
+```
+
+## Migration Guide
+
+### Step 1: Update FilterBuilder Usage
+
+If you're using `DrizzleFilterBuilder` directly (rare), rename to `FilterBuilder`:
+
+```typescript
+// Before
+import { DrizzleFilterBuilder } from '@venizia/ignis';
+
+// After
+import { FilterBuilder } from '@venizia/ignis';
+```
+
+### Step 2: Update Custom Repository Generic Types
+
+If you have custom repositories with explicit generic types:
+
+```typescript
+// Before
+class MyRepo extends PersistableRepository<Schema, Data, Persist, TTransactionOption> {}
+
+// After
+class MyRepo extends PersistableRepository<Schema, Data, Persist, IExtraOptions> {}
+```
+
+### Step 3: Add Default Filters to Models (Optional)
+
+To enable automatic filtering, add `defaultFilter` to your model settings:
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { isDeleted: false },
+    },
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
+}
+```
+
+## Common Use Cases
+
+### Soft Delete Pattern
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { deletedAt: null },  // or { isDeleted: false }
+    },
+  },
+})
+export class Post extends BaseEntity<typeof Post.schema> {}
+
+// All queries automatically exclude deleted posts
+await postRepo.find({ filter: { where: { published: true } } });
+// WHERE deletedAt IS NULL AND published = true
+
+// Restore deleted post (bypass default filter)
+await postRepo.updateById({
+  id: postId,
+  data: { deletedAt: null },
+  options: { shouldSkipDefaultFilter: true }
+});
+```
+
+### Multi-Tenant Isolation
+
+```typescript
+// Note: tenantId would be injected per-request in real applications
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { tenantId: 'current-tenant-id' },
+    },
+  },
+})
+export class Document extends BaseEntity<typeof Document.schema> {}
+```
+
+### Active Records Only
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: {
+        isActive: true,
+        expiresAt: { gt: new Date().toISOString() },
+      },
+      limit: 50,  // Prevent unbounded queries
+    },
+  },
+})
+export class Subscription extends BaseEntity<typeof Subscription.schema> {}
+```
+
+## Documentation
+
+- [Default Filter Guide](/references/base/filter-system/default-filter) - Full documentation
+- [Repository Mixins](/references/base/repositories/mixins) - Mixin architecture
+- [Advanced Repository Features](/references/base/repositories/advanced) - Updated with shouldSkipDefaultFilter

package/wiki/changelogs/index.md

@@ -17,6 +17,12 @@ This section tracks the history of significant changes, refactors, and updates t
 
 | Date | Title | Type |
 |------|-------|------|
+| 2026-01-02 | [Default Filter & Repository Mixins](./2026-01-02-default-filter-and-repository-mixins) | New Feature |
+| 2025-12-31 | [JSON Path Filtering & Array Operators](./2025-12-31-json-path-filtering-array-operators) | New Feature |
+| 2025-12-31 | [String ID with Custom Generator](./2025-12-31-string-id-custom-generator) | Enhancement |
+| 2025-12-30 | [Repository Enhancements](./2025-12-30-repository-enhancements) | Enhancement |
+| 2025-12-29 | [Snowflake UID Helper](./2025-12-29-snowflake-uid-helper) | New Feature |
+| 2025-12-29 | [Dynamic Binding Registration Fix](./2025-12-29-dynamic-binding-registration) | Bug Fix |
 | 2025-12-26 | [Transaction Support](./2025-12-26-transaction-support) | Enhancement |
 | 2025-12-26 | [Nested Relations & Generic Types](./2025-12-26-nested-relations-and-generics) | Enhancement |
 | 2025-12-18 | [Performance Optimizations](./2025-12-18-performance-optimizations) | Enhancement |

package/wiki/changelogs/planned-schema-migrator.md

@@ -40,7 +40,6 @@ await migrator.automigrate(); // Drops and recreates all tables
 | `autoupdate()` | Compares DB ↔ Model, applies ALTER statements | **No** |
 | `automigrate()` | Drops and recreates tables | **Yes** |
 
----
 
 ## Implementation Steps
 
@@ -409,7 +408,6 @@ export abstract class BaseDataSource<...> {
 }
 ```
 
----
 
 ## Files to Create
 
@@ -428,7 +426,6 @@ export abstract class BaseDataSource<...> {
 | `packages/core/src/base/datasources/base.ts` | Add `getMigrator()`, `autoupdate()`, `automigrate()` |
 | `packages/core/src/base/datasources/index.ts` | Export new classes |
 
----
 
 ## Drizzle to PostgreSQL Type Mapping
 
@@ -449,7 +446,6 @@ export abstract class BaseDataSource<...> {
 | `real()` | `real` | 32-bit float |
 | `doublePrecision()` | `double precision` | 64-bit float |
 
----
 
 ## Change Detection Matrix
 
@@ -466,7 +462,6 @@ export abstract class BaseDataSource<...> {
 | New index | Index not in DB | `CREATE INDEX` |
 | Removed index | Index not in model | `DROP INDEX` |
 
----
 
 ## Usage Examples
 
@@ -515,7 +510,6 @@ if (process.env.NODE_ENV === 'development') {
 }
 ```
 
----
 
 ## Safety Considerations
 
@@ -536,7 +530,6 @@ if (process.env.NODE_ENV === 'development') {
 | `ALTER TYPE` | May fail if incompatible | Checks compatibility first |
 | `automigrate()` | Drops all tables | Requires `force: true` |
 
----
 
 ## Future Enhancements
 
@@ -546,7 +539,6 @@ if (process.env.NODE_ENV === 'development') {
 4. **Multi-Schema Support** - Support for PostgreSQL schemas beyond `public`
 5. **MySQL/SQLite Support** - Extend beyond PostgreSQL
 
----
 
 ## Comparison with Alternatives
 

package/wiki/{get-started/core-concepts → guides/core-concepts/application}/bootstrapping.md

@@ -558,9 +558,22 @@ npx glob "your-pattern/**/*.controller.js"
 - Skip subdirectories if you have nested structure
 - Ignore boot errors (they indicate misconfiguration)
 
-## Related Documentation
+## See Also
 
-- [Boot Package Reference](/references/src-details/boot.md)
-- [Application Concepts](/get-started/core-concepts/application.md)
-- [Dependency Injection](/references/base/dependency-injection.md)
-- [Building a CRUD API](/get-started/building-a-crud-api.md)
+- **Related Concepts:**
+  - [Application Overview](./index) - Main application class
+  - [Controllers](/guides/core-concepts/controllers) - Auto-discovered controllers
+  - [Services](/guides/core-concepts/services) - Auto-discovered services
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Auto-discovered repositories
+
+- **References:**
+  - [Bootstrapping API](/references/base/bootstrapping) - Complete API reference
+  - [Boot Package](/references/src-details/boot) - Boot system internals
+  - [Dependency Injection](/references/base/dependency-injection) - DI container
+
+- **Tutorials:**
+  - [Complete Installation](/guides/tutorials/complete-installation) - Project structure
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Bootstrapping in action
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - Project organization patterns