@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/references/base/models.md

@@ -1,3 +1,9 @@
+---
+title: Models & Enrichers Reference
+description: Technical reference for model architecture and schema enrichers
+difficulty: intermediate
+---
+
 # Deep Dive: Models and Enrichers
 
 Technical reference for model architecture and schema enrichers in Ignis.
@@ -29,6 +35,145 @@ Fundamental building block wrapping a Drizzle ORM schema.
 | **Static Properties** | Supports static `schema`, `relations`, and `TABLE_NAME` for cleaner syntax |
 | **Convenience** | Includes `toObject()` and `toJSON()` methods |
 
+### The `@model` Decorator
+
+The `@model` decorator marks a class as a database entity and configures its behavior.
+
+#### Decorator Options
+
+```typescript
+@model({
+  type: 'entity' | 'view',
+  tableName?: string,
+  skipMigrate?: boolean,
+  settings?: {
+    hiddenProperties?: string[],  // Properties to exclude from query results
+    defaultFilter?: TFilter,      // Filter applied to all repository queries
+  }
+})
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | `'entity' \| 'view'` | Entity type - `'entity'` for tables, `'view'` for database views |
+| `tableName` | `string` | Optional custom table name (defaults to class name) |
+| `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)) |
+
+### Hidden Properties
+
+Hidden properties are **excluded at the SQL level** - they are never fetched from the database when querying through repositories. This provides:
+
+- **Security**: Sensitive data like passwords are never accidentally exposed
+- **Performance**: Less data transferred from database
+- **Consistency**: Hidden properties are excluded from ALL repository operations
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { BaseEntity, model, generateIdColumnDefs } from '@venizia/ignis';
+
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['password', 'secret'],  // Never returned via repository
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    email: text('email').notNull(),
+    password: text('password'),  // Hidden - never in query results
+    secret: text('secret'),      // Hidden - never in query results
+  });
+}
+```
+
+#### Behavior
+
+| Operation | Hidden Properties |
+|-----------|-------------------|
+| `find()`, `findOne()`, `findById()` | Excluded from SELECT |
+| `create()`, `createAll()` | Excluded from RETURNING |
+| `updateById()`, `updateAll()` | Excluded from RETURNING |
+| `deleteById()`, `deleteAll()` | Excluded from RETURNING |
+| `count()`, `existsWith()` | Can filter by hidden fields |
+| Direct connector query | **Included** (bypasses repository) |
+
+#### Important Notes
+
+- Hidden properties can still be used in `where` clauses for filtering
+- Data is still **stored** in the database - only excluded from query results
+- Use direct connector queries when you need to access hidden data:
+
+```typescript
+// Repository query - password/secret NOT included
+const user = await userRepo.findById({ id: '123' });
+// user = { id: '123', email: 'john@example.com' }
+
+// Direct connector query - ALL fields included
+const connector = userRepo.getConnector();
+const [fullUser] = await connector
+  .select()
+  .from(User.schema)
+  .where(eq(User.schema.id, '123'));
+// fullUser = { id: '123', email: 'john@example.com', password: 'hashed...', secret: '...' }
+```
+
+### Default Filter
+
+Default filters are **automatically applied** to all repository queries for a model. This is useful for:
+
+- **Soft Delete**: Automatically exclude deleted records
+- **Multi-Tenancy**: Isolate data by tenant
+- **Active Records**: Filter to active/non-expired records
+- **Query Limits**: Prevent unbounded queries
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { isDeleted: false },  // Applied to all queries
+      limit: 100,                    // Prevents unbounded queries
+    },
+  },
+})
+export class Post extends BaseEntity<typeof Post.schema> {
+  static override schema = postTable;
+}
+```
+
+#### Behavior
+
+| Operation | Default Filter |
+|-----------|----------------|
+| `find()`, `findOne()`, `findById()` | Applied to WHERE clause |
+| `count()`, `existsWith()` | Applied to WHERE clause |
+| `updateById()`, `updateAll()` | Applied to WHERE clause |
+| `deleteById()`, `deleteAll()` | Applied to WHERE clause |
+| `create()`, `createAll()` | **Not applied** |
+
+#### Bypassing
+
+Use `shouldSkipDefaultFilter: true` to bypass:
+
+```typescript
+// Normal query - includes default filter
+await postRepo.find({ filter: {} });
+// WHERE isDeleted = false LIMIT 100
+
+// Admin query - bypass default filter
+await postRepo.find({
+  filter: {},
+  options: { shouldSkipDefaultFilter: true }
+});
+// No WHERE clause (includes deleted)
+```
+
+> [!TIP]
+> See [Default Filter](/references/base/filter-system/default-filter) for full documentation including merge strategies and common patterns.
+
 ### Definition Patterns
 
 `BaseEntity` supports two patterns for defining models:
@@ -185,7 +330,7 @@ Enrichers are helper functions located in `packages/core/src/base/models/enriche
 | **`generateUserAuditColumnDefs`** | Adds `createdBy` and `modifiedBy` columns to track user audit information. |
 | **`generateDataTypeColumnDefs`** | Adds generic data type columns (`dataType`, `nValue`, `tValue`, `bValue`, `jValue`, `boValue`) for flexible data storage. |
 | **`generatePrincipalColumnDefs`** | Adds polymorphic fields for associating with different principal types. |
-| **`extraUserColumns`** (from `components/auth/models/entities/user.model.ts`) | Adds common fields for a user model, such as `realm`, `status`, `type`, `activatedAt`, `lastLoginAt`, and `parentId`. |
+| **`extraUserColumns`** | Adds common fields for a user model, such as `realm`, `status`, `type`, `activatedAt`, `lastLoginAt`, and `parentId`. Import from `@venizia/ignis`. |
 
 ### Example Usage
 
@@ -205,7 +350,6 @@ export const myTable = pgTable('MyTable', {
 });
 ```
 
----
 
 ## Detailed Enricher Reference
 
@@ -228,7 +372,7 @@ generateIdColumnDefs<Opts extends TIdEnricherOptions | undefined>(
 ```typescript
 type TIdEnricherOptions = {
   id?: { columnName?: string } & (
-    | { dataType: 'string' }
+    | { dataType: 'string'; generator?: () => string }  // Optional custom ID generator
     | {
         dataType: 'number';
         sequenceOptions?: PgSequenceOptions;
@@ -250,7 +394,7 @@ type TIdEnricherOptions = {
 
 | Data Type | Column Type | Constraints | Description |
 |-----------|------------|-------------|-------------|
-| `'string'` | `uuid` | Primary Key, Default: `gen_random_uuid()` | Native PostgreSQL UUID (no extension required) |
+| `'string'` | `text` | Primary Key, Default: `crypto.randomUUID()` | Text column with customizable ID generator (default: UUID) |
 | `'number'` | `integer` | Primary Key, `GENERATED ALWAYS AS IDENTITY` | Auto-incrementing integer |
 | `'big-number'` | `bigint` | Primary Key, `GENERATED ALWAYS AS IDENTITY` | Auto-incrementing big integer (mode: 'number' or 'bigint') |
 
@@ -259,18 +403,27 @@ type TIdEnricherOptions = {
 The function provides **full TypeScript type inference** based on the configuration options:
 
 ```typescript
-type TIdColumnDef<Opts extends TIdEnricherOptions | undefined> =
-  Opts extends { id: infer IdOpts }
-    ? IdOpts extends { dataType: 'string' }
-      ? { id: IsPrimaryKey<NotNull<HasDefault<PgUUIDBuilderInitial<'id'>>>> }
-      : IdOpts extends { dataType: 'number' }
-        ? { id: IsIdentity<IsPrimaryKey<NotNull<PgIntegerBuilderInitial<'id'>>>, 'always'> }
-        : IdOpts extends { dataType: 'big-number' }
-          ? IdOpts extends { numberMode: 'number' }
-            ? { id: IsIdentity<IsPrimaryKey<NotNull<PgBigInt53BuilderInitial<'id'>>>, 'always'> }
-            : { id: IsIdentity<IsPrimaryKey<NotNull<PgBigInt64BuilderInitial<'id'>>>, 'always'> }
-          : { id: IsIdentity<IsPrimaryKey<NotNull<PgIntegerBuilderInitial<'id'>>>, 'always'> }
-    : { id: IsIdentity<IsPrimaryKey<NotNull<PgIntegerBuilderInitial<'id'>>>, 'always'> };
+// Type aliases for readability
+type TStringIdCol = HasRuntimeDefault<
+  HasDefault<IsPrimaryKey<NotNull<PgTextBuilderInitial<'id', [string, ...string[]]>>>>
+>;
+type TNumberIdCol = IsIdentity<IsPrimaryKey<NotNull<PgIntegerBuilderInitial<'id'>>>, 'always'>;
+type TBigInt53IdCol = IsIdentity<IsPrimaryKey<NotNull<PgBigInt53BuilderInitial<'id'>>>, 'always'>;
+type TBigInt64IdCol = IsIdentity<IsPrimaryKey<NotNull<PgBigInt64BuilderInitial<'id'>>>, 'always'>;
+
+type TIdColumnDef<Opts extends TIdEnricherOptions | undefined> = Opts extends {
+  id: infer IdOpts;
+}
+  ? IdOpts extends { dataType: 'string' }
+    ? { id: TStringIdCol }
+    : IdOpts extends { dataType: 'number' }
+      ? { id: TNumberIdCol }
+      : IdOpts extends { dataType: 'big-number' }
+        ? IdOpts extends { numberMode: 'number' }
+          ? { id: TBigInt53IdCol }
+          : { id: TBigInt64IdCol }
+        : { id: TNumberIdCol }
+  : { id: TNumberIdCol };
 ```
 
 This ensures that TypeScript correctly infers the exact column type based on your configuration.
@@ -291,7 +444,7 @@ export const myTable = pgTable('MyTable', {
 // Generates: id integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY
 ```
 
-**UUID-based string ID:**
+**Text-based string ID (UUID by default):**
 
 ```typescript
 export const myTable = pgTable('MyTable', {
@@ -299,8 +452,26 @@ export const myTable = pgTable('MyTable', {
   name: text('name').notNull(),
 });
 
-// Generates: id uuid PRIMARY KEY DEFAULT gen_random_uuid()
-// No extension required - built into PostgreSQL 13+
+// Generates: id text PRIMARY KEY with $defaultFn(() => crypto.randomUUID())
+// Uses text column for maximum database compatibility
+```
+
+**Custom ID generator (e.g., nanoid, cuid):**
+
+```typescript
+import { nanoid } from 'nanoid';
+
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({
+    id: {
+      dataType: 'string',
+      generator: () => nanoid(),  // Custom generator function
+    },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: id text PRIMARY KEY with $defaultFn(() => nanoid())
 ```
 
 **Auto-incrementing integer with sequence options:**
@@ -357,12 +528,12 @@ export const myTable = pgTable('MyTable', {
 
 #### Important Notes
 
-- **UUID Type:** When using `dataType: 'string'`, the native PostgreSQL `uuid` type is used with `gen_random_uuid()` - no extension required (built into PostgreSQL 13+). This is more efficient than `text` type (16 bytes vs 36 bytes) and provides better indexing performance.
+- **Text Column:** When using `dataType: 'string'`, a `text` column is used for maximum database compatibility. This allows you to use any ID format (UUID, nanoid, cuid, etc.) without database-specific constraints.
+- **Custom Generator:** You can provide a custom `generator` function to generate IDs. Default is `crypto.randomUUID()`.
 - **Type Safety:** The return type is fully inferred based on your options, providing better autocomplete and type checking
 - **Big Number Mode:** For `dataType: 'big-number'`, the `numberMode` field is required to specify whether to use JavaScript `number` (up to 2^53-1) or `bigint` (for larger values)
 - **Sequence Options:** Available for `number` and `big-number` types to customize identity generation behavior
 
----
 
 ### `generateTzColumnDefs`
 
@@ -516,7 +687,6 @@ type TTzEnricherResult<ColumnDefinitions extends TColumnDefinitions = TColumnDef
 };
 ```
 
----
 
 ### `generateUserAuditColumnDefs`
 
@@ -625,7 +795,6 @@ export const myTable = pgTable('MyTable', {
 // modifiedBy: integer('editor_id')
 ```
 
----
 
 ## Schema Utilities
 
@@ -790,3 +959,26 @@ try {
 - Recursively handles nested objects
 - Preserves array structures
 - Works seamlessly with Zod's other features (refinements, transforms, etc.)
+
+## See Also
+
+- **Related Concepts:**
+  - [Models Guide](/guides/core-concepts/persistent/models) - Creating models tutorial
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Using models in repositories
+  - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
+
+- **References:**
+  - [Repositories API](/references/base/repositories/) - Data access layer
+  - [Relations](/references/base/repositories/relations) - Model relationships
+  - [Filter System](/references/base/filter-system/) - Querying models
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - Schema definition guide
+  - [PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html) - Column types
+
+- **Best Practices:**
+  - [Data Modeling](/best-practices/data-modeling) - Schema design patterns
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Model examples
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Models with relations