@nxtoai/gati/README.md

A flexible Aerospike service for NestJS applications

# Gati - Aerospike Service for NestJS

A flexible and powerful Aerospike service for NestJS applications, providing a simple interface for Aerospike operations.

## Installation

```bash
npm install @nxtoai/gati
```

## Configuration

Import the `GatiModule` in your application module:

```typescript
import { Module } from '@nestjs/common';
import { GatiModule } from '@nxtoai/gati';

@Module({
  imports: [
    GatiModule.forRoot({
      hosts: ['localhost'],
      port: 3000,
      namespace: 'test'
    }),
  ],
})
export class AppModule {}
```

## Usage

Inject the `GatiService` into your service:

```typescript
import { Injectable } from '@nestjs/common';
import { GatiService } from '@nxtoai/gati';

@Injectable()
export class UserService {
  constructor(private readonly gati: GatiService) {}

  // Example: Storing user data in multiple bins
  async createUser(userId: string, userData: any) {
    await this.gati.put('users', userId, {
      id_bin: {
        id: userId,
        created_at: new Date().toISOString()
      },
      email_bin: {
        email: userData.email,
        email_verified: false
      },
      data_bin: {
        ...userData,
        updated_at: new Date().toISOString()
      }
    }, { ttl: 86400 });
  }

  // Example: Retrieving data from multiple bins
  async getUserData(userId: string) {
    const userData = await this.gati.get('users', userId);
    if (!userData) return null;

    return {
      id: userData.id_bin?.id,
      created_at: userData.id_bin?.created_at,
      email: userData.email_bin?.email,
      email_verified: userData.email_bin?.email_verified,
      ...userData.data_bin
    };
  }

  // Example: Updating specific bins
  async updateUserEmail(userId: string, email: string) {
    const currentData = await this.gati.get('users', userId);
    if (!currentData) return;

    await this.gati.put('users', userId, {
      ...currentData,
      email_bin: {
        email,
        email_verified: false,
        updated_at: new Date().toISOString()
      }
    });
  }

  // Example: Checking if specific bins exist
  async checkUserBins(userId: string) {
    const userData = await this.gati.get('users', userId);
    if (!userData) return { hasId: false, hasEmail: false, hasData: false };

    return {
      hasId: !!userData.id_bin,
      hasEmail: !!userData.email_bin,
      hasData: !!userData.data_bin
    };
  }
}
```

## API Reference

### put(set: string, key: string, bins: RecordBins, options?: { ttl?: number }): Promise<void>

Stores data in Aerospike.

```typescript
// Example: Storing user data in multiple bins
const userId = 'user:123';
const userData = {
  name: 'John Doe',
  age: 30,
  address: {
    street: '123 Main St',
    city: 'New York',
    country: 'USA'
  },
  preferences: {
    theme: 'dark',
    notifications: true
  }
};

await gati.put('users', userId, {
  id_bin: {
    id: userId,
    created_at: new Date().toISOString()
  },
  email_bin: {
    email: 'john@example.com',
    email_verified: false
  },
  data_bin: userData
}, { ttl: 86400 });
```

### get(set: string, key: string): Promise<RecordBins | null>

Retrieves data from Aerospike.

```typescript
// Example: Getting data from multiple bins
const userId = 'user:123';
const userData = await gati.get('users', userId);

if (userData) {
  console.log('User ID:', userData.id_bin?.id);
  console.log('Created at:', userData.id_bin?.created_at);
  console.log('Email:', userData.email_bin?.email);
  console.log('Email verified:', userData.email_bin?.email_verified);
  console.log('User data:', userData.data_bin);
}
```

### exists(set: string, key: string): Promise<boolean>

Checks if a record exists.

```typescript
// Example: Checking if user exists
const userId = 'user:123';
const exists = await gati.exists('users', userId);
console.log('User exists:', exists);
```

### remove(set: string, key: string): Promise<void>

Removes a record.

```typescript
// Example: Removing user data
const userId = 'user:123';
await gati.remove('users', userId);
```

### scan(set: string, options?: ScanOptions): Promise<RecordBins[]>

Scans all records in the set.

```typescript
// Example: Scanning all users
const users = await gati.scan('users');
console.log(`Found ${users.length} users`);

// Example: Scanning with options
const limitedUsers = await gati.scan('users', { limit: 10 });
console.log(`Retrieved ${limitedUsers.length} users`);
```

### close(): Promise<void>

Closes the Aerospike connection.

```typescript
// Example: Closing the connection
await gati.close();
```

## Error Handling

The service includes comprehensive error handling and logging:

```typescript
try {
  await gati.put('users', 'key', { value: 'data' });
} catch (error) {
  if (error instanceof GatiValidationError) {
    console.error('Validation error:', error.message);
  } else {
    console.error('Operation error:', error.message);
  }
}
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.