@akanjs/cli 0.0.142 → 0.0.144

package/esm/src/guidelines/modelConstant/modelConstant.instruction.md

@@ -0,0 +1,958 @@
+# Akan.js Model Constant Implementation Guide
+
+## Purpose and Role of Model Constant Files
+
+Model constant files (`model.constant.ts`) serve as the foundation of the Akan.js framework by:
+
+- Defining data structures for database schemas
+- Generating GraphQL types for API interfaces
+- Configuring validation rules for input data
+- Establishing relationships between entities
+- Supporting search indexing and optimization
+- Enabling type-safe data manipulation
+- Creating a single source of truth for the data model
+
+## Model Class Hierarchy and Relationships
+
+Akan.js uses a multi-tiered model architecture with clear inheritance patterns:
+
+```
+                           ┌───────────────┐
+                           │  ModelInput   │
+                           └───────┬───────┘
+                                   │
+                                   ▼
+                           ┌───────────────┐
+                           │  ModelObject  │
+                           └───┬───────────┘
+                               │
+           ┌─────────────────┬─┴───┬─────────────────┐
+           │                 │     │                 │
+           ▼                 ▼     ▼                 ▼
+┌───────────────────┐  ┌─────────┐ ┌─────────┐ ┌─────────────┐
+│ ModelFilter       │  │ Model   │ │LightMod.│ │ModelInsight │
+└───────────────────┘  └─────────┘ └─────────┘ └─────────────┘
+                                                      │
+                                                      ▼
+                                              ┌───────────────┐
+                                              │ModelSummary   │
+                                              └───────────────┘
+```
+
+Each model type serves a specific purpose in the data lifecycle:
+
+1. **Input Model**: User-provided data for create/update operations
+2. **Object Model**: Input + system-managed fields
+3. **Light Model**: Subset of Object for listings/references
+4. **Full Model**: Complete model for database schema
+5. **Filter Model**: Query methods and sorting options
+6. **Insight Model**: Aggregation fields for analytics
+7. **Summary Model**: Dashboard statistics and counters
+
+## File Structure and Organization
+
+```typescript
+// 1. Imports
+import { enumOf, ID, Int } from "@akanjs/base";
+import { Field, Filter, Model, sortOf, via } from "@akanjs/constant";
+import { LightRelatedModel } from "../related/related.constant";
+
+// 2. Enums
+export const StatusEnum = enumOf(["active", "inactive"] as const);
+export type StatusEnum = enumOf<typeof StatusEnum>;
+
+// 3. Input Model
+@Model.Input("ProductInput")
+export class ProductInput {
+  // User-editable fields
+}
+
+// 4. Object Model
+@Model.Object("ProductObject")
+export class ProductObject extends via(ProductInput) {
+  // System fields
+}
+
+// 5. Light Model
+@Model.Light("LightProduct")
+export class LightProduct extends via(ProductObject, ["id", "name", "price"] as const) {}
+
+// 6. Full Model
+@Model.Full("Product")
+export class Product extends via(ProductObject, LightProduct) {}
+
+// 7. Insight Model (optional)
+@Model.Insight("ProductInsight")
+export class ProductInsight {
+  // Aggregation fields
+}
+
+// 8. Summary Model (optional)
+@Model.Summary("ProductSummary")
+export class ProductSummary {
+  // Summary statistics
+}
+
+// 9. Filter Model
+@Model.Filter("ProductFilter")
+export class ProductFilter extends sortOf(Product, {
+  newest: { createdAt: -1 },
+}) {
+  // Query methods
+}
+```
+
+## Required Imports
+
+```typescript
+// Base types
+import { enumOf, ID, Int, Float, String, Boolean, Date, type Dayjs, dayjs, JSON } from "@akanjs/base";
+
+// Model decorators
+import { Field, Filter, Model, sortOf, via } from "@akanjs/constant";
+
+// Related models (use Light models to prevent circular dependencies)
+import { LightCategory } from "../category/category.constant";
+```
+
+## Enum Definition Patterns
+
+Enums should be defined with `enumOf()` and exported as both const and type:
+
+```typescript
+// Define enum with camelCase values (preferred)
+export const StatusEnum = enumOf([
+  "active",
+  "inactive",
+  "pending"
+] as const);
+
+// Export as type for TypeScript
+export type StatusEnum = enumOf<typeof StatusEnum>;
+
+// Usage in fields
+@Field.Prop(() => String, {
+  enum: StatusEnum,
+  default: "active"
+})
+status: StatusEnum;
+```
+
+## ModelInput Implementation
+
+The Input model defines fields that users can create or update:
+
+```typescript
+@Model.Input("ProductInput")
+export class ProductInput {
+  @Field.Prop(() => String, {
+    minlength: 3,
+    maxlength: 100,
+  })
+  name: string;
+
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+  })
+  price: number;
+
+  @Field.Prop(() => String, {
+    nullable: true,
+    maxlength: 1000,
+  })
+  description: string | null;
+
+  @Field.Prop(() => LightCategory, {
+    ref: "Category",
+  })
+  category: LightCategory;
+}
+```
+
+Key characteristics:
+
+- Contains only user-editable fields
+- Includes validation rules (min, max, etc.)
+- Uses nullable fields for optional data
+- References other models with Light variants
+- No system-generated fields (id, timestamps)
+
+## ModelObject Implementation
+
+The Object model extends Input with system-managed fields:
+
+```typescript
+@Model.Object("ProductObject")
+export class ProductObject extends via(ProductInput) {
+  @Field.Prop(() => String, {
+    enum: StatusEnum,
+    default: "active",
+  })
+  status: StatusEnum;
+
+  @Field.Prop(() => Int, {
+    default: 0,
+    min: 0,
+  })
+  viewCount: number;
+
+  @Field.Hidden(() => String, {
+    nullable: true,
+  })
+  internalNotes: string | null;
+
+  @Field.Secret(() => String, {
+    nullable: true,
+  })
+  apiKey: string | null;
+}
+```
+
+Key characteristics:
+
+- Inherits all Input model fields via `via()`
+- Adds system-managed fields like status
+- Can include counters and metrics
+- May include hidden fields with `Field.Hidden`
+- May include sensitive data with `Field.Secret`
+
+## LightModel Implementation
+
+The Light model defines a subset of fields for listings and references:
+
+```typescript
+@Model.Light("LightProduct")
+export class LightProduct extends via(ProductObject, ["id", "name", "price", "status", "category"] as const) {}
+```
+
+Key characteristics:
+
+- Selects essential fields from Object model
+- Uses `as const` assertion for type safety
+- Always includes `id` field
+- Optimized for listings and relationships
+- No additional fields, only selection
+
+## Full Model Implementation
+
+The Full model combines Object and Light models for database schema:
+
+```typescript
+@Model.Full("Product")
+export class Product extends via(ProductObject, LightProduct) {}
+```
+
+Key characteristics:
+
+- Usually empty implementation
+- Combines Object and Light models
+- Used for database schema generation
+- Primary model for CRUD operations
+- Name should match the base entity (no suffix)
+
+## Insight Model Implementation
+
+The Insight model defines fields for analytics and aggregation:
+
+```typescript
+@Model.Insight("ProductInsight")
+export class ProductInsight {
+  @Field.Prop(() => Int, {
+    default: 0,
+    accumulate: { $sum: 1 },
+  })
+  count: number;
+
+  @Field.Prop(() => Int, {
+    default: 0,
+    accumulate: { $sum: "$price" },
+  })
+  totalSales: number;
+
+  @Field.Prop(() => Float, {
+    default: 0,
+    accumulate: { $avg: "$price" },
+  })
+  averagePrice: number;
+}
+```
+
+Key characteristics:
+
+- Uses MongoDB accumulator operators
+- Defines metrics and KPIs
+- Supports data analytics
+- Fields typically have numeric types
+- Often has count, sum, avg operations
+
+## Summary Model Implementation
+
+The Summary model defines dashboard statistics:
+
+```typescript
+@Model.Summary("ProductSummary")
+export class ProductSummary {
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+    query: {},
+  })
+  totalProducts: number;
+
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+    query: { status: "active" },
+  })
+  activeProducts: number;
+
+  @Field.Prop(() => Float, {
+    default: 0,
+    query: { price: { $gt: 0 } },
+  })
+  averagePrice: number;
+}
+```
+
+Key characteristics:
+
+- Defines summary statistics for dashboards
+- Uses `query` option to filter records
+- Provides high-level metrics
+- May combine data from multiple models
+- Often uses queries to filter record sets
+
+## Filter Model Implementation
+
+The Filter model defines query operations and sorting options:
+
+```typescript
+@Model.Filter("ProductFilter")
+export class ProductFilter extends sortOf(Product, {
+  newest: { createdAt: -1 },
+  oldest: { createdAt: 1 },
+  cheapest: { price: 1 },
+  expensive: { price: -1 },
+}) {
+  @Filter.Mongo()
+  byStatus(
+    @Filter.Arg("status", () => String, {
+      enum: StatusEnum,
+      default: "active",
+    })
+    status: StatusEnum
+  ) {
+    return { status };
+  }
+
+  @Filter.Mongo()
+  inCategory(
+    @Filter.Arg("categoryId", () => ID, {
+      ref: "Category",
+      renderOption: (cat: LightCategory) => cat.name,
+    })
+    categoryId: string
+  ) {
+    return { category: categoryId };
+  }
+
+  @Filter.Mongo()
+  priceRange(
+    @Filter.Arg("min", () => Int, { min: 0, default: 0 })
+    min: number,
+
+    @Filter.Arg("max", () => Int, { min: 0, nullable: true })
+    max: number | null
+  ) {
+    const query: Record<string, any> = { price: { $gte: min } };
+    if (max !== null) {
+      query.price.$lte = max;
+    }
+    return query;
+  }
+}
+```
+
+Key characteristics:
+
+- Extends with `sortOf()` to define sorting options
+- Uses `@Filter.Mongo()` for query methods
+- Defines parameters with `@Filter.Arg()`
+- Returns MongoDB query objects
+- Can have complex query logic
+- Supports references with `ref` option
+
+## Field Decorators and Options
+
+Field decorators configure property behavior:
+
+```typescript
+// Standard field (visible in API and DB)
+@Field.Prop(() => String, { options })
+name: string;
+
+// Hidden field (DB only, not in API)
+@Field.Hidden(() => JSON, { options })
+metadata: Record<string, any>;
+
+// Sensitive field (not selected by default)
+@Field.Secret(() => String, { options })
+apiKey: string;
+
+// Computed field (not stored in DB)
+@Field.Resolve(() => Int)
+get total(): number {
+  return this.quantity * this.price;
+}
+```
+
+Common field options:
+
+| Option      | Type       | Description              | Example                    |
+| ----------- | ---------- | ------------------------ | -------------------------- |
+| `default`   | `any`      | Default value            | `{ default: 0 }`           |
+| `nullable`  | `boolean`  | Allows null              | `{ nullable: true }`       |
+| `enum`      | `Enum`     | Restricts to enum values | `{ enum: StatusEnum }`     |
+| `min`       | `number`   | Minimum value            | `{ min: 0 }`               |
+| `max`       | `number`   | Maximum value            | `{ max: 100 }`             |
+| `minlength` | `number`   | Minimum string length    | `{ minlength: 3 }`         |
+| `maxlength` | `number`   | Maximum string length    | `{ maxlength: 255 }`       |
+| `ref`       | `string`   | Reference to model       | `{ ref: "Category" }`      |
+| `refPath`   | `string`   | Dynamic reference path   | `{ refPath: "modelType" }` |
+| `immutable` | `boolean`  | Cannot be changed        | `{ immutable: true }`      |
+| `validate`  | `function` | Custom validation        | `{ validate: isEmail }`    |
+| `text`      | `string`   | Search configuration     | `{ text: "search" }`       |
+
+## Filter Decorators and Arguments
+
+Filter decorators define query methods:
+
+```typescript
+// MongoDB query
+@Filter.Mongo()
+byStatus(
+  @Filter.Arg("status", () => String, {
+    enum: StatusEnum,
+    default: "active"
+  })
+  status: StatusEnum
+) {
+  return { status };
+}
+
+// Meilisearch query
+@Filter.Meili()
+searchText(
+  @Filter.Arg("query", () => String)
+  query: string
+) {
+  return { q: query };
+}
+```
+
+Filter argument options:
+
+| Option         | Description              | Example                           |
+| -------------- | ------------------------ | --------------------------------- |
+| `enum`         | Restricts to enum values | `{ enum: StatusEnum }`            |
+| `default`      | Default value            | `{ default: "active" }`           |
+| `nullable`     | Allows null              | `{ nullable: true }`              |
+| `ref`          | Reference to model       | `{ ref: "Category" }`             |
+| `renderOption` | Display function         | `{ renderOption: (x) => x.name }` |
+
+## Inheritance with via() and sortOf()
+
+Akan.js uses utility functions for model inheritance:
+
+```typescript
+// Inherit all fields from Input model
+extends via(ProductInput)
+
+// Inherit specific fields from Object model
+extends via(ProductObject, [
+  "id", "name", "price"
+] as const)
+
+// Inherit both Object and Light models
+extends via(ProductObject, LightProduct)
+
+// Define sorting options
+extends sortOf(Product, {
+  newest: { createdAt: -1 },
+  cheapest: { price: 1 }
+})
+```
+
+Key points:
+
+- `via()` handles field inheritance
+- Field selection uses `as const` for type safety
+- `sortOf()` configures sorting options for filters
+- Sort order: 1 for ascending, -1 for descending
+
+## Working with References to Other Models
+
+Models can reference other models in several ways:
+
+```typescript
+// Basic reference
+@Field.Prop(() => LightCategory, { ref: "Category" })
+category: LightCategory;
+
+// Array of references
+@Field.Prop(() => [LightTag], { ref: "Tag" })
+tags: LightTag[];
+
+// Optional reference
+@Field.Prop(() => LightUser, {
+  ref: "User",
+  nullable: true
+})
+assignedTo: LightUser | null;
+
+// Dynamic reference (polymorphic)
+@Field.Prop(() => String, { enum: ModelType })
+modelType: ModelType;
+
+@Field.Prop(() => LightModel, { refPath: "modelType" })
+model: LightModel;
+
+// Parent-child relationship
+@Field.Prop(() => LightProject, {
+  ref: "Project",
+  refType: "parent"
+})
+project: LightProject;
+```
+
+Key points:
+
+- Always use Light models for references
+- Set `ref` to the model name string
+- Use arrays for one-to-many relationships
+- Use `refPath` for polymorphic relationships
+- Set `refType` for relationship semantics
+
+## Validation Rules and Constraints
+
+Add validation to ensure data integrity:
+
+```typescript
+// Numeric range validation
+@Field.Prop(() => Int, { min: 0, max: 100 })
+score: number;
+
+// String length validation
+@Field.Prop(() => String, { minlength: 3, maxlength: 50 })
+username: string;
+
+// Format validation
+@Field.Prop(() => String, { type: "email" })
+email: string;
+
+// Custom validation function
+@Field.Prop(() => String, {
+  validate: (value, model) => {
+    return /^[A-Z][a-z]+$/.test(value);
+  }
+})
+properName: string;
+```
+
+## Type Safety Considerations
+
+Ensure type safety across the model:
+
+```typescript
+// 1. Use proper types for fields
+@Field.Prop(() => Int)
+count: number;  // TypeScript type matches decorator type
+
+// 2. Mark arrays as const for Light models
+extends via(ProductObject, [
+  "id", "name"
+] as const)  // Type-safe field selection
+
+// 3. Handle nullable fields correctly
+@Field.Prop(() => String, { nullable: true })
+description: string | null;  // Include union with null
+
+// 4. Export enum types
+export type StatusEnum = enumOf<typeof StatusEnum>;
+
+// 5. Use precise array types
+@Field.Prop(() => [Int])
+scores: number[];  // Array of integers
+```
+
+## Common Mistakes and Solutions
+
+### 1. Missing Field Type
+
+```typescript
+// ❌ Wrong (missing type function)
+@Field.Prop(String)
+name: string;
+
+// ✅ Correct
+@Field.Prop(() => String)
+name: string;
+```
+
+### 2. Incorrect Array Type
+
+```typescript
+// ❌ Wrong (using Array<T> syntax)
+@Field.Prop(() => Array<String>)
+tags: string[];
+
+// ✅ Correct
+@Field.Prop(() => [String])
+tags: string[];
+```
+
+### 3. Missing Const Assertion
+
+```typescript
+// ❌ Wrong (missing as const)
+extends via(ProductObject, ["id", "name"])
+
+// ✅ Correct
+extends via(ProductObject, ["id", "name"] as const)
+```
+
+### 4. Missing Nullable Type
+
+```typescript
+// ❌ Wrong (missing null in type)
+@Field.Prop(() => String, { nullable: true })
+description: string;
+
+// ✅ Correct
+@Field.Prop(() => String, { nullable: true })
+description: string | null;
+```
+
+### 5. Circular Dependencies
+
+```typescript
+// ❌ Wrong (circular dependency)
+import { Product } from "../product/product.constant";
+
+// ✅ Correct
+import { LightProduct } from "../product/product.constant";
+```
+
+### 6. Missing Default for Arrays
+
+```typescript
+// ❌ Wrong (no default for array)
+@Field.Prop(() => [String])
+tags: string[];
+
+// ✅ Correct
+@Field.Prop(() => [String], { default: [] })
+tags: string[];
+```
+
+## Best Practices for Maintainable Models
+
+1. **Follow the standard model hierarchy**
+
+   - Create all model types in the recommended order
+   - Use inheritance properly with `via()` and `sortOf()`
+
+2. **Keep models focused**
+
+   - Each model should represent a single entity
+   - Split complex models into related entities
+
+3. **Use proper naming conventions**
+
+   - File: `camelCase.constant.ts`
+   - Classes: `PascalCase` with type suffix
+   - Fields: `camelCase`
+   - Enums: `PascalCase` with `Enum` suffix
+
+4. **Add appropriate defaults**
+
+   - Set reasonable defaults for required fields
+   - Use empty arrays for array fields: `{ default: [] }`
+   - Use function defaults for dates: `{ default: () => dayjs() }`
+
+5. **Implement proper validation**
+
+   - Add min/max for numbers
+   - Add minlength/maxlength for strings
+   - Use custom validation for complex rules
+
+6. **Optimize Light models**
+
+   - Include only essential fields
+   - Always include `id` field
+   - Keep them small for efficient API responses
+
+7. **Document complex fields**
+
+   - Add comments for non-obvious fields
+   - Explain validation rules when complex
+
+8. **Use appropriate Field decorators**
+
+   - `Field.Prop` for standard fields
+   - `Field.Hidden` for internal data
+   - `Field.Secret` for sensitive data
+   - `Field.Resolve` for computed properties
+
+9. **Handle references correctly**
+
+   - Always use Light models for references
+   - Set proper `ref` option to model name
+   - Use `refPath` for polymorphic references
+
+10. **Export everything needed**
+    - Export all models and enums
+    - Export type definitions for enums
+
+## Complete Example with All Model Types
+
+```typescript
+// File: apps/ecommerce/lib/product/product.constant.ts
+import { enumOf, ID, Int, Float, type Dayjs, dayjs } from "@akanjs/base";
+import { Field, Filter, Model, sortOf, via } from "@akanjs/constant";
+
+import { LightCategory } from "../category/category.constant";
+import { LightUser } from "../user/user.constant";
+
+// Enums
+export const ProductStatus = enumOf(["draft", "active", "outOfStock", "discontinued"] as const);
+export type ProductStatus = enumOf<typeof ProductStatus>;
+
+// Input Model
+@Model.Input("ProductInput")
+export class ProductInput {
+  @Field.Prop(() => String, {
+    minlength: 3,
+    maxlength: 100,
+  })
+  name: string;
+
+  @Field.Prop(() => String, {
+    nullable: true,
+    maxlength: 1000,
+  })
+  description: string | null;
+
+  @Field.Prop(() => Float, {
+    min: 0,
+    default: 0,
+  })
+  price: number;
+
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+  })
+  stock: number;
+
+  @Field.Prop(() => LightCategory, {
+    ref: "Category",
+  })
+  category: LightCategory;
+
+  @Field.Prop(() => [String], {
+    default: [],
+  })
+  tags: string[];
+
+  @Field.Prop(() => String, {
+    nullable: true,
+  })
+  imageUrl: string | null;
+}
+
+// Object Model
+@Model.Object("ProductObject")
+export class ProductObject extends via(ProductInput) {
+  @Field.Prop(() => String, {
+    enum: ProductStatus,
+    default: "draft",
+  })
+  status: ProductStatus;
+
+  @Field.Prop(() => LightUser, {
+    ref: "User",
+  })
+  createdBy: LightUser;
+
+  @Field.Prop(() => Int, {
+    default: 0,
+    min: 0,
+  })
+  viewCount: number;
+
+  @Field.Prop(() => Date, {
+    default: () => dayjs(),
+    immutable: true,
+  })
+  launchDate: Dayjs;
+
+  @Field.Hidden(() => String, {
+    nullable: true,
+  })
+  internalNotes: string | null;
+}
+
+// Light Model
+@Model.Light("LightProduct")
+export class LightProduct extends via(ProductObject, [
+  "id",
+  "name",
+  "price",
+  "imageUrl",
+  "status",
+  "category",
+] as const) {}
+
+// Full Model
+@Model.Full("Product")
+export class Product extends via(ProductObject, LightProduct) {}
+
+// Insight Model
+@Model.Insight("ProductInsight")
+export class ProductInsight {
+  @Field.Prop(() => Int, {
+    default: 0,
+    accumulate: { $sum: 1 },
+  })
+  count: number;
+
+  @Field.Prop(() => Float, {
+    default: 0,
+    accumulate: { $sum: "$price" },
+  })
+  totalValue: number;
+
+  @Field.Prop(() => Int, {
+    default: 0,
+    accumulate: { $sum: "$viewCount" },
+  })
+  totalViews: number;
+}
+
+// Summary Model
+@Model.Summary("ProductSummary")
+export class ProductSummary {
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+    query: {},
+  })
+  totalProducts: number;
+
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+    query: { status: "active" },
+  })
+  activeProducts: number;
+
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+    query: { stock: { $lte: 0 } },
+  })
+  outOfStockProducts: number;
+}
+
+// Filter Model
+@Model.Filter("ProductFilter")
+export class ProductFilter extends sortOf(Product, {
+  newest: { createdAt: -1 },
+  oldest: { createdAt: 1 },
+  cheapest: { price: 1 },
+  expensive: { price: -1 },
+  popular: { viewCount: -1 },
+}) {
+  @Filter.Mongo()
+  byStatus(
+    @Filter.Arg("status", () => String, {
+      enum: ProductStatus,
+      default: "active",
+    })
+    status: ProductStatus
+  ) {
+    return { status };
+  }
+
+  @Filter.Mongo()
+  inCategory(
+    @Filter.Arg("categoryId", () => ID, {
+      ref: "Category",
+      renderOption: (cat: LightCategory) => cat.name,
+    })
+    categoryId: string
+  ) {
+    return { category: categoryId };
+  }
+
+  @Filter.Mongo()
+  hasTag(
+    @Filter.Arg("tag", () => String)
+    tag: string
+  ) {
+    return { tags: tag };
+  }
+
+  @Filter.Mongo()
+  priceRange(
+    @Filter.Arg("min", () => Float, {
+      min: 0,
+      default: 0,
+    })
+    min: number,
+
+    @Filter.Arg("max", () => Float, {
+      min: 0,
+      nullable: true,
+    })
+    max: number | null
+  ) {
+    const query: Record<string, any> = { price: { $gte: min } };
+    if (max !== null) {
+      query.price.$lte = max;
+    }
+    return query;
+  }
+
+  @Filter.Mongo()
+  inStock() {
+    return { stock: { $gt: 0 } };
+  }
+
+  @Filter.Meili()
+  searchText(
+    @Filter.Arg("query", () => String)
+    query: string
+  ) {
+    return { q: query };
+  }
+}
+```
+
+## Summary Checklist
+
+1. **Structure**: Follow the model hierarchy (Input → Object → Light/Full → Filter/Summary/Insight)
+2. **Naming**: Use consistent class naming (ModelInput, ModelObject, LightModel, Model)
+3. **Enums**: Define with `enumOf()` and export both const and type
+4. **Fields**: Use `Field.Prop` with appropriate options
+5. **Validation**: Add constraints (min, max, minlength, maxlength)
+6. **Defaults**: Set appropriate defaults, especially for arrays
+7. **References**: Use Light models with proper `ref` option
+8. **Light Models**: Select essential fields with `as const` assertion
+9. **Full Models**: Combine Object and Light models
+10. **Filter Models**: Define sort options and query methods
+11. **Insight/Summary**: Add aggregation and summary fields
+12. **Type Safety**: Ensure TypeScript types match field definitions
+13. **Exports**: Export all models and enums