@venizia/ignis-docs 0.0.1-8 → 0.0.1-9

package/wiki/references/base/models.md

@@ -26,49 +26,151 @@ 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 |
 | **Convenience** | Includes `toObject()` and `toJSON()` methods |
 
-### Class Definition
+### Definition Patterns
+
+`BaseEntity` supports two patterns for defining models:
+
+#### Pattern 1: Static Properties (Recommended)
+
+Define schema and relations as static properties:
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { BaseEntity, model, generateIdColumnDefs, createRelations } from '@venizia/ignis';
+
+// Define table schema
+export const userTable = pgTable('User', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  name: text('name').notNull(),
+  email: text('email').notNull(),
+});
+
+// Define relations
+export const userRelations = createRelations({
+  source: userTable,
+  relations: [],
+});
+
+// Entity class with static properties
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
+  static override relations = () => userRelations.definitions;
+  static override TABLE_NAME = 'User';
+}
+```
+
+**Benefits:**
+- Schema and relations are auto-resolved by repositories
+- No need to pass `relations` in repository constructor
+- Cleaner, more declarative syntax
+
+#### Pattern 2: Constructor-Based (Legacy)
+
+Pass schema in constructor:
+
+```typescript
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof userTable> {
+  constructor() {
+    super({ name: 'User', schema: userTable });
+  }
+}
+```
+
+### Static Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `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) |
+
+### IEntity Interface
+
+Models implementing static properties conform to the `IEntity` interface:
 
 ```typescript
-import { createSchemaFactory } from 'drizzle-zod';
-import { BaseHelper } from '../helpers';
-import { SchemaTypes, TSchemaType, TTableSchemaWithId } from './common';
+interface IEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId> {
+  TABLE_NAME?: string;
+  schema: Schema;
+  relations?: TValueOrResolver<Array<TRelationConfig>>;
+}
+```
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `getSchema({ type })` | Get Zod schema for validation (`SELECT`, `CREATE`, `UPDATE`) |
+| `toObject()` | Convert to plain object |
+| `toJSON()` | Convert to JSON string |
 
-export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId> extends BaseHelper {
+### Class Definition
+
+```typescript
+export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId>
+  extends BaseHelper
+  implements IEntity<Schema>
+{
+  // Instance properties
   name: string;
   schema: Schema;
-  schemaFactory: ReturnType<typeof createSchemaFactory>;
 
-  constructor(opts: { name: string; schema: Schema }) {
-    super({ scope: opts.name });
-    this.name = opts.name;
-    this.schema = opts.schema;
-    this.schemaFactory = createSchemaFactory();
+  // Static properties - override in subclass
+  static schema: TTableSchemaWithId;
+  static relations?: TValueOrResolver<Array<TRelationConfig>>;
+  static TABLE_NAME?: string;  // Optional, defaults to class name
+
+  // Static singleton for schemaFactory - shared across all instances
+  // Performance optimization: avoids creating new factory per entity
+  private static _schemaFactory?: ReturnType<typeof createSchemaFactory>;
+  protected static get schemaFactory(): ReturnType<typeof createSchemaFactory> {
+    return (BaseEntity._schemaFactory ??= createSchemaFactory());
+  }
+
+  // Constructor supports both patterns
+  constructor(opts?: { name?: string; schema?: Schema }) {
+    const ctor = new.target as typeof BaseEntity;
+    // Use explicit TABLE_NAME if defined, otherwise fall back to class name
+    const name = opts?.name ?? ctor.TABLE_NAME ?? ctor.name;
+
+    super({ scope: name });
+
+    this.name = name;
+    this.schema = opts?.schema || (ctor.schema as Schema);
   }
 
   getSchema(opts: { type: TSchemaType }) {
+    const factory = BaseEntity.schemaFactory;  // Uses static singleton
     switch (opts.type) {
-      case SchemaTypes.CREATE: {
-        return this.schemaFactory.createInsertSchema(this.schema);
-      }
-      case SchemaTypes.UPDATE: {
-        return this.schemaFactory.createUpdateSchema(this.schema);
-      }
-      case SchemaTypes.SELECT: {
-        return this.schemaFactory.createSelectSchema(this.schema);
-      }
-      default: {
+      case SchemaTypes.CREATE:
+        return factory.createInsertSchema(this.schema);
+      case SchemaTypes.UPDATE:
+        return factory.createUpdateSchema(this.schema);
+      case SchemaTypes.SELECT:
+        return factory.createSelectSchema(this.schema);
+      default:
         throw getError({
-          message: `[getSchema] Invalid schema type | type: ${opts.type} | valid: ${[SchemaTypes.SELECT, SchemaTypes.UPDATE, SchemaTypes.CREATE]}`,
+          message: `[getSchema] Invalid schema type | type: ${opts.type}`,
         });
-      }
     }
   }
+
+  toObject() {
+    return { ...this };
+  }
+
+  toJSON() {
+    return this.toObject();
+  }
 }
 ```
 
-When you define a model in your application, you extend `BaseEntity`, passing your Drizzle table schema to the `super` constructor.
+**Performance Note:** The `schemaFactory` is implemented as a static lazy singleton, meaning it's created once and shared across all `BaseEntity` instances. This avoids the overhead of creating a new `drizzle-zod` schema factory for every entity instantiation.
 
 ## Schema Enrichers
 
@@ -107,6 +209,161 @@ export const myTable = pgTable('MyTable', {
 
 ## Detailed Enricher Reference
 
+### `generateIdColumnDefs`
+
+Adds a primary key `id` column with support for string UUID, integer, or big integer types with full TypeScript type inference.
+
+**File:** `packages/core/src/base/models/enrichers/id.enricher.ts`
+
+#### Signature
+
+```typescript
+generateIdColumnDefs<Opts extends TIdEnricherOptions | undefined>(
+  opts?: Opts,
+): TIdColumnDef<Opts>
+```
+
+#### Options (`TIdEnricherOptions`)
+
+```typescript
+type TIdEnricherOptions = {
+  id?: { columnName?: string } & (
+    | { dataType: 'string' }
+    | {
+        dataType: 'number';
+        sequenceOptions?: PgSequenceOptions;
+      }
+    | {
+        dataType: 'big-number';
+        numberMode: 'number' | 'bigint'; // Required for big-number
+        sequenceOptions?: PgSequenceOptions;
+      }
+  );
+};
+```
+
+**Default values:**
+- `dataType`: `'number'` (auto-incrementing integer)
+- `columnName`: `'id'`
+
+#### Generated Columns
+
+| Data Type | Column Type | Constraints | Description |
+|-----------|------------|-------------|-------------|
+| `'string'` | `uuid` | Primary Key, Default: `gen_random_uuid()` | Native PostgreSQL UUID (no extension required) |
+| `'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') |
+
+#### Type Inference
+
+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'> };
+```
+
+This ensures that TypeScript correctly infers the exact column type based on your configuration.
+
+#### Usage Examples
+
+**Default (auto-incrementing integer):**
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { generateIdColumnDefs } from '@venizia/ignis';
+
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs(),
+  name: text('name').notNull(),
+});
+
+// Generates: id integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY
+```
+
+**UUID-based string ID:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  name: text('name').notNull(),
+});
+
+// Generates: id uuid PRIMARY KEY DEFAULT gen_random_uuid()
+// No extension required - built into PostgreSQL 13+
+```
+
+**Auto-incrementing integer with sequence options:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({
+    id: {
+      dataType: 'number',
+      sequenceOptions: { startWith: 1000, increment: 1 },
+    },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: id integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY (START WITH 1000 INCREMENT BY 1)
+```
+
+**Big number with JavaScript number mode (up to 2^53-1):**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({
+    id: {
+      dataType: 'big-number',
+      numberMode: 'number', // Required field
+      sequenceOptions: { startWith: 1, increment: 1 },
+    },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: id bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY
+// Type-safe: Returns PgBigInt53BuilderInitial (safe for JavaScript numbers)
+```
+
+**Big number with BigInt mode (for values > 2^53-1):**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({
+    id: {
+      dataType: 'big-number',
+      numberMode: 'bigint', // Required field
+      sequenceOptions: { startWith: 1, increment: 1 },
+    },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: id bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY
+// Type-safe: Returns PgBigInt64BuilderInitial (requires BigInt in JavaScript)
+```
+
+#### 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.
+- **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`
 
 Adds timestamp columns for tracking entity creation, modification, and soft deletion.
@@ -124,11 +381,15 @@ generateTzColumnDefs(opts?: TTzEnricherOptions): TTzEnricherResult
 ```typescript
 type TTzEnricherOptions = {
   created?: { columnName: string; withTimezone: boolean };
-  modified?: { enable: boolean; columnName: string; withTimezone: boolean };
-  deleted?: { enable: boolean; columnName: string; withTimezone: boolean };
+  modified?: { enable: false } | { enable?: true; columnName: string; withTimezone: boolean };
+  deleted?: { enable: false } | { enable?: true; columnName: string; withTimezone: boolean };
 };
 ```
 
+The `modified` and `deleted` options use a discriminated union pattern:
+- When `enable: false`, no other properties are needed
+- When `enable: true` (or omitted), `columnName` and `withTimezone` are required
+
 **Default values:**
 - `created`: `{ columnName: 'created_at', withTimezone: true }`
 - `modified`: `{ enable: true, columnName: 'modified_at', withTimezone: true }`
@@ -257,6 +518,115 @@ type TTzEnricherResult<ColumnDefinitions extends TColumnDefinitions = TColumnDef
 
 ---
 
+### `generateUserAuditColumnDefs`
+
+Adds `createdBy` and `modifiedBy` columns to track which user created or modified a record.
+
+**File:** `packages/core/src/base/models/enrichers/user-audit.enricher.ts`
+
+#### Signature
+
+```typescript
+generateUserAuditColumnDefs(opts?: TUserAuditEnricherOptions): {
+  createdBy: PgIntegerBuilderInitial | PgTextBuilderInitial;
+  modifiedBy: PgIntegerBuilderInitial | PgTextBuilderInitial;
+}
+```
+
+#### Options (`TUserAuditEnricherOptions`)
+
+```typescript
+type TUserAuditColumnOpts = {
+  dataType: 'string' | 'number';  // Required - type of user ID
+  columnName: string;              // Column name in database
+};
+
+type TUserAuditEnricherOptions = {
+  created?: TUserAuditColumnOpts;
+  modified?: TUserAuditColumnOpts;
+};
+```
+
+**Default values:**
+- `created`: `{ dataType: 'number', columnName: 'created_by' }`
+- `modified`: `{ dataType: 'number', columnName: 'modified_by' }`
+
+#### Generated Columns
+
+| Column | Data Type | Column Name | Description |
+|--------|-----------|-------------|-------------|
+| `createdBy` | `integer` or `text` | `created_by` | User ID who created the record |
+| `modifiedBy` | `integer` or `text` | `modified_by` | User ID who last modified the record |
+
+#### Validation
+
+The enricher validates the `dataType` option and throws an error for invalid values:
+
+```typescript
+// ✅ Valid
+generateUserAuditColumnDefs({ created: { dataType: 'number', columnName: 'created_by' } });
+generateUserAuditColumnDefs({ created: { dataType: 'string', columnName: 'created_by' } });
+
+// ❌ Invalid - throws error
+generateUserAuditColumnDefs({ created: { dataType: 'uuid', columnName: 'created_by' } });
+// Error: [enrichUserAudit] Invalid dataType for 'createdBy' | value: uuid | valid: ['number', 'string']
+```
+
+#### Usage Examples
+
+**Default (integer user IDs):**
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { generateIdColumnDefs, generateUserAuditColumnDefs } from '@venizia/ignis';
+
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs(),
+  ...generateUserAuditColumnDefs(),
+  name: text('name').notNull(),
+});
+
+// Generates:
+// createdBy: integer('created_by')
+// modifiedBy: integer('modified_by')
+```
+
+**String user IDs (UUID):**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  ...generateUserAuditColumnDefs({
+    created: { dataType: 'string', columnName: 'created_by' },
+    modified: { dataType: 'string', columnName: 'modified_by' },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates:
+// createdBy: text('created_by')
+// modifiedBy: text('modified_by')
+```
+
+**Custom column names:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs(),
+  ...generateUserAuditColumnDefs({
+    created: { dataType: 'number', columnName: 'author_id' },
+    modified: { dataType: 'number', columnName: 'editor_id' },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates:
+// createdBy: integer('author_id')
+// modifiedBy: integer('editor_id')
+```
+
+---
+
 ## Schema Utilities
 
 ### `snakeToCamel`
@@ -325,7 +695,7 @@ console.log(result);
 **Use case:** API endpoint that accepts snake_case but works with camelCase internally
 
 ```typescript
-import { BaseController, controller, snakeToCamel } from '@venizia/ignis';
+import { BaseController, controller, snakeToCamel, HTTP } from '@venizia/ignis';
 import { z } from '@hono/zod-openapi';
 
 const createUserSchema = snakeToCamel({
@@ -366,7 +736,7 @@ export class UserController extends BaseController {
         console.log(data.firstName);  // ✅ TypeScript knows this exists
         console.log(data.first_name);  // ❌ TypeScript error
         
-        return ctx.json({ success: true });
+        return ctx.json({ success: true }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
   }