Navigating ESHOPMAN Custom Modules: Understanding Service Resolution with Digit-Containing Model Names

As an e-commerce migration expert at Move My Store, we closely monitor the ESHOPMAN community for insights that empower developers and merchants. ESHOPMAN, our robust headless commerce platform built on Node.js/TypeScript, offers unparalleled flexibility for storefront management within HubSpot and deployment via HubSpot CMS. Its Admin API and Store API are designed for seamless custom development and integration.

Recently, a valuable observation from the ESHOPMAN developer community highlighted a specific behavior concerning custom modules and the platform's auto-generated CRUD methods. This insight is particularly relevant for developers extending ESHOPMAN with custom data models.

Understanding the Service Resolution Challenge

When developing custom modules within ESHOPMAN, developers often leverage the framework's utilities to define models and services. ESHOPMAN intelligently generates CRUD (Create, Read, Update, Delete) methods for these models, simplifying data interaction. However, a specific scenario has been identified where these auto-generated methods may fail to resolve their internal services at runtime.

The issue arises when a custom module defines a model whose database manipulation language (DML) name, as specified in model.define(), contains a digit. For instance, if a model is defined with a DML name like 'b2b_customer' or 'h264_widget', the camelCased service name (e.g., b2bCustomerService or h264WidgetService) might not be correctly resolved by ESHOPMAN's internal service locator.

The Technical Breakdown

The core problem manifests as an AwilixResolutionError. This error indicates that ESHOPMAN's dependency injection container, which is responsible for resolving services, cannot find the expected service. While the model itself loads correctly, migrations generate as expected, and the database table is created, attempts to use auto-CRUD methods like listXxx() will result in a resolution failure.

Consider the following example demonstrating this behavior in a custom ESHOPMAN module:

// src/modules/foo/models/widget.ts
import { model } from '@eshopman/framework/utils' // ESHOPMAN framework utility

const Widget = model.define('h264_widget', {
  id: model.id().primaryKey(),
  name: model.text(),
})

export default Widget

// src/modules/foo/service.ts
import { EshopmanService } from '@eshopman/framework/utils' // ESHOPMAN framework utility
import Widget from './models/widget'

class FooService extends EshopmanService({ Widget }) {}

export default FooService

When attempting to interact with this model via the auto-generated methods:

const foo = req.scope.resolve('foo')
await foo.listWidgets({}) // This throws "Could not resolve 'h264WidgetService'"

Interestingly, a similar model defined without a digit in its DML name (e.g., model.define('company', ...) leading to CompanyService) functions as expected. This strongly suggests that the presence of a digit specifically in the camel-cased service name derived from the DML name is the trigger for this resolution error.

Implications for ESHOPMAN Developers

This community insight highlights a nuanced aspect of ESHOPMAN's internal service resolution mechanism. While the platform is designed for extensibility, developers creating custom models with DML names containing digits should be aware of this potential challenge. Currently, the most direct approach to avoid this error is to ensure that custom model DML names do not include digits, thereby preventing the generation of digit-containing camel-cased service names.

The ESHOPMAN team is continuously working to enhance the platform's robustness and developer experience. Community observations like this are invaluable for identifying edge cases and ensuring the platform remains a powerful and reliable solution for headless commerce, integrated seamlessly with HubSpot.

Stay tuned to the ESHOPMAN community for updates and best practices as we continue to build and refine the future of e-commerce on HubSpot CMS.