@akanjs/cli 0.0.142 → 0.0.144

package/src/guidelines/scalarConstant/scalarConstant.instruction.md

@@ -0,0 +1,489 @@
+# Scalar Constant Implementation Guide for Akan.js
+
+## Purpose of Scalar Constants
+
+Scalar constants in Akan.js serve as the foundation for complex data modeling by:
+
+- Defining reusable value objects that can be embedded in other models
+- Representing complex data types without creating database collections
+- Providing standardized field definitions across the application
+- Enabling type-safe data modeling and validation
+- Serving as building blocks for larger domain models
+
+## File Structure and Location
+
+### Location Convention
+
+```
+{app,lib}/
+└── */lib/__scalar/
+    └── <scalarName>/               // camelCase directory
+        └── <scalarName>.constant.ts  // scalar definition file
+```
+
+### Naming Standards
+
+- **Directory**: `camelCase` (e.g., `geoLocation`)
+- **File**: `<scalarName>.constant.ts` (matches directory name)
+- **Class**: `PascalCase` matching directory name (e.g., `GeoLocation`)
+- **Model Reference**: Matches class name in `@Model.Scalar()` decorator
+- **Enum Values**: `camelCase` (e.g., `active`, `pendingApproval`)
+
+### File Structure
+
+```typescript
+// 1. Core imports
+import { Float, Int, String, Boolean, Date, type Dayjs, dayjs, enumOf } from "@akanjs/base";
+import { Field, Model } from "@akanjs/constant";
+
+// 2. Optional enum definitions (camelCase values)
+export const Status = enumOf(["active", "inactive"] as const);
+export type Status = enumOf<typeof Status>;
+
+// 3. Scalar model class (SINGLE CLASS PER FILE)
+@Model.Scalar("ScalarName") // Must match class name
+export class ScalarName {
+  // Field definitions
+  @Field.Prop(() => FieldType, { ...options })
+  fieldName: FieldType;
+}
+```
+
+## Required Imports
+
+### Essential Framework Imports
+
+```typescript
+import { Field, Model } from "@akanjs/constant";
+```
+
+### Common Base Types
+
+```typescript
+import { ID, Int, Float, String, Boolean, Date, type Dayjs, dayjs, enumOf, JSON, Map } from "@akanjs/base";
+```
+
+### Cross-Scalar References
+
+```typescript
+import { OtherScalar } from "../other-scalar/other-scalar.constant";
+```
+
+## Model Definition
+
+### Basic Structure
+
+```typescript
+@Model.Scalar("ScalarName") // String must match class name
+export class ScalarName {
+  // Field definitions go here
+}
+```
+
+### Key Rules
+
+- **One scalar model per file** - Create separate files for different scalars
+- **Class name matches directory name** in PascalCase (e.g., `PaymentInfo` for `payment-info`)
+- **Model names should be domain-specific** and descriptive
+- **No ID/timestamp fields** - Scalars are value objects, not entities
+- **`@Model.Scalar` decorator parameter must match class name** - This is critical for proper metadata registration
+
+## Field Definitions
+
+### Basic Field Types
+
+```typescript
+@Field.Prop(() => String)
+name: string;
+
+@Field.Prop(() => Int)
+quantity: number;
+
+@Field.Prop(() => Float)
+percentage: number;
+
+@Field.Prop(() => Boolean)
+isActive: boolean;
+
+@Field.Prop(() => Date)
+timestamp: Dayjs;  // Always use Dayjs for dates
+```
+
+### Field Options Reference
+
+| Option      | Type     | Description                          | Example                      |
+| ----------- | -------- | ------------------------------------ | ---------------------------- |
+| `default`   | Any      | Default field value                  | `{ default: 0 }`             |
+| `nullable`  | Boolean  | Allows null values                   | `{ nullable: true }`         |
+| `enum`      | Enum     | Restricts to enum values             | `{ enum: Status }`           |
+| `min`       | Number   | Minimum numeric value                | `{ min: 0 }`                 |
+| `max`       | Number   | Maximum numeric value                | `{ max: 100 }`               |
+| `minlength` | Number   | Minimum string length                | `{ minlength: 3 }`           |
+| `maxlength` | Number   | Maximum string length                | `{ maxlength: 255 }`         |
+| `example`   | Any      | Example value for documentation      | `{ example: [0,0] }`         |
+| `validate`  | Function | Custom validation function           | `{ validate: (v) => v > 0 }` |
+| `immutable` | Boolean  | Prevents modification after creation | `{ immutable: true }`        |
+| `select`    | Boolean  | Includes in query results by default | `{ select: false }`          |
+| `text`      | String   | Enables text search capabilities     | `{ text: "search" }`         |
+
+### Special Field Types
+
+```typescript
+// Hidden field (not exposed in GraphQL)
+@Field.Hidden(() => String)
+internalCode: string;
+
+// Secret field (not selected by default)
+@Field.Secret(() => String)
+apiKey: string;
+
+// Resolve field (computed at runtime)
+@Field.Resolve(() => Int)
+get total(): number {
+  return this.items.length;
+}
+```
+
+## Array Fields
+
+### Simple Arrays
+
+```typescript
+// String array
+@Field.Prop(() => [String])
+tags: string[];
+
+// Number array with default
+@Field.Prop(() => [Int], { default: [1, 2, 3] })
+values: number[];
+```
+
+### Nested Arrays
+
+```typescript
+// 2D number array
+@Field.Prop(() => [[Int]])
+matrix: number[][];
+
+// 3D coordinate array
+@Field.Prop(() => [[[Float]]])
+coordinates: number[][][];
+```
+
+### Array of Scalars
+
+```typescript
+@Field.Prop(() => [OtherScalar])
+items: OtherScalar[];
+```
+
+## Map Fields
+
+```typescript
+@Field.Prop(() => Map, {
+  of: String,  // Must specify value type
+  default: new Map()
+})
+metadata: Map<string, string>;
+```
+
+## Enum Implementation (camelCase Values)
+
+```typescript
+// Define enum with camelCase values (export REQUIRED)
+export const Status = enumOf(["active", "inactive", "pendingApproval"] as const);
+export type Status = enumOf<typeof Status>;  // Type export
+
+// Use in field
+@Field.Prop(() => String, {
+  enum: Status,
+  default: "active"
+})
+status: Status;
+```
+
+## Static Methods
+
+Scalar classes can include static methods for common operations on the scalar type:
+
+```typescript
+@Model.Scalar("Coordinate")
+export class Coordinate {
+  @Field.Prop(() => [Float], { default: [0, 0] })
+  coordinates: number[];
+
+  // Static utility methods
+  static getDistanceKm(loc1: Coordinate, loc2: Coordinate) {
+    const [lon1, lat1] = loc1.coordinates;
+    const [lon2, lat2] = loc2.coordinates;
+    // Distance calculation logic
+    return distance;
+  }
+}
+```
+
+## Validation Rules and Checklist
+
+### File-Level Validation
+
+- [ ] Location: `__scalar/<camelCase>/<camelCase>.constant.ts`
+- [ ] Single `@Model.Scalar` class per file
+- [ ] Class name matches directory name (PascalCase)
+- [ ] All required imports present
+- [ ] The string passed to `@Model.Scalar()` must match the class name exactly
+
+### Field-Level Validation
+
+- [ ] All fields have `@Field.Prop` decorator (or `@Field.Hidden`, `@Field.Secret`, `@Field.Resolve`)
+- [ ] Type references use arrow functions: `() => Type`
+- [ ] Array types use bracket notation: `[Type]`
+- [ ] Nullable fields use TypeScript union: `Type | null`
+- [ ] Default values match field types
+- [ ] Enums are properly defined with camelCase values and exported
+- [ ] Custom validation functions are pure and side-effect free
+- [ ] Dayjs type is used for date fields
+
+### Best Practices
+
+- **Focused models**: Each scalar should represent a single concept
+- **Descriptive names**: Use clear, domain-relevant terminology
+- **Enum Values**: Always use camelCase (`active`, not `ACTIVE`)
+- **Reusability**: Create separate scalars for commonly used structures
+- **Documentation**: Add comments for complex fields
+- **Validation**: Use min/max for numbers, minlength/maxlength for text
+- **Immutability**: Mark fields as `immutable` where appropriate
+- **Default values**: Provide sensible defaults for most fields
+
+## Common Mistakes and Fixes
+
+### Incorrect Enum Case
+
+```typescript
+// ❌ Wrong (uppercase values)
+export const Status = enumOf(["ACTIVE", "INACTIVE"] as const);
+
+// ✅ Correct (camelCase values)
+export const Status = enumOf(["active", "inactive"] as const);
+```
+
+### Incorrect Array Syntax
+
+```typescript
+// ❌ Wrong
+@Field.Prop(() => Array<Int>)
+values: number[];
+
+// ✅ Correct
+@Field.Prop(() => [Int])
+values: number[];
+```
+
+### Missing Nullable Type Declaration
+
+```typescript
+// ❌ Wrong (type mismatch)
+@Field.Prop(() => String, { nullable: true })
+description: string;
+
+// ✅ Correct
+@Field.Prop(() => String, { nullable: true })
+description: string | null;
+```
+
+### Improper Enum Implementation
+
+```typescript
+// ❌ Wrong (missing export/type)
+const Status = enumOf(["active"] as const);
+
+// ✅ Correct
+export const Status = enumOf(["active"] as const);
+export type Status = enumOf<typeof Status>;
+```
+
+### Multiple Models in One File
+
+```typescript
+// ❌ Wrong (violates single-responsibility)
+@Model.Scalar("Address") class Address { ... }
+@Model.Scalar("User") class User { ... }
+
+// ✅ Correct (separate files)
+// address.constant.ts
+export class Address { ... }
+
+// user.constant.ts
+import { Address } from "../address/address.constant";
+export class User { ... }
+```
+
+### Incorrect Date Handling
+
+```typescript
+// ❌ Wrong (uses native Date)
+@Field.Prop(() => Date)
+createdAt: Date;
+
+// ✅ Correct (uses Dayjs)
+import { type Dayjs } from "@akanjs/base";
+
+@Field.Prop(() => Date)
+createdAt: Dayjs;
+```
+
+### Missing Model.Scalar Parameter
+
+```typescript
+// ❌ Wrong (missing or mismatched parameter)
+@Model.Scalar()
+export class GeoLocation { ... }
+
+// ✅ Correct
+@Model.Scalar("GeoLocation")
+export class GeoLocation { ... }
+```
+
+## Full Examples
+
+### Basic Scalar Example
+
+```typescript
+// libs/payment/lib/__scalar/amount/amount.constant.ts
+import { Float } from "@akanjs/base";
+import { Field, Model } from "@akanjs/constant";
+
+@Model.Scalar("Amount")
+export class Amount {
+  @Field.Prop(() => Float, { min: 0, default: 0 })
+  value: number;
+
+  @Field.Prop(() => String, { default: "USD" })
+  currency: string;
+}
+```
+
+### Complex Scalar Example (with camelCase enums)
+
+```typescript
+// apps/maps/lib/__scalar/geoLocation/geoLocation.constant.ts
+import { Float, type Dayjs, dayjs, enumOf } from "@akanjs/base";
+import { Field, Model } from "@akanjs/constant";
+
+// CORRECT: camelCase enum values
+export const AccuracyLevel = enumOf(["low", "medium", "high"] as const);
+export type AccuracyLevel = enumOf<typeof AccuracyLevel>;
+
+@Model.Scalar("GeoLocation")
+export class GeoLocation {
+  @Field.Prop(() => Float, {
+    min: -90,
+    max: 90,
+    example: 37.7749,
+  })
+  latitude: number;
+
+  @Field.Prop(() => Float, {
+    min: -180,
+    max: 180,
+    example: -122.4194,
+  })
+  longitude: number;
+
+  @Field.Prop(() => Float, {
+    nullable: true,
+    min: 0,
+    example: 12.5,
+  })
+  elevation: number | null;
+
+  @Field.Prop(() => String, {
+    enum: AccuracyLevel,
+    default: "medium",
+  })
+  accuracy: AccuracyLevel;
+
+  @Field.Prop(() => Date, {
+    default: () => dayjs(),
+    immutable: true,
+  })
+  measuredAt: Dayjs;
+}
+```
+
+### Scalar with Nested Objects
+
+```typescript
+// apps/ecommerce/lib/__scalar/product-spec/product-spec.constant.ts
+import { Int, Float } from "@akanjs/base";
+import { Field, Model } from "@akanjs/constant";
+import { Dimension } from "../dimension/dimension.constant";
+
+@Model.Scalar("ProductSpec")
+export class ProductSpec {
+  @Field.Prop(() => String)
+  sku: string;
+
+  @Field.Prop(() => [String], {
+    default: [],
+    example: ["red", "blue"],
+  })
+  colors: string[];
+
+  @Field.Prop(() => Dimension)
+  size: Dimension;
+
+  @Field.Prop(() => Float, { min: 0 })
+  weight: number;
+
+  @Field.Prop(() => Int, {
+    min: 0,
+    default: 0,
+  })
+  stock: number;
+}
+```
+
+### Scalar with Static Methods
+
+```typescript
+// libs/util/lib/__scalar/coordinate/coordinate.constant.ts
+import { Float } from "@akanjs/base";
+import { Field, Model } from "@akanjs/constant";
+
+@Model.Scalar("Coordinate")
+export class Coordinate {
+  @Field.Prop(() => [Float], { default: [0, 0], example: [127.114367, 37.497114] })
+  coordinates: number[];
+
+  @Field.Prop(() => Float, { default: 0 })
+  altitude: number;
+
+  static getDistanceKm(loc1: Coordinate, loc2: Coordinate) {
+    const [lon1, lat1] = loc1.coordinates;
+    const [lon2, lat2] = loc2.coordinates;
+    // Distance calculation logic...
+    return distance;
+  }
+
+  static moveMeters(loc: Coordinate, x: number, y: number): Coordinate {
+    // Calculate new position...
+    return { ...loc, coordinates: [newLon, newLat] };
+  }
+}
+```
+
+## Summary Checklist
+
+1. **Location**: `__scalar/<camelCase>/<camelCase>.constant.ts`
+2. **Structure**: Single `@Model.Scalar` class per file
+3. **Naming**: Class name = PascalCase directory name
+4. **Decorator**: `@Model.Scalar("ClassName")` with exact class name match
+5. **Enum Values**: Always camelCase (`active`, not `ACTIVE`)
+6. **Fields**: Use `@Field.Prop` with arrow function types
+7. **Arrays**: Wrap in `[]` (e.g., `[Int]`)
+8. **Enums**: Export with `enumOf` and derived type
+9. **Dates**: Always use `Dayjs` type with `Date` decorator
+10. **Nullability**: Use `| null` with `{ nullable: true }`
+11. **Validation**: Implement field-level constraints
+
+Following these patterns ensures type-safe, maintainable scalar definitions that integrate seamlessly with the Akan.js framework's data modeling layer.