@mbc-cqrs-serverless/ui-setting 1.0.16 → 1.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +254 -137
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,17 +1,19 @@
1
1
  ![MBC CQRS serverless framework](https://mbc-cqrs-serverless.mbc-net.com/img/mbc-cqrs-serverless.png)
2
2
 
3
- # MBC CQRS serverless framework UI Setting package
3
+ # @mbc-cqrs-serverless/ui-setting
4
4
 
5
- ## Description
5
+ [![npm version](https://badge.fury.io/js/@mbc-cqrs-serverless%2Fui-setting.svg)](https://www.npmjs.com/package/@mbc-cqrs-serverless/ui-setting)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
7
 
7
- The UI Setting package manages user interface configuration and preferences in the MBC CQRS Serverless framework. It provides:
8
+ UI configuration management for the MBC CQRS Serverless framework. Manage user interface settings, themes, preferences, and tenant-specific customizations.
8
9
 
9
- - User interface configuration management
10
- - Theme and layout settings
11
- - User preferences storage
12
- - Multi-tenant UI customization
13
- - Dynamic UI configuration updates
14
- - Settings synchronization
10
+ ## Features
11
+
12
+ - **Setting Schema Definition**: Define settings with codes and attributes
13
+ - **Data Setting Management**: CRUD operations for setting values
14
+ - **Multi-tenant Support**: Tenant-isolated UI configurations
15
+ - **Validation**: Automatic setting code validation
16
+ - **CQRS Integration**: Full event sourcing for setting changes
15
17
 
16
18
  ## Installation
17
19
 
@@ -19,186 +21,301 @@ The UI Setting package manages user interface configuration and preferences in t
19
21
  npm install @mbc-cqrs-serverless/ui-setting
20
22
  ```
21
23
 
22
- ## Usage
24
+ ## Quick Start
23
25
 
24
- ### Basic Setup
26
+ ### 1. Register the Module
25
27
 
26
- 1. Import and configure the UI Setting module:
27
28
  ```typescript
28
- import { UiSettingModule } from '@mbc-cqrs-serverless/ui-setting';
29
29
  import { Module } from '@nestjs/common';
30
+ import { SettingModule } from '@mbc-cqrs-serverless/ui-setting';
30
31
 
31
32
  @Module({
32
33
  imports: [
33
- UiSettingModule.forRoot({
34
- tableName: 'ui-settings',
35
- region: 'ap-northeast-1',
34
+ SettingModule.register({
35
+ enableSettingController: true, // Optional: enable setting schema REST endpoints
36
+ enableDataController: true, // Optional: enable data setting REST endpoints
36
37
  }),
37
38
  ],
38
39
  })
39
40
  export class AppModule {}
40
41
  ```
41
42
 
42
- ### Managing Settings
43
-
44
- 1. Define settings schema:
45
- ```typescript
46
- import { SettingSchema } from '@mbc-cqrs-serverless/ui-setting';
47
-
48
- const themeSettings: SettingSchema = {
49
- name: 'theme',
50
- properties: {
51
- mode: { type: 'string', enum: ['light', 'dark'] },
52
- primaryColor: { type: 'string' },
53
- fontSize: { type: 'number' },
54
- },
55
- };
56
- ```
43
+ ### 2. Use the Data Setting Service
57
44
 
58
- 2. Use the settings service:
59
45
  ```typescript
60
- import { SettingService } from '@mbc-cqrs-serverless/ui-setting';
46
+ import { Injectable } from '@nestjs/common';
47
+ import { DataSettingService } from '@mbc-cqrs-serverless/ui-setting';
48
+ import { IInvoke } from '@mbc-cqrs-serverless/core';
61
49
 
62
50
  @Injectable()
63
51
  export class ThemeService {
64
- constructor(
65
- private readonly settingService: SettingService
66
- ) {}
52
+ constructor(private readonly dataSettingService: DataSettingService) {}
67
53
 
68
- async getUserTheme(userId: string): Promise<ThemeSettings> {
69
- return this.settingService.getUserSettings(userId, 'theme');
70
- }
71
-
72
- async updateUserTheme(
73
- userId: string,
74
- theme: ThemeSettings
75
- ): Promise<void> {
76
- await this.settingService.updateUserSettings(
77
- userId,
78
- 'theme',
79
- theme
54
+ async createThemePreset(tenantCode: string, data: any, opts: { invokeContext: IInvoke }) {
55
+ return this.dataSettingService.create(
56
+ tenantCode,
57
+ {
58
+ settingCode: 'THEME',
59
+ code: data.code,
60
+ name: data.name,
61
+ attributes: {
62
+ primaryColor: data.primaryColor,
63
+ mode: data.mode,
64
+ fontSize: data.fontSize,
65
+ },
66
+ },
67
+ opts,
80
68
  );
81
69
  }
82
70
  }
83
71
  ```
84
72
 
85
- ### Multi-tenant Configuration
73
+ ## API Reference
74
+
75
+ ### DataSettingService
76
+
77
+ Service for managing setting data values.
78
+
79
+ | Method | Description |
80
+ |--------|-------------|
81
+ | `create(tenantCode, dto, options)` | Create new setting data |
82
+ | `update(key, dto, options)` | Update setting data |
83
+ | `delete(key, options)` | Soft delete setting data |
84
+ | `get(key)` | Get setting data by pk/sk |
85
+ | `list(tenantCode, searchDto)` | List settings by tenant |
86
+ | `checkExistCode(tenantCode, settingCode, code)` | Check if code exists |
87
+
88
+ ### SettingService
89
+
90
+ Service for managing setting schemas.
91
+
92
+ | Method | Description |
93
+ |--------|-------------|
94
+ | `create(tenantCode, dto, options)` | Create setting schema |
95
+ | `update(key, dto, options)` | Update setting schema |
96
+ | `delete(key, options)` | Delete setting schema |
97
+ | `get(key)` | Get setting schema |
98
+ | `list(tenantCode, searchDto)` | List setting schemas |
99
+
100
+ ### CreateDataSettingDto
101
+
102
+ | Property | Type | Required | Description |
103
+ |----------|------|----------|-------------|
104
+ | `settingCode` | string | Yes | Parent setting schema code |
105
+ | `code` | string | Yes | Unique value code |
106
+ | `name` | string | No | Display name |
107
+ | `attributes` | object | No | Setting values |
108
+
109
+ ## Usage Examples
110
+
111
+ ### Define Setting Schema
112
+
113
+ First, create the setting schema:
86
114
 
87
- 1. Manage tenant-level settings:
88
115
  ```typescript
89
- @Injectable()
90
- export class TenantConfigService {
91
- constructor(
92
- private readonly settingService: SettingService
93
- ) {}
94
-
95
- @UseTenant()
96
- async getTenantLayout(
97
- @TenantContext() tenantId: string
98
- ): Promise<LayoutSettings> {
99
- return this.settingService.getTenantSettings(
100
- tenantId,
101
- 'layout'
102
- );
103
- }
116
+ async createSettingSchema(tenantCode: string, opts: { invokeContext: IInvoke }) {
117
+ return this.settingService.create(
118
+ tenantCode,
119
+ {
120
+ code: 'THEME',
121
+ name: 'Theme Settings',
122
+ attributes: {
123
+ description: 'UI theme configuration',
124
+ schema: {
125
+ primaryColor: { type: 'string', format: 'color' },
126
+ mode: { type: 'string', enum: ['light', 'dark'] },
127
+ fontSize: { type: 'number', min: 12, max: 24 },
128
+ },
129
+ },
130
+ },
131
+ opts,
132
+ );
104
133
  }
105
134
  ```
106
135
 
107
- ### Dynamic Updates
136
+ ### Create Setting Values
137
+
138
+ Then, create values for the schema:
108
139
 
109
- 1. Listen for setting changes:
110
140
  ```typescript
111
- import { SettingUpdateEvent } from '@mbc-cqrs-serverless/ui-setting';
112
-
113
- @EventsHandler(SettingUpdateEvent)
114
- export class SettingUpdateHandler implements IEventHandler<SettingUpdateEvent> {
115
- async handle(event: SettingUpdateEvent): Promise<void> {
116
- // Handle setting update
117
- if (event.settingType === 'theme') {
118
- await this.notifyThemeChange(event.userId);
119
- }
120
- }
141
+ async createThemePreset(
142
+ tenantCode: string,
143
+ preset: ThemePresetDto,
144
+ opts: { invokeContext: IInvoke },
145
+ ) {
146
+ return this.dataSettingService.create(
147
+ tenantCode,
148
+ {
149
+ settingCode: 'THEME',
150
+ code: preset.code,
151
+ name: preset.name,
152
+ attributes: {
153
+ primaryColor: preset.primaryColor,
154
+ mode: preset.mode,
155
+ fontSize: preset.fontSize,
156
+ },
157
+ },
158
+ opts,
159
+ );
121
160
  }
122
161
  ```
123
162
 
124
- ### User Preferences
163
+ ### Update Setting
125
164
 
126
- 1. Manage user preferences:
127
165
  ```typescript
128
- @Injectable()
129
- export class PreferenceService {
130
- constructor(
131
- private readonly settingService: SettingService
132
- ) {}
133
-
134
- async getUserPreferences(userId: string): Promise<UserPreferences> {
135
- const [theme, layout, notifications] = await Promise.all([
136
- this.settingService.getUserSettings(userId, 'theme'),
137
- this.settingService.getUserSettings(userId, 'layout'),
138
- this.settingService.getUserSettings(userId, 'notifications'),
139
- ]);
140
-
141
- return { theme, layout, notifications };
142
- }
166
+ async updateTheme(
167
+ pk: string,
168
+ sk: string,
169
+ updates: UpdateThemeDto,
170
+ opts: { invokeContext: IInvoke },
171
+ ) {
172
+ return this.dataSettingService.update(
173
+ { pk, sk },
174
+ {
175
+ name: updates.name,
176
+ attributes: updates.attributes,
177
+ },
178
+ opts,
179
+ );
143
180
  }
144
181
  ```
145
182
 
146
- ### Layout Management
183
+ ### Delete Setting
147
184
 
148
- 1. Configure layout settings:
149
185
  ```typescript
150
- @Injectable()
151
- export class LayoutService {
152
- constructor(
153
- private readonly settingService: SettingService
154
- ) {}
155
-
156
- async updateLayout(
157
- userId: string,
158
- layout: LayoutConfig
159
- ): Promise<void> {
160
- await this.settingService.updateUserSettings(
161
- userId,
162
- 'layout',
163
- {
164
- sidebar: layout.sidebar,
165
- toolbar: layout.toolbar,
166
- content: layout.content,
167
- }
168
- );
169
- }
186
+ async deleteTheme(pk: string, sk: string, opts: { invokeContext: IInvoke }) {
187
+ return this.dataSettingService.delete({ pk, sk }, opts);
170
188
  }
171
189
  ```
172
190
 
173
- ### Settings Synchronization
191
+ ### List Settings
174
192
 
175
- 1. Implement real-time updates:
176
193
  ```typescript
177
- @WebSocketGateway()
178
- export class SettingGateway {
179
- @SubscribeMessage('syncSettings')
180
- async handleSync(
181
- client: Socket,
182
- userId: string
183
- ): Promise<void> {
184
- const settings = await this.settingService.getAllUserSettings(
185
- userId
186
- );
187
- client.emit('settingsUpdate', settings);
194
+ async getThemePresets(tenantCode: string) {
195
+ return this.dataSettingService.list(tenantCode, {
196
+ settingCode: 'THEME',
197
+ });
198
+ }
199
+
200
+ async searchSettings(tenantCode: string, keyword: string) {
201
+ return this.dataSettingService.list(tenantCode, {
202
+ // Returns all settings for the tenant
203
+ });
204
+ }
205
+ ```
206
+
207
+ ### Check Code Availability
208
+
209
+ ```typescript
210
+ async isCodeAvailable(
211
+ tenantCode: string,
212
+ settingCode: string,
213
+ code: string,
214
+ ): Promise<boolean> {
215
+ const exists = await this.dataSettingService.checkExistCode(
216
+ tenantCode,
217
+ settingCode,
218
+ code,
219
+ );
220
+ return !exists;
221
+ }
222
+ ```
223
+
224
+ ## Data Model
225
+
226
+ ### Setting Schema Key Pattern
227
+
228
+ ```
229
+ pk: SETTING#[tenantCode]
230
+ sk: SETTING#[settingCode]
231
+
232
+ Example:
233
+ pk: SETTING#MBC
234
+ sk: SETTING#THEME
235
+ ```
236
+
237
+ ### Setting Data Key Pattern
238
+
239
+ ```
240
+ pk: SETTING#[tenantCode]
241
+ sk: [settingCode]#[code]
242
+
243
+ Example:
244
+ pk: SETTING#MBC
245
+ sk: THEME#DARK_MODE
246
+ ```
247
+
248
+ ### Example Setting Data Structure
249
+
250
+ ```json
251
+ {
252
+ "pk": "SETTING#MBC",
253
+ "sk": "THEME#DARK_MODE",
254
+ "code": "DARK_MODE",
255
+ "name": "Dark Mode Theme",
256
+ "tenantCode": "MBC",
257
+ "type": "MASTER",
258
+ "isDeleted": false,
259
+ "attributes": {
260
+ "primaryColor": "#1a1a2e",
261
+ "mode": "dark",
262
+ "fontSize": 14
188
263
  }
189
264
  }
190
265
  ```
191
266
 
267
+ ## Common Use Cases
268
+
269
+ ### Theme Configuration
270
+
271
+ ```typescript
272
+ // Create theme presets
273
+ await dataSettingService.create(tenantCode, {
274
+ settingCode: 'THEME',
275
+ code: 'CORPORATE',
276
+ name: 'Corporate Theme',
277
+ attributes: { primaryColor: '#003366', mode: 'light', fontSize: 14 },
278
+ }, opts);
279
+ ```
280
+
281
+ ### Layout Preferences
282
+
283
+ ```typescript
284
+ // Store user layout preferences
285
+ await dataSettingService.create(tenantCode, {
286
+ settingCode: 'LAYOUT',
287
+ code: 'COMPACT',
288
+ name: 'Compact Layout',
289
+ attributes: { sidebarWidth: 200, contentPadding: 16, density: 'compact' },
290
+ }, opts);
291
+ ```
292
+
293
+ ### Feature Flags
294
+
295
+ ```typescript
296
+ // Store feature flags per tenant
297
+ await dataSettingService.create(tenantCode, {
298
+ settingCode: 'FEATURE_FLAGS',
299
+ code: 'BETA_FEATURES',
300
+ name: 'Beta Features',
301
+ attributes: { newDashboard: true, darkMode: true, experimentalApi: false },
302
+ }, opts);
303
+ ```
304
+
305
+ ## Related Packages
306
+
307
+ | Package | Description |
308
+ |---------|-------------|
309
+ | [@mbc-cqrs-serverless/core](https://www.npmjs.com/package/@mbc-cqrs-serverless/core) | Core CQRS framework |
310
+ | [@mbc-cqrs-serverless/master](https://www.npmjs.com/package/@mbc-cqrs-serverless/master) | Hierarchical settings |
311
+ | [@mbc-cqrs-serverless/tenant](https://www.npmjs.com/package/@mbc-cqrs-serverless/tenant) | Multi-tenancy support |
312
+
192
313
  ## Documentation
193
314
 
194
- Visit https://mbc-cqrs-serverless.mbc-net.com/ to view the full documentation, including:
195
- - Configuration options
196
- - Theme customization
197
- - Layout management
198
- - User preferences
199
- - API reference
315
+ Full documentation available at [https://mbc-cqrs-serverless.mbc-net.com/](https://mbc-cqrs-serverless.mbc-net.com/)
200
316
 
201
317
  ## License
202
318
 
203
- Copyright &copy; 2024, Murakami Business Consulting, Inc. https://www.mbc-net.com/
204
- This project and sub projects are under the MIT License.
319
+ Copyright © 2024-2025, Murakami Business Consulting, Inc. [https://www.mbc-net.com/](https://www.mbc-net.com/)
320
+
321
+ This project is under the [MIT License](../../LICENSE.txt).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mbc-cqrs-serverless/ui-setting",
3
- "version": "1.0.16",
3
+ "version": "1.0.17",
4
4
  "description": "Setting master data",
5
5
  "keywords": [
6
6
  "mbc",
@@ -41,7 +41,7 @@
41
41
  "access": "public"
42
42
  },
43
43
  "dependencies": {
44
- "@mbc-cqrs-serverless/core": "1.0.16"
44
+ "@mbc-cqrs-serverless/core": "1.0.17"
45
45
  },
46
- "gitHead": "4ab967474160873735b8cb816272a7012b8940d5"
46
+ "gitHead": "1870821803cfb045c9c4d6bc18d513fa2558de1c"
47
47
  }