@akanjs/cli 0.0.145 → 0.0.147

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

@@ -14,92 +14,92 @@ Model constant files (`model.constant.ts`) serve as the foundation of the Akan.j
 
 ## Model Class Hierarchy and Relationships
 
-Akan.js uses a multi-tiered model architecture with clear inheritance patterns:
-
-```
-                           ┌───────────────┐
-                           │  ModelInput   │
-                           └───────┬───────┘
-                                   │
-                                   ▼
-                           ┌───────────────┐
-                           │  ModelObject  │
-                           └───┬───────────┘
-                               │
-           ┌─────────────────┬─┴───┬─────────────────┐
-           │                 │     │                 │
-           ▼                 ▼     ▼                 ▼
-┌───────────────────┐  ┌─────────┐ ┌─────────┐ ┌─────────────┐
-│ ModelFilter       │  │ Model   │ │LightMod.│ │ModelInsight │
-└───────────────────┘  └─────────┘ └─────────┘ └─────────────┘
-                                                      │
-                                                      ▼
-                                              ┌───────────────┐
-                                              │ModelSummary   │
-                                              └───────────────┘
+```mermaid
+graph TD
+    Input[Model.Input] --> Object[Model.Object]
+    Object --> Light[Model.Light]
+    Object --> Full[Model.Full]
+    Object --> Insight[Model.Insight]
+    Insight --> Summary[Model.Summary]
+    Object --> Query[Model.Query]
+    Object --> Sort[Model.Sort]
 ```
 
 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
+1. **Input Model**: Data required to create a schema
+2. **Object Model**: Schema completed when data is created
+3. **Light Model**: Lightweight schema used when querying multiple data
+4. **Full Model**: Class-based complete form of data
+5. **Insight Model**: Statistical data extractable during queries
+6. **Summary Model**: Statistical data extracted periodically during monitoring
+7. **Query Model**: Defines query methods and statements
+8. **Sort Model**: Defines sort keys and values for data ordering
 
 ## 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";
+import { Field, Model } from "@akanjs/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
+@Model.Input("DroneInput")
+export class DroneInput {
+  @Field.Prop(() => String)
+  name: string;
 }
 
 // 4. Object Model
-@Model.Object("ProductObject")
-export class ProductObject extends via(ProductInput) {
-  // System fields
+@Model.Object("DroneObject")
+export class DroneObject extends BaseModel(DroneInput) {
+  @Field.Prop(() => String, { enum: StatusEnum, default: "offline" })
+  status: StatusEnum;
 }
 
 // 5. Light Model
-@Model.Light("LightProduct")
-export class LightProduct extends via(ProductObject, ["id", "name", "price"] as const) {}
+@Model.Light("LightDrone")
+export class LightDrone extends Light(DroneObject, ["id", "name", "status"] as const) {
+  isConnected() {
+    return this.status !== "offline";
+  }
+}
 
 // 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
+@Model.Full("Drone")
+export class Drone extends Full(DroneObject, LightDrone) {
+  isAvailable() {
+    return this.isConnected() && this.wsUri.startsWith("ws://");
+  }
 }
 
-// 8. Summary Model (optional)
-@Model.Summary("ProductSummary")
-export class ProductSummary {
-  // Summary statistics
+// 7. Insight Model
+@Model.Insight("DroneInsight")
+export class DroneInsight {
+  @Field.Prop(() => Int, { default: 0, accumulate: { $sum: 1 } })
+  count: number;
 }
 
-// 9. Filter Model
-@Model.Filter("ProductFilter")
-export class ProductFilter extends sortOf(Product, {
-  newest: { createdAt: -1 },
-}) {
-  // Query methods
+// 8. Summary Model
+@Model.Summary("DroneSummary")
+export class DroneSummary {
+  @Field.Prop(() => Int, { min: 0, default: 0, query: { status: { $ne: "inactive" } } })
+  totalDrone: number;
 }
+
+// 9. Query Model
+export const droneQuery = {
+  byName: (name: string) => ({ name }),
+};
+
+// 10. Sort Model
+export const droneSort = {
+  alphabetical: { name: 1 },
+};
 ```
 
 ## Required Imports
@@ -109,850 +109,433 @@ export class ProductFilter extends sortOf(Product, {
 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";
+import { Field, Model } 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:
+The Input model defines fields required for data creation:
 
 ```typescript
-@Model.Input("ProductInput")
-export class ProductInput {
-  @Field.Prop(() => String, {
-    minlength: 3,
-    maxlength: 100,
-  })
+@Model.Input("DroneInput")
+export class DroneInput {
+  @Field.Prop(() => String)
   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;
+  @Field.Prop(() => String, { default: "ws://10.10.150.10:9091" })
+  wsUri: string;
 }
 ```
 
-Key characteristics:
+**Usage Examples**:
 
-- 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)
+```typescript
+// Document creation
+new this.Drone({ name: "myDrone", wsUri: "ws://10.10.150.10:9091" });
+
+// Service logic
+this.createDrone({ name: "myDrone", wsUri: "ws://10.10.150.10:9091" });
+
+// API call
+fetch.createDrone({ name: "myDrone", wsUri: "ws://10.10.150.10:9091" });
+```
 
 ## ModelObject Implementation
 
-The Object model extends Input with system-managed fields:
+The Object model adds system-managed fields:
 
 ```typescript
-@Model.Object("ProductObject")
-export class ProductObject extends via(ProductInput) {
-  @Field.Prop(() => String, {
-    enum: StatusEnum,
-    default: "active",
-  })
-  status: StatusEnum;
+export const droneStatuses = ["active", "offline", "inactive"] as const;
+export type DroneStatus = (typeof droneStatuses)[number];
 
-  @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;
+@Model.Object("DroneObject")
+export class DroneObject extends BaseModel(DroneInput) {
+  @Field.Prop(() => String, { enum: droneStatuses, default: "offline" })
+  status: DroneStatus;
 }
 ```
 
-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:
+**Usage Examples**:
 
 ```typescript
-@Model.Light("LightProduct")
-export class LightProduct extends via(ProductObject, ["id", "name", "price", "status", "category"] as const) {}
-```
-
-Key characteristics:
+// Document lookup
+const drone = await this.Drone.pickById("droneId"); // drone.status
 
-- 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
+// Service lookup
+const drone = await this.getDrone("droneId"); // drone.status
 
-## Full Model Implementation
-
-The Full model combines Object and Light models for database schema:
+// Store lookup
+const drone = await fetch.drone("droneId"); // drone.status
 
-```typescript
-@Model.Full("Product")
-export class Product extends via(ProductObject, LightProduct) {}
+// Component usage
+const drone = st.use.drone(); // drone.status
 ```
 
-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
+## LightModel Implementation
 
-The Insight model defines fields for analytics and aggregation:
+Light model defines lightweight schema for list queries:
 
 ```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;
+@Model.Light("LightDrone")
+export class LightDrone extends Light(DroneObject, ["name", "status"] as const) {
+  isConnected() {
+    return this.status !== "offline";
+  }
 }
 ```
 
-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:
+**Usage Examples**:
 
 ```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:
+// Store query
+const droneList = await fetch.droneList({ status: "active" });
+// drone.name available, drone.wsUri not available
 
-- 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
+// Component usage
+const droneMap = st.use.droneMap(); // Map<string, LightDrone>
+```
 
-## Filter Model Implementation
+## Full Model Implementation
 
-The Filter model defines query operations and sorting options:
+Full model adds convenience functions:
 
 ```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 };
+@Model.Full("Drone")
+export class Drone extends Full(DroneObject, LightDrone) {
+  static isDronesAllConnected(droneList: LightDrone[]) {
+    return droneList.every((drone) => drone.isConnected());
   }
 
-  @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;
+  isAvailable() {
+    return this.isConnected() && this.wsUri.startsWith("ws://");
   }
 }
 ```
 
-Key characteristics:
+**Usage Examples**:
 
-- 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
+```typescript
+// API response handling
+const drone = await fetch.drone("droneId");
+drone.isAvailable();
+
+// Component logic
+const droneMap = st.use.droneMap();
+const droneList = [...droneMap.values()];
+const isAllConnected = cnst.Drone.isDroneAllConnected(droneList);
+```
 
-## Field Decorators and Options
+## Insight Model Implementation
 
-Field decorators configure property behavior:
+Insight model defines statistical fields:
 
 ```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;
+@Model.Insight("DroneInsight")
+export class DroneInsight {
+  @Field.Prop(() => Int, { default: 0, accumulate: { $sum: 1 } })
+  count: number;
 }
 ```
 
-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:
+**Usage Examples**:
 
 ```typescript
-// MongoDB query
-@Filter.Mongo()
-byStatus(
-  @Filter.Arg("status", () => String, {
-    enum: StatusEnum,
-    default: "active"
-  })
-  status: StatusEnum
-) {
-  return { status };
-}
+// Service usage
+const droneInsight = await this.insight({ ...query });
 
-// Meilisearch query
-@Filter.Meili()
-searchText(
-  @Filter.Arg("query", () => String)
-  query: string
-) {
-  return { q: query };
-}
+// API call
+const droneInsight = await fetch.droneInsight({ ...query });
+
+// Component usage
+const droneInsight = st.use.droneInsight(); // droneInsight.count
 ```
 
-Filter argument options:
+## Summary Model Implementation
 
-| 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 }` |
+Summary model defines periodic statistics:
 
-## Inheritance with via() and sortOf()
+```typescript
+@Model.Summary("DroneSummary")
+export class DroneSummary {
+  @Field.Prop(() => Int, { min: 0, default: 0, query: { status: { $ne: "inactive" } } })
+  totalDrone: number;
+}
+```
 
-Akan.js uses utility functions for model inheritance:
+**Usage Examples**:
 
 ```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 }
-})
-```
+// Service usage
+const summary = await this.getActiveSummary();
 
-Key points:
+// API call
+const summary = await fetch.getActiveSummary();
 
-- `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
+// Component usage
+const summary = st.use.summary(); // summary.totalDrone
+```
 
-## Working with References to Other Models
+## Query Model Implementation
 
-Models can reference other models in several ways:
+Query model defines query methods:
 
 ```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;
+export const droneQuery = {
+  ...baseQueries,
+  byName: (name: string) => ({ name }),
+};
 ```
 
-Key points:
+**Usage Examples**:
 
-- 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
+```typescript
+// Document queries
+const drone = await this.findByName("myDrone");
+const drones = await this.listByName("myDrone");
+const droneCount = await this.countByName("myDrone");
+
+// Service queries
+const drone = await this.findByName("myDrone");
+const drones = await this.listByName("myDrone");
+```
 
-## Validation Rules and Constraints
+## Sort Model Implementation
 
-Add validation to ensure data integrity:
+Sort model defines sorting options:
 
 ```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;
+export const droneSort = {
+  ...baseSorts,
+  alphabetical: { name: 1 },
+};
 ```
 
-## Type Safety Considerations
-
-Ensure type safety across the model:
+**Usage Examples**:
 
 ```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
+// Document sorting
+const drones = await this.listByName("myDrone", { sort: "alphabetical" });
 
-// 3. Handle nullable fields correctly
-@Field.Prop(() => String, { nullable: true })
-description: string | null;  // Include union with null
+// Service sorting
+const drones = await this.listByName("myDrone", { sort: "alphabetical" });
+```
 
-// 4. Export enum types
-export type StatusEnum = enumOf<typeof StatusEnum>;
+## Field Decorators and Options
 
-// 5. Use precise array types
-@Field.Prop(() => [Int])
-scores: number[];  // Array of integers
+| Option       | Type                 | Default | Description                            | Example                                                                |
+| ------------ | -------------------- | ------- | -------------------------------------- | ---------------------------------------------------------------------- |
+| `nullable`   | `boolean`            | `false` | Field required status                  | `@Field.Prop(()=> String, { default: "untitled" }) title: string;`     |
+| `ref`        | `string`             | -       | Reference collection name              | `@Field.Prop(()=> ID, { ref: "drone" }) drone: string;`                |
+| `refPath`    | `string`             | -       | Dynamic reference collection name      | `@Field.Prop(()=> ID, { refPath: "rootType" }) root: string;`          |
+| `default`    | `any`                | -       | Default value when no value entered    | `@Field.Prop(()=> String, { default: "untitled" }) title: string;`     |
+| `type`       | `string`             | -       | Preset validation (email/password/url) | `@Field.Prop(()=> String, { type: "email" }) email: string;`           |
+| `immutable`  | `boolean`            | `false` | Cannot be changed after creation       | `@Field.Prop(()=> ID, { immutable: true }) creator: string;`           |
+| `min`        | `number`             | -       | Minimum value for Int/Float fields     | `@Field.Prop(()=> Int, { min: 0 }) progress: number;`                  |
+| `max`        | `number`             | -       | Maximum value for Int/Float fields     | `@Field.Prop(()=> Float, { min: 0, max: 1 }) ratio: number;`           |
+| `enum`       | `any[]`              | -       | Enum values restriction                | `@Field.Prop(()=> String, { enum: ["active","inactive"] }) status;`    |
+| `minlength`  | `number`             | -       | Minimum string length                  | `@Field.Prop(()=> String, { minlength: 2 }) name: string;`             |
+| `maxlength`  | `number`             | -       | Maximum string length                  | `@Field.Prop(()=> String, { maxlength: 30 }) title: string;`           |
+| `query`      | `object`             | -       | Query value for Summary fields         | `@Field.Prop(() => Int, { query: { status: { $ne: 'inactive' } })`     |
+| `accumulate` | `object`             | -       | Aggregation value for Insight fields   | `@Field.Prop(() => Int, { accumulate: { $sum: 1 } }) count: number;`   |
+| `example`    | `any`                | -       | Example value for API docs             | `@Field.Prop(()=> String, { example: "hello@akanjs.com" }) email;`     |
+| `of`         | `any`                | -       | Value type for Map fields              | `@Field.Prop(()=> Map, { of: Date }) readAts: Map<string, Dayjs>;`     |
+| `validate`   | `(value) => boolean` | -       | Custom validation function             | `@Field.Prop(()=> String, { validate: (v)=> v.includes("@") }) email;` |
+
+## Advanced Field Types
+
+```mermaid
+graph LR
+    Prop[Field.Prop] -->|General purpose| Standard
+    Hidden[Field.Hidden] -->|Backend only| Restricted
+    Secret[Field.Secret] -->|Security restricted| Sensitive
+    Resolve[Field.Resolve] -->|Computed| Virtual
 ```
 
-## Common Mistakes and Solutions
+1. **Field.Prop**  
+   General schema field declaration, visible in both backend and frontend
 
-### 1. Missing Field Type
+   ```typescript
+   @Field.Prop(() => String)
+   name: string;
+   ```
 
-```typescript
-// ❌ Wrong (missing type function)
-@Field.Prop(String)
-name: string;
+2. **Field.Hidden**  
+   Backend-only fields, restricted in frontend for security
 
-// ✅ Correct
-@Field.Prop(() => String)
-name: string;
-```
+   ```typescript
+   @Field.Hidden(() => String)
+   internalCode: string;
+   ```
 
-### 2. Incorrect Array Type
+3. **Field.Secret**  
+   Security-sensitive fields with query restrictions
 
-```typescript
-// ❌ Wrong (using Array<T> syntax)
-@Field.Prop(() => Array<String>)
-tags: string[];
+   ```typescript
+   @Field.Secret(() => String)
+   apiKey: string;
+   ```
 
-// ✅ Correct
-@Field.Prop(() => [String])
-tags: string[];
-```
+4. **Field.Resolve**  
+   Computed fields not stored in database
+   ```typescript
+   @Field.Resolve(() => Int)
+   get total() { return this.items.length }
+   ```
+
+## Advanced - Relation Patterns
 
-### 3. Missing Const Assertion
+### 1. Scalar Embedded Style
 
 ```typescript
-// ❌ Wrong (missing as const)
-extends via(ProductObject, ["id", "name"])
+@Model.Scalar("DronePhysicalState")
+export class DronePhysicalState {
+  @Field.Prop(() => [Float], { default: [0, 0, 0] })
+  rpy: [number, number, number];
+}
 
-// ✅ Correct
-extends via(ProductObject, ["id", "name"] as const)
+@Model.Object("DroneObject")
+export class DroneObject {
+  @Field.Prop(() => DronePhysicalState)
+  physicalState: DronePhysicalState;
+}
 ```
 
-### 4. Missing Nullable Type
+### 2. Reference ID Style
 
 ```typescript
-// ❌ Wrong (missing null in type)
-@Field.Prop(() => String, { nullable: true })
-description: string;
-
-// ✅ Correct
-@Field.Prop(() => String, { nullable: true })
-description: string | null;
+@Model.Input("MissionInput")
+export class MissionInput {
+  @Field.Prop(() => ID, { ref: "drone" })
+  drone: string;
+}
 ```
 
-### 5. Circular Dependencies
+### 3. Resolved Reference Style
 
 ```typescript
-// ❌ Wrong (circular dependency)
-import { Product } from "../product/product.constant";
-
-// ✅ Correct
-import { LightProduct } from "../product/product.constant";
+@Model.Object("DroneObject")
+export class DroneObject {
+  @Field.Prop(() => LightMission, { nullable: true })
+  mission: LightMission | null;
+}
 ```
 
-### 6. Missing Default for Arrays
+**Important**: Avoid circular dependencies by importing directly from constant files:
 
 ```typescript
-// ❌ Wrong (no default for array)
-@Field.Prop(() => [String])
-tags: string[];
+// Correct
+import { LightMission } from "../mission/mission.constant";
 
-// ✅ Correct
-@Field.Prop(() => [String], { default: [] })
-tags: string[];
+// Incorrect
+import { LightMission } from "../cnst_";
 ```
 
 ## 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()`
+1. **Consistent Naming**:
 
-2. **Keep models focused**
+   - Input: `DroneInput`
+   - Object: `DroneObject`
+   - Light: `LightDrone`
+   - Query: `droneQuery`
+   - Sort: `droneSort`
 
-   - Each model should represent a single entity
-   - Split complex models into related entities
+2. **Reference Handling**:
 
-3. **Use proper naming conventions**
+   - Use Light models for references
+   - Avoid circular dependencies
+   - Prefer direct imports over barrel files
 
-   - File: `camelCase.constant.ts`
-   - Classes: `PascalCase` with type suffix
-   - Fields: `camelCase`
-   - Enums: `PascalCase` with `Enum` suffix
+3. **Field Design**:
 
-4. **Add appropriate defaults**
+   - Use proper field types (Prop, Hidden, Secret, Resolve)
+   - Set appropriate defaults (especially for arrays)
+   - Add validation where needed
 
-   - Set reasonable defaults for required fields
-   - Use empty arrays for array fields: `{ default: [] }`
-   - Use function defaults for dates: `{ default: () => dayjs() }`
+4. **Performance Optimization**:
 
-5. **Implement proper validation**
+   - Use Light models for list queries
+   - Keep Insight/Summary models lean
+   - Use appropriate indexes for queries
 
-   - Add min/max for numbers
-   - Add minlength/maxlength for strings
-   - Use custom validation for complex rules
+5. **Documentation**:
+   - Comment complex fields
+   - Explain non-obvious relationships
+   - Document query/sort usage patterns
 
-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
+## Complete Example
 
 ```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>;
+import { ID, Int, String } from "@akanjs/base";
+import { Field, Model } from "@akanjs/constant";
 
 // Input Model
-@Model.Input("ProductInput")
-export class ProductInput {
-  @Field.Prop(() => String, {
-    minlength: 3,
-    maxlength: 100,
-  })
+@Model.Input("DroneInput")
+export class DroneInput {
+  @Field.Prop(() => String)
   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;
+@Model.Object("DroneObject")
+export class DroneObject extends BaseModel(DroneInput) {
+  @Field.Prop(() => String, { enum: ["active", "offline"], default: "offline" })
+  status: string;
 }
 
 // Light Model
-@Model.Light("LightProduct")
-export class LightProduct extends via(ProductObject, [
-  "id",
-  "name",
-  "price",
-  "imageUrl",
-  "status",
-  "category",
-] as const) {}
+@Model.Light("LightDrone")
+export class LightDrone extends Light(DroneObject, ["id", "name", "status"] as const) {
+  isConnected() {
+    return this.status === "active";
+  }
+}
 
 // Full Model
-@Model.Full("Product")
-export class Product extends via(ProductObject, LightProduct) {}
+@Model.Full("Drone")
+export class Drone extends Full(DroneObject, LightDrone) {
+  isAvailable() {
+    return this.isConnected() && this.battery > 20;
+  }
+}
 
 // Insight Model
-@Model.Insight("ProductInsight")
-export class ProductInsight {
-  @Field.Prop(() => Int, {
-    default: 0,
-    accumulate: { $sum: 1 },
-  })
+@Model.Insight("DroneInsight")
+export class DroneInsight {
+  @Field.Prop(() => Int, { 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;
+@Model.Summary("DroneSummary")
+export class DroneSummary {
+  @Field.Prop(() => Int, { query: { status: "active" } })
+  activeDrones: 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;
-  }
+// Query Model
+export const droneQuery = {
+  byStatus: (status: string) => ({ status }),
+};
 
-  @Filter.Mongo()
-  inStock() {
-    return { stock: { $gt: 0 } };
-  }
-
-  @Filter.Meili()
-  searchText(
-    @Filter.Arg("query", () => String)
-    query: string
-  ) {
-    return { q: query };
-  }
-}
+// Sort Model
+export const droneSort = {
+  byName: { name: 1 },
+};
 ```
 
 ## 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
+1. [ ] Implement all required model types (Input, Object, Light, Full, Insight, Summary, Query, Sort)
+2. [ ] Define field options properly (nullable, ref, default, etc.)
+3. [ ] Add necessary validation rules
+4. [ ] Implement relation patterns where needed
+5. [ ] Use proper field types (Prop, Hidden, Secret, Resolve)
+6. [ ] Add convenience functions to Light/Full models
+7. [ ] Prevent circular dependencies in references
+8. [ ] Add comprehensive JSDoc comments
+9. [ ] Verify all examples in usage contexts
+10. [ ] Test query/sort functionality