@vitkuz/shop-service

A robust e-commerce service package for Node.js applications, built with TypeScript and DynamoDB.

Features

🛍️ Complete e-commerce functionality (products, carts, orders)
🔒 Secure and validated operations
📝 Comprehensive logging system
🔄 Proper order status flow management
⚡ Edge case handling
🎯 Type safety with TypeScript
📦 DynamoDB integration
🚀 ESM and CommonJS support

Installation

npm install @vitkuz/shop-service

Order Status Flow

Orders follow a strict status transition flow:

PENDING -> PAID -> SHIPPED -> CANCELLED

Each status can only transition to allowed next states:

PENDING: Can transition to PAID or CANCELLED
PAID: Can transition to SHIPPED or CANCELLED
SHIPPED: Can only transition to CANCELLED
CANCELLED: No further transitions allowed

Edge Cases Handled

Product stock validation during cart operations
Price preservation in cart during product updates
Deleted product handling in orders
Invalid order status transitions prevention
Comprehensive error messages with context

Usage

import { 
  createProduct, 
  createCart, 
  addItemToCart,
  createOrder,
  updateOrderStatus,
  STATUS 
} from '@vitkuz/shop-service';

// Create a product
const product = await createProduct({
  id: 'unique-id',
  name: 'Product Name',
  description: 'Product Description',
  price: 99.99,
  stock: 10,
  imageUrl: 'https://example.com/image.jpg'
});

// Create a cart and add items
const cart = await createCart({ userId: 'user-id' });
await addItemToCart(userId, cart.id, {
  productId: product.id,
  qty: 1,
  price: product.price
});

// Create an order
const order = await createOrder(userId, {
  items: cart.items,
  total: cart.items.reduce((sum, item) => sum + item.price * item.qty, 0),
  paymentMethod: 'credit_card'
});

// Update order status
await updateOrderStatus(userId, order.id, STATUS.ORDER.PAID);

Configuration

The package requires DynamoDB configuration:

import { createContext } from '@vitkuz/shop-service';

createContext({
  tableName: 'your-table-name',
  region: 'your-aws-region'
});

Error Handling

All operations include detailed error messages and proper error types:

try {
  await updateOrderStatus(userId, orderId, STATUS.ORDER.SHIPPED);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
    // Example: "Invalid status transition from PENDING to SHIPPED. 
    // Allowed transitions from PENDING are: PAID, CANCELLED"
  }
}

Logging

The package includes comprehensive logging for all operations:

const context = getContext();
context.logger.level = 'debug'; // Set logging level

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines for details.