Package Exports

@kenniy/godeye-data-contracts
@kenniy/godeye-data-contracts/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@kenniy/godeye-data-contracts) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@kenniy/godeye-data-contracts

Enterprise Repository Architecture with Intelligent Search

Zero runtime overhead. Maximum code reuse. Enterprise-ready performance.

Eliminates 82.5% of repository repetition across TypeORM and Mongoose services with:

WhereConfig Pattern: Clean separation of backend control and frontend requests
Intelligent Search: Multi-algorithm fuzzy search with typo tolerance
Auto-Response Detection: ResponseFactory automatically formats pagination/array/single entity
Graceful Error Handling: Relations fail silently with detailed metadata
Performance Monitoring: Built-in query timing and metrics

🚀 Quick Start

npm install @kenniy/godeye-data-contracts
# or
pnpm add @kenniy/godeye-data-contracts

import { 
  BaseTypeORMRepository, 
  FindManyDto,
  IWhereConfig,
  SearchStrategy,
  ResponseFactory 
} from '@kenniy/godeye-data-contracts';

⚡ Core Pattern - WhereConfig + QueryDto

The cleanest way to handle complex search with backend control:

@Controller('users')
export class UsersController {
  @Get()
  async getUsers(@Query() queryDto: FindManyDto) {
    // Backend defines search intelligence and conditions
    const whereConfig: IWhereConfig = {
      conditions: { 
        status: 'active', 
        isDeleted: false 
      },
      searchConfig: [
        {
          fields: ["firstName", "lastName"],
          defaultStrategy: SearchStrategy.FUZZY, // Handles typos
          priority: 10,
          weight: 1.0
        }
      ]
    };
    
    // Clean separation: backend config + frontend request
    const result = await this.userRepository.findWithPagination(whereConfig, queryDto);
    
    // Auto-detects format (pagination/array/single)
    return ResponseFactory.success(result);
  }
}

Frontend sends simple request:

GET /users?search=kenniy&include=profile,business&page=1&limit=20

Gets back sophisticated response:

{
  "success": true,
  "data": {
    "items": [
      {
        "firstName": "Kenny",  // Fuzzy matched "kenniy"
        "profile": { ... },
        "business": { ... }
      }
    ],
    "total": 147,
    "page": 1,
    "limit": 20
  },
  "metadata": {
    "queryTime": "23ms",
    "searchAlgorithms": ["fuzzy"],
    "relationsLoaded": ["profile", "business"]
  }
}

🔍 Intelligent Search Features

Search Strategies

Strategy	Example	Use Case
`EXACT`	`john` = `john`	IDs, emails
`FUZZY`	`kenniy` ≈ `Kenny`	Names (typo tolerance)
`CONTAINS`	`java` in `javascript`	Skills, descriptions
`STARTS_WITH`	`john` in `john123`	Prefix matching

Field Groups

{
  // Multiple fields, same algorithm
  fields: ["firstName", "lastName", "displayName"],
  defaultStrategy: SearchStrategy.FUZZY,
  priority: 10,
  weight: 1.0
}

Array Fields

{
  // Database array field
  field: "skills",
  isArray: true,
  defaultStrategy: SearchStrategy.CONTAINS,
  priority: 7,
  weight: 0.7
}

📚 Repository Methods

1. Pagination Search

const result = await userRepository.findWithPagination(whereConfig, queryDto);
// Returns: { items: [...], total: 147, page: 1, metadata: {...} }

2. Single Entity

const user = await userRepository.findById(id, whereConfig, queryDto);
// Returns: { data: {...}, metadata: {...} }

3. Array Search

const users = await userRepository.find(whereConfig, queryDto);  
// Returns: { items: [...], metadata: {...} }

🏗️ Entity Setup

TypeORM

import { BaseTypeORMRepository } from '@kenniy/godeye-data-contracts';

@Injectable()
export class UserRepository extends BaseTypeORMRepository<User> {
  // Inherits all intelligent functionality
}

Mongoose

import { BaseMongooseRepository } from '@kenniy/godeye-data-contracts';

@Injectable()
export class UserRepository extends BaseMongooseRepository<User> {
  // Works with MongoDB too!
}

📋 Complete Examples

Check out these comprehensive examples:

Complete Max Usage - Full flow with all features
Basic ICriteria Usage - Simple queries
Deep Relations Usage - Nested population
DTO Usage - Frontend integration
Response Usage - ResponseFactory patterns

🚦 Response Factory Auto-Detection

The ResponseFactory automatically detects your data format:

// Pagination data → Pagination response
ResponseFactory.success({
  items: [...],
  total: 100,
  page: 1,
  limit: 20
});

// Single entity → Entity response  
ResponseFactory.success({
  data: { id: "123", name: "John" },
  metadata: { queryTime: "12ms" }
});

// Array data → Array response
ResponseFactory.success({
  items: [...],
  metadata: { count: 5 }
});

🎯 Key Benefits

✅ Frontend Simplicity: Just search, include, page, limit
✅ Backend Control: Full algorithm and condition control
✅ Auto-Population: Deep relations with graceful error handling
✅ Performance: Optimized queries with monitoring
✅ Type Safety: Full TypeScript support
✅ Universal: Works with TypeORM and Mongoose
✅ Enterprise Ready: Error handling, logging, metrics

📊 Performance

Query Optimization: ~10-20ms for complex searches
Parallel Execution: Count and data queries run in parallel
Relation Validation: Auto-discovery prevents invalid JOINs
Memory Efficient: Optimized query builders
Monitoring: Built-in performance tracking

🛠️ Advanced Configuration

Dynamic Conditions

const whereConfig: IWhereConfig = {
  conditions: { status: 'active' },
  dynamicConditions: (criteria) => {
    // Add conditions based on search context
    if (criteria.search?.term) {
      return { profileComplete: true };
    }
    return {};
  }
};

Custom Search Fields

searchConfig: [
  {
    fields: ["firstName", "lastName"],
    defaultStrategy: SearchStrategy.FUZZY,
    priority: 10,
    weight: 1.0
  },
  {
    field: "skills",
    isArray: true,
    defaultStrategy: SearchStrategy.CONTAINS, 
    priority: 7,
    weight: 0.7
  }
]

📝 Migration from Old Pattern

Old Way:

const criteria = queryDto.toICriteria();
return repository.findWithPagination(criteria);

New Way:

const whereConfig = { conditions: { status: 'active' } };
return repository.findWithPagination(whereConfig, queryDto);

🧪 Testing

The package includes comprehensive tests demonstrating all functionality:

npm test

📄 License

MIT © kenniy

Ready to use in production! This architecture powers high-performance microservices with intelligent search capabilities.