npm package: @mirshadkvr/fake-store-api
Description: A comprehensive fake store API package for generating mock e-commerce data including products, users, orders, and more.
Author: mirshadkvr
Latest version: 1.0.0

# Fake Store API

A comprehensive fake store API package for generating mock e-commerce data including products, users, orders, carts, and more. Perfect for testing, prototyping, and development of e-commerce applications.

## Features

- 🛍️ **Products**: Generate fake products with categories, ratings, prices, and more
- 👥 **Users**: Create mock users with realistic addresses and contact information
- 🛒 **Carts**: Generate shopping carts with multiple products
- 📦 **Orders**: Create orders with shipping information and payment methods
- 🏷️ **Categories**: Pre-built product categories
- 🎲 **Deterministic**: Use seeds for reproducible data generation
- 📝 **TypeScript**: Full TypeScript support with type definitions
- 🧪 **Well-tested**: Comprehensive test coverage

## Installation

```bash
npm install @mirshadkvr/fake-store-api
```

## Quick Start

```typescript
import { FakeStoreAPI } from '@mirshadkvr/fake-store-api';

// Create an instance
const fakeStore = new FakeStoreAPI();

// Generate some products
const products = fakeStore.getAllProducts({ limit: 10 });
console.log(products);

// Get a specific product
const product = fakeStore.getProduct(1);
console.log(product);

// Generate users
const users = fakeStore.getAllUsers({ limit: 5 });
console.log(users);
```

## API Reference

### Constructor

```typescript
const api = new FakeStoreAPI(options?: FakeStoreOptions);
```

#### Options

- `seed?: number` - Seed for deterministic data generation
- `locale?: string` - Locale for data generation (reserved for future use)

### Products

#### `getAllProducts(options?: QueryOptions): Product[]`

Get all products with optional filtering and sorting.

```typescript
const products = api.getAllProducts({
  limit: 20,        // Limit number of results
  sort: 'asc'       // Sort by ID ('asc' or 'desc')
});
```

#### `getProduct(id: number): Product | null`

Get a specific product by ID.

```typescript
const product = api.getProduct(1);
```

#### `getProductsByCategory(category: string, options?: QueryOptions): Product[]`

Get products filtered by category.

```typescript
const electronics = api.getProductsByCategory('Electronics', { limit: 10 });
```

#### `generateProduct(id?: number): Product`

Generate a single product.

```typescript
const product = api.generateProduct(42);
```

### Users

#### `getAllUsers(options?: QueryOptions): User[]`

Get all users.

```typescript
const users = api.getAllUsers({ limit: 10 });
```

#### `getUser(id: number): User | null`

Get a specific user by ID.

```typescript
const user = api.getUser(1);
```

#### `generateUser(id?: number): User`

Generate a single user.

```typescript
const user = api.generateUser(42);
```

### Carts

#### `getAllCarts(options?: QueryOptions): Cart[]`

Get all carts.

```typescript
const carts = api.getAllCarts({ limit: 5 });
```

#### `getCart(id: number): Cart`

Get a specific cart by ID.

```typescript
const cart = api.getCart(1);
```

#### `getUserCarts(userId: number, options?: QueryOptions): Cart[]`

Get carts for a specific user.

```typescript
const userCarts = api.getUserCarts(1, { limit: 3 });
```

#### `generateCart(id?: number, userId?: number): Cart`

Generate a single cart.

```typescript
const cart = api.generateCart(42, 1);
```

### Orders

#### `getAllOrders(options?: QueryOptions): Order[]`

Get all orders with optional sorting.

```typescript
const orders = api.getAllOrders({
  limit: 10,
  sort: 'desc'  // Sort by date
});
```

#### `getOrder(id: number): Order`

Get a specific order by ID.

```typescript
const order = api.getOrder(1);
```

#### `getUserOrders(userId: number, options?: QueryOptions): Order[]`

Get orders for a specific user.

```typescript
const userOrders = api.getUserOrders(1, { limit: 5 });
```

#### `generateOrder(id?: number, userId?: number): Order`

Generate a single order.

```typescript
const order = api.generateOrder(42, 1);
```

### Categories

#### `getAllCategories(): Category[]`

Get all available categories.

```typescript
const categories = api.getAllCategories();
```

#### `getCategory(id: number): Category | null`

Get a specific category by ID.

```typescript
const category = api.getCategory(1);
```

### Utility Methods

#### `reset(seed?: number): void`

Reset the API state and optionally set a new seed.

```typescript
api.reset(12345);
```

#### `getApiResponse<T>(data: T, total?: number, page?: number, limit?: number): ApiResponse<T>`

Wrap data in an API response format.

```typescript
const response = api.getApiResponse(products, products.length, 1, 20);
```

## Types

The package exports comprehensive TypeScript types:

```typescript
import { 
  Product, 
  User, 
  Cart, 
  Order, 
  Category, 
  QueryOptions,
  FakeStoreOptions 
} from '@mirshadkvr/fake-store-api';
```

### Product

```typescript
interface Product {
  id: number;
  title: string;
  price: number;
  description: string;
  category: string;
  image: string;
  rating: Rating;
  stock?: number;
  brand?: string;
  sku?: string;
  tags: string[];
}
```

### User

```typescript
interface User {
  id: number;
  email: string;
  username: string;
  password: string;
  name: Name;
  address: Address;
  phone: string;
  avatar?: string;
  dateOfBirth?: string;
  role?: 'admin' | 'customer';
}
```

### Order

```typescript
interface Order {
  id: number;
  userId: number;
  date: string;
  products: OrderProduct[];
  total: number;
  status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
  shippingAddress: Address;
  paymentMethod: 'credit_card' | 'paypal' | 'bank_transfer';
}
```

## Advanced Usage

### Deterministic Data Generation

Use seeds for consistent, reproducible data:

```typescript
const api1 = new FakeStoreAPI({ seed: 12345 });
const api2 = new FakeStoreAPI({ seed: 12345 });

// Both will generate identical data
const product1 = api1.generateProduct(1);
const product2 = api2.generateProduct(1);

console.log(product1 === product2); // Products will be identical
```

### Custom Data Generation

```typescript
// Generate specific amounts of data
const smallStore = api.getAllProducts({ limit: 5 });
const userAccounts = api.getAllUsers({ limit: 100 });

// Get category-specific products
const books = api.getProductsByCategory('Books');
const electronics = api.getProductsByCategory('Electronics');

// Generate orders sorted by date
const recentOrders = api.getAllOrders({ 
  limit: 20, 
  sort: 'desc' 
});
```

### Integration with Testing Frameworks

```typescript
// Jest example
describe('E-commerce tests', () => {
  let fakeStore: FakeStoreAPI;
  
  beforeEach(() => {
    // Use fixed seed for predictable tests
    fakeStore = new FakeStoreAPI({ seed: 12345 });
  });
  
  test('should handle product data', () => {
    const products = fakeStore.getAllProducts({ limit: 5 });
    expect(products).toHaveLength(5);
    expect(products[0]).toHaveProperty('title');
    expect(products[0]).toHaveProperty('price');
  });
});
```

## Available Categories

- Electronics
- Clothing  
- Books
- Home & Garden
- Sports & Outdoors
- Beauty & Personal Care
- Toys & Games
- Automotive
- Health & Wellness
- Food & Beverages

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Changelog

### 1.0.0
- Initial release
- Full TypeScript support
- Comprehensive fake data generation
- Deterministic data with seeds
- Complete test coverage