Optimizing ESHOPMAN Cart Performance: Addressing Quadratic Variant Lookups for Smoother B2B and Bulk Orders

Boosting ESHOPMAN Performance: A Deep Dive into Cart Workflow Optimization

At Move My Store, we understand that a seamless shopping experience is paramount for any e-commerce platform. For ESHOPMAN, our headless commerce solution built on Node.js/TypeScript and deeply integrated with HubSpot for storefront management and CMS deployment, performance is a continuous priority. The ESHOPMAN community recently identified and addressed a critical performance bottleneck within the core cart workflows, particularly impacting merchants handling large B2B orders or bulk purchases. This insight sheds light on the issue and its elegant solution, showcasing ESHOPMAN's commitment to robust and efficient commerce.

The Challenge: Quadratic Variant Lookups in Core Cart Processes

The problem was identified in the prepareVariantsAndItemsWithPricesStep, a crucial component within ESHOPMAN's core flows, specifically located in packages/core/core-flows/src/cart/workflows/get-variants-and-items-with-prices.ts. This step is responsible for preparing variant and item data with pricing information, a process vital for accurate cart representation.

The original implementation iterated over each line item in the cart and, for every item, performed a linear scan (.find()) through the list of fetched variants to match the corresponding variant ID:

const items = (inputItems ?? cart.items ?? []).map((item) => {
  ...
  const variant = variantsData.find((v) => v.id === item.variant_id)

While seemingly innocuous for small carts, this approach resulted in a quadratic time complexity, denoted as O(items × variants). As both the number of line items and the number of distinct variants in the cart grew, the processing time increased exponentially. This issue was not isolated to a single operation; it impacted several critical ESHOPMAN workflows:

• cart/workflows/refresh-cart-items.ts (executed on nearly every cart modification)
• cart/workflows/add-to-cart.ts
• cart/workflows/create-carts.ts
• order/workflows/create-order.ts
• order/workflows/add-line-items.ts

For typical B2C carts with 5-20 items, the performance hit was negligible, measured in microseconds. However, for ESHOPMAN merchants managing large B2B orders, imported carts, or quote-style flows—where carts can contain hundreds or thousands of line items—this quadratic scaling led to significant delays. A cart with 2,000 items, for instance, could experience delays of tens of milliseconds on a single refresh, purely due to this inefficient lookup.

The ESHOPMAN Solution: Efficient Indexing for O(1) Lookups

The ESHOPMAN community proposed and implemented an elegant solution: optimize the variant lookup to achieve constant time complexity, or O(1). This was achieved by first indexing the variantsData into a Map, using the variant ID as the key, before performing the lookups. This pre-processing step ensures that subsequent lookups are instantaneous, regardless of the number of variants.

const variantsById = new Map()
for (const variant of variantsData) {
  if (!variantsById.has(variant.id)) {
    variantsById.set(variant.id, variant)
  }
}
// ...
const variant = variantsById.get(item.variant_id!)

This change is localized to the affected step, introducing no alterations to ESHOPMAN's API or overall behavior. The result is a dramatic improvement in performance for large carts, with speedups ranging from 3.2x for 5 items to an impressive 58.4x for 2,000 items, as measured during testing. This ensures that ESHOPMAN storefronts deployed via HubSpot CMS remain highly responsive, even under heavy load from complex B2B transactions.

Community Impact and ESHOPMAN's Commitment to Performance

This initiative highlights the strength of the ESHOPMAN community and our commitment to continuous platform improvement. Identifying and resolving such core performance issues ensures that ESHOPMAN remains a leading headless commerce platform, offering unparalleled speed and scalability for merchants leveraging HubSpot's ecosystem. For ESHOPMAN developers, understanding these optimizations provides valuable insight into best practices for building high-performance applications on our Node.js/TypeScript foundation. This fix is already in progress, reinforcing ESHOPMAN's dedication to delivering a fast and reliable experience for all users, from storefront management in HubSpot to the end customer.