Master

The Master Service provides functionality for managing master data and settings in a multi-tenant environment

Overview

The Master Service consists of two main components:

Master Setting Service

• Implements hierarchical settings management
• Supports creation of settings at all levels
• Provides update and delete operations for tenant settings
• Implements cascading settings retrieval

Master Data Service

• Implements CRUD operations for master data entities
• Provides list and retrieval functionality
• Includes code validation capabilities
• Ensures data integrity across tenant boundaries

Architecture

Installation

npm install @mbc-cqrs-serverless/master

Basic Usage

The solution for customizing the behavior of the MasterModule is to pass it an options object in the static register() method.

Module Options

Option	Type	Description
enableController	boolean	Enable or disable default master controller
dataSyncHandlers	Type<IDataSyncHandler>[]	Optional handlers to sync master data to external systems (e.g., RDS)
prismaService	Type<any>	Optional Prisma service for RDS-backed queries

import { MasterModule } from '@mbc-cqrs-serverless/master'

@Module({
  imports: [ MasterModule.register({
      enableController: true,
      dataSyncHandlers: [MasterDataRdsSyncHandler],
      prismaService: PrismaService,
    })],
  controllers: [],
  exports: [],
})

API Reference

MasterSettingService

The MasterSettingService interface manages settings at various levels user, group, tenant, common. It allows retrieving, updating, creating, and deleting settings.

getSetting(dto: GetSettingDto, context: { invokeContext: IInvoke }): Promise<MasterSettingEntity>

Retrieves a specific setting based on the provided setting code.

const masterSetting = await this.masterSettingService.getSetting(
  {
    code: "service",
  }
);

createCommonTenantSetting(dto: CommonSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>

Creates a common tenant setting that is shared across the system.

const masterSetting = await this.masterSettingService.createGroupSetting(
  {
  name: "common setting",
  code: "service",
  settingValue: {
    region: "US",
    plan: "common"
  }
});

createTenantSetting(dto: TenantSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>

Creates a tenant-specific setting.

const masterSetting = await this.masterSettingService.createGroupSetting(
  {
  name: "tenant setting",
  code: "service",
  tenantCode: "mbc",
  settingValue: {
    region: "US",
    plan: "tenant"
  }
});

createGroupSetting(dto: GroupSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>

Creates a group-specific setting within a tenant.

const masterSetting = await this.masterSettingService.createGroupSetting(
  {
  name: "group setting",
  code: "service",
  tenantCode: "mbc",
  groupId: "12",
  settingValue: {
    region: "US",
    plan: "USER"
  }
});

createUserSetting(dto: UserSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>

Creates a user-specific setting within a tenant.

const masterSetting = await this.masterSettingService.createUserSetting(
  {
  name: "user setting",
  code: "service",
  tenantCode: "mbc",
  userId: "92ca4f68-9ac6-4080-9ae2-2f02a86206a4",
  settingValue: {
    region: "US",
    plan: "USER"
  }
});

updateSetting(params: DetailKey, dto: UpdateSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>

Updates an existing setting.

const masterSetting = await this.masterSettingService.updateSetting(
  {
    pk:"MASTER#abc", 
    sk:"MASTER_SETTING#service"
  },
  {
  name: 'Example Master Setting',
  settingValue: {
    homepage: "url",
    desc: "string"
  }
});

deleteSetting(key: DetailKey, context: { invokeContext: IInvoke }): Promise<CommandModel>

Deletes a specific setting based on the provided key.

const masterSetting = await this.masterSettingService.deleteSetting(
  {
    pk:"MASTER#abc", 
    sk:"MASTER_SETTING#service"
  }
);

MasterDataService

The MasterDataService service provides methods to manage master data and operations. This includes listing, retrieving, creating, updating, and deleting data, as well as checking for the existence of specific codes.

list( searchDto: MasterDataSearchDto): Promise<MasterDataListEntity>

Lists master data based on the provided search criteria.

const masterData = await this.masterDataService.list(
  {
    tenantCode: "mbc",
    settingCode: "service"
  }
);

get(key: DetailDto): Promise<MasterDataEntity>

Get a master data by pk and sk.

const masterData = await this.masterDataService.get(
  {
    pk:"MASTER#abc", 
    sk:"MASTER_DATA#service#01"
  }
);

create(data: CreateMasterDataDto, context: { invokeContext: IInvoke })

Creates a new master data entity

const masterData = await this.masterDataService.create({
  code: 'MASTER001',
  name: 'Example Master Data',
  settingCode: "service",
  tenantCode: "COMMON",
  attributes: {
    homepage: "http://mbc.com",
    desc: "description for mbc"
  }
});

update(key: DetailDto, updateDto: UpdateDataSettingDto, context: { invokeContext: IInvoke })

Updates existing master data.

const masterData = await this.masterDataService.update(
  {
    pk:"MASTER#abc", 
    sk:"MASTER_DATA#service#01"
  },
  {
  name: 'Example Master Data',
  attributes: {
    homepage: "http://mbc.com",
    desc: "description for mbc"
  }
});

delete(key: DetailDto, opts: { invokeContext: IInvoke })

Deletes specific master data based on the provided key.

const masterData = await this.masterDataService.delete(
  {
    pk:"MASTER#abc", 
    sk:"MASTER_DATA#service#01"
  }
);

checkExistCode(tenantCode: string, type: string, code: string)

Checks if a specific code exists within the given tenant and type.

const masterData = await this.masterDataService.checkExistCode("mbc", "service", "01");

search(searchDto: CustomMasterDataSearchDto): Promise<MasterRdsListEntity>

Searches master data in RDS with filtering and pagination. This method is used when Prisma service is configured.

const result = await this.masterDataService.search({
  settingCode: "service",    // Exact match for master type code
  keyword: "example",        // Partial match (case-insensitive) for name
  code: "001",               // Partial match (case-insensitive) for master code
  page: 1,
  pageSize: 10,
  orderBys: ["seq", "masterCode"],
});

Search Parameters

Parameter	Type	Required	Match Type	Description
settingCode	string	No	Exact match	Filter by master type code (masterTypeCode)
keyword	string	No	Partial match (case-insensitive)	Filter by name field
code	string	No	Partial match (case-insensitive)	Filter by master code
page	number	No	-	Page number (default: 1)
pageSize	number	No	-	Items per page (default: 10)
orderBys	string[]	No	-	Sort order (default: ["seq", "masterCode"])
isDeleted	boolean	No	Exact match	Filter by deletion status

Known Issue (Fixed in v1.0.17)

In versions prior to v1.0.17, the settingCode parameter incorrectly used partial matching (contains) instead of exact matching. This caused unintended search results - for example, searching for "PRODUCT" would also return "PRODUCT_TYPE" and "MY_PRODUCT".

If you are using v1.0.16 or earlier and need exact matching for settingCode, upgrade to v1.0.17 or later.

See also: Changelog v1.0.17