Field Decorator Usage Guide

Field decorators are the foundation for data modeling in Akan.js, enabling type-safe properties, GraphQL schema generation, MongoDB validation, and search optimization.
Decorator Types
Akan.js provides specialized decorators for different data handling scenarios:
Field.Prop

Standard visible property stored in DB and exposed in API

@Field.Prop(() => String)
Field.Hidden

Internal data stored in DB but not exposed in API

@Field.Hidden(() => String)
Field.Secret

Sensitive data with restricted access

@Field.Secret(() => String)
Field.Resolve

Computed property calculated at runtime

@Field.Resolve(() => Int)
Basic Syntax
Field decorators follow a consistent pattern with type specification and configuration options:
// Standard property definition
@Field.Prop(() => Type, { ...options })
propertyName: TypeScriptType;
// Example with validation
@Field.Prop(() => Int, { min: 0, max: 100 })
score: number;
        
Property Types
Standard Properties
@Field.Prop(() => String, { minlength: 3, maxlength: 50 })
username: string;
@Field.Prop(() => Boolean, { default: false })
isActive: boolean;
        
Computed Properties
@Field.Resolve(() => String)
get fullName(): string {
  return `${this.firstName} ${this.lastName}`;
}
        
Field Options
Fine-tune field behavior with these configuration options:
default:any:null

Default value for the field

{ default: "active" }
nullable:boolean:false

Allows null values

{ nullable: true }
enum:Enum:-

Restricts to specific enum values

{ enum: StatusEnum }
immutable:boolean:false

Prevents modification after creation

{ immutable: true }
min/max:number:-

Value range constraints

{ min: 0, max: 100 }
ref:string:-

Reference to another model

{ ref: "User" }
text:"search" | "filter":-

Search indexing behavior

{ text: "search" }
Advanced Patterns
Enums
export const Status = enumOf(["active", "inactive"] as const);
export type Status = enumOf<typeof Status>;
@Field.Prop(() => String, { enum: Status, default: "active" })
status: Status;
        
Relationships
// Single reference
@Field.Prop(() => LightUser, { ref: "User" })
owner: LightUser;
// Dynamic reference
@Field.Prop(() => LightModel, { refPath: "modelType" })
model: LightModel;
        
Validation
// Built-in validation
@Field.Prop(() => String, { minlength: 8, maxlength: 100 })
password: string;
// Custom validation
@Field.Prop(() => String, {
  validate: (value) => /^[A-Z][a-z]+$/.test(value)
})
properName: string;
        
Best Practices
Ensure type safety and consistency with these guidelines:
  • Match TypeScript types with GraphQL types
  • Use Field.Secret for sensitive data
  • Provide defaults for required fields
  • Use bracket notation for arrays: () => [String]
  • Always use Dayjs for date fields
Troubleshooting
Field not appearing in GraphQL

Check if using Field.Hidden instead of Field.Prop

Default value not applied

Ensure default value type matches field type

Search not working

Add { text: 'search' } option to searchable fields

Summary Checklist
Released under the MIT License
Official Akan.js Consulting onAkansoft
Copyright © 2025 Akan.js. All rights reserved.
System managed bybassman