[!WARNING] This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

📚 Documentation: 86d.app/docs/modules/comparisons

Comparisons Module

Product comparison module that lets customers add products to a side-by-side comparison view. Supports comparing prices, categories, and arbitrary product attributes across up to 4 products (configurable). Works for both guest and authenticated customers.

Installation

npm install @86d-app/comparisons

Usage

import comparisons from "@86d-app/comparisons";

const module = comparisons({
  maxProducts: "6", // allow up to 6 products per comparison
});

Configuration

| Option | Type | Default | Description | |---|---|---|---| | maxProducts | string | "4" | Maximum number of products per comparison list |

Store Endpoints

| Method | Path | Description | |---|---|---| | POST | /comparisons/add | Add a product to the comparison | | GET | /comparisons | Get the current comparison items | | POST | /comparisons/remove | Remove a product from the comparison | | POST | /comparisons/clear | Clear all comparison items | | POST | /comparisons/merge | Merge session comparison to customer (requires auth) |

Response shapes

Add product:

{ item: ComparisonItem }
// or { error: string, status: 400 } if limit reached

List comparison:

{ items: ComparisonItem[], total: number }

Remove product:

{ removed: boolean }

Clear comparison:

{ cleared: number }

Merge comparison:

{ merged: number }

Admin Endpoints

| Method | Path | Description | |---|---|---| | GET | /admin/comparisons | List all comparison items (paginated) | | GET | /admin/comparisons/frequent | Most frequently compared products | | GET | /admin/comparisons/customer/:id | Comparison items for a specific customer | | DELETE | /admin/comparisons/:id/delete | Delete a comparison item |

Controller API

interface ComparisonController {
  /** Add product to comparison. Throws if limit reached. Updates if already present. */
  addProduct(params: {
    customerId?: string;
    sessionId?: string;
    productId: string;
    productName: string;
    productSlug: string;
    productImage?: string;
    productPrice?: number;
    productCategory?: string;
    attributes?: Record<string, string>;
    maxProducts?: number;
  }): Promise<ComparisonItem>;

  /** Remove a product from comparison by productId. */
  removeProduct(params: {
    customerId?: string;
    sessionId?: string;
    productId: string;
  }): Promise<boolean>;

  /** Get all items in a comparison list. Sorted by addedAt ascending. */
  getComparison(params: {
    customerId?: string;
    sessionId?: string;
  }): Promise<ComparisonItem[]>;

  /** Clear all items from a comparison list. Returns count cleared. */
  clearComparison(params: {
    customerId?: string;
    sessionId?: string;
  }): Promise<number>;

  /** Merge session comparison to customer on login. Respects max limit. */
  mergeComparison(params: {
    sessionId: string;
    customerId: string;
    maxProducts?: number;
  }): Promise<number>;

  /** Delete a specific item by ID (admin). */
  deleteItem(id: string): Promise<boolean>;

  /** List all items across all customers (admin). */
  listAll(params?: {
    customerId?: string;
    productId?: string;
    take?: number;
    skip?: number;
  }): Promise<ComparisonItem[]>;

  /** Count comparison items (admin). */
  countItems(params?: {
    customerId?: string;
    productId?: string;
  }): Promise<number>;

  /** Get most frequently compared products (admin). */
  getFrequentlyCompared(params?: {
    take?: number;
  }): Promise<FrequentlyCompared[]>;
}

Types

interface ComparisonItem {
  id: string;
  customerId?: string;
  sessionId?: string;
  productId: string;
  productName: string;
  productSlug: string;
  productImage?: string;
  productPrice?: number;
  productCategory?: string;
  attributes?: Record<string, string>;
  addedAt: Date;
}

interface FrequentlyCompared {
  productId: string;
  productName: string;
  productSlug: string;
  productImage?: string;
  compareCount: number;
}

Store Components

ComparisonBar

Fixed bottom bar that shows products currently in the comparison list. Displays product thumbnails with remove buttons, a "Compare" link, and a "Clear" button.

Props

| Prop | Type | Default | Description | |---|---|---|---| | customerId | string? | — | Customer ID (for authenticated users) | | sessionId | string? | — | Session ID (for guest users) |

Usage in MDX

<ComparisonBar sessionId={sessionId} />

Typically placed in the main layout so it appears on every page when the comparison list is non-empty. The bar auto-hides when the comparison list is empty.

ComparisonTable

Full side-by-side product comparison table. Shows product images, prices, categories, and all attributes in a horizontally scrollable table with sticky row labels.

Props

| Prop | Type | Default | Description | |---|---|---|---| | customerId | string? | — | Customer ID (for authenticated users) | | sessionId | string? | — | Session ID (for guest users) | | title | string? | "Compare Products" | Section heading |

Usage in MDX

<ComparisonTable title="Compare Products" />

Typically placed on a dedicated /compare page. Shows an empty state message when no products are added. Each product column includes an image, name link, remove button, and all attribute rows.

Notes

• Comparison items are sorted by addedAt ascending to maintain a stable display order
• Duplicate products are updated in-place rather than rejected
• The attributes field accepts arbitrary key-value pairs (e.g., { "Color": "Red", "Weight": "2kg" }) for side-by-side comparison rows
• Session comparisons are automatically merged to the customer on login via the /merge endpoint
• Merge respects the max products limit and skips products already in the customer's comparison