Categories

Organize your products with categories. Every product must belong to a category.

Important

Categories are required for products. Every product must belong to a category. Category names must be unique. Create categories before creating products.

Category Model

Structure and properties of a Category

class Category {
  id: string;              // Unique UUID identifier
  name: string;            // Unique category name (required)
  description: string | null;  // Optional description
  isActive: boolean;      // Active status (default: true)
}

Create Category

Create a new category with optional description

With description:

import { createCategoryService } from "commercio";

const categoryService = createCategoryService();

// Create category with description
const category = await categoryService.createCategory(
  "Electronics",
  "Electronic devices and accessories"
);

console.log(category.id);        // UUID
console.log(category.name);       // "Electronics"
console.log(category.description); // "Electronic devices and accessories"
console.log(category.isActive);   // true

Without description:

// Create category without description
const category = await categoryService.createCategory("Electronics");

console.log(category.description); // null
console.log(category.isActive);   // true (default)

Error Handling

Creating a category with a name that already exists will throw an error:

try {
  await categoryService.createCategory("Electronics");
  await categoryService.createCategory("Electronics"); // Error!
} catch (error) {
  // Error: Category with name "Electronics" already exists
}

Category Operations

Get Category

Retrieve categories by ID or name

Get by ID:

// Get category by ID
const category = await categoryService.getCategoryById(categoryId);

console.log(category.name);
console.log(category.description);
console.log(category.isActive);

Get by name:

// Get category by name
const category = await categoryService.getCategoryByName("Electronics");

console.log(category.id);
console.log(category.name);

Error Handling

Both methods throw an error if the category is not found:

try {
  await categoryService.getCategoryById("non-existent-id");
} catch (error) {
  // Error: Category with ID "non-existent-id" not found
}

try {
  await categoryService.getCategoryByName("NonExistent");
} catch (error) {
  // Error: Category with name "NonExistent" not found
}

Complete Example

Full workflow: Creating categories and using them with products

import { createServices } from "commercio";

const { categoryService, productService } = createServices();

// 1. Create categories first
const electronics = await categoryService.createCategory(
  "Electronics",
  "Electronic devices and accessories"
);

const clothing = await categoryService.createCategory(
  "Clothing",
  "Apparel and fashion items"
);

// 2. Get all active categories
const activeCategories = await categoryService.getAllCategories(true);
console.log(`Active categories: ${activeCategories.length}`);

// 3. Create products using categories
const laptop = await productService.createProduct(
  "Laptop Dell XPS 15",
  "SKU-LAPTOP-001",
  electronics.id  // Required: category ID
);

const shirt = await productService.createProduct(
  "Cotton T-Shirt",
  "SKU-SHIRT-001",
  clothing.id  // Required: category ID
);

// 4. Update category
await categoryService.updateCategory(electronics.id, {
  name: "Consumer Electronics",
  description: "Updated: Consumer electronic devices"
});

// 5. Deactivate category (products still reference it)
await categoryService.deactivateCategory(clothing.id);

// 6. Get category by name
const foundCategory = await categoryService.getCategoryByName("Consumer Electronics");
console.log(foundCategory.id === electronics.id); // true

Best Practices

Important guidelines for working with categories

1. Create Categories Before Products

Products require a category. Always create categories first:

// Good: Create category first
const category = await categoryService.createCategory("Electronics");
const product = await productService.createProduct("Laptop", "SKU-001", category.id);

// Bad: This will fail
const product = await productService.createProduct("Laptop", "SKU-001", "non-existent-id");

2. Unique Category Names

Category names must be unique. Handle duplicate name errors:

try {
  await categoryService.createCategory("Electronics");
} catch (error) {
  if (error.message.includes("already exists")) {
    // Category already exists, get it instead
    const existing = await categoryService.getCategoryByName("Electronics");
    return existing;
  }
  throw error;
}

3. Use Active Categories for Filtering

When displaying categories to users, filter by active status:

// Get only active categories for dropdown/selection
const activeCategories = await categoryService.getAllCategories(true);

// Use inactive categories for admin views
const allCategories = await categoryService.getAllCategories();

4. Handle Errors Gracefully

Always handle "not found" errors when retrieving categories:

try {
  const category = await categoryService.getCategoryById(categoryId);
  // Use category...
} catch (error) {
  if (error.message.includes("not found")) {
    // Handle missing category
    console.error("Category not found");
  } else {
    throw error;
  }
}