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

npm install @mirshadkvr/fake-store-api

Quick Start

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

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.

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.

const product = api.getProduct(1);

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

Get products filtered by category.

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

generateProduct(id?: number): Product

Generate a single product.

const product = api.generateProduct(42);

Users

getAllUsers(options?: QueryOptions): User[]

Get all users.

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

getUser(id: number): User | null

Get a specific user by ID.

const user = api.getUser(1);

generateUser(id?: number): User

Generate a single user.

const user = api.generateUser(42);

Carts

getAllCarts(options?: QueryOptions): Cart[]

Get all carts.

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

getCart(id: number): Cart

Get a specific cart by ID.

const cart = api.getCart(1);

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

Get carts for a specific user.

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

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

Generate a single cart.

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

Orders

getAllOrders(options?: QueryOptions): Order[]

Get all orders with optional sorting.

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

getOrder(id: number): Order

Get a specific order by ID.

const order = api.getOrder(1);

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

Get orders for a specific user.

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

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

Generate a single order.

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

Categories

getAllCategories(): Category[]

Get all available categories.

const categories = api.getAllCategories();

getCategory(id: number): Category | null

Get a specific category by ID.

const category = api.getCategory(1);

Utility Methods

reset(seed?: number): void

Reset the API state and optionally set a new seed.

api.reset(12345);

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

Wrap data in an API response format.

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

Types

The package exports comprehensive TypeScript types:

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

Product

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

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

Order

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:

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

// 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

// 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