@mbc-cqrs-serverless/master

Master data and hierarchical settings management for the MBC CQRS Serverless framework. Manage reference data, configuration settings, and multi-level overrides with automatic RDS synchronization.

Features

• Master Data Management: CRUD operations for reference data (products, categories, etc.)
• Hierarchical Settings: 4-level setting inheritance (Common → Tenant → Group → User)
• RDS Integration: Automatic sync to relational database for complex queries
• Multi-tenant: Isolated master data per tenant
• Bulk Operations: Create multiple records in a single request
• Copy Settings: Replicate settings across tenants

Installation

npm install @mbc-cqrs-serverless/master

Quick Start

1. Register the Module

When enableController is true, MasterModule does not register @mbc-cqrs-serverless/task for you. Register TaskModule once in the host app (with your ITaskQueueEventFactory implementation) before or alongside MasterModule. TaskModule.register() is global, so TaskService is available to MasterSettingService, MyTaskService, and controllers without importing TaskModule into every feature module.

import { Module } from '@nestjs/common';
import { MasterModule } from '@mbc-cqrs-serverless/master';
import { TaskModule } from '@mbc-cqrs-serverless/task';
import { PrismaService } from './prisma/prisma.service';
import { MasterDataSyncHandler } from './handlers/master-data-sync.handler';
import { AppTaskQueueEventFactory } from './task/app-task-queue-event.factory';

@Module({
  imports: [
    TaskModule.register({
      taskQueueEventFactory: AppTaskQueueEventFactory,
      // enableController: true, // optional: task REST API from @mbc-cqrs-serverless/task
    }),
    MasterModule.register({
      enableController: true, // Optional: enable REST endpoints
      prismaService: PrismaService, // Required (MasterDataService/MasterSettingService inject it)
      dataSyncHandlers: [MasterDataSyncHandler], // Optional: custom sync handlers
    }),
  ],
})
export class AppModule {}

TaskModule requirement

| Scenario | Action | |----------|--------| | MasterModule.register({ enableController: true }) | Required: call TaskModule.register({ taskQueueEventFactory }) in the host. MasterSettingService and CustomTaskModule (MyTaskService) inject TaskService. | | enableController omitted or false | TaskModule is still needed if you use APIs or services that inject TaskService; otherwise follow your app’s architecture. |

Use one factory class that implements ITaskQueueEventFactory for both app-specific tasks and master Step Functions task mapping (transformTask / transformStepFunctionTask) so only one TASK_QUEUE_EVENT_FACTORY binding exists. Details: @mbc-cqrs-serverless/task README.

2. Use Master Data Service

import { Injectable } from '@nestjs/common';
import { MasterDataService } from '@mbc-cqrs-serverless/master';
import { IInvoke } from '@mbc-cqrs-serverless/core';

@Injectable()
export class ProductService {
  constructor(private readonly masterDataService: MasterDataService) {}

  async createProduct(data: any, opts: { invokeContext: IInvoke }) {
    return this.masterDataService.create(
      {
        tenantCode: 'MBC',
        settingCode: 'PRODUCT',
        code: 'PROD-001',
        name: data.name,
        attributes: { price: data.price, category: data.category },
      },
      opts,
    );
  }
}

API Reference

MasterDataService

Service for managing master data records.

| Method | Description | |--------|-------------| | create(dto, options) | Create new master data | | createSetting(dto, invokeContext) | Create with auto-generated seq | | createBulk(dto, invokeContext) | Create multiple records | | update(key, dto, options) | Update master data | | updateSetting(key, dto, invokeContext) | Update with simplified params | | delete(key, options) | Soft delete master data | | deleteSetting(key, invokeContext) | Delete with simplified params | | get(key) | Get single record by pk/sk | | getDetail(key) | Get record with RDS entity format | | list(searchDto) | List by DynamoDB query | | listByRds(searchDto, context) | List with RDS full-text search | | checkExistCode(tenantCode, type, code) | Check if code exists |

MasterSettingService

Service for managing hierarchical settings.

| Method | Description | |--------|-------------| | getSetting(dto, options) | Get effective setting (auto-resolves hierarchy) | | createCommonTenantSetting(dto, options) | Create common-level setting | | createTenantSetting(dto, options) | Create tenant-level setting | | createGroupSetting(dto, options) | Create group-level setting | | createUserSetting(dto, options) | Create user-level setting | | updateSetting(key, dto, options) | Update existing setting | | deleteSetting(key, options) | Soft delete setting | | copy(dto, options) | Copy settings to other tenants | | list(searchDto, invokeContext) | List settings with search |

Setting Hierarchy

Settings are resolved in order of specificity (most specific wins):

1. User Setting     (SETTING#TENANT_USER#userId#code)
         ↓ if not found
2. Group Setting    (SETTING#TENANT_GROUP#groupId#code)
         ↓ if not found
3. Tenant Setting   (SETTING#code)
         ↓ if not found
4. Common Setting   (pk: SETTING#common)

Example: Theme Setting

// 1. Create common default (all tenants)
await masterSettingService.createCommonTenantSetting({
  code: 'THEME',
  name: 'UI Theme',
  settingValue: { primaryColor: '#007bff', mode: 'light' },
}, opts);

// 2. Override for specific tenant
await masterSettingService.createTenantSetting({
  tenantCode: 'COMPANY_A',
  code: 'THEME',
  name: 'UI Theme',
  settingValue: { primaryColor: '#ff0000', mode: 'light' },
}, opts);

// 3. Override for admin group
await masterSettingService.createGroupSetting({
  tenantCode: 'COMPANY_A',
  groupId: 'ADMIN',
  code: 'THEME',
  name: 'UI Theme',
  settingValue: { primaryColor: '#ff0000', mode: 'dark' },
}, opts);

// 4. Override for specific user
await masterSettingService.createUserSetting({
  tenantCode: 'COMPANY_A',
  userId: 'user-123',
  code: 'THEME',
  name: 'UI Theme',
  settingValue: { primaryColor: '#00ff00', mode: 'dark' },
}, opts);

// Get effective setting (resolves automatically)
const theme = await masterSettingService.getSetting({ code: 'THEME' }, opts);
// Returns user setting if exists, otherwise group → tenant → common

Usage Examples

Master Data CRUD

@Injectable()
export class CategoryService {
  constructor(private readonly masterDataService: MasterDataService) {}

  // Create
  async create(dto: CreateCategoryDto, invokeContext: IInvoke) {
    return this.masterDataService.createSetting(
      {
        settingCode: 'CATEGORY',
        name: dto.name,
        attributes: { description: dto.description },
      },
      invokeContext,
    );
  }

  // Update
  async update(pk: string, sk: string, dto: UpdateCategoryDto, invokeContext: IInvoke) {
    return this.masterDataService.updateSetting(
      { pk, sk },
      { name: dto.name, attributes: dto.attributes },
      invokeContext,
    );
  }

  // Delete (soft delete)
  async delete(pk: string, sk: string, invokeContext: IInvoke) {
    return this.masterDataService.deleteSetting({ pk, sk }, invokeContext);
  }

  // Search with RDS
  async search(keyword: string, invokeContext: IInvoke) {
    return this.masterDataService.listByRds(
      {
        keyword,
        settingCode: 'CATEGORY',
        page: 1,
        pageSize: 20,
      },
      { invokeContext },
    );
  }
}

Bulk Creation

async createCategories(categories: CreateCategoryDto[], invokeContext: IInvoke) {
  return this.masterDataService.createBulk(
    {
      items: categories.map((cat) => ({
        settingCode: 'CATEGORY',
        name: cat.name,
        attributes: cat.attributes,
      })),
    },
    invokeContext,
  );
}

Copy Settings Across Tenants

async copySettingsToNewTenant(settingId: string, targetTenants: string[], opts: { invokeContext: IInvoke }) {
  return this.masterSettingService.copy(
    {
      masterSettingId: settingId,
      targetTenants,
      dataCopyOption: { mode: DataCopyMode.ALL },
    },
    opts,
  );
}

Data Model

Master Data Key Pattern

pk: MASTER#[tenantCode]
sk: DATA#[settingCode]#[code]

Master Setting Key Pattern

pk: SETTING#[tenantCode] or SETTING#common
sk: SETTING#[code]                           (tenant/common)
    SETTING#TENANT_GROUP#[groupId]#[code]    (group)
    SETTING#TENANT_USER#[userId]#[code]      (user)

Related Packages

| Package | Description | |---------|-------------| | @mbc-cqrs-serverless/core | Core CQRS framework | | @mbc-cqrs-serverless/task | Async tasks and TaskService (register once in the host when using master controllers) | | @mbc-cqrs-serverless/sequence | Uses master data for sequence formats | | @mbc-cqrs-serverless/tenant | Tenant management for group settings |

Documentation

Full documentation available at https://mbc-cqrs-serverless.mbc-net.com/

• Master Service Guide

Configurable table name

MasterModule uses the master DynamoDB table by default. Pass tableName to override it (backward compatible — omitting it keeps master). Both register and registerAsync accept it:

⚠️ Renaming the master table is not fully supported. The master table is a framework-wide central config store — TtlService (TTL config) and the @mbc-cqrs-serverless/sequence package (numbering formats) read a fixed master-data table name. If you override the master tableName, those readers keep looking at master-data, so TTLs are not applied and sequence formats silently fall back to defaults. MasterModule.register/registerAsync logs a warning when a custom tableName is set. Prefer keeping the default master; only override it if you have separately addressed those readers. (Customizing the directory / survey-template / ui-setting table names has no such caveat.)

MasterModule.register({
  enableController: true,
  prismaService: PrismaService,
  tableName: 'catalog', // default: 'master' — see the caveat above
})

MasterModule.registerAsync({
  tableName: 'catalog',
  imports: [PrismaModule],
  inject: [PrismaService], // resolve and return the PrismaService INSTANCE
  useFactory: (prisma) => ({ prismaService: prisma }),
})

Provisioning: Add only the raw base name (e.g. "catalog") to prisma/dynamodbs/cqrs.json; the CLI creates the -command / -data / -history physical tables, and your IaC must define the same three. Note that @mbc-cqrs-serverless/master's postinstall auto-adds only the default master name — a custom name must be added manually.

Shared table: If you also use @mbc-cqrs-serverless/ui-setting (SettingModule), both modules must use the same tableName, because they share the same physical table. MasterModule should own the data-sync pipeline — register SettingModule with registerEventHandlerAlias: false. If both modules own the <tableName>_CommandEventHandler alias, the app boots but logs a warning and the effective owner becomes import-order dependent.

License

Copyright © 2024-2025, Murakami Business Consulting, Inc. https://www.mbc-net.com/

This project is under the MIT License.