@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 when enableController is true
      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

License

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

This project is under the MIT License.