@nestgate/core/README.md

Core utilities for NestJS - Mix classes, connect entities, and compose decorators with ease

# @nestgate/core

Core utilities and composable decorators for NestJS applications.

## 📦 Installation

```bash
npm install @nestgate/core
# or
pnpm add @nestgate/core
# or
yarn add @nestgate/core
```

## 🎯 Features

- **Mix** - Combine multiple classes with proper TypeScript types and metadata
- **ConnectOne** - Connect single nested entity with validation
- **ConnectMany** - Connect array of nested entities with validation

## 📚 API Reference

### Mix

Combine multiple classes into one, inheriting all properties and decorators.

```typescript
import { Mix } from '@nestgate/core';

class Timestamped {
  @DateTime()
  createdAt: Date;

  @DateTime()
  updatedAt: Date;
}

class SoftDelete {
  @DateTime({ required: false })
  deletedAt?: Date;

  @Boolean({ default: false })
  isDeleted: boolean;
}

// Combine multiple mixins
class User extends Mix(Timestamped, SoftDelete) {
  @UUID()
  id: string;

  @String()
  name: string;
}
```

**Features:**

- ✅ Full TypeScript type inference
- ✅ Swagger metadata preserved
- ✅ Validation decorators work correctly
- ✅ Multiple mixins supported

### ConnectOne

Connect a single nested entity with automatic validation and transformation.

```typescript
import { ConnectOne } from '@nestgate/core';

class Address {
  @String()
  street: string;

  @String()
  city: string;

  @String()
  country: string;
}

class User {
  @UUID()
  id: string;

  @String()
  name: string;

  // Single nested object
  @ConnectOne(Address, {
    description: 'User address',
    required: false,
  })
  address?: Address;
}
```

**Options:**

```typescript
interface ConnectOptions {
  required?: boolean; // Default: true
  description?: string; // Swagger description
  example?: any; // Swagger example
  deprecated?: boolean; // Mark as deprecated
  exclude?: boolean; // Exclude from API response
}
```

**Features:**

- ✅ Automatic nested validation with `@ValidateNested()`
- ✅ JSON to class transformation with `@Type()`
- ✅ Swagger schema generation
- ✅ Optional/Required support

### ConnectMany

Connect an array of nested entities.

```typescript
import { ConnectMany } from '@nestgate/core';

class Post {
  @UUID()
  id: string;

  @String()
  title: string;

  @String()
  content: string;
}

class User {
  @UUID()
  id: string;

  @String()
  name: string;

  // Array of nested objects
  @ConnectMany(Post, {
    description: 'User posts',
    required: false,
  })
  posts?: Post[];
}
```

**Features:**

- ✅ Validates each array item
- ✅ Transforms each item to class instance
- ✅ Swagger shows array type correctly
- ✅ Works with pagination

## 💡 Examples

### Complete CRUD Entity

```typescript
import { Mix, ConnectOne, ConnectMany } from '@nestgate/core';

// Base mixins
class Timestamped {
  @DateTime()
  createdAt: Date;

  @DateTime()
  updatedAt: Date;
}

class Authorable {
  @UUID()
  authorId: string;
}

// Related entities
class Tag {
  @String()
  name: string;
}

class Comment {
  @String()
  text: string;

  @DateTime()
  createdAt: Date;
}

// Main entity with everything
class BlogPost extends Mix(Timestamped, Authorable) {
  @UUID()
  id: string;

  @String({ minLength: 3, maxLength: 200 })
  title: string;

  @String()
  content: string;

  @ConnectMany(Tag)
  tags: Tag[];

  @ConnectMany(Comment, { required: false })
  comments?: Comment[];
}
```

### Multi-level Nesting

```typescript
class Author {
  @UUID()
  id: string;

  @String()
  name: string;
}

class Comment {
  @String()
  text: string;

  @ConnectOne(Author)
  author: Author;
}

class Post {
  @String()
  title: string;

  @ConnectOne(Author)
  author: Author;

  @ConnectMany(Comment)
  comments: Comment[];
}
```

### Excluding from Response

```typescript
class User {
  @UUID()
  id: string;

  @String()
  email: string;

  // This won't appear in API response
  @ConnectOne(UserSettings, { exclude: true })
  internalSettings: UserSettings;
}
```

## 🔗 Related Packages

- [@nestgate/rest](../rest) - REST API decorators
- [@nestgate/entity](../entity) - Entity validation decorators
- [@nestgate/setup](../setup) - Quick application setup

## 📝 License

MIT © [NestGate](https://nestgate.org)

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md).

## 💬 Support

- [Documentation](https://nestgate.org)
- [GitHub Issues](https://github.com/nestgate/nestgate/issues)
- [Discord](https://discord.gg/nestgate)